wicked-garden-build-guide
Skill9 starsChanged 7 months agoMITView on GitHub
Discover 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.
- Reads credentials
- Installs packages
In this repository142 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- plugin-json-schemaSkill
- readme-style-guideSkill
- releaseSkill
- scaffoldSkill
- wicked-garden-agentic-agentic-patternsSkill
- wicked-garden-agentic-architectSkill
- wicked-garden-agentic-context-engineeringSkill
- wicked-garden-agentic-frameworksSkill
- wicked-garden-agentic-performance-analystSkill
- wicked-garden-agentic-review-methodologySkill
- wicked-garden-agentic-safety-reviewerSkill
- wicked-garden-agenticSkill
- wicked-garden-agentic-trust-and-safetySkill
- wicked-garden-appsSkill
- wicked-garden-archetypeSkill
- wicked-garden-classifySkill
- wicked-garden-coreSkill
- wicked-garden-data-engineerSkill
- wicked-garden-dataSkill
- wicked-garden-deliberateSkill
- wicked-garden-demoSkill
- wicked-garden-domain-coverageSkill
- wicked-garden-domain-extractorSkill
- wicked-garden-domain-modelerSkill
- wicked-garden-domainSkill
- wicked-garden-draftSkill
- wicked-garden-editor-scaffoldSkill
- wicked-garden-engineering-api-documentarianSkill
- wicked-garden-engineering-architectureSkill
- wicked-garden-engineering-backendSkill
- wicked-garden-engineering-debuggingSkill
- wicked-garden-engineering-docsSkill
- wicked-garden-engineering-frontendSkill
- wicked-garden-engineering-integrationSkill
- wicked-garden-engineering-large-scale-migrationSkill
- wicked-garden-engineering-migration-engineerSkill
- wicked-garden-engineering-patchSkill
- wicked-garden-engineeringSkill
- wicked-garden-engineering-solution-architectSkill
- wicked-garden-engineering-system-designSkill
- wicked-garden-engineering-unit-test-qualitySkill
- wicked-garden-governed-workerSkill
- wicked-garden-groundSkill
- wicked-garden-jam-brainstorm-facilitatorSkill
- wicked-garden-jam-councilSkill
- wicked-garden-jamSkill
- wicked-garden-learnSkill
- wicked-garden-mcp-scaffoldSkill
- wicked-garden-mcpSkill
- wicked-garden-mem-captureSkill
- wicked-garden-mem-ingestSkill
- wicked-garden-memSkill
- wicked-garden-personaSkill
- wicked-garden-platform-auditSkill
- wicked-garden-platform-compliance-officerSkill
- wicked-garden-platform-complianceSkill
- wicked-garden-platform-errorsSkill
- wicked-garden-platform-gate-benchmark-rebaselineSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 38
If none of these is available, or Python 3 is missing, skip the script-backed step, say so, and follow the manual alternative where one is …
- Very specific: line 58
No argv goes through a shell.
- Very specific: line 60
When a token is a regex for the runner, use {id:re} (the id regex-escaped, per id) or {ids:re|} (every id regex-escaped and joined with |, …
- Distinctive: line 127
Use JUnit if the runner already emits it through a flag, a reporter or a plugin it has (JSON lines and TAP are reserved in v1).
- Distinctive: line 189
Before you open the PR, show the user the guide and the probe table, and ask whether to open it.
- Distinctive: line 195
If the repo has no tests, or no candidate survives step 4 within the attempts, say so plainly: *"no build/test guide: the floor will run …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Build/test guide
The floor decides by exit codes and excludes only the base's own failures. To do that for any
runner without runner names in engine code, it reads a per-repo guide that says how this repo
runs its tests, how to read their results, and how to list, run one or deselect a test. The floor
reads .wicked/build-guide.json from the base tree, so a head edit never applies to its own
run. Every piece is checked against reality by wicked-core floor probe. A piece whose probe did
not pass is not used, and that check runs exit-code only.
This skill discovers, drafts, validates and proposes the guide. It never decides "verified".
Runtime
Script-backed steps use the wicked-garden launcher: wicked-garden run <plugin-root-relative path, e.g. scripts/…> [args]. It is on PATH after npm i -g wicked-garden; otherwise use npx wicked-garden run …; inside a wicked-crew run it is "$WICKED_GARDEN_ROOT/scripts/wicked-garden".
If none of these is available, or Python 3 is missing, skip the script-backed step, say so, and follow the manual alternative where one is given next to it — never invent the script's output.
Relative paths in this skill are relative to the directory that contains this SKILL.md.
Actions
| Action | When | How |
discover (default) | the repo has no guide | steps 1 to 6 below |
refresh | the guide is stale (a derivedFrom file or the runner version changed), a probe failed, or crew dispatched re-onboarding | start from the committed guide; if a derivedFrom file changed, redo step 1; otherwise revise only the failing piece; then steps 4 to 6 |
check | validate a guide file someone wrote | wicked-garden run scripts/build_guide/check.py --guide <file> --repo <dir> [--schema <file>]. For a test check (one with list), it flags what the floor needs before it will use it: a non-empty failedExit, alone, deselect, two mutations, and a text or junit results kind. It warns when the version piece is missing. With --repo, it warns for every CI step no check declares. On a probed guide, it flags any required probe that did not pass. |
The contract is fixed (DES-BUILD-GUIDE, "Contract v1"). Its schema is wicked-core's
schemas/build-guide.v1.json, which the scripts carry as a vendored copy. Produce exactly that
shape, and add no fields. refs/contract-notes.md lists what core's schema adds to the DES text,
how this skill reads it, and the open questions. To check against a newer core schema, pass it
as --schema.
Pinned semantics (core's interpreter):
- Regexes apply per line. A block's items are the contiguous item lines after its start (blank lines are allowed), and any other line ends the block.
- No argv goes through a shell.
{id}/{q}fill whole argv elements, so no quoting is needed;{q}is allowed inaloneanddeselect.{files}expands to one argv element per file. When a token is a regex for the runner, use{id:re}(the id regex-escaped, per id) or{ids:re|}(every id regex-escaped and joined with|, in a single token). - Deselect tokens before the first per-id token (
{id},{q},{id:re}) are added once (a leading--only when the argv has none). The tokens through the last one repeat per id, and the rest are added once. So a flag and its value are one token (--skip={id}). A runner that takes one exclusion pattern gets one{ids:re|}token instead. - Paths (
results.how.path, the mutation files) are relative tocwd.invalidatedByglobs are matched against the files the change touched. - Each JUnit
<testcase>is judged on its own. A<skipped/>one neither passed nor failed, andmultineeds two distinct failures. The results kind istextorjunit;json-linesandtapare reserved.results.how.envapplies only to runs whose results are read, not tolistorversion. affectedruns the full check whenever the change deletes a file or renames one away.- The floor and the probe both refuse to load a guide with an empty
run, astageother thancreator/verify, alistwithoutfailedExit, a0infailedExit, acwdthat is not.or plain relative segments (absolute, climbing, an empty or.segment,\or:), anamethat is not 1-64 ofA-Z a-z 0-9 . _ -(or is./..), aresults.how.envname that is not[A-Z_][A-Z0-9_]*or is a loader/shell hook (LD_*,DYLD_*,BASH_ENV, …), or{ids:re|}among the per-id tokens or together with{q}in onedeselect. Then detection is the whole floor. - A check named
installis the floor's install step. The probe runs it first, in every fresh copy, for checks in the samecwd, so declare it whenever a runner comes from the install. - How the floor reads exit codes: 0 passes. A code in
failedExitwith parsed failures is tests failing. AfailedExitcode with no parsed failure isbase_red_unseparatedon the base andnew_failureon the head. Any other non-zero code iscould_not_run. - The guide replaces detection, per directory. In the directories its checks cover (their
cwds), a usable guide's checks ARE the floor's checks, run at thestages they declare (absent means both). A package no check covers keeps its detected checks, judged by exit code. So declare EVERY step the repo's CI gates on (install, build, format, lint, typecheck and test), each with thecwdCI runs it in, sub-packages included. Give an expensive gatestage: ["verify"]. A check with nolistis a gate (name,cwd,run, and afailedExitwhere the tool documents one; noresults, noversion). Its exit code alone decides it, and it is not probed. Only a test check (withlist, and soresults) carries the pieces and probes below. version: {run: argv}is the runner's own version command. The probe records its first output line asrunnerVersionand adds a requiredversionprobe; the floor treats a different version as stale. When any probe fails, the whole probe re-runs once on a fresh copy, and that retry's results are recorded, each marked(retried).pass (retried)counts as a pass;fail: … (retried)leaves the guide unverified. A failure for a missing piece is not retried.- Onboard from a GREEN commit. The probes need a green clean run. On a red base, every
probe after
runfails with "needs a green base". If the repo's tests are red, say so and ask for a green commit (or a fix) before you probe. Don't relax the guide to fit a red suite.
1. Discover what the repo already declares
wicked-garden run scripts/build_guide/discover.py --repo <dir>It reads CI config first (.github/workflows/*, .gitlab-ci.yml, Makefile, justfile), then
the manifests (Cargo.toml, package.json scripts, pyproject/setup.cfg/tox.ini, go.mod,
gradle/maven). It follows make test, just test and npm test one level into what they run,
and lists every test candidate with its file:line. It also lists ciSteps: every command CI
runs. Each one becomes a check, a gate unless it is the test run. It runs nothing. Manual alternative:
read those files yourself, in that order.
Then interrogate each candidate's runner: run its --version and --help, and any sub-help it
points to (for example cargo test -- --help). From the runner's own words, learn its result
formats, how it lists tests, how it runs one test, how it deselects exact tests, and which exit
code means "tests failed". Record the version command as the check's version piece
({"run": ["<runner>", "--version"]}). refs/discover.md has the checklist. Record every file you derived
the guide from in derivedFrom.
verdict: no-test-command → go to step 6.
2. Results: structured first
Use JUnit if the runner already emits it through a flag, a reporter or a plugin it has (JSON
lines and TAP are reserved in v1). Set results.id/idJoin so the ids are the ones the list
prints, and set results.how.merge/list.merge when the runner names scopes on stderr. Put the flag in results.how.argvAppend and the file in results.how.path. Only
when none exists, write a text parser: line regexes, an optional section qualifier and summary
blocks. Learn them from real output of this repo's runner, captured by running it on a
scratch copy with the mutation probe in it. Base the parser on the runner's own final summary
where one exists, not on per-test lines interleaved with test output. refs/results.md has the
rules (RE2 only, every regex ^…$), the id round-trip test, and worked examples. The starting
points in assets/seeds/ (cargo, pytest, vitest) are drafts too: probe them like anything else.
3. Write the two mutation probes
probes.mutation and probes.mutation2 are two minimal, deliberately failing tests in the
repo's own language and test framework. Each goes in its own new file that the runner's
normal discovery picks up, with a different id, and each carries the id the parser must name
(expectId, plus expectQ when ids are qualified). One proves that the parser, the ids and
deselect agree. Both together prove that two failures are both parsed and both deselected.
The alone probe runs the mutated test alone (it must fail, naming exactly it), and then a
passing test under the same qualifier (it must run green). When each test file is its own
qualifier (cargo: one binary per integration-test file), put a passing test beside the failing
one in the mutation file (fn floor_probe_mutation_beside() {}). Never edit an existing test
file.
4. Validate: rehearse, then probe (at most 3 attempts per check)
wicked-garden run scripts/build_guide/check.py --guide <draft> --repo <dir> --draft
wicked-garden run scripts/build_guide/rehearse.py --repo <dir> --guide <draft>
wicked-garden run scripts/build_guide/probe.py --repo <dir> --guide <draft>check --draftvalidates the shape and refuses a draft that carriesverified.rehearsemirrors the core probes (list,run,mutation,ids,alone,deselect,multi, plusaffectedandversionwhen present, retried as core retries) in a scratch copy, so you can iterate quickly. It composes argvs around--as core does, and it skips gates. It is not evidence and writes nothing.proberunswicked-core floor probe --repo <dir> --guide <file>. Only that command writesverified, includingrunnerVersionfrom theversionpiece you wrote (for example{"run": ["cargo", "--version"]}). Never hand-writeverified(runnerVersionincluded), and never edit what the probe wrote.
A failed probe names a piece. Revise that piece's argv, parser or template and probe again. Stop after 3 probe attempts for a check, and report each attempt's results. Do not keep tuning.
Probe unavailable (probe.py exits 3, because wicked-core is missing or has no
floor probe): say exactly "probe unavailable: the guide is unverified, so the floor will not
use it for exclusion". You may still propose the draft, labelled unverified, with the rehearsal
results. It is not verified, and the floor will run that check exit-code only until a probe
passes it.
5. Propose, never write silently
The guide lands through the approve queue, never as a silent write. refs/propose.md has the
steps and the PR body template.
- Inside a wicked-crew run, write
.wicked/build-guide.jsonin the run's worktree. The run's deliver gate is the proposal. Do not open a second PR. - Otherwise, create a branch (
wicked/build-guide) and commit only the guide. Open a PR (draft when any probe failed or was unavailable). Its description holds the probe results: themarkdowntable thatprobe.pyprints, or the rehearsal results labelled "rehearsal, unverified". Also give the runner version and thederivedFromlist. - Never push to the default branch, and never commit the scratch copy or result files.
- Before you open the PR, show the user the guide and the probe table, and ask whether to open it. Use your harness's question prompt where it has one; otherwise ask in plain text and wait. In a headless run, do not ask: the deliver gate asks.
6. No guide possible
If the repo has no tests, or no candidate survives step 4 within the attempts, say so plainly: "no build/test guide: the floor will run this repo's checks exit-code only", and give the reason (no test command; a runner that names no failures; ids that do not round-trip). Propose no file.
Report
Give the check names with their run argv, the result kind (and why text, if text), the
per-probe results with attempt count, any known limit (for example, multi failed because the
runner rejects a repeated deselect flag), the runnerVersion, and the PR link or "no guide". Report a failure exactly as it happened.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

