@polymorphism-tech/morph-spec 4.8.1 → 4.8.4

package/docs/ARCHITECTURE.md

@@ -1,328 +0,0 @@
-# morph-spec Architecture
-
-> System design reference for morph-spec v4.8.1
-
----
-
-## Overview
-
-morph-spec is a CLI tool that scaffolds a spec-driven development workflow on top of Claude Code. It installs a structured set of files into `.morph/` and `.claude/`, then lets the AI orchestrate feature development through well-defined phases with approval gates.
-
-The framework has three main concerns:
-
-1. **State** — tracking features, phases, and outputs in `.morph/state.json`
-2. **Agents** — 38 specialized agents organized in 4 tiers, installed as native Claude Code subagents
-3. **Workflow** — 8 phases from proposal through implementation, enforced via hooks and guards
-
----
-
-## Agent hierarchy
-
-```
-Tier 1 — Orchestrators (3)
-  standards-architect   always active — Chief Architect, enforces standards
-  ai-system-architect   on-demand — multi-agent / AI system design
-  po-pm-advisor         on-demand — requirements, business value
-
-Tier 2 — Domain Leaders (4)
-  dotnet-senior         always active — Backend Squad lead (skipped for non-.NET)
-  infra-architect       always active — Infrastructure Squad Leader (cloud-agnostic)
-  domain-architect      on-demand — DDD analysis and bounded context design
-  ui-designer           on-demand — UI/UX Squad lead
-
-Tier 3 — Specialists (26)
-  Backend (10)          ef-modeler, event-architect, api-designer, nosql-cache-expert,
-                        hangfire-orchestrator, ms-agent-expert,
-                        asaas-financial, clerk-auth, resend-email, ddd-expert
-  Frontend (3)          blazor-builder, nextjs-expert, css-specialist
-  Infrastructure (6)    azure-architect, bicep-architect, devops-engineer,
-                        container-specialist, observability-expert, azure-identity
-  Quality/Cross (7)     testing-specialist, code-analyzer, troubleshooting-expert,
-                        load-testing-expert, documentation-specialist,
-                        migration-specialist, integration-specialist
-
-Tier 4 — Validators (5)
-  security-expert       SQL injection, XSS, hardcoded secrets
-  architecture-expert   DbContext, async/await, DI order
-  packages-validator    NuGet conflicts, .NET 10 compatibility
-  design-system-validator CSS palette, spacing, typography
-  blazor-concurrency-validator DbContext lifecycle, async void, JSInterop
-```
-
-### Agent installation
-
-Tier 1–2 agents are installed to `.claude/agents/morph-{id}.md` with YAML frontmatter:
-
-```yaml
----
-name: morph-standards-architect
-description: Chief Architect...
-model: sonnet
----
-```
-
-Tier 3 domain agents are installed to `.claude/agents/morph-domain-{name}.md` with:
-
-```yaml
----
-model: sonnet
-memory: project
-maxTurns: 20
----
-```
-
-Both sets are updated by `morph-spec update`.
-
-### Agent detection
-
-When a feature is created, Claude reads `agents.json` directly and matches keywords in the feature description against each agent's keyword list. Matched agents are stored in `state.json` under the feature's `activeAgents` array. The active agent set determines which standards are loaded and which validators run.
-
-> Note: Some skill files reference `npx morph-spec detect-agents --json` — this is not a real CLI command. Agent detection is performed by Claude reading `agents.json` inline, not by a subprocess.
-
----
-
-## Phase pipeline
-
-```
-0-proposal → 1-setup → [1.5-uiux] → 2-design → 3-clarify → 4-tasks → 5-implement → [6-sync]
-```
-
-| Phase | ID | Optional | Approval gate | Output directory |
-|-------|-----|----------|--------------|-----------------|
-| Proposal | `proposal` | No | Yes | `0-proposal/` |
-| Setup | `setup` | No | No | — |
-| UI/UX | `uiux` | Yes | Yes | `2-ui/` |
-| Design | `design` | No | Yes | `1-design/` |
-| Clarify | `clarify` | No | No | `1-design/` (updates) |
-| Tasks | `tasks` | No | Yes | `3-tasks/` |
-| Implement | `implement` | No | No | `4-implement/` |
-| Sync | `sync` | Yes | No | `.morph/context/` |
-
-Phase transitions are controlled by the state machine in `src/lib/state/`. Advancing to a phase with an approval gate is blocked until the gate is explicitly passed. `protect-spec-files.js` (hook) guards spec/contracts from edits after the design gate is passed.
-
-Canonical phase definitions live in `framework/phases.json`.
-
----
-
-## File structure
-
-### Framework source (this repo)
-
-```
-framework/
-├── agents.json              # 38 agents definition (v3.2.0)
-├── phases.json              # 8 phase definitions
-├── CLAUDE_runtime.md        # copied to .claude/CLAUDE.md on init
-├── agents/                  # tier 1-2 agent markdown files
-├── hooks/
-│   ├── claude-code/         # 10 Claude Code hook scripts
-│   │   └── shared/          # state-reader, phase-utils, hook-response, stdin-reader
-│   └── git/                 # pre-commit, commit-msg, pre-push
-├── rules/                   # 6 rule files (copied to .claude/rules/)
-├── skills/
-│   ├── README.md
-│   ├── level-0-meta/        # 7 meta skills (brainstorming, code-review, etc.)
-│   │   └── {skill}/
-│   │       ├── SKILL.md     # skill content
-│   │       ├── scripts/     # optional helper scripts
-│   │       └── references/  # optional reference materials
-│   └── level-1-workflows/   # 8 workflow skills (phase-proposal, phase-design, etc.)
-│       └── {skill}/
-│           └── SKILL.md
-├── standards/               # 82 standards, 11 categories
-│   ├── STANDARDS.json       # registry (regenerate: node scripts/generate-standards-registry.js)
-│   ├── core/
-│   ├── backend/
-│   ├── frontend/
-│   ├── infrastructure/
-│   └── integration/
-├── templates/               # Handlebars v2.0 code and IaC templates
-│   ├── infrastructure/      # Bicep, Docker, GitHub Actions
-│   └── ...
-└── workflows/
-    └── configs/             # 10 workflow configs (express, spec-only, zero-touch, fusion, ...)
-```
-
-### Installed into a project (after init)
-
-```
-.morph/
-├── config/config.json       # editable project config
-├── framework/               # READ-ONLY copy from package
-│   ├── agents.json
-│   ├── standards/
-│   └── templates/
-├── context/                 # editable project context
-│   ├── README.md            # loaded at every SessionStart
-│   └── standards.md
-├── features/{feature}/      # feature outputs
-│   ├── 0-proposal/
-│   ├── 1-design/
-│   ├── 2-ui/
-│   ├── 3-tasks/
-│   └── 4-implement/
-├── checkpoints/
-├── logs/tool-failures.log
-└── state.json               # READ-ONLY — gitignored, managed by CLI only
-
-.claude/
-├── CLAUDE.md                # runtime instructions
-├── commands/                # slash command .md files
-├── skills/                  # flat install of framework/skills/
-│   └── {skill-name}/
-│       └── SKILL.md
-├── agents/                  # native subagents
-│   ├── morph-{id}.md        # tier 1-2 (from framework/agents/)
-│   └── morph-domain-{name}.md # tier 3 (from framework/skills/level-2-domains/)
-├── rules/                   # path-scoped rules (from framework/rules/)
-│   ├── morph-workflow.md    # always active (no paths: filter)
-│   ├── csharp-standards.md  # paths: **/*.cs, **/*.csproj
-│   ├── frontend-standards.md # paths: **/*.razor, **/*.css, **/*.scss
-│   ├── nextjs-standards.md  # paths: **/*.tsx, **/*.ts
-│   ├── testing-standards.md # paths: tests/**, **/*.test.*, **/*Tests.cs
-│   └── infrastructure-standards.md # paths: **/*.bicep, **/Dockerfile, ...
-└── settings.local.json      # hooks, permissions.deny, env vars
-```
-
----
-
-## Skills system
-
-Skills are Markdown files that provide Claude Code with domain knowledge and procedures. They are invoked via the `Skill` tool inside Claude Code.
-
-### Directory structure
-
-Each skill lives in its own directory under `framework/skills/{level}/{skill-name}/`:
-
-```
-{skill-name}/
-├── SKILL.md           # required — main content
-├── scripts/           # optional — helper scripts (.mjs)
-└── references/        # optional — reference documents
-```
-
-### Levels
-
-| Level | Directory | Count | Purpose |
-|-------|-----------|-------|---------|
-| 0 | `level-0-meta/` | 7 | Cross-cutting: brainstorming, code review, verification, tool usage |
-| 1 | `level-1-workflows/` | 8 | Phase workflows: phase-proposal, phase-setup, phase-uiux, phase-design, phase-clarify, phase-tasks, phase-implement, phase-sync |
-
-### Installation
-
-`installSkills()` in `src/utils/skills-installer.js` flattens all skills to `.claude/skills/{name}/SKILL.md`. Skills become available as `/{name}` slash commands in Claude Code.
-
----
-
-## Hooks system
-
-10 Claude Code hooks are configured in `.claude/settings.local.json`. All hooks fail-open (catch + exit 0) to prevent blocking Claude Code on errors.
-
-| Event | Hook | Function |
-|-------|------|----------|
-| `SessionStart` | `inject-morph-context.js` | Injects active feature `1-design/spec.md` (configurable char limit) into context |
-| `UserPromptSubmit` | `enrich-prompt.js` | Scans prompt for feature names/intent; injects phase hints and approval syntax |
-| `PreToolUse` (Write\|Edit) | `protect-spec-files.js` | Blocks edits to spec/contracts after design gate is approved |
-| `PreToolUse` (Write\|Edit) | `enforce-phase-writes.js` | Validates write targets are in the correct phase subfolder |
-| `PreToolUse` (Bash) | Prompt-type inline guard (`type: "prompt"`) | Detects destructive shell patterns; no subprocess |
-| `PostToolUse` (Bash) | `dispatch.js` | Auto-checkpoint via `morph-spec checkpoint-save` every 3 completed tasks |
-| `PostToolUseFailure` | `handle-tool-failure.js` | Appends failure details to `.morph/logs/tool-failures.log` |
-| `Stop` | `validate-completion.js` | Warns about incomplete tasks, missing outputs, or pending approval gates |
-| `PreCompact` | `save-morph-context.js` | Snapshots state to `.morph/memory/pre-compact-{ts}.json` |
-| `Notification` | `approval-reminder.js` | Reminds about pending approval gates when Claude is idle |
-
-> Note: `.morph/state.json` and `.morph/framework/**` are protected via native `permissions.deny` in `settings.local.json` — not a hook.
-
-Shared utilities live in `framework/hooks/claude-code/shared/`:
-- `state-reader.js` — reads `.morph/state.json` without subprocess
-- `phase-utils.js` — phase validation helpers
-- `hook-response.js` — standardized hook response formatting
-- `stdin-reader.js` — reads hook event data from stdin
-
-Git hooks (`framework/hooks/git/`): `pre-commit`, `commit-msg` (Conventional Commits), `pre-push` (runs tests).
-
-### Protected files
-
-`permissions.deny` in `settings.local.json` blocks direct edits:
-
-```json
-"permissions": {
-  "deny": [
-    "Write(.morph/state.json)",
-    "Edit(.morph/state.json)",
-    "Write(.morph/framework/**)",
-    "Edit(.morph/framework/**)"
-  ]
-}
-```
-
----
-
-## State machine
-
-`.morph/state.json` tracks the state of all features. It is managed exclusively by the CLI — never edited directly.
-
-```json
-{
-  "version": "4.0.0",
-  "features": {
-    "my-feature": {
-      "phase": "design",
-      "status": "in_progress",
-      "activeAgents": ["dotnet-senior", "ef-modeler", "testing-specialist"],
-      "approvals": {
-        "proposal": true,
-        "design": false,
-        "tasks": false
-      }
-    }
-  }
-}
-```
-
-State auto-migrates from v3.0.0 to v4.0.0 on first CLI access.
-
-Feature outputs (spec.md, contracts.cs, tasks.md, etc.) are tracked by scanning the filesystem at runtime — not stored in state. This keeps state lean and avoids the circular tracking bug of earlier versions.
-
----
-
-## Standards registry
-
-82 standards across 11 categories are registered in `framework/standards/STANDARDS.json`. Each entry has an `id`, `name`, `path`, `scope`, `layer`, and `keywords`.
-
-Regenerate the registry after adding standards:
-
-```bash
-node scripts/generate-standards-registry.js
-```
-
----
-
-## Workflow configs
-
-`framework/workflows/configs/` contains 10 workflow configurations that customize how the phase pipeline runs:
-
-| Config | Description |
-|--------|-------------|
-| `default` | Full pipeline with all phases |
-| `express` | Condensed pipeline for small features |
-| `spec-only` | Proposal through tasks, no implementation |
-| `zero-touch` | Fully automated (maximum trust level) |
-| `fusion` | Combines setup + design into single phase |
-| ... | + 5 more |
-
-Trust levels (`low`, `medium`, `high`, `maximum`) control how many approval gates are enforced automatically vs manually.
-
----
-
-## CLI internals
-
-- **Entry point:** `bin/morph-spec.js` — Commander.js, ~20 framework-internal commands + 3 user commands (`init`, `update`, `doctor`)
-- **Commands:** `src/commands/` — organized into subdirectories by domain (project, state, tasks, validation, templates, trust, mcp)
-- **Libraries:** `src/lib/` — state, validators, templates, agents, detection
-- **Templates engine:** Handlebars v2.0 with helpers (pascalCase, camelCase, snakeCase, kebabCase, pluralize)
-- **Test suite:** `test/` — Node.js built-in test runner, 670+ tests
-
----
-
-*morph-spec v4.8.1 by Polymorphism Tech*