# morph-spec Quick Start ## Install ```bash npm install -g @polymorphism-tech/morph-spec@latest --prefer-online ``` > The installer automatically configures your PowerShell PATH on Windows. If `morph-spec` is not found, open a new terminal window. --- ## Initialize a project Navigate to your project root and run: ```bash morph-spec init ``` `init` does the following: - Auto-detects your stack (.NET, Next.js, Node.js, monorepo) - Creates `.morph/` with framework files, standards, and templates - Creates `.morph/context/` with inferred project context - Installs `.claude/skills/`, `.claude/agents/`, `.claude/rules/` - Writes `.claude/settings.local.json` with the fail-open Claude Code hooks (see `docs/ARCHITECTURE.md`) - Copies `CLAUDE.md` with runtime instructions Verify the installation: ```bash morph-spec doctor ``` --- ## Your first feature Open your project in Claude Code and run: ``` /morph-proposal my-feature ``` Replace `my-feature` with a short kebab-case name for your feature (e.g., `user-notifications`, `payment-flow`). The proposal pipeline runs the `proposal` and `plan` phases (plus the optional `uiux` phase), with an approval gate at each: ### Proposal (Gate 1) Claude analyzes your request, detects the relevant stack and standards, and produces `0-proposal/proposal.md`. You review it and approve (or request changes). ### UI/UX — optional (Gate) Only runs for UI-heavy features. Claude generates, under `1-design/`: - `design-system.md` — colors, typography, spacing - `mockups.md` — ASCII wireframes - `components.md` — component specs - `flows.md` — user flows and edge cases You approve the UI design before moving on. ### Plan (Gate 2) Claude produces, under `2-plan/`: - `spec.md` — full requirements, use cases, validations - `mandate.md` — the implementation contract (stack defaults, forbidden patterns) - `tasks.json` — ordered task breakdown (`T001`, `T002`, …) - `decisions.md` — architectural decision records (optional) Claude identifies ambiguities in the spec and resolves them with you before finalizing. You review and approve the spec + mandate + task list together. At this point, planning is complete: ``` ✅ Planning complete — run /morph-apply my-feature to implement ``` --- ## Implement ``` /morph-apply my-feature ``` Claude reads `spec.md`, `mandate.md`, and `tasks.json`, then implements task by task with auto-advance (no pause between tasks unless there's a blocking ambiguity): - Records task progress in `tasks.json`, writing the mutable `status`/`outputs`/`notes` fields - Runs the validators relevant to your stack after each task (e.g. `architecture`/`packages`/`contract-compliance` for .NET, `nextjs-component`/`css`/`design-system` for Next.js) via `morph-spec verify` - Applies `morph-eval` after each task — a score below 9 triggers an autonomous correction loop, not a pause - Generates `3-implement/recap.md` on completion, then Gate 3 review (`4-review/`) --- ## During development Check feature state: ```bash morph-spec status my-feature ``` Approve the current gate and scaffold the next phase folder in one step: ```bash morph-spec advance my-feature ``` Task progress is recorded in `tasks.json` — Claude writes the mutable `status`/`outputs`/`notes` fields directly, and there is no separate CLI command for marking a task done. Run validators at any time: ```bash morph-spec validate # all validators morph-spec validate architecture # specific validator morph-spec validate packages ``` Run the deterministic verification chain (build + tests + validators) before trusting an LLM judge score: ```bash morph-spec verify my-feature # whole feature morph-spec verify my-feature T001 # scoped to one task ``` --- ## Work-type routing Not every change needs the full pipeline walked above. Every feature is born with a **work type** that dimensions its pipeline: Every feature is also born with an **identity** — a `--description` (the one field a human must supply; `create` refuses a nameless scaffold without it) and a `name` (defaults to the slug): ```bash # full: proposal → [uiux] → plan → implement → review morph-spec create my-feature --type feature --description "what & why" # bug: lean proposal/plan morph-spec create my-fix --type bug --description "what broke" # chore: skips straight to implement (Gates 1/2 stamped by policy) morph-spec create my-chore --type chore --description "the tidy-up" # hotfix: scout → surgical fix → test loop; Gate 3 always pauses for a human morph-spec create my-hotfix --type hotfix --description "the incident" ``` You can also let the deterministic detector classify a free-text request instead of picking a type by hand (`--request` doubles as the description): ```bash morph-spec create my-feature --request "produção caiu, corrigir urgente" ``` Change the type later if it turns out to be wrong (blocked after Gate 3): ```bash morph-spec retype my-feature hotfix --reason "escalated to production incident" ``` Production incidents run through the dedicated `/morph-hotfix my-feature` slash command instead of `/morph-proposal`. --- ## Parallel development with worktrees Independent features can be developed in parallel, each isolated in its own git worktree — one feature, one worktree, one Claude Code instance: ```bash morph-spec create my-feature --description "what & why" --worktree # birth the feature already isolated # or, for an existing feature: morph-spec worktree setup my-feature # creates worktrees/my-feature/ on branch morph/my-feature ``` Open the new worktree directory in its own Claude Code instance and work normally — a SessionStart hook injects the worktree's feature identity into context automatically. When the feature is done (Gate 3 approved), close it in one step: ```bash morph-spec finish my-feature --merge # archive + merge --no-ff into the default branch (local), tear down the worktree # or, to open a PR instead of merging locally: morph-spec finish my-feature --pr # archive + push morph/my-feature + gh pr create (keeps the branch the PR needs) ``` `finish` archives the feature (committing the move inside `morph/my-feature`) *and* integrates *and* tears down the worktree in one step — it replaces the old `worktree finish` + separate `archive`. The same command closes features developed **without** a worktree (they're born on `morph/{feature}` too). List every active worktree with its phase and gate status: ```bash morph-spec worktree list ``` --- ## Multiple features You can have multiple features in progress simultaneously. Each has its own directory under `.morph/features/`, with its own committed `feature.json`: ``` .morph/features/ ├── user-notifications/ │ ├── feature.json │ ├── 0-proposal/ │ └── 2-plan/ └── payment-flow/ ├── feature.json └── 0-proposal/ ``` See every active feature — root and worktrees — with phase, gates, and activity: ```bash morph-spec fleet ``` --- ## Keeping up to date When a new version of `@polymorphism-tech/morph-spec` is published: ```bash # Update the CLI (--prefer-online bypasses the ~5 min local packument cache) npm install -g @polymorphism-tech/morph-spec@latest --prefer-online # Update framework files in your project morph-spec update # Verify morph-spec doctor ``` `morph-spec update` re-syncs `.morph/framework/`, `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, and `CLAUDE.md`. It does not touch your config, context, or feature outputs. --- ## Tips **Use `/morph-proposal` even for small features.** The proposal phase catches scope creep, identifies the right agents, and generates contracts early — before implementation makes it expensive to change direction. **Approve explicitly at each gate.** The design gate exists to prevent implementing the wrong thing. If something in `spec.md` or `contracts.cs` looks off, say so before approving. **ADRs belong in `decisions.md`.** When Claude makes an architectural choice, it documents it there. Read it after Design completes. Decisions drive the validators that run during implementation. **`morph-spec doctor` is your first debugging step.** If something is behaving unexpectedly, doctor will surface version mismatches, missing files, and hook configuration issues. --- ## Next steps - [CHEATSHEET.md](CHEATSHEET.md) — command reference - [ARCHITECTURE.md](ARCHITECTURE.md) — system design and agent hierarchy - [CHANGELOG.md](../CHANGELOG.md) — release history - `.morph/framework/standards/` — all coding and architecture standards --- *morph-spec v8.37.1 by Polymorphism Tech*