Why no behavioral shims?

v2 is a full clean slate. Redirect stubs were deleted in v2.0, there is no v2.1 sunset window. An unknown subcommand now prints usage help only.

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).

Migrate from v1 to v2, Guild Stack

Guild Stack v2 is the clean command surface for the gated specialist workflow: six phase verbs, one --rigor profile, .guild/settings.json, opt-in initiatives, host-adapted execution, and evidence under .guild/.

v1 to v2split_migration_before_after

Before

nested commandslegacy names
config.ymllegacy settings
claimed supportlabel-led state

After

flat verbsone command surface
settings.jsonclosed-key config
receipt-backed stateverified promotion

v1's nested command names and config.yml become v2's flat verbs and settings.json.

Nested command names (guild-team, guild-wiki, guild-evolve...), .guild/config.yml, and host assumptions baked into copy.

Flat /guild:<verb> commands, one .guild/settings.json with closed-key validation, and 16 canonical hosts with receipt-backed Support labels.

FAST PATH

Step	Do this	Proof or safety check
1	Run `/guild:migrate`	Default mode is dry-run; it writes a migration report and does not convert live state.
2	Read the report	Confirm whether the tree is v1, v2, mixed, corrupt, or empty.
3	Replace v1 command names	Use the command panel below; bare `/guild` is not a v2 command.
4	Convert config	Move `.guild/config.yml` into `.guild/settings.json`; unknown keys are rejected.
5	Recheck hosts	Use current Support labels and `/hosts`, not v1 assumptions.
6	Migrate only when ready	Run `/guild:migrate --mode=migrate` for the snapshot-first conversion.

/guild:migrate

Default /guild:migrate is a dry run. It detects the current .guild/ shape, prints the conversion plan, and writes only the migration report. Use /guild:migrate --mode=migrate only after you are ready for the snapshot-first conversion.

What Changed Conceptually

v1 exposed a long linear spine. v2 keeps that work, but organizes it as one state machine with six phases:

init -> ideate -> plan -> build -> qa -> ops

The linear entrypoint remains /guild:guild [brief]; it walks the lifecycle and surfaces gates as it goes. Phase entrypoints are /guild:init, /guild:ideate, /guild:plan, /guild:build, /guild:qa, and /guild:ops. Bare /guild is not a command.

Initiatives are opt-in. A one-off run is still first-class. Guild Stack asks before attaching a run to an initiative, and D8 initiative closure keeps three separate legs: execution verified, release readiness resolved, and documentation sync resolved.

Command Migration Panel

v1 command	v2 replacement	What changed
`/guild:guild [brief]` with loop/review tuning flags	`/guild:guild [brief]` plus phase verbs	main entry remains; phase detection and gates are surfaced
`/guild:guild-team propose`	`/guild:plan`	team composition moved inside Planning
`/guild:guild-team show`	`/guild:status`	status shows active team/run state
`/guild:guild-team edit`	edit at the plan/team gate	editing is an approval-gate response
`/guild:guild-team --allow-larger`	`/guild:plan --team-size=N`	larger teams are explicit
`/guild:guild-wiki ingest	query	lint`
`/guild:guild-evolve`	`/guild:evolve`	redundant command prefix dropped
`/guild:guild-rollback`	`/guild:rollback`	redundant command prefix dropped
`/guild:guild-stats`	`/guild:stats`	redundant command prefix dropped
`/guild:guild-audit`	`/guild:audit`	redundant command prefix dropped
`/guild:guild-diagnose`	`/guild:fix`	verb renamed; diagnose skill remains internal
`/guild:guild-init` design-era name	`/guild:init`	phase command
`/guild:guild-initiative ...` design-era name	`/guild:initiative ...`	opt-in initiative command

Removed names do not execute work in v2.0. Unknown subcommands print usage help and exit non-zero.

Flag Migration Panel

Use --rigor=quick|standard|deep for the normal upgrade path. It expands the common loop, cap, and review posture and prints the expanded profile before the first gate.

v1 flag	v2 equivalent
`--loops=<...>`	still accepted; prefer `--rigor` or `settings.json` `loops`
`--loop-cap=N`	still accepted; persistent key is `loop_cap`
`--codex-cap=N`	still accepted; persistent key is `codex_cap`
`--codex-review`	`--review=cross`
`--auto-approve=spec-and-plan`	`--auto-approve=spec,plan`
`--auto-approve=implementation`	`--auto-approve=build`
`--auto-approve=all`	still accepted; hard-set approvals still ask
`--restart` as the first argument	`/guild:resume --restart`
`--deep-scan` on init	`--learn` or `defaults.auto_learn: true`

Config Migration Panel

v2 uses one config file:

.guild/settings.json

The v1 .guild/config.yml reader was removed in v2.0. If config.yml is still present, run /guild:migrate; do not assume runtime reads it.

v1 config	v2 config	Notes
`loops:`	`loops:` or `rigor:`	prefer `rigor`; `loops` is a power-user override
`loop_cap:`	`loop_cap:`	same setting name
`codex_cap:`	`codex_cap:`	same setting name
`codex_review: true`	`review: "cross"`	cross-host review posture
`codex_review: false`	`review: "local"`	same-host/local posture
`auto_approve: none`	`auto_approve: []`	no soft gates pre-cleared
`auto_approve: spec-and-plan`	`auto_approve: ["spec", "plan"]`	split token list
`auto_approve: implementation`	`auto_approve: ["build"]`	build token
`auto_approve: all`	`auto_approve: ["all"]`	hard-set approvals still ask
`defaults.agent_team: true`	`agent_mode: "team"`	top-level key
`defaults.agent_team: false`	`agent_mode: "subagent"`	top-level key
absent team default	`agent_mode: "auto"`	default resolver behavior

Unknown keys are rejected by validation. No config key turns wiki promotion into an automatic path; knowledge promotion remains human-gated.

Host Migration Panel

Do not carry v1 host assumptions forward. v2 uses 16 canonical host targets through one adapter contract, but hosts do not all expose identical runtime behavior. The same lifecycle, artifacts, gates, and receipts are the goal; host capability gaps degrade with an observable on-disk signal.

Support label	Meaning
Supported	committed verification receipt exists
Supported (beta)	installable target exists; operator-box receipt is pending
Supported (app)	app surface uses a degraded bootstrap or enqueue path
Supported (connector)	connector path with serial/enqueue behavior and approval needs

The Support label is presentation language. Shipped reality still comes from the evidence-derived public state and committed receipts. Recheck current host claims on Host support, especially for app and connector surfaces.

Roster Migration Panel (v2.2)

The v2.2 roster change, shipped on the beta (next) channel, replaces the host-registered specialist roster with two registered machinery agents (advisor, developer) plus 15 read-only domain specialist type templates at templates/specialists/<role>.md. A domain specialist now joins a team as a project instance under .guild/agents/, minted deterministically from the template library. Groups, default tiers, and trigger boundaries are unchanged.

Existing projects with team files that still point at shipped domain agents (definition_source: shipped entries) are fixed with one command:

npx tsx <plugin>/scripts/roster-resolve.ts migrate-team-roster --cwd .

It mints the missing instances and re-points the team entries; machinery entries are untouched. Re-composing the phase team achieves the same result. Optionally, mint <role> --host-native also projects an instance into .claude/agents/ for Claude host-native routing; the projection is marker-stamped and never clobbers a hand-authored file.

Knowledge, Quality, And Operations

The canonical durable knowledge store is .guild/wiki/**. The KnowledgeGraph, knowledge-links, recall projections, and optional .guild/index.sqlite are derived and rebuildable. Learning writes proposals and candidates. It does not promote wiki pages, decisions, skills, agents, or policy by itself.

/guild:qa and /guild:ops are shipped v2 phase entrypoints, not reserved notices. Quality computes release readiness from discovered evidence. Operations executes runbook classes such as release, monitoring, incident, rollback, and maintenance. Incident and rollback are never autonomous, and destructive, network, and spend steps always ask.

Verification checklist

A migration is not proven by renamed commands alone. Before retiring the v1 path:

Keep the dry-run migration report and the pre-migration snapshot.
Validate .guild/settings.json and confirm each migrated key has the intended value.
Replace removed command names and test the current command surface.
Recheck the selected host against current support evidence and capability limits.
Complete one bounded project run that references an approved spec, team, and plan, then inspect its handoff, review, verification, and trace receipts.
Keep the rollback snapshot until the verified run and its docs or support claims have been reviewed.

Source Anchors

This page is anchored to docs/v2/lifecycle.md, docs/v2/knowledge-memory.md, docs/v2/host-adversarial-adaptability.md, docs/v2/config-surfaces.md, docs/v2/distribution.md, docs/v2/host-adapter-migration-spec.md, and docs/v2/architecture/modules/migrations.md.

Page evidence and guidance