@polymorphism-tech/morph-spec 4.7.2 → 4.8.1

package/docs/COMMAND-FLOWS.md

@@ -1,368 +1,398 @@
-# morph-spec — Command Flow Diagrams
+# morph-spec — Framework Flows
 
-> Each diagram shows the sequence of CLI calls and internal function calls for each slash command.
+> Authoritative reference for how the framework connects: slash commands → skills → CLI → state manager.
+> Version: 4.8.1
 
 ---
 
-## 1. /morph-proposal
+## 1. Mental Model — The 4 Layers
 
-```mermaid
-flowchart TD
-    START(["/morph-proposal FEATURE"]) --> A
-
-    A["state get FEATURE"] --> B{"Exists?"}
-    B -->|yes| C["Identify current phase\nResume from where it stopped"]
-    B -->|no| D["Start Phase 0 from scratch"]
-    C --> D
-
-    subgraph P0 ["PHASE 0 — PROPOSAL"]
-        D --> E["detect-agents INPUT"]
-        E --> E1["loadAgentsConfig() ← agents.json"]
-        E1 --> E2["detectAgents() — keyword matching"]
-        E2 --> E3["analyzeRequestComplexity()"]
-        E3 --> E4["getStandardsListForAgent()\nloadStandardsForAgent()"]
-        E4 --> F["Render proposal.md via template"]
-        F --> G1["state set FEATURE status draft"]
-        G1 --> G2["state set FEATURE phase proposal"]
-        G2 --> G3["state mark-output FEATURE proposal"]
-        G3 --> G4["state add-agent FEATURE agent-id × N"]
-        G4 --> PAUSE0(["⏸ GATE — approve proposal"])
-    end
-
-    PAUSE0 -->|approved| H
-
-    subgraph P1 ["PHASE 1 — SETUP (auto, no gate)"]
-        H["Read .morph/context/"] --> I["Confirm detected stack"]
-        I --> J["List active agents"]
-        J --> J2["state set FEATURE phase setup"]
-    end
-
-    J2 --> UICHECK{"uiux-designer\nin activeAgents?"}
-
-    subgraph P15 ["PHASE 1.5 — UI/UX (conditional)"]
-        UICHECK -->|yes| L["Generate wireframes + design system\n(.claude/skills/phase-uiux/SKILL.md)"]
-        L --> PAUSEUI(["⏸ GATE — approve UI/UX"])
-    end
-
-    UICHECK -->|no| M
-    PAUSEUI -->|approved| M
-
-    subgraph P2 ["PHASE 2 — DESIGN"]
-        M["Generate spec.md\n(.claude/skills/phase-design/SKILL.md)"] --> N["Generate contracts.cs"]
-        N --> O["Generate decisions.md with ADRs"]
-        O --> P["Estimate costs per resource"]
-        P --> Q1["state mark-output FEATURE spec"]
-        Q1 --> Q2["state mark-output FEATURE contracts"]
-        Q2 --> Q3["state mark-output FEATURE decisions"]
-        Q3 --> PAUSE2(["⏸ GATE — approve design"])
-    end
-
-    PAUSE2 -->|approved| R
-
-    subgraph P3 ["PHASE 3 — CLARIFY"]
-        R["Identify ambiguities in spec\n(.claude/skills/phase-clarify/SKILL.md)"] --> S["Generate 3-7 questions"]
-        S --> WAIT(["⏳ Waiting for user answers"])
-        WAIT -->|answered| T["Update spec with clarifications\nand edge cases"]
-        T --> T2["state set FEATURE phase clarify"]
-    end
-
-    T2 --> U
-
-    subgraph P4 ["PHASE 4 — TASKS"]
-        U["Break spec into tasks T001-TXXX\n(.claude/skills/phase-tasks/SKILL.md)"] --> V["Define order and dependencies"]
-        V --> W["Checkpoints every 3 tasks"]
-        W --> X1["state mark-output FEATURE tasks"]
-        X1 --> X2["state set FEATURE tasks.total N"]
-        X2 --> PAUSE4(["⏸ GATE — approve tasks"])
-    end
-
-    PAUSE4 -->|approved| END(["✅ Planning complete\nRun /morph-apply FEATURE"])
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  USER                                                               │
+│    /morph-proposal my-feature          (Claude Code slash command)  │
+└────────────────────────┬────────────────────────────────────────────┘
+                         │ invokes Skill tool
+┌────────────────────────▼────────────────────────────────────────────┐
+│  SKILL  (.claude/skills/{name}/SKILL.md)                            │
+│    Claude reads the markdown and follows its instructions.          │
+│    Skills chain other skills via "invoke Skill tool with X".        │
+│    Skills call CLI via Bash tool: npx morph-spec ...                │
+└────────────────────────┬────────────────────────────────────────────┘
+                         │ Bash: npx morph-spec <command>
+┌────────────────────────▼────────────────────────────────────────────┐
+│  CLI  (bin/morph-spec.js → src/commands/**)                         │
+│    Commander.js routes to command handler functions.                │
+│    Handlers call state-manager.js and other lib modules.            │
+└────────────────────────┬────────────────────────────────────────────┘
+                         │ imports
+┌────────────────────────▼────────────────────────────────────────────┐
+│  STATE MANAGER  (src/core/state/state-manager.js)                   │
+│    Single source of truth. Reads/writes .morph/state.json.          │
+│    All state mutations go through here — never direct file edits.   │
+└─────────────────────────────────────────────────────────────────────┘
 ```
 
----
-
-## 2. /morph-apply
-
-```mermaid
-flowchart TD
-    START(["/morph-apply FEATURE"]) --> A
-
-    A["state get FEATURE"] --> B{"All phases\ncomplete?"}
-    B -->|no| ERR(["❌ ERROR — phase X not complete\nRun /morph-proposal FEATURE"])
-    B -->|yes| C
-
-    subgraph PREP ["INITIALIZATION"]
-        C["Read 1-design/spec.md + 3-tasks/tasks.md + 1-design/contracts.cs"] --> D
-        D["Read framework/standards/\n.morph/context/"] --> E1
-        E1["state set FEATURE phase implement"] --> E2
-        E2["state set FEATURE status in_progress"] --> E3
-        E3["state set FEATURE tasks.total N"]
-    end
+**Hooks** run as side-effects alongside this chain (see Section 9).
 
-    E3 --> LOOP_START
-
-    subgraph LOOP ["LOOP — For each task in order"]
-        LOOP_START["Select next task"] --> F
-        F["task start FEATURE task-id"] --> F1
-        F1["spawn task-manager.cjs start"] --> G
-        G["Implement code\nfollowing contracts.cs + standards"] --> H
-        H["task done FEATURE task-id"] --> H1
-        H1["spawn task-manager.cjs done"] --> VAL_START
-
-        subgraph VAL ["Automatic validators (hooks)"]
-            VAL_START["security-expert\nSQL injection, XSS, hardcoded secrets"] --> V2
-            V2["architecture-expert\nIDbContextFactory, async/await, DI order"] --> V3
-            V3["packages-validator\nNuGet conflicts, vulnerabilities"] --> V4
-            V4["blazor-concurrency-validator\nLifecycle, thread safety"]
-        end
-
-        V4 --> VRESULT{"Validation\npassed?"}
-        VRESULT -->|no| FIX["Fix violations\nDO NOT use --skip-validation"] --> H
-        VRESULT -->|yes| CHK{"task_count\nmultiple of 3?"}
-        CHK -->|yes| CP["state checkpoint FEATURE\nstate list"]
-        CHK -->|no| NEXT
-        CP --> NEXT{"Next task\nexists?"}
-        NEXT -->|yes| LOOP_START
-    end
+---
 
-    NEXT -->|no| FIN1
+## 2. Slash Command → Skill Map
 
-    subgraph FIN ["FINALIZATION"]
-        FIN1["generate recap FEATURE"] --> FIN2
-        FIN2["extractFeatureMetadata()\nWrites 4-implement/recap.md"] --> FIN3
-        FIN3["state set FEATURE status done"] --> FIN4
-        FIN4["state mark-output FEATURE recap"] --> FIN5
-        FIN5["phase advance FEATURE"]
-    end
+| Slash command | Skill invoked | What it covers |
+|---|---|---|
+| `/morph-proposal {feature}` | Chains: `phase-setup` → `phase-uiux`\* → `phase-design` → `phase-clarify` → `phase-tasks` | Full planning pipeline (phases 1–4) |
+| `/morph-apply {feature}` | `phase-implement` | Implementation (phase 5) |
+| `/morph-status` | No skill — Claude uses `morph-spec status` directly | Feature status dashboard |
+| `/morph-preflight` | No skill — Claude runs validators directly | Pre-deploy validation checks |
+| `/morph-archive {feature}` | No skill — Claude follows CLAUDE.md instructions | Archive completed feature |
+| `/{phase-name} {feature}` | The matching phase skill directly | Run a single phase |
 
-    FIN5 --> END(["✅ Feature complete\nRun /morph-archive FEATURE"])
-```
+\* `phase-uiux` only if frontend agents are active.
 
 ---
 
-## 3. /morph-status
+## 3. Skill Invocation Chain
 
 ```mermaid
 flowchart TD
-    START(["/morph-status"]) --> A
-
-    A["state list"] --> B
-    B["StateManager.getSummary()"] --> C
-    C["StateManager.listFeatures()"] --> D
-    D["Read .morph/state.json"] --> DASH
-
-    DASH["Display dashboard\nfeatures | phases | tasks X/Y | agents | costs"] --> EXTRA
-
-    EXTRA{"Specific feature\nrequested?"} -->|yes| G
-    EXTRA -->|no| CHECK
-
-    G["state get FEATURE"] --> G1["StateManager.getFeature()"] --> CHECK
-
-    subgraph CHECK_BLOCK ["Additional checks"]
-        CHECK["Check .morph/config/config.json"] --> CHECK2
-        CHECK2["Check .morph/framework/standards/ present"] --> CHECK3
-        CHECK3["Check .morph/archive/\ncompleted features"]
-    end
-
-    CHECK3 --> SUGEST["Suggest next actions\n/morph-proposal | /morph-apply | /morph-archive"]
-
-    SUGEST --> END(["✅ Dashboard displayed"])
+    P(["/morph-proposal FEATURE"]) --> SETUP
+
+    SETUP["Skill: phase-setup\n(Phase 1)"]
+    SETUP --> UICHECK{"uiux-designer\nactive?"}
+    UICHECK -->|yes| UIUX["Skill: phase-uiux\n(Phase 1.5)"]
+    UICHECK -->|no| DESIGN
+    UIUX --> DESIGN
+
+    DESIGN["Skill: phase-design\n(Phase 2)"]
+    DESIGN --> CODEBASE["Skill: phase-codebase-analysis\n(sub-phase of Design)"]
+    CODEBASE --> DESIGN2["Back in phase-design:\nspec.md + contracts.cs + decisions.md"]
+    DESIGN2 --> GATE1(["⏸ Gate: approve design"])
+    GATE1 -->|approved| CLARIFY
+
+    CLARIFY["Skill: phase-clarify\n(Phase 3)"]
+    CLARIFY --> TASKS
+
+    TASKS["Skill: phase-tasks\n(Phase 4)"]
+    TASKS --> GATE2(["⏸ Gate: approve tasks"])
+    GATE2 --> DONE(["✅ /morph-proposal complete"])
+
+    A(["/morph-apply FEATURE"]) --> IMPL
+    IMPL["Skill: phase-implement\n(Phase 5)"]
+    IMPL --> DONE2(["✅ /morph-apply complete"])
 ```
 
+**How one skill calls another:**
+Skills don't call each other via code. The SKILL.md instructs Claude to `invoke Skill tool with <skill-name>`. Claude executes that as a new Skill tool call. Each skill is a fresh markdown load — they share context only through the conversation and the state.json.
+
 ---
 
-## 4. /morph-archive
+## 4. /morph-proposal — Detailed Flow
 
 ```mermaid
 flowchart TD
-    START(["/morph-archive FEATURE"]) --> A
+    START(["/morph-proposal FEATURE"]) --> CHECK
+
+    CHECK["morph-spec state get FEATURE"] --> EXISTS{"Feature\nexists?"}
+    EXISTS -->|yes| RESUME["Resume from current phase"]
+    EXISTS -->|no| P0
+
+    subgraph PHASE0 ["PHASE 0 — PROPOSAL  (Claude writes directly)"]
+        P0["Write 0-proposal/proposal.md"] --> P0S1
+        P0S1["morph-spec state set FEATURE phase proposal"] --> P0S2
+        P0S2["morph-spec state set FEATURE status draft"] --> P0S3
+        P0S3["morph-spec state mark-output FEATURE proposal"] --> P0S4
+        P0S4["morph-spec state add-agent FEATURE agent-id × N"]
+        P0S4 --> GATE0(["⏸ GATE — approve proposal\nmorph-spec approve FEATURE proposal"])
+    end
 
-    A["Read .morph/features/FEATURE/3-tasks/tasks.md"] --> B
-    B{"All tasks\ncomplete?"} -->|no| ERR(["❌ Feature not ready\nFinish pending tasks first"])
-    B -->|yes| C
+    GATE0 -->|approved| PHASE1
 
-    C(["Confirm with user\nthat archiving is OK"]) --> D
+    subgraph PHASE1 ["PHASE 1 — SETUP  (Skill: phase-setup)"]
+        S1["Read .morph/context/README.md"] --> S2
+        S2["Read .morph/framework/agents.json\nMatch keywords → active agents"] --> S3
+        S3["morph-spec state set FEATURE phase setup"] --> S4
+        S4["morph-spec state set FEATURE status in_progress"]
+    end
 
-    subgraph RECAP ["RECAP"]
-        D["Update 4-implement/recap.md"] --> D1
-        D1["Fill in final metrics\n(tasks, time, actual vs estimated cost)"] --> D2
-        D2["Document lessons learned"]
+    S4 --> UICHECK{"uiux-designer\nin activeAgents?"}
+
+    subgraph PHASE15 ["PHASE 1.5 — UI/UX  (Skill: phase-uiux, conditional)"]
+        UICHECK -->|yes| U1["Write 2-ui/design-system.md"]
+        U1 --> U2["Write 2-ui/mockups.md"]
+        U2 --> U3["Write 2-ui/components.md"]
+        U3 --> U4["Write 2-ui/flows.md"]
+        U4 --> U5["morph-spec state mark-output FEATURE uiDesignSystem"]
+        U5 --> U6["morph-spec state mark-output FEATURE uiMockups"]
+        U6 --> U7["morph-spec state mark-output FEATURE uiComponents"]
+        U7 --> U8["morph-spec state mark-output FEATURE uiFlows"]
+        U8 --> GATE15(["⏸ GATE — approve UI/UX\nmorph-spec approve FEATURE uiux"])
     end
 
-    D2 --> E{"Does spec define permanent\nsystem behavior?"}
+    UICHECK -->|no| PHASE2
+    GATE15 -->|approved| PHASE2
+
+    subgraph PHASE2 ["PHASE 2 — DESIGN  (Skill: phase-design + phase-codebase-analysis)"]
+        D0["Skill: phase-codebase-analysis\nRead DB schema via Supabase MCP or Grep"] --> D1
+        D1["morph-spec state mark-output FEATURE schema-analysis"] --> D2
+        D2["morph-spec template render code/dotnet/contracts/contracts-levelN.cs"] --> D3
+        D3["morph-spec template render docs/spec"] --> D4
+        D4["morph-spec template render feature/decisions"] --> D5
+        D5["morph-spec state set FEATURE phase design"] --> D6
+        D6["morph-spec state set FEATURE costs.estimated X.XX"] --> D7
+        D7["morph-spec state mark-output FEATURE spec"] --> D8
+        D8["morph-spec state mark-output FEATURE contracts"] --> D9
+        D9["morph-spec state mark-output FEATURE decisions"]
+        D9 --> GATE2(["⏸ GATE — approve design\nmorph-spec approve FEATURE design"])
+    end
 
-    E -->|yes| F["Extract spec → .morph/specs/DOMAIN/\nBecomes the 'current truth' of the system"]
-    F --> G
-    E -->|no| G
+    GATE2 -->|approved| PHASE3
 
-    subgraph MOVE ["MOVE"]
-        G["Move full directory:\n.morph/features/FEATURE/\n→ .morph/archive/FEATURE/"]
+    subgraph PHASE3 ["PHASE 3 — CLARIFY  (Skill: phase-clarify)"]
+        C1["Read 1-design/spec.md\nIdentify 3-7 ambiguities"] --> C2
+        C2["Present questions → wait for answers"] --> C3
+        C3["Update spec with clarifications"] --> C4
+        C4["morph-spec state set FEATURE phase clarify"]
     end
 
-    G --> H
+    C4 --> PHASE4
 
-    subgraph METRICS ["METRICS UPDATE"]
-        H["Increment completed features counter"] --> I
-        I["Update total accumulated cost"] --> J
-        J["Update total time spent"]
+    subgraph PHASE4 ["PHASE 4 — TASKS  (Skill: phase-tasks)"]
+        T1["Read spec.md + contracts.cs"] --> T2
+        T2["Check domain complexity level\ngrep '## Domain Complexity' spec.md"] --> T3
+        T3["Write 3-tasks/tasks.md (T001…TXXX)"] --> T4
+        T4["morph-spec state set FEATURE phase tasks"] --> T5
+        T5["morph-spec state set FEATURE tasks.total N"] --> T6
+        T6["morph-spec state mark-output FEATURE tasks"]
+        T6 --> GATE4(["⏸ GATE — approve tasks\nmorph-spec approve FEATURE tasks"])
     end
 
-    J --> END(["✅ Feature archived at\n.morph/archive/FEATURE/"])
+    GATE4 --> END(["✅ Planning complete\nRun /morph-apply FEATURE"])
 ```
 
 ---
 
-## 5. /morph-infra
+## 5. /morph-apply — Detailed Flow
 
 ```mermaid
 flowchart TD
-    START(["/morph-infra ACTION"]) --> ROUTE
-
-    ROUTE{"Action?"}
-
-    ROUTE -->|init| INIT_1
-    ROUTE -->|validate| VAL_1
-    ROUTE -->|plan| PLAN_1
-    ROUTE -->|deploy| DEP_1
-    ROUTE -->|destroy| DES_1
-
-    subgraph INIT ["INIT — Initialize IaC"]
-        INIT_1["Copy templates from\n.morph/framework/templates/infrastructure/"] --> INIT_2
-        INIT_2["Create infra/ structure\nmain.bicep\nparameters.dev.json, parameters.prod.json\nmodules/*.bicep"] --> INIT_3
-        INIT_3["Replace placeholders\nAPP_NAME, SUBSCRIPTION_ID\nRESOURCE_GROUP"] --> INIT_4
-        INIT_4["Document structure in decisions.md"]
-        INIT_4 --> INIT_END(["✅ Done — run /morph-infra validate"])
+    START(["/morph-apply FEATURE"]) --> CHECK
+
+    subgraph INIT ["INITIALIZATION  (Skill: phase-implement)"]
+        CHECK["morph-spec state get FEATURE"] --> GATES
+        GATES["morph-spec approval-status FEATURE\nVerify design + tasks gates passed"] --> READ
+        READ["Read 1-design/spec.md\nRead 3-tasks/tasks.md\nRead 1-design/contracts.cs"] --> SETPHASE
+        SETPHASE["morph-spec state set FEATURE phase implement"] --> SETSTATUS
+        SETSTATUS["morph-spec state set FEATURE status in_progress"]
     end
 
-    subgraph VALIDATE ["VALIDATE — Validate Templates"]
-        VAL_1["az bicep build --file infra/main.bicep"] --> VAL_2
-        VAL_2["Check required parameters"] --> VAL_3{"No errors?"}
-        VAL_3 -->|yes| VAL_OK(["✅ Templates valid"])
-        VAL_3 -->|no| VAL_ERR(["❌ Report syntax errors"])
+    SETSTATUS --> GETNEXT
+
+    subgraph TASKLOOP ["TASK LOOP"]
+        GETNEXT["morph-spec task next FEATURE\n(find next pending task)"] --> START_T
+        START_T["morph-spec task start FEATURE T00X"] --> IMPL
+        IMPL["Implement code\nfollowing contracts.cs + standards\nTDD: write test first"] --> TEST
+        TEST["dotnet test / npm test"] --> TESTOK{"Tests\npassed?"}
+        TESTOK -->|no| FIX["Fix code"] --> TEST
+        TESTOK -->|yes| DONE_T
+        DONE_T["morph-spec task done FEATURE T00X"] --> DISPATCH
+        DISPATCH["[Hook: dispatch.js fires]\nChecks: completed % 3 === 0?"] --> CHKCHECK{"Auto-checkpoint\nneeded?"}
+        CHKCHECK -->|yes| CP["morph-spec checkpoint-save FEATURE\n(auto-triggered by dispatch.js hook)"]
+        CP --> MORETASKS
+        CHKCHECK -->|no| MORETASKS
+        MORETASKS{"More tasks?"}
+        MORETASKS -->|yes| GETNEXT
     end
 
-    subgraph PLAN ["PLAN — Preview Changes"]
-        PLAN_1["az account show"] --> PLAN_2{"Authenticated\nto Azure?"}
-        PLAN_2 -->|no| PLAN_ERR(["❌ Run az login"])
-        PLAN_2 -->|yes| PLAN_3["az deployment group what-if\n--template-file infra/main.bicep\n--parameters parameters.ENV.json"]
-        PLAN_3 --> PLAN_4["Display summary:\nCREATE / MODIFY / DELETE\n+ estimated costs"]
-        PLAN_4 --> PLAN_PAUSE(["⏸ GATE — wait for approval\nbefore running deploy"])
-    end
+    MORETASKS -->|no| RECAP
 
-    subgraph DEPLOY ["DEPLOY — Execute Deploy"]
-        DEP_1["Verify plan approval"] --> DEP_2
-        DEP_2["az group create --name rg-APP-ENV\n--location brazilsouth"] --> DEP_3
-        DEP_3["az deployment group create\n--template-file infra/main.bicep\n--parameters parameters.ENV.json"] --> DEP_4
-        DEP_4["Capture outputs:\nContainer App URL\nSQL Connection String\nKey Vault URI"] --> DEP_5
-        DEP_5["Update documentation\nwith deploy info"]
-        DEP_5 --> DEP_END(["✅ Deploy complete"])
+    subgraph WRAP ["FINALIZATION"]
+        RECAP["morph-spec generate recap FEATURE\n(auto-calls markOutput internally)"] --> VALFEAT
+        VALFEAT["morph-spec validate-feature FEATURE --phase implement"] --> SETDONE
+        SETDONE["morph-spec state set FEATURE status done"] --> ADVANCE
+        ADVANCE["morph-spec phase advance FEATURE"]
     end
 
-    subgraph DESTROY ["DESTROY — Remove Resources"]
-        DES_1(["⚠️ WARNING: irreversible action"]) --> DES_2
-        DES_2["List all resources\nthat will be deleted"] --> DES_3
-        DES_3(["⏸ GATE — require explicit confirmation\n'yes, delete'"]) --> DES_4
-        DES_4["az group delete --name rg-APP-ENV\n--yes --no-wait"]
-        DES_4 --> DES_END(["✅ Resources removed"])
-    end
+    ADVANCE --> END(["✅ Feature complete"])
 ```
 
 ---
 
-## 6. /morph-preflight
+## 6. /morph-status — Flow
 
 ```mermaid
 flowchart TD
-    START(["/morph-preflight azure"]) --> C1
+    START(["/morph-status"]) --> A
+    A["morph-spec state list\n→ StateManager.getSummary() + listFeatures()\n→ reads .morph/state.json"] --> B
+    B["Display: all features, phases, task counts, gates"] --> C
+    C{"Specific feature?"}
+    C -->|yes| D["morph-spec status FEATURE --verbose\n→ reads state + scans feature directory for output files"]
+    C -->|no| E["Suggest next actions"]
+    D --> E
+    E --> END(["✅ Done"])
+```
 
-    subgraph CHECKS ["7 SEQUENTIAL CHECKS"]
-        C1["Check 1 — Package Conflicts\ndotnet restore --verbosity normal\ngrep NU1605 NU1608"] --> R1{"OK?"}
-        R1 -->|✅| C2
-        R1 -->|❌| FIX1["Fix: declare Azure.Identity\nwith explicit version in .csproj"] --> C2
+---
 
-        C2["Check 2 — EF Core Migrations\ndotnet ef migrations has-pending-model-changes\n--project src/Infrastructure --startup-project src/Web"] --> R2{"OK?"}
-        R2 -->|✅| C3
-        R2 -->|❌| FIX2["Fix: dotnet ef migrations add NAME"] --> C3
+## 7. Skill → CLI Commands Reference
+
+### Meta Skills (level-0-meta)
+
+| Skill | CLI Commands Called |
+|---|---|
+| `verification-before-completion` | `morph-spec state get {f}` · `morph-spec validate-feature {f} --phase {p}` · `morph-spec status {f} --verbose` · `morph-spec checkpoint-save {f}` · `morph-spec task done {f} T001` |
+| `brainstorming` | `morph-spec state get {f}` · `morph-spec state mark-output {f} proposal` · `morph-spec state mark-output {f} decisions` |
+| `morph-init` | `morph-spec setup-infra` · `morph-spec install-plugin superpowers` · `morph-spec install-plugin context7` |
+| `morph-checklist` | None (pure checklist) |
+| `simulation-checklist` | None (pure checklist) |
+| `code-review` | None (pure checklist) |
+| `code-review-nextjs` | None (pure checklist) |
+| `tool-usage-guide` | None (reference guide) |
+
+### Workflow Skills (level-1-workflows)
+
+| Skill | CLI Commands Called |
+|---|---|
+| `phase-setup` | `morph-spec state get {f}` · `morph-spec state set {f} phase setup` · `morph-spec state set {f} status in_progress` |
+| `phase-uiux` | `morph-spec state set {f} phase uiux` · `morph-spec state mark-output {f} uiDesignSystem` · `morph-spec state mark-output {f} uiMockups` · `morph-spec state mark-output {f} uiComponents` · `morph-spec state mark-output {f} uiFlows` · `morph-spec approve {f} uiux` |
+| `phase-codebase-analysis` | `morph-spec state mark-output {f} schema-analysis` |
+| `phase-design` | `morph-spec state get {f}` · `morph-spec template render ...` (×3) · `morph-spec state set {f} phase design` · `morph-spec state set {f} costs.estimated N` · `morph-spec state mark-output {f} schema-analysis` · `morph-spec state mark-output {f} spec` · `morph-spec state mark-output {f} contracts` · `morph-spec state mark-output {f} decisions` |
+| `phase-clarify` | `morph-spec state set {f} phase clarify` · `morph-spec state mark-output {f} clarifications` |
+| `phase-tasks` | `morph-spec state get {f}` · `morph-spec state set {f} phase tasks` · `morph-spec state set {f} tasks.total N` · `morph-spec state mark-output {f} tasks` |
+| `phase-implement` | `morph-spec state get {f}` · `morph-spec approval-status {f}` · `morph-spec task next {f}` · `morph-spec task start {f} T00X` · `morph-spec task done {f} T00X` · `morph-spec checkpoint-save {f}` · `morph-spec validate-feature {f} --phase implement` · `morph-spec generate recap {f}` · `morph-spec state set {f} phase implement` · `morph-spec state set {f} status done` · `morph-spec phase advance {f}` |
 
-        C3["Check 3 — Dockerfile\ndocker build --check .\nVerify multi-stage, EXPOSE, ENTRYPOINT"] --> R3{"Applicable\nand OK?"}
-        R3 -->|✅ or N/A| C4
-        R3 -->|❌| FIX3["Fix: correct Dockerfile"] --> C4
+---
 
-        C4["Check 4 — Blazor .NET 10 Assets\ngrep RequiresAspNetWebAssets *.csproj"] --> R4{"OK?"}
-        R4 -->|✅ or N/A| C5
-        R4 -->|❌| FIX4["Fix: add RequiresAspNetWebAssets=true\nto .csproj"] --> C5
+## 8. CLI Command → Internal Implementation
+
+| CLI Command | Handler | Key State-Manager Calls |
+|---|---|---|
+| `state get {f}` | `src/commands/state/state.js` → `getCommand()` | `StateManager.getFeature(f)` |
+| `state set {f} {key} {value}` | `state.js` → `setCommand()` | `StateManager.updateFeature(f, key, value)` |
+| `state list` | `state.js` → `listCommand()` | `StateManager.getSummary()` · `StateManager.listFeatures()` |
+| `state mark-output {f} {type}` | `state.js` → `markOutputCommand()` | `StateManager.markOutput(f, type)` → normalizes type, sets `outputs.{type}.created = true` |
+| `state add-agent {f} {id}` | `state.js` → `addAgentCommand()` | `StateManager.addAgent(f, id)` → pushes to `activeAgents[]` |
+| `state remove-agent {f} {id}` | `state.js` → `removeAgentCommand()` | `StateManager.removeAgent(f, id)` → filters from `activeAgents[]` |
+| `task start {f} {id}` | `src/commands/tasks/task.js` → `taskStartCommand()` | `StateManager.updateTaskStatus(f, id, 'in_progress')` |
+| `task done {f} {ids...}` | `task.js` → `taskDoneCommand()` | `StateManager.updateTaskStatus(f, id, 'completed')` · increments `tasks.completed` |
+| `task next {f}` | `task.js` → `taskNextCommand()` | `StateManager.getNextTask(f)` → scans `taskList[]` for first pending |
+| `checkpoint-save {f}` | `src/commands/project/checkpoint.js` → `checkpointSaveCommand()` | `StateManager.addCheckpoint(f, note)` → appends to `checkpoints[]` |
+| `checkpoint-restore {f}` | `checkpoint.js` → `checkpointRestoreCommand()` | `StateManager.getCheckpoints(f)` + file restoration |
+| `checkpoint-list {f}` | `checkpoint.js` → `checkpointListCommand()` | `StateManager.getCheckpoints(f)` |
+| `approve {f} {gate}` | `src/commands/state/approve.js` → `approveCommand()` | `StateManager.setApprovalGate(f, gate, true, meta)` |
+| `approval-status {f}` | `approve.js` → `approvalStatusCommand()` | `StateManager.getApprovalGate(f, gate)` × 4 · `StateManager.getApprovalHistory(f)` |
+| `phase advance {f}` | `src/commands/state/advance-phase.js` → `advancePhaseCommand()` | `StateManager.getFeature(f)` · `StateManager.updateFeature(f, 'phase', next)` |
+| `validate-phase {f} {phase}` | `src/commands/state/validate-phase.js` | `StateManager.getFeature(f)` · checks `outputs` + `approvals` |
+| `validate-feature {f}` | `src/commands/validation/validate-feature.js` | `StateManager.getFeature(f)` · `runValidation()` from `validation-runner.js` |
+| `generate recap {f}` | inline in `bin/morph-spec.js` → `generateRecap()` | `StateManager.loadState()` · `StateManager.markOutput(f, 'recap')` *(auto, post-write)* |
+| `template render {id} {out} {vars}` | `src/commands/templates/template-render.js` | None — reads template file, renders Handlebars, writes output |
+| `status {f}` | `src/commands/project/status.js` | `StateManager.getFeature(f)` · scans filesystem for outputs |
 
-        C5["Check 5 — Bicep Syntax\naz bicep build --file infra/main.bicep --stdout"] --> R5{"OK?"}
-        R5 -->|✅| C6
-        R5 -->|❌| FIX5["Fix: correct Bicep syntax errors"] --> C6
+---
 
-        C6["Check 6 — Key Vault Config\ngrep KeyVaultUri appsettings*.json\ngrep IsDevelopment Program.cs"] --> R6{"OK?"}
-        R6 -->|✅| C7
-        R6 -->|❌| FIX6["Fix: add KeyVaultUri\nDO NOT gate on IsDevelopment"] --> C7
+## 9. Hook Event Chain
 
-        C7["Check 7 — Connection Strings\ngrep 'Password= Pwd= Secret='\nappsettings*.json excluding Development"] --> R7{"OK?"}
-        R7 -->|✅| SUM
-        R7 -->|⚠️| WARN["Warning: move secrets to Key Vault"] --> SUM
-    end
+Hooks are configured in `.claude/settings.local.json`. All fail-open (catch + exit 0).
 
-    SUM["Display summary\nN passed / N failed / N warnings"] --> RESULT
-
-    RESULT{"Any\nfailures?"} -->|yes| BLOCK(["❌ BLOCKED\nDo not deploy until resolved!"])
-    RESULT -->|no| PASS(["✅ Ready to deploy to Azure"])
+```
+SessionStart ──────────────── inject-morph-context.js
+                               Reads state.json → injects active feature summary
+                               + spec.md up to hooks.specInjectionLimit chars (default: 3000)
+
+UserPromptSubmit ─────────── enrich-prompt.js
+                               Scans prompt for feature names, detects intent
+                               (implement/approve/next-task) → injects hints
+
+PreToolUse (Write|Edit) ──┬─ protect-spec-files.js
+                           │   If gate approved → blocks edits to spec/contracts/tasks
+                           └─ enforce-phase-writes.js
+                               If write target is wrong phase folder → blocks
+                           [permissions.deny in settings.local.json]
+                               Always blocks: .morph/state.json, .morph/framework/**
+
+PostToolUse (Bash) ──────── dispatch.js
+                               Detects: morph-spec task done {f} {id}
+                               If completed % 3 === 0 → triggers:
+                                 morph-spec checkpoint-save {f}
+
+PostToolUseFailure ──────── handle-tool-failure.js
+                               Appends JSON to .morph/logs/tool-failures.log
+
+Stop ────────────────────── validate-completion.js
+                               Checks for incomplete tasks, missing outputs,
+                               pending gates → returns advisory (non-blocking)
+
+PreCompact ─────────────── save-morph-context.js
+                               Snapshots state to .morph/memory/pre-compact-{ts}.json
+
+Notification (idle) ─────── approval-reminder.js
+                               If pending gate → suggests: morph-spec approve {f} {gate}
 ```
 
 ---
 
-## 7. /morph-troubleshoot
-
-```mermaid
-flowchart TD
-    START(["/morph-troubleshoot KEYWORDS"]) --> A
-
-    A["troubleshootCommand(keywords, options)"] --> LISTCAT
+## 10. State-Manager Key Methods
+
+Located in `src/core/state/state-manager.js`.
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `loadState` | `loadState(throwIfMissing?)` | Read `.morph/state.json` → returns parsed object |
+| `saveState` | `saveState(state)` | Write state object to disk |
+| `stateExists` | `stateExists()` | Boolean check for `.morph/state.json` existence |
+| `initState` | `initState(opts)` | Create fresh state.json (v4.0.0 schema) |
+| `getFeature` | `getFeature(name)` | Return single feature object or null |
+| `listFeatures` | `listFeatures()` | Return `[name, feature][]` array |
+| `getSummary` | `getSummary()` | Return project-level metadata (counts, totals) |
+| `updateFeature` | `updateFeature(name, key, value)` | Set `feature[key] = value`, save |
+| `markOutput` | `markOutput(name, type)` | Set `feature.outputs[normalizedType].created = true` |
+| `addAgent` | `addAgent(name, agentId)` | Push to `feature.activeAgents[]` if not present |
+| `removeAgent` | `removeAgent(name, agentId)` | Filter from `feature.activeAgents[]` |
+| `setApprovalGate` | `setApprovalGate(name, gate, approved, meta)` | Set `feature.approvals[gate]` with timestamp + metadata |
+| `getApprovalGate` | `getApprovalGate(name, gate)` | Return gate object or null |
+| `getApprovalHistory` | `getApprovalHistory(name)` | Return `feature.approvalHistory[]` |
+| `addCheckpoint` | `addCheckpoint(name, note)` | Append to `feature.checkpoints[]`, returns checkpoint object |
+| `getCheckpoints` | `getCheckpoints(name)` | Return `feature.checkpoints[]` |
+| `updateTaskStatus` | `updateTaskStatus(name, taskId, status)` | Update task in `taskList[]`, recalculate counters |
+| `getNextTask` | `getNextTask(name)` | Return first task with `status === 'pending'` |
 
-    LISTCAT{"--list-categories?"} -->|yes| CATS["getCategories()\nList: blazor, efcore, azure, auth, deploy"]
-    CATS --> END_CATS(["✅ Categories displayed"])
+---
 
-    LISTCAT -->|no| L1_START
+## 11. Agent Detection — How It Actually Works
 
-    subgraph L1 ["Level 1 — Known Issues Index (Primary)"]
-        L1_START["searchIndex(searchTerms, options)"] --> L1A
-        L1A["Search JSON database\nof known issues"] --> L1B{"Filter\n--category?"}
-        L1B -->|yes| L1C["Filter by category"]
-        L1B -->|no| L1D["Match all keywords"]
-        L1C --> L1RESULT
-        L1D --> L1RESULT["Return matches with score"]
-    end
+> `detect-agents` appears in some skill files as `npx morph-spec detect-agents --json`. This CLI command is **not in bin/morph-spec.js** — the source file never made it to the registered CLI.
 
-    L1RESULT --> CHECK1{"Enough\nresults?"}
-    CHECK1 -->|yes| FORMAT
+The actual flow when agents are needed:
 
-    subgraph L2 ["Level 2 — Grep Standards (Automatic fallback)"]
-        CHECK1 -->|no| L2_START["searchGrep(searchTerms, options)"]
-        L2_START --> L2A["grep framework/standards/*.md"]
-        L2A --> L2B["grep .morph/framework/standards/*.md"]
-        L2B --> L2C["Deduplicate against Level 1 results"]
-        L2C --> L2D["Merge and limit to 10 results"]
-    end
+1. Claude reads `.morph/framework/agents.json` directly (via Read tool)
+2. Claude reads `.morph/framework/standards/STANDARDS.json` for the standards registry
+3. Claude matches the feature description keywords against each agent's `keywords[]` array in agents.json
+4. Matched agents are added to state via `morph-spec state add-agent {f} {agent-id}`
+5. Standards for active agents are loaded from `.morph/framework/standards/{path}` as needed
 
-    L2D --> CHECK2{"Enough\nresults?"}
-    CHECK2 -->|yes| FORMAT
+---
 
-    subgraph L3 ["Level 3 — Web Search (If needed)"]
-        CHECK2 -->|no| L3_START["WebSearch — external sources"]
-        L3_START --> L3A["site:github.com/dotnet/aspnetcore ERROR\nsite:github.com/dotnet/efcore ERROR"]
-        L3_START --> L3B["site:stackoverflow.com blazor ERROR\nsite:stackoverflow.com azure ERROR"]
-        L3_START --> L3C["site:learn.microsoft.com ERROR\nsite:learn.microsoft.com/azure ERROR"]
-        L3A & L3B & L3C --> L3MERGE["Consolidate relevant links"]
-    end
+## 12. Data Flow Diagram — A Single Task Cycle
 
-    L3MERGE --> FORMAT
+```
+Claude reads: 3-tasks/tasks.md           → identifies T003
+CLI:  morph-spec task start f T003       → StateManager.updateTaskStatus('f','T003','in_progress')
+                                           .morph/state.json updated
+
+Claude writes: src/Services/Foo.cs       → [Hook: enforce-phase-writes.js fires]
+                                           Path outside .morph/features/? → passes
+                                           (source files are always allowed)
+
+Claude runs: dotnet test                 → tests pass
+
+CLI:  morph-spec task done f T003        → StateManager.updateTaskStatus('f','T003','completed')
+                                           tasks.completed incremented
+                                           [Hook: dispatch.js fires on Bash PostToolUse]
+                                           completed=3, 3%3===0 → triggers:
+                                           morph-spec checkpoint-save f
+                                           StateManager.addCheckpoint('f', 'Auto #1 at T003')
+```
 
-    subgraph FMT ["Output Formatting"]
-        FORMAT["formatResult(result, verbose)\nRoot cause + Solution + Fix code"] --> FSUM
-        FSUM["formatSummary(stats)\nTotal found per level (L1/L2/L3)"]
-    end
+---
 
-    FSUM --> END(["✅ Results displayed\nin standard format"])
-```
+*morph-spec v4.8.1 by Polymorphism Tech*