feature

New Feature

Append new features to an existing keel project, ensuring numbering continuity and document consistency.

Language Rules

• Support questions in Chinese and English
• Always reply in Chinese

Trigger Conditions

• The user wants to add a new feature to an existing project
• The user mentions "incremental", "iteration", "new feature", "additional requirements"
• The user requests extending an existing feature

Preconditions

• A keel document directory already exists:docs/devdocs/
• Exists 01-requirements.md or 00-baseline.md

Has 00-baseline.md and no 01-requirements.md(baseline project): This skill creates 01-requirements.md，F-001 starting from this new requirement. Existing code is not numbered—the historical implementation of a baseline project does not enter the numbering system; only real changes after the baseline have F/US/AC.

If neither exists, it is recommended:

• New project → /requirements
• Existing code with no docs → /retrofit(establish project baseline)

⛔ This precondition once hardcoded "at least exists 01-requirements.md", which with /retrofit 's "baseline already established, no retrofit needed" final state forms a dead loop: want to add a new feature → feature says go run retrofit → retrofit says baseline already established → back to feature. A baseline project must be able to enter from here.

Quick Start

One sentence: Append new features to an existing keel project, automatically orchestrating requirements/design/tests/tasks.

Most common usage: /feature "功能描述"(automatically selects the tier). To force a tier or reduce confirmations, just say so.

This skill is the orchestration layer, responsible for normalization. The user's natural language ("don't ask step by step", "be careful") is normalized by it into ceremony（fast / standard / deep) written into the delegation handshake, passed down to requirements / system-design / test-cases / dev-tasks; the delegateonly reads this field and no longer interprets the user's original words itself（task/intent-normalization）。

⚠️ ceremony and "lightweight / full mode" are two different things: mode is determined byimpact scopeauto-detection (determines which documents are produced),ceremony is determined byuser intentnormalization (determines how many times to ask). The two are independent and must not be derived from each other.

Not suitable? New project→/pipeline init, fix Bug→/bugfix, existing code with no docs→/retrofit

Run Modes

Mode Selection

/feature "功能描述"             → 自动检测模式（Lite/Standard/Deep）
/feature F-XX realign           → 只对齐 F-XX 关联产物（调度 system-design/test-cases/dev-tasks/dev-workflow --realign=F-XX）；共享契约见 [../pipeline/references/realign.md](../pipeline/references/realign.md)

Mode Comparison

Mode	Applicable Scenario	Update Documents	Context Load	Verification Strength
Lightweight Mode	Configuration changes, UI tweaks, simple fields	01 + 04	Low	Basic
Full Mode	New modules, new interfaces	01 + 02 + 03 + 04	High (step-by-step)	Standard
Deep Mode	Cross-module architecture changes, security-related, core data models	01 + 02 + 03 + 04	High (step-by-step)	Mandatory review + docs alignment

Automatic Mode Detection (Three Tiers)

Analyze the requirement description and recommend a tier based on impact scope:

Deep 信号（任一命中 → 深度模式）：
[ ] 跨模块依赖变更（影响 ≥2 个现有模块的边界）
[ ] 安全相关变更（认证、授权、加密、敏感数据）
[ ] 核心数据模型/表结构变更
[ ] 架构模式变更（如新增中间件层、消息队列）

Standard 信号（任一命中 → 完整模式）：
[ ] 新增 API 接口
[ ] 数据模型变更（非核心表）
[ ] 组件间依赖变化
[ ] 第三方服务集成
[ ] 新增独立模块

Lite（以上均无）→ 轻量模式

# Deep 示例
检测到高影响变更：
- 跨模块：AuthModule ↔ UserModule 边界变更
- 安全相关：认证流程修改

建议使用深度模式（强制 review + docs 验证）。[深度/完整/轻量]

# Standard 示例
检测到架构变更：
- 新增接口: UserPreferenceAPI

建议使用完整模式。[完整/轻量]

⛔ The first requirement of a baseline project is forced to go through the full/standard tier：docs/devdocs/00-baseline.md exists and there is no 01-requirements.md , the automatic tier detection result is always upgraded to the standard tier. Lightweight mode Step 1 must read 01-requirements.md to get the maximum AC number, and the constraint "do not create new F-XXX, only append to existing features" — neither holds for a baseline project. Lite is available from the second requirement onward.

Core Concept

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

Lightweight Mode Workflow

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

Lightweight Mode Constraints

• Steps 1-4 are the documentation phase and only produce Markdown documents under docs/devdocs/ ; no implementation code is written. When coding is needed, it must be connected via Step 6 to /dev-workflow
• Do not create new F-XXX (feature points); only append ACs 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 append task; it is recommended to confirm before entering dev-workflow that corresponding entries already exist in 03-test-cases, dev-workflow will automatically detect and prompt for completion at startup)
• The task volume is small enough to append directly, with no need to invoke dev-tasks; if it exceeds that, switch to the standard tier
• Milestone attribution is inherited automatically: the lightweight task hangs on the existing F, and that F's value in 01 §2 "Attributed Milestone" is its segment. ⛔ Do not write M separately on the task card (the §2 attribution column is the sole authoritative source); ⛔ Do not bypass segmented execution because of lightweight mode
• Tasks must follow the TAR principle format

⚠️ Lightweight Mode Traceability Warning

Lightweight mode skips updates to the 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 the test layer). The following warning must be displayed at Step 4 user confirmation:

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

Full Mode Workflow (Step-by-Step Orchestration)

Core change: no longer update 4 documents all 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	Maintain 4 sets of numbering at once, error-prone	Focus only on the current document's numbering at each step
Missed updates	Context is too long, easy to miss	Confirm at each step, nothing is missed
Incomplete traceability	Difficult to guarantee AC→test completeness	Step 3 focuses on the traceability matrix
Difficult to roll back	Full-scale modifications are hard to roll back	Can be terminated at any step

Detailed Explanation of Full Mode Steps

For the detailed delegation specification for Full Mode Steps 0-6 (inputs/outputs/confirmation points/sub-Agent scheduling), see references/full-mode-steps.md。

Key points summary:

• Step 0 Scan numbering + architecture summary
• Steps 1-4 delegate respectively to /requirements / /system-design / /test-cases / /dev-tasks(must be a Task tool sub-Agent)
• Step 4.5 delegate to /verify --readiness as the pre-development quality gate
• Step 5 generate 00-feature-log.md(template see templates/feature-log-template.md）
• Step 6 optionally connects to /dev-workflow(deep mode automatically --review + upon completion --docs verification)

Orchestration Principles: Context isolation + summary passing + exception fallback + do not troubleshoot on your own.

Skill Collaboration

Phase	Collaborating Skill	Description
Requirements Append	/requirements	Full mode must delegate(incremental update)
Design Append	/system-design	Full mode must delegate(incremental update)
Test Append	/test-cases	Full mode must delegate(incremental update + matrix)
Task Append	/dev-tasks	Full mode must delegate
Readiness Check	/verify --readiness	Full mode must delegate(Step 4.5 quality gate)
Development Implementation	/dev-workflow	Step 6 automatic handoff (user can skip)
Coding Constraints	/code-quality, /testing-guide	Coding Phase

Orchestrator Boundaries：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 Skill; this Skill does not duplicate its logic.

Constraints

Numbering Constraints

• Must continue the existing numbering, no duplicates
• Must first scan existing documents to obtain the maximum number

Document Constraints

• Appended content must be labeled with the feature version and date
• Must not delete or overwrite existing content

Step-by-Step Orchestration Constraints (Full Mode)

• By default, wait for user confirmation after each step completes
• Must not skip steps (unless the user explicitly requests it)
• Information passed between steps is limited to: new number list
• Full mode Step 1-4, Step 4.5, Step 6 must launch sub-Agents via the Task tool
• Between steps, only the YAML summary + number list are passed, not the full document text
• ⛔ Prohibited from continuing: the documentation phase (Step 0-5) must not produce implementation code(Recovery method: move code output to Step 6 dev-workflow delegation)

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
• Must prompt the user when architectural impact is detected

Deep Mode Constraints

• Automatically append when handing off to dev-workflow --review(all tasks enforce adversarial verification)
• Automatically execute after development completes /verify --docs(alignment between document layers)
• Must prompt the user to confirm mode selection when a Deep signal is detected
• Deep signals: cross-module boundary changes, security-related, core data models, architectural pattern changes

Impact Analysis Constraints

• Modifying existing interfaces must specify backward compatibility
• Must list regression risk points
• High-impact changes require user confirmation

Traceability Constraints (Full Mode)

• New F-XXX must have corresponding US-XXX and AC-XXX
• New AC-XXX must have corresponding test cases
• Must update the traceability matrix

Special Cases

Case	Handling
Incomplete document structure	Missing document indicated, suggest /retrofit complete
Large-scale feature (>3 feature points)	Suggest splitting by module into multiple iterations
Requirement change (not new addition)	Mark the change under the original F-XXX, update US/AC/tests, and record the reason

Sub-Agent Summary Format

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

skill: feature
status: success | failed | interrupted | partial
summary:
  headline: "完整模式 Step 4 完成，新增 F-004"
  details:
    mode: lite | full
    step_reached: 1~6
    dev_workflow_triggered: true | false
blockers: []
output_files:
  - docs/devdocs/01-requirements.md
  - docs/devdocs/00-feature-log.md
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]
next_recommended:
  skill: dev-workflow
  args: "T-11~T-13"

Output

Update 01-requirements.md、02-system-design*.md、03-test-*.md、04-dev-tasks*.md、00-feature-log.md。