<p align="center">
  <img src="docs/assets/hero.svg" alt="Get Magic Done — Self-improving agent orchestration for Claude Code" width="100%"/>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/get-magic-done-cc"><img src="https://img.shields.io/npm/v/get-magic-done-cc.svg" alt="npm version"/></a>
  <a href="https://github.com/just2majic/Get-Magic-Done/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/get-magic-done-cc.svg" alt="license"/></a>
  <a href="https://github.com/just2majic/Get-Magic-Done/blob/master/CHANGELOG.md"><img src="https://img.shields.io/badge/changelog-v1.8-blue.svg" alt="changelog"/></a>
</p>

# Get Magic Done (GMD)

Self-improving agent orchestration for Claude Code.

```bash
npx get-magic-done-cc@latest
```

<p align="center">
  <img src="docs/assets/installer.svg" alt="GMD installer demo — npx get-magic-done-cc@latest" width="100%"/>
</p>


## Why GMD

- **Codebase Mapper** (v1.7–v1.8) — point GMD at a repo that's too big to read and it produces a current, structural *map*: files, functions, classes, and individual methods across **eight languages** (Java, C#, Go, Python, Rust, TypeScript, C++, and C), plus dependency edges between files. For **Java and C#** it goes deeper, resolving which exact method calls which exact method. Deterministic and reproducible; single-repository scope. [Details below.](#codebase-mapper)
- **Obsidian knowledge vault** (v1.3–v1.6, optional) — sync your planning and knowledge into an Obsidian vault as a typed-edge knowledge graph: atomic notes, reading "trails", automatic clustering, a curator/lint loop, and bi-temporal history. Config-gated, off by default.
- **Self-evolution** — agents detect workflow gaps, author new skills, and validate them via TDD before integration.
- **22 behavioral skills** — brainstorming, TDD, debugging, review, and verification patterns auto-discovered at SessionStart.
- **Model-aware orchestration** — Haiku, Sonnet, and Opus selected per task via a 9-cell profile × complexity routing table.
- **Sequential or parallel milestones** (v1.5.9) — init-time choice. Solo developer? Sequential. Multi-initiative team running 2+ streams on the same codebase? Parallel mode keeps each milestone in its own isolated `.planning/milestones/<slug>/` subtree.
- **One-command installer** — `npx get-magic-done-cc@latest` deploys commands, agents, hooks, skills, and runtime into `~/.claude/`.
- **Update manager** — SessionStart version check plus `/gmd:update` keeps installs current with a single command.

## Model Routing

Every subagent spawn picks its model from a 9-cell table indexed by **task complexity** × **profile**. Pick a profile with `/gmd:set-profile <quality|balanced|budget>`; per-task complexity is set at the dispatch site.

| Profile  | Simple  | Standard | Complex |
| -------- | ------- | -------- | ------- |
| quality  | Sonnet  | Sonnet   | Opus    |
| balanced | Haiku   | Sonnet   | Opus    |
| budget   | Haiku   | Sonnet   | Sonnet  |

Default is `balanced`. Cross-model routing (Codex, Gemini) sits on top of this matrix — see [Cross-Model Routing](#cross-model-routing).

## Codebase Mapper

Point GMD at a codebase that's too big to read and it produces a usable, current *map* of it. Run it on any repo — including before `/gmd:new-project` on a brownfield codebase:

```
/gmd:map-codebase
```

**What you get:**

- **Structural breadth across eight languages** — Java, C#, Go, Python, Rust, TypeScript, C++, and C (C is read with the C++ grammar, which we disclose honestly), on top of the existing JavaScript and Bash support. The map lists files, functions, classes, and individual methods, plus dependency edges between files.
- **Method-level call graphs for Java and C#** — for these two languages the mapper goes deeper: a project-wide symbol table feeds call resolution, so the map shows which exact method calls which exact method. Each call is tagged honestly by how it was determined — exact, file-level, or best-guess — and the mapper never fabricates an answer it can't determine.
- **Deterministic output** — the generated map is byte-for-byte reproducible from the same source.
- **Drift warning** — a pre-commit hook warns when the committed map has fallen out of date with the code.
- **Single-repository scope** — the mapper analyzes one repo at a time.

The mapper was built in two milestones: v1.7 laid the foundation (a structural pass plus a semantic pass, a "C4"-style output schema, code-flavored typed edges, `file:line`-grounded provenance, a graph reviewer, and auto-generated code "trails"). v1.8 made it multi-language and tiered — adding a language is a one-entry-plus-one-module operation.

A companion command, `/gmd:map-review`, runs an on-demand integrity review over the generated map (dangling links, stale `file:line` pointers, claim/evidence mismatches) without re-running the full mapper. It is advisory-only and never blocks.

## Prerequisites

- **Claude Code** — Anthropic's CLI. Install from https://docs.anthropic.com/en/docs/claude-code. Verify:

```bash
claude --version
```

- **Node.js ≥ 18** — matches `package.json` `engines.node` (single source of truth). Verify:

```bash
node --version
```

- **OS** — macOS, Linux, or Windows (tested on Windows 11 + bash).

### Optional components

The installer offers opt-in components, each prerequisite-checked and config-gated (off unless you enable them):

- **Obsidian knowledge vault** — sync planning and knowledge into an Obsidian vault (see [Vault Sync](#vault-sync)). Requires Obsidian.
- **Codebase Mapper** — structural maps plus method-level call graphs (see [Codebase Mapper](#codebase-mapper)). The language grammars it needs ship with the package; no extra setup.
- **Cross-model routing** — route tasks to Codex and/or Gemini (see [Cross-Model Routing](#cross-model-routing)). Requires the respective CLI on your PATH.

## Quick Start

**1. Initialize a project.**

```
/gmd:new-project
```

Claude will prompt you for project name, core value, and tech stack.

**2. Plan the first phase.**

```
/gmd:plan-phase 1
```

Claude will decompose the phase into plans, each with verification steps.

**3. Execute the phase.**

```
/gmd:execute-phase 1
```

Claude will run plans in waves, commit after each, and report results.

### Project lifecycle

```mermaid
flowchart LR
    A["/gmd:new-project"] --> B["/gmd:new-milestone"]
    B --> C["/gmd:plan-phase"]
    C --> D["/gmd:execute-phase"]
    D -->|more phases| C
    D --> E["/gmd:audit-milestone"]
    E -->|gaps found| F["/gmd:plan-milestone-gaps"]
    F --> C
    E -->|passed| G["/gmd:complete-milestone"]
    G -->|next cycle| B
```

The orchestrator drives the flow; each `/gmd:*` command spawns fresh subagents (planner, executor, verifier, optionally critic) so the orchestrator stays lean. Atomic commits land between waves; STATE.md and SUMMARY.md persist context across sessions.

## Organizational Mode (sequential vs parallel)

GMD ships in two organizational modes as an init-time choice (v1.5.9+):

- **Sequential (default)** — one active milestone at a time, planning artifacts at `.planning/` root. Best for solo developers, single-initiative projects, and most teams. This is the recommended starting mode.

- **Parallel (advanced)** — multiple concurrent milestones, each in its own `.planning/milestones/<slug>/` subtree. Best for multi-initiative teams running 2+ feature streams on the same codebase. Opt-in via `organizational_mode: "parallel"` in `config.json`.

```mermaid
flowchart LR
    subgraph S["Sequential (default)"]
        direction TB
        S1[".planning/"]
        S1 --> S2["PROJECT.md"]
        S1 --> S3["REQUIREMENTS.md"]
        S1 --> S4["ROADMAP.md"]
        S1 --> S5["STATE.md"]
        S1 --> S6["phases/"]
    end
    subgraph P["Parallel (opt-in)"]
        direction TB
        P1[".planning/"]
        P1 --> P2["PROJECT.md"]
        P1 --> P3["STATE.md<br/>(current_milestone pointer)"]
        P1 --> P4["milestones/"]
        P4 --> P5["v2.0-redesign/"]
        P5 --> P51["REQUIREMENTS.md<br/>ROADMAP.md<br/>STATE.md<br/>phases/"]
        P4 --> P6["v2.1-perf/"]
        P6 --> P61["REQUIREMENTS.md<br/>ROADMAP.md<br/>STATE.md<br/>phases/"]
    end
```

See [references/organizational-modes.md](references/organizational-modes.md) for the full mode comparison, when each mode fits, cross-milestone reference syntax (`<slug>:phase-<N>`), and migration safety guarantees.

**For existing projects** wanting to convert mode, GMD provides two migration commands:

- `/gmd:migrate-to-parallel <first-milestone-slug>` — always safe; converts root planning artifacts into parallel layout. Supports `--dry-run`.
- `/gmd:migrate-to-sequential` — asymmetric safety: refuses unless ≤1 milestone In Progress (per SPEC D6 hard contract). Supports `--dry-run`.

## Command Reference

### Init

| Command | Description |
| --- | --- |
| `/gmd:new-project` | Initialize a new project with deep context gathering and PROJECT.md |
| `/gmd:new-milestone` | Start a new milestone cycle — update PROJECT.md and route to requirements |
| `/gmd:set-profile` | Switch model profile for GMD agents (quality/balanced/budget) |
| `/gmd:set-vault-root` | Set or change the Obsidian vault root for this project |
| `/gmd:set-cross-model` | Configure cross-model routing matrix and per-component gates |
| `/gmd:settings` | Configure GMD workflow toggles and model profile |
| `/gmd:update` | Update GMD to latest version with changelog display |
| `/gmd:reapply-patches` | Reapply local modifications after a GMD update |
| `/gmd:help` | Show available GMD commands and usage guide |
| `/gmd:join-discord` | Join the GMD Discord community |

### Planning

| Command | Description |
| --- | --- |
| `/gmd:add-phase` | Add phase to end of current milestone in roadmap |
| `/gmd:discuss-phase` | Gather phase context through adaptive questioning before planning |
| `/gmd:insert-phase` | Insert urgent work as decimal phase (e.g., 72.1) between existing phases |
| `/gmd:list-phase-assumptions` | Surface Claude's assumptions about a phase approach before planning |
| `/gmd:plan-milestone-gaps` | Create phases to close all gaps identified by milestone audit |
| `/gmd:plan-phase` | Create detailed phase plan (PLAN.md) with verification loop |
| `/gmd:remove-phase` | Remove a future phase from roadmap and renumber subsequent phases |
| `/gmd:research-phase` | Research how to implement a phase (standalone - usually use /gmd:plan-phase instead) |

### Execution

| Command | Description |
| --- | --- |
| `/gmd:add-tests` | Generate tests for a completed phase based on UAT criteria and implementation |
| `/gmd:add-todo` | Capture idea or task as todo from current conversation context |
| `/gmd:check-integration` | On-demand per-phase cross-phase integration check |
| `/gmd:check-todos` | List pending todos and select one to work on |
| `/gmd:codex-verify` | Delegate code verification to Codex CLI as an independent second-opinion agent |
| `/gmd:debug` | Systematic debugging with persistent state across context resets |
| `/gmd:execute-phase` | Execute all plans in a phase with wave-based parallelization |
| `/gmd:gemini-verify` | Cross-model second-opinion verification via Gemini CLI (tiered timeouts, Sonnet fallback) |
| `/gmd:pause-work` | Create context handoff when pausing work mid-phase |
| `/gmd:quick` | Execute a quick task with GMD guarantees (atomic commits, state tracking) but skip optional agents |
| `/gmd:resolve-gap` | Resolve a detected workflow gap by authoring, testing, and promoting a new skill. User-invoked only. |
| `/gmd:resume-work` | Resume work from previous session with full context restoration |
| `/gmd:test-skill` | Adversarial testing of a skill via subagent comparison |
| `/gmd:validate-phase` | Retroactively audit and fill Nyquist validation gaps for a completed phase |
| `/gmd:verify-work` | Validate built features through conversational UAT |

### Milestone

| Command | Description |
| --- | --- |
| `/gmd:audit-milestone` | Audit milestone completion against original intent before archiving |
| `/gmd:complete-milestone` | Archive completed milestone and prepare for next version |
| `/gmd:list-milestones` | List all milestones grouped by status with active-milestone marker (parallel mode) |
| `/gmd:switch-milestone` | Switch active milestone in parallel mode (pure pointer flip on root STATE.md) |
| `/gmd:migrate-to-parallel` | Migrate `.planning/` from sequential → parallel organizational mode (interactive) |
| `/gmd:migrate-to-sequential` | Migrate `.planning/` from parallel → sequential (asymmetric safety; refuses with >1 In Progress) |

### Maintenance

| Command | Description |
| --- | --- |
| `/gmd:cleanup` | Archive accumulated phase directories from completed milestones |
| `/gmd:health` | Diagnose planning directory health and optionally repair issues |
| `/gmd:map-codebase` | Map a codebase into `.planning/codebase/` — structural maps across 8 languages plus method-level call graphs for Java/C# |
| `/gmd:map-review` | On-demand integrity review of a generated code map (dangling links, stale `file:line`, claim/evidence mismatches); advisory, never blocks |
| `/gmd:progress` | Check project progress, show context, and route to next action (execute or plan) |
| `/gmd:add-directive` | Author a human directive shaping agent reasoning in the Obsidian vault |
| `/gmd:vault-clip` | Clip a web URL into the Obsidian vault as a curator-compatible inbox proposal |

## Critic Protocol (opt-in)

GMD ships an optional `gmd-critic` agent that argues from a perspective
different from the lead at high-signal decision gates (architectural
choices, scope changes, deviation-from-recommendation moments). The
critic returns a JSON envelope (`verdict`, `alternative_argument`,
`missed_concerns`, `escalate_to_human`, `confidence`) and the dispatcher
logs the observation to `.planning/specs/gmd-critic-data/observations.ndjson`.

**Default state in npm-published install: DISABLED**
(`components.critic.enabled: false`). This is deliberate — in a single-
user repo, the global default cannot be the source of corpus growth
(per critic R2 in [`.planning/milestones/v1.5.5-SPEC.md`](.planning/milestones/v1.5.5-SPEC.md)
D6). Lead-machine opt-in is the corpus path.

**To enable on your lead machine:**

1. Open `~/.claude/get-magic-done/config.json` (or `./.claude/get-magic-done/config.json`
   for project-local installs).
2. Set:

   ```json
   {
     "components": {
       "critic": { "enabled": true }
     }
   }
   ```

3. The critic is consulted at named gates in `/gmd:new-milestone`,
   `/gmd:plan-phase`, and `/gmd:discuss-phase` (workflow wiring shipped
   in Phase 51).

**Acknowledgment.** Future telemetry — `CRIT-TELM-02` correlation
routine, `CRIT-TELM-03` `Maps/_Critic-Telemetry.md` aggregator — depends
on opt-in usage. The corpus grows only when the lead opts in. This is
the intended design (per critic R2: in a single-user repo, the global
default cannot be the source of corpus growth), not a bug.

**PII redaction (D8):** the dispatcher reuses TELM-06's
`[A-Za-z0-9_-]{20,}` high-entropy regex on 4 named fields
(`decision_point`, `lead_recommendation`, `critic_alternative`, `notes`)
before NDJSON serialization. No new redaction infrastructure.

**References:**

- Library SoT: [`bin/lib/critic-dispatch.js`](bin/lib/critic-dispatch.js)
  (Plan 50-01; harness-neutral with caller-injected `spawnSubagent`
  primitive per D2).
- Agent definition: [`agents/gmd-critic.md`](agents/gmd-critic.md)
  (Plan 50-02; JSON output contract; same-model default; cross-model
  opt-in per D7).
- NDJSON schema + reciprocal-marker convention:
  [`references/critic-observations-schema.md`](references/critic-observations-schema.md)
  (Plan 50-03).
- Protocol source-of-record:
  [`.planning/specs/gmd-critic-protocol.md`](.planning/specs/gmd-critic-protocol.md).
- Milestone SPEC:
  [`.planning/milestones/v1.5.5-SPEC.md`](.planning/milestones/v1.5.5-SPEC.md)
  (D2 / D6 / D7 / D8 / D11 / D12 — locked principles).

## Cross-Model Routing

GMD v1.5.7 ships a cross-model routing substrate that lets `gmd-executor` and
`gmd-verifier` leverage Codex and Gemini as routable backends alongside Claude
— either substituting Claude per task type (cost / throughput / model
strengths) or running additively for independent second opinions (defense-in-
depth on Stage-2 verification). Per-component gates default OFF (manual-flip-
only critic-gate pattern); the static routing matrix at
`.planning/cross-model.json` controls which task types route where. If the
matrix is missing or unparseable, routing falls back to all-Claude (advisory
failure mode per L6).

### Per-Component Gates

Cross-model is gated by three independent keys in `config.json`:

```json
{
  "components": {
    "cross_model": {
      "shared": {},
      "executor": { "enabled": false },
      "verifier": { "enabled": false }
    }
  }
}
```

`executor.enabled` and `verifier.enabled` are independent (you can opt in to
verifier cross-model substitution without enabling executor cross-model, or
vice versa). Both default to `false` per GATE-02 (manual-flip-only critic-
gate pattern, mirroring v1.5.5 critic gate). The `shared` key defaults to
`{}` and accepts adapter-wide overrides (e.g., `{"gemini_binary": "gemini"}`
to point at an alternative Gemini binary for Antigravity migration
readiness).

**Snapshot semantics:** gate state is snapshotted at phase entry per GATE-03;
per-task lookups read the snapshot, NOT live config. This means flipping a
gate mid-phase has no effect on the current phase — the flip takes effect at
the next phase entry. The `/gmd:set-cross-model` setter surfaces this in its
help text (SETTER-04 Pitfall 11 UX mitigation).

### Matrix Syntax

The static matrix lives at `.planning/cross-model.json`. Each `routing.<task_type>`
value is one of: `"claude"` sentinel (native `Task()`), single qualified
`"<vendor>:<model-id>"` string (substitution), or additive list `["<entry>",
"<entry>", ...]` (additive review with critic adjudication on disagreement):

```json
{
  "version": "1.0",
  "routing": {
    "code_review": ["claude", "codex:gpt-5.5"],
    "data_transformation": "gemini:gemini-3-pro",
    "ui_implementation": "claude:sonnet-4.5"
  },
  "escalation_timeout_seconds": 300,
  "commit_timeout_seconds": 60
}
```

Full schema (qualified model values, additive list semantics, capability-
probe readback, cache semantics) at
[`references/cross-model-routing-matrix.md`](references/cross-model-routing-matrix.md).

### `/gmd:set-cross-model` Walkthrough

The interactive setter (Phase 54 SETTER-01; reuses `/gmd:set-vault-root`
v1.3.4 precedent) is the canonical edit surface for both the matrix and the
per-component gates:

1. **Invoke** `/gmd:set-cross-model`.
2. **Setter shows current state.** Per-component gate state (executor /
   verifier enabled or disabled) and the current matrix routing.
3. **Pick an action.** Options: edit matrix entry / flip executor gate / flip
   verifier gate / quit.
4. **Edit matrix path.** Select task type → pick model. Setter capability-
   probes the requested `vendor:model-id` at edit time (SETTER-03; ≤5s probe
   envelope via `bin/lib/probe-cli.js::existsOnDisk` + `launchProbe`).
   Unknown variant warns; `--force` override permitted for future-model
   preregistration.
5. **Gate flip path.** Setter writes atomically. Help text surfaces snapshot
   semantics: "Gate flips take effect at next phase entry; current phase
   uses snapshot taken at `<timestamp>`."
6. **Validation.** Matrix JSON schema strictly validated; malformed values
   (bare `"codex"` / `"gemini"` without model-id) rejected with example of
   correct form (SETTER-02). Never silent-accept invalid values.
7. **Atomic write.** Setter writes the matrix file atomically (temp-file +
   rename) per the same pattern as other GMD setters.

### Troubleshooting `routed_to ≠ executed_by` Audit Reads

Every cross-model task records a 3-tuple in STATE.md per-task records and
SUMMARY.md per-plan `cross_model_routes:` frontmatter (Phase 58 AUDIT family;
AUDIT-01..04):

| Field | Semantics |
|-------|-----------|
| `routed_to` | Resolved matrix value at task dispatch time (e.g., `codex:gpt-5.5`) |
| `executed_by` | Actual final executor (e.g., `codex:gpt-5.5-2026-04` resolved variant; or `claude` after fallback) |
| `fallback_reason` | `null` if `routed_to == executed_by`; else one of: `codex_appcrash`, `codex_timeout`, `sandbox_violation`, `truncation_detected`, `checklist_failed`, `gate_disabled`, `escalation_timeout_auto_mode`, `commit_barrier_timeout`, `critic_gate_disabled`, `capability_probe_failed` |

**Coverage invariant (AUDIT-04):** for every `routed_to ≠ executed_by`,
`fallback_reason ≠ null`. Mutation-RED on dropping any of the 3 fields
independently. If you see `routed_to ≠ executed_by` with `fallback_reason:
null`, that's an audit bug — file an issue with the failing SUMMARY.md
attached.

**Phase-end gap report.** `VERIFICATION.md` "Cross-Model Coverage" section
aggregates fallback rates by reason per AUDIT-03 (surfaced even when 0
fallbacks — proves the audit ran, not skipped). Use this to detect "I
configured the matrix but everything fell back to Claude" failure modes
(usually a missing CLI capability or a critic-gate-disabled cascade).

**References:**

- Full matrix schema:
  [`references/cross-model-routing-matrix.md`](references/cross-model-routing-matrix.md)
- Setter command:
  [`commands/gmd/set-cross-model.md`](commands/gmd/set-cross-model.md)
- Invariant scaffolding:
  [`references/cross-model-invariants.md`](references/cross-model-invariants.md)
- Adapter dispatch primitives:
  [`references/cross-model-dispatch.md`](references/cross-model-dispatch.md)
- v1.5.7 ship notes: [`CHANGELOG.md`](CHANGELOG.md) `[1.5.7]` entry.

## Vault Sync

GMD's optional Obsidian vault component mirrors planning artifacts into a navigable knowledge graph. Sync via `node bin/gmd-tools.cjs vault-sync --all` (gated by `components.obsidian.enabled` in `~/.claude/get-magic-done/config.json`).

**Backfill is implicit.** `vault-sync --all` walks both active milestone planning content (`.planning/{phases,milestones,*.md}`) and archived milestones (`.planning/milestones/v*-phases/`) in a single pass. There is no separate `--backfill` flag — running `vault-sync --all` against a fresh vault populates the full v1.0 → v1.3.x history alongside active-milestone content; re-running it is idempotent (no duplicates, no epoch bump on unchanged sources).

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| Install state unknown — is GMD installed? | Run `/gmd:health`, or `cat ~/.claude/get-magic-done/VERSION` to confirm the installed version. |
| `/gmd:*` commands don't appear after install | Restart Claude Code — commands load at session start. |
| `npx` serves an old version | Clear the npx cache: `npx clear-npx-cache`, then rerun `npx get-magic-done-cc@latest`. |
| Hook log shows `Cannot find module 'config.js'` | Reinstall: `npx get-magic-done-cc@latest`. |
| Skills show `[disabled]` unexpectedly | Run `/gmd:settings` to review and re-enable, or reinstall if `config.json` is corrupted. |
| Install fails or hooks crash on older Node | Upgrade to Node.js ≥ 18 (see Prerequisites); `node --version` to verify. |
| Non-bash shell on Windows causes path errors | Use bash (tested on Windows 11 + bash per Prerequisites). |

## Migration

GMD v1.5 changed the slash invocation pattern from `/gmd-<skill>` to
`/gmd:<skill>` so Claude Code's `/` autocomplete shows every GMD skill under
the unified `gmd:` namespace. This is a hard cutover — there are no
deprecated `/gmd-<name>` aliases.

If you have personal notes, project memory files, or scripts that reference
the old `/gmd-<skill>` pattern, update them by hand:

- Personal memory at `~/.claude/projects/**/memory/`
- CLAUDE.md / AGENTS.md files mentioning `/gmd-<name>` examples
- Saved chat transcripts or runbooks containing the old pattern
- Custom shell aliases referencing `/gmd-` invocations

The full pre→post rename list, including the 3 skills whose underlying slug
also changed (`add-directive`, `set-vault-root`, `vault-clip`), is in
[CHANGELOG.md](./CHANGELOG.md).

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for the full v1.5 breaking-change notice
and version history.

---

*Built on ideas from [GSD](https://github.com/obra/superpowers).*
