@erclx/aitk 0.8.0

package/claude/skills/claude-docs/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: claude-docs
+description: Updates `.claude/` planning docs to reflect decisions made during the session, marks outcomes the diff shipped `[x]`, and archives the plans those tasks cite. Use when design or requirements changed mid-cycle, after discussing a pivot, or before shipping. Do NOT use to create a task file or move one out of the live folder. That is `claude-tasks`.
+---
+
+# Claude docs
+
+## Guards
+
+- If no `.claude/` directory exists, stop: `❌ No .claude/ directory found. Run aitk claude init to set up the workflow.`
+
+The bail on a session that changed nothing lives at the end of Step 2, because it needs the diff to decide.
+
+## Diff baseline
+
+Steps 2, 4, and 7 share one diff on the usable path. An unusable baseline splits them, per the rule below. Resolve the base ref once and reuse it:
+
+```bash
+git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
+```
+
+Take the union of `git diff --name-only <base> HEAD`, `git diff --name-only HEAD`, and `git ls-files --others --exclude-standard`. Read content with `git diff <base> HEAD` and `git diff HEAD`.
+
+Prefer `origin/main` over local `main`. On `main` itself the local ref resolves to HEAD, so every committed change drops out of the set and the skill goes blind to the work it is meant to read.
+
+The baseline is unusable in two cases:
+
+- No merge base resolves against either ref.
+- The base came from local `main` and equals HEAD. Nothing is pushed to compare against, so a narrow read reports no changes rather than admitting it cannot see them.
+
+An unusable baseline costs only the committed half. `git diff <base> HEAD` is empty by definition once the base equals HEAD, while `git diff HEAD` and `git ls-files --others --exclude-standard` still report uncommitted and untracked work at correct scope.
+
+**Step 2 recovers the committed half.** Read `git log -p -1`, widening to `git log -p -<n>` when the session spans several commits, and read the candidate task files against the working tree. That yields names and content both, which is what lets Step 2 decide on behavior rather than on filenames. A fresh `git init` on `main` with no remote is the ordinary shape of a scaffolded project, so this path carries the evidence rather than covering an edge case.
+
+**Steps 4 and 7 keep the scoped set.** Run them on the working tree and untracked files alone, and skip only when that set comes out empty, each reporting the warning its own step names.
+
+Never substitute the whole tree for a missing baseline, and do not reuse Step 2's commit read in these two for consistency. On a fresh `git init` project the last commit is the scaffold commit, so `git log -p -1` is the whole tree by another route. Step 2 tolerates that because it only reads, and it matches conservatively against outcomes already on the board. These two write, so the same set stubs a wireframe for every uncovered surface in the repository and rewrites every context entry that tree touches.
+
+Widening what a step reads is safe. Widening what a step writes is not.
+
+## Step 1: read current docs
+
+Read these in parallel from the current worktree root (`pwd`), not the main worktree root. These are tracked files and edits must commit with the branch. Skip any that do not exist:
+
+- `.claude/REQUIREMENTS.md`
+- `.claude/ARCHITECTURE.md`
+- `.claude/DESIGN.md`
+- `.claude/wireframes/index.md` and every `.claude/wireframes/<surface>.md`
+
+Read the task board from the main worktree root instead, per Worktrees in `CLAUDE.md`. It is gitignored scratch and never commits with the branch:
+
+- `.claude/tasks/index.md` first, then the task files this session touched. That narrow read serves the marking step. Step 8 reads every file in the folder for its plans sweep and states that where it gives the instruction.
+
+## Step 2: identify what changed
+
+Two sources feed this step. The session carries judgments no diff can show. The diff carries facts about the repository the session may never have mentioned.
+
+Review the session for decisions that diverged from the original plan:
+
+- Requirements added, removed, or changed scope
+- Architecture or technical decisions made or revised
+- Design or UX decisions that differ from DESIGN.md or any `.claude/wireframes/<surface>.md`
+- Tasks blocked or newly identified
+
+Then resolve the diff baseline and match it against the board. From `.claude/tasks/index.md` at the main worktree root, pick the task files whose title or description relates to the changed paths and read the ones Step 1 skipped. Path matching only chooses which files to open. Behavior decides each outcome. For each unchecked outcome, decide whether the diff shipped the behavior that outcome names. Completion is the one judgment here that is a fact about the repository rather than a fact about the conversation, so the diff decides it and the session does not. Requirements, architecture, and design stay session-sourced.
+
+Keep the match conservative:
+
+- Mark only outcomes already written on the board. Never infer a new task from the diff.
+- Match on the behavior an outcome describes, not on filenames or commit subjects. The path match above only narrowed which task files to open.
+- Leave an outcome `[ ]` when the diff is ambiguous. An unmarked shipped outcome costs one manual edit, while a wrongly marked one hides work that never happened.
+
+Stop here when the session shows no divergence **and** the diff matches no queued outcome: `✅ No doc updates needed. Session matched the original plan.` Both conditions have to hold. Shipping a queued task exactly as planned is the ordinary case and it reads as no divergence, so a session-only bail would stop the skill before it reaches the marking step.
+
+## Step 3: update
+
+For each doc with relevant changes, apply updates following these rules. Read a standard this skill names, here or in Step 7, from `${CLAUDE_SKILL_DIR}/../../standards/` when the project does not have it.
+
+**`.claude/tasks/`**
+
+- Mark completed outcomes `[x]` in place in the task's own file. Do not move or archive the file.
+- Write a newly identified task as its own file, following `.claude/standards/tasks.md` for the filename and frontmatter.
+- Do not touch task files this session did not change.
+- Never hand-edit `.claude/tasks/index.md`. A hook regenerates it.
+
+**REQUIREMENTS.md, ARCHITECTURE.md, DESIGN.md, `.claude/wireframes/<surface>.md`**
+
+- Update only the sections affected by session decisions.
+- Do not rewrite sections unrelated to what changed.
+- Follow `.claude/standards/prose.md` for all edits.
+
+Write each updated file immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+
+## Step 4: wireframe coverage sweep
+
+Skip this step silently when `.claude/wireframes/` does not exist or has no surface files. When the baseline is unusable, scope it to the working tree and untracked files, and skip it only when that set is empty, reporting `⚠ No diff to scope against. Skipped the wireframe sweep.`
+
+Reuse the diff from the baseline above and filter for UI-affecting paths. UI-affecting paths are framework-dependent. Default heuristic: any file under a `components/`, `features/`, `pages/`, `app/`, `routes/`, or `screens/` folder, plus any `*.tsx`, `*.jsx`, `*.vue`, or `*.svelte` file anywhere in the diff.
+
+For each UI-affecting path, derive a candidate surface slug from the file's basename and parent folder (e.g. `web/src/features/mock/MockDemoStrip.tsx` → `mock-demo-strip` or `mock`). Cross-reference against the surface files in `.claude/wireframes/`:
+
+- **Contradicted sections:** when a surface file exists for a path in the diff and the diff renames or removes a literal string that appears in the wireframe prose (e.g. provider name, button label, copy string), output a one-line report entry and stop. Do not auto-rewrite prose. Operator resolves.
+- **Uncovered surfaces:** when a UI-affecting path has no matching surface file by slug, write `.claude/wireframes/<slug>.md` with this stub:
+
+  ```markdown
+  ---
+  title: <Slug as title case>
+  description: TODO: describe the surface.
+  ---
+
+  # <Slug as title case>
+
+  TODO: describe when and where this surface appears.
+
+  ## Behavior
+
+  - TODO
+  ```
+
+  Skip the write when the slug would collide with an existing file (different surface, same slug). Surface the collision in the report instead.
+
+Output one line per finding:
+
+- `⚠ Wireframe drift in .claude/wireframes/<surface>.md: <contradicted string>`
+- `📝 Stubbed: .claude/wireframes/<surface>.md`
+- `⚠ Slug collision: <slug> matches existing <existing-surface>.md, review and rename`
+
+If the sweep finds nothing, skip silently.
+
+## Step 5: flag diagram staleness
+
+If `.claude/DIAGRAMS.md` exists at `pwd` and this session edited any source `claude-diagram` reads (planning docs, deploy or infrastructure config, top-level component folders), surface a one-line warning:
+
+`⚠ DIAGRAMS.md may be stale. Run /claude-diagram`
+
+Do not regenerate inline. The author decides when to re-run the diagram skill. Skip the step silently when `.claude/DIAGRAMS.md` does not exist.
+
+## Step 6: flag CLAUDE.md drift
+
+If this session established or changed a cross-cutting behavior rule that belongs in root `CLAUDE.md` (a new always-on convention, a revised workflow rule), surface a one-line warning:
+
+`⚠ CLAUDE.md may need a rule from this session. Review and edit by hand.`
+
+Do not edit `CLAUDE.md` inline. Every `CLAUDE.md` change goes through the show-diff-and-approve gate, so this step only flags. Skip silently when the session made no cross-cutting behavior decision.
+
+## Step 7: refresh context entries
+
+Read `.claude/context/index.md` at `pwd` to see which domain entries exist. Skip this step silently if the directory does not exist or has no entries. When the baseline is unusable, scope it to the working tree and untracked files, and skip it only when that set is empty, reporting `⚠ No diff to scope against. Skipped the context refresh.`
+
+Reuse the diff from the baseline above, names and content both. For each existing `.claude/context/<domain>.md`:
+
+- Map the entry's section headings to the changed files. An entry is relevant when its prose references files, modules, or decisions touched by the diff.
+- For each relevant entry, rewrite only the sections affected by the diff. Same pattern as `docs-sync`. Do not touch unrelated sections.
+
+Do not create new entries automatically. New entries are a deliberate decision: the user invokes `claude-docs --new-context <domain>` (future flag) or hand-creates the file following `.claude/standards/context.md`. Auto-creation risks padding `.claude/context/` with low-signal entries.
+
+Write each updated entry immediately. Output one line per file:
+
+`✅ Context: .claude/context/<domain>.md`
+
+The base lint-staged config runs `aitk indexes regen` on every committed `*.md`, so `.claude/context/index.md` refreshes automatically on commit. No manual step needed.
+
+## Step 8: sweep consumed scratch
+
+Sweep reviews this session consumed, and sweep plans across the whole board. Resolve all paths at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
+
+**Plans.** Scan every file in `.claude/tasks/`, not only the ones this session touched. For each task file whose outcomes are now all `[x]`, check for a `Plan:` line directly under the title and parse the target. The line carries a markdown link, so read the target out of the parentheses rather than taking the rest of the line. A task still carrying the older bare-path form parses the same way once the link is absent, so accept both. Resolve the target against `.claude/tasks/` before routing on it, which lands `../plans/x.md` and `.claude/plans/x.md` on the same file. The bullets below name resolved locations, so an unresolved target falls to the last one and no plan is ever archived. Never delete a plan. `CLAUDE.md` owns why a shipped plan is archived rather than removed.
+
+Board-wide scope is the one place this sweep reaches past Step 3's rule against touching task files the session did not change. A board carrying a task that closed while an earlier run missed its archive is the defect this exists to clear, and skipping those tasks would preserve it. Reaching them is safe because the archive moves the plan and points the task at the new path, so a task from unrelated work ends up with a working pointer rather than a broken one.
+
+Before moving anything, count the other citations. Scan every `.claude/tasks/*.md` file except the one being processed for a `Plan:` line naming the same plan. Compare the resolved target from the parse above, never the raw target string and never the filename alone. A board carrying one task written `../plans/x.md` and another written `.claude/plans/x.md` cites one plan, and a raw string comparison reads two, counts zero, and archives the file out from under a live task. Comparing filenames swaps that for the opposite error, since a live plan and an archived one share a basename whenever a closed task still points into `.claude/.tmp/plans-archive/`, and the count then reads a citation that does not exist and archives nothing.
+
+Exclude the closing task explicitly. It sits on the board and cites the plan itself, so a scan that counts it never reaches zero and no plan is ever archived.
+
+A plan can serve more than one task, and archiving on the first task to close strands every other task's pointer at a path that has moved. `.claude/plans/` is gitignored, so that retarget would be the only record and there is nothing to recover it from.
+
+- Target resolves inside `.claude/plans/`, the file exists, and no other task file cites it: create `.claude/.tmp/plans-archive/`, move the file there under its original name, overwriting any file already sitting at that name. Then rewrite the task file's `Plan:` line to the archive path, so a completed task still leads to the reasoning behind it.
+- Target resolves inside `.claude/plans/` and at least one other task file cites it: leave the plan where it is and retarget nothing. Report the shared citation.
+- Target resolves inside `.claude/.tmp/plans-archive/`: skip silently. The plan was archived by an earlier pass and the task file is already correct.
+- Any other resolved target outside `.claude/plans/`: warn and skip.
+
+Write the retarget as a markdown link, `Plan: [feature-<slug>](../.tmp/plans-archive/feature-<slug>.md)`, updating both halves so the text and the target stay in step. This branch is the only writer that produces a `Plan:` line nobody authored by hand, so a retarget that emits a bare path converts every task to the old form as it closes and drifts the board back to two shapes on its own.
+
+**Reviews.** Derive `<slug>` from the current branch name (replace `/` with `-`). If `.claude/review/review-<slug>.md` exists, delete it. `claude-review` writes with this convention. Do not sweep any other `review-*.md` file.
+
+Do not sweep `ui-checklist-*.md` (pending human verification) or `ux-audit-*.md` (standalone deliverable).
+
+Output one line per file swept:
+
+- `📦 Archived: <path>` for a plan moved into `.claude/.tmp/plans-archive/`
+- `⏭ Kept: <path>, still cited by <task-file>` for a plan another live task shares
+- `🧹 Deleted: <path>` for a swept review
+
+If nothing qualifies, skip this step silently.
+
+## After completion
+
+Output one line per file updated:
+
+`✅ Updated: .claude/<filename>`
+
+If no files were updated and nothing was swept, output:
+
+`✅ No changes needed.`

package/claude/skills/claude-feature/REQUIREMENT.md

@@ -0,0 +1,35 @@
+---
+name: claude-feature
+description: What feature planning is for, the gaps it closes, and why it stops before implementing
+---
+
+# Claude feature requirement
+
+## Gap
+
+Without this skill, implementation starts before anyone knows what it touches. A session reads no project context and rediscovers a settled constraint halfway through, the file list emerges as the work goes rather than before it, and the ambiguities that needed a decision get resolved silently in whichever direction the first edit happened to go.
+
+## Must
+
+- Read the project's own Claude setup before scanning source, so the plan inherits decisions already made instead of reopening them
+- Name every file the work touches with the reason it is touched
+- Surface each unresolved ambiguity as a numbered question carrying a suggested answer and an empty answer slot, so the plan is decision-ready in one pass
+- Scale the output to the work. A two-file change with nothing to decide should not produce a plan file.
+- Stop at the plan and wait to be told to continue
+
+## Must not
+
+- Implement, or edit any file the plan describes
+- Read directories speculatively. Context spent on files the feature does not touch is context the plan does not get.
+- Bundle independent concerns into one plan, since a plan covering two things gets executed as neither
+- Restate the plan in chat during follow-up rounds. The file is the source of truth and a chat copy of it goes stale immediately.
+
+## Guards
+
+- No feature description: stop and ask for one
+
+## Out of scope
+
+- Executing the plan, which is the ship pipeline
+- Task-board state, which `claude-tasks` owns. A plan links to its task and does not create one.
+- Reconciling the planning docs after the work lands, which `claude-docs` owns

package/claude/skills/claude-feature/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: claude-feature
+description: Plans a feature by reading the project's Claude setup and scanning relevant source files. Outputs which files to touch, risks, and ambiguities, then stops. Use before implementing anything, or when asked to "implement X", "add X", "build X", or "I want to add X". Do NOT implement. Plan only.
+---
+
+# Claude feature
+
+## Guards
+
+- If no feature description is provided, stop: `❌ No feature description. Describe what you want to add.`
+- Do not implement anything. Output the plan and stop.
+- When the feature description spans two or more independent concerns, write one plan file per concern. Do not bundle them under a single slug.
+
+## Step 1: read the Claude setup
+
+Read these in parallel from the project root, skipping any that do not exist:
+
+- `CLAUDE.md`: behavior rules, conventions, commands
+- `.claude/REQUIREMENTS.md`: feature scope and non-goals
+- `.claude/ARCHITECTURE.md`: decisions already made
+- `.claude/tasks/index.md`: current scope and status, then any task file the feature relates to
+
+Also read these when the feature touches code or UI. Skip them for prose, docs, catalog, or config-only changes:
+
+- `.claude/DESIGN.md`: tokens, typography, spacing, and component rules
+- `.claude/wireframes/index.md` + the surface files relevant to the feature: intended UI layout and behavior. Read `index.md` first, then load only the per-surface files (`.claude/wireframes/<surface>.md`) the feature actually touches. Do not read the whole folder speculatively. When the plan adds or revises a surface, the wireframe file follows `.claude/standards/wireframes.md`, or `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md` when the project does not have it.
+
+Coding standards live in `.claude/rules/`. Claude Code loads them automatically. Path-scoped rules apply to the files they match.
+
+## Step 2: scan relevant source files
+
+Based on the feature description, identify and read source files that are directly relevant. Do not read entire directories speculatively.
+
+Measure against the tree rather than recall. Grep for each construct the plan will name and count the sites, so the plan carries the count the tree holds today. Confirm any work the plan sequences behind is still open, so it does not lead with an item that already shipped. Open each file before describing what is in it. A count or a claim carried from an earlier session, a summary, or another document is the most common way a plan ships the wrong scope.
+
+## Step 3: build the plan
+
+Construct the plan with these sections:
+
+- **Summary:** three to five one-line bullets covering the goal, the main deliverables, and the key trade-off or decision. Aimed at humans scanning the plan, not agents executing it. Full mode only.
+- **Constraints:** durable rules the work must respect (patterns to reuse, surfaces not to touch, platform limits). Optional. Include when an orchestrator or prior context supplies them, omit the section otherwise.
+- **Files to touch:** each file with a one-line reason
+- **Risks:** conflicts, coupling, or tricky spots. When the plan establishes a resource with more than one consumer, list the consumers and mark each read or write, because a policy stated over that resource has to hold for the writers and not just the consumer that prompted it. If none, use `None identified.`
+- **Questions:** numbered list of things to resolve before starting. Each carries a `- Suggested:` line and an `- Answer:` slot (see Suggestions below). If none, use `None identified.`
+
+Prefer `None identified.` over low-signal fillers. A small feature should produce a short plan, not a padded one. Small mode skips the summary since the plan is already short enough to scan in full.
+
+### Suggestions
+
+Attach a `- Suggested:` line to every question, then an empty `- Answer:` slot below it. A blank answer means accept the suggestion at execution time. This makes the plan decision-ready in one pass, with no separate decision-help round.
+
+- Apply senior judgment: pick the best option and state it in one line with its reason or main tradeoff. No padding, no alternatives unless they change the pick.
+- Suggest a real default when best practice, the codebase, or prior context points to one.
+- When the answer hinges on the user's preference or their intent is unclear, write `- Suggested: needs your call, <why>` rather than fabricating a technical default.
+
+When three or more questions remain, keep chat output to the file pointer plus a short summary. Inline chat is fine when two or fewer remain.
+
+## Step 4: output
+
+Decide the mode based on what Step 3 produced:
+
+- **Small** when the plan touches 2 files or fewer, has no architectural or cross-cutting choices, and both Risks and Questions come out `None identified.`
+- **Full** otherwise
+
+A consumer list is a `Risks` entry, which already forces Full. Establishing a resource with more than one consumer, where at least one writes, is a cross-cutting choice wherever that list ends up living, so such a plan stays Full even at two files.
+
+### Small mode
+
+Output the plan to chat. Do not write a plan file.
+
+```markdown
+**Files to touch:**
+
+- `path/to/file`: reason
+```
+
+If real questions exist, include a numbered `**Questions:**` section below, each with a `- Suggested:` line and an `- Answer:` slot:
+
+```markdown
+**Questions:**
+
+1. <question>
+   - Suggested: <pick>, <reason or tradeoff>
+   - Answer:
+```
+
+Omit empty sections. Do not print `None identified.` in chat.
+
+### Full mode
+
+Derive a 2-to-4-word kebab-case slug from the feature description. Write the full plan to `.claude/plans/feature-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist.
+
+File format:
+
+```markdown
+# Feature: <short title>
+
+<feature description>
+
+## Summary
+
+- <one-line bullet covering the goal>
+- <one-line bullet covering the main deliverables>
+- <one-line bullet covering the key decision or trade-off>
+
+**Constraints:**
+
+- <durable rule the work must respect>
+
+**Files to touch:**
+
+- `path/to/file`: reason
+
+**Risks:**
+
+- <risk>
+
+**Questions:**
+
+1. <question>
+   - Suggested: <pick>, <reason or tradeoff>
+   - Answer:
+```
+
+Then output in chat:
+
+```markdown
+📝 Wrote .claude/plans/feature-<slug>.md
+
+**Questions:**
+
+1. <question>
+   - Suggested: <pick>, <reason or tradeoff>
+
+Next: /claude-worktree
+```
+
+Show only the path line and the `Next:` line when there are no questions. The `.claude/plans/` directory is gitignored. Do not stage or commit the file.
+
+Do not proceed to implementation until the user explicitly says to continue.
+
+## Discussion rounds
+
+After the plan is written, the user may re-ping with follow-up questions or pushback. Keep chat output to a decision-help shape.
+
+- State each pick as one-line pick plus one-line reason. Do not use section headers, context blocks, or multi-section breakdowns in chat. Those belong in the plan file.
+- Put numbered decisions to resolve at the bottom of the response, not interleaved with findings.
+- When a finding needs more than two lines to explain, update `.claude/plans/feature-<slug>.md` in place with the detail and point the user at the file instead.

package/claude/skills/claude-groundwork/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: claude-groundwork
+description: Opens and runs a numbered groundwork folder under `.claude/.tmp/groundwork/<slug>/` for a topic that has to be measured before it can be planned. Detects open, resume, and close from the folder itself. Use when asked to "research X", "dig into X", "work out what we should do about X", "measure this before we commit", or "open a groundwork folder". Do NOT use to write a feature plan or to implement. That is `claude-feature`.
+---
+
+# Claude groundwork
+
+Groundwork gathers and weighs. A plan commits. A groundwork folder costs nothing to throw away, which is what makes it the right container for a question nobody has answered yet.
+
+Read `${CLAUDE_SKILL_DIR}/references/folder-format.md` before writing any file in the folder. It holds the reserved numbers, what each required file carries, the conventions, and the anti-patterns.
+
+## Guards
+
+- If no topic is given, stop: `❌ No topic. Name what needs measuring.`
+- Apply the qualifying test before creating anything. Two of these three must hold: the current state is not known, more than one approach is live, and committing wrong costs more than a day of measuring. When one or fewer holds, stop: `❌ Already decided enough to plan. Run /claude-feature instead.`
+- Do not pause for approval between steps. The write scope below is what makes that safe.
+
+## Write scope
+
+- Write only inside `.claude/.tmp/groundwork/<slug>/`. A feature plan, source changes, a standard, a rule, and a reference doc all live outside that folder, so this one rule forbids every one of them.
+- One exception, at close only: write one task file recording what the track concluded.
+- A second exception, for experiments: write a fixture a spike needs under `.claude/.tmp/groundwork-fixtures/<slug>/`. Keep it out of `.claude/.tmp/groundwork/` so mode detection never matches a fixture as a track. A fixture a headless run is pointed at goes outside the repository instead, per the rule in `## Running a spike`.
+- Reading is not restricted. External research is in scope, so read documentation, comparable projects, and papers whenever a live question needs them.
+- Every claim about a source outside the project carries a link to it. A source found and not read is listed as a lead and is never cited.
+- Treat the folder as gitignored and unbacked. It dies with the machine, so `07-next-session.md` repeats what it needs instead of pointing at its siblings.
+
+## Running a spike
+
+A track may run an experiment to settle an open question without stopping to ask. What it takes depends on what the experiment does.
+
+- Reading or computing: run it. Unrestricted reading already covers this, and it is what most spikes turn out to be.
+- Writing a fixture this session reads or provisions itself: run it, under the fixtures path above. Provisioning is the usual blocker rather than spend, and it costs nothing.
+- Spawning a billed headless session: run up to three, then ask before spawning more. The bound is a run count rather than a budget, because a headless run reports its total cost only after it finishes, so a dollar ceiling is reportable and not enforceable while a run count is checkable before spawning.
+
+A fixture a headless run is pointed at goes outside the repository, under `mktemp -d`, and never under `.claude/.tmp/`. A session started anywhere beneath the project root loads that project's `CLAUDE.md`, `.claude/rules/`, and `.claude/standards/` through the ancestor chain, so an in-repo fixture measures the repository instead of the arm. Record the fixture as contaminated and re-run it outside if this is discovered after the fact, because the result reads as evidence either way.
+
+Record method, result, measured cost, and caveats in `08-spikes.md`. Reach for a test harness the project already carries before building one, and copy how it isolates its fixture rather than only what it asserts.
+
+## Step 1: detect the mode
+
+List `.claude/.tmp/groundwork/` from the project root and match the topic against the tracks already there before deriving anything. A resume pass rarely phrases the topic the way the folder was named, so a fresh slug derived from the wording would miss a live track and restart it.
+
+Never match against `.claude/.tmp/` itself. That directory is scratch shared with every other skill, so a topic matched there lands on a folder that was never a track.
+
+With no match, derive a kebab-case slug named for the subject rather than the activity. Prefer `ts-migration` over `migration-research`. Then route on `.claude/.tmp/groundwork/<slug>/`:
+
+- Folder absent: open
+- Folder present without `06-decision.md`: resume
+- Present folder the user judges ready: close
+
+Detect the mode from the folder. Do not ask which one to run.
+
+## Step 2: orient
+
+Read these in parallel from the project root, skipping any that do not exist:
+
+- `CLAUDE.md`: behavior rules, conventions, commands
+- `.claude/REQUIREMENTS.md`: scope and non-goals
+- `.claude/ARCHITECTURE.md`: decisions already made
+- `.claude/tasks/index.md`: what is already tracked, and what a prior track concluded. Open a task file only when its entry looks related.
+
+Then read only what a live question needs. Do not read entire directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
+
+Do not dispatch subagents. A groundwork track is a conversation, and fanning out loses the reasoning that makes the folder worth keeping. A search too large to run inline is a finding that the question is too broad.
+
+## Open question format
+
+Every open question carries a lean, wherever it appears: inside a topic file, in `00-scope.md`, and in the chat output. A bare numbered list hands the reader a quiz and defers the judgment the track exists to inform.
+
+```markdown
+1. <question>
+   - Leaning: <where the evidence currently points>
+   - Overturned by: <the finding that would change it>
+```
+
+- `Leaning:` is weaker than a plan's `- Suggested:`. It records the current read on a question still open by definition, not a decision to accept by default at execution time.
+- Pair every lean with what would overturn it. A lean with no falsifier is an opinion.
+- On a measurement rather than a judgment, write `- Leaning: none, needs measuring` and drop the overturn line. A guess at a number is worse than an admission.
+
+## Open mode
+
+1. Create `.claude/.tmp/groundwork/<slug>/`.
+2. Write `README.md` first. Writing it first forces the question of what the track is for.
+3. Write `01-current-state.md` by measuring now. Never carry a figure from a previous session or from recall without re-measuring it. Measure only what an open question in the folder needs. A number with no question attached is how groundwork turns into the work.
+4. Write `00-scope.md` when the track is large enough to run away. Skip it on a small track.
+5. Add topic files at `02` through `05` as the subject demands. Close each one with its open questions in the format above.
+6. Keep going. Revise, reframe, and take correction as the questions move. The folder is meant to be rewritten.
+
+## Resume mode
+
+1. Read `README.md` and its file map first, then the numbered files in order.
+2. Do not re-measure what `01-current-state.md` holds unless the project moved under it. When it did move, re-measure and mark what changed.
+3. Continue from the open questions carried at the end of each file. Add or rewrite files as those questions move.
+4. Update the file map in `README.md` whenever a file is added or retired.
+
+## Close mode
+
+1. Write `06-decision.md`. It states the problem once, names the goal, lists what to do, and lists what was considered and dropped.
+2. Write `07-next-session.md` self-contained, so it survives a compaction that loses the conversation.
+3. Update the file map in `README.md`.
+4. Write one task file in `.claude/tasks/` recording what the track concluded, even when the conclusion is to do nothing. Follow `.claude/standards/tasks.md` for the filename and frontmatter, or `${CLAUDE_SKILL_DIR}/../../standards/tasks.md` when the project does not have it. Aside from an experiment fixture, this is the only write permitted outside the folder.
+5. Report uncited external claims. Closing already reads every file in the folder, so list any statement about a source outside the project that carries neither a link nor a lead entry. Report and do not block, because judging whether a sentence makes an external claim is the call a checker gets wrong.
+
+Do not close while an open question quietly fails an outcome. Resolve it, or record it in `06-decision.md` as knowingly accepted.
+
+## Output
+
+Emit the full relative path from the project root for every file written or updated. Bare filenames are not clickable.
+
+Open and resume:
+
+```plaintext
+📂 Opened .claude/.tmp/groundwork/<slug>/
+
+**Written:**
+
+- `.claude/.tmp/groundwork/<slug>/README.md`
+- `.claude/.tmp/groundwork/<slug>/01-current-state.md`
+
+**Open questions:**
+
+1. <question>
+   - Leaning: <where the evidence currently points>
+   - Overturned by: <the finding that would change it>
+```
+
+Use `📂 Resumed` in place of `📂 Opened` on a resume pass.
+
+Close:
+
+```plaintext
+✅ Closed .claude/.tmp/groundwork/<slug>/
+
+**Written:**
+
+- `.claude/.tmp/groundwork/<slug>/06-decision.md`
+- `.claude/.tmp/groundwork/<slug>/07-next-session.md`
+
+**Uncited external claims:** <count, or none>
+
+- `<file>`: <the claim>
+
+<the decision in one line>
+
+Next: /claude-feature
+```
+
+Omit the uncited-claims block when the count is zero.

package/claude/skills/claude-groundwork/references/folder-format.md

@@ -0,0 +1,107 @@
+---
+title: Groundwork folder reference
+description: Reserved file numbers, required file contents, and anti-patterns for a .claude/.tmp/groundwork/ folder
+---
+
+# Groundwork folder reference
+
+Applies to a groundwork folder at `.claude/.tmp/groundwork/<slug>/`. The numbering is the table of contents: a reader opens the folder and knows where to start and what follows, with no index maintained inside each file. Protect that first, because the instinct when adding a file mid-track is to name it for its topic instead.
+
+The folder is gitignored and unbacked. It dies with the machine, which is why the handoff file has to be self-contained.
+
+## Reserved numbers
+
+Five slots carry a fixed meaning. The rest are free, which is what lets the middle of a folder follow its subject.
+
+| Number       | Holds                                           | Required                    |
+| ------------ | ----------------------------------------------- | --------------------------- |
+| `00`         | Scope: constraints, risks, question list        | Large tracks only           |
+| `01`         | Current state, measured                         | Always                      |
+| `02` to `05` | Topic files, whatever the subject demands       | As needed                   |
+| `06`         | Decision                                        | To close                    |
+| `07`         | Handoff, self-contained                         | To close                    |
+| `08`         | Spikes: method, result, and cost per experiment | Tracks that run experiments |
+
+A folder missing `06` and `07` is live. That is the only status marker, and no separate tracking is needed.
+
+`08` sits after the closing files because it is an appendix. It holds evidence rather than a topic, so folding it into the `02` to `05` range buries it, and a track closes with or without one.
+
+## README.md
+
+Orients. Holds no findings.
+
+- A one-line definition of the investigation
+- The date opened
+- A `## Why` section stating why the track is running now
+- A file-map table of filename and what it holds, kept current as files are added or retired
+- A `## Method` section splitting internal sources from external ones, naming which were used and which were not yet done, and listing under a leads heading any external source found but not opened
+- A `## Prior art` section
+- A `## Source citation` section stating the rule below, so a returning session picks it up from the folder
+- The phase stated out loud in the first three lines, in the form `Groundwork phase. Nothing here is a feature plan.`
+
+The file map is how a returning reader re-enters. After the decision, it is the highest-value thing in the folder.
+
+Every claim about a source outside the project carries a link to it, wherever the claim appears in the folder. A sentence asserting that the vendor documents something reads the same whether it came from a fetched page or from recall, and a later reader can neither check it nor tell the two apart.
+
+A source found and not read is listed as a lead and is never cited. That half is what keeps the rule from producing citation theater, because a link attached to a page nobody opened is worse than no link. Listing it still pays, since it stops a later pass re-searching for what this one already surfaced.
+
+Where the track supersedes an earlier plan or an earlier folder, name it and say not to go looking for it. Without that, the old reasoning keeps circulating.
+
+## 01-current-state.md
+
+Facts before opinion. Verified measurement only, taken during this pass.
+
+- Never carry a figure from a previous session without re-measuring. Stale ratios survive a sunset that invalidates them, and every number built on top of one is quietly wrong.
+- Mark an inference as an inference where one is unavoidable.
+- Measure only what an open question needs. A number with no question attached is the mechanism by which the groundwork becomes the work.
+
+## 00-scope.md
+
+Written when the subject is large enough to run away. Holds constraints, risks, the open question list, and the downstream surfaces a decision would touch. A small track skips it and carries its questions inside the topic files.
+
+## 06-decision.md
+
+Closes the folder. Everything above it is input.
+
+- The problem stated once
+- The goal
+- The items to do
+- What was considered and dropped
+
+The dropped list pays off later. It is what stops a future session re-proposing something already rejected.
+
+## 07-next-session.md
+
+Written to survive a compaction that loses the conversation. It repeats facts held elsewhere in the folder rather than pointing at them. That duplication is correct here and wrong everywhere else.
+
+## 08-spikes.md
+
+Evidence by experiment, sitting beside the evidence by measurement `01-current-state.md` holds. Optional, and most tracks never open it, because measuring what is already there settles most questions.
+
+Each spike carries four things:
+
+- The open question it answers, named by file and number. A spike attached to no question is the same runaway the current-state file is capped against.
+- The method, stated fully enough for a later reader to re-run it. Name the fixture and where it lived, the exact command, and how many repetitions were run. A headless arm pointed at a fixture inside the repository measured the repository, so the fixture location is part of whether the result stands.
+- The result, and which question it closes. A spike that settles nothing is still recorded, so a later pass does not pay to learn the same thing twice.
+- The measured cost, and the caveats that bound what the result proves.
+
+Cost is a report rather than a limit, and it is what makes the next spike estimable before anyone commits to it. Record it even when it comes to a single read.
+
+Reach for a test harness the project already carries before building one. A track that needs an experiment no existing harness can express has found a finding, and it belongs in the folder rather than in a new abstraction.
+
+One method error is worth naming here, because it was made and corrected rather than imagined. Counting matches in a transcript overstates whether a file was read, since an instruction that names a path puts that path in the transcript whether or not anything opened it. The check is the tool call.
+
+## Conventions
+
+- Questions carry an open or answered marker, and open ones repeat at the end of the file they belong to. That gives `06-decision.md` its agenda for free.
+- Every open question carries a lean and what would overturn it, in the open question format in `SKILL.md`. A measurement question records that it needs measuring instead of guessing.
+- State a number with what it settles. The strongest sections are the ones where a measurement answers a named question and says so.
+- Send findings that would change an existing standard or rule to a backlog. Only a demonstrated failure changes one.
+- Let the file count follow the number of genuinely separable questions, not the importance of the topic. A large topic with one question is a small folder.
+
+## Anti-patterns
+
+- **The groundwork becomes the work.** Gathering expands until the measuring costs more than the change it justifies. Cap it, and drop any thread with no question attached.
+- **Deciding by omission.** Closing a track while an unresolved question quietly fails an outcome. Resolve it or record it as knowingly accepted.
+- **Recording a constraint discovered while defending a decision.** Check a constraint against the alternative design before writing it down, or a fact about the current shape gets written up as inherent to the problem.
+- **A plan written before the groundwork.** Every track that has done this had to supersede the plan it wrote.