@polymorphism-tech/morph-spec 4.8.1 → 4.8.4

package/docs/COMMAND-FLOWS.md

@@ -1,398 +0,0 @@
-# morph-spec — Framework Flows
-
-> Authoritative reference for how the framework connects: slash commands → skills → CLI → state manager.
-> Version: 4.8.1
-
----
-
-## 1. Mental Model — The 4 Layers
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│  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.   │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-**Hooks** run as side-effects alongside this chain (see Section 9).
-
----
-
-## 2. Slash Command → Skill Map
-
-| 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 |
-
-\* `phase-uiux` only if frontend agents are active.
-
----
-
-## 3. Skill Invocation Chain
-
-```mermaid
-flowchart TD
-    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-proposal — Detailed Flow
-
-```mermaid
-flowchart TD
-    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
-
-    GATE0 -->|approved| PHASE1
-
-    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
-
-    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
-
-    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
-
-    GATE2 -->|approved| PHASE3
-
-    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
-
-    C4 --> PHASE4
-
-    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
-
-    GATE4 --> END(["✅ Planning complete\nRun /morph-apply FEATURE"])
-```
-
----
-
-## 5. /morph-apply — Detailed Flow
-
-```mermaid
-flowchart TD
-    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
-
-    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
-
-    MORETASKS -->|no| RECAP
-
-    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
-
-    ADVANCE --> END(["✅ Feature complete"])
-```
-
----
-
-## 6. /morph-status — Flow
-
-```mermaid
-flowchart TD
-    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"])
-```
-
----
-
-## 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}` |
-
----
-
-## 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 |
-
----
-
-## 9. Hook Event Chain
-
-Hooks are configured in `.claude/settings.local.json`. All fail-open (catch + exit 0).
-
-```
-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}
-```
-
----
-
-## 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'` |
-
----
-
-## 11. Agent Detection — How It Actually Works
-
-> `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.
-
-The actual flow when agents are needed:
-
-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
-
----
-
-## 12. Data Flow Diagram — A Single Task Cycle
-
-```
-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')
-```
-
----
-
-*morph-spec v4.8.1 by Polymorphism Tech*