Skip to content

mikeparcewski/wicked-garden / skills/archetype

wicked-garden-archetype

Verified

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

FileKindSize
SKILL.mdskill md8.0 KB
refs/build.mdmarkdown7.5 KB
refs/decide.mdmarkdown6.1 KB
refs/explore.mdmarkdown2.3 KB
refs/incident.mdmarkdown8.2 KB
refs/migrate.mdmarkdown9.7 KB
refs/modernize.mdmarkdown11.6 KB
refs/review.mdmarkdown9.7 KB
refs/ship.mdmarkdown6.1 KB
refs/specify.mdmarkdown5.8 KB
refs/triage.mdmarkdown2.7 KB

refs/build.md

View on GitHub
# build — plan / implement / test / review

The most common archetype. Implement and ship a feature or fix. **Test
rigor scales with complexity, blast_radius, and novelty** — a one-line
typo fix and a new auth path are both `build` archetype, but the test
phase looks different.

## Phase shape

| Phase     | Goal                                                |
|-----------|-----------------------------------------------------|
| plan      | Name the diff in 2–3 sentences. Pick the test rigor. |
| implement | Write the change. Stay in the diff; resist drift.   |
| test      | Verify the diff does what plan said. Rigor scales.  |
| review    | Hand off to the `review` archetype if needed.       |

## Produces

- **Shipped code**: a commit (or PR) with the diff.
- **Test report**: at minimum, evidence that the change was exercised.
  At higher rigor: unit tests, integration tests, acceptance evidence.

The review 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 evidence is re-hashed and its verifier
re-run, never trusting a cached "done". 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. `--no-require` opts a throwaway/low-rigor run
back to the doctrine-light claim-only path.

## HITL

`discrete:review-gate` — review is the discrete gate. Approve happens
through PR review, council, or the `review` archetype if rigor warrants.

## 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). If its skills are present — `add-feature` /
`fix-bug` / `scaffold` / `write-tests`, or the routing block in
`AGENTS.md` / `CLAUDE.md` — **load the one matching this task and follow its
repo-specific method**: the file that owns this kind of change, the wiring step
("register it here or it won't boot"), the real test command, the gotcha. That
turns the plan phase from "discover how this repo works" into "follow the known
method." 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. Initialise the evidence tracker for this archetype run:
   `wicked-garden run scripts/qe/evidence_tracker.py init <project_dir> --archetype build`.
   Pre-populates `shipped-code` and `test-report` as pending.
   Then, if a vault is resolvable
   (`wicked-garden run scripts/qe/vault_gate.py resolve` → `available: true`), declare the
   re-derivable contract for this phase so the review gate has a bar to
   check against:
   `wicked-vault init` (once per repo) then
   `wicked-vault declare-contract --scope <scope> --phase build --spec contract.json`
   — `required_evidence` should pin `tests-pass` to a deterministic
   verifier (e.g. `exit_code_eq:0`). Skip silently if no vault.
2. If picking up open conditions from a prior `review` archetype, read
   `wicked-garden run scripts/qe/conditions_manifest.py status <project_dir>` and pin
   each one to a build task so they don't get lost.
3. Name the diff in 2–3 sentences. What changes? What stays the same?
   What's the smallest possible scope?
2. Pick the test rigor based on signals (factor scoring from the
   propose-process rubric is a fine input):

   | Signal pattern                                  | Test rigor             |
   |-------------------------------------------------|------------------------|
   | reversibility HIGH + blast_radius LOW + novelty LOW | one targeted test  |
   | medium on any of the above                      | unit tests + 1–2 integration |
   | high on any of the above                        | unit + integration + acceptance |
   | compliance scope OR auth changes                | full + security audit  |

3. If the diff is simple-edit-class (typo, comment, format), build
   shouldn't have been the archetype — drop back to `triage` and
   suppress.

### implement

1. Before you write code, check what the chosen framework or library already
   provides for the job, at the version the repo pins. The user and the steering
   policies choose the stack (wicked-core rule POL-2101); never swap in another.
   Record the check in the phase output: what you read and what it offers. Custom
   code that duplicates a built-in states why the built-in does not fit (the
   `wicked-garden-governed-worker` floor's rule C8).
2. Write the change. Stay tight to the plan.
3. Use the `wicked-garden-engineering-patch` module for patch-style edits when the
   change is well-scoped.
4. **Don't refactor adjacent code unless plan said so.** Drift is the
   #1 source of inflated build cycles.

### test

1. The rigor picked in plan governs which tests get written.
2. Use the `wicked-garden-qe` skill's `author` action to generate tests when the rigor is
   medium or high.
3. **Tests must actually fail when the code is wrong.** The
   test-code-quality-auditor exists for a reason — assertion-free
   tests are worse than no tests.
4. Record the test run as re-derivable evidence (vault present):
   `wicked-vault record --scope <scope> --phase build --claim tests-pass
   --kind test-run --source "<the test command>" --criteria "<the bar>"
   --verifier exit_code_eq:0 --run`. The `--run` captures the command's
   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`.

### review

1. Open the PR. Use the appropriate review skill:
   - Low rigor: `pr-review-toolkit:code-reviewer` only.
   - Medium: code-reviewer + relevant specialist (security / data /
     etc.).
   - High: full `review` archetype (this skill family).
2. Address findings. Keep the response narrow — review feedback is for
   THIS diff, not for opening adjacent issues.

## When to stop

Build is done when the produces-gate is satisfied AND the PR is merged.
Check the gate — don't self-assert it.

**Frictionless (recommended for a single decisive claim):** skip the
init/declare/record/gate ritual and re-derive in one call —
`wicked-garden run scripts/qe/prove.py tests-pass --by "<your test command>" --scope <scope> --phase build`
(exit 0 = re-derived PASS; exit 1 = REJECT; exit 3 = backend down / fail-closed).
Run it before you tell anyone the build is done.

**Full contract (multi-claim):** declare a contract then
`wicked-garden run scripts/qe/vault_gate.py gate <project_dir> --scope <scope> --phase build`
(exit 0 = satisfied). Either way it is a re-derived PASS over the declared
contract. A REJECT means the recorded evidence does not 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. If the
change is high-blast-radius, hand off to `ship`.

## Anti-patterns

- **Don't refactor in build.** A bug fix doesn't need surrounding
  cleanup. The CLAUDE.md "no premature abstraction" rule applies.
- **Don't write tests before the code compiles.** TDD is fine; testing
  uncompilable code is not.
- **Don't merge with red CI.** The "I'll fix it in a follow-up"
  mentality is how main goes red and stays red.
- **Don't test-stamp with rigor that doesn't match the change.**
  Adding 200 LOC of integration scaffolding for a typo fix is its own
  anti-pattern.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall