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/modernize.md
View on GitHub# modernize — discover / extract / blueprint / transform / parity / cutover
For porting a **legacy codebase to a new stack** (a language/framework/runtime
jump, a rehost/replatform, a rewrite from the working code as the spec). This is
NOT `migrate` — `migrate` is in-place expand-contract shape change on a *running*
system. `modernize` reverse-engineers an estate, blueprints a target, transforms
with leverage, and proves parity before cutting over.
This archetype is a **general modernization steering shape**. It is self-contained
and **composes the general `code-modernization` skills** for the heavy lifting —
it does not own a parallel lifecycle, and it routes the same rigor/gate discipline
garden already preaches into those skills.
## Phase shape
| Phase | Goal |
|-----------|-------------------------------------------------------------------|
| discover | Map the estate; resolve the legacy **stack class** via the registry. |
| extract | Pull out the testable business rules (what it does, not how). |
| blueprint | Decide the target-state architecture. Decision matrix, not prose. |
| transform | Codemod / regenerate with leverage. Deterministic before AI. |
| parity | Prove old ≡ new on identical inputs. Differential equivalence. |
| cutover | Switch to the new stack. **Hard gate** — staged, parity-proved. |
## Produces
- **Modernization blueprint**: the target-state architecture (target stack,
package/module structure, API surface, data model) + the recorded technique
choice per transform wave.
- **Parity proof**: an executable, re-derivable equivalence check — old vs new
on identical seeded inputs assert identical outputs (the trust, not review).
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 parity
harness is re-run and the blueprint post-condition re-checked, never trusting a
self-asserted "ported fine". 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 modernizer confirms the parity proof
and blueprint 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 cut over to the new stack
without explicit user approval AND a green pre-cutover checklist (parity proved on
real seeded data, rollback path to the legacy system tested, traffic plan staged).
## Ground in the repo's method first
Before you discover, check for **wicked-understanding** repo playbooks (the opt-in
"how to work in THIS repo" layer). A modernization lives or dies on repo-specific
wiring — the build/run command, where the seam between old and new lives, the
deploy/rollback command. If its skills are present, **load the matching playbook**
and let it name those points instead of rediscovering them mid-cutover. Absent?
Discover it the usual way — and consider
`npx skills add mikeparcewski/wicked-understanding --all`.
## How to run
### discover
1. Survey the legacy estate: entry points, modules, data stores, external
contracts. Use `code-modernization:modernize-assess` for the structural read
and `code-modernization:modernize-brief` to frame scope + risk.
2. **Resolve the stack class — DO NOT fabricate a playbook.** Read the dispatch
truth in `.claude-plugin/stack-registry.json` via the reader:
```bash
wicked-garden run \
scripts/crew/stack_registry.py \
resolve --stack <stack-id>
```
- `status: wired` (exit 0) → the printed `dispatch` names the `blueprint`,
`transform`, and `validate` skills/gate to use in the phases below.
- unknown / `planned` / `none` (exit 3) → the reader returns a **capability-gap
task** and emits `wicked.garden.modernize.gap_emitted`. **STOP.** Create that task
(`TaskCreate`) and surface the gap to the user — never invent a transform for a
stack the system can't actually handle. This is the fail-closed ETHOS as
dispatch data: an honest "we don't handle this yet" beats a fabricated port.
- When the legacy stack genuinely is not in the registry but IS general
(any language → modern target), use the `generic-cross-stack` entry, which is
wired to the general `code-modernization` skills.
### extract
1. Mine the domain logic — calculations, validations, policies — into testable
Given/When/Then specs with `code-modernization:modernize-extract-rules`.
Separate *what the business requires* from *how the old code happened to do it*.
2. These extracted rules become the parity oracle: the new stack must satisfy the
same rules. Pin each rule so the parity phase has a bar to check.
**Domain-model extraction (the Domain-Brain path).** When the estate is graphed
in **wicked-estate** and the goal is a shared, gate-able domain model — not just
a local rule list — drive the **`wicked-garden-domain`** router instead. It
STEERS three fork workers that emit a document conforming to
`@wicked/domain-model-schema@1.0.0` (vendored at
`skills/domain/vendor/domain-model.schema.json`): **domain-extractor**
(business rules with confidence + provenance → estate `requirement`
annotations), **domain-modeler** (cluster → domain, invokes
`wicked-core domain-graph` — which reads the annotated estate store and builds the
requirements graph itself, coverage-gated fail-closed), **domain-coverage**
(pre-build threat model). Estate annotations + SymbolId strings are what cross repo
lines; core builds + coverage-gates the requirements graph, crew governs the run.
Garden clears no gate here — it is advisory steering; the coverage terminal is
core's fail-closed build. See `skills/domain/SKILL.md`.
### blueprint
1. Decide the **target-state architecture** with `code-modernization:modernize-reimagine`
(the registry `blueprint` field names this for the resolved stack). Capture it
as a **decision matrix, not a narrative**: target stack + version (pin, don't
"latest"), module/package structure, API surface, data model, the engines/tools.
2. Write the blueprint to `docs/modernization/{slug}-blueprint.md` and declare the
re-derivable contract early so the cutover gate has a bar. If a vault is
resolvable (`wicked-garden run scripts/qe/vault_gate.py resolve` → `available: true`):
`wicked-vault init` then
`wicked-vault declare-contract --scope <scope> --phase modernize --spec contract.json`.
`required_evidence` must pin `parity-proof` to a deterministic verifier
(`exit_code_eq:0` on the differential harness). Skip silently if no vault.
### transform
1. Transform **with leverage, not an agent-grind** — follow
`wicked-garden-engineering-large-scale-migration` (MAP → TRANSFORM → GATE) and
its ranked techniques menu: **prefer the lowest-numbered technique that fully
covers the task** (deterministic recipe/codemod before AI-assisted waves), and
**record the chosen technique** per wave. Drive the bulk through a deterministic
codemod/codegen; touch only the self-flagged residue by hand.
2. Run the resolved `transform` skills (`code-modernization:modernize-map` then
`code-modernization:modernize-transform`) over the estate.
3. **Don't grandfather.** No exemptions, no "left raw with a TODO" — an exemption
preserves the exact legacy case the modernization exists to remove.
### parity
1. Prove **old ≡ new** on identical seeded inputs (differential equivalence) — the
parity proof is the trust, not a diff review. Seed broadly; an empty fixture
passes trivially and lies.
2. Harden the result with `code-modernization:modernize-harden` (security/CVEs,
error handling) before it carries traffic.
3. Record the parity proof as re-derivable evidence (vault present; **wicked-vault
≥ 0.8.0** <!-- vault-floor -->):
`wicked-vault record --scope <scope> --phase modernize --claim parity-proof
--kind differential --source "<the differential harness command>"
--criteria "old(input) == new(input) on seeded data" --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. No vault → fall back to
`evidence_tracker.py claim`.
### cutover
1. **Pre-cutover checklist**:
- Parity proved on real seeded data. (`✓` or block.)
- Rollback path to the legacy system tested.
- Traffic plan staged (canary first, not big-bang).
- Monitoring + alerts cover the new stack.
2. **Gate before any switch** — don't self-assert the checklist. Run the
produces-gate WITH judgment:
`wicked-garden run scripts/qe/prove.py parity-proof --by "<command>" --scope <scope> --phase modernize --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 modernize --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 modernize`. The doer's
own evidence cannot satisfy a hard gate. (exit 0 = satisfied.) A REJECT means the
parity proof 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**: canary the new stack, watch, ramp. Hand the rollout tail to
the `ship` archetype if blast radius warrants.
4. The cutover gate is HARD — explicit user "go" before each ramp step.
5. If anything looks off post-cutover: **roll back to the legacy system first,
debug second.**
## When to stop
Cutover may only proceed when the produces-gate is satisfied — check it, don't
self-assert it (see the cutover step). Modernize is done when traffic is on the new
stack, parity has soaked, and the blueprint matches what shipped. Hand off to
`review` for a post-modernization audit when the change touched compliance or
revenue surface.
## Anti-patterns
- **Don't fabricate a playbook for an unhandled stack.** If the registry says
`planned`/`none`/unknown, emit the gap task and stop. A fabricated port is the
exact failure the fail-closed ETHOS exists to prevent.
- **Don't hand-edit the bulk.** Modernization is MAP → TRANSFORM → GATE, not "fan
out N agents to rewrite each file." Deterministic transform first; AI only for the
residue, eval-gated.
- **Don't trust build-green as parity.** Build/test green ≠ behavior preserved —
*especially* for any LLM/agent surface. Prove `old ≡ new` on real inputs.
- **Don't big-bang the cutover.** Canary, ramp, soak — same discipline as `migrate`.
- **Don't skip rollback testing.** A path back to the legacy system 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 | Verified | 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 |