Ship the agent guidance the repo was missing

[somebox]

Why

The best "how to work a Cards board" document was an untracked file in a home directory. It was better than anything the project shipped, and it would have been lost with the laptop.

Meanwhile MCP initialize returned no instructions at all — the protocol has a slot for exactly this — so the docs asked humans to hand-paste a block into their own CLAUDE.md and keep it in sync. serverInfo.version answered "poc" on tagged releases. And the guidance contradicted itself: the skill told a worker to record on its own card while pi-cards told its subagent never to.

What changed

internal/agentguide owns the guidance. invariants.md is a single shared trunk: served verbatim behind a two-line preamble as the MCP handshake, and spliced into the marked region of the skill by go test ./internal/agentguide -update. Nothing else is generated — the skill's operational sections are authored, so the always-on handshake stays short while the on-demand skill grows independently. The two have different audiences and different token budgets; only the trunk is common to both.

Sizing is enforced, not hoped for: the handshake is capped at 2 KiB / 40 lines (currently 1923 bytes) because it lands in every session's prompt prefix, including sessions that never touch a board. New guidance goes in the skill.

• MCP — initialize serves the instructions and a real version via a variadic WithVersion option.
• CLI — cards mcp --print-instructions prints the same bytes with no workspace and no server, so a harness can be wired from a bare install. cards init installs the skill to .claude/skills/cards beside .cards, atomically (staged, then renamed), never clobbering, and it runs even when the workspace already exists — an established project is the case with no other install path. --no-skill opts out; --global follows $HOME, never $CARDS_HOME, which relocates the board but not the harness directory.
• Skill — carries a project-practices reference for adoption: the minimal epic/story/task ladder, migration with provenance, collaboration modes, review packets, snapshot hooks, release conventions. Its frontmatter description triggers on setup and migration too, or the playbook would ship and never fire.
• Docs — .claude/skills is named as what Claude Code and compatible harnesses read; MCP is the harness-neutral path; another harness's skill location is stated as a follow-up rather than a promise.

Smoke tests

Two tiers, because they answer different questions and cost different amounts.

scripts/smoke-adoption.sh is deterministic — no key, no network, 26 assertions over a real binary in a throwaway directory. It also pins the starting conditions an adopting agent must overcome (cards init ships zero link types, no default_board, a welcome board), so changing the starter surfaces here instead of silently invalidating the playbook.

internal/smoke/adoption_test.go is the agentic half — build-tagged, skipping without CARDS_AGENT_CMD, following the idiom pi-cards already established. Two rules make it worth running: assert over artifacts, never the transcript (the agent's path is nondeterministic; the workspace it leaves is not), and assert properties, not mimicry (checking for exactly epic/story/task would only prove it copied the playbook). The runner is swappable because one oracle across several harnesses is the only way to read a failure: every runner failing one check means the guidance is wrong; one runner failing it means that harness never loaded the skill.

The load canary is part-of. cards init ships no link types, so it cannot be copied off the scaffold, and it is not what a model reaches for unaided. Scoring is per-check pass rate over CARDS_SMOKE_RUNS, not a binary verdict — the system under test is stochastic and a hard gate would just be a flaky red build.

Found by writing this

Two hard load failures the playbook now warns about, both the same class: settings.default_board naming a board whose file does not exist yet, and deleting a card type while a board still lists it in card_type_ids. Either bricks the workspace for every subsequent command. Setting up a board is exactly where an agent hits them.

Also, in the final review pass: the atomic-install fix had landed a skill root at mode 0700 (MkdirTemp creates 0700, Rename preserves it), unreadable to a CI runner or container on another uid; and the oracle read link edges as type when the wire name is type_id, which would have made the hierarchy canary fail on every run including correct ones.

Verification

go build, go vet, full go test ./..., and -race on the touched packages all pass. scripts/smoke-adoption.sh is 26/26.

The oracle was validated both ways against stub agents rather than trusted: a stub following the playbook passes 8/8; one behaving as a model without the skill (parent field, no link types, no default_board, six required fields) fails five checks with the intended diagnostics.

Not done

The agentic tier has never run against a real model — only against stubs. Expect the first live run to shake out assertions that are too strict. The stub fixtures that validated the oracle live outside the repo; promoting them so CI can prove the checks aren't vacuous is a reasonable follow-up.

Board: 524c06f7 and 086bb35f, both in review with evidence.

🤖 Generated with Claude Code