| name | Feature |
| description | Write the feature design doc — the WHY + SHAPE for a single feature. No formal requirements yet (those come in /genesis-specify). |
| argument-hint | <feature-name> [--update|--fresh] |
Feature — The WHY + SHAPE
Write the feature design doc: why this feature exists, what shape it takes, how it fits the project. It contains no formal requirements, acceptance criteria, or user stories — those come in /genesis-specify. This is the first per-feature pipeline command after that feature's brainstorm.
Gate: the feature's brainstorm phase must be accepted in approvals/master.json (else "Run /genesis-brainstorm and accept it first"). Also requires the project overview to exist.
Inputs
.genesis/project-state.md (mode)
- The constitution
.genesis/design/overview.md (required), plus architecture.md, data-model.md, and other design docs
.genesis/features/<feature>/brainstorm-log.md (required)
.genesis/features/<feature>/approvals/master.json (verify brainstorm accepted)
Process
- Resolve the feature name; verify brainstorm accepted.
- Handle an existing/partial doc (revise vs continue vs fresh).
- Create the feature branch (named for the feature) if not already on one, and create
.genesis/features/<feature>/.
- Write
design.md from feature-design-template.md. Sections: Overview · Business Rules · User Experience · Edge Cases · Error Handling · Data Requirements · Security Considerations · Performance Considerations · System Diagram · Technology Choices · Design Decisions (institutional memory) · Scope · Future Considerations — plus mode-specific sections.
- Cross-reference project docs for contradictions and terminology; flag architectural discoveries that may require updating the project architecture doc.
- Self-validation pass (up to 3 iterations): flag vague business rules, missing mode-specific sections, scope creep beyond the brainstorm, contradictions with architecture, empty/placeholder sections; auto-correct and report.
- Constitution-compliance check; present for review; commit on the feature branch.
Mode differences
- Greenfield: technical architecture / component breakdown.
- Brownfield: add Existing System Analysis and a Scope Boundary Map (what changes vs what stays); use git blame for ownership.
- Lowfield: process design — Pipeline Table Design, Artifact Schema Design, Domain Vocabulary.
Output
.genesis/features/<feature>/design.md — the WHY + SHAPE document.
Next step
Run /genesis-specify.
Natural language triggers
- "write the feature design"
- "shape this feature"
- "feature doc for X"