devdocs-dev-workflow

Development Workflow

Workflow guidance for executing development tasks, supporting single-task and batch execution, using a top-down development model and layered TDD.

Language Rules

Support questions in Chinese and English
Unified replies in Chinese

Mode Selection

At the entry point, select the appropriate development mode based on task scale:

Mode	Applicable Scenario	Process
Lightweight	Bug fix, small changes, configuration changes	→ `/devdocs-bugfix`(existing)
Standard	New features, requirement changes	→ Complete Requirements→Design→Tests→Tasks→Dev
Exploration	Prototypes, technical research	→ Allowed to skip part of verification, supplement `/devdocs-retrofit` documentation afterward

Mode Determination Guidelines

If the task comes from devdocs-dev-tasks(with a complete existing documentation chain) → Standard mode
If the user describes it as a bug/hotfix/configuration change → Lightweight mode, route to /devdocs-bugfix
If the user describes it as a prototype/research/exploration/spike → Exploration mode, skip adversarial verification and traceability annotation enforcement, and after development is complete, prompt to run /devdocs-retrofit

The following process isStandard mode. For lightweight mode and exploration mode, see the routing above.

Trigger Conditions

The user starts executing a certain task (such as T-01)
The user executes tasks in batch (such as T-01~T-05, F-001, --all)
The user needs to continue development (resume from a breakpoint)
The user needs development guidance
The user enters the development phase from devdocs-dev-tasks
Keywords: "development task", "execute task", "start T-XX", "batch development", "continue development"

Run Modes

Syntax

Specifier	Example	Description
Single task	`T-03`	Execute a single task (existing behavior)
Range	`T-01~T-05`	Execute all tasks within the range
Enumeration	`T-01,T-03,T-07`	Execute the specified task list
Feature point	`F-001`	Look up all associated tasks via the `关联需求` field
User story	`US-001`	Same as above
All	`--all`	All `状态≠已完成` tasks
Unattended	`--headless`	Batch mode + fully automatic decision-making (fail-fast)
Auto-commit	`--auto-commit`	Automatically commit when tests pass, pause only on Blocker (mutually exclusive with `--headless` )

Mode Comparison

Feature	Single-task mode	Batch mode (interactive)	`--auto-commit`	`--headless`
Dependency resolution	Automatically supplement prerequisite dependencies	Topologically sort all tasks	Topologically sort all tasks	Topological sort + prerequisite validation
Breakpoint detection	Execute	Lightweight execution by the orchestrator	Lightweight execution by the orchestrator	Orchestrator lightweight execution
Submission method	User selection	Interactive confirmation within sub-agent	Automatic submission upon test pass	Automatic submission (guaranteed by safety invariants)
Interrupt handling	N/A	Interaction within sub-agent	Pause and prompt upon Blocker	fail-fast termination + resume command
Completion summary	None	Batch execution report	Batch execution report	Delivery report + checkpoint file
Execution mode	Main Agent executes directly	Orchestrator + sub-agent	Orchestrator + sub-agent	Orchestrator + sub-agent
Context isolation	Not required	Independent context per task	Independent context per task	Independent context per task

Batch execution flow

解析指定符 → 依赖解析 + 拓扑排序 → 逐任务循环（断点检测 → 执行 → 原子提交）→ 汇总

See task-orchestration.md

Preconditions

Task document:docs/devdocs/04-dev-tasks.md
The task is defined and includes: associated requirements, acceptance criteria, test methods

Workflow

1. 读取任务定义
   ├── 从 04-dev-tasks.md 获取任务详情
   ├── 确认关联的 F-XXX、AC-XXX
   └── 确认关联的测试用例 UT/IT/E2E-XXX
           │
           ▼
2. 生成骨架代码（自顶向下）
   ├── 接口骨架 + @requirement/@satisfies 标注
   └── 测试骨架 + @verifies/@testcase 标注
           │
           ▼
3. 执行开发（统一流程，分级强制）
   ├── 所有层级遵循统一 11 步流程
   ├── 层级标记（🔴🟡🟢⚪）决定各步骤强制程度
   └── 详见 execution-flow.md 强制程度矩阵
           │
           ▼
4. 完成检查
   ├── 基础检查（始终执行）
   │   ├── 验收标准全部满足
   │   ├── 测试通过
   │   └── Review 要点自查
   │
   ├── 前置验证（--review 触发时，对抗式验证之前）
   │   ├── /devdocs-verify --impl：AC 满足度 + 设计一致性（若存在 DevDocs 文档）
   │   └── /devdocs-verify --ui：设计稿↔实现对齐（仅 UI 任务 + 有设计稿）
   │
   └── 对抗式验证（🔴自动触发 / 其他层级 --review 手动触发）
       ├── 🔍 代码质量审查（/code-quality 视角）
       ├── 🧪 测试完备性审查（/testing-guide 视角）
       └── 📋 综合审查报告
           │
           ▼
4.5 更新自描述（/code-self-describe --update）
           │
           ▼
5. 提交代码（Commit 1: 代码，遵循 /commit-convention）
           │
           ▼
6. 更新追溯 + 文档提交（/devdocs-sync → Commit 2: 文档）
        │
        ▼
6.5 更新 AGENTS.md "当前状态"（若存在）
    ├── 更新活跃任务编号 (T-XX)
    └── 更新进度统计 (X/Y)
        │
        ▼
7. [推荐] 知识沉淀（/devdocs-compound）
    ├── 批量模式完成后默认执行（用户可跳过）
    └── 单任务模式：提示用户是否运行 /devdocs-compound

Step status tracking

In the 11-step execution flow, a status marker (S1–S11) is recorded after each step is completed, used to precisely locate the position during breakpoint recovery. This is more precise than the original 5-step checkpoint, reducing duplicate work.

See execution-flow.md Step status tracking table

Code traceability annotation specification

Achieve bidirectional traceability between implementation documents and code; AI automatically adds annotations when generating code.

Annotation types

Annotation	Purpose	Location
`@requirement F-XXX`	Associated feature point	Interface/class/module
`@satisfies AC-XXX`	Acceptance criteria satisfied	Interface/method
`@verifies AC-XXX`	Acceptance criteria verified	Test case
`@testcase UT/IT/E2E-XXX`	Test number	Test case

Annotation examples

/**
 * 创建用户
 * @requirement F-001 - 用户注册
 * @satisfies AC-001 - 邮箱格式校验
 * @satisfies AC-002 - 密码强度校验
 */
export async function createUser(dto: CreateUserDTO): Promise<User> {
  // 实现代码
}

/**
 * @verifies AC-001 - 邮箱格式校验
 * @testcase UT-001
 */
test('createUser 应该拒绝无效邮箱格式', () => {
  // 测试代码
});

Annotation rules

Level	Annotation location	Mandatory
Public interface	Service/API entry method	Required
Test file	Each test case	Required
Internal implementation	Complex logic	Optional

Top-down development mode

Define the skeleton first, then fill in the details. Ensure the traceability chain is established at code generation time.

Development flow

Step 1: 生成接口骨架
        ├── 方法签名（来自 02-system-design.md）
        ├── 添加 @requirement/@satisfies 标注
        └── 方法体: throw new Error('Not implemented')
                │
                ▼
Step 2: 生成测试骨架
        ├── 测试结构（来自 03-test-*.md）
        ├── 添加 @verifies/@testcase 标注
        └── 测试体: test.skip() 或 test.todo()
                │
                ▼
Step 3: 实现接口细节（遵循 /code-quality）
                │
                ▼
Step 4: 完善测试（断言来自 03-test-*.md 中 AC 对应的测试用例，遵循 /testing-guide）
                │
                ▼
Step 5: 运行 /devdocs-sync 更新追溯矩阵

Skeleton generation constraints

Interface skeletons must contain complete signatures(parameters, return values, generics)
Interface skeletons must add traceability annotations
Unimplemented methods must throw an Error and note the task number
Test skeletons must use skip/todo markers
Test skeletons must add @verifies and @testcase annotations

See skeleton-examples.md

Layered TDD mode

All levels follow the unified 11-step execution flow; the level marker only determines thedegree of enforcement：

Level	Marker	Mandatory step	Recommended step	Optional step
Core logic (Service/Domain)	🔴	All 11 steps	—	—
Interface layer (Controller/API)	🟡	Skeleton/Implementation/Green/AC/Self-description/Commit	Test assertions/Red/Refactor/Verification	—
UI layer (Component/View)	🟢	Skeleton/Implementation/Green/AC/Self-description/Commit	Test assertions/Verification	Red/Refactor
Infrastructure (DB/Config)	⚪	Skeleton/Implementation/Green/AC/Self-description/Commit	Test skeleton	Test assertions/Red/Refactor/Verification

TDD cycle (core of the unified process)

┌─────┐    ┌─────┐    ┌─────┐
│ 红  │ → │ 绿  │ → │重构 │ ──┐
│写测试│    │写实现│    │优化 │   │
│(失败)│    │(通过)│    │代码 │   │
└─────┘    └─────┘    └─────┘   │
    ↑                           │
    └───────────────────────────┘

⚠️ Core principles of the Red phase: assertions must come from the test cases corresponding to the ACs in 03-test-*.md; deriving tests from implementation code is prohibited.

See execution-flow.md Unified Task Execution Process + Mandatory Level Matrix

Orchestration specification (sub-agent scheduling)

When dev-workflow invokes the following skills,a sub-agent must be launched via the Task tool：

Phase	Scheduled skill	Scheduling method
Pre-verification	`/devdocs-verify --impl`	Task tool sub-agent
UI alignment	`/devdocs-verify --ui`	Task tool sub-agent
Traceability sync	`/devdocs-sync`	Task tool sub-agent
Knowledge capture	`/devdocs-compound`	Task tool sub-agent
Full test suite	`/devdocs-test-run`	Task tool sub-agent

Scheduling principles

Context isolation: Each sub-agent reads the documents it needs on its own; dev-workflow does not pass full texts
Summary passing: Only the YAML summary returned by the sub-agent is received, and the next step is decided based on it
Exception fallback: When a sub-agent returns status: failed + blockers , display the blocking items and ask the user
Do not troubleshoot on your own: The orchestration layer does not read the full output documents of sub-skills to attempt fixes

Skill collaboration

Phase	Collaborating Skill	Description
Writing business code	`/code-quality`	MTE principles, dependency injection, avoid over-engineering
Writing test code	`/testing-guide`	Assertion quality, mutation testing, coverage
UI implementation	`/ui-orchestrator`	Accessibility, animation, layout constraints
Implementation review	`/devdocs-verify --impl`	Pre-verification: AC satisfaction + design consistency (DevDocs feature development tasks)
UI alignment	`/devdocs-verify --ui`	Pre-verification: design mockup ↔ implementation alignment (UI tasks only + when a design mockup exists)
Completion verification	`/code-quality` + `/testing-guide`	Adversarial verification: multi-perspective review
Completion check	`/code-self-describe`	Update module self-description (--update)
Code commit	`/git-safety`	Use git mv/rm to handle files
Commit message	`/commit-convention`	Follow the project commit conventions
Dependency resolution	`/devdocs-dev-tasks`	Read task dependencies and status
Task completion	`/devdocs-sync`	Follow-up: Update traceability matrix (traceability sync)
Knowledge capture	`/devdocs-compound`	Recommended: Extract experience patterns after sync (executed by default in batch mode)
Full test	`/devdocs-test-run`	After batch completion: full test + traceability verification (--trace)

Constraints

Skeleton generation constraints

Interface skeletons must include complete signatures
Interface skeletons must add traceability annotations
Unimplemented methods must throw Error
Test skeletons must use skip/todo markers
Test skeletons must add @verifies and @testcase annotations

Layered TDD constraints

All layers follow the unified 11-step execution flow(layer markers only determine the degree of enforcement)
Core logic tasks must be marked 🔴 mandatory TDD(all 11 steps ■ required)
Core logic tasks must write tests first, then implementation
Core logic tasks are prohibited from committing before tests pass
Interface layer tasks are marked 🟡 recommended TDD
UI layer tasks are marked 🟢 optional TDD
Infrastructure tasks are marked ⚪ recommended test skeleton
Assertions must come from the test cases corresponding to the AC in 03-test-*.md; deriving tests from implementation code is prohibited
TDD tasks must include the three steps of red-green-refactor
When □/○ steps are skipped, the reason must be recorded in the commit message

Completion check constraints

All acceptance criteria (AC-XXX) are satisfied
All associated tests pass
Review key points self-check completed
Code traceability annotations complete
Code branch coverage analysis completed (optional,supplementary in nature, use /testing-guide branch analysis; business logic branches should be traced back to formal tests corresponding to ACs)

Adversarial verification (optional)

Review code from different role perspectives, simulating the multi-person collaboration mode of "development → review → testing".

Trigger conditions

Layer determination: Task layer markers (🔴🟡🟢⚪) come from 04-dev-tasks.md task definitions, assigned by /devdocs-dev-tasks during task breakdown according to the task layering rules.

Task layer	Default behavior	Manual control
🔴 Core logic	Auto-trigger	`--skip-review` Skip
🟡 Interface layer	Not triggered	`--review` Enable
🟢 UI layer	Not triggered	`--review` Enable
⚪ Infrastructure	Not triggered	`--review` Enable

Verification flow overview

Basic completion check (AC + tests + annotations) → Phase 1: Code quality review (/code-quality perspective) → Phase 2: Test completeness review (/testing-guide perspective) → Phase 3: Comprehensive report (Blocker must be fixed / Suggestion may be skipped)

When performing adversarial verification, you must read verification-flow.md to obtain the AC↔diff cross-verification rules, minimum number of findings, finding classification criteria, and detailed handling rules for Blocker/Suggestion under --headless.

Adversarial Verification Constraints

Blocker issues must be fixed before submission
Each Phase must explicitly declare the current review role
Review results must be graded (Blocker/Suggestion)
Core logic tasks (🔴) trigger by default
After fixing a Blocker, verification must be re-run

Dependency Resolution Constraints

Dependency resolution must be completed before execution
Circular dependencies must error out and terminate(list the circular path)
Completed dependencies are skipped, not executed again
Automatically add incomplete prerequisite dependencies to the execution queue
"In progress" dependencies are queried to the user via AskUserQuestion

Atomic Commit Constraints

Each task is committed independently, not merged across tasks
Code commits and documentation commits are separated(Commit 1: code, Commit 2: documentation status + trace sync results)
Completion checks must pass before committing
After committing, update the 04-dev-tasks*.md task status to 已完成
--single-commit Code + documentation can be merged into a single commit

Resume-from-Breakpoint Constraints

Perform status detection before each task starts(5-step pipeline)
Irrelevant changes must warn the user(AskUserQuestion: stash/ignore/terminate)
Completed tasks are automatically skipped
In-progress tasks analyze the resume starting point (11-step precise localization: S1~S11)
Triple verification of documentation status + Git history + working tree

See task-orchestration.md

`--auto-commit` Constraints

Interactive mode (non-headless), the user can still observe the process
Auto-commit when all tests pass and there is no Blocker, without asking
Pause and ask when a Blocker appears or tests fail
and --headless are mutually exclusive (--headless already includes auto-commit semantics)
Safety invariants same as --headless: do not commit if tests fail, do not commit if a Blocker is unresolved

Memory File Sync Constraints

After task completion, check whether AGENTS.md exists in the project root directory
Only updating is allowed ## 当前状态 section(active task numbers, progress statistics)
Modifying structural sections is prohibited(Project Overview, Skill Architecture, Conventions, etc. are managed by /agent-memory)
CLAUDE.md is automatically imported via @AGENTS.md, no sync needed
Only perform text replacement, do not call /agent-memory
The format must be consistent with /agent-memory template
Skip if AGENTS.md does not exist

Full Test Verification Constraints

After batch mode completes, /devdocs-test-run --trace must be called
Single-task mode does not trigger full tests (its own tests have already been run during development)
Full test failure does not roll back committed tasks
Interactive mode: AskUserQuestion asks whether to fix the failed tests
--headless / --auto-commit mode: record a warning in the delivery report, do not interrupt

Unattended Constraints (--headless)

The working tree must be clean(Before startup + verification after Commit 2 for each task)
Prerequisite dependencies must not be in "in progress" status(otherwise fail-fast)
Output resume command after fail-fast
Annotations must not be deleted during fixes
The number of assertions must not decrease during fixes
Suggestions are automatically skipped(unless --fix-suggestions）
Never push to remote

See auto-mode.md

Task Completion Flow

All levels follow a unified completion flow (level markers determine the enforcement degree of each step; see execution-flow.md for details):

Confirm test status: Check whether tests pass
Confirm TDD cycle(■🔴 □🟡 ○🟢⚪): The red-green cycle of tests going from failing to passing
Check refactoring(■🔴 □🟡 ○🟢⚪): Whether the code has been optimized
Verify acceptance criteria: Check whether all ACs are satisfied
Adversarial verification(■🔴 automatic / □🟡🟢--review / ○⚪--review):
- Phase 1: Code quality review (/code-quality perspective)
- Phase 2: Test completeness review (/testing-guide perspective)
- Phase 3: Comprehensive report, handle Blockers
Update self-description: Run /code-self-describe --update
Commit decision：
- --headless mode: automatic commit (safety invariants already guaranteed in preceding steps)
- --auto-commit mode: automatic commit when tests pass + no Blockers
- Interactive mode: AskUserQuestion: "Task T-XX is complete. Commit the code?"
  - Options: "Commit" / "Continue modifying" / "Skip"
If committing(atomic commit):
- Commit 1: Code commit <type>(T-XX): <名称>
- Update 04-dev-tasks*.md status + /devdocs-sync
- Commit 2: Documentation commit docs(T-XX): 更新任务状态并同步 trace
Update status: Mark as completed in TodoWrite

Commit message format

Follow the /commit-convention specification, with the following format:

<type>(T-XX): <任务名称>

- <完成内容1>
- <完成内容2>

关联: F-XXX, AC-XXX
测试: UT-XXX, IT-XXX 通过

Sub-agent summary format

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

skill: devdocs-dev-workflow
task: T-XX
status: success | failed | skipped
commits:
  code: "abc1234"      # Commit 1 hash
  docs: "def5678"      # Commit 2 hash
test_summary:
  passed: X
  failed: 0
  coverage: "XX%"
blockers_resolved: 0
suggestions_skipped: 0
ac_verified: [AC-001, AC-002]
next_task: T-YY | null

References

skeleton-examples.md - Interface/test skeleton examples
execution-flow.md - Detailed task execution flow
verification-flow.md - Detailed adversarial verification flow
task-orchestration.md - Multi-task orchestration (batch/dependencies/resume from breakpoint)
auto-mode.md - Detailed unattended mode

About this skill

Language Rules

Mode Selection

Mode Determination Guidelines

Trigger Conditions

Run Modes

Syntax

Mode Comparison

Batch execution flow

Preconditions

Workflow

Step status tracking

Code traceability annotation specification

Annotation types

Annotation examples

Annotation rules

Top-down development mode

Development flow

Skeleton generation constraints

Layered TDD mode

TDD cycle (core of the unified process)

Orchestration specification (sub-agent scheduling)

Scheduling principles

Skill collaboration

Constraints

Skeleton generation constraints

Layered TDD constraints

Completion check constraints

Adversarial verification (optional)

Trigger conditions

Verification flow overview

Adversarial Verification Constraints

Dependency Resolution Constraints

Atomic Commit Constraints

Resume-from-Breakpoint Constraints

--auto-commit Constraints

Memory File Sync Constraints

Full Test Verification Constraints

Unattended Constraints (--headless)

Task Completion Flow

Commit message format

Sub-agent summary format

References

`--auto-commit` Constraints