v1 → v2 Migration

Guild v2 is a full clean slate: flat command surface, one --rigor knob, cost-aware model tiering, and a new lifecycle structure with dedicated phase verbs. This guide documents every removed/renamed command, the config and flag changes, and the new v2 surfaces you’ll encounter upgrading from v1.

Start here if you’re upgrading. For the complete settings.json key reference, see the Configuration Reference.

TL;DR — the 60-second version

• /guild:guild-x → /guild:x — the : plugin namespace stays (Claude Code requires it); v2 drops the redundant guild- command prefix. The main entry command is /guild:guild [brief].
• Flag soup → --rigor=quick|standard|deep — one knob replaces five tuning flags plus 5 global flags and a universal --dry-run.
• New phase subcommands: init ideate plan build qa ops. The Operations verb is ops.
• /guild:guild-team is removed — team-compose is folded into /guild:plan.
• /guild:guild-diagnose → /guild:fix — verb rename.
• Initiatives are new and opt-in — one-off runs remain first-class.
• No shims that execute. Every removed name prints a redirect and exits non-zero. Redirect stubs live one minor version (v2.0.x) and are deleted at v2.1.0.

1. Command-by-command mapping

The mapping table

Designed-but-unshipped in v1, now placed in v2:

Exact redirect messages

Each removed/renamed name prints one of the following, then exits non-zero and runs nothing.

Generic rename (prefix drop) — applies to wiki, evolve, rollback, stats, audit. Example for /guild:guild-wiki:

/guild:guild-wiki was renamed in Guild v2.

  v2 equivalent:  /guild:wiki <ingest|query|lint>

Guild v2 keeps the : namespace; it drops the redundant `guild` prefix — every command is /guild:<verb>.
Full mapping: MIGRATION.md  (repo root or plugin docs/).

/guild:guild-team (removed outright):

/guild:guild-team was removed in Guild v2 (no direct replacement).

Team composition is now a step inside planning:
  • propose  → run /guild:plan        (team is composed, then approved at the plan gate)
  • show     → /guild:status          (shows the active team)
  • edit     → answer [edit] at the plan/team approval gate
  • --allow-larger → /guild:plan --team-size=N   (prints the cap-6 warning)

Full mapping: MIGRATION.md §2.

/guild:guild-diagnose (verb renamed):

/guild:guild-diagnose was renamed in Guild v2.

  v2 equivalent:  /guild:fix [run-id | "symptom"] [--review=cross]

(`--codex-review` is now `--review=cross`.)
Full mapping: MIGRATION.md §2.

/guild:guild [brief] is renamed/restructured, not removed — it still works. The two visible changes on first run: a surfaced phase-detection prompt, and the deleted tuning flags (--loops, --loop-cap, --codex-cap).

2. Config migration (.guild/settings.json)

v2 config surface: .guild/settings.json (JSON) replaces .guild/config.yml (YAML).

It is the single config file and holds every option. Scaffold it with /guild:config init; inspect the resolved config with /guild:config show.

A back-compat shim in read-guild-config.ts still reads an existing .guild/config.yml, maps the v1 keys, and warns once per run:

warn: .guild/config.yml uses v1 keys (codex_review, auto_approve=spec-and-plan).
      Mapped to v2 (review=cross, auto_approve=[spec,plan]). Update the file to
      silence this — see MIGRATION.md §3.

The shim is mapping-and-warn only — it does not rewrite the file. Once settings.json exists it is authoritative and config.yml is ignored.

Key mapping

Worked example

v1 .guild/config.yml:

loops: all
loop_cap: 16
codex_review: true
codex_cap: 5
auto_approve: spec-and-plan

v2 .guild/settings.json equivalent:

{
  "rigor": "deep",
  "auto_approve": ["spec", "plan"],
  "host": "auto",
  "initiative_default": null,
  "loops": null,
  "loop_cap": 16,
  "codex_cap": 5
}

rigor: "deep" already implies loops=all, loop_cap=16, and review=cross — set it in one knob instead of three. Omit review: when using rigor: deep; the profile expansion already implies cross.

New optional defaults: block (nothing to migrate)

v2 adds an optional top-level defaults: block for project-wide behavior defaults: adversarial, team size/always-include, review workflow, skill policy, soft-gate auto-approve, wiki share-mode, reporting verbosity, auto_learn. See the Configuration Reference for the full key set.

• Absent defaults: ⇒ byte-identical to today. Purely additive; zero-config behavior is unchanged.
• project.yaml is now identity-only (name, slug, label taxonomy). wiki.share_mode moved from project.yaml into defaults.wiki.share_mode in settings.json. Move it if you set it there previously.
• Unknown keys are rejected — defaults.wiki.autopromote: true is rejected always; defaults.adversarial: off is rejected for Guild self-build.

3. Flag migration cheat-sheet

“Give me the old always-loop behavior” → --rigor=deep per invocation, or set rigor: "deep" in settings.json. Note: --rigor=deep also auto-implies --review=cross; the expanded profile is printed before the first gate.

4. Deprecation timeline

The one-version sunset caps the support tail. Documenting stub removal here so v2.1.0 is not itself a surprise.

5. Additive v2.x additions (no breaking change)

models: config block + --model-tier flag (cost-aware tiering)

Both are purely additive — zero-config repos are unchanged.

Precedence (normative): --model-tier CLI flag > per-lane plan override (model_tier:) > settings.json models: block > built-in default.

Full key reference: Configuration Reference models.*.

6. New in v2 (not a migration, but you’ll want these)

• Phase entrypoints + surfaced smart detection — start at any phase; bare /guild:guild proposes a phase and asks before proceeding. Never silent.

• Flat-token command surface (D1/D2) — beyond the prefix-drop, commands are flat /guild:<verb> and sub-verbs are positional arguments, never separate files. Guild skills are model-invoked, never user-typed.

• Full skill internalization (D4) — Guild’s skills are clean-room re-authored and Guild-native, with no runtime dependency on external plugins. Methodology skills (tdd, systematic-debug, worktrees, finish-branch) promoted from fallback to first-class.

• Initiatives (opt-in durable work) — /guild:initiative …. One-off runs remain first-class.

• Cross-host review (--review=cross) + host adapter (--host) — the Claude↔Codex reciprocal review broker.

• /guild:learn (NEW) + cheap-by-default /guild:init (D3) — /guild:init stays cheap. The full understand-everything pipeline is /guild:learn <map|graph|onboard|diff|explain>. Init runs it only under defaults.auto_learn: true or --learn.

• --rigor profile — one three-valued knob (quick|standard|deep) replaces five tuning flags.

• Quality + Operations are full v2 skills — /guild:qa executes E2E/smoke/a11y/perf/integration checks auto-selected from the CodebaseMap. /guild:ops executes release/monitoring/incident/rollback/maintenance runbooks. Command verbs, artifact paths, and gate markers are unchanged from their v1 reserved state; only the behavior behind them is promoted from deferred to shipped.

• --auto-approve asymmetry — --auto-approve collapses soft gates only. Token set: [spec,plan,build,all]. No qa or ops token. A Quality BLOCK→release override is never a soft gate — stays human-gated even under --auto-approve=all. Same asymmetry in Operations: release, destructive, incident, or rollback actions always prompt.

• .guild/ ownership boundary + /guild:audit boundary check — every Guild-owned file lives under the consuming repo’s .guild/. The plugin install directory is static read-only base state. /guild:audit gains a boundary-check section that flags violations.

• Optional .guild/index.sqlite read-through cache — lazy-built, gitignored, fully deletable (rm .guild/index.sqlite is always safe). Disable with index: "off" in settings.json.

7. Self-build / CI caller find-and-replace

For internal scripts and CI that invoked v1 commands:

CI ergonomics: name phases explicitly (/guild:build --auto-approve=…) rather than rely on bare /guild:guild phase detection — detection is interactive by design. A bare /guild:guild reaching a gate in a non-interactive context hard-fails with a clear message rather than implicitly granting autonomy.

FAQ

Why no behavioral shims? v2 is a full clean slate. A print-only redirect stub is documentation, not a behavioral shim: it runs nothing and advances nothing. The one-version sunset caps the support tail.

Where did /guild:guild-team go? Team composition is now a step inside /guild:plan with its own approval gate. Inspect the active team via /guild:status; edit it via the [edit] response at the plan/team gate; raise the cap with /guild:plan --team-size=N.

How do I get the old always-loop behavior? Use --rigor=deep per invocation, or set rigor: "deep" in settings.json. deep = loops=all + cap=16 + --review=cross (auto-implied, profile printed before the first gate).

Did /guild:guild-diagnose just disappear? No — it was renamed to /guild:fix. The diagnose skill is retained internally; the command verb changed because a user wants the thing fixed, not merely diagnosed.

Is /guild:guild itself breaking? The verb still works. Two visible changes: a surfaced phase-detection prompt on bare /guild:guild, and the removal of --loops/--loop-cap/--codex-cap from the CLI (now --rigor + config).

Related

• Configuration Reference — complete settings.json key reference with the full key mapping table.
• Command Reference — the v2 command surface in detail.
• Get Started with Guild — upgrading from v1 or installing fresh.