devdocs-feature

New Feature

Add new features to an existing DevDocs project, ensuring numbering continuity and document consistency.

Language Rules

Support questions in Chinese and English
Unified Chinese replies

Trigger Conditions

The user wants to add new features to an existing project
The user mentions "incremental", "iteration", "new features", "additional requirements"
The user requests extending existing functionality

Preconditions

A DevDocs document directory already exists:docs/devdocs/
At least 01-requirements.md

If it does not exist, it is recommended:

New project → /devdocs-requirements
Existing code without documentation → /devdocs-retrofit

Run Modes

Mode Selection

/devdocs-feature "功能描述"             → 自动检测模式
/devdocs-feature --lite "功能描述"      → 强制轻量模式
/devdocs-feature --fast "功能描述"      → 连续执行 Step 1-5，仅最终汇总确认
/devdocs-feature --lite --fast "功能描述" → 轻量 + 快速组合

Mode Comparison

Mode	Applicable Scenarios	Update Documents	Context Load
Lite Mode	Configuration changes, UI tweaks, simple fields	01 + 04	Low
Full Mode	New modules, new interfaces, architecture changes	01 + 02 + 03 + 04	High (step-by-step)

Automatic Mode Detection

Analyze the requirement description and detect whether it involves:

[ ] 新增 API 接口
[ ] 数据模型变更
[ ] 组件间依赖变化
[ ] 第三方服务集成
[ ] 新增独立模块

None of the above → Lite Mode
Any match → Full Mode (prompt the user for confirmation)

检测到可能涉及架构变更：
- 新增接口: UserPreferenceAPI

建议使用完整模式。是否继续轻量模式？[是/否]

Core Concept

新功能开发 = 延续编号 + 追加文档 + 影响分析 + 回归保护

Lite Mode Flow (--lite)

1. 扫描编号
   │
   ├── 读取 01-requirements.md → 获取 AC 最大编号
   └── 读取 04-dev-tasks*.md → 获取 T 最大编号
   │
   ▼
2. 收集需求（简化）
   │
   └── 验收标准（AC 级别）
   │
   ▼
3. 追加文档（仅两份）
   │
   ├── 01-requirements.md → 追加 AC（挂载到现有 F/US）
   └── 04-dev-tasks*.md → 追加 1-3 个任务
   │
   ▼
4. 用户确认

Lite Mode Constraints

Steps 1-4 are the documentation phase, producing only Markdown documents under docs/devdocs/ , without writing implementation code; when coding is needed, it must connect through Step 6 to /devdocs-dev-workflow
Do not create new F-XXX (feature points); only append AC to existing features
Do not update 02-system-design (no architecture changes)
Do not update 03-test-cases (inline the test case numbers and acceptance criteria directly in the appended task; it is recommended to confirm before entering dev-workflow that corresponding entries already exist in 03-test-cases, and dev-workflow will automatically detect and prompt completion at startup)
Task count is limited to 1-3 (can be appended directly without calling devdocs-dev-tasks)
Tasks must follow the TAR principle format

⚠️ Lite Mode Traceability Warning

Lite Mode skips updates to 02 (system design) and 03 (test cases) documents,the traceability chain is incomplete(the F → US → AC → UT/IT/E2E chain is broken at the design layer and test layer). At user confirmation in Step 4, the following warning must be displayed:

⚠️ 轻量模式跳过了设计文档和测试用例更新，追溯链不完整。
建议在开发前补齐：
  - /devdocs-system-design（补充设计）
  - /devdocs-test-cases（补充测试用例）
或切换到完整模式：/devdocs-feature "功能描述"

Full Mode Flow (Step-by-Step Orchestration)

Core Change: No longer update all 4 documents at once, but execute step by step, proceeding to the next step only after each step is confirmed.

┌─────────────────────────────────────────────────────────────┐
│  Step 0: 扫描现有文档，获取编号和架构摘要                    │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 1: 需求追加                                           │
│  ├── 收集新功能描述                                         │
│  ├── 追加 01-requirements.md（F/US/AC）                     │
│  └── ✅ 用户确认                                            │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 2: 设计追加                                           │
│  ├── 影响分析（模块/接口/数据）                             │
│  ├── 追加 02-system-design*.md                              │
│  └── ✅ 用户确认                                            │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 3: 测试追加                                           │
│  ├── 根据新增 AC 设计测试用例                               │
│  ├── 追加 03-test-cases*.md + 更新追溯矩阵                  │
│  └── ✅ 用户确认                                            │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 4: 任务追加                                           │
│  ├── 根据设计和测试拆分开发任务                             │
│  ├── 追加 04-dev-tasks*.md                                  │
│  └── ✅ 用户确认                                            │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 5: 生成功能日志                                       │
│  └── 更新 00-feature-log.md                                 │
└─────────────────────────────────────────────────────────────┘

Advantages of Step-by-Step Execution

Problem	Traditional Approach	Step-by-Step Orchestration
Duplicate Numbering	Maintaining 4 sets of numbering at once is error-prone	Each step focuses only on the current document's numbering
Missed Updates	Context is too long, easy to miss items	Confirm at each step, no omissions
Incomplete Traceability	Difficult to ensure AC→test completeness	Step 3 focuses on the traceability matrix
Difficult Rollback	Full modifications are hard to roll back	Can terminate at any step

Step 0: Scan existing documents

Number extraction

Extract the highest number from existing documents:

## 当前状态

| 类型 | 当前最大编号 | 下一编号 |
|------|-------------|----------|
| 功能点 (F) | F-003 | F-004 |
| 用户故事 (US) | US-008 | US-009 |
| 验收标准 (AC) | AC-015 | AC-016 |
| 单元测试 (UT) | UT-012 | UT-013 |
| 集成测试 (IT) | IT-003 | IT-004 |
| E2E 测试 (E2E) | E2E-002 | E2E-003 |
| 开发任务 (T) | T-10 | T-11 |

Architecture summary (full mode)

From 02-system-design*.md extract:

Existing module list
Core interfaces
Data entities

Step 1: Requirement addition

Delegated execution: This step must be delegated to /devdocs-requirements --incremental, which is responsible for the incremental requirements.

Delegation input

Context passed to /devdocs-requirements :

The user's new feature description
The existing numbering status scanned in Step 0

Delegation output

From /devdocs-requirements obtain:

The list of newly added F-XXX, US-XXX, AC-XXX numbers
The updated traceability matrix

✅ Confirmation point (default mode)

Display the step summary block (numbers + key changes), and wait for user confirmation.--fast mode skips this confirmation.

Step 2: Design addition (full mode)

Delegated execution: This step must be delegated to /devdocs-system-design, which is responsible for the incremental design.

Delegation input

Context passed to /devdocs-system-design :

The newly added F-XXX, US-XXX, AC-XXX numbers from Step 1
Existing architecture summary (from Step 0)
Impact analysis question list

Delegation output

From /devdocs-system-design obtain:

Newly added/changed modules and interfaces
Impact summary
Regression risk points

✅ Confirmation point (default mode)

Display the step summary block (impact scope + compatibility conclusion), and wait for user confirmation.--fast mode skips this confirmation.

Step 3: Test addition (full mode)

Delegated execution: This step must be delegated to /devdocs-test-cases, which is responsible for the incremental test design.

Delegation input

Context passed to /devdocs-test-cases :

The newly added AC-XXX numbers from Step 1
The newly added interfaces and modules from Step 2 (from system-design)

Delegation output

From /devdocs-test-cases obtain:

Newly added UT/IT/E2E-XXX numbers
The updated traceability matrix

✅ Confirmation point (default mode)

Display the step summary block (new test numbers + matrix update status), and wait for user confirmation.--fast mode skips this confirmation.

Step 4: Task addition

Call devdocs-dev-tasks

Important: In full mode, task breakdown is handled by /devdocs-dev-tasks , ensuring consistency of the TAR principles and layered TDD labels.

Context passed to devdocs-dev-tasks：

Newly added F-XXX, AC-XXX numbers
Newly added UT/IT/E2E-XXX numbers
Affected modules and interfaces

调用 /devdocs-dev-tasks：
- 输入：Step 1-3 产生的新增编号
- 输出：追加到 04-dev-tasks*.md
- 遵循：TAR 原则、分层 TDD

✅ Confirmation point (default mode)

Display the step summary block (new task scope + TDD layering annotations), and wait for user confirmation.--fast mode skips this confirmation.

Step 4.5: Readiness check (full mode)

Delegated execution: This step must be delegated to /devdocs-verify --readiness, as a quality gate before entering development.

Delegation input

Context passed to /devdocs-verify --readiness :

Numbered list of new additions from Step 1-4

Delegation output

Obtained from /devdocs-verify --readiness :

Readiness check results (P1/P2/P3 issue list)
Readiness status (pass / fail)

Gate rules

P1 issues exist → Block entry into Step 6, display the issue list and recommend fixing before retrying
Only P2/P3 → Display warnings, ask the user whether to continue
All passed → Automatically enter Step 5

Step 5: Generate feature log

Output file

docs/devdocs/
└── 00-feature-log.md    # 功能日志（追加）

For detailed templates, see templates/feature-log-template.md

Step 6: Connect to development execution (optional)

In full mode, after task decomposition is complete, ask the user whether to continue with development execution:

任务分解已完成，新增 N 个开发任务（T-XX ~ T-YY）。

是否继续执行开发？[是(默认)/否]
- 是 → 自动衔接 /devdocs-dev-workflow T-XX~T-YY
- 否 → 结束 feature 流程，用户后续手动调用 dev-workflow

Default behavior: Yes (continue execution). When the user selects "No", output the task number range for subsequent manual invocation.

Lightweight mode also supports Step 6, connecting the development of 1-3 tasks by delegating to /devdocs-dev-workflow . Lightweight mode itself does not write implementation code.

Orchestration specification (sub-agent scheduling)

In full mode, when devdocs-feature invokes sub-skills, itmust start sub-agents via the Task tool：

Step	Scheduled skill	Scheduling method
Step 1	`/devdocs-requirements --incremental`	Task tool sub-agent
Step 2	`/devdocs-system-design`	Task tool sub-agent
Step 3	`/devdocs-test-cases`	Task tool sub-agent
Step 4	`/devdocs-dev-tasks`	Task tool sub-agent
Step 4.5	`/devdocs-verify --readiness`	Task tool sub-agent
Step 6	`/devdocs-dev-workflow`	Task tool sub-agent

Scheduling principles

Context isolation: Each sub-agent reads the required documents itself; the feature orchestration layer does not pass full texts
Summary passing: Only the YAML summary + numbered list of new additions is passed between steps
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 repairs

Because lightweight mode has simple tasks (1-3 tasks),documentation steps(Step 1-4) are executed directly within the feature context, without starting sub-agents. Step 6 development connection still requires delegating to /devdocs-dev-workflow。

Skill collaboration

Phase	Collaborating Skill	Description
Requirement append	`/devdocs-requirements`	Full mode must delegate(incremental update)
Design append	`/devdocs-system-design`	Full mode must delegate(incremental update)
Test append	`/devdocs-test-cases`	Full mode must delegate(incremental update + matrix)
Task append	`/devdocs-dev-tasks`	Full mode must delegate
Readiness check	`/devdocs-verify --readiness`	Full mode must delegate(Step 4.5 quality gate)
Development implementation	`/devdocs-dev-workflow`	Step 6: Automatic handoff (user may skip)
Coding constraints	`/code-quality`, `/testing-guide`	Coding phase

Orchestrator boundaries：devdocs-feature is a pure orchestrator, responsible for step orchestration, confirmation flow, and feature logging. The specific requirements, design, testing, and task content are all handled by the corresponding specialized Skills; this Skill does not duplicate their logic.

Constraints

Numbering constraints

Must continue existing numbering; duplicates are not allowed
Must first scan existing documents to obtain the maximum number
Numbering format must remain consistent (F-XXX, US-XXX, AC-XXX)

Document constraints

Appended content must be marked with the feature version and date
Existing content must not be deleted or overwritten
The append location must be correct (end of section)
The format must be consistent with the existing document

Step-by-step orchestration constraints (full mode)

By default, wait for user confirmation after each step is completed
--fast Mode: Step 0 scanning proceeds as usual, Steps 1-4 execute continuously without step-by-step confirmation, and Step 5 generates the feature log and then presents a summary for 1 confirmation
Steps must not be skipped (unless the user explicitly requests it)
The user may choose "terminate" at any step (--fast ; Ctrl+C is available there)
Each step focuses only on the numbering and format of the current document
The information passed between steps is limited to: the list of newly added numbers
In full mode, Step 1-4, Step 4.5, and Step 6 must launch sub-Agents via the Task tool
Only YAML summaries + number lists are passed between steps; the full document text is not passed
Step 0-5 are document phases; producing implementation code is strictly prohibited
Coding occurs only in Step 6 (delegated by dev-workflow)

Lightweight mode constraints

Only update 01-requirements.md and 04-dev-tasks.md
Do not create new F-XXX; only append AC to existing features
The number of tasks is limited to 1-3
The user must be prompted when architectural impact is detected
In lightweight mode, Step 1-4 are document phases; writing implementation code is strictly prohibited
Write operations are limited to docs/devdocs/ Markdown documents under
When coding is required, it must be handed off to /devdocs-dev-workflow

Impact analysis constraints

Modifying existing interfaces must explain backward compatibility
Regression risk points must be listed
High-impact changes require user confirmation

Traceability constraints (full mode)

Newly added F-XXX must have corresponding US-XXX and AC-XXX
Newly added AC-XXX must have corresponding test cases
The traceability matrix must be updated

Special cases

Incomplete document structure

If only some documents exist:

1. 提示用户缺失的文档
2. 建议先补全文档（使用 /devdocs-retrofit）
3. 或仅追加到已有文档

Large-scale features

If the new feature requirements are relatively large (more than 3 feature points):

建议拆分为多次迭代：
1. 按功能模块拆分
2. 每次迭代独立完成
3. 分别提交和验证

Requirement changes (not additions)

If existing requirements are being modified rather than added:

⚠️ 这是需求变更，不是新功能需求。

建议：
1. 在原 F-XXX 下标注变更
2. 更新相关 US/AC
3. 更新受影响的测试用例
4. 记录变更原因

Sub-Agent summary format

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

skill: devdocs-feature
mode: lite | full
new_ids:
  features: [F-004]
  stories: [US-009, US-010]
  acceptance: [AC-016~AC-020]
  tests: [UT-013~UT-015, IT-004]
  tasks: [T-11~T-13]
status: completed | interrupted
step_reached: 1~6
dev_workflow_triggered: true | false
output_files:
  - docs/devdocs/01-requirements.md
  - docs/devdocs/00-feature-log.md

Output

Update 01-requirements.md(append)
Update 02-system-design*.md(append/modify)
Update 03-test-*.md(append)
Update 04-dev-tasks*.md(Append)
Update/Create 00-feature-log.md(Append)

About this skill

Language Rules

Trigger Conditions

Preconditions

Run Modes

Mode Selection

Mode Comparison

Automatic Mode Detection

Core Concept

Lite Mode Flow (--lite)

Lite Mode Constraints

⚠️ Lite Mode Traceability Warning

Full Mode Flow (Step-by-Step Orchestration)

Advantages of Step-by-Step Execution

Step 0: Scan existing documents

Number extraction

Architecture summary (full mode)

Step 1: Requirement addition

Delegation input

Delegation output

✅ Confirmation point (default mode)

Step 2: Design addition (full mode)

Delegation input

Delegation output

✅ Confirmation point (default mode)

Step 3: Test addition (full mode)

Delegation input

Delegation output

✅ Confirmation point (default mode)

Step 4: Task addition

Call devdocs-dev-tasks

✅ Confirmation point (default mode)

Step 4.5: Readiness check (full mode)

Delegation input

Delegation output

Gate rules

Step 5: Generate feature log

Output file

Step 6: Connect to development execution (optional)

Orchestration specification (sub-agent scheduling)

Scheduling principles

Skill collaboration

Constraints

Numbering constraints

Document constraints

Step-by-step orchestration constraints (full mode)

Lightweight mode constraints

Impact analysis constraints

Traceability constraints (full mode)

Special cases

Incomplete document structure

Large-scale features

Requirement changes (not additions)

Sub-Agent summary format

Output