@polymorphism-tech/morph-spec 4.5.0 → 4.7.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,331 @@
+# morph-spec Architecture
+
+> System design reference for morph-spec v4.6.0
+
+---
+
+## 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** — 37 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 (3)
+  dotnet-senior         always active — Backend Squad lead
+  infra-architect       always active — Infrastructure Squad Leader (cloud-agnostic)
+  ui-designer           on-demand — UI/UX Squad lead
+
+Tier 3 — Specialists (27)
+  Backend (10)          ef-modeler, event-architect, api-designer, nosql-cache-expert,
+                        ddd-expert, hangfire-orchestrator, ms-agent-expert,
+                        asaas-financial, clerk-auth, resend-email
+  Frontend (3)          blazor-builder, nextjs-expert, css-specialist
+  Infrastructure (6)    azure-architect, bicep-architect, devops-engineer,
+                        container-specialist, observability-expert, azure-identity
+  Quality/Cross (8)     testing-specialist, code-analyzer, troubleshooting-expert,
+                        load-testing-expert, documentation-specialist,
+                        migration-specialist, integration-specialist, data-modeler
+
+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` and `morph-spec update-agents`.
+
+### Agent detection
+
+When a feature is created, `detect-agents` matches keywords in the feature description against `agents.json` keyword lists. 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.
+
+---
+
+## 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              # 37 agents definition (v3.1.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/         # 11 Claude Code hook scripts
+│   │   └── shared/          # state-reader, phase-utils, hook-response, stdin-reader
+│   └── git/                 # pre-commit, commit-msg, pre-push
+├── rules/                   # 5 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/               # 74 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
+
+.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
+│   ├── csharp-standards.md
+│   ├── frontend-standards.md
+│   ├── testing-standards.md
+│   └── infrastructure-standards.md
+└── 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
+
+11 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` (3000 char max) into context |
+| `UserPromptSubmit` | `protect-spec-files.js` | Guards spec files after design gate approval |
+| `PreToolUse` (Bash) | Prompt-type inline guard | Detects destructive shell patterns in Claude's reasoning |
+| `PreToolUse` (Write/Edit) | `validate-feature-phase.js` | Validates write targets against current phase |
+| `PostToolUse` (Write) | `track-output-creation.js` | Detects when feature output files are created; updates state directly via JSON I/O (no subprocess) |
+| `PostToolUse` (any) | `checkpoint-trigger.js` | Triggers auto-checkpoint every 3 completed tasks |
+| `PostToolUseFailure` | `handle-tool-failure.js` | Appends failure details to `.morph/logs/tool-failures.log` |
+| `Stop` | `session-summary.js` | Writes session summary |
+| `PreCompact` | `compact-context.js` | Preserves critical state before context compaction |
+| `Notification` | `morph-notify.js` | Routes approval gate notifications |
+
+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
+
+74 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
+```
+
+Browse via CLI:
+
+```bash
+morph-spec standards --list
+morph-spec standards --list --category backend
+morph-spec standards --search "async"
+morph-spec standards --show csharp-naming
+```
+
+---
+
+## 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, 110+ commands
+- **Commands:** `src/commands/` — organized into subdirectories by domain
+- **Libraries:** `src/lib/` — state, validators, templates, agents, detection
+- **Templates engine:** Handlebars v2.0 with helpers (pascalCase, camelCase, snakeCase, pluralize)
+- **Test suite:** `test/` — Node.js built-in test runner, 625+ tests
+
+---
+
+*morph-spec v4.6.0 by Polymorphism Tech*

package/docs/CHEATSHEET.md

@@ -0,0 +1,221 @@
+# morph-spec Cheat Sheet
+
+## Setup
+
+```bash
+npm install -g @polymorphism-tech/morph-spec   # install globally
+morph-spec init                                 # initialize project
+morph-spec init --wizard                        # interactive wizard
+morph-spec init --force                         # overwrite existing
+morph-spec update                               # sync framework files
+morph-spec doctor                               # health check
+morph-spec --version
+```
+
+---
+
+## Phase workflow
+
+```
+proposal → setup → [uiux] → design → clarify → tasks → implement → [sync]
+```
+
+Phases in brackets are optional.
+
+| Phase | Directory | Output files | Gate |
+|-------|-----------|--------------|------|
+| proposal | `0-proposal/` | `proposal.md` | ✅ Approval |
+| setup | *(no output)* | context loaded | — |
+| uiux *(optional)* | `2-ui/` | `design-system.md`, `mockups.md`, `components.md`, `flows.md` | ✅ Approval |
+| design | `1-design/` | `spec.md`, `contracts.cs`, `decisions.md` | ✅ Approval |
+| clarify | `1-design/` | spec updated | — |
+| tasks | `3-tasks/` | `tasks.md` | ✅ Approval |
+| implement | `4-implement/` | code + `recap.md` | — |
+| sync *(optional)* | `.morph/context/` | standards updated | — |
+
+---
+
+## Slash commands (Claude Code)
+
+| Command | Description |
+|---------|-------------|
+| `/morph-proposal {feature}` | Full spec pipeline — phases 0–4 with approval gates |
+| `/morph-apply {feature}` | Implement approved feature — phase 5 |
+| `/morph-status` | Project-wide feature status dashboard |
+| `/morph-preflight` | Pre-implementation validation (7 checks) |
+
+---
+
+## CLI — project management
+
+```bash
+morph-spec init [--wizard] [--force] [--skip-detection] [--skip-mcp]
+morph-spec update [--wizard] [--templates] [--standards]
+morph-spec doctor
+morph-spec detect [--verbose]
+morph-spec update-agents                       # refresh .claude/agents/
+```
+
+---
+
+## CLI — feature workflow
+
+```bash
+morph-spec state list                          # all features
+morph-spec state get {feature} [--json]        # feature detail
+morph-spec state show {feature}                # phase + approval status
+morph-spec state set {feature} {key} {value}   # update property
+morph-spec state checkpoint {feature} "note"   # manual checkpoint
+morph-spec phase advance {feature}             # advance to next phase
+morph-spec status {feature} [--json] [--verbose]
+morph-spec diff {feature}                      # spec changes since snapshot
+morph-spec diff-save {feature}                 # save snapshot
+morph-spec rollback {feature} --to {phase}     # revert to phase
+morph-spec task done {feature}                 # mark task complete
+morph-spec task start {feature}                # start next task
+morph-spec task next {feature}                 # preview next task
+```
+
+---
+
+## CLI — validation
+
+```bash
+morph-spec validate                            # all validators
+morph-spec validate architecture
+morph-spec validate packages
+morph-spec validate contrast [--wcag-aaa]
+morph-spec validate-blazor [path]
+morph-spec validate-blazor-state [path]
+morph-spec analyze-blazor-concurrency [path]
+morph-spec validate-css [path]
+morph-spec validate-feature {feature} [--phase {phase}] [--json]
+```
+
+---
+
+## CLI — standards
+
+```bash
+morph-spec standards --list
+morph-spec standards --list --category {name}  # categories: core, backend, frontend, infra, ...
+morph-spec standards --search {query}
+morph-spec standards --show {id}
+morph-spec standards --json
+```
+
+---
+
+## CLI — utilities
+
+```bash
+morph-spec cost {bicep-file}                   # Azure cost estimate
+morph-spec cost {bicep-file} --verbose
+morph-spec cost {bicep-file} --strict          # exit 1 if over limit
+morph-spec troubleshoot {keywords}
+morph-spec troubleshoot --category {name}
+morph-spec session-summary {feature}
+```
+
+---
+
+## State — mark-output
+
+```bash
+morph-spec state mark-output {feature} proposal
+morph-spec state mark-output {feature} spec
+morph-spec state mark-output {feature} contracts
+morph-spec state mark-output {feature} decisions
+morph-spec state mark-output {feature} tasks
+morph-spec state mark-output {feature} recap
+
+# UI outputs (camelCase or kebab-case both work)
+morph-spec state mark-output {feature} uiDesignSystem
+morph-spec state mark-output {feature} uiMockups
+morph-spec state mark-output {feature} uiComponents
+morph-spec state mark-output {feature} uiFlows
+```
+
+---
+
+## State — agents
+
+```bash
+morph-spec state add-agent {feature} {agent-id}
+morph-spec state remove-agent {feature} {agent-id}
+morph-spec detect-agents "{description}"          # detect agents for request
+morph-spec detect-agents --json "{description}"   # with standards
+morph-spec detect-agents --ids-only "{description}"
+```
+
+---
+
+## Checkpoints
+
+```bash
+morph-spec checkpoint-save {feature}
+morph-spec checkpoint-restore {feature}
+morph-spec checkpoint-list {feature}
+```
+
+---
+
+## Directory structure
+
+```
+.morph/
+├── config/
+│   └── config.json               # project config (editable)
+├── framework/                    # READ-ONLY
+│   ├── agents.json               # 37 agents, 4 tiers
+│   ├── standards/                # 74 standards across 11 categories
+│   └── templates/                # code and IaC templates
+├── context/                      # project context (editable)
+│   ├── README.md
+│   └── standards.md
+├── features/
+│   └── {feature}/
+│       ├── 0-proposal/proposal.md
+│       ├── 1-design/spec.md, contracts.cs, decisions.md
+│       ├── 2-ui/design-system.md, mockups.md, components.md, flows.md
+│       ├── 3-tasks/tasks.md
+│       └── 4-implement/recap.md
+├── checkpoints/
+├── logs/
+└── state.json                    # READ-ONLY — CLI managed
+
+.claude/
+├── commands/                     # slash commands
+├── skills/                       # framework skills (SKILL.md per dir)
+├── agents/                       # native subagents (37)
+│   ├── morph-{id}.md             # tier 1-2 agents
+│   └── morph-domain-{name}.md   # tier 3 domain agents
+├── rules/                        # path-scoped rules (5 files)
+└── settings.local.json           # hooks (11)
+```
+
+---
+
+## Protected files
+
+These files are never edited directly. Use CLI commands or `morph-spec update` instead:
+
+| Path | Protected by |
+|------|-------------|
+| `.morph/state.json` | `permissions.deny` |
+| `.morph/framework/**` | `permissions.deny` |
+| Approved spec/contracts | `protect-spec-files.js` hook |
+
+---
+
+## Links
+
+- [QUICKSTART.md](QUICKSTART.md) — step-by-step guide
+- [ARCHITECTURE.md](ARCHITECTURE.md) — system design
+- [CHANGELOG.md](../CHANGELOG.md) — release history
+- [npm](https://www.npmjs.com/package/@polymorphism-tech/morph-spec)
+- support@polymorphism.com.br
+
+---
+
+*morph-spec v4.6.0 by Polymorphism Tech*