create-harness-vibe-coding 0.8.7 → 0.8.8

package/templates/common/Harness/context-loading.md

@@ -1,142 +1,142 @@
-# Context Loading Protocol
-
-Use when context is growing, subagents are needed, or an agent is unsure which harness doc applies.
-
-## Routing Authority
-
-`Harness/README.md` is the primary router. This file is a secondary context-splitting protocol for subagents and long tasks.
-
-If this file and `Harness/README.md` disagree, follow `Harness/README.md`, record the assumption in `Harness/tasks/<task-id>/PROGRESS.md`, and update this file later.
-
-project files are the only durable communication channel; chat/subagent transcript state is non-authoritative. Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
-
-## Main Context
-
-Always keep:
-
-- `CLAUDE.md`
-- `Harness/MEMORY.md`
-- `Harness/README.md`
-- `Harness/PROGRESS.md` when active
-- `Harness/tasks/<task-id>/PROGRESS.md` when active
-- `Harness/tasks/<task-id>/PLAN.md` when active
-- current feature doc when active
-
-Load other docs only by trigger.
-
-## Trigger Matrix
-
-| Trigger | Load |
-| --- | --- |
+# Context Loading Protocol
+
+Use when context is growing, subagents are needed, or an agent is unsure which harness doc applies.
+
+## Routing Authority
+
+`Harness/README.md` is the primary router. This file is a secondary context-splitting protocol for subagents and long tasks.
+
+If this file and `Harness/README.md` disagree, follow `Harness/README.md`, record the assumption in `Harness/tasks/<task-id>/PROGRESS.md`, and update this file later.
+
+project files are the only durable communication channel; chat/subagent transcript state is non-authoritative. Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
+
+## Main Context
+
+Always keep:
+
+- `CLAUDE.md`
+- `Harness/MEMORY.md`
+- `Harness/README.md`
+- `Harness/PROGRESS.md` when active
+- `Harness/tasks/<task-id>/PROGRESS.md` when active
+- `Harness/tasks/<task-id>/PLAN.md` when active
+- current feature doc when active
+
+Load other docs only by trigger.
+
+## Trigger Matrix
+
+| Trigger | Load |
+| --- | --- |
 | idea, scope, MVP | `Harness/lifecycle.md`, `Harness/research/PRD.md`, `Harness/ACCEPTANCE_PROTOCOL.md` |
 | acceptance, AC, criteria, contract, validation matrix | `Harness/ACCEPTANCE_PROTOCOL.md`, `Harness/AGENT_ISOLATION.md`, `Harness/HARNESS_BRIDGE.md` as needed |
 | research, competitors, stack choice | `Harness/research/README.md`, `Harness/research/research-results.md` |
-| task split, owner, write set | `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, `Harness/agent-workflow.md` |
-| parallel agents, dispatch, worktree decision | `Harness/subagents.md`, `Harness/dispatch.md`, `Harness/tasks/<task-id>/PLAN.md` |
-| `/wf` mode, long task, multi-file, multi-agent | `Harness/WF.md`, `Harness/subagents.md`, `Harness/dispatch.md`, `Harness/tasks/<task-id>/PLAN.md` |
-| `/wf max`, 5+ disjoint files, maximum parallelism | `Harness/WF-MAX.md`, `Harness/subagents.md`, `Harness/dispatch.md`, `Harness/tasks/<task-id>/PLAN.md` |
+| task split, owner, write set | `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, `Harness/agent-workflow.md` |
+| parallel agents, dispatch, worktree decision | `Harness/subagents.md`, `Harness/dispatch.md`, `Harness/tasks/<task-id>/PLAN.md` |
+| `/wf` mode, long task, multi-file, multi-agent | `Harness/WF.md`, `Harness/subagents.md`, `Harness/dispatch.md`, `Harness/tasks/<task-id>/PLAN.md` |
+| `/wf max`, 5+ disjoint files, maximum parallelism | `Harness/WF-MAX.md`, `Harness/subagents.md`, `Harness/dispatch.md`, `Harness/tasks/<task-id>/PLAN.md` |
 | memory, scenario memory, repeated tool failure, repeated user correction, reusable lesson | `Harness/MEMORY.md`, `Harness/MEMORY_PROTOCOL.md`, the relevant `Harness/memory/*.md` file |
 | subagent spawn | `Harness/subagents.md`, `Harness/AGENT_ISOLATION.md`, this file plus the role pack below |
-
-## ECC Rules Per Role
-
-Each subagent role loads a specific ECC rule subset. The dispatcher MUST include
-`ecc` in the dispatch packet so the subagent knows which rules to read first.
-
-| Role | Frontend Task | Backend Task | Full-Stack Task |
-|------|--------------|-------------|-----------------|
-| **Explorer** | `web/patterns.md`, `web/design-quality.md` | `common/patterns.md`, stack patterns | All |
-| **Planner** | `common/patterns.md`, `web/patterns.md` | `common/patterns.md`, stack patterns | All |
-| **Architect** | `web/patterns.md`, `web/performance.md` | `common/patterns.md`, `python/fastapi.md` or `golang/patterns.md` | All + API contract |
-| **Implementer (FE)** | `web/design-quality.md`, `web/patterns.md`, `web/performance.md`, `typescript/patterns.md` | N/A | Frontend subset |
-| **Implementer (BE)** | N/A | `common/patterns.md`, `python/fastapi.md` or `golang/patterns.md` | Backend subset |
-| **Test Writer** | `web/testing.md`, `typescript/testing.md` | Stack testing rules | Both |
-| **Reviewer** | `web/design-quality.md`, `web/security.md`, `web/performance.md` | Stack security + testing rules | All |
+
+## ECC Rules Per Role
+
+Each subagent role loads a specific ECC rule subset. The dispatcher MUST include
+`ecc` in the dispatch packet so the subagent knows which rules to read first.
+
+| Role | Frontend Task | Backend Task | Full-Stack Task |
+|------|--------------|-------------|-----------------|
+| **Explorer** | `web/patterns.md`, `web/design-quality.md` | `common/patterns.md`, stack patterns | All |
+| **Planner** | `common/patterns.md`, `web/patterns.md` | `common/patterns.md`, stack patterns | All |
+| **Architect** | `web/patterns.md`, `web/performance.md` | `common/patterns.md`, `python/fastapi.md` or `golang/patterns.md` | All + API contract |
+| **Implementer (FE)** | `web/design-quality.md`, `web/patterns.md`, `web/performance.md`, `typescript/patterns.md` | N/A | Frontend subset |
+| **Implementer (BE)** | N/A | `common/patterns.md`, `python/fastapi.md` or `golang/patterns.md` | Backend subset |
+| **Test Writer** | `web/testing.md`, `typescript/testing.md` | Stack testing rules | Both |
+| **Reviewer** | `web/design-quality.md`, `web/security.md`, `web/performance.md` | Stack security + testing rules | All |
 | **Debugger** | Stack-specific coding-style + patterns | Stack-specific coding-style + patterns | Context-dependent |
-| **Verifier** | `web/testing.md` | Stack testing rules | Both |
-
-## Subagent Packs
-
-Each pack now includes `ecc` — the ECC rule files this role MUST load first.
-
-Explorer Pass:
-- ecc: `common/patterns.md` + stack-specific patterns (see ECC Rules Per Role)
-- inject: question, read boundary, relevant docs
-- forbid: writes
-- return: files found, facts, risks, suggested tests
-
+| **Verifier** | `web/testing.md` | Stack testing rules | Both |
+
+## Subagent Packs
+
+Each pack now includes `ecc` — the ECC rule files this role MUST load first.
+
+Explorer Pass:
+- ecc: `common/patterns.md` + stack-specific patterns (see ECC Rules Per Role)
+- inject: question, read boundary, relevant docs
+- forbid: writes
+- return: files found, facts, risks, suggested tests
+
 Planner:
 - ecc: `common/patterns.md` + `common/development-workflow.md`
 - inject: user goal, lifecycle phase, PRD or PLAN section, acceptance gate status, dispatch constraints
 - forbid: production code
 - return: tasks, dependencies, read/write sets, dispatch table, gates, open questions
-
-Researcher:
-- ecc: none (uses WebSearch/WebFetch, not code rules)
-- inject: question, decision needed, source boundaries, tool options
-- forbid: production code
-- return: sources, adopted/rejected/watch decisions, risks, research-results.md patch
-
-Docs Researcher:
-- ecc: none (uses official docs, not code rules)
-- inject: library/API/config, implementation question, version/date constraints
-- forbid: production code
-- return: official links, constraints, errors, examples, affected docs
-
-Architect:
-- ecc: `common/patterns.md` + stack-specific (web/patterns.md for FE, python/fastapi.md for BE)
-- inject: PRD, current architecture, ports
-- forbid: implementation
-- return: boundary decision, affected docs, risks
-
+
+Researcher:
+- ecc: none (uses WebSearch/WebFetch, not code rules)
+- inject: question, decision needed, source boundaries, tool options
+- forbid: production code
+- return: sources, adopted/rejected/watch decisions, risks, research-results.md patch
+
+Docs Researcher:
+- ecc: none (uses official docs, not code rules)
+- inject: library/API/config, implementation question, version/date constraints
+- forbid: production code
+- return: official links, constraints, errors, examples, affected docs
+
+Architect:
+- ecc: `common/patterns.md` + stack-specific (web/patterns.md for FE, python/fastapi.md for BE)
+- inject: PRD, current architecture, ports
+- forbid: implementation
+- return: boundary decision, affected docs, risks
+
 Test Writer:
 - ecc: `common/testing.md` + stack-specific testing rules
 - inject: acceptance criteria, UI/API contracts, feature doc, test write set
 - forbid: production code
 - return: failing tests, AC ID mapping, and test intent
-
-Implementer (Frontend):
-- ecc: `web/design-quality.md`, `web/patterns.md`, `web/performance.md`, `typescript/patterns.md`
-- inject: task, tests, allowed write set, forbidden scope
-- forbid: unrelated refactor and test loosening
-- return: changed files and implementation notes
-
-Implementer (Backend):
-- ecc: `common/patterns.md`, stack-specific patterns (`python/fastapi.md` or `golang/patterns.md`)
-- inject: task, tests, allowed write set, forbidden scope
-- forbid: unrelated refactor and test loosening
-- return: changed files and implementation notes
-
+
+Implementer (Frontend):
+- ecc: `web/design-quality.md`, `web/patterns.md`, `web/performance.md`, `typescript/patterns.md`
+- inject: task, tests, allowed write set, forbidden scope
+- forbid: unrelated refactor and test loosening
+- return: changed files and implementation notes
+
+Implementer (Backend):
+- ecc: `common/patterns.md`, stack-specific patterns (`python/fastapi.md` or `golang/patterns.md`)
+- inject: task, tests, allowed write set, forbidden scope
+- forbid: unrelated refactor and test loosening
+- return: changed files and implementation notes
+
 Reviewer:
 - ecc: `web/design-quality.md` (FE), `web/security.md` (FE), `common/security.md`, stack security
 - inject: PRD, acceptance criteria, UI/API contracts, diff, test/validation evidence, architecture docs
 - forbid: writes
 - return: findings by severity, AC traceability, missing tests, boundary issues
-
+
 Debugger:
 - ecc: stack-specific coding-style + patterns
 - inject: failed AC ID, failing command, error output, trace/screenshot/network evidence, related files
 - forbid: broad rewrites
 - return: failure layer, root cause, fix, proof
-
+
 Verifier:
 - ecc: stack-specific testing rules
 - inject: verification commands, acceptance criteria, UI/API contracts, running app/API endpoint
 - forbid: code changes
 - return: commands run, AC-by-AC validation matrix, evidence paths, residual risk
-
-Memory Master:
-- inject: trigger reason, current failure/user-correction/closeout context, task PROGRESS.md section
-- forbid: source code, unrelated Harness docs
-- return: memory action summary, files written, cross-project flag
-
-Context Master:
-- inject: trigger reason (threshold % or closeout), current task PROGRESS.md, task phase
-- forbid: source code, memory files, MEMORY.md writes
-- return: context usage %, stale blocks, compressible blocks, durable knowledge candidates, compression suggestion
-
-## Handoff Rule
-
-Only the subagent summary enters main context. If details are needed, load the named files directly instead of replaying the subagent conversation.
-
-Use the handoff format in [dispatch.md](dispatch.md) for every dispatched agent.
+
+Memory Master:
+- inject: trigger reason, current failure/user-correction/closeout context, task PROGRESS.md section
+- forbid: source code, unrelated Harness docs
+- return: memory action summary, files written, cross-project flag
+
+Context Master:
+- inject: trigger reason (threshold % or closeout), current task PROGRESS.md, task phase
+- forbid: source code, memory files, MEMORY.md writes
+- return: context usage %, stale blocks, compressible blocks, durable knowledge candidates, compression suggestion
+
+## Handoff Rule
+
+Only the subagent summary enters main context. If details are needed, load the named files directly instead of replaying the subagent conversation.
+
+Use the handoff format in [dispatch.md](dispatch.md) for every dispatched agent.

package/templates/common/Harness/extension.md

@@ -1,70 +1,70 @@
-# Extension Contract
-
+# Extension Contract
+
 Purpose: keep stack-specific agents, skills, and rules compatible with this harness.
-
-Use during setup whenever adding assets from ECC, SuperClaude, toolboxes, or local project conventions.
-
-## Non-Invasive Extension Rules
-
-Extensions must preserve project and harness ownership boundaries.
-
+
+Use during setup whenever adding assets from ECC, SuperClaude, toolboxes, or local project conventions.
+
+## Non-Invasive Extension Rules
+
+Extensions must preserve project and harness ownership boundaries.
+
 - Preserve existing `.claude/`, `CLAUDE.md`, `AGENTS.md`, `.gitignore`, `Harness/README.md`, `Harness/workflows/*.md`, settings, and local rules unless the user explicitly requests an overwrite.
-- Treat existing project config as project fact. Read it before adding assets, then adapt new assets to the project instead of replacing the project.
+- Treat existing project config as project fact. Read it before adding assets, then adapt new assets to the project instead of replacing the project.
 - Register added agents, skills, workflows, and rules in `Harness/MEMORY.md` and this docs router where applicable.
-- Added assets may extend `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, or `Harness/workflows/`, but they must not replace core harness docs.
-- Core harness docs are `Harness/README.md`, `Harness/PROGRESS.md`, `Harness/subagents.md`, `Harness/context-loading.md`, `Harness/dispatch.md`, `Harness/agent-workflow.md`, and this file.
-- If an optional workflow needs a new command or tool, document the command and fallback in `Harness/workflows/<name>.md` instead of changing core harness behavior.
-
-## Agent Contract
-
-Every added agent must have frontmatter:
-
-```yaml
----
-name: stack-agent-name
-description: Use when ...
-tools: Read, Grep, Glob
-model: sonnet
----
-```
-
-Agent body must state:
-
-- load first
-- inputs required
-- allowed write set or read-only
-- forbidden scope
-- verification or evidence
-- return format from [subagents.md](subagents.md) and [dispatch.md](dispatch.md)
-
-## Skill Contract
-
-Every added skill must state:
-
-- when to use
-- docs to load
-- required inputs
-- allowed writes
-- output format
-- whether to update `Harness/PROGRESS.md` and task files
-- whether to use [subagents.md](subagents.md) and [dispatch.md](dispatch.md)
-
+- Added assets may extend `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, or `Harness/workflows/`, but they must not replace core harness docs.
+- Core harness docs are `Harness/README.md`, `Harness/PROGRESS.md`, `Harness/subagents.md`, `Harness/context-loading.md`, `Harness/dispatch.md`, `Harness/agent-workflow.md`, and this file.
+- If an optional workflow needs a new command or tool, document the command and fallback in `Harness/workflows/<name>.md` instead of changing core harness behavior.
+
+## Agent Contract
+
+Every added agent must have frontmatter:
+
+```yaml
+---
+name: stack-agent-name
+description: Use when ...
+tools: Read, Grep, Glob
+model: sonnet
+---
+```
+
+Agent body must state:
+
+- load first
+- inputs required
+- allowed write set or read-only
+- forbidden scope
+- verification or evidence
+- return format from [subagents.md](subagents.md) and [dispatch.md](dispatch.md)
+
+## Skill Contract
+
+Every added skill must state:
+
+- when to use
+- docs to load
+- required inputs
+- allowed writes
+- output format
+- whether to update `Harness/PROGRESS.md` and task files
+- whether to use [subagents.md](subagents.md) and [dispatch.md](dispatch.md)
+
 Skills should extend the harness. They should not replace `Harness/README.md`, `Harness/PROGRESS.md`, `subagents.md`, `context-loading.md`, `dispatch.md`, or `agent-workflow.md`.
-
-## Rules
-
-- Do not add broad agents that can write anywhere.
-- Do not add agents whose role overlaps an existing common agent without naming the difference.
-- Do not add tools that bypass project permissions or user approval.
-- Do not run stack-specific writing agents in parallel unless write sets are disjoint.
-- If an added asset conflicts with this harness, adapt the asset instead of changing the core contract.
-
-## Registration
-
-After adding assets:
-
-- list agents in `Harness/MEMORY.md#Agents`
-- list skills in `Harness/MEMORY.md#Skills`
-- list workflows by path in `Harness/MEMORY.md` or `Harness/README.md`
-- update `Harness/PROGRESS.md` and `Harness/tasks/<task-id>/PROGRESS.md` when the asset affects current work
-- run `node Harness/scripts/validate-harness.mjs`
+
+## Rules
+
+- Do not add broad agents that can write anywhere.
+- Do not add agents whose role overlaps an existing common agent without naming the difference.
+- Do not add tools that bypass project permissions or user approval.
+- Do not run stack-specific writing agents in parallel unless write sets are disjoint.
+- If an added asset conflicts with this harness, adapt the asset instead of changing the core contract.
+
+## Registration
+
+After adding assets:
+
+- list agents in `Harness/MEMORY.md#Agents`
+- list skills in `Harness/MEMORY.md#Skills`
+- list workflows by path in `Harness/MEMORY.md` or `Harness/README.md`
+- update `Harness/PROGRESS.md` and `Harness/tasks/<task-id>/PROGRESS.md` when the asset affects current work
+- run `node Harness/scripts/validate-harness.mjs`

package/templates/common/Harness/lifecycle.md

@@ -1,12 +1,12 @@
-# 0-1 Product Lifecycle
-
-Use when starting a new product, clarifying a vague idea, or deciding the next phase.
-
-## Phase Contract
-
-| Phase | Input | Output | Gate |
-| --- | --- | --- | --- |
-| Idea | user intent | problem, target user, non-goals | unclear points asked or assumptions recorded |
+# 0-1 Product Lifecycle
+
+Use when starting a new product, clarifying a vague idea, or deciding the next phase.
+
+## Phase Contract
+
+| Phase | Input | Output | Gate |
+| --- | --- | --- | --- |
+| Idea | user intent | problem, target user, non-goals | unclear points asked or assumptions recorded |
 | Research | problem and constraints | `research/research-results.md` | `research/README.md` followed; at least 3 references or explicit reason not possible |
 | PRD | research decision | `research/PRD.md` or task Mini PRD | goal, scope, non-scope, user flow, and verification commands are explicit |
 | Acceptance | PRD | AC IDs in `ACCEPTANCE.md` section, feature doc, or task PLAN | every user-visible behavior has Given/When/Then and evidence method |
@@ -18,22 +18,22 @@ Use when starting a new product, clarifying a vague idea, or deciding the next p
 | Independent Validation | running slice | acceptance result matrix, screenshots/traces/logs | validator is not implementer; no unresolved critical/high findings |
 | Debug | failed AC evidence | root-cause handoff and smallest fix | failing layer identified before edits |
 | Memory | verified or repeated failure | concise memory entry or no-op rationale | durable lessons recorded without secrets |
-
-## Operating Rules
-
-- Move one phase at a time unless the user explicitly asks for a fast lane.
+
+## Operating Rules
+
+- Move one phase at a time unless the user explicitly asks for a fast lane.
 - Start coding only after PRD-GATE, AC-GATE, CONTRACT-GATE, TEST-GATE, and minimum architecture gates pass.
 - Prefer one thin vertical slice over broad scaffolding.
 - If feedback changes scope, update PRD and acceptance criteria before implementation.
 - If implementation reveals a boundary problem, update architecture or ports before continuing.
 - If implementation reveals incorrect acceptance criteria or contracts, stop and use Change Request from `ACCEPTANCE_PROTOCOL.md`; do not let the implementer rewrite truth files directly.
-
-## Fast Lane
-
-Small edits may skip full lifecycle when all are true:
-
-- user intent is clear
-- one file or one narrow behavior
+
+## Fast Lane
+
+Small edits may skip full lifecycle when all are true:
+
+- user intent is clear
+- one file or one narrow behavior
 - no architecture, permission, or public API change
 - one verification command or one manual check is enough
 - Mini PRD, AC IDs, and verification evidence still fit inside the task PLAN

package/templates/common/Harness/research/PRD.md

@@ -1,47 +1,47 @@
-# PRD: {{projectName}}
-
-> **Audience**: AI + future you. Not for PM approval — for implementation and review.
-> **Principle**: One page max. Use checkboxes, not prose. Negative definitions > positive definitions.
->
-> Philosophy source: Miqdad Jaffer (OpenAI)'s lean PRD template for the AI era.
-
----
-
-## 1. Why
-
-{{WHY_THIS_PROJECT_EXISTS}}
-
-## 2. MVP Scope
-
-### v0.1 Must Be Able To
-
-> Each item below should have a task capsule created from `Harness/tasks/_template/` with its own `PROGRESS.md` and `PLAN.md`.
-
-- [ ] {{MUST_1}}
-- [ ] {{MUST_2}}
-- [ ] {{MUST_3}}
-
-### Explicitly Out of Scope
-
-- {{NON_GOAL_1}}
-- {{NON_GOAL_2}}
-- {{NON_GOAL_3}}
-
-## 3. Decision Priorities
-
-1. **Security Boundary** — No bypassing permissions, security gates, or audit.
-2. **Architecture Boundary** — Domain must not depend on harness/infrastructure/interfaces, and harness must not make domain judgments.
-3. **Verifiability** — New behavior must have tests or explicit manual verification records.
-4. **Correctness** — Behavior must match design docs, port contracts, data flows, and state machines.
-5. **Simplicity** — Minimum code to solve the current MVP. No abstractions pre-built for future scenarios.
-
-## 4. Users & Usage Scenarios
-
-| User Role | Core Scenario | Frequency | Pain Point |
-| --- | --- | --- | --- |
-| {{USER_ROLE_1}} | {{SCENARIO}} | {{FREQUENCY}} | {{PAIN}} |
-| {{USER_ROLE_2}} | {{SCENARIO}} | {{FREQUENCY}} | {{PAIN}} |
-
+# PRD: {{projectName}}
+
+> **Audience**: AI + future you. Not for PM approval — for implementation and review.
+> **Principle**: One page max. Use checkboxes, not prose. Negative definitions > positive definitions.
+>
+> Philosophy source: Miqdad Jaffer (OpenAI)'s lean PRD template for the AI era.
+
+---
+
+## 1. Why
+
+{{WHY_THIS_PROJECT_EXISTS}}
+
+## 2. MVP Scope
+
+### v0.1 Must Be Able To
+
+> Each item below should have a task capsule created from `Harness/tasks/_template/` with its own `PROGRESS.md` and `PLAN.md`.
+
+- [ ] {{MUST_1}}
+- [ ] {{MUST_2}}
+- [ ] {{MUST_3}}
+
+### Explicitly Out of Scope
+
+- {{NON_GOAL_1}}
+- {{NON_GOAL_2}}
+- {{NON_GOAL_3}}
+
+## 3. Decision Priorities
+
+1. **Security Boundary** — No bypassing permissions, security gates, or audit.
+2. **Architecture Boundary** — Domain must not depend on harness/infrastructure/interfaces, and harness must not make domain judgments.
+3. **Verifiability** — New behavior must have tests or explicit manual verification records.
+4. **Correctness** — Behavior must match design docs, port contracts, data flows, and state machines.
+5. **Simplicity** — Minimum code to solve the current MVP. No abstractions pre-built for future scenarios.
+
+## 4. Users & Usage Scenarios
+
+| User Role | Core Scenario | Frequency | Pain Point |
+| --- | --- | --- | --- |
+| {{USER_ROLE_1}} | {{SCENARIO}} | {{FREQUENCY}} | {{PAIN}} |
+| {{USER_ROLE_2}} | {{SCENARIO}} | {{FREQUENCY}} | {{PAIN}} |
+
 ## 5. Acceptance Criteria
 
 - [ ] AC-001: {{GIVEN_WHEN_THEN_SUMMARY_1}}
@@ -55,18 +55,18 @@
 | UI | Critical controls have `data-testid` or stable accessible roles. | AC-001 |
 | API | Endpoint method, URL, payload, success, and failure behavior are explicit. | AC-002 |
 | State | URL, DOM, store, localStorage, database, or side effects are observable. | AC-003 |
-
-## 6. Non-Functional Requirements
-
-| Dimension | Target | Measurement |
-| --- | --- | --- |
-| {{DIMENSION_1}} | {{TARGET}} | {{MEASUREMENT}} |
-| {{DIMENSION_2}} | {{TARGET}} | {{MEASUREMENT}} |
-
----
-
-## Fill Completion Standard
-
+
+## 6. Non-Functional Requirements
+
+| Dimension | Target | Measurement |
+| --- | --- | --- |
+| {{DIMENSION_1}} | {{TARGET}} | {{MEASUREMENT}} |
+| {{DIMENSION_2}} | {{TARGET}} | {{MEASUREMENT}} |
+
+---
+
+## Fill Completion Standard
+
 - [ ] MVP and Non-goals are project facts; no `{{...}}` placeholders remain.
 - [ ] Decision priorities guide tradeoffs, not generic platitudes.
 - [ ] Every acceptance criterion has an AC ID and is verifiable by test, command, or manual step.