devdocs-pipeline

DevDocs Workflow Orchestrator

Top-level orchestrator that provides 5 process entry points, reducing the cognitive burden on users facing 13 atomic skills.

Language Rules

• Supports questions in Chinese and English
• Unified Chinese replies

Positioning

用户 → /devdocs-pipeline → 自动路由到合适的 skill 组合
                         ↓
              取代手动选择 13 个原子 skill

Core Value: Users only need to say "what I want to do"; the pipeline is responsible for "which skills to use and in what order."

Operating Modes

/devdocs-pipeline                → 提问式调度（自动判断）
/devdocs-pipeline init           → 新项目全流程
/devdocs-pipeline feature        → 新功能开发
/devdocs-pipeline bugfix         → Bug 修复
/devdocs-pipeline verify         → 质量检查
/devdocs-pipeline close          → 周期收尾

Question-Based Scheduling (Intelligent Guidance)

When called without parameters, it converges to the appropriate entry point through stage awareness + intelligent guidance:

Stage Detection

First scan docs/devdocs/ for existing files to determine the current stage:

扫描 docs/devdocs/ 目录
    │
    ├── 无文件 → 新项目判断（见下方 Q1）
    │
    └── 有文件 → 分析当前阶段
          │
          ├── 仅 01-requirements.md → "需求已完成，建议运行 /devdocs-system-design"
          ├── 有 01 + 02 → "设计已完成，建议运行 /devdocs-test-cases"
          ├── 有 01~03 → "测试设计已完成，建议运行 /devdocs-dev-tasks"
          ├── 有 01~04 + 有 readiness-report → "就绪检查已通过，建议运行 /devdocs-dev-workflow"
          ├── 有 01~04 + 无 readiness-report → "任务已拆分，建议运行 /devdocs-verify --readiness"
          ├── 有代码提交 + 任务进行中 → "开发进行中，建议继续 /devdocs-dev-workflow"
          └── 有 verify-report → "验证已完成，建议运行 /devdocs-sync 或 /devdocs-compound"

Lightweight Track Prompt

Based on the scale of change described by the user, provide path suggestions:

Change Scale	Characteristics	Suggested Path
Small Change	bugfix, single-file fix, configuration change	/devdocs-pipeline bugfix
Standard Feature	new feature, requirement change, multi-file change	/devdocs-pipeline feature
Large Feature	cross-module, new architecture, brand-new project	/devdocs-pipeline init full path

Fallback Q&A

When stage detection cannot determine, converge through 2-3 questions:

Q1: "项目已有 DevDocs 文档吗？"
    │
    ├── 没有 → Q1a: "已有代码还是全新项目？"
    │           ├── 全新项目 → init
    │           └── 已有代码 → /devdocs-retrofit（非 pipeline 管辖）
    │
    └── 有 → Q2: "你要做什么？"
              ├── 新功能  → feature
              ├── 修 Bug  → bugfix
              ├── 检查质量 → verify
              └── 收尾/沉淀 → close

Q3（feature/bugfix 追加，可选）:
    "这次改动涉及 UI 吗？"
    ├── 是 → verify 阶段包含 --ui 维度
    └── 否 → verify 阶段仅 --docs/--impl

Entry Point Details

init — Full Process for New Projects

Suitable for brand-new projects, the complete process from requirements to development.

/devdocs-requirements
    │
    ▼
/devdocs-system-design
    │
    ▼
/devdocs-test-cases
    │
    ▼
/devdocs-dev-tasks
    │
    ▼
/devdocs-verify --readiness   ← 就绪关卡（P1 阻塞则修复后重试）
    │
    ▼
/devdocs-dev-workflow（批量模式）
    │  ← 批量模式内部已含逐任务 sync + compound
    ▼
/devdocs-verify        ← 全量验证（覆盖 dev-workflow 逐任务验证可能遗漏的跨任务一致性）
    │
    ▼
/devdocs-sync          ← 全量补充同步（幂等，捕获跨任务遗漏）

Readiness Gate: Automatically call verify --readinessafter dev-tasks is completed. Check items include: AC↔test case alignment, task file path specificity, dependency acyclicity, design↔task consistency. P1 issues block entry into dev-workflow, displaying the issue list and suggesting retry after fixes.

Granularity Notes: dev-workflow batch mode already performs per-task sync and compound internally. The verify → sync here in the pipeline isfull verification + supplementary sync, covering overall cross-task consistency. sync is idempotent; multiple executions will not produce erroneous results. compound is no longer additionally executed—dev-workflow batch mode already executes it by default.

Context Passing: When the pipeline starts, it prioritizes checking docs/devdocs/00-context.md; if it exists and is not expired (< 24h), read it as quick context to avoid repeated scanning.

feature — New Feature Development

Suitable for adding new features to an existing project.

/devdocs-feature（含 requirements/design/tests/tasks + readiness 关卡 + 自动衔接 dev-workflow）
    │  ← feature 内置 Step 4.5 verify --readiness，P1 阻塞则修复后重试
    │  ← dev-workflow 内部已含逐任务 sync
    ▼
/devdocs-verify        ← 全量验证（覆盖所有新增任务的整体一致性）
    │
    ▼
/devdocs-sync          ← 全量补充同步（幂等，捕获跨任务遗漏）

/devdocs-feature already has a built-in Step 4.5 readiness gate and Step 6 automatically connects to dev-workflow; the pipeline only needs to supplement verify and sync after feature is completed. verify is full verification, covering cross-task consistency that dev-workflow per-task verification may miss; sync is an idempotent full supplementary sync, not repeated execution.

bugfix — Bug Fix

Suitable for fixing bugs in an existing project.

评估复杂度
    │
    ├── 简单 Bug → /devdocs-bugfix（直接修复）
    │                  │
    │                  ▼
    │              /devdocs-verify --impl
    │                  │
    │                  ▼
    │              /devdocs-sync
    │
    └── 复杂 Bug → /devdocs-dev-tasks（拆分任务）
                       │
                       ▼
                   /devdocs-dev-workflow
                       │
                       ▼
                   /devdocs-verify --impl
                       │
                       ▼
                   /devdocs-sync

verify — Quality Check

Suitable for quality checks at any stage.

自动判断维度
    │
    ├── 有代码变更 → /devdocs-verify --impl
    ├── 有文档变更 → /devdocs-verify --docs
    ├── 有 UI 设计稿 → /devdocs-verify --ui
    └── 不确定 → 询问用户
    │
    ▼
生成修复建议
    │
    ▼
路由到对应 skill 执行修复

close — Cycle Wrap-Up

Suitable for wrap-up work after the development cycle ends.

/devdocs-sync（trace + audit）
    │
    ▼
/devdocs-compound（知识沉淀）
    │
    ▼
/devdocs-onboard --update（更新上下文摘要）

Inter-Stage Transitions

After each stage is completed, the pipeline:

1. Status Check: Confirm that the stage output files exist
2. Brief Summary: Show the user an overview of the results of this stage
3. Transition Prompt: Ask the user whether to continue to the next stage (default is yes)

✅ 需求文档已完成（F-001~F-003, AC-001~AC-012）
是否继续进入系统设计阶段？[是(默认)/否]

Orchestration Specification (Sub-Agent Scheduling)

Scheduling Principles

When the pipeline calls other skills,it must launch sub-agents via the Task tool：

pipeline（编排层）
    │
    ├── Task: /devdocs-requirements → YAML 摘要
    ├── Task: /devdocs-system-design → YAML 摘要
    ├── Task: /devdocs-test-cases → YAML 摘要
    ├── Task: /devdocs-dev-tasks → YAML 摘要
    ├── Task: /devdocs-verify --readiness → YAML 摘要
    ├── Task: /devdocs-dev-workflow → YAML 摘要
    ├── Task: /devdocs-verify → YAML 摘要
    └── Task: /devdocs-sync → YAML 摘要

Summary Passing

Only the YAML summary + file paths are passed between stages. The orchestration agent does not readthe full output documents of sub-skills.

Exception Fallback

When a sub-agent returns status: failed + blockers :

1. Display the blocking items to the user
2. Ask the user how to handle it (fix/skip/abort)
3. Do not read documents to troubleshoot on your own

Context Isolation

Each sub-agent reads the prerequisite documents it needs on its own (from the docs/devdocs/ file system), without relying on the orchestration agent to pass the full text.

Constraints

Stage Boundary Constraints (Global Rules)

The DevDocs workflow strictly distinguishes between thedocumentation phaseand thecoding phase：

Stage	Skill	Output Type	Coding Allowed
Requirements	devdocs-requirements	Document	❌
Design	devdocs-system-design	Document	❌
Test Design	devdocs-test-cases	Document	❌
Task Breakdown	devdocs-dev-tasks	Document	❌
Project Transformation	devdocs-retrofit	Document	❌
Development Execution	devdocs-dev-workflow	Code	✅
Bug Fix	devdocs-bugfix	Code	✅

• Skills in the documentation phase are strictly forbidden from producing implementation code and only write docs/devdocs/ Markdown documents under
• Coding only occurs in the devdocs-dev-workflow and devdocs-bugfix stages
• The orchestrator must not start coding operations during the documentation phase

Orchestration Constraints

• The pipeline is only responsible for routing and connecting, and does not replicate the logic of any atomic skill
• Each stage must be delegated to the corresponding atomic skill for execution
• The information passed between stages is limited to: newly added numbered lists, status summaries, file paths
• The user can exit the pipeline at any stage

Question-Based Scheduling Constraints

• Prioritize automatic determination via stage detection, and only ask questions when it cannot be determined
• The fallback Q&A converges to the entry point with at most 3 questions
• Questions must have clear options (no open-ended questions)
• When a retrofit scenario is identified, route to /devdocs-retrofit and exit the pipeline
• Track-splitting hints are based on change scale and do not introduce additional terminology

Context Constraints

• Prioritize reading 00-context.md as fast context (if it exists and is < 24h old)
• The pipeline orchestration layer does not read large amounts of source code (delegated to sub-skills)
• After each stage completes, display a brief summary (< 10 lines)

Orchestration Constraints (Sub-Agent)

• When calling other skills, sub-agents must be launched via the Task tool
• Only the YAML summary + file paths are passed between stages
• When a sub-agent fails, display the blocking items and ask the user, without troubleshooting on your own
• Each sub-agent reads prerequisite documents on its own; the orchestration layer does not pass the full text

Skill Collaboration

Entry	Orchestrated Skill Chain
init	requirements → system-design → test-cases → dev-tasks → verify --readiness → dev-workflow → verify → sync
feature	feature (including readiness + dev-workflow) → verify → sync
bugfix	bugfix / (dev-tasks → dev-workflow) → verify → sync
verify	verify --docs/--impl/--ui
close	sync → compound → onboard --update

Sub-Agent Summary Format

When this Skill runs as a sub-Agent, return the following structured summary:

skill: devdocs-pipeline
entry: init | feature | bugfix | verify | close
stages_completed:
  - { skill: devdocs-requirements, status: success }
  - { skill: devdocs-system-design, status: success }
stages_remaining:
  - devdocs-test-cases
summary:
  new_ids: [F-001, F-002, AC-001~AC-012]
  status: completed | interrupted | failed
  interrupt_reason: "用户选择退出"  # 仅中断时
output_files:
  - docs/devdocs/01-requirements.md
  - docs/devdocs/02-system-design.md

Next Steps

After the pipeline is complete, all output documents have been generated/updated. The user can:

• Continue to the next feature/bugfix round
• Run /devdocs-onboard --read to pass context to a new AI
• Proceed directly to coding (the outputs of dev-tasks and dev-workflow are already available)