design

/design — Development design

Receive feature requirements, automatically inventory available resources (agents/skills), build a complete implementation plan via the Plan agent, and output it to plans/active/.md.It will not automatically execute the implementation; it must wait for the user's confirmation.

Step 0: Task tracking (default text list, non-interrupting)

Tracking by default does not depend on the Task tool. TaskCreate / TaskUpdate / TaskList On Opus 4.8, Sonnet 5, Fable 5, Mythos 5 and newer modelsdoes not exist by default(as of Claude Code v2.1.233, see rules/task-tracking-availability.md). Default approach: maintain a numbered Step list within the reply and mark each item's status — same precision as the tool, the only difference being no UI panel.

During the planning phase (Step 1–4), do not issue an AskUserQuestion separately for task tracking. and when the session does not have the Task tool, directly remove the "Task tracking" question from the Step 6 batch inquiry— do not ask about a switch that cannot be turned on at the moment (an env var only takes effect after a session restart). Only when the session actually has the Task tool (the user has set CLAUDE_CODE_ENABLE_TODO_TOOLS=1 or --allowedTools) should it be included in that batch inquiry. If the user has explicitly enabled it → directly create subtasks with TaskCreate (including activeForm, and addBlockedBy when necessary), and mark them completed with TaskUpdate upon completion;if the call fails, just continue, do not abort the flow。

Why defer: HITL waiting is the largest wall-clock cost of the entire /design→implementation process. Measured in the 2026-07-16 PDT-10398 session: of the full 3.5h, ~85–100 min was spent waiting for user replies, of which ~40 min came from 4 AskUserQuestions scattered throughout the flow, each blocking on its own (Task tracking, Worktree, advancement method, formation authorization). These four questions are independent of each other, and their answers all fall into the "how to execute" category, so merging them into a single inquiry after the plan is written is sufficient — if asked separately, each question may hit a window when the user is away.

Step 1: Inventory available resources

Tracking: In the reply's Step list, mark "Inventory available resources" as in progress, and mark it as complete when done. (When the session has the Task tool and it is enabled, use TaskCreate(subject: "盤點可用資源", activeForm: "掃描 agent/skill 中...") → TaskUpdate(status: "completed")）

Inventory Claude Code built-in resources as planning references:

Agent types：Plan(planning, see Step 3),Explore(read-only search and locate),general-purpose(multi-step research/review, see Step 4a)
Built-in skills：/code-review(quality review),/security-review(security review),/simplify(reuse/simplification/efficiency cleanup),/verify(end-to-end behavior verification)
This repo's self-maintained agents/ definitions(see agents/README.md index):complexity-triage(Step 2a triage),doc-reviewer(Step 4a review),doc-updater(for /update use),tdd-guide(when a new feature/bug fix lacks test coverage, its red-green-refactor flow may be referenced)
Based on the user's requirements ($ARGUMENTS), filter outrelevant resources

Output: A concise resource list, marking each resource's degree of relevance to the current requirement (high/medium/low).

Step 2: Complexity assessment

Step 2a: Triage subagent (before any heavy process)

Before entering the full process, first dispatch a lightweight triage agent to determine complexity——Do not let the main model judge by impression, and do not let tasks that can take the fast path fall directly into the full ceremony (2026-07-10 user instruction):

Agent(subagent_type="general-purpose", model="haiku")

haiku is the low-cost tier. Execute according to the definition in agents/complexity-triage.md (the triage process, criteria table, and red flags all use that file as the authoritative version); attach the contents of that file to the prompt or directly reference the path. For path resolution and invocation conventions, see agents/README.md。

Input：$ARGUMENTS + the requirement context in the conversation (/notion-plan sources include the organized Markdown) + the project root directory path
Action: only Glob/Grep/Read are allowed to roughly estimate the scope of impact (find the files that may need to be changed, determine whether there are solution trade-offs),do not read deeply, do not design solutions; for the output contract, see the "Output Format" section of agents/complexity-triage.md (the sole authority; the JSON schema is not repeated here)
Main model adjudication: adopt or reject against the table below——when the triage result conflicts with the main model's judgment,take the higher complexity(triage may only fail to downgrade, and may not fail to upgrade);ambiguous_requirements=true → first use AskUserQuestion to supplement requirements, then re-triage
The triage agent costs about 5-15K tokens, and what it buys is: low-complexity tasks skip the full ceremony of the Plan agent + the cost of the 61K-token review agent

Step 2b: Path determination

Based on the triage result, choose the execution path:

Complexity	Judgment criteria	Execution path
Low (fast path)	Single bug fix or small change: ≤3 files, no architectural decisions, clear direction for the fix (e.g., display logic bug, update README, change configuration)	Step 3 (streamlined plan, see below) → Step 4a change to main model self-check (do not dispatch a subagent) → Step 4b
Medium or above	Cross-file and with architectural impact, or the direction of the fix requires trade-offs	Step 3 (including architectural decisions) → Step 4 (including architectural review)
Multi-session	Large plans that need continuous progress across sessions (framework migration, multi-day refactoring)	Follow the standard process to produce a plan; hand off cross-session progress to `/plan-run`(state is persisted in `plans/active/.plan-state/`）

The rationale for the fast path(2026-07-10 PDT-10428 precedent): a P2 display bug went through the full ceremony, producing an industry reference table, community consensus table, RTM, and threat model, and was then sent back by the 61K-token review agent for revision over bureaucratic formatting items such as "missing performance evaluation section" and "missing documentation impact chapter"——not one of the 4 FAILs changed the implementation direction. Ceremony cost should be proportional to risk × irreversibility, not to process completeness.The number of files is not the only criterion: bug fixes often span 2-3 files (util + component + test) but are still a single decision, so they belong to the fast path; conversely, a single file that involves solution trade-offs (caching strategy, state management selection) goes to medium.

If the requirement is too vague to determine complexity, use AskUserQuestion to ask the user to supplement specific information.

Whichever path is taken, plans/active/.md is output.

Step 3: Plan agent — create the implementation plan

Tracking: In the reply's Step list, mark "Plan agent creates implementation plan" as in progress, and mark it as complete once done. (When the session has the Task tool and it is enabled, use instead TaskCreate(subject: "Plan agent 建立實作計畫", activeForm: "Plan agent 規劃中...") → TaskUpdate(status: "completed")）

Use the built-in Plan agent to create a detailed implementation plan.

Agent(subagent_type="Plan")

Input context:

The user's requirement description ($ARGUMENTS + conversation context)
The list of available resources inventoried in Step 1
The current project structure (understood via ls、git status , etc.)

The plan must include:

The plan is divided into two groups of sections:Core sections (Group A, required by default for all complexity levels) and Research sections (Group B, only when triggered by risk). The criterion is "ceremony cost proportional to risk × irreversibility" (see the principle at Step 2b line 57)—complexity only determines "the depth of the core sections" and "whether Step 4 review dispatches a subagent",not whether research sections appear。

Group A — Core sections (included by default at all complexity levels):

Requirement breakdown — decompose the requirement into executable subtasks
Technical approach — the implementation method for each subtask
Architecture decisions(fill in only when there are architectural trade-offs; may use a condensed form) — technical choices involving architecture must include: the chosen option and rationale, at least 1 rejected alternative and the reason, compatibility with existing code, and performance and security impact; tasks without architectural trade-offs may omit this section (e.g., pure display bugs, copy changes, configuration changes)
Available resource integration — explicitly indicate which agent/skill each step should use (e.g., "Step 3: use Plan agent", "Step 5: use /code-review").Resource allocation must be confirmed through the Step 1 inventory — do not assume resources are available
Dependencies — which steps must be executed in order, and which can be parallelized
Risk assessment — potential technical risks and countermeasures
Security / Threat Model(proactively triggered, according to the trigger gate of rules/security-guidance/skill-integration.md ) — first determine whether the plan touches security-sensitive surfaces (authentication/input/endpoint/DB/deserialization/file/shell/SSRF/DOM/encryption):Touched → must include a "Security / Threat Model" section, checking item by item against ~/.claude/claude-security-guidance.md(the same criteria as the plugin), and post-implementation steps must incorporate /security-review；Not touched → one sentence: "No security-sensitive surface, skipped", without leaving an empty list
Acceptance criteria — what counts as done
Test coverage(when adding new features/fixing bugs and test coverage is lacking) — the relevant steps may reference the red-green-refactor flow of agents/tdd-guide.md , writing failing tests first and then implementing, aligned with the global 80% coverage rule
Token budget — for medium complexity and above, annotate each step with [expected number of agents × model tier × estimated tokens]; for low complexity, reduce it to a one-line total estimate

Group B — Research sections (added only when triggered by risk; omitted entirely by default):

Industry practices and standardized solution references — industry standards/conventions (RFC, W3C, OWASP, 12-Factor, etc.), academic research or mature standardized solutions,community consensusanddissenting opinions/known pitfallsquotation from
Requirements Traceability Matrix (RTM) — each requirement (REQ-1, REQ-2...) maps to implementation steps and acceptance criteria, for Step 4a requirement coverage set-difference comparison

Group B trigger conditions (include if any is met, otherwise omit): ①High risk or irreversible (production data migration, destructive schema changes, payment flows, authentication/authorization aspects); ②introducing a new architecture/new framework/new pattern not yet adopted by the team (the selection itself must convince others); ③the user explicitly requests rigorous argumentation or cited evidence.Default scenarios that do not trigger(including most implementation tasks, even across multi-session): feature development, refactoring of existing patterns, self-contained components/POCs, bug fixes—these require only the Group A core sections.

When Group B is not triggered, the corresponding Step 4a review is relaxed：agents/doc-reviewer.md The two dimensions "industry/academic support" and "community consensus and dissenting opinions" are checked only when Group B is triggered; when not triggered, mark N/A, and do not judge FAIL due to missing research sections. For requirement coverage, when there is no RTM, use the requirement list directly for set-difference.

Additional streamlining for low complexity (fast path): Group A is further trimmed to 1, 2, 7, 8, 10 + Implementation Steps (S-code format unchanged, maintaining /plan-run compatibility); 4 is filled in only when there are architectural trade-offs; 9 is reduced to a one-sentence determination. Diagnostic steps (live verification, payload capture) are not ceremonial and must not be trimmed—when ticket assumptions contradict the code, the diagnostic gate is the most valuable part of the fast path.

Step 4: Quality Check and Plan Mode Presentation

Tracking: In the reply's Step list, mark "Quality Check and Plan Mode Presentation" as in progress (prerequisite = Step 3), and mark it as complete after completion. (When the session has the Task tool and it is enabled, use TaskCreate(subject: "品質檢查與 Plan Mode 呈現", activeForm: "品質檢查與輸出中...", addBlockedBy: [Step 3 TaskCreate 回傳的 task ID]) → TaskUpdate(status: "completed")）

Step 4a: Quality Review (subagent isolation)

Fast path (low complexity) does not dispatch a subagent: the main model self-checks with a 7-item streamlined list—executability (each step has a file path + action), dependency correctness, testable acceptance, presence of post-implementation QA steps, presence of diagnostic gates (when ticket assumptions have not been live-verified), security-sensitive surface determination, test coverage (new/modified logic has corresponding tests, or an explicitly stated reason why not needed, may cite agents/tdd-guide.md). If any fails, directly revise the plan, without entering a FAIL loop. The subagent review below applies only to medium or higher complexity.

Launch general-purpose subagent to review the Step 3 plan in an isolated context. Do not use the disabled architect agent (both the ECC version and the unprefixed version are disabled, ablation experiment delta=-0.50, see rules/refactor/remove-architect-pipeline.md), instead use a general-purpose agent to perform the review according to the definition and checklist in agents/doc-reviewer.md . For path resolution and invocation conventions, see agents/README.md。

Agent(subagent_type="general-purpose", model="sonnet")

prompt: "Perform the review according to the definition and checklist in agents/doc-reviewer.md" + the context below.

Context passed to the subagent:

The complete plan content produced in Step 3
The resource inventory results from Step 1
The complexity level determined in Step 2

The authoritative version of the checklist is in agents/doc-reviewer.md(basic quality dimensions + architecture review dimensions + research support dimensions), this section retains only an execution contract summary: the subagent must check item by item and report results (PASS/FAIL + explanation). The two dimensions "industry support" and "community consensus"only when the Group B research sections are triggeredActive verification (missing citations / incorrect citations / failure to disclose opposing views → FAIL); for the streamlined plan not triggered by Group B, mark these two dimensions as N/A and do not judge FAIL.If agents/ directory does not exist (incomplete installation), obtain from https://github.com/ashe-li/agent-skills of agents/doc-reviewer.md , or ask the user to rerun npx skills update。

Handling after subagent reports:

All PASS: Proceed to Step 4b
Has FAIL items: Feed back to Step 3 for replanning (pass the FAIL items and correction directions as additional context to the Plan agent), and after correction relaunch the Step 4a subagent check. Initial check + up to 2 retries (up to 3 rounds total)
Still FAIL after 3 rounds: Mark items pending confirmation in the plan's Review Notes and leave it to the user to decide

Step 4b: EnterPlanMode to present the plan

After the quality check passes, use EnterPlanMode to present the complete plan content to the user.

Why use Plan Mode: Claude Code 2.1.77+ automatically names the session when the user accepts the plan. Presenting the plan via Plan Mode triggers session auto-naming after the user accepts, and also serves as the formal plan confirmation process.

Content to present: Present the complete plan (according to the format below) as the Plan Mode output. Write/Edit cannot be used in Plan Mode, sopresent only, do not write files。

After the user accepts: ExitPlanMode triggers session auto-naming, then proceed to Step 5 to write the file.

Long waits can be notified: the approval after the plan is presented is the longest HITL gap in the entire flow (measured 43 min on 2026-07-16—the user left without knowing the plan was ready). Before presenting the plan, if the harness has a PushNotification tool, send a "plan ready for review" notification; do the same before the Step 6 batch inquiry.

Step 5: Generate Slug and write to the plan file

After the user accepts in Plan Mode (ExitPlanMode), write the plan to a file.

Slug generation rules: From the plan's H1 title (# Implementation Plan: <名稱>) take the part after : and convert it to kebab-case (keep only alphanumerics and -, convert Chinese and special characters to -, deduplicate, truncate to 60 characters, all lowercase); when it cannot be converted, such as for an all-Chinese title, use plan-YYYYMMDD. Example:Stripe Subscription Billing → stripe-subscription-billing。

Output path: plans/active/<slug>.md(relative to the project root)

If the directory does not exist, automatically mkdir -p plans/active/
If a file with the same name already exists, use AskUserQuestion to ask: overwrite / add date suffix / cancel

plan format:

# Implementation Plan: [功能名稱]

> Generated by /design on [日期]
> Plan file: plans/active/<slug>.md
> Status: PENDING APPROVAL

## Overview
<!-- 1-3 句話描述目標 -->

## Resources
<!-- 本次計畫使用的 agents/skills -->

| Resource | Type | Usage |
|----------|------|-------|
| Plan | agent | Step 3: 建立實作計畫 |
| /code-review | skill | Step 5: 品質審查 |
| /simplify | skill | Phase 2: dead code、命名、nesting、重複程式碼合併 |
| ... | ... | ... |

<!-- 以下兩張研究表為 B 組，僅在 Step 3 B 組觸發條件成立時填入；否則整段省略 -->
## Industry & Standards Reference（B 組，風險觸發才填）
| 技術決策 | 參照依據 | 類型 | 來源 |
|----------|---------|------|------|
| ... | ... | 業界標準/學術研究/標準化方案/最佳實踐 | ... |

## Community Consensus & Dissenting Views（B 組，風險觸發才填）
| 技術決策 | 社群共識 | 反面意見/已知陷阱 | 來源 |
|----------|---------|------------------|------|
| ... | ... | ... | GitHub/SO/Reddit/... |

## Implementation Steps

<!--
格式約束（/plan-run state machine 需要）：
- Step 標頭：`- [ ] **S<phase>.<num>** — <title>`（S-code 必填，例 S1.1、S1.2、S2.1）
- 欄位：兩個空格縮排 + ASCII 冒號（`  - Files: ...`，不要 bold、不要全形冒號）
- Dependencies 值：純 step ID list（`S1.1, S1.2`），支援 range（`S1.1 ~ S2.3`），禁止自由文字
-->

### Phase 1: [實作階段]
- [ ] **S1.1** — [Step title]
  - Files: src/foo.ts, src/bar.ts
  - Agent: `planner`
  - Action: ...
  - Dependencies: []
  - Why: ...

> **Dependencies canonical form**: 無 deps 時用 `Dependencies: []`（不要省略整個欄位、不要寫 `None` 或留空白），plan_runner.py parser 對 `[]` 一致處理。有 deps 時用 step ID list：`Dependencies: S1.1, S1.2` 或 range `Dependencies: S1.1 ~ S2.3`。

### Phase 2: [品質保障]
- [ ] 執行 /code-review 審查程式碼品質
- [ ] 執行 /simplify 自動修正（dead code、命名、nesting、重複程式碼合併）
- [ ] 執行 /security-review 檢查安全性
- [ ] 執行 /verify 進行全面驗證

### Phase 3: [文件同步]
- [ ] 執行 /update 更新知識庫（文件更新 + 審查 + inline 5 維知識沉澱）
- [ ] 或手動同步相關文件（README、docs/）

## Architecture Notes
<!-- 中等以上複雜度必填 -->
<!-- 每個架構決策：選擇方案、排除的替代方案、相容性分析、效能/安全影響 -->
<!-- 文件影響評估：實作後需新增或更新哪些文件 -->

## Risks & Mitigations
<!-- 風險評估 -->

## Acceptance Criteria
- [ ] ...
- [ ] ...

## Review Notes
<!-- 計畫品質自審的結果 -->

After writing, prompt the user:

plans/active/<slug>.md has been written. You can start implementation; after implementation is complete, run /plan-archive to archive.

Step 6: Execution mode batch confirmation (single AskUserQuestion, the only pre-execution HITL consolidation point)

After the plan is written, consolidate all "how to execute" decisionsinto a single AskUserQuestion(the tool supports up to 4 questions in a single call), rather than scattering them throughout the flow and asking one by one. Batch composition:

Question	Options (first option = Recommended)	When to remove from the batch (if the answer is already known, do not ask)
Task tracking (Only when the session has the Task tool）	Enabled (Recommended) (with token estimate) / Disabled	If the session has no Task tool, exclude it(this is already the case for the default model, see `rules/task-tracking-availability.md`, switch to a text list); the user has explicitly stated a preference; a low-complexity single fix proceeds without asking
Worktree	Yes, create a sibling worktree (Recommended) / No, current directory	`rules/worktree-prompt.md` Skip conditions: already stated, already in a worktree, small task
Advancement method	Recommend based on complexity (table below)	The user has already stated a preference in `$ARGUMENTS` or in the conversation
Squad authorization	Enable parallelism (Recommended) (with token estimate) / single-track sequential	The plan's Dependencies DAG has no parallelizable branches; or the user has already stated a preference

All questions excluded → the entire batch is skipped and work begins directly.
After the batchDo not issue a second AskUserQuestion for these four types of decisions. Decisions newly discovered during implementation (such as scope issues uncovered by code review) are still asked immediately, butbefore asking, dispatch the work that does not depend on that answer first(agents run while waiting for the answer, rather than everyone stopping to wait).

Execution details for batch answers:

Worktree = Yes: follow the rules/worktree-prompt.md path convention to create a sibling worktree (git worktree add ~/Documents/<project>-<slug> -b <branch>), and prompt to run after development is complete /pr。
Squad = Enabled: dispatch in parallel according to the plan's Dependencies DAG; if not enabled, advance sequentially.
Advancement method: see below.

Advancement method options

Recommend based on the complexity determined in Step 2:

Complexity (determined in Step 2)	Recommended option
Low (1-3 steps, no dependencies)	LLM autonomous advancement
Medium (4-10 steps, with dependencies)	`/plan-run`(Recommended)
High (10+ steps, complex DAG, multiple parallel tracks)	`/plan-run`(Strongly recommended; if it will span sessions, additionally attach a Stop hook)

Option text (place into the "Advancement method" question of the batch inquiry):

/plan-run — the advancement order is determined by the state machine and will not skip steps; you do not need to manually prod each step, and it will periodically stop for your confirmation. By default it uses the built-in /goal to provide continued advancement force (zero installation); for long plans spanning sessions, you can instead attach a Stop hook. On failure, it still uses AskUserQuestion to hand back to a human for a decision

LLM autonomous advancement — start implementing directly in the current session; suitable for simple linear plans, with no state machine overhead

Do not start for now — end /design, and the user decides the timing separately

Prerequisites and exceptions for option 1: the default mode has zero installation (init --no-attach + one /goal). Only whencross-session continued advancementis needed do you need to install a Stop hook (see docs/hooks-setup.md), and that path only recognizes plans under $HOME —those falling in $HOME pointer cannot be attached otherwise; use the default mode. When uncertain about the plan or there are high-risk irreversible steps, you can pause automatic progression and confirm step by step—these operations are all in the /plan-run documentation.

If 1 (/plan-run）：

normalize fallback (running in canonical format is a no-op):python3 "${AGENT_SKILLS_HOME:-$HOME/Documents/agent-skills}/scripts/plan_runner.py" normalize plans/active/<slug>.md --write. stderr shows Wrote normalized plan → normalized (.bak backup in the same directory); shows WARN: Dependencies prose did not yield step IDs → that line needs a manually added step ID
Initialize state (default mode A, zero installation）：python3 "${AGENT_SKILLS_HOME:-$HOME/Documents/agent-skills}/scripts/plan_runner.py" init plans/active/<slug>.md --no-attach. If it returns No steps found in plan, handle it according to the hint field in the returned payload;warnings if the field is only range syntax that has already been automatically expanded, it can be ignored
Prompt the user (mode A)./goal The text is taken verbatim from plan-run/SKILL.md Step 1.5; those three pieces of wording are intentional, do not rewrite them:
State has been initialized at <state_path>. The next command will continue on its own:
```
/goal plans/active/<slug>.md 的所有 step 都已 completed 或 skipped——判準是 plan_runner.py 的
輸出出現 Progress: N/N；或同一個 step 連續 2 輪沒有前進。尚未達成時，下一輪第一個
動作必須是跑 python3 ~/Documents/agent-skills/scripts/plan_runner.py next plans/active/<slug>.md，
照它印出的三行做完並回報 complete，不要問使用者是否繼續。

現在開始推進，每輪盡量多推幾步。
```
You can run python3 "${AGENT_SKILLS_HOME:-$HOME/Documents/agent-skills}/scripts/plan_runner.py" status plans/active/<slug>.md at any time to check progress./clear, compaction, and starting a new session will make /goal disappear; the state file is still there, and reissuing the same /goal will resume it.
Onlywhen the user explicitly wants to continue across sessions and python3 "${AGENT_SKILLS_HOME:-$HOME/Documents/agent-skills}/scripts/plan_runner.py" doctor 's two items—"Stop hook registered" and "wrapper exists and is executable"—both PASS, switch to mode B: remove --no-attach from step 2 and rerun init(idempotent; it will attach the pointer in cwd), and change the prompt to "the hook will take over from the next round,do notissue /goalagain". When the plan is outside $HOME , the pointer cannot be attached, so stay in mode A. The two drivers cannot be enabled at the same time—the continuation round limit is shared by all blockers; stacking them does not buy more steps, only mutually diluted instructions.

If 2 (LLM autonomous progression): goes directly into the standard implementation flow (the plan can still be switched at any time /plan-run，state machine init is idempotent; future calls are unaffected).

If 3 (do not start yet): end /design, and inform: The plan has been saved at plans/active/<slug>.md; you can run /plan-run plans/active/<slug>.md at any time to start progression, or start implementing directly in the session.