AI-native workspace: full roadmap (Phases 1-4)

.agents/skills/capture-learning/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: capture-learning
+description: After a PR merges, examine the completed change and decide whether permanent project knowledge should be preserved — a new ADR, an updated runbook, a changed command/dependency in .ai/, or an architecture doc that's now stale — then write it and clean up the task's handoff/context files. Use when the user says "capture learnings from this", "what should we document from this merge", after merging a PR, or when closing out a ticket.
+---
+
+# Capture Learning
+
+> Project values (ticket prefix, default branch, repo list) come from
+> `devrig.toml` and `AGENTS.md` at the workspace root — read them; never assume.
+
+Closes the loop in `AGENTS.md`'s lifecycle: implement → verify → review → PR →
+merge → **capture learning** → better context for the next task. This is the
+one point where the workspace's own knowledge improves from doing the work,
+instead of staying static until someone remembers to update a doc.
+
+## Usage
+
+`/capture-learning` — the merged PR/ticket is inferred from the current session or branch.
+`/capture-learning <PR-URL or TICKET-ID>` — explicit target.
+
+## Step 1 — Resolve what happened
+
+Gather, in parallel:
+
+1. The merged PR's diff and description: `gh pr view <num> --json title,body,files,commits` and `gh pr diff <num>` (same resolution as `/code-review`'s Step 1 if only a branch/ticket is given).
+2. The task's persisted context, if it exists: `.ai/context/<TICKET-ID>.json`.
+3. The task's handoff doc, if it exists: `knowledge/handoffs/<TICKET-ID>.md`.
+4. Any `/verify-change` evidence from this session.
+
+## Step 2 — Ask the reflective questions
+
+Go through each; answer from the actual diff/PR body, not speculation:
+
+| Question | If yes |
+|---|---|
+| Did we make an architectural decision (a real fork in the road, not just "how we implemented it")? | Draft an ADR — `/write-doc adr <decision>` |
+| Did we discover an operational lesson (something that would help whoever's on call next)? | Add/update a runbook — `/write-doc runbook for <task>` |
+| Did a command change (new script, changed test/build/lint invocation)? | Update `.ai/commands.yaml` and `AGENTS.md`'s Commands table |
+| Did a system or dependency relationship change? | Update `.ai/systems.yaml` and `AGENTS.md`'s Systems table |
+| Did we solve a recurring bug worth remembering? | Note it in the relevant architecture/runbook doc's known-gaps section (and remove the gap if it's now fixed) |
+| Did this make existing architecture/design documentation inaccurate? | Update that doc directly; bump its `last_reviewed` |
+
+If every answer is genuinely no, say so and stop — don't manufacture a doc
+for a purely mechanical change. Manufactured documentation is worse than none
+(it erodes trust in `authority: canonical`).
+
+## Step 3 — Confirm scope
+
+If more than one item came back "yes", list them and let the user pick via
+`AskUserQuestion` (multi-select) which to write now vs. skip — don't silently
+write everything without a chance to review the list first.
+
+## Step 4 — Write it
+
+For each confirmed item, follow `/write-doc`'s normal flow (template, frontmatter, style) — don't duplicate its logic here, just feed it the right doc type and content. Set `authorship: ai-assisted`, `human_reviewed: false` unless a human is actively co-authoring.
+
+## Step 5 — Close out the task's working state
+
+- If `knowledge/handoffs/<TICKET-ID>.md` exists, delete it (the task is done, not interrupted) or set `status: archived` if the team prefers keeping history.
+- If `.ai/context/<TICKET-ID>.json` exists, delete it — it's no longer useful once the task is merged.
+
+## Step 6 — Close the observability trail
+
+Write `.ai/runs/<TICKET-ID>/summary.md` — the final entry in that ticket's
+observability trail (see `.ai/README.md`): what was captured as permanent
+knowledge (with paths), what was skipped and why, and what was cleaned up.
+This closes the run; nothing else writes to `.ai/runs/<TICKET-ID>/` after this.
+
+## Step 7 — Regenerate and land
+
+1. If `.ai/systems.yaml` or `.ai/ownership.yaml` changed: `node scripts/generate-architecture-views.mjs`.
+2. `node scripts/build-knowledge-index.mjs`.
+3. Land all changes from this run on **one** branch (`<ticket-id>-docs-capture-learning`) and suggest `/raise-pr` — do not commit to the default branch.
+
+## Output
+
+Report what was captured (or "nothing worth capturing, here's why") and what was cleaned up (handoff/context files removed).

.agents/skills/check-knowledge-consistency/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: check-knowledge-consistency
+description: Compare the knowledge base and .ai/ config against actual repo state — ADRs vs implementation, architecture docs vs repos, runbooks vs scripts, documented API contracts vs actual routes, commands.yaml vs package.json, ownership.yaml vs CODEOWNERS — and report drift. Use when the user asks "are the docs still accurate", "find outdated documentation", "check knowledge consistency", or periodically as a health check.
+---
+
+# Check Knowledge Consistency
+
+> Project values (ticket prefix, default branch, repo list) come from
+> `devrig.toml` and `AGENTS.md` at the workspace root — read them; never assume.
+
+Combines a mechanical pass (fast, deterministic) with a semantic pass (needs
+an agent reading code) to catch documentation that's gone stale — the gap
+`scripts/detect-doc-drift.mjs` can't close on its own because it can't read code.
+
+## Usage
+
+`/check-knowledge-consistency` — checks everything.
+`/check-knowledge-consistency <system>` — scope to one system/repo.
+
+## Step 1 — Mechanical pass
+
+Run both, capture the output, don't re-derive what they already found:
+
+```bash
+node scripts/validate-knowledge.mjs
+node scripts/detect-doc-drift.mjs
+```
+
+## Step 2 — Semantic checks
+
+Run these per affected system/repo (in parallel where independent). Only
+check repos that are actually cloned locally — note as "not checked (repo not
+cloned)" for any that aren't, rather than skipping silently.
+
+**Commands ↔ package.json** — for each system in `.ai/commands.yaml`, read
+that repo's `package.json` `scripts` and confirm every referenced `npm run
+<script>` exists. Flag any command in `.ai/commands.yaml` that would fail.
+
+**Ownership ↔ CODEOWNERS** — if the repo has `.github/CODEOWNERS`, compare
+the paths/owners there against `.ai/ownership.yaml`'s `areas`. Flag areas
+whose owners disagree, and CODEOWNERS entries with no corresponding area.
+
+**Architecture docs ↔ repos** — for each `architecture/` doc's "Repos
+involved"/systems table, confirm every named repo still exists in
+`.ai/systems.yaml`/`devrig.toml`, and spot-check a few "Source pointers" —
+does the cited path/symbol still exist? Use `mcp__semble__search` or a direct
+file check, not a full re-read of the repo.
+
+**Runbooks ↔ scripts** — for each numbered step that runs a command or
+script, confirm the script/file it references still exists at that path.
+
+**API docs ↔ API routes** — for each documented endpoint/event in an
+as-built doc's "Contracts" section, `mcp__semble__search` the backing repo
+for that exact name. Flag anything not found (renamed/removed) and, if you
+have time, anything found in code but undocumented (new surface).
+
+**ADRs ↔ implementation** — for `accepted` ADRs touching a system under
+review, spot-check whether the "Decision" is still what the code actually
+does. Flag contradictions — don't assume an old ADR is still followed just
+because no one marked it superseded.
+
+## Step 3 — Report
+
+Group findings by drift type, most actionable first:
+
+```markdown
+## Knowledge consistency — <scope>
+
+### Mechanical (validate-knowledge / detect-doc-drift)
+<pass-through of Step 1's output, only if non-empty>
+
+### Commands vs package.json
+- <repo>: `.ai/commands.yaml` `test` runs `npm run test:unit`, but package.json has no such script — <file:line or "not found">
+
+### Ownership vs CODEOWNERS
+- <finding, or "consistent">
+
+### Architecture vs repos
+- <finding, or "consistent">
+
+### Runbooks vs scripts
+- <finding, or "consistent">
+
+### API docs vs routes
+- <finding, or "consistent">
+
+### ADRs vs implementation
+- <finding, or "consistent">
+```
+
+Omit a subsection only if it was genuinely not applicable (e.g. no CODEOWNERS
+file exists at all) — write "consistent" rather than omitting a section that
+was actually checked and found nothing wrong, so the reader knows it was
+checked.
+
+## Step 4 — Next step
+
+For each finding, suggest either `/write-doc` (doc needs updating) or
+`/capture-learning` (if this surfaced during a task's wrap-up) rather than
+fixing it inline here — this skill's job is to find drift, not resolve it.

.agents/skills/plan-task/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: plan-task
+description: Turn gathered task context into a written plan before touching code — goal, affected systems, relevant knowledge/ADRs, files likely to change, proposed changes, risks, test strategy, and documentation impact. Use for anything non-trivial (multi-repo, schema/auth/billing changes, unclear scope) after /start-task, or whenever the user asks to "plan this task" / "write a plan before implementing". Skip for small, well-scoped changes.
+---
+
+# Plan a Task
+
+> Project values (ticket prefix, default branch, repo list) come from
+> `devrig.toml` and `AGENTS.md` at the workspace root — read them; never assume.
+
+Produces a written plan an agent (or a human) implements against, instead of
+rediscovering context mid-implementation. Complements Claude Code's native
+plan mode — where available, presenting this plan through that flow (so the
+user gets the same approve/edit gate) is preferred over dumping it as chat
+text; on agent tools without a native plan mode, print it directly.
+
+## Usage
+
+`/plan-task` — uses context already gathered by `/start-task` in this session.
+`/plan-task <TICKET-ID or description>` — gathers context first if `/start-task` wasn't run.
+
+## Step 1 — Ensure context exists
+
+If `/start-task`'s "Context gathered" block is already in this session, use it.
+Otherwise check for a persisted bundle at `.ai/context/<ISSUE-ID>.json` (from
+a prior `/start-task` run, possibly in an earlier session) and use that. If
+neither exists, run `/start-task`'s Step 4 (Gather context) now — don't plan
+on a guess.
+
+## Step 2 — Read what retrieval found
+
+Per the retrieval policy in `AGENTS.md`: read the related ADRs and design
+docs found, not just their titles. Read enough of each likely-affected file
+to know its current shape — don't propose changes to code you haven't looked at.
+
+If retrieval found nothing relevant for a non-trivial task, say so explicitly
+in the plan rather than proceeding on assumptions.
+
+## Step 3 — Draft the plan
+
+```markdown
+## Goal
+
+<1-2 sentences: what this task achieves and why, from the ticket/request.>
+
+## Systems affected
+
+<rows from AGENTS.md's Systems table, plus anything depending on them.>
+
+## Relevant knowledge
+
+<knowledge/ docs read, with a one-line takeaway each — "none found" if genuinely none.>
+
+## Relevant ADRs
+
+<knowledge/decisions/ docs that constrain this work — "none found" if genuinely none.>
+
+## Files likely affected
+
+<repo/path — what changes there, one line each. Group by repo.>
+
+## Proposed changes
+
+<the approach, as concrete steps. Call out any alternative considered and why
+it lost, if there was a real fork in the road.>
+
+## Risks
+
+<what could go wrong — breaking changes, cross-repo coordination, migration
+order, rollback difficulty. "None identified" only if you actually checked
+POLICY.md's risk triggers and none apply.>
+
+## Test strategy
+
+<which suites run (per AGENTS.md's Commands table), and any new test coverage
+this task should add.>
+
+## Documentation impact
+
+<which knowledge/ docs need creating/updating, and whether this crosses
+POLICY.md's ADR-required list. "None" only if genuinely nothing changes.>
+
+## Confidence
+
+<High | Medium | Low — per POLICY.md's confidence/uncertainty reporting.>
+
+## Assumptions
+
+<anything taken as given without direct verification.>
+
+## Unverified
+
+<anything not directly checked — e.g. a config only readable in production.>
+
+## Human attention required
+
+<anything risky enough (per POLICY.md's risk levels) that a human should
+look closely before/while it's implemented — "none" only if the risk level
+is genuinely Low.>
+```
+
+Every claim in the plan should trace back to something actually read this
+session — retrieval hits, `AGENTS.md`, or the ticket. Mark anything unverified
+as `TODO(verify: ...)` rather than asserting it.
+
+## Step 4 — Get the plan approved
+
+Present the plan and wait for the user to approve, edit, or redirect before
+implementing. Treat this as a real gate, not a formality — a plan the user
+hasn't seen is not an approved plan.
+
+Once approved, write the final plan (as approved, including any edits the
+user made) to `.ai/runs/<ISSUE-ID>/plan.md` — the next entry in that ticket's
+observability trail (see `.ai/README.md`).
+
+## Step 5 — Hand off
+
+Once approved, implement against the plan directly, or note that
+`/verify-change` should run once implementation is done. Don't re-run context
+gathering mid-implementation unless the plan turns out to be wrong.

.agents/skills/raise-pr/SKILL.md

@@ -19,6 +19,10 @@ description: Raise pull requests for the current task — detects which workspac
 
 Detects which workspace repos have changes for the current task, creates the task branch where needed, commits and pushes, then creates a PR on GitHub for every affected repo.
 
+If `/verify-change` hasn't run yet this session, run it first — per
+`POLICY.md`'s Definition of Done, a PR shouldn't go up with unverified or
+failing checks. Include its evidence block in the PR description (Step 8).
+
 ---
 
 ## Step 1 — Recall the ticket context
@@ -187,30 +191,54 @@ Examples:
 
 ### Description
 
-Write a description aimed at an engineer reviewer. Structure it as follows:
+Write a description aimed at an engineer reviewer, evidence-based per
+`POLICY.md`'s Definition of Done — not just an assertion that it works.
+Structure it as follows:
 
 ```
-## What
+## What & why
 
 [1–3 sentence summary of what this PR does and why. Include the motivation or ticket context if inferable from commits.]
 
 ## How
 
 [Bullet list of the key implementation decisions — what was changed, added, or removed and the reasoning. Be specific: name files, functions, or APIs touched where helpful.]
 
-## How to test
+## Systems affected
+
+[Rows from AGENTS.md's Systems table that this PR touches, plus anything depending on them. One repo, one line if this is single-repo.]
+
+## Testing
+
+[Step-by-step instructions a reviewer can follow to verify the changes work — setup steps, the flows to exercise (happy path + at least one edge case), expected outcome. Then the /verify-change evidence block if it was run this session:]
+
+Unit tests: PASS — `<command>`
+Lint: PASS — `<command>`
+Typecheck: PASS — `<command>`
+Build: PASS — `<command>`
+
+## Risks
+
+[Breaking changes, cross-repo coordination, migration/deploy ordering, rollback difficulty — per POLICY.md's risk levels. "None identified" only if you actually checked and none apply.]
+
+## Documentation
 
-[Step-by-step instructions a reviewer can follow to verify the changes work. Include:
-- Setup steps if any (migrations, env vars, seed data)
-- The specific flows to exercise (happy path and at least one edge case)
-- What the expected outcome looks like]
+[knowledge/ docs added or updated, with paths — or "Not required: <reason>".]
+
+## ADR
+
+[knowledge/decisions/NNNN-<slug>.md if POLICY.md's ADR requirement applies — or "Not required: <reason>".]
+
+## Rollback
+
+[How to revert if this ships a problem — usually "revert this PR", but call out anything that makes rollback harder (irreversible migration, a mobile client that can't be force-upgraded).]
 
 ## Concerns / notes
 
-[Any risks, trade-offs, known limitations, or things the reviewer should pay special attention to. If there are none, omit this section entirely.]
+[Any trade-offs, known limitations, or things the reviewer should pay special attention to that don't fit above. If there are none, omit this section entirely.]
 ```
 
-Populate each section from the commit messages, diff, and any context available. Do not leave placeholder text — if a section has nothing meaningful to say, omit it rather than filling it with filler.
+Populate each section from the commit messages, diff, `/verify-change`'s evidence (if run this session), and any context available. Do not leave placeholder text — if a section has nothing meaningful to say, write the explicit "Not required"/"None identified" form shown above rather than omitting it silently (the reviewer should see that it was considered, not guess). `Concerns / notes` is the one section that's fine to omit entirely when empty.
 
 ---
 
@@ -291,3 +319,9 @@ Print the full PR URL for every affected repo:
 > - repo-b: https://github.com/<owner>/repo-b/pull/<number>"
 
 If the CLI returned a URL, use that directly. If only a PR number was returned, construct the URL from the known owner/repo/number.
+
+---
+
+## Step 11 — Record changed files
+
+For each affected repo, append `git diff --stat $(git merge-base HEAD origin/<BASE>)..HEAD` to `.ai/runs/<ISSUE-ID>/changed-files.txt` (one section per repo, headed by the repo name) — the next entry in that ticket's observability trail (see `.ai/README.md`).