mikeparcewski/wicked-garden / skills/build-guide
wicked-garden-build-guide
VerifiedDiscover how a repo builds and tests, and write its build/test guide (`.wicked/build-guide.json`, contract v1): the data the wicked-core floor interprets instead of hardcoding runners. Reads CI config first, then the manifests, then each runner's own --version and --help. Prefers structured results (JUnit; JSON lines and TAP are reserved in v1) and writes a text parser, learned from this repo's real output, only when none exists. Writes a deliberately failing mutation probe, validates with `wicked-core floor probe` (only the probe writes `verified`), and proposes the file as a PR or governed change, never silently. Use when: "build guide", "write the build/test guide", "how does this repo test", "onboard this repo's tests for the floor", "re-onboard the build guide", "the build guide is stale", the onboarding step of the wicked-garden-core setup action, or a wicked-crew onboarding run dispatched because the floor found no guide, a stale one, or a failed probe.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.7 KB |
| assets/seeds/cargo-libtest.json | config | 2.6 KB |
| assets/seeds/pytest-short-summary.json | config | 2.5 KB |
| assets/seeds/vitest-junit.json | config | 2.0 KB |
| refs/contract-notes.md | markdown | 12.1 KB |
| refs/discover.md | markdown | 4.9 KB |
| refs/propose.md | markdown | 1.9 KB |
| refs/results.md | markdown | 7.0 KB |
refs/discover.md
View on GitHub# Discover: from what the repo declares to a draft check
## Reading order (most reliable first)
1. **CI config** says how the repo really tests. Look in `.github/workflows/*.yml`
(`run:` steps, including `run: |` blocks), `.gitlab-ci.yml` (`script:`), and `Makefile` or
`justfile` recipes that CI calls. Note any setup the test step depends on (a toolchain
version, an install step, environment variables). The floor runs the check in a prepared
tree, so put only environment variables that change **result output** into
`results.how.env`.
2. **Manifests** say what the CI command resolves to: `package.json` `scripts`, the
`[tool.pytest.ini_options]` in `pyproject.toml`, `setup.cfg`/`tox.ini`, `Cargo.toml` workspace
members, `go.mod`, gradle/maven test tasks.
3. **The runner itself.** Run `<runner> --version` and `<runner> --help`, plus the sub-help it
points to. What the runner prints decides the guide; this skill carries no runner table.
`discover.py` does 1 and 2 mechanically: every command whose text says `test`, with
`file:line`, followed one level through `make`, `just` and `npm|pnpm|yarn run`. It also marks
npm's `no test specified` placeholder, which declares that the repo has no tests.
## Choosing the check(s)
- **Every CI step is a check, with its `cwd`.** In the directories a usable guide's checks cover,
the guide replaces the floor's own detection, so a CI step the guide leaves out there stops
gating. Use the step's `working-directory` as the check's `cwd` (`ciSteps` carries it), and give
expensive gates `stage: ["verify"]`. Declare each `ciSteps` entry. Install, build, format, lint
and typecheck are gates: `name`, `cwd`, `run`, and a `failedExit` where the tool documents
one. Gates have no `list`, `results` or `version`, and are not probed.
`check.py --repo` warns for any step left out.
- One test check per distinct test command CI runs, for example a Rust workspace and a JS package in
the same repo. Give each a short `name` (`test`, `test-web`) and its own `cwd`.
- `run` is the exact argv, not a shell string. The floor excludes failures only for a check
whose argv equals `run` exactly, so the guide is the allowlist. Use the CI command's own
argv. Put a separator that the deselect tokens need (libtest's `--`) at the start of
`deselect.append`: the interpreter adds it only when the argv has none.
- `stage`: `["creator","verify"]` unless the repo marks a suite as slow or verify-only.
- `failedExit`: the exit code(s) the runner documents for "tests failed", as distinct from
usage, collection or crash codes (pytest: 1; cargo: 101; vitest: 1). When the runner uses
the same code for "could not run", say so in the report. The parser then has to name a
failure, or the run counts as could-not-run.
- `invalidatedBy`: globs for files that change how the suite runs (the manifest, the lockfile,
runner config, the CI file, toolchain pins). A head change matching one disables exclusion
for that check.
## Interrogating the runner (`--help` checklist)
For each question, find the runner's own flag. If there is none, write "none", and do not
invent one.
| Question | Where it lands | Example of what to look for |
|---|---|---|
| Can it write JUnit? (JSON lines and TAP are reserved in v1: note them, do not use them) | `results` | a `--reporter`, `--format`, `--junitxml` or `--outputFile` flag |
| Is that format stable on this version? | `results` | cargo's `--format junit` is nightly-only on stable toolchains |
| How does it list tests without running them? | `list.run`, `list.item` | `--list`, `--collect-only -q`, a `list` subcommand |
| How does it run exactly one test? | `alone.run` with `{id}` | an exact-match flag, or a positional node id |
| How does it skip exact tests, repeatably? | `deselect.append` with `{id}` | a skip flag that may be repeated per id, written as one token (`--skip={id}`) |
| Which exit code means "tests failed"? | `failedExit` | the exit status section of the help or man page |
| Can it run only tests touched by files? | `affected.run` with `{files}` (optional) | a related-files or changed-files mode |
The deselect tokens are also appended to `list.run`. The probe checks that the list, with one
id deselected, lists exactly the rest. So the list command must honour the same skip flag.
Check repeatability for real. A flag that takes one value (the last one wins) or rejects
repeats cannot deselect two ids, even when the one-id `mutation` probe passes. The `multi` probe
(two mutations, `probes.mutation2`) tests two ids.
## Learn from real output, in a scratch copy
Never run probes in the operator's tree. Copy the base to a scratch directory, inject the
mutation probe there, run the check, and keep what the runner printed (stdout, and the result
file if there is one). That output is what the parser or the JUnit reading is written against.
`rehearse.py` does exactly this, and removes the copy afterwards.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |