@polymorphism-tech/morph-spec

v4.20.0

Published

2 hours ago

MORPH-SPEC: AI-First development framework with validation pipeline and multi-stack support

morph-spec

Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.

Package: @polymorphism-tech/morph-spec Version: 4.20.0
Requires: Node.js 18+, Claude Code

What it does

morph-spec enforces a spec-first development workflow. When you ask for a feature, it does not write code immediately. It runs through structured phases (proposal, design, tasks) with approval gates before a single line of implementation is generated. Each phase produces traceable output files. Every decision is documented.

It integrates natively with Claude Code: skills become slash commands, agents become native subagents, hooks inject state context automatically, and rules enforce standards based on file paths.

Requirements

Claude Code (latest)
Node.js 18+
npm 9+ or pnpm

Installation

Install the CLI globally:

npm install -g @polymorphism-tech/morph-spec

Then initialize in your project:

morph-spec init

Init options

| Flag | Description | | ------------ | ------------------------------------- | | --force | Overwrite existing installation | | --skip-mcp | Skip MCP configuration prompt | | --path | Target directory (default: cwd) |

After init, open the project in Claude Code. The framework activates automatically via .claude/settings.local.json.

Project structure (after init)

your-project/
├── CLAUDE.md                        # AI instructions for this project
├── .morph/
│   ├── config/
│   │   └── config.json              # Project configuration
│   ├── framework/
│   │   ├── agents.json              # 22 agents in 4 tiers (READ-ONLY)
│   │   ├── standards/               # Coding and architecture standards (READ-ONLY)
│   │   └── templates/               # Code and IaC templates (READ-ONLY)
│   ├── context/                     # Project context (README.md, standards.md)
│   ├── features/                    # Active features
│   │   └── {feature}/
│   │       ├── 0-proposal/          # User story + acceptance criteria
│   │       ├── 1-ui/                # UI/UX design (optional, UI-heavy features)
│   │       ├── 2-design/            # Technical spec, contracts, decisions
│   │       ├── 3-tasks/             # Atomic task list
│   │       └── 4-implement/         # Recap and implementation notes
│   └── state.json                   # READ-ONLY — managed by CLI only
└── .claude/
    ├── commands/                    # Slash commands
    ├── skills/                      # Framework skills (flat .md files)
    ├── agents/                      # Native subagents (22 agents)
    ├── rules/                       # Path-scoped standards rules
    └── settings.local.json          # Hooks configuration (10 hooks)

Phase workflow

Features move through structured phases. Some are optional depending on feature type.

proposal → [uiux] → design → plan → tasks → implement → [sync]

Phases in brackets are optional. uiux applies to UI-heavy features. sync is a post-implementation reconciliation step.

Phase outputs

| Phase | Directory | Key files | | --------- | -------------- | ------------------------------------------------------------- | | Proposal | 0-proposal/ | proposal.md | | UI/UX | 1-ui/ | design-system.md, mockups.md, components.md, flows.md | | Design | 2-design/ | spec.md, contracts.cs, decisions.md | | Plan | 3-plan/ | plan.md | | Tasks | 4-tasks/ | tasks.md | | Implement | 5-implement/ | recap.md |

Approval gates

Design gate — Spec must be approved before moving to Plan.
Plan gate — Plan must be approved before moving to Tasks.
Tasks gate — Task list must be approved before implementation starts.

Check gate status:

morph-spec approval-status {feature}

Slash commands

These commands are available inside Claude Code after init.

| Command | Description | | --------------------------- | --------------------------------------------------------- | | /morph-proposal {feature} | Full spec pipeline (phases 0-4, pauses at approval gates) | | /morph-apply {feature} | Implement approved feature (phase 5) | | /morph-status | Feature status dashboard | | /morph-preflight | Pre-implementation validation |

CLI reference

Project management

morph-spec init                        # Initialize MORPH in current project
morph-spec init --force                # Overwrite existing installation
morph-spec update                      # Update framework files and re-analyze project
morph-spec doctor                      # Check installation health
morph-spec doctor --full               # Full health check (all file verifications)

Feature workflow

morph-spec state list                  # List all features and their states
morph-spec state get {feature}         # Get feature state
morph-spec state set {feature} {key} {value}
morph-spec phase advance {feature}     # Advance to next phase
morph-spec task done {feature}         # Mark current task complete
morph-spec task start {feature}        # Start next task
morph-spec status {feature}            # Feature status dashboard

Validation

morph-spec validate                    # Run all validators
morph-spec validate {validator}        # Run specific validator
morph-spec validate-feature {feature}  # Content-aware feature validation

Agent hierarchy

morph-spec includes 22 agents organized in 4 tiers (2+3+13+4). Tier 1-2 agents are installed as native Claude Code subagents in .claude/agents/. Tier 3 domain agents are installed as .claude/agents/morph-domain-{name}.md.

Tier 1 — Orchestrators (2)

| Agent | Role | Active | | --------------------- | ------------------------------------------------------ | --------- | | standards-architect | Chief Architect — enforces standards across all phases | Always | | ai-system-architect | AI/Agent system design and orchestration | On-demand |

Tier 2 — Domain Leaders (3)

| Agent | Squad | Active | | ------------------ | ------------------------- | --------- | | dotnet-senior | Backend squad lead | Always | | nextjs-expert | Frontend squad lead | Always | | infra-architect | Infrastructure squad lead | Always |

Tier 3 — Specialists (13)

Organized into squads:

Backend (6): ef-modeler, hangfire-orchestrator, ms-agent-expert, supabase-expert, vector-search-expert, morph-spec-architect

Frontend (3): css-specialist, ui-designer, seo-growth-hacker

Integrations (3): asaas-financial, clerk-auth, resend-email

Security (1): security-expert

Tier 4 — Validators (4)

| Agent | Validates | | ------------------------------ | --------------------------------------- | | architecture-expert | Architectural decisions and constraints | | packages-validator | Package versions and compatibility | | design-system-validator | Design system adherence | | nextjs-component-validator | Next.js component structure and naming |

Hooks

10 Claude Code hooks are installed into .claude/settings.local.json across 8 event types:

| Event | Hook | Purpose | | -------------------- | -------------------------- | ----------------------------------------------------------------- | | SessionStart | inject-morph-context.js | Injects active feature spec into context (configurable char max) | | UserPromptSubmit | enrich-prompt.js | Context-aware prompt enrichment, wrong-phase warnings | | PreToolUse | Bash guard (prompt type) | Detects destructive patterns inline via Claude's reasoning | | PreToolUse | protect-spec-files.js | Blocks edits to spec files after approval gate | | PreToolUse | enforce-phase-writes.js | Ensures writes go to the correct phase directory | | PostToolUse | dispatch.js | Triggers auto-checkpoints on task completion | | PostToolUseFailure | handle-tool-failure.js | Logs failures to .morph/logs/tool-failures.log | | Stop | validate-completion.js | Warns about incomplete tasks/missing outputs/pending gates | | PreCompact | save-morph-context.js | Snapshots state to .morph/memory/ before compaction |

Protected files (via permissions.deny):

.morph/state.json — never edited directly, CLI only
.morph/framework/** — read-only framework content

Rules

Path-scoped rules are installed to .claude/rules/ and activate automatically based on file patterns:

| Rule file | Applies to | | ----------------------------- | -------------------------------------------------------- | | morph-workflow.md | Always active — spec-first mandate, phase commands | | csharp-standards.md | **/*.cs, **/*.csproj | | frontend-standards.md | **/*.razor, **/*.css, **/*.scss | | nextjs-standards.md | **/*.tsx, **/*.ts | | testing-standards.md | tests/**, **/*.test.*, **/*.spec.*, **/*Tests.cs | | infrastructure-standards.md | **/*.bicep, **/Dockerfile, **/pipelines/** |

Stack support

| Technology | Support | | ------------------------------------------- | ------------------------------------------------ | | .NET 10 / ASP.NET Core | Full — C# contracts, EF Core, CQRS, Minimal API | | Next.js / React / TypeScript | Full — components, routing, state management | | Supabase | Supported via CLI (local Docker) |

TypeScript strict mode is enforced by default. See .morph/framework/standards/ for all coding standards.

Update

To update the framework files in an existing project:

morph-spec update

This re-syncs .morph/framework/, .claude/skills/, .claude/agents/, .claude/rules/, and CLAUDE.md with the installed package version. Your .morph/config/config.json, .morph/context/, and feature outputs are not touched.

After updating, run morph-spec doctor to confirm the installation is healthy.

Key rules

Never skip phases. Every feature starts with a proposal. No code is written until the design is approved and a task list exists.

Never edit protected files directly:

.morph/state.json — use morph-spec state set
.morph/framework/** — read-only, updated by morph-spec update

Always document decisions. Each feature has a 2-design/decisions.md. Architectural choices go there, not in commit messages.

Checkpoints every 3 tasks. The framework auto-validates architecture compliance, package versions, and security after every third completed task.

Troubleshooting

`morph-spec: command not found`

The installer automatically adds the npm global directory to your PowerShell $PROFILE. Open a new terminal after installing. If it still doesn't work, add it manually:

npm config get prefix
# Add {prefix} to your PATH

`morph-spec doctor` reports issues

Run doctor to see all checks:

morph-spec doctor

Common fixes:

Missing .claude/agents/ — run morph-spec update to reinstall agents
Missing .claude/rules/ — run morph-spec update to reinstall rules
State version mismatch — state auto-migrates on next CLI command; if it fails, back up and re-init
Hooks not firing — confirm .claude/settings.local.json exists and contains the hooks key

EPERM on Windows global install

Windows may block global npm installs without elevated permissions. Options:

Run terminal as Administrator (not recommended long-term)
Change npm global prefix to a user-writable directory:

mkdir %APPDATA%\npm-global
npm config set prefix %APPDATA%\npm-global
:: Add %APPDATA%\npm-global to your PATH
npm install -g @polymorphism-tech/morph-spec

Open a new terminal (the installer adds npm to your PATH automatically)

Hook not triggering on SessionStart

Ensure .claude/settings.local.json is not gitignored in your project. The file must be present for Claude Code to load hooks. If it is missing, re-run morph-spec setup-infra or morph-spec init --force.

Standards

The framework ships 82 registered standards across 11 categories, stored in .morph/framework/standards/STANDARDS.json. Standards are enforced via path-scoped rules installed to .claude/rules/ during morph-spec init.

License

Proprietary — see LICENSE.

Code generated by morph-spec (contracts, templates, implementation output) belongs to you.

morph-spec v4.20.0 by Polymorphism Tech