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

.agent-context/BRIEF.md

@@ -0,0 +1,88 @@
+# RAC growth programme — shared brief
+
+Read `.agent-context/SCHEMA.md` first. Every deliverable lands as RAC
+artifacts in this repository (requirements first, supporting artifacts
+second, linked via `## Related …` sections where the schema allows).
+A deliverable that exists only as a loose Markdown note has failed.
+
+## Repo reality (overrides anything you assume)
+
+- Version v0.10.3. Product identity is recorded in **ADR-036
+  (`rac/decisions/adr-036-lore-product-identity.md`): Lore is the product
+  ("agents that know why", MCP grounding); RAC is the engine.** The README
+  first screen leads with Lore and MUST NOT be repositioned. This was
+  confirmed by the maintainer on 2026-06-12.
+- The corpus is already fully dogfooded (38 ADRs, requirements, designs,
+  roadmaps, prompts under `rac/`, validated in CI).
+- Relationships/traceability shipped in v0.7.x (ADR-016). Gap records now
+  motivate FUTURE roadmap work, not "v0.8.0".
+- Read `rac/decisions/` before designing; recorded decisions take
+  precedence. If your task conflicts with one, stop and report the
+  conflict — do not override it.
+
+## Positioning thesis (adapted; use verbatim where comparison framing is needed)
+
+Primary positioning is ADR-036's: Lore gives coding agents the decisions a
+team already made, served deterministically over MCP from a typed Markdown
+corpus in Git.
+
+Secondary positioning, for comparison content only (below the README fold
+or in `docs/`): spec-driven tools (GitHub Spec Kit, OpenSpec, Kiro) manage
+the *change* — proposal, design, tasks — and treat requirements as
+ephemeral inputs that are consumed and archived. RAC manages the
+*requirements* as a durable, versioned, governed corpus that persists
+across changes. RAC is the layer above SDD tools, not a competitor to
+them. Comparison framing is "complements, owns a different layer", never
+"better than".
+
+## Global constraints (verbatim, apply to all agents)
+
+1. **Schema fidelity.** Do not invent a requirement format. SCHEMA.md is
+   extracted from the codebase; use exactly that. If the schema lacks a
+   field you want, note it as a gap, do not add it ad hoc.
+2. **Voice.** Conservative, execution-focused language. No promotional
+   framing, no superlatives, no "blazingly", no emoji. UK spelling
+   throughout. Observation before conclusion. If a claim about a
+   competitor cannot be verified from their repo or docs, it is not made.
+3. **Restraint.** Prefer the smallest artifact that does the job. A
+   three-requirement change beats a twelve-requirement change covering
+   the same ground.
+4. **Human gates.** Two decisions are reserved for Tom and must be
+   flagged, never resolved by an agent:
+   - GATE-1: nothing intended for public posting (X/LinkedIn/HN) ships
+     until employer external-communications and personal-project IP
+     policies have been reviewed. Agents may draft; drafts are marked.
+   - GATE-2: the contribution policy and any "PRs welcome" language does
+     not go live until a CLA is in place. Same marking convention.
+   Gate marking convention (the real schema has no status field for
+   this — that is itself a recorded gap): keep `## Status` as `Proposed`
+   and add a body line directly under it:
+   `Blocked: GATE-1 (employer external-communications / IP review)` or
+   `Blocked: GATE-2 (CLA not yet in place)`.
+5. **No fabrication.** Where you need a fact about spec-kit, OpenSpec,
+   Kiro, or any tool, read the actual repo/README/docs (web fetch).
+   Uncited competitor claims are deleted at integration review.
+6. **Verification.** Finish by running the validation commands in
+   SCHEMA.md against your outputs and fixing failures before reporting
+   done.
+
+## Gap recording (first-class output)
+
+When you need something RAC cannot express, do NOT work around it
+silently. Append a record to `.agent-context/gaps/<your-agent-name>.md`:
+
+```
+## Gap: <relationship or capability needed>
+- Instance: <concrete case from this programme or the existing corpus>
+- Instance: ...
+- Minimal schema addition that would have sufficed: <one sentence>
+```
+
+## Working rules
+
+- Write files only; do NOT run `git commit` or `git push` — the
+  orchestrator commits.
+- Stay inside your assigned paths.
+- New requirement files: `rac/requirements/rac-growth-<slug>.md`, created
+  with `/tmp/racenv/bin/rac new requirement <path>`.
+- UK spelling in all artifact prose.

.agent-context/CHANGES_SUMMARY.md

@@ -0,0 +1,95 @@
+# Growth programme — changes summary
+
+Branch `claude/rac-growth-orchestration-obphpo`, 2026-06-12. The
+programme was adapted before execution: ADR-036 (Lore product identity)
+governs positioning, so the layer-above-SDD thesis appears only as
+comparison content below the README fold; the dogfood-conversion
+workstream was re-scoped to a corpus gap audit because the corpus is
+already fully RAC-native; gap records motivate future roadmap work, not
+"v0.8.0". Adaptation confirmed by the maintainer on 2026-06-12.
+
+## Agent 1 — positioning and comparison
+
+Authored `rac-growth-positioning` (REQ-001..005), then satisfied it
+with one README section, "How this relates to spec-driven development",
+inserted below "Who it's for": layer-above thesis, a five-dimension
+comparison table against GitHub Spec Kit and OpenSpec, every cell
+verified against the tools' own repos with sources in an adjacent HTML
+comment. Kiro is named in prose only — its docs returned HTTP 403 at
+verification time, so no Kiro capability claims are made. First screen
+byte-identical; pure 36-line insertion.
+
+## Agent 2 — adoption surface
+
+Authored `rac-growth-adoption` (REQ-001..005: pipx/uv zero-config
+install, sub-five-minute cold start, timing evidence, ≤20 s demo GIF;
+REQ-005 is the one item needing a core change, left Proposed) and
+`rac-growth-agent-skill` (REQ-001..004). Implemented the Claude Code
+skill at `.claude/skills/rac-artifacts/SKILL.md` per Anthropic's
+documented project discovery path, constrained to the host project's
+RAC directory. Measured cold start: ≈13.8 s machine time
+(`.agent-context/cold-start-timing.md`). Demo shot list recorded as the
+`growth-demo-gif` design (5 shots, 20 s).
+
+## Agent 3 — gap audit and contribution policy (re-scoped)
+
+Audited the existing corpus and recorded seven traceability gaps with
+3–4 concrete instances each (`.agent-context/gaps/agent3.md`). Authored
+`rac-growth-contribution-policy` (REQ-001..005): proposal-gated
+substantial changes modelled on OpenSpec's verified flow, draft
+CONTRIBUTING.md text embedded in the artifact body, the live file
+untouched, marked Blocked: GATE-2.
+
+## Agent 4 — essay–artifact bridge
+
+Authored `rac-growth-essay-bridge` (REQ-001..004, Blocked: GATE-1) and
+the `growth-essay-mapping` design: six Article 1 claims mapped to
+verified capabilities or explicitly flagged absences, least-promotional
+link placements, and five dogfood article slots (titles and one-line
+premises only). Zero prose written in the maintainer's voice.
+
+## Agent 5 — ecosystem seed
+
+Authored `rac-growth-extensibility` (REQ-001..005: entry-point
+discovery of third-party schemas/templates, byte-identical behaviour
+when absent, designed within ADR-012/015/021/024; GATE-2-blocked
+standalone-repo bundle convention draft embedded) and
+`rac-growth-ecosystem-list` (REQ-001..005). Created `docs/ecosystem.md`
+with exactly three verified entries (dogfood corpus, the
+`rac-artifacts` skill, `examples/guide/`) and no solicitation language.
+
+## Requirement artifacts created
+
+| Artifact | Id | REQs | Status |
+| --- | --- | --- | --- |
+| rac/requirements/rac-growth-positioning.md | RAC-KTYB8944G7TN | REQ-001..005 | Proposed |
+| rac/requirements/rac-growth-adoption.md | RAC-KTYB6QBZNTD0 | REQ-001..005 | Proposed |
+| rac/requirements/rac-growth-agent-skill.md | RAC-KTYB6R0DM280 | REQ-001..004 | Proposed |
+| rac/requirements/rac-growth-contribution-policy.md | RAC-KTYBCCTFG5JW | REQ-001..005 | Proposed, Blocked: GATE-2 |
+| rac/requirements/rac-growth-essay-bridge.md | RAC-KTYBHXKBWZGZ | REQ-001..004 | Proposed, Blocked: GATE-1 |
+| rac/requirements/rac-growth-extensibility.md | RAC-KTYBK6T1NQMY | REQ-001..005 | Proposed (bundle section GATE-2) |
+| rac/requirements/rac-growth-ecosystem-list.md | RAC-KTYBK7FSW6HS | REQ-001..005 | Proposed |
+
+Supporting corpus artifacts: `rac/roadmaps/future/growth-programme.md`
+(RAC-KTYB8RVVQ1HX, umbrella, links all of the above),
+`rac/designs/growth-demo-gif.md` (RAC-KTYB6RMYBQ5X),
+`rac/designs/growth-essay-mapping.md` (RAC-KTYBHY87XKV8).
+
+Non-corpus artifacts: README comparison section,
+`.claude/skills/rac-artifacts/SKILL.md`, `docs/ecosystem.md`,
+`.agent-context/` (brief, schema, timing log, five gap files, this
+summary, `GAPS_TRACEABILITY.md`).
+
+## Integration review results
+
+- `rac validate rac/`: 113 valid, 0 invalid, exit 0.
+- `rac relationships rac/ --validate`: 277 checked, 0 issues, exit 0.
+- `rac review rac/`: health 80/100, zero priority 1–2 findings.
+- Every produced artifact traces to a requirement (recorded in prose —
+  the structural link is itself gap 1 of `GAPS_TRACEABILITY.md`).
+- All competitor claims source-cited; the OpenSpec packaging quote and
+  contribution-model claims were independently re-verified against the
+  live README at integration. No uncited claim survived.
+- Gate check: `Blocked: GATE-1/GATE-2` markers present on all four
+  gated artifacts; grep confirms no gate-blocked content in README,
+  docs/, examples/, or the skill.

.agent-context/GAPS_TRACEABILITY.md

@@ -0,0 +1,130 @@
+# Traceability gaps — consolidated report
+
+Growth programme, 2026-06-12, corpus at v0.10.3. Twenty raw gap records
+from five agents (`.agent-context/gaps/agent1..5.md`) consolidate into
+eight schema gaps and two authoring-friction findings. Every instance
+cites a real file in this repository; none is speculative. The original
+programme framed this report as justification for "the v0.8.0
+traceability work"; that shipped as the v0.7.x relationships series
+(ADR-016), so each gap instead names the future work it motivates.
+
+The linking mechanisms that exist today: untyped `## Related <Type>`
+sections (corpus-internal, by id) and `## Supersedes` (decisions only).
+
+## 1. Links from artifacts to non-artifact repo files
+
+The most frequently hit gap — all five agents recorded it independently.
+
+- Instances: `rac-growth-positioning` REQ-001..005 are satisfied by a
+  README section it cannot reference; `rac-growth-agent-skill` REQ-001
+  is satisfied by `.claude/skills/rac-artifacts/SKILL.md`;
+  `rac-growth-ecosystem-list` governs `docs/ecosystem.md`; pre-existing:
+  `rac-documentation-structure` places testable requirements on eight
+  doc files by bare path, and `adr-027` governs four CI workflow files
+  the same way. Renames break these silently.
+- Minimal addition: an optional `## Related Files` (or `## Satisfied
+  By`) section accepting repo-relative paths, validated for existence
+  by `rac relationships --validate`.
+- Motivates: requirement→artifact traceability in a future
+  relationships milestone; also gives Guide's `get_related` a way to
+  answer "what file satisfies this requirement".
+
+## 2. External source and URL references as structured data
+
+- Instances: the README comparison table's competitor sources
+  (spec-kit, OpenSpec) live in an HTML comment invisible to validation
+  and MCP; Kiro's exclusion (docs returned HTTP 403 on 2026-06-12)
+  has no machine-readable "re-verify later" marker; the essay series
+  mapped in `growth-essay-mapping` is unpublished and external, so the
+  article side of every mapping row is an unresolvable label.
+- Minimal addition: an optional `## Sources` section, one URL per line
+  with an optional status token, extracted and exposed via
+  `get_artifact` (not fetched by the engine — determinism holds).
+- Motivates: evidence-grounded artifacts; staleness checking as a
+  deterministic review finding.
+
+## 3. Typed edge semantics (implements / satisfies / depends-on / derived-from)
+
+- Instances: `adr-028` invents unvalidated `### Implements`
+  sub-headings inside a non-schema section; the Explorer requirement
+  invents `### Depends On`; `v0.10.3-search-quality` lists the
+  decisions it implements (ADR-037/038) and the standing constraints it
+  must not break (ADR-007/027) in one flat `## Related Decisions` list;
+  `growth-essay-mapping`'s claim→capability mapping is unqueryable
+  table prose.
+- Minimal addition: validated optional edge-label sub-headings
+  (`### Implements`, `### Depends On`, `### Satisfies`) inside existing
+  `Related <Type>` sections, defaulting to untyped when absent.
+- Motivates: relationship semantics in a post-v0.10 series; directly
+  improves `rac relationships` output and `get_related` answer quality.
+
+## 4. Machine-readable lifecycle and gate status
+
+- Instances: `rac-product-intent-ci-watchkeeper` carries Status
+  "Deferred", outside any vocabulary, accepted silently; shipped
+  requirements still read "Proposed" with no transition to record;
+  this programme's GATE-1/GATE-2 markers are free-text lines
+  (`Blocked: GATE-2 (CLA not yet in place)`) in four artifacts —
+  nothing can enumerate "everything blocked behind GATE-1", and the
+  section-level block on `rac-growth-extensibility`'s bundle convention
+  is pure prose.
+- Minimal addition: a validated Status vocabulary for requirements
+  (Proposed | Accepted | Implemented | Deferred | Blocked) with one
+  reason line for Blocked.
+- Motivates: the review engine (`future/v1.1-review-engine`) and CI
+  Watchkeeper intent analysis, both of which need lifecycle state.
+
+## 5. Supersession outside decisions
+
+- Instances: `archive/v0.8.0-service-api.md` and
+  `v0.8.x-explorer/v0.8.0-explorer-foundation.md` both claim the v0.8.0
+  identity with no marker between them; the entire archived v0.9 plan
+  was replaced by `v0.9.x-watchekeeper/` via directory move only;
+  `v0.10.0-guide-foundation` supersedes the deleted `v1.2-mcp-server`
+  stub in prose that now dangles invisibly.
+- Minimal addition: permit `## Supersedes` on roadmap artifacts,
+  validated for target existence including archived targets.
+- Motivates: roadmap lifecycle hygiene; makes `archive/` queryable
+  instead of conventional.
+
+## 6. Relationship directionality and back-references
+
+- Instances: ADR-036 → v0.10.2 has no reverse edge; six early ADRs
+  cited by `rac-agent-context-guide` carry zero Related sections
+  themselves — an agent at the target cannot discover the citing
+  artifact.
+- Minimal addition: an advisory asymmetric-edge finding in
+  `rac relationships --validate` (no schema change).
+- Motivates: relationship-quality findings in the review engine.
+
+## 7. Scoping / applies-to
+
+- Instances: ADR-018 governs `rac/`; ADR-023 scopes itself to
+  `src/rac/` internals in bold prose; ADR-027 applies to the CI
+  workflows; ADR-033 applies to the Guide tool surface — none of these
+  scopes is data.
+- Minimal addition: an optional `## Applies To` section on decisions
+  accepting paths or component names.
+- Motivates: scoped grounding — Guide could serve "decisions that apply
+  to the file you are editing".
+
+## 8. Validation blind spots in relationship extraction
+
+- Instances: `## Related Artifacts` (a non-schema section) appears in
+  eight artifacts with display-name targets that resolve to nothing
+  while CI stays green; `rac-growth-agent-skill` links
+  `v1.4-claude-skills`, whose file classifies as Unknown type, and
+  validation reports 0 issues — targets are not type-checked.
+- Minimal addition: advisory findings for unrecognised `Related *`
+  sections and for targets resolving to Unknown or mismatched types.
+- Motivates: near-term `rac review` / relationships hardening; cheap
+  relative to the schema gaps above.
+
+## Authoring-friction findings (not schema gaps)
+
+- `[REQ-NNN]` statements cannot hard-wrap: continuation lines raise
+  `req-missing-id`, forcing one-line statements against the corpus's
+  72-column prose convention. Hit by three agents.
+- `rac new` does not create parent directories — the only zero-config
+  snag on the measured cold-start path (covered by Proposed REQ-005 in
+  `rac-growth-adoption`).

.agent-context/SCHEMA.md

@@ -0,0 +1,76 @@
+# RAC schema — extracted from the live codebase (v0.10.3, 2026-06-12)
+
+Source of truth: `docs/artifacts.md`, `docs/relationships.md`, `src/rac/`,
+`rac new` output. Do not invent fields beyond what is listed here.
+
+## Artifact model
+
+Five types, all plain Markdown. Type is **inferred from `##` section
+headings** (deterministic, case/whitespace-insensitive, 50% confidence
+threshold) — never declared. Frontmatter carries identity only:
+
+```yaml
+---
+schema_version: 1
+id: RAC-XXXXXXXXXXXX   # machine-generated, opaque (ADR-026)
+type: requirement       # requirement|decision|roadmap|prompt|design
+---
+```
+
+**Never hand-write an id.** Create artifacts with:
+
+```bash
+/tmp/racenv/bin/rac new <type> <output-path>
+```
+
+(The repo identity namespace `.rac/config.yaml` already exists; `rac new`
+mints the id and writes the canonical template.)
+
+## Sections per type
+
+| Type | Required | Recommended | Optional |
+| --- | --- | --- | --- |
+| Requirement | Problem · Requirements | Success Metrics · Risks · Assumptions | Related Decisions · Related Roadmaps · Related Prompts · Related Designs · Related Requirements |
+| Decision | Context · Decision · Consequences | Status · Category · Alternatives Considered | Supersedes · Related Requirements · Related Roadmaps · Related Designs |
+| Roadmap | Outcomes · Initiatives | Success Measures · Assumptions · Risks | Related Decisions · Related Requirements · Related Prompts · Related Designs |
+| Prompt | Objective · Input · Instructions · Output | Constraints · Examples · Evaluation | Related Requirements · Related Decisions · Related Roadmaps · Related Designs |
+| Design | Context · User Need · Design · Constraints | Rationale · Alternatives · Accessibility · Style Guidance · Open Questions | Related Requirements · Related Decisions · Related Roadmaps · Related Prompts |
+
+Validated decision metadata values:
+- `Status`: Proposed | Accepted | Superseded | Deprecated
+- `Category`: Architecture | Product | Process | Technical | Other
+
+Requirements convention in this repo: a `## Status` section (Proposed /
+Accepted style) and testable `[REQ-NNN]` statements under `## Requirements`.
+
+## Identity and relationships
+
+Id resolution order: explicit `## ID` section → `<letters>-<digits>`
+filename prefix (`adr-004-…` → `adr-004`) → filename stem. Case-insensitive.
+
+The ONLY linking mechanism is the `## Related <Type>` sections (one id per
+line) plus `## Supersedes` on decisions. Links are corpus-internal, by id.
+There is no mechanism for: links to non-artifact files (README sections,
+code, skills), typed edge semantics (derived-from, satisfies, applies-to),
+or machine-readable gate/blocked status. If you need one of these, record
+it as a gap (see BRIEF) — do not improvise frontmatter fields.
+
+## Directory layout (this repo's dogfood corpus)
+
+- `rac/requirements/` — long-lived capabilities (ADR-020), slug `rac-<area>.md`.
+  Existing: rac-agent-context-guide, rac-documentation-structure,
+  rac-product-intent-ci-watchkeeper, rac-product-knowledge-navigator-explorer,
+  rac-repository-review-mode, rac-trust-transparency.
+- `rac/decisions/` — `adr-NNN-slug.md` (next free number: adr-039).
+- `rac/roadmaps/<series>/` — `vX.Y.Z-slug.md`; `rac/roadmaps/future/` for unscheduled.
+- `rac/prompts/`, `rac/designs/` — descriptive slugs.
+- `docs/` — user documentation layer (ADR-022); `README.md` — entry point only.
+- `examples/guide/` — runnable MCP grounding example.
+
+## Validation commands (run before reporting done)
+
+```bash
+/tmp/racenv/bin/rac validate rac/                    # must exit 0
+/tmp/racenv/bin/rac relationships rac/ --validate    # must exit 0
+/tmp/racenv/bin/rac review rac/                      # no priority 1-2 findings
+```