feather-spec

name

feather-spec

description

The Feather Spec framework reference. Use this skill when authoring spec.md (15-section feature spec), design.md, or tasks.md for any feature. Also the canonical reference for vocabulary, stable IDs, EARS patterns, and change protocol. Invoked directly by feather-brainstorm (to produce spec artifacts from project-level docs/brainstorm.md) and referenced by feather-execute-task (for task structure and test layering). Part of the feather-flow pipeline.

Feather Spec

The requirements and delivery framework for Feather Flow. Covers everything from file structure to task ordering to test layering.

---

1. Core Vocabulary

Term	Definition
Feature	A coherent feature area — one domain concept with full lifecycle. One PR.
Screen	A surface the user interacts with — listed inline inside spec.md Section 5.
Component	An embeddable UI fragment owned by exactly one feature.
Action	What a user can do on a screen, listed under that screen's Actions in spec.md.
Task	One developer work unit inside a feature's tasks.md.
ADR	System-wide architecture decision that cuts across features.

Dropped terms: Feature, Sub-feature, Epic, Story, Slice. Cross-capability work gets its own capability folder — not a slice manifest.

---

2. File Structure

docs/
  ├── brainstorm.md                    ← project-level: workflow, decomposition,
  │                                      motivation, app shell (written by
  │                                      feather-brainstorm)
  ├── sample-data.json                 ← realistic sample data for the prototype
  │                                      (written by feather-brainstorm)
  ├── mockup.html                      ← interactive project-wide prototype
  │                                      (written by feather-brainstorm)
  ├── ROADMAP.md                       ← inventory + sequencing of all features
  │                                      (written by feather-brainstorm scope detection;
  │                                       status updated by feather-execute-task)
  ├── STATE.md                         ← active feature + current task + step
  │                                      (updated every gate cycle by
  │                                       feather-execute-task; never edited by humans)
  ├── decisions/                       ← system-wide ADRs (cross-feature)
  │     ├── 0001-convex-over-supabase.md
  │     └── 0002-tanstack-router.md
  └── features/
        └── <feature-name>/
              ├── spec.md           ← product spec — WHAT + WHY
              ├── design.md         ← architecture/tech — optional, only if needed
              ├── decisions/        ← per-feature ADRs
              │     └── 0001-<slug>.md
              ├── tasks.md          ← developer task list
              └── plans/            ← per-task plan files (written by feather-execute-task)
                    └── T-01-build-upload-screen.md

Components: not present by default. Describe components inline within the spec that uses them. Add components/ only when components become a recurring concern shared across multiple screens.

Naming patterns:

• Top-level continuously-updated state (ROADMAP, STATE) — UPPERCASE per open-source convention
• Top-level written-once docs (brainstorm) — lowercase
• Per-feature primary docs (spec, design, tasks) — lowercase; "front-door" docs that get read top-to-bottom
• Containers (decisions/, plans/) — lowercase; folders of detail
• Mockup — docs/mockup.html is project-level (one comprehensive prototype covering the app shell + all screens), generated by feather-brainstorm during the brainstorm phase. There are no per-feature mockup HTML sidecars and no per-screen .md files — screens fold inline into spec.md Section 5
• Plan files — T-NN-<slug>.md matching the task ID in tasks.md
• ADR files — NNNN-<slug>.md (4-digit, ADR convention). Do NOT prefix the filename with ADR — the parent folder (decisions/ or docs/decisions/) already implies ADR. The display label in cross-link text is [ADR-NNNN] (with ADR- prefix and dash) — that's a human-reading convention; the filename stays just NNNN-<slug>.md. Filename and label serve different audiences

One PR per capability. Specs evolve in place. Git is the audit trail. Removed actions are deleted, not deprecated. Renamed actions keep their stable ID.

---

3. ADRs vs design.md

Scope	Lives in	Examples
Affects the whole system	docs/decisions/ ADR	Chose Convex, defer Projects layer
Affects one capability only (architecture/tech)	capability/design.md	Chose SheetJS, store rows as records
Capability decision promoted to system-wide	ADR + pointer in design.md	Row format → ADR-0007

When a capability decision graduates to system-wide: create the ADR, replace the design.md decision with a one-line pointer:

### D3 — Row storage format
See ADR-0007. Applied here as: one document per row, cellData keyed by column name.

---

4. Stable IDs

IDs are optional and emergent. The new spec.md template does not mandate stable IDs everywhere. IDs are added only when something gets cited from outside (a test, a workflow step, a cross-feature reference) — not pre-allocated for every action or field. When IDs are used, they survive renames.

The screen-spec-specific prefixes (A1/RQ1/E1/S1) are gone — those belonged to the old per-screen .md format which no longer exists. The remaining inline IDs apply at the feature spec level when warranted:

Prefix	Scope	Example
C	Calculation	C1, C2
F	Cross-feature flow / workflow	F1, F2
I	Integration	I1, I2
D	Decision (design.md)	D1, D2
R	Risk (design.md)	R1, R2

Cross-feature acknowledgments:

Consumes: task-management#I3

---

5. The Spec Artifacts

5.0 The lens-per-artifact model (foundational)

Each spec artifact serves one consistent lens — one audience, one perspective. This is the core organising principle of the framework. When you don't know where a piece of content belongs, ask which lens it serves.

Artifact	Lens	Audience	Answers
docs/mockup.html	UX (visual, project-wide)	Designers, stakeholders, product owners	What the entire app looks and feels like; navigable across features
spec.md	Product	Any reader (PM, designer, dev, client)	WHAT it does, WHY it exists, including UX (screens fold inline)
design.md	Architecture / tech	Developers, architects	HOW it's built — tech stack, patterns, implementation strategy
tasks.md	Build (developer)	Developer doing the work	HOW to build it — ordered steps
decisions/NNNN-<slug>.md	Architecture (per-feature)	Devs, architects	Feature-scoped ADRs
docs/decisions/NNNN-<slug>.md	Architecture (system-wide)	Architects, leads	System-level HOW that crosses features
(components/<component>.md)	UX (embeddable)	Same as screens	Optional — only when components are shared across multiple screens

Decision rule: when content surfaces (a decision, a risk, an open question, a constraint), identify which lens it serves. If it serves multiple, the primary motivation wins — i.e. the audience who most needs to know about it. Cross-link if the secondary motivation is substantial.

Optional artifacts: design.md is created only when there are architecture/tech decisions worth recording. The project-level docs/mockup.html is generated by feather-brainstorm; spec phase does not produce mockup HTML.

Always-present artifacts: spec.md and tasks.md.

Why one lens per artifact: the alternative — splitting content by other axes (e.g., "current state vs history") — mixes lenses awkwardly. spec.md ends up with "what the system does" but "why it exists" gets stranded with "we chose Convex over Supabase" in design.md, even though those two answer different questions for different audiences. The lens-per-artifact model eliminates that confusion. A reader of any artifact knows what perspective they're getting before they start.

5.1 Screens (folded inline into spec.md)

Screens are not separate artifacts anymore. They live inline inside spec.md Section 5 (Screens) — each screen described by an ASCII zone diagram plus bullets for Sort / Filter / Search / Display where they apply, then Actions. See §10 (Spec Doc Format) for the exact format inside the template.

A screen deserves its own entry inside Section 5 when it has:

• A distinct routable URL, OR
• A distinct user intent ("done" means something different here), OR
• A distinct entity being acted on

Modals, panels, and inline CRUD ("+ New" buttons, edit modals) are Actions on the parent screen, not separate screens.

Mockups live at the project level (docs/mockup.html), generated during the brainstorm phase by feather-brainstorm. The spec phase does not produce mockups; it references the mockup's existing screen sections by name. If a feature needs a layout exploration the project mockup doesn't yet address, update the project mockup rather than creating a per-feature variant.

There are no per-screen .md files anymore. The old screens/<screen>.md format has been replaced entirely by inline screen entries inside spec.md.

5.2 Spec (the bounded comprehensive doc — spec.md)

Stance: bounded. Where brainstorm.md broadens the design space at the project level (workflow capture, decomposition into features, pains, alternatives considered), spec.md bounds one feature — pins one answer to every question and puts everything in a single place. This is THE document downstream agents are seeded with; everything they need to build the feature is either here or one link away.

Target: 1–2 pages. Comprehensive, not exhaustive — section headings cover everything important, and detail spills into adjacent files (design.md, decisions/) only when a topic warrants more than the spec page can hold.

The full product perspective, including UX (screens fold inline). No tech / architecture content (that's design.md).

The 15 sections, in order (per §10 below):

1. What is this?
2. Who uses it
3. User journey
4. Data
5. Screens (inline ASCII + Sort/Filter/Search/Display + Actions)
6. Permissions
7. Validations
8. Business rules
9. Workflows
10. Calculations
11. Reports
12. Out of scope
13. Open questions
14. Technical notes (one-paragraph deferral to design.md)
15. Glossary

Read on every implementation task. Must stay lean. The spec does not include a top-of-file backlink — start directly with # Feature: <Name> and ## What is this?. Cross-references to other docs appear inside the relevant section content (e.g., the Technical notes section's body mentions design.md).

5.3 Design (architecture & tech — HOW)

The architecture and technology lens. How this capability is built — the technical decisions, the implementation patterns, the tech-level risks. Not the product perspective (that lives in spec.md).

• Architectural decisions (chose Convex over Supabase, etc.) with alternatives considered
• Implementation strategies for non-obvious calculations / flows / integrations declared in spec.md
• Tech-level risks (e.g., OCC contention, scaling limits)
• Tech-level open questions

Optional. Create only when there are architecture/tech decisions worth recording. A pure-UI capability on existing infra may have no design.md. spec.md remains always-present; design.md does not.

Read once during exploration when it exists.

5.4 Component (composition unit)

• Owned by exactly one capability
• Embeddable in screens of other capabilities
• Host screen references: Embeds: <capability>#<component>

5.5 Minimal Mode

A capability with one screen, no integrations, no non-obvious decisions may collapse to a single spec.md with tasks folded in at the bottom. (design.md is already optional under the standard framework — only created when there are architecture/tech decisions worth recording.)

Test layering may also collapse in minimal mode: the three top-level test groups (T(last-2) integration, T(last-1) unit, T(last) E2E) may be folded into a single test task with sub-checkboxes for each layer. Promote back to three groups when the capability leaves minimal mode.

Promote out of minimal mode the moment any of these become true:

• Second screen added
• Non-obvious decision arises
• Any integration introduced
• Open question worth recording

Promotion is a split operation, not a rewrite. The single file's sections map directly to the expanded structure.

---

6. Capability Types

Internal routing only. These are internal categories that help feather-spec route content; they do not appear in user-facing spec content. The new spec.md template treats every feature uniformly — the same 15 sections apply regardless of whether the feature owns data, aggregates from others, or coordinates across features.

Type	Purpose	Distinguishing feature
Standard	Owns an entity and its lifecycle	Task Management, Projects
Aggregation	Aggregates across other capabilities	Search, Dashboard, Settings
Cross-capability	Coordinates a feature spanning multiple capabilities	Task Due Date

Single-capability rule: Every screen belongs to exactly one capability.

Decision tree when a screen appears to need two parents:

1. Is it an aggregation screen?           → name the aggregation capability
2. Who is the primary owner?              → screen lives there
3. Does it need cross-cap behavior?       → embed via component
4. Would embedding produce incoherent UI? → only then split into two screens

---

7. Screen Spec Format

Per-screen .md files no longer exist. Screens fold inline into spec.md Section 5 (Screens) — see the format inside the template in §10.

Each screen entry inside spec.md Section 5 includes:

• An ASCII zone diagram (derived from the project-level docs/mockup.html for this screen, or written fresh from the layout-confirmation conversation if the screen isn't yet in the mockup)
• Bullets for Sort / Filter / Search / Display where they apply (skip the bullet entirely if the screen has no sort, no filter, etc.)
• Actions (always present) — what the user can do on the screen, including inline CRUD ("+ New", edit modal, delete button) which lives under the parent screen's Actions, not as a separate screen

The EARS pattern reference (§8 below) remains useful for writing rules in the Business rules and Workflows sections of spec.md. EARS is a way to write conditional rules precisely; it is not coupled to any particular file format.

---

8. EARS Patterns

Pattern	Keyword	Use for
Event-driven	WHEN	User actions, system events
Unwanted	IF/THEN	Errors, failures, rejections
State-driven	WHILE	Sustained states
Ubiquitous	THE SYSTEM SHALL (no trigger)	Always-true rules
Optional	WHERE	Feature flags

State-driven baseline: every screen must address loading, empty, and error as the minimum three states — plus feature-specific states on top.

---

9. Scenario Rules

H4 labeled scenario — behavioral variants

Use when: different code path, different outcome shape, multi-line input, or a design decision worth naming.

#### A3.E1 — No confirmation
WHEN user clicks delete,
THE SYSTEM SHALL remove the task immediately without confirmation.

Example table — data-driven variants

Use when: same code path, different input values. Add "Why?" column when intent is not obvious from input/output alone.

| Input | Saved as | Why? |
|---|---|---|
| `Buyer Mapping v1.xlsx` | `Buyer Mapping`  | version suffix stripped |
| `~$data.xlsx`           | rejected         | Office lock file        |

Mixed accept/reject: one table, rejected as sentinel. If any cell exceeds one line → promote that row to an H4 scenario.

No scenario

Use when: the EARS statement alone is fully precise.

---

10. Spec Doc Format (spec.md)

Target: 1–2 pages. This is THE document downstream agents are seeded with. The 15 sections below appear in this order. Each section has an italic guidance line directly under its heading — those lines stay in the rendered spec; they orient both the writer and any future reader to what belongs there.

Sections marked with † are mandatory. The rest are cue-driven: keep them as section headings even when content is sparse, with (none — <reason>) content. Truly omittable: only when nothing applies (Workflows is the most common example; Glossary another).

# Feature: <Name>

## What is this?
*The feature's primary value in 2–3 sentences. Plain English; no jargon. State what it does and the primary outcome it delivers. Avoid describing how it's built.*

[content]

## Who uses it
*Roles in this feature. One bullet per role with a one-line description of their responsibility within this feature. Do not list non-users.*

[content]

## User journey
*The typical flow through this feature. 5–8 numbered steps per role when actors take substantively different paths through the system; a single flat list when one actor drives the whole flow. Soft cap: 3 role-distinct journeys. Steps should reference concrete UI elements and observable outcomes — avoid abstract verbs.*

[content]

## Data
*Things the system tracks. One block per entity with attributes in business-language types (text, number, yes/no, date/time, reference to <entity>). Field-level validations (required, max length, unique, valid format, default value) appear inline next to the field. Code generators read this section directly — keep it concrete enough to drive table creation.*

[content]

## Screens
*The surfaces the user interacts with, in flow order: entry-point lists → detail/drill-in → alternative entry points. Each entry has an ASCII zone diagram, then bullets for Sort / Filter / Search / Display where they apply, then Actions (always include). CRUD operations that happen inline (modals, "+ New" buttons) live under the parent screen's Actions, not as separate screens.*

[content]

## Permissions
*Who can do what, by role. Bullets for global rules ("anyone signed in can read all projects") plus role-specific rules where they exist. Skip the section content with "(everyone signed in is a full member; no role tiers)" if that's the truthful answer — the cue is preserved, the noise is gone.*

[content]

## Validations
*Cross-field / cross-entity validation rules only. Field-level rules (required, max length, format, default) belong inline with Data above. Often "(none)" for simple CRUD features — that itself is a meaningful statement.*

[content]

## Business rules
*Rules governing special states, conditional behavior, or things outside basic CRUD ("a task is stale when..."). Each rule stated plainly. Add a clarifying example only when the rule isn't obvious from its statement.*

[content]

## Workflows
*Multi-step coordinated processes (approval flows, multi-stage transitions, anything where one user action triggers a sequence of system actions). Per workflow: name, the trigger, the steps, branches for non-obvious cases. "(none)" when all behavior is single-step.*

[content]

## Calculations
*Derived values: formulas the system computes from stored data. Per calculation: formula in plain language plus edge cases (cap, fallback, rounding). "(none)" when no computed values exist.*

[content]

## Reports
*Insights the user wants from the data. Per report: name, source data, output shape (list, summary, totals). Implementation (in-app screen, Excel export, PDF) deferred to `design.md`.*

[content]

## Out of scope
*Things deliberately excluded from this feature, with one-line reasoning per item. Surfacing what was rejected helps future readers understand the chosen direction. Boundary cases that border on in-scope are especially worth listing here.*

[content]

## Open questions
*Unresolved at this level only. When a question is answered, the answer goes into the relevant section and the question is removed. Project-level open questions belong in `docs/brainstorm.md`, not here.*

[content]

## Technical notes
*One-paragraph deferral to `design.md`. Notes anything architectural the spec reader needs to know up-front: auth method, key external dependency, hosting model. Implementation detail belongs in `design.md`, not here.*

[content]

## Glossary
*Definitions of product-specific terms used in this spec. Skip the section entirely if no jargon was introduced. Include any term used across two or more sections that isn't plain English (e.g., "stale", "blocker", "swimlane"). Industry-standard terms (CRUD, API, JSON) don't need definitions.*

[content]

Mandatory sections (always include): What is this? · Who uses it · User journey · Data · Screens · Out of scope · Technical notes Cue-driven (keep heading even when sparse): Permissions · Validations · Business rules · Calculations · Reports Truly optional (omit if nothing applies): Workflows · Open questions · Glossary

The template does NOT have a top-of-file backlink to design.md or brainstorm.md. Start directly with # Feature: <Name> and immediately go to ## What is this?. Cross-references to other docs appear inside the relevant section content (e.g., the Technical notes section's body mentions design.md).

---

11. Design Doc Format

# Design: <Feature Name>

> Product spec in `spec.md` — read first to understand WHAT this
> capability does and WHY it exists. This file covers HOW it's built
> from an architecture / tech perspective.

## Architectural decisions

### D1 — <Decision title>
**Chose:** <tech / framework / pattern, and why>
**Rejected:** <alternatives and why not>

## Implementation strategies

<For non-obvious calculations, flows, or integrations declared in
spec.md — describe the implementation approach. Skip the section
if implementation is obvious from the spec.>

### <Implementation topic>
<approach + reasoning>

## Tech-level risks

### R1 — <Risk title>
**Threat:** <what could go wrong technically>
**Mitigation:** <what we are doing about it>
**Accepted:** <what we are living with>

## Tech-level open questions

<Unresolved architecture / implementation questions. Product-level
open questions live in spec.md.>
(delete section when empty)

This file is optional. If a capability has no architecture/tech decisions worth recording (e.g., pure UI work on existing infra), omit design.md entirely. spec.md remains always-present.

---

12. Component Spec Format

# Component: <Name>

**Owned by:** <capability>
**Embeddable in:** any screen via `<capability>#<component>`

## Props
| Prop | Type | Required | Notes |
|---|---|---|---|

## Emits
| Event | Payload | When |
|---|---|---|
(omit if emits nothing)

## Actions

### A1 — <Action>
WHEN ..., THE SYSTEM SHALL ...

## States

### S1 — Loading
### S2 — Empty
### S3 — Error

## Spec Checklist
- [ ] Event-driven (WHEN)
- [ ] Unwanted (IF/THEN)
- [ ] State-driven (WHILE) — loading · empty · error
- [ ] Ubiquitous
- [ ] Optional (WHERE)
- [ ] Accessibility
- [ ] Authorization
- [ ] Internationalization
- [ ] Emits documented
- [ ] Data model

Host screen reference:

Embeds: comments#thread (entityId: task.id)

---

13. Tasks Format

Core principle

Specs are user-perspective. Tasks are developer-perspective.

A spec says: "The analyst can upload an xlsx." A task says: "Prove the import engine by ingesting a hardcoded dataset."

If a task heading is stated from the developer's perspective ("Set up routing"), it is a sub-task checkbox, not a task heading.

Task ordering — prove the engine first

T1 — Prove the engine
     Hardcoded UI triggers the full pipeline end-to-end.
     After T1, the backend is known-good and untouched by later tasks.

T2+ — Build real UX
     Replace hardcoded trigger with real interactions.
     Backend is proven; these tasks are pure frontend enrichment.

T(n) — Screen tasks
     Thin vertical slices. Each delivers one analyst capability
     end-to-end: the analyst does something and sees a result.

T(last-2) — Integration tests
T(last-1) — Unit tests (coverage gaps only)
T(last)   — E2E tests (happy path, ~1 per flow)

Task file format

# Tasks: <Capability Name>

## T1 — Prove the engine — <one-line verification description>
- [ ] T1.1 Schema: <entity> table (<fields>)
- [ ] T1.2 Mutations: <list>
- [ ] T1.3 Queries: <list>
- [ ] T1.4 Hardcoded UI: trigger full pipeline, confirm data lands in DB
- [ ] T1.5 Verify: <specific observable check>

## T2 — <Screen name> — <one-line verification description>
- [ ] T2.1 UI: <what screen shows>
- [ ] T2.2 Wire <mutation/query>
- [ ] T2.3 Verify: <specific observable check>

## T3 — Integration tests
- [ ] T3.1 Install: vitest, @edge-runtime/vm, convex-test,
           @testing-library/react, @testing-library/user-event, jsdom
- [ ] T3.2 Fixture: <xlsx or seed data>
- [ ] T3.3 Test matrix: <screen> — write BEFORE tests.
       Always list states. Add approach × what-to-verify columns when
       behavior varies by approach (e.g. keyboard vs. mouse, optimistic
       vs. confirmed). Single-axis matrix is fine for simple screens.
- [ ] T3.4 Integration tests per matrix
- [ ] T3.5 Verify: all states covered, no mocked component tests

## T4 — Unit tests (coverage gaps only)
- [ ] T4.1 Unit tests for pure functions (<list>)
- [ ] T4.2 Run vitest --coverage; identify uncovered lines
- [ ] T4.3 Unit tests for uncovered lines (loading states, error states,
           edge cases integration can't produce)
- [ ] T4.4 Document any v8 ignore exceptions with justification
- [ ] T4.5 Verify: 100% coverage (or justified exceptions)

## T5 — E2E tests
- [ ] T5.1 Install @playwright/test; add config and npm run test:e2e
- [ ] T5.2 One smoke test per critical user journey
- [ ] T5.3 Verify: passes against running dev server

Task sizing rules

• Simple screen → one task covers UI + wiring
• Complex screen → T(n): backend, T(n+1): frontend
• Data model always comes first as its own task
• Navigation / routing scaffolding → sub-checkbox inside first task that needs it
• Empty states and loading states → minor affordances within a screen task, not own tasks
• Each task's last checkbox is always a verification step

Three-layer test rules

• Integration tests — workhorse. Real in-memory backend + real React. One test per component state (MECE). Write test matrix BEFORE writing tests. These replace both backend-only tests and mocked component tests.
• Unit tests — fill gaps only. Run coverage first, then fill. Not the default. Only for pure functions and states integration can't produce.
• E2E tests — ~1 per critical flow. Real browser, real backend. Deliberate overlap with integration tests for critical journeys is acceptable.

Cross-capability tasks.md

When a capability has no screens, tasks.md spans affected systems in producer-first order:

# Tasks: Task Due Date

## T1 — Task Management side
- [ ] T1.1 Add dueDate field to Task schema
- [ ] T1.2 Update mutations to accept dueDate
- [ ] T1.3 Surface dueDate on Task Form (task-management#A2)
- [ ] T1.4 Verify: task created with due date → stored correctly

## T2 — Calendar side
- [ ] T2.1 Query tasks with dueDate for current month
- [ ] T2.2 Render task chips on Calendar day cells
- [ ] T2.3 Verify: task with due date appears on correct calendar day

## T3 — Integration tests
## T4 — Unit tests (coverage gaps only)
## T5 — E2E tests
(Standard test layering applies — sub-checkboxes omitted here for brevity.
See § 13 task file format.)

---

14. Anti-Patterns

❌ Don't	✅ Do
Per-screen .md files	Screens fold inline into spec.md Section 5
Delete button as its own screen	Delete is an Action under the parent screen's Actions
"Persist data" as a rule	Obvious — omit
DB schema or API paths in spec.md	Tech detail goes in design.md; build steps in tasks.md
SHALL for style ("button SHALL be blue")	Visual style belongs in the ASCII zone diagram or in mockup HTML
Tech / architecture decisions in spec.md	Those live in design.md
Product content (what is this, who uses it, screens) in design.md	Those live in spec.md
Always-create design.md even when no tech decisions exist	design.md is optional — create only when there are architecture decisions worth recording
Splitting rationale between spec.md and design.md by hand	Use the product-vs-tech lens — every rationale fits one or the other (primary motivation wins for mixed cases)
Operating rules in design.md	Those live in spec.md (Business rules / Workflows)
System-wide decisions in design.md	Those live in docs/decisions/ as ADRs
Multi-parent screens	Aggregation capability or embedded component
Cross-capability work without own capability folder	Create a capability folder
Task stated from developer perspective	Rewrite as user capability
Building UI before backend is proven	T1 always proves the engine first
Writing tests before the test matrix	Matrix first, tests second
Mocked component tests	Use integration tests instead
Inventing a generic layout when the project mockup already shows the screen	Derive the ASCII zone diagram from docs/mockup.html — that's the source of truth for layout
Generate per-feature mockup HTML files (features/<f>/screens/<screen>-NN.html)	Mockup is project-level (docs/mockup.html); per-feature mockups fragment what should be one coherent app design
Pre-allocating stable IDs for every action and field	IDs are emergent — add them only when something gets cited from outside (test, workflow step, cross-feature reference)
Leaving Open questions when empty	Omit the section (it's truly optional)

---

15. Change Protocol

Renaming: update the name. If a stable ID was previously assigned, keep it. Removing: delete from spec.md, don't deprecate. Note in design.md if non-obvious. Modifying: edit spec.md in place; git diff is the record. Adding: add to the relevant section in spec.md. Allocate a stable ID only if the new element gets cited from outside. Promoting feature decision to ADR: create ADR in docs/decisions/, replace the decision body in design.md with a one-line pointer.

---

16. Quick Decision Reference

Question	Answer
Screen or action?	Own URL → screen entry under spec.md Section 5. Otherwise action inside parent.
Which feature owns this screen?	What entity is the screen about? That feature.
Cross-feature work?	New feature folder. Producer ships first.
Constraint or obvious behavior?	Would a competent developer choose differently without it? No → omit.
Screen-level or cross-cutting?	Applies to more than one screen → lift to a feature-wide section in spec.md (Permissions / Validations / Business rules).
spec.md or design.md?	Product perspective (WHAT + WHY + UX) → spec.md. Architecture / tech (HOW) → design.md.
design.md or docs/decisions/?	Feature-scoped architecture → design.md. System-wide architecture → ADR.
Renaming a screen?	Rename the entry inside spec.md Section 5. Update the corresponding section in docs/mockup.html so the project mockup stays in sync.
Removing a screen?	Delete the entry from spec.md Section 5. Remove the corresponding section from docs/mockup.html. Note in design.md if non-obvious.
Need a layout exploration the mockup doesn't address?	Update docs/mockup.html (the project-level prototype). Don't create per-feature mockup variants.
Removing an action?	Delete it from the parent screen's Actions inside spec.md. Note in design.md if non-obvious.

---

17. Commit Protocol

After spec authoring is complete (all relevant artifacts written: spec.md, design.md if applicable, decisions/ ADRs, tasks.md), prompt the user to commit BEFORE handing off to feather-execute-task.

Why this gate exists

The spec phase produces real source-of-truth artifacts that the build phase will reference continuously. These belong in git as a discrete commit before code generation begins — otherwise:

• A later code revert can entangle uncommitted spec changes with the reverted code
• Git history loses "spec complete" as a discrete moment
• The asymmetry with brainstorm's Phase 4 commit prompt is confusing to teach

The prompt

After all spec artifacts are written, list what was created/changed and propose a commit:

"Spec phase produced these files:

• docs/features/<name>/spec.md (new)
• docs/features/<name>/design.md (new, if created)
• docs/features/<name>/decisions/0001-<slug>.md (new ADR, if any)
• docs/features/<name>/tasks.md (new)
• docs/STATE.md (updated)

Proposed commit message:

spec:

15-section spec for : data, screens (inline), behaviors, workflows, tasks. Project-level discovery context in docs/brainstorm.md. Architecture decisions in design.md. N tasks, prove-engine-first ordering.

Three ways to reply:

• 'commit' — I'll stage and commit these files with the message above
• 'edit message: ' — change the commit message, then commit
• 'skip commit' — leave the work uncommitted (you'll commit manually later)"

If the user picks commit, run git add on the listed files and git commit with the proposed message. Then proceed to the build handoff. If edit message, use the new message. If skip commit, proceed without committing — the user takes responsibility for the eventual commit.

Build handoff

After the commit prompt resolves, slim handoff:

"spec.md and supporting artifacts are written and committed. Ready to build? Say 'start building' to invoke feather-execute-task on T1, or note any changes first."

(If commit was skipped: "...are written (uncommitted). Ready to build?...")

Do not auto-proceed. The user confirms.

When confirmed, hand off to feather-execute-task. feather-execute-task reads docs/STATE.md, the active feature's tasks.md, and per-task plan files in plans/ to drive the build phase.