@openflowjs/cli 0.2.0

package/dist/core-artifacts/openflow/skills/spec/SKILL.md

@@ -0,0 +1,341 @@
+---
+name: openflow-spec
+description: Use for the OpenFlow spec phase: route level, clarify requirements, write iteration spec artifacts, run spec review, and hand off to implement.
+---
+
+# OpenFlow Spec
+
+Create a reviewable spec for one concrete change. The output must let a future agent execute the work without relying on chat history. This skill owns the spec-stage boundary — it must produce a reviewable iteration, not product code.
+
+This skill depends on:
+
+- `openflow-workflow-governance` for level, stage, and gate rules, directory contract, ID conventions, and artifact write order.
+- `openflow-cli-reference` for exact CLI command syntax and options.
+- `openflow-knowledge-retrieval` for knowledge search during spec writing.
+
+## Inputs
+
+- User request and follow-up answers.
+- `.openflow/config.json`
+- `.openflow/current.json`
+- Active iteration files under `.openflow/iterations/<iteration-id>/` when present.
+- Relevant repository source files, tests, docs, and conventions.
+- Review feedback from `reviews/spec-review.json` and `reviews/spec-reviewer.md` when present.
+
+Use `.openflow/config.json.language` for generated OpenFlow documents and final handoff text. If the value is absent, use `en-US`.
+
+## Preflight
+
+1. Run `openflow preflight --command spec` and parse the JSON output.
+2. Use `language` and `defaultLevel` from the output for all subsequent document generation.
+3. If `action` is `"continue"`, resume the iteration at `iterationPath`.
+4. If `action` is `"create"`, derive a slug from the user's request and run:
+   ```bash
+   openflow iteration create YYYY-MM-DD-short-slug
+   ```
+   Then use the new `iterationPath` returned by a follow-up `openflow state` call.
+
+Use an iteration id shaped like `YYYY-MM-DD-short-slug`. Keep all durable spec artifacts inside that iteration folder.
+Write generated OpenFlow documents in the resolved `language`; if absent, use `en-US`.
+
+## Level 0 Guard
+
+Before entering any spec flow, check whether the request meets **Level 0** criteria:
+
+- Single file change
+- Fewer than 10 lines affected
+- Zero risk (no API, no data, no permissions, no cross-boundary impact)
+- No ambiguity in the request
+
+If all four conditions are true: **Skip OpenFlow entirely.** Execute the change directly. Do not create an iteration, do not write artifacts, do not enter any level flow. Tell the user what was done and move on.
+
+If any condition is false, proceed to level routing below.
+
+## Level Routing
+
+See `openflow-workflow-governance` for complete level routing rules, selection criteria, and gate requirements.
+
+**Key points for spec phase:**
+- Route before writing the spec. Revise the route if exploration reveals more risk.
+- Level 0: Skip OpenFlow entirely for single-file, <10 lines, zero-risk changes.
+- Level 1: SPEC only (no PLAN/TASKS), conversational confirm.
+- Level 2: SPEC + PLAN + TASKS, single review gate (SPEC primary, PLAN/TASKS as reference).
+- Level 3: Full artifacts, single review gate (SPEC only; PLAN+TASKS reviewed by AI only).
+
+Routing belongs to the main agent using governance rules. A subagent may review the route but must not own the decision.
+
+## Clarification Loop
+
+Ask **exactly ONE** high-signal question at a time when unknowns would change:
+
+- scope or non-goals
+- acceptance criteria
+- platform/runtime boundaries
+- data shape, permissions, or migration
+- risk tolerance
+- review or validation requirements
+
+For each question:
+1. **Research the codebase FIRST** — most answers can be found by reading existing code, tests, or docs
+2. Only ask if the answer truly requires user judgment or preference
+3. Provide a recommended answer with rationale when applicable
+
+For Claude Code, use the exact tool `AskUserQuestion` for that single question. Do not ask blocking clarification questions as plain prose when the tool is available.
+
+Do not ask questions that can be answered by reading the repository. When you can proceed with a reasonable assumption, record it in `SPEC.md` or `CONTEXT.md` instead of interrupting the user.
+
+Continue the loop until the spec can state the goal, scope, non-goals, acceptance criteria, and risks without hand-waving.
+
+## Exploration Rules
+
+Read enough code and docs to avoid writing an abstract spec. Prefer narrow inspection:
+
+- existing modules and ownership boundaries
+- nearby tests and validation commands
+- existing UI/API/CLI patterns
+- prior OpenFlow iteration artifacts if they affect continuity
+- reference material only when it changes the spec
+
+Capture durable findings in `CONTEXT.md`. Do not dump raw notes that will not help execution.
+
+## Artifact Rules
+
+Write all spec-stage artifacts inside the active iteration folder:
+
+```text
+.openflow/iterations/<iteration-id>/
+  flow.json
+  STATE.md
+  SPEC.md
+  CONTEXT.md
+  TASKS.md        # Level 2+ only
+  PLAN.md         # Level 2+ only
+  reviews/
+```
+
+Use `SPEC.md` as the default human review surface. It should reduce reviewer burden, not expose every exploration note.
+
+Use `CONTEXT.md`, `TASKS.md`, and `PLAN.md` for AI-facing detail. Human-visible content may still be AI-readable, but the files have different jobs.
+
+> **⛔ Strict ordering constraint**: `PLAN.md` and `TASKS.md` must NEVER be generated before SPEC is approved by human review. SPEC is the single source of truth — PLAN/TASKS must be derived only from the approved SPEC. Violating this rule means the implement phase would act on unreviewed specifications.
+
+### Level-Conditional Artifacts
+
+| Artifact | Level 0 | Level 1 | Level 2 | Level 3 | When Written |
+|----------|---------|---------|---------|---------|----------|
+| SPEC.md | No | Yes | Yes | Yes | Start of spec phase |
+| CONTEXT.md | No | Optional | Yes | Yes | Start of spec phase (Level 1: only when exploration produces valuable findings) |
+| TASKS.md | No | No | Yes | Yes | **Only after SPEC is approved** |
+| PLAN.md | No | No | Yes | Yes | **Only after SPEC is approved** |
+
+## Level 1 Flow
+
+1. Create iteration via `openflow iteration create`.
+2. Write `SPEC.md` (simplified format only):
+   - One-Sentence Goal
+   - Scope (include mindmap diagram for clarity)
+   - Non-Goals
+   - Acceptance Criteria
+   > **Important**: Write SPEC.md in clear, accessible language. Prefer mermaid mindmaps to show feature structure. Ensure content is easy for humans to quickly understand and approve.
+3. **Ask user for confirmation** using `AskUserQuestion`. Translate visible text to `config.json.language`:
+
+   Question text: "SPEC is ready. Goal: [one-sentence goal]. Choose next step:"
+
+   Options:
+   - "Open website to review SPEC (in browser)"
+   - "I have issues, need revision"
+   - "Approved, but don't execute yet"
+   - "Approved, start execution now"
+
+4. Handle user choice:
+   - **"Open website to review SPEC"**: Call `openflow_review_start` with `flowPath=<iterationPath>` and `mode=spec`. Show the URL. Call `openflow_review_wait` with `closeOnSubmit=true`. Read `reviews/spec-review.json` and handle as approved/changes_requested.
+   - **"I have issues, need revision"**: Ask `AskUserQuestion` "Describe what needs to change:" (freeform), revise `SPEC.md`, then repeat step 3.
+   - **"Approved, but don't execute yet"**: Run `openflow flow set-gate approved`. Tell the user SPEC is approved and they can run `/openflow-implement` when ready.
+   - **"Approved, start execution now"**: Run `openflow flow set-gate approved`. Run `openflow flow set-stage implement`. Tell the user the iteration is ready and handoff to `/openflow-implement`.
+
+5. If approved: `flow.json.gate` must be `approved` before handing off.
+
+Do not write `PLAN.md` or `TASKS.md` for Level 1. `CONTEXT.md` is optional for Level 1 — write it only if exploration produces findings worth preserving.
+
+## Level 2 Flow
+
+1. Create iteration via `openflow iteration create`.
+2. **Opening Sequence (see `openflow-workflow-governance` Spec Phase Opening Sequence):**
+   - **① Read repository state (includes knowledge retrieval)**: Call `openflow-knowledge-retrieval` skill to retrieve relevant knowledge from `.openflow/knowledge/`. Then explore the codebase to understand current project state.
+   - **② Write explicit assumptions**: Write exploration results and retrieved knowledge into `CONTEXT.md` (including Assumptions section).
+   - **③ At most ONE question**: Ask only when assumptions cannot cover critical information (max 1 question).
+   - **④ Continue if not blocked**: Proceed directly to SPEC writing.
+3. Write `SPEC.md` with sections:
+   - One-Sentence Goal
+   - Scope (include mindmap diagram for clarity)
+   - Non-Goals
+   - Context
+   - Constraints
+   - Acceptance Criteria
+   - Risks
+
+   > **Important**:
+   > - Write SPEC.md in clear, accessible language. Avoid excessive technical jargon.
+   > - Prefer mermaid mindmaps to show feature structure and relationships.
+   > - Every section should be human-readable and easy to understand.
+   > - Use tables and diagrams to make content clearer.
+
+   Do **not** include "Decisions Needed" or "AI Execution Summary" sections.
+
+4. Run `openflow validate --flow .openflow/iterations/<iteration-id>`.
+
+5. **Ask user for SPEC confirmation** using `AskUserQuestion`. Translate visible text to `config.json.language`:
+
+   Question text: "SPEC is ready. Goal: [one-sentence goal]. Choose next step:"
+
+   Options:
+   - "Open website to review SPEC (in browser)"
+   - "I have issues, need revision"
+   - "Approved, but don't execute yet"
+   - "Approved, start execution now"
+
+6. Handle user choice:
+   - **"Open website to review SPEC"**: Call `openflow_review_start` with `flowPath=<iterationPath>` and `mode=spec`. Show the URL. Call `openflow_review_wait` with `closeOnSubmit=true`. Read `reviews/spec-review.json`.
+     - If `changes_requested`: run `openflow flow inc-revision`, revise `SPEC.md`, re-run validate, repeat from step 5.
+     - If `approved`: continue to step 7.
+   - **"I have issues, need revision"**: Ask `AskUserQuestion` "Describe what needs to change:" (freeform), run `openflow flow inc-revision`, revise `SPEC.md`, re-run validate, repeat from step 5.
+   - **"Approved, but don't execute yet"**: Set approved, write PLAN+TASKS (step 7), then stop — do NOT run `set-stage implement`.
+   - **"Approved, start execution now"**: Set approved, write PLAN+TASKS (step 7), then run `set-stage implement` and handoff.
+
+7. **After SPEC is approved** (gate confirmed in step 6), write `PLAN.md` and `TASKS.md`.
+   > **⛔ Do not generate early**: before entering this step, `flow.json.gate` must be `approved`. Do not create any content for `PLAN.md` or `TASKS.md` before steps 5–6.
+   - `PLAN.md` sections: Context, Decisions, File Map, Key Interfaces, Spec Coverage, Dependencies
+   - `TASKS.md`: per-task entries with stable T-### IDs, Files, Dependencies, Read First, Detailed Action, Acceptance Criteria, Evidence placeholder
+
+8. Run `openflow validate --flow .openflow/iterations/<iteration-id>`.
+
+9. Run `openflow flow set-gate approved`.
+
+10. If user chose "Approved, start execution now" (or review was approved and user intent was to execute):
+   - Run `openflow flow set-stage implement`.
+    - Tell the user the iteration is ready for `/openflow-implement`.
+    Otherwise tell the user SPEC+PLAN+TASKS are ready and they can run `/openflow-implement` when ready.
+
+## Level 3 Flow
+
+1. Create iteration via `openflow iteration create`.
+2. **Opening Sequence (see `openflow-workflow-governance` Spec Phase Opening Sequence):**
+   - **① Read repository state (includes knowledge retrieval)**: Call `openflow-knowledge-retrieval` skill to retrieve relevant knowledge from `.openflow/knowledge/`. Then explore the codebase to understand current project state.
+   - **② Write explicit assumptions**: Write exploration results and retrieved knowledge into `CONTEXT.md` (required, include Related Knowledge section + Assumptions section).
+   - **③ At most ONE question**: Ask only when assumptions cannot cover critical information (max 1 question).
+   - **④ Continue if not blocked**: Proceed directly to SPEC writing.
+3. Write `SPEC.md` with emphasis on human readability:
+   - One-Sentence Goal (clear and concise)
+   - Scope with mindmap diagram for visual understanding
+   - Non-Goals (explicit boundaries)
+   - Context (business background, code paths, design decisions, references)
+   - Constraints (boundaries, tests, tools/permissions)
+   - Acceptance Criteria (observable outcomes with verification methods)
+   - Risks (probability, impact, mitigation)
+
+   > **Important**:
+   > - Use clear, accessible language that non-technical stakeholders can understand.
+   > - Prefer mermaid diagrams (mindmap, flowchart) to show complex relationships.
+   > - Keep structure clear for quick human approval.
+   > - Every section should serve "help the reader quickly understand what to do, what not to do, and how to verify."
+
+4. **AI Revision Loop (SPEC)**: Run `artifact-reviewer` (AI subagent, mode: spec). Save output to `reviews/spec-reviewer.md`.
+   - If blockers are found, revise `SPEC.md` and re-run `artifact-reviewer` (mode: spec).
+   - Maximum 3 iterations of the revision loop.
+   - After 3 iterations, proceed with remaining blockers explicitly documented.
+
+5. Run `openflow validate --flow .openflow/iterations/<iteration-id>`.
+
+6. **Ask user for SPEC confirmation** using `AskUserQuestion` with the following text and exactly these 4 options:
+
+   Question text: "SPEC is ready (passed AI pre-review). Goal: [one-sentence goal]. Choose next step:"
+
+   Options:
+   - "Open website to review SPEC (in browser)"
+   - "I have issues, need revision"
+   - "Approved, but don't execute yet"
+   - "Approved, start execution now"
+
+7. Handle user choice:
+   - **"Open website to review SPEC"**: Call `openflow_review_start` with `flowPath=<iterationPath>` and `mode=spec`. Show the URL. Call `openflow_review_wait` with `closeOnSubmit=true`. Read `reviews/spec-review.json`.
+     - If `changes_requested`: run `openflow flow inc-revision`, revise, re-run AI loop + validate, repeat from step 6.
+     - If `approved`: continue to step 8.
+   - **"I have issues, need revision"**: Ask `AskUserQuestion` "Describe what needs to change:" (freeform), run `openflow flow inc-revision`, revise `SPEC.md`, re-run AI loop + validate, repeat from step 6.
+   - **"Approved, but don't execute yet"** or **"Approved, start execution now"**: Continue to step 8.
+
+8. **After SPEC approval**, write `PLAN.md` and `TASKS.md`.
+   > **⛔ Do not generate early**: before entering this step, `flow.json.gate` must be `approved`. Do not create any content for `PLAN.md` or `TASKS.md` before steps 6–7.
+
+
+9. **AI Revision Loop (PLAN)**: Run `artifact-reviewer` (AI subagent, mode: plan). Save output to `reviews/plan-reviewer.md`.
+    - If blockers are found, revise `PLAN.md`/`TASKS.md` and re-run `artifact-reviewer` (mode: plan).
+    - Maximum 3 iterations of the revision loop.
+    - After 3 iterations, proceed with remaining blockers explicitly documented.
+
+10. Run `openflow validate --flow .openflow/iterations/<iteration-id>`.
+
+11. Run `openflow flow set-gate approved`.
+12. If user chose "Approved, start execution now" (or review status was approved with implement intent):
+    - Run `openflow flow set-stage implement`.
+    - Tell the user the iteration is ready for `/openflow-implement`.
+    Otherwise tell the user SPEC+PLAN+TASKS are ready and they can run `/openflow-implement` when ready.
+
+## Required Spec Quality
+
+`SPEC.md` must make these clear:
+
+- What are we doing?
+- What are we not doing?
+- How will we know this is correct?
+- What is the background and context?
+- What constraints and boundaries apply?
+
+Avoid vague phrases such as "improve", "handle edge cases", or "make it better" unless the spec defines observable outcomes.
+
+SPEC.md does NOT include "Decisions Needed" or "AI Execution Summary" sections. Decisions belong in PLAN.md. Execution details belong in TASKS.md.
+
+## Task Quality
+
+`TASKS.md` (Level 2+ only) must contain executable task slices with stable IDs.
+
+Each task needs:
+
+- **Files**: which files to create or modify
+- **Read First**: files to read before implementing
+- **Action**: concrete implementation steps
+- **Acceptance Criteria**: observable condition proving completion
+- **Validation**: command or check to verify correctness
+- **Evidence**: placeholder for execution results
+
+Tasks should be small enough for `/openflow-implement` to complete and validate independently. Do not create a single task named "implement everything".
+
+## Done State
+
+The spec phase is done when:
+
+- `flow.json.stage` is `spec`.
+- `flow.json.gate` is `approved` for Level 2+.
+- For Level 1: conversational confirm received.
+- `SPEC.md`, `CONTEXT.md` are current for the same revision.
+- `PLAN.md` and `TASKS.md` exist and are current for Level 2+ iterations.
+- `reviews/spec-review.json` records approval when review is required (Level 2+).
+- The final response tells the user the iteration id and that `/openflow-implement` can start.
+
+## Guardrails
+
+- Do not implement product code in this phase.
+- Do not scatter files directly under `.openflow/` except project-level control files such as `config.json` and `current.json`.
+- Do not use OpenFlow MCP for workflow state management. MCP is only for Review UI interaction; write `.openflow` artifacts directly and validate them with `openflow validate`.
+- When clarification is required in Claude Code, research the repository first, then use the exact tool name `AskUserQuestion` with exactly one high-signal question. Include a recommended answer with rationale when applicable. Do not ask blocking questions as plain prose.
+- Do not generate an HTML spec as the source of truth. Write `SPEC.md`; the Review UI owns HTML rendering, styling, comments, and approval state.
+- Do not let a subagent make routing or phase-transition decisions. Subagents can review and recommend only.
+- Do not proceed to `/openflow-implement` for Level 2 or Level 3 without an approved review, unless the user explicitly overrides the gate and the override is recorded in `flow.json` and `STATE.md`.
+
+## User-Facing Output
+
+When communicating with the user:
+
+- Do not show raw `openflow validate` or `openflow preflight` error codes, field names, or schema rules (e.g. `tasks.checkbox`, `markdown.heading`, `flow.gate`). Translate errors into plain language (e.g. "There is a formatting issue in TASKS.md" instead of "tasks.checkbox: TASKS.md must include at least one checkbox task with a stable T-### id").
+- Do not explain internal OpenFlow state machine concepts (gates, stages, revisions, level routing rationale) unless the user asks.
+- Do not output "Insight" blocks about OpenFlow's internal mechanics, validation rules, or artifact schemas.
+- Keep status updates short: iteration id, what changed, and what the user should do next.

package/dist/core-artifacts/openflow/skills/spec/references/context-template.md

@@ -0,0 +1,38 @@
+# CONTEXT.md
+
+`CONTEXT.md` stores AI-facing exploration context for execution.
+
+Location:
+
+```text
+.openflow/iterations/<iteration-id>/CONTEXT.md
+```
+
+Template:
+
+```markdown
+# Context
+
+## Repository Findings
+
+- `<path>`: <Relevant pattern, constraint, or behavior.>
+
+## Assumptions
+
+- <Assumption that allowed the spec to proceed.>
+
+## Constraints
+
+- <Technical, product, platform, or policy constraint.>
+
+## References
+
+- <Reference material used, only when it affected the spec.>
+```
+
+Rules:
+
+- Write only context that helps future execution.
+- Prefer exact file paths and concise notes over pasted source.
+- If an assumption could change scope, surface it in `SPEC.md` instead.
+- Decisions belong in `PLAN.md`, not here.

package/dist/core-artifacts/openflow/skills/spec/references/plan-template.md

@@ -0,0 +1,61 @@
+# PLAN.md
+
+Technical execution plan for Level 2+ iterations. Location: `.openflow/iterations/<iteration-id>/PLAN.md`
+
+## Sections
+
+- **`# Plan: <title>`** — Title matching SPEC.md.
+- **`## Context`** — Why this plan exists and current state.
+- **`## Decisions`** — Technical decisions in D-NNN table: `| ID | Decision | Choice | Reason | Alternatives |`
+- **`## File Map`** — Every file touched: `| File | Action | Description |`
+- **`## Spec Coverage`** — REQ→Task mapping: `| Requirement | Task(s) |`. Optional **Multi-Source Audit**: `| GOAL | REQ | CONTEXT | Task(s) |`
+- **`## Must Haves`** — Verifiable claims: `truths` (observable behaviors), `artifacts` (required files), `key_links` (file connections).
+- **`## Key Interfaces`** — Public APIs/contracts affected: `| Interface | Change | Impact |`
+- **`## Dependencies`** — Task DAG: `T-001 → T-002, T-003`. Optional **Wave** format: `Wave 1: T-001` / `Wave 2: T-002, T-003 (parallel)`
+- **`## Risks`** — Implementation risks: `| Risk | Mitigation |`
+
+## Level-Conditional Requirements
+
+| Section | Level 2 | Level 3 |
+|---------|---------|---------|
+| `# Plan: <title>` | Required | Required |
+| `## Context` | Required | Required |
+| `## Decisions` | Required | Required |
+| `## File Map` | Required | Required |
+| `## Spec Coverage` | Required | Required |
+| `## Must Haves` | Optional | Required |
+| `## Key Interfaces` | Optional | Required |
+| `## Dependencies` | Optional | Required |
+| `## Risks` | Optional | Required |
+| `## Must NOT Have` | Optional | Optional |
+| `## Wave Dependencies` | Optional | Optional |
+| `## Multi-Source Audit` | Optional | Optional |
+
+Target 50-200 lines. Over 200 → split iteration.
+
+## Example
+
+```markdown
+# Plan: Add Level Routing
+
+## Context
+Replace three-tier routing with four-level model (Level 0-3).
+
+## Decisions
+| ID | Decision | Choice | Reason | Alternatives |
+|----|----------|--------|--------|-------------|
+| D-001 | Level storage | `level: 0-3` | Simple | String enum |
+
+## File Map
+| File | Action | Description |
+|------|--------|-------------|
+| `src/flow/schema.ts` | Modify | Add `level` field |
+
+## Spec Coverage
+| Requirement | Task(s) |
+|-------------|---------|
+| R-001 | T-001 |
+
+## Dependencies
+T-001 → T-002, T-003
+```

package/dist/core-artifacts/openflow/skills/spec/references/spec-template.md

@@ -0,0 +1,187 @@
+# SPEC.md
+
+`SPEC.md` is the default human review surface and the main statement of what the iteration should deliver.
+
+Location:
+
+```text
+.openflow/iterations/<iteration-id>/SPEC.md
+```
+
+## Required Headings
+
+The validator requires these exact headings (in English). Content below each heading may be in any language.
+
+1. `# Spec: <title>`
+2. `## One-Sentence Goal`
+3. `## Scope`
+4. `## Non-Goals`
+5. `## Context`
+6. `## Constraints`
+7. `## Acceptance Criteria`
+
+### Optional Per Level
+
+| Heading | Level 0 | Level 1 | Level 2 | Level 3 |
+|---------|---------|---------|---------|---------|
+| `## One-Sentence Goal` | N/A | Required | Required | Required |
+| `## Scope` | N/A | Required | Required | Required |
+| `## Non-Goals` | N/A | Required | Required | Required |
+| `## Context` | N/A | Optional | Required | Required |
+| `## Constraints` | N/A | Optional | Required | Required |
+| `## Acceptance Criteria` | N/A | Required | Required | Required |
+| `## Risks` | N/A | Optional | Required | Required |
+
+### Removed Sections
+
+The following sections are NO LONGER part of SPEC.md:
+
+- `## Decisions Needed` -- Decisions belong in PLAN.md.
+- `## AI Execution Summary` -- Execution details belong in TASKS.md.
+
+Do not include these headings in SPEC.md.
+
+## Template
+
+```markdown
+# Spec: <title>
+
+## One-Sentence Goal
+
+<One sentence describing the outcome and its significance>
+
+## Scope
+
+### Mindmap
+
+```mermaid
+mindmap
+  root((Feature Topic))
+    Sub-feature 1
+      Implementation 1
+      Implementation 2
+    Sub-feature 2
+      Implementation 3
+```
+
+> 💡 **Tip**: Use mindmaps to visually show feature structure and relationships. Recommended mermaid types: mindmap, flowchart, or sequenceDiagram.
+
+### Feature Scope
+
+| ID | Requirement | Description |
+|----|------------|-------------|
+| R-001 | <Short name> | <Observable outcome> |
+| R-002 | <Short name> | <Observable outcome> |
+
+## Non-Goals
+
+| Excluded | Reason |
+|-----------|--------|
+| <Work not being done> | <Why> |
+
+## Context
+
+<Optional for Level 1, required for Level 2+>
+
+### Business Background
+<Why this change is needed, what problem it solves>
+
+### Relevant Code
+<Related files, directories, and modules. Use code formatting, e.g. `packages/core/src/agents/`>
+
+### Design Decisions
+<Related historical design decisions>
+
+### References
+<Reference implementations, related resources, or similar features>
+
+## Constraints
+
+<Optional for Level 1, required for Level 2+>
+
+### Boundaries
+<Parts that must not be modified or affected>
+
+### Test Requirements
+<Existing tests that must pass after implementation>
+
+### Tools and Permissions
+<Allowed tools, libraries, frameworks, or special permissions>
+
+## Acceptance Criteria
+
+| ID | Acceptance Criterion | Verification Method |
+|----|---------------------|-------------------|
+| A-001 | <Observable completion condition> | <How to check> |
+| A-002 | <Observable completion condition> | <How to check> |
+
+## Risks
+
+<Required for Level 2+, optional for Level 1>
+
+| Risk | Probability | Impact | Mitigation |
+|------|------------|--------|------------|
+| <Potential issue> | High/Medium/Low | High/Medium/Low | <How to handle> |
+```
+
+## Formatting Guidelines
+
+### Prioritize Human Readability
+
+SPEC.md's primary reader is a human reviewer. Ensure:
+
+- **Clear language**: Use concise, accessible language. Avoid jargon overload.
+- **Clear structure**: Use headings, tables, and diagrams for quick scanning.
+- **Highlight key info**: Place critical information prominently. Use formatting (bold, blockquotes) for emphasis.
+
+### Diagrams First
+
+Text suits details; diagrams suit big-picture understanding. Prefer diagrams:
+
+1. **Mindmap** (`mindmap`): Show feature structure and hierarchy
+2. **Flowchart** (`flowchart`): Show workflows and decision logic
+3. **Sequence diagram** (`sequenceDiagram`): Show component interactions
+
+Each SPEC should include at least one mindmap to help quickly understand overall scope.
+
+### Mermaid Diagrams
+
+Use `mermaid` code blocks. The Review UI renders them as SVG:
+
+```mermaid
+mindmap
+  root((Topic))
+    Branch 1
+      Item 1
+      Item 2
+    Branch 2
+      Item 3
+```
+
+Supported diagram types:
+- `mindmap` - Concept hierarchy and feature structure (recommended for Scope)
+- `flowchart` - Workflows and decision trees
+- `sequenceDiagram` - Component interactions
+- `gantt` - Timelines (less common)
+
+Keep diagrams simple (fewer than 15 nodes). Split complex diagrams into multiple focused ones.
+
+### Tables
+
+Use GFM tables for structured data: requirements, acceptance criteria, risks. Tables are easier to scan than prose and align well in the Review UI.
+
+### ASCII Trees
+
+Tree characters (`├──`, `└──`) in `text` code blocks can show directory structures or simple hierarchies. These render well in any markdown viewer.
+
+## Rules
+
+**Human-first principle**:
+- Optimize for quick human approval and scope understanding
+- Use clear, accessible language; avoid over-engineering the prose
+- Use diagrams to aid understanding; prefer mermaid mindmaps for overall structure
+- Keep it concise: do not expose implementation details in SPEC.md unless they affect scope, risk, or acceptance
+- Do not embed HTML, scripts, CSS, or UI directives
+- For richer rendering, use stable headings and IDs for the Review UI to parse
+- Each acceptance criterion should map to at least one task in `TASKS.md`
+- Use table format for requirements, acceptance criteria, and risks