feat(skill): bundled agent skills and growth programme corpus [roadmap:v0.10.5]

[tcballard]

Summary

Implements rac/roadmaps/v0.10.x-guide/v0.10.5-bundled-agent-skill.md, rac/roadmaps/v0.10.x-guide/v0.10.5-review-and-ingest-skills.md, and the growth programme umbrella rac/roadmaps/future/growth-programme.md.

Adds:

• Three Claude Code skills bundled as package resources (rac-artifacts, rac-review, rac-ingest), installable into any project from the wheel alone
• rac skill install [name] and rac skill list with pinned human and JSON output
• The growth programme corpus: seven requirements, two designs, an umbrella roadmap, the README spec-driven-development comparison, docs/ecosystem.md, and the consolidated traceability gap report
• 39 skill tests (1003 total after merging main), six golden files, CLI documentation, changelog entries for the v0.10.5 tag

Roadmap / ADR Trace

Roadmap:

• rac/roadmaps/v0.10.x-guide/v0.10.5-bundled-agent-skill.md (originally numbered v0.10.4; renumbered when main assigned that release identity to Guide telemetry)
• rac/roadmaps/v0.10.x-guide/v0.10.5-review-and-ingest-skills.md
• rac/roadmaps/future/growth-programme.md

Relevant ADRs:

• rac/decisions/adr-021-templates-product-contracts.md — skills ship exactly as canonical templates do: package resources via importlib.resources
• rac/decisions/adr-003-structured-outputs-first.md, adr-007-json-contract-stability.md — new output contracts pinned by golden tests
• rac/decisions/adr-036-lore-product-identity.md — governs the growth positioning; the README first screen is unchanged

Scope

Included

• rac.skills subpackage carrying three SKILL.md resources, shipped via package-data; each kept byte-identical to its .claude/skills/ dogfood copy by test
• rac skill install (no name): installs every bundled skill, all-or-nothing — every target path is checked before anything is written, refusal reports all existing paths and writes nothing
• rac skill install rac-review (named): installs one; the documented recovery when some skills already exist
• rac skill list: bundle enumeration, human and --json
• Growth corpus: rac-growth-positioning, -adoption, -agent-skill, -contribution-policy, -essay-bridge, -extensibility, -ecosystem-list requirements; growth-demo-gif and growth-essay-mapping designs; README "How this relates to spec-driven development" section with every comparison cell cited to the named tool's own documentation
• .agent-context/: programme brief/schema, per-agent gap records, GAPS_TRACEABILITY.md (eight consolidated schema gaps with corpus-cited instances), CHANGES_SUMMARY.md, cold-start timing log
• A merge of main (v0.10.4 Guide telemetry, lore server rename); conflicts in cli.py, the output modules, docs/cli.md, and CHANGELOG.md were additive and resolved keeping both features

Excluded

• Publishing or registry work; the release happens when the maintainer tags v0.10.5
• The remaining v1.4 skills scope (workspace analysis); only review and ingest were pulled forward
• Skill distribution to other agent platforms (Cursor, Copilot) — one deep integration, per the growth brief
• The rac-growth-extensibility plugin mechanism — requirements only, no core code
• GATE-1/GATE-2 items: the essay bridge and the contribution policy remain Blocked in their artifacts; CONTRIBUTING.md is untouched and docs/ecosystem.md contains no solicitation language
• Kiro rows in the comparison table: its documentation returned HTTP 403 at verification time, so Kiro is named in prose only with the exclusion recorded at the table

Product / Architecture Decisions

• Skills mirror templates, not a new mechanism: resource loading, the usage-error/operational-error split (SkillNotFound / SkillResourceMissing mirror TemplateNotFound / TemplateResourceMissing), and package-data shipping all reuse the ADR-021 pattern.
• No-arg install is all-or-nothing rather than skip-existing: partial installs would blur the never-overwrite contract; the named install is the additive path.
• The install JSON contract is a list ("skills": [...]) for both the no-arg and named forms — one shape instead of two. The earlier single-object shape was replaced before any tag existed, so this is a reviewed contract change, not a break.
• The repository keeps its own .claude/skills/ copies (dogfooding — Claude Code discovers them in this repo) with byte-equality tests preventing drift against the packaged resources.
• Growth positioning defers to ADR-036: the layer-above-SDD comparison lives below the README fold; the Lore lead is byte-identical to before.

User-Facing Contract

CLI

rac skill install                       # all bundled skills into ./
rac skill install rac-review            # one skill by name
rac skill install --dir ../app --json
rac skill list

Human Output

• Install: one Installed ... skill: path line per installed skill, then the Claude Code discovery hint
• Refusal: rac: ... already exists; rac skill install never overwrites on stderr, every conflicting path reported
• List: name plus one-line description per bundled skill

JSON Output

{
  "schema_version": "1",
  "installed": true,
  "skills": [
    {"skill": "rac-artifacts", "path": ".claude/skills/rac-artifacts/SKILL.md"},
    {"skill": "rac-review", "path": ".claude/skills/rac-review/SKILL.md"},
    {"skill": "rac-ingest", "path": ".claude/skills/rac-ingest/SKILL.md"}
  ]
}

skill list --json returns {"schema_version": "1", "skills": [{"skill": ..., "description": ...}]}.

Exit Codes

• 0: installed / listed
• 1: a target skill file already exists (nothing written), or a packaged resource is missing (broken installation)
• 2: --dir is not a directory, or an unknown skill name (available skills listed)

Verification

Ran

python -m pytest tests/            # 1003 passed (post-merge, telemetry + skills)
ruff check src/ tests/ && ruff format --check src/ tests/ && mypy src/
pip wheel . -w /tmp/wheel2 --no-deps   # wheel contains all three SKILL.md resources
rac validate rac/                      # 118 valid, 0 invalid
rac relationships rac/ --validate      # 310 checked, 0 issues
rac review rac/                        # no priority 1-2 findings

Covered

• Per-skill byte-equality between packaged resource and dogfood copy (all three pairs)
• No-arg install into a fresh directory writes three files; re-run exits 1 and writes nothing
• All-or-nothing boundary: with exactly one pre-existing skill file, refusal writes none of the other two
• Named install writes exactly one file; unknown name exits 2 and lists the bundle
• Skill frontmatter name agrees with the registry entry for every bundled skill
• skill list performs no writes; human and JSON shapes pinned by goldens
• Competitor claims in the README comparison re-verified against the live spec-kit and OpenSpec documentation at integration review
• Live discovery: Claude Code picked up all three skills from this repository's .claude/skills/ during development

Review Path

1. rac/roadmaps/v0.10.x-guide/v0.10.5-bundled-agent-skill.md, v0.10.5-review-and-ingest-skills.md — the accepted contracts
2. src/rac/core/skills.py, src/rac/services/skill.py — registry and install semantics
3. src/rac/cli.py, src/rac/output/human.py, src/rac/output/json.py — surface wiring (also carries the additive merge with mcp-stats)
4. .claude/skills/*/SKILL.md — the skill content agents will actually follow
5. tests/test_skill.py, tests/golden/skill_* — contract evidence
6. rac/requirements/rac-growth-*.md, README.md, docs/ecosystem.md, .agent-context/ — the growth corpus and programme records
7. docs/cli.md, CHANGELOG.md

Notes For Reviewer

• .agent-context/GAPS_TRACEABILITY.md is the substantive read in the growth half: eight schema gaps with real corpus instances, each with a minimal addition and the future work it motivates. The v0.10.4 version-identity collision this branch just hit is a live instance of its supersession gap.
• The README diff is a pure 36-line insertion below "Who it's for"; the first screen is unchanged per ADR-036.
• Known limitation: sync tests catch drift between the two copies of each skill but cannot catch skill prose drifting from CLI behaviour; that risk is recorded in the v0.10.5 roadmap.
• Deferred follow-ups live as Proposed requirements (rac-growth-extensibility, adoption REQ-005) and the gate-blocked artifacts.

Implementation Process

Implemented with AI assistance under the roadmap contract.

Final scope, review, and acceptance decisions were made by the maintainer.