claudecode-boilerplate/.claude/commands/add-feature.md

description
Implement a new feature following existing patterns, fully autonomously without stopping

Adding a New Feature (Fully Autonomous Execution Mode)

Important: This workflow is designed to run fully automatically from start to finish without user intervention. After completing each step, immediately move on to the next step. Do not ask the user for confirmation mid-thought or interrupt the work.

Feature name: $ARGUMENTS (e.g. /add-feature User profile editing)

---

Step 1: Preparation and Context Setup

1. Establish the current task context:

• Feature name: $ARGUMENTS
• Date: [get the current date in YYYYMMDD format]
• Steering directory path: .steering/[date]-[feature name]/

2. Create the steering directory above.
3. Create the following three empty files:

• [steering directory path]/requirements.md
• [steering directory path]/design.md
• [steering directory path]/tasklist.md

Step 2: Understand the Project

1. Read CLAUDE.md to grasp the overall picture of the project.
2. Review the persistent documents in the docs/ directory to understand the relevant design philosophy and architecture.
3. If docs/milestones/ exists, read docs/milestones/roadmap.md and find the phase file (docs/milestones/phase[N]-milestones.md) whose milestone contains this feature. Use the feature's description, related requirements, affected screens, and acceptance criteria as the basis for planning. If the feature is not in any phase file, note that it is unplanned work and proceed.

Step 3: Investigate Existing Patterns

1. Use the Grep tool to search the source code (src/) for keywords related to the feature name.

Grep('[keyword related to the feature]', 'src/')

2. Analyze the search results to identify existing implementation patterns, naming conventions, and how components are used.

Step 3.5: Check the Design Specification (Before Implementation)

Before implementing any feature, respect the UI/UX design specification.

1. Check whether the design files exist:

   • docs/design/design-brief.md
   • docs/design/design-tokens.json
   • docs/design/ui-blueprint.json
   • docs/design/platform-mapping.md

2. If the design files do not exist, warn the user and suggest running /define-design before continuing. Do not silently proceed without a design spec.

3. If the design files exist, read all four of them before implementation:

   1. docs/design/design-brief.md
   2. docs/design/design-tokens.json
   3. docs/design/ui-blueprint.json (source of truth)
   4. docs/design/platform-mapping.md

4. If the feature changes the UI, update the design files first, following the /update-design order:

   • ui-blueprint.json → design-tokens.json → design-brief.md → platform-mapping.md → regenerate affected screens/*.svg
   • The blueprint is the source of truth; SVGs are visual references only.

5. Then implement the feature according to the selected platform mapping in platform-mapping.md, using tokens from design-tokens.json (no hard-coded values) and the component tree from ui-blueprint.json.

Step 4: Planning Phase (Automatic Generation of Steering Files)

1. Run Skill('steering') in planning mode to generate the contents of the three files created in Step 1 (requirements.md, design.md, tasklist.md).
2. Once this step completes successfully, never stop; immediately proceed to Step 5.

Step 5: Implementation Loop (Fully Working Through tasklist.md)

This step is a loop that repeats automatically until all tasks in tasklist.md are [x]. Once this step completes successfully, never stop; immediately proceed to Step 6.

Loop start:

1. Read the task list:

• Read the [steering directory path]/tasklist.md file.

2. Check progress:

• Check whether any incomplete tasks ([ ]) exist in the file.
• If no incomplete tasks exist: consider this implementation loop complete and immediately proceed to Step 6.
• If incomplete tasks exist: proceed to the next step (3. Execute the task).

3. Execute the task:

• Identify one incomplete task at the top of tasklist.md.
• Carry out the implementation work needed to complete that task.
• Use Skill('steering') in implementation mode.
• Always follow the coding standards in Skill('development-guidelines').

4. Update the task list:

• Once the executed task is complete, use the Edit tool to update tasklist.md, changing the task from [ ] to [x].

5. Continue the loop:

• Return to the top of Step 5 (1. Read the task list) and repeat the process.

---

* Exception-Handling Rules Within the Implementation Loop *

If any of the following situations occur while the implementation loop is running, handle them autonomously according to these rules and continue the loop.

• Rule A: When a task is too large

  • Handling: Break the current task into multiple smaller subtasks. Use the Edit tool to delete the original task and insert the new subtasks (with [ ]) in its place. Then continue the loop.

• Rule B: When a task becomes unnecessary for technical reasons

  • Condition: Apply only when there is a clear technical reason, such as a change in implementation approach, architecture, or dependencies.
  • Handling: Use the Edit tool to update the task in the format [x] ~~task name~~ (Reason: [briefly describe the specific technical reason]). Then continue the loop.

• ❌ Strictly Forbidden Actions:

  • Intentionally skipping an incomplete task for reasons such as "do it later" or "make it a separate task."
  • Leaving incomplete tasks unaddressed and ending the loop without reason.
  • Asking the user to make a decision.

---

Step 6: Implementation Validation (Launch a Subagent)

1. Do a final check that all tasks in tasklist.md are complete.
2. Use the Task tool to launch the implementation-validator subagent to validate quality.

• subagent_type: "implementation-validator"
• description: "Implementation quality validation"
• prompt: "Please validate the quality of all the changes related to the [feature name] implemented this time. The target files are [list of paths of the implemented files]. Focus on coding standards, error handling, testability, and consistency with existing patterns."

Once this step completes successfully, never stop; immediately proceed to Step 7.

Step 7: Run Automated Tests (including Playwright E2E)

1. Write or update the feature's end-to-end tests following the e2e-testing skill (Skill('e2e-testing')):

• Create/update e2e/[feature-name].spec.ts covering the feature's acceptance criteria.
• If Playwright is not yet set up in the repository, set it up first as described in the skill.

2. Run the following commands in order and confirm that all of them pass.

Bash('npm test')
Bash('npm run lint')
Bash('npm run typecheck')
Bash('npm run test:e2e')

3. If any command produces an error, analyze the problem, generate and apply a fix, and then run this step again. Never skip or delete a failing test to make verification pass.

Once this step completes successfully, never stop; immediately proceed to Step 8.

Step 8: Retrospective and Document Updates

1. Run Skill('steering') in retrospective mode and record handover notes in tasklist.md.

• Implementation completion date
• Differences between plan and actual
• Lessons learned
• Improvement suggestions for next time

2. Reconcile all six persistent documents in docs/ with the feature just implemented. For each document, read its current content, then use the Edit tool to update it so it reflects the new feature. An update may be skipped only when the document genuinely requires no change for this feature — in that case, leave the document untouched and note the skip reason in the retrospective.

   • ✅ docs/product-requirements.md — add/update user stories, acceptance criteria, non-functional requirements, and success metrics for the feature
   • ✅ docs/functional-design.md — add/update functional modules, screens, data flows, and state changes introduced by the feature
   • ✅ docs/architecture.md — add/update components, layers, data models, APIs, and non-functional decisions affected by the feature
   • ✅ docs/repository-structure.md — add/update any new directories, files, or modules created for the feature
   • ✅ docs/development-guidelines.md — add/update any new conventions, patterns, or standards established during the feature
   • ✅ docs/glossary.md — add/update any new domain terms introduced by the feature

3. Update the milestone documents (if docs/milestones/ exists):

   • In the feature's phase file, use the Edit tool to check the feature off ([ ] → [x]).
   • If this was the last unchecked feature of the milestone, set the milestone's status to Completed (in both the phase file and docs/milestones/roadmap.md), fill in its "Completion Notes", and update the roadmap's current-milestone pointer to the next milestone. If it was also the phase's last milestone, mark the phase Completed and point the roadmap at the next phase file.
   • If the feature was not part of any milestone, add it to the current milestone's section in the current phase file as a completed ([x]) feature so the plan reflects reality.

4. Consistency check: re-read each updated document and confirm it is consistent with the other documents and with the implemented code. Fix any inconsistencies found.

5. Once this step completes successfully, never stop; immediately proceed to the Completion Criteria.

Completion Criteria

This workflow completes automatically once all of the following conditions are met.

• Step 5: All tasks in tasklist.md are complete ([x] or skipped for a valid reason).
• Step 6: The implementation-validator subagent's validation passes.
• Step 7: The test, lint, typecheck, and test:e2e (Playwright) commands all succeed without errors, and the feature has E2E tests covering its acceptance criteria.
• Step 8: Handover notes are recorded in tasklist.md, all six persistent documents in docs/ have been reconciled with the feature (updates applied, or a skip reason noted for each), and the feature is checked off in its phase file (if docs/milestones/ exists).

Until these completion criteria are met, continue to think autonomously, solve problems, and carry on the work.