# morph-spec Cheat Sheet

## Setup

```bash
npm install -g @polymorphism-tech/morph-spec@latest --prefer-online   # install/upgrade globally
morph-spec init                                 # initialize project
morph-spec init --force                         # overwrite existing install
morph-spec init --skip-mcp                      # skip interactive MCP setup
morph-spec setup-infra                          # headless install, no prompts (used by init internally)
morph-spec setup-infra --reinstall              # re-install only stack-aware assets (rules/skills/agents)
morph-spec update                               # sync framework templates/standards to the installed version
morph-spec doctor                               # health check (agents/rules drift, hook config, etc.)
morph-spec --version
```

> `--prefer-online` faz parte do comando canônico: sem ele, o cache local do
> npm segura o packument velho por ~5 min após uma release e o install falha
> com `ETARGET` (o CDN do registry também leva alguns minutos para propagar).

---

## Phase workflow

```
proposal → [uiux] → plan → implement → review
```

`uiux` is optional. Which of the 5 phases actually run for a given feature is also shaped by its **work type** (see below) — a `chore` skips straight to implement, a `hotfix` runs a different pipeline entirely.

| Phase | Folder | Gate |
|-------|--------|------|
| proposal | `0-proposal/` | ✅ Gate 1 |
| uiux *(optional)* | `1-design/` | ✅ |
| plan | `2-plan/` | ✅ Gate 2 |
| implement | `3-implement/` | — (auto-advance between tasks) |
| review | `4-review/` | ✅ Gate 3 |

---

## Slash commands (Claude Code)

| Command | Purpose |
|---------|---------|
| `/morph-proposal {feature}` | Business understanding + plan (Gates 1 and 2). Step 0 routes by work type (`feature`/`bug`/`chore`/`hotfix`) |
| `/morph-hotfix {feature}` | Surgical hotfix ADW (scout → fix → human gate → ship) |
| `/morph-apply {feature}` | Autonomous execution + review (Gate 3) |
| `/morph-status [feature]` | Status of the active (or specified) feature |
| `/morph-archive {feature}` | Archive **without integrating** (legacy feature / cleanup) — normal close is `morph-spec finish --pr\|--merge` |
| `/morph-preflight` | Pre-deploy validation (specs, contracts, tests, infra) |
| `/morph-troubleshoot [error]` | Root-cause diagnosis for .NET/Next.js errors |

---

## CLI — approvals & phase advance

```bash
morph-spec approve {feature} {gate} [--mode auto] [--approver name] [--notes text]
morph-spec advance {feature} [--design]         # approve current gate + scaffold next phase folder in one step
morph-spec approval-status {feature} [--json]
morph-spec unapprove {feature} {gate} [--reason text]   # recovery only
morph-spec finish {feature} --pr|--merge [--push] [--keep] [--force] [--discard-ignored]   # normal close: archive + integrate + teardown
morph-spec archive {feature} [--force] [--no-git]        # archive WITHOUT integrating (legacy feature / cleanup)
```

`finish` is the normal way to close a feature (both the worktree flow and the common flow): it archives (committing the move inside `morph/{feature}`), then integrates — `--merge` merges `--no-ff` into the default branch locally (no push); `--pr` pushes `morph/{feature}` + `gh pr create` (needs `origin` + authenticated `gh`). After a `--merge` the output reports how many commits the default branch is ahead of `origin/{default}` and the exact `git push origin {default}` that publishes them (in every `--merge` output, `--keep` included); `--push` runs that push for you. It then tears down the worktree and releases the port block. `archive` alone is reserved for legacy features (no `morph/{feature}` branch) and cleanup.

---

## CLI — feature birth & work-type routing

Every feature is born with a **work type** that dimensions its pipeline: `feature` (full proposal → [uiux] → plan → implement → review), `bug` (lean), `chore` (fast-track straight to implement), `hotfix` (scout → surgical fix → human Gate 3 always, even under `trust: auto`).

Every feature is also born with an **identity**: `--description` is required (`create` refuses a nameless scaffold without it), `name` defaults to the slug.

```bash
morph-spec create {feature} --type feature|bug|chore|hotfix --description "<what/why>"
morph-spec create {feature} --request "<free text>"       # detector classifies the type AND seeds the description
morph-spec retype {feature} {newType}                     # change type mid-flight (blocked after Gate 3)
```

---

## CLI — state (server-side, timestamped)

```bash
morph-spec score {feature} {task} [score] [--dims "9.5,9,9,9"]  # writes taskScores — {task} must match T<n> and {score} must be a number 0-10
                                                                # a blank/missing score or a dotted taskId is REFUSED (exit 1), never recorded as a fabricated 0
morph-spec gate-decision {feature} {gate} --pause <bool> [--reason] [--signals json]   # writes gateDecisions
```

Never hand-edit `taskScores`/`gateDecisions`/`approvalGates` in `feature.json` — always go through these commands (they collide with the `state-sync` hook otherwise).

---

## CLI — validation

```bash
morph-spec validate [architecture|packages|contrast] [--wcag-aaa]
morph-spec validate-feature {feature} [--phase {phase}] [--json]   # alias: vf
morph-spec verify {feature} [task] [--json] [--skip-tests] [--skip-build]   # deterministic build+test+validator chain, before the LLM judge
```

---

## CLI — DAG

```bash
morph-spec dag {feature} [--json]          # sequential vs parallel dispatch decision (effort-weighted)
morph-spec dag {feature} --mermaid         # emit the tasks.json DAG as a Mermaid flowchart
```

---

## CLI — worktrees (parallel development / fleet)

One feature = one git worktree = one Claude Code instance. Each worktree gets its own deterministic port block (`.morph/worktree.env`) and a regenerable handoff document.

```bash
morph-spec create {feature} --description "<what/why>" --worktree   # birth the feature already isolated in its own worktree
morph-spec worktree setup {feature}        # create worktrees/{feature}/ on branch morph/{feature}
morph-spec worktree link [--all]           # relink shared infra (node_modules[, .claude, .morph/framework])
morph-spec worktree list [--json]          # active feature worktrees with phase/gate status
# Close a worktree feature with `morph-spec finish {feature} --pr|--merge` (see above) — it absorbed `worktree finish`.
morph-spec handoff {feature} [--json] [--here]   # regenerate the handoff doc — resolves the owning tree and writes THERE, safe to run from the root
morph-spec doctor --worktrees [--prune]    # reconcile git's registry × disk × features; --prune also clears a dangling root worktree.path pointer
morph-spec fleet [--json]                  # every active feature (root + worktrees) with phase/gates/ports/handoff/activity
```

---

## CLI — scaffolding & misc

```bash
morph-spec scaffold dotnet {feature} {slice-name} [--dry-run]   # generate a VSA feature slice
morph-spec scaffold nextjs {feature} [--dry-run]                # generate a feature page + components
morph-spec context refresh                                       # rescan project, regenerate .morph/context/README.md
morph-spec mcp setup [name] [--list] [--auto]
morph-spec dashboard [--port 3200]                                # open the inspector dashboard
```

---

## Directory structure

```
.morph/
├── config/config.json           # project config (editable)
├── framework/                    # READ-ONLY
│   ├── agents.json                # 8 domain personas
│   ├── standards/                 # standards registry
│   └── templates/                 # code, IaC, and context templates
├── context/                       # project context (editable)
├── features/{feature}/
│   ├── feature.json                # authoritative, committed
│   ├── handoff.md
│   └── 0-proposal/ 1-design/ 2-plan/ 3-implement/ 4-review/
└── state.json                      # gitignored, derived index — never hand-edited

.claude/
├── commands/                    # slash commands
├── skills/                       # framework skills (SKILL.md per dir)
├── agents/morph-{id}.md           # generated subagents (one per persona, no tiers)
└── settings.local.json            # hooks + permissions.deny
```

---

## Protected files

Never edited directly — go through CLI commands or `morph-spec update` instead:

| Path | Protected by |
|------|-------------|
| `.morph/state.json`, `.morph/framework/**` | `permissions.deny` |
| `tasks.json` plan contract (`title`/`description`/`dependencies`/`effort`/`doneCriteria`/`group`) after Gate 2 | `protect-spec-files` hook (semantic diff) |

---

## 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 v8.37.1 by Polymorphism Tech*