Migrate to v3

Migrate from v1 to v2 (historical)

This page is kept for history. It describes the v1 to v2 move. If you run v2 today, follow Migrate from v2 to v3 instead.

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

FAST PATH

/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

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.

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.

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.

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.

Compatibility Window And Independent Rollback

Public compatibility shims and explicit v1 normalized event mappings remain available through at least one full stable release after the first stable release containing the converged boundary. They are not removed in that same release.

Rollback is boundary-specific:

• Adapter rollback: restore the previous conformant host adapter or factory binding without changing lifecycle authority.
• Transport rollback: restore a prior transport port or refuse the transition; no host-specific path may bypass lifecycle policy.
• Consumer rollback: restore the previous copied release contract together with its digest pin. Benchmark and website reject mismatched bytes and never import plugin source.

Receipts remain append-only throughout. Removing a compatibility shim requires a later release-bound side-by-side replay, independent adapter and transport rollback proof, preserved receipts, reconciled D8 documentation, and updated consumer pins.