mikeparcewski/wicked-garden / skills/archetype
wicked-garden-archetype
Verifiedv11 work-shape archetype runner. When a prompt has been routed to one of the archetypes (triage, explore, specify, decide, ship, review, incident, build, migrate, modernize), this skill is the entry point. It picks the right per-archetype playbook from refs/ and executes the phase shape declared in `.claude-plugin/archetypes.json`. Use when: a `<wg archetype="X">` or `<wg archetypes>` system-reminder tag appears, an explicit "let's run the X archetype" request, or a direct per-archetype ask — "triage this prompt", "review this PR / artifact", "build this feature", "decide between these options", "explore this problem", "handle this incident", "run this migration", "modernize / port this legacy app", "ship this release", "write acceptance criteria" (invoke with archetype=<name> plus the user's args — see the Direct invocation table).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.0 KB |
| refs/build.md | markdown | 7.5 KB |
| refs/decide.md | markdown | 6.1 KB |
| refs/explore.md | markdown | 2.3 KB |
| refs/incident.md | markdown | 8.2 KB |
| refs/migrate.md | markdown | 9.7 KB |
| refs/modernize.md | markdown | 11.6 KB |
| refs/review.md | markdown | 9.7 KB |
| refs/ship.md | markdown | 6.1 KB |
| refs/specify.md | markdown | 5.8 KB |
| refs/triage.md | markdown | 2.7 KB |
refs/migrate.md
View on GitHub# migrate — expand / backfill / cutover / contract
For shape changes that require both forward and rollback proof. Schema
migrations, data backfills, breaking API rollouts. Uses the standard
**expand-contract** pattern: add the new shape, make both work, switch
readers, switch writers, remove the old shape.
## Phase shape
| Phase | Goal |
|----------|-------------------------------------------------------|
| plan | Document the shape change. Define rollback contract. |
| expand | Add the new shape. **Do not remove the old shape.** |
| backfill | Populate the new shape from the old. Idempotent. |
| cutover | Switch readers/writers. **Hard gate** — staged. |
| contract | Remove the old shape. Only after cutover has soaked. |
## Produces
- **Shape change**: the new schema / API / data layout.
- **Rollback proof**: an executable rollback path. Tested in staging
before cutover.
The cutover gate **re-derives** these through the garden's in-process gate engine (`scripts/qe/vault_gate.py` → `scripts/loom/`, which shells `wicked-vault cross-check`): the rollback drill is re-run and the
shape-change post-condition re-checked, never trusting a self-asserted
"rolled back fine". This is the original evidence-vault use case — for a
migration the load-bearing honesty move is **no cutover without a
re-derivable rollback proof**. The gate engine ships inside wicked-garden; wicked-vault (the evidence backend) is the one **required** peer (installed by the `wicked-garden-core` skill's `setup` action); if the engine cannot resolve — or the vault behind it is absent — the gate **fails closed** (`gate: "unavailable"`, `satisfied: false`) rather than
self-asserting a PASS. Because `cutover` is a HARD gate, the gate also
demands an **independent attestation**: an evaluator who is **not** the
migrator confirms the rollback proof and shape change are adequate
(recorded via `wicked-vault:analyze-evidence`), and the gate fails closed
on a self-grade.
## HITL
`hard:cutover-gate` — cutover is a hard gate. Don't cutover without
explicit user approval AND a green pre-cutover checklist (rollback
tested, backfill complete, dual-read working).
## Ground in the repo's method first
Before you plan, check for **wicked-understanding** repo playbooks (the opt-in
"how to work in THIS repo" layer). A migration lives or dies on repo-specific
wiring — where readers/writers are switched, how schema/config is loaded, the
deploy/rollback command. If its skills are present — `add-domain` / `add-feature`
/ `scaffold`, or the routing block in `AGENTS.md` / `CLAUDE.md` — **load the
matching playbook** and let it name those exact points instead of rediscovering
them mid-cutover. Absent? Discover it the usual way — and consider
`npx skills add mikeparcewski/wicked-understanding --all` so next time it's known.
## How to run
### plan
1. Document the shape change at `docs/migrations/{N}-{slug}.md`. The
doc names:
- The OLD shape, the NEW shape.
- The rollback contract: how to undo, who pulls the trigger, how
long the rollback window is.
- The expand-contract phase boundaries: when each step happens.
2. Use `wicked-garden-engineering-migration-engineer` for the canonical
playbook.
3. Declare the re-derivable contract early so the cutover gate has a bar
to check against. If a vault is resolvable
(`wicked-garden run scripts/qe/vault_gate.py resolve` → `available: true`):
`wicked-vault init` (once per repo) then
`wicked-vault declare-contract --scope <scope> --phase migrate --spec contract.json`.
`required_evidence` must pin both claim_ids:
- `rollback-proof` → `exit_code_eq:0` on the rollback-drill command —
the rollback was actually exercised and succeeded, not asserted.
- `shape-change` → a deterministic post-condition: `exit_code_eq:0`
on a migration-applied verification, or `jq_pred` over a captured
schema-state JSON.
Skip silently if no vault.
4. **If the shape change is reversible HIGH (e.g. a column add), this
archetype is overkill.** Drop back to `build`.
### expand
1. Add the new shape alongside the old. **Both must work.**
2. New writes go to BOTH shapes (dual-write). New reads still come from
the old shape.
3. Land + deploy expand. Don't combine with backfill.
4. Record the **shape-change** as re-derivable evidence (vault present;
**wicked-vault ≥ 0.8.0** <!-- vault-floor -->):
`wicked-vault record --scope <scope> --phase migrate --claim shape-change
--kind schema-state --source "<migration-applied verification>"
--criteria "<the post-condition>" --verifier exit_code_eq:0
--actor "${WICKED_VAULT_ACTOR:-garden-prove}" --run`. The **`--actor`**
is mandatory because `cutover` is a hard gate: the vault refuses an
`attest` over weak/ambient-identity evidence (fail-closed since 0.4.0),
so without an explicit actor the independent attestation fails closed
and cutover can never be gated PASS. The `--run` captures the real exit
code now and the gate re-runs it later — a claim you can't re-derive is
not evidence.
### backfill
1. Populate the new shape from the old. The backfill must be
**idempotent** — a half-completed backfill that gets restarted
should converge to the same end state as a clean run.
2. Run in batches; rate-limit against the production DB.
3. Verify completeness: the row count + checksum + spot-check sample
match the old shape.
4. **Exercise the rollback drill and record it as re-derivable evidence —
this must exist and re-derive BEFORE cutover** (vault present):
`wicked-vault record --scope <scope> --phase migrate --claim rollback-proof
--kind rollback-drill --source "<the rollback-drill command>"
--criteria "rollback exercised and succeeded" --verifier exit_code_eq:0
--actor "${WICKED_VAULT_ACTOR:-garden-prove}" --run`.
The **`--actor`** keeps the rollback proof attestable by an independent
reviewer (the vault refuses weak identities since 0.4.0; the hard
cutover gate needs it). The
`--run` captures the drill's real exit code now; the gate re-runs
it at cutover. A rollback path you can't re-derive is not a rollback
path. No vault → fall back to `evidence_tracker.py claim`.
### cutover
1. **Pre-cutover checklist**:
- Rollback path executed in staging. (`✓` or block.)
- Backfill complete + verified.
- Dual-write running cleanly for at least 24h.
- Monitoring + alerts updated to surface new shape's anomalies.
2. **Gate before any switch** — don't self-assert the checklist. Run the
produces-gate WITH judgment:
`wicked-garden run scripts/qe/prove.py <claim> --by "<command>" --scope <scope> --phase migrate --with-attestations` (frictionless, single claim — re-derive, don't assert) — or the full multi-claim contract via `wicked-garden run scripts/qe/vault_gate.py gate <project_dir> --scope <scope> --phase migrate --with-attestations` **`--with-attestations`** keeps this gate `UNATTESTED`/`REJECT` until an INDEPENDENT evaluator (not the doer) runs `wicked-vault attest <artifact-id> --opinion pass` — find it via `wicked-vault list --scope <scope> --phase migrate`. The doer's own evidence cannot satisfy a hard gate.
(exit 0 = satisfied). This re-derives the rollback drill and the
shape-change post-condition over the declared contract, and requires
the independent attestation (evaluator ≠ migrator, via
`wicked-vault:analyze-evidence`). A REJECT means the rollback proof or
shape change doesn't clear its contract — fix the work, not the claim.
An `unavailable` verdict means the required vault isn't installed — run
the `wicked-garden-core` skill's `setup` action. **No cutover on a fail-closed verdict.**
3. **Cutover staged**: switch readers first, watch for 1h, then switch
writers. Don't switch both at once.
4. The cutover gate is HARD — explicit user "go" before each switch.
5. If anything looks off post-cutover: **rollback first, debug second.**
### contract
1. Wait for cutover to soak (24–72h, longer for data shape).
2. Stop the dual-write. Only the new shape is being written.
3. After another soak, drop the old shape.
4. Land the contract change with a docs update — the migration is now
complete.
## When to stop
Cutover may only proceed when the produces-gate is satisfied — check it,
don't self-assert it:
`wicked-garden run scripts/qe/prove.py <claim> --by "<command>" --scope <scope> --phase migrate --with-attestations` (frictionless, single claim — re-derive, don't assert) — or the full multi-claim contract via `wicked-garden run scripts/qe/vault_gate.py gate <project_dir> --scope <scope> --phase migrate --with-attestations` **`--with-attestations`** keeps this gate `UNATTESTED`/`REJECT` until an INDEPENDENT evaluator (not the doer) runs `wicked-vault attest <artifact-id> --opinion pass` — find it via `wicked-vault list --scope <scope> --phase migrate`. The doer's own evidence cannot satisfy a hard gate.
(exit 0 = satisfied). This is a re-derived PASS over the declared contract
plus the independent attestation; a missing vault is `gate: "unavailable"`
/ `satisfied: false`, never a claim-only pass.
Migrate is done when the old shape is removed AND the contract phase
has soaked. Hand off to `review` for a post-migration audit when the
change touched compliance or revenue surface.
## Anti-patterns
- **Don't combine expand with backfill.** Each phase is a separate
ship. Combining them removes the ability to roll back to a clean
intermediate state.
- **Don't switch readers and writers simultaneously.** Stage them.
- **Don't contract before soaking.** "We've cutover; let's clean up
the old shape" is how you discover at 3am that one consumer never
switched.
- **Don't skip rollback testing.** A rollback path you haven't
exercised is not a rollback path.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |