@erclx/aitk 0.18.0 → 0.20.0

package/README.md

@@ -48,7 +48,7 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 - [Standards](.claude/context/standards.md): shared authoring conventions, synced to projects
 - [Snippets](.claude/context/snippets.md): reusable prompts for Claude and Gemini chat
 - [Tooling stacks](.claude/context/tooling.md): golden configs, seeds, and references per framework
-- [Design system](.claude/context/design.md): `DESIGN.md` token shape, extract skill, render command
+- [Design system](.claude/context/design.md): `DESIGN.md` token shape, extract skill and its two paths, render command
 - [Slides](.claude/context/slides.md): `SLIDES.md` source, layout catalog, render command, draft skill
 - [Transcripts](.claude/context/transcripts.md): fetch a YouTube transcript with metadata frontmatter via `aitk transcripts`
 - [Sandbox](.claude/context/sandbox.md): scenario-based scaffolds for verifying each domain flow

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-design-extract/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: claude-design-extract
-description: Drafts `.claude/DESIGN.md` from a project's existing prose and shell UI surfaces using the toolkit seed template. Reads CLAUDE.md, standards, docs, and CLI UI modules to codify visual intent already implicit in the project. Use when asked to "extract the design system", "draft DESIGN.md", "bootstrap design tokens", or "capture the visual system". Do NOT use to mutate an existing `.claude/DESIGN.md`.
+description: Drafts `.claude/DESIGN.md` from a project's existing prose and shell UI surfaces, or proposes token values from `REQUIREMENTS.md` and a `## Personality` section when no UI code exists yet. Use when asked to "extract the design system", "draft DESIGN.md", "bootstrap design tokens", "capture the visual system", "propose a design system", "bootstrap DESIGN.md from scratch", "draft tokens for a greenfield project", or "replace Claude Design onboarding". Do NOT use to mutate an existing `.claude/DESIGN.md`.
 ---
 
 # Design extract
@@ -10,23 +10,39 @@ description: Drafts `.claude/DESIGN.md` from a project's existing prose and shel
 - If `.claude/DESIGN.md` already exists and has content beyond the seed template, stop: `❌ .claude/DESIGN.md already populated. Edit directly or archive the existing file first.`
 - If `aitk` is not on PATH, stop: `❌ aitk CLI not found.`
 
-## Step 1: read source signals in parallel
+Step 1 carries two more stops that apply to one path only. Do not evaluate them before the path is picked.
 
-Read these from the project root, skipping any that do not exist:
+## Step 1: pick the path from what the project already has
+
+Check the project root for UI surfaces: `src/ui.ts`, `src/ui.tsx`, `src/components/**`, `scripts/lib/ui.sh`, and any `*.css`, `tailwind.config.*`, or `theme.*`.
+
+- Any match takes the source path. Existing code defines the system, so every filled cell traces to a value already in the tree.
+- No match takes the greenfield path. Nothing anchors a value, so every filled cell is a proposal and carries the tag that says so.
+
+The project decides this, never a user flag or an argument. Announce which path ran in one line before Step 2, since the two produce different-looking output from the same skill.
+
+The greenfield path needs a personality paragraph to propose against, and stops without one. The source path needs neither file and skips both stops.
+
+- If `.claude/REQUIREMENTS.md` is missing, stop: `❌ .claude/REQUIREMENTS.md not found. Write requirements before proposing a design system.`
+- If `.claude/REQUIREMENTS.md` has no `## Personality` section, stop: `❌ .claude/REQUIREMENTS.md missing ## Personality section. Add a paragraph describing voice and tone before running this skill.`
+
+## Step 2: read source signals in parallel
+
+Read these from the project root on both paths, skipping any that do not exist:
 
 - `CLAUDE.md`: voice, personality, spelling rules
-- `.claude/REQUIREMENTS.md`: worldview and non-goals that shape visual intent
+- `.claude/REQUIREMENTS.md`: the `## Personality` paragraph, worldview, non-goals
 - `.claude/standards/prose.md`: tone constraints
-- `src/ui.ts`, `src/ui.tsx`, `src/components/**`: color codes, typography, spacing constants
-- `scripts/lib/ui.sh`, `scripts/lib/*.sh`: ANSI color codes, frame glyphs, spacing conventions
-- `docs/agents.md`, `docs/index.md`: any output shape or framing rules already documented
-- Any `*.css`, `tailwind.config.*`, or `theme.*` file at the project root
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
 
+On the source path, also read the UI surfaces matched in Step 1 plus `docs/agents.md` and `docs/index.md` for output shape or framing rules already documented.
+
+On the greenfield path, also read `.claude/ARCHITECTURE.md` for platform, tech stack, and surface type. Do not scan `src/`, stylesheets, or UI modules. Step 1 already established they hold nothing.
+
 Run these reads in parallel. Do not speculatively recurse into every directory.
 
-## Step 2: fetch the seed template
+## Step 3: fetch the seed template
 
 Run this from the project root:
 
@@ -36,20 +52,38 @@ aitk claude seeds list --json | jq -r '.[] | select(.path == ".claude/DESIGN.md"
 
 Use the returned content as the target shape. Keep every section heading and every table header intact. The `aitk design render` parser depends on them.
 
-## Step 3: fill the template
+## Step 4: fill the template
+
+Walk each section once. Follow `.claude/standards/prose.md` throughout: no em dashes, no semicolons, no marketing buzzwords. Use commas or separate sentences instead.
+
+Mark any cell not traced to a source value by appending ` ? verify` inside the cell value, never as a trailing column. The cell stays inside the table shape: `| #ffffff ? verify |`. A trailing `| ? verify` after the row breaks the parser. A prose section takes its uncertainty inline instead, for example `Proposed 150ms ease-out, not yet confirmed.`, because a trailing tag on a sentence renders raw in the preview.
+
+On the source path, the tag marks the exception. On the greenfield path it marks nearly every cell, since the values are speculative until code or a designer anchors them.
 
-Walk each section once, pulling concrete signals from Step 1:
+### Source path
 
-- **Personality**: one paragraph. Transcribe what `CLAUDE.md` and `.claude/REQUIREMENTS.md` say about voice, tone, and visual feeling. Do not invent rules the source does not state. Follow `.claude/standards/prose.md`: no em dashes, no semicolons, no marketing buzzwords. If nothing matches, write a one-sentence placeholder ending in `? verify`.
+- **Personality**: one paragraph. Transcribe what `CLAUDE.md` and `.claude/REQUIREMENTS.md` say about voice, tone, and visual feeling. Do not invent rules the source does not state. If nothing matches, write a one-sentence placeholder ending in `? verify`.
 - **Color**: one row per role. Source hex values from the CLI UI files or stylesheets. If a role has no source signal, leave `Value` blank rather than guessing.
 - **Typography**: one row per role. Source families and sizes from stylesheet or theme config. Leave cells blank when no signal exists.
 - **Spacing**: fill the base unit and multipliers from stylesheet tokens or obvious repeated values in the UI code.
 - **Borders**: one row per role. Source from stylesheet or CSS variables.
 - **Motion** and **Iconography**: one line each. Default to `No animation.` and `No custom icons.` when no evidence exists.
 
-Mark any inferred cell by appending ` ? verify` inside the cell value, never as a trailing column. The cell stays inside the table shape: `| display ? verify | | | | |`. A trailing `| ? verify` after the row breaks the parser.
+### Greenfield path
+
+Anchor every proposal to a signal, never to a default. "Calm and dense" pins muted grays and tight spacing. A requirements non-goal of "no motion" makes Motion read `No animation.` with no tag. A CLI-only surface leans Typography monospaced and keeps Borders minimal.
+
+- **Personality**: transcribe the `## Personality` paragraph from `.claude/REQUIREMENTS.md` verbatim. This is the one section that is not a proposal. No tag.
+- **Color**: one row per role. Rewrite the Intent cell in personality language, for example `warm off-white page canvas` instead of the seed default `page canvas`. Propose hex values matching the personality. Dense and calm gives low saturation and high text contrast. Playful gives saturated accents. Every Intent and Value cell gets `? verify`.
+- **Typography**: one row per role. Propose families fitting the platform, system UI for web, monospaced for CLI tools, serif for editorial, and a harmonious scale. Every cell gets `? verify`.
+- **Spacing**: propose a base unit matching density intent. Dense gives a 4px base, roomy gives 8px. Keep the Multiplier column as the seed ships it, no tag. Only the Value column gets `? verify`.
+- **Borders**: propose radius and width per role. Sharp and technical gives a small radius, soft gives a larger one. Every Radius and Width cell gets `? verify`.
+- **Motion**: one line. Write `No animation.` when the requirements forbid motion. Otherwise phrase the uncertainty inline.
+- **Iconography**: one line. Propose style and source library matching personality, phrasing the uncertainty inline.
+
+Do not invent non-goals. A proposed motion line is fine when neither the personality paragraph nor the requirements rule motion out.
 
-## Step 4: write and render
+## Step 5: write and render
 
 Write the filled template to `.claude/DESIGN.md` from the project root. Then run:
 
@@ -65,5 +99,5 @@ The command writes an HTML plus CSS preview to `.claude/review/design/`. Output
 📝 Wrote .claude/DESIGN.md
 📝 Wrote .claude/review/design/index.html
 
-N cells marked `? verify`. Open the preview and confirm before committing.
+Ran the <source|greenfield> path. N cells marked `? verify`. Open the preview and confirm before committing.
 ```

package/claude/skills/claude-design-propose/SKILL.md

@@ -1,75 +1,15 @@
 ---
 name: claude-design-propose
-description: Drafts `.claude/DESIGN.md` on day one of a project from `REQUIREMENTS.md`, `ARCHITECTURE.md`, and a `## Personality` section, with token values proposed by the agent. Use when asked to "propose a design system", "bootstrap DESIGN.md from scratch", "draft tokens for a greenfield project", or "replace Claude Design onboarding". Do NOT use when UI code or stylesheets already exist. Reach for `claude-design-extract` instead.
+description: Retired. `claude-design-extract` absorbed this skill and now takes the greenfield path itself. Invoke `aitk:claude-design-extract` instead.
+disable-model-invocation: true
 ---
 
 # Design propose
 
-## Guards
+Retired. `claude-design-extract` absorbed the greenfield path, picks it from what the project has, and its description carries every trigger this skill used to route on.
 
-- If `.claude/DESIGN.md` already exists and has content beyond the seed template, stop: `❌ .claude/DESIGN.md already populated. Edit directly or archive the existing file first.`
-- If `.claude/REQUIREMENTS.md` is missing, stop: `❌ .claude/REQUIREMENTS.md not found. Write requirements before proposing a design system.`
-- If `.claude/REQUIREMENTS.md` has no `## Personality` section, stop: `❌ .claude/REQUIREMENTS.md missing ## Personality section. Add a paragraph describing voice and tone before running this skill.`
-- If `aitk` is not on PATH, stop: `❌ aitk CLI not found.`
+Invoke `aitk:claude-design-extract` instead. It reads `.claude/REQUIREMENTS.md` for the `## Personality` paragraph and `.claude/ARCHITECTURE.md` for platform signals when the project has no UI code, which is what this skill did.
 
-## Step 1: read source signals in parallel
+This body exists so a project that installed the plugin before the merge keeps resolving the old name for one sync cycle. It ships in `0.18.0` and is removed in `0.19.0`.
 
-Read these from the project root, skipping any that do not exist:
-
-- `.claude/REQUIREMENTS.md`: the `## Personality` paragraph, worldview, non-goals
-- `.claude/ARCHITECTURE.md`: platform, tech stack, surface type (CLI, web, desktop)
-- `CLAUDE.md`: voice rules, spelling, conventions
-- `.claude/standards/prose.md`: tone constraints if present
-
-Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
-
-Do not scan `src/`, stylesheets, or UI modules. This skill runs before code exists. If those files are present, the scenario is wrong and `claude-design-extract` is the correct tool.
-
-## Step 2: fetch the seed template
-
-Run this from the project root:
-
-```bash
-aitk claude seeds list --json | jq -r '.[] | select(.path == ".claude/DESIGN.md") | .content'
-```
-
-Use the returned content as the target shape. Keep every section heading and every table header intact. The `aitk design render` parser depends on them.
-
-## Step 3: propose tokens from personality and requirements
-
-Walk each section once. Follow `.claude/standards/prose.md` throughout: no em dashes, no semicolons, no marketing buzzwords. Use commas or separate sentences instead.
-
-Every proposed table cell is speculative, so every filled table cell gets a trailing `? verify` tag inside the cell value, never as a trailing column.
-
-Anchor proposals to signals, not defaults. If the personality says "calm and dense", that pins muted grays and tight spacing. If the requirements say "no motion", Motion writes `No animation.` with no tag. If the architecture names a CLI-only surface, Typography leans monospaced and Borders stays minimal.
-
-- **Personality**: transcribe the `## Personality` paragraph from `.claude/REQUIREMENTS.md` verbatim. This is the one section that is not a proposal. No tag.
-- **Color**: one row per role. Rewrite the Intent cell in personality language, for example `warm off-white page canvas` instead of the seed default `page canvas`. Propose hex values that match the personality. Dense and calm → low saturation, high text contrast. Playful → saturated accents. Every Intent and Value cell gets `? verify`.
-- **Typography**: one row per role. Propose families that fit the platform (system UI for web, monospaced for CLI tools, serif for editorial) and a harmonious scale. Every cell gets `? verify`.
-- **Spacing**: propose a base unit that matches density intent. Dense → 4px base. Roomy → 8px base. Keep the Multiplier column as the seed ships it, no tag. Only the Value column gets `? verify`.
-- **Borders**: propose radius and width per role. Sharp and technical → small radius. Soft → larger radius. Every Radius and Width cell gets `? verify`.
-- **Motion**: one line. If the requirements forbid motion, write `No animation.` If motion is allowed, phrase uncertainty inline, for example `Proposed 150ms ease-out, not yet confirmed.` Do not append a trailing `? verify` tag to a prose sentence. It renders raw in the preview.
-- **Iconography**: one line. Propose style and source library matching personality. Phrase uncertainty inline, for example `Proposed outline style, source library not yet chosen.` Do not append a trailing `? verify` tag.
-
-Do not invent non-goals. If the personality paragraph does not mention motion and the requirements do not forbid it, a proposed motion line is acceptable.
-
-A cell marked `? verify` must stay inside the table shape: `| #ffffff ? verify |`. A trailing `| ? verify` column breaks the parser.
-
-## Step 4: write and render
-
-Write the filled template to `.claude/DESIGN.md` from the project root. Then run:
-
-```bash
-aitk design render
-```
-
-The command writes an HTML plus CSS preview to `.claude/review/design/`. Output the path in chat so the user can open it.
-
-## Response format
-
-```plaintext
-📝 Wrote .claude/DESIGN.md
-📝 Wrote .claude/review/design/index.html
-
-N cells marked `? verify`. Open the preview, confirm the personality read as intended, then edit DESIGN.md directly to lock values.
-```
+`scripts/sandbox/claude/design-propose.sh` goes at the same time, but its fixture does not. That scenario is the only greenfield coverage the survivor has, so `0.19.0` folds it into `scripts/sandbox/claude/design-extract.sh` as a second arm rather than deleting it. Removing the file outright drops the greenfield path from the catalog.

package/claude/skills/create-snippet/SKILL.md

@@ -1,28 +1,13 @@
 ---
 name: create-snippet
-description: Creates a new snippet file in `snippets/` (toolkit repo) or `.claude/snippets/` (target project). Use when asked to create a snippet, add a snippet, or make a new snippet.
+description: Retired. `create-standard` absorbed this skill and writes snippets as well as standards. Invoke `aitk:create-standard` instead.
+disable-model-invocation: true
 ---
 
 # Create snippet
 
-Read these files in parallel:
+Retired. `create-standard` absorbed the snippet surface, resolves `snippets/` or `.claude/snippets/` the same way it resolves the standards folders, and its description carries every trigger this skill used to route on.
 
-- `${CLAUDE_SKILL_DIR}/references/snippets.md`: authoring conventions, invocation channels, use patterns
-- `.claude/standards/prose.md` from the project root: prose conventions for all generated text
+Invoke `aitk:create-standard` instead and ask for a snippet. The name understates what the skill covers, which is why its description names both surfaces.
 
-Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
-
-## Guards
-
-- If neither `snippets/` nor `.claude/snippets/` exists, stop: `❌ No snippets/ or .claude/snippets/ directory found.`
-
-## Steps
-
-1. Resolve the write surface: `snippets/` at the project root if present, the toolkit's own authoring source. Otherwise `.claude/snippets/`, a target project's installed copy.
-2. Confirm the slug and full content with the user before writing
-3. Write the file to `<surface>/<slug>.md`
-
-## After writing
-
-- Root surface (`snippets/`): this is the toolkit's authoring source. Remind the user `bun run check` regenerates the consumed copy under `.claude/snippets/`.
-- `.claude/snippets/` surface: the file is project-local. `aitk snippets sync` leaves it alone, since sync only updates filenames it recognizes from the toolkit. Remind the user to copy it to the toolkit repo, under `snippets/<category>/<name>.md`, if it should ship to every project.
+This body exists so a project that installed the plugin before the merge keeps resolving the old name for one sync cycle. It ships in `0.18.0` and is removed in `0.19.0`.

package/claude/skills/create-standard/SKILL.md

@@ -1,25 +1,29 @@
 ---
 name: create-standard
-description: Creates a new standard file in `standards/` (toolkit repo) or `.claude/standards/` (target project). Use when asked to create a standard, add a standard, or write a new authoring convention. Do NOT use to edit an existing standard.
+description: Creates a new standard file in `standards/` or `.claude/standards/`, or a new snippet file in `snippets/` or `.claude/snippets/`. Use when asked to create a standard, add a standard, write a new authoring convention, create a snippet, add a snippet, or make a new snippet. Do NOT use to edit an existing standard or snippet.
 ---
 
 # Create standard
 
+Creates one authoring file on either surface. Read the user's request for which artifact they asked for, standard or snippet, and carry that choice through every step below. Ask only when the request names neither.
+
 Read these files in parallel:
 
-- `.claude/standards/standard.md` from the project root: the meta-standard for a standard's shape, frontmatter, and structure
 - `.claude/standards/prose.md` from the project root: prose conventions for all generated text
+- `.claude/standards/standard.md` from the project root, for a standard: the meta-standard for shape, frontmatter, and structure
+- `${CLAUDE_SKILL_DIR}/references/snippets.md`, for a snippet: authoring conventions, invocation channels, use patterns
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
 
 ## Guards
 
-- If neither `standards/` nor `.claude/standards/` exists, stop: `❌ No standards/ or .claude/standards/ directory found.`
+- For a standard, if neither `standards/` nor `.claude/standards/` exists, stop: `❌ No standards/ or .claude/standards/ directory found.`
+- For a snippet, if neither `snippets/` nor `.claude/snippets/` exists, stop: `❌ No snippets/ or .claude/snippets/ directory found.`
 
 ## Steps
 
-1. Resolve the write surface: `standards/` at the project root if present, the toolkit's own authoring source. Otherwise `.claude/standards/`, a target project's installed copy.
-2. Draft the standard from the user's description, following `standard.md` for frontmatter, headings, and structure
+1. Resolve the write surface for the chosen artifact: the root folder (`standards/` or `snippets/`) if present, the toolkit's own authoring source. Otherwise the `.claude/` folder, a target project's installed copy.
+2. Draft the content from the user's description. A standard follows `standard.md` for frontmatter, headings, and structure.
 3. Confirm the slug and full content with the user before writing
 4. Write the file to `<surface>/<slug>.md`
 
@@ -27,5 +31,5 @@ Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the pro
 
 Emit the full path on its own line.
 
-- Root surface (`standards/`): this is the toolkit's authoring source. Remind the user to run `bun run check` to regenerate the consumed copy under `.claude/standards/` and the `standards/index.md` entry, and to add a row to the standards table in `.claude/context/standards.md`.
-- `.claude/standards/` surface: the file is project-local. `aitk standards sync` leaves it alone, since sync only updates filenames it recognizes from the toolkit. Remind the user to copy it to the toolkit repo, under `standards/<slug>.md`, if it should ship to every project.
+- Root surface: this is the toolkit's authoring source. Remind the user to run `bun run check` to regenerate the consumed copy under `.claude/`. For a standard, that pass also regenerates the `standards/index.md` entry, and the user adds a row to the standards table in `.claude/context/standards.md`.
+- `.claude/` surface: the file is project-local. `aitk standards sync` and `aitk snippets sync` leave it alone, since sync only updates filenames it recognizes from the toolkit. Remind the user to copy it to the toolkit repo, under `standards/<slug>.md` or `snippets/<category>/<name>.md`, if it should ship to every project.

package/claude/skills/{create-snippet → create-standard}/references/snippets.md

@@ -1,7 +1,7 @@
 ---
 title: Snippet reference
 description: Snippet reference and authoring conventions
-consumers: create-snippet
+consumers: create-standard
 ---
 
 # Snippet reference

package/docs/ai-workflow.md

@@ -126,24 +126,24 @@ Before the first feature session on a UI-heavy project, pick a design tier. The
 
 ## Skills
 
-| Skill                        | When to use                                                                                                            |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `aitk:claude-groundwork`     | Before a plan is warranted, measure an unknown in a scratch folder under `.claude/.tmp/groundwork/`                    |
-| `aitk:claude-feature`        | Before implementation, scan for conflicts and ambiguities                                                              |
-| `aitk:claude-roadmap`        | Sequence MVP scope into ordered versions in `.claude/ROADMAP.md`                                                       |
-| `aitk:claude-orchestrate`    | Assert the orchestrator role, refill the ready queue, and dispatch the roadmap, feature, and review skills             |
-| `aitk:claude-diagram`        | Draft per-kind mermaid entries under `.claude/diagrams/` from architecture and code, then verify each rendered image   |
-| `aitk:claude-design-propose` | Day one on a UI project, draft `.claude/DESIGN.md` from requirements. Use `claude-design-extract` if UI already exists |
-| `aitk:claude-review`         | In a fresh session, review all changes since main                                                                      |
-| `aitk:claude-pr-review`      | Review an open PR from an independent session, then close the review out against the commits added since               |
-| `aitk:claude-address-review` | Address PR findings and CI status, refresh stale docs, then push a follow-up                                           |
-| `aitk:claude-tasks`          | Add a task to `.claude/tasks/` or archive a shipped one out of the folder                                              |
-| `aitk:claude-docs`           | When decisions diverged from plan, update `.claude/` docs                                                              |
-| `aitk:claude-ui-test`        | After UI changes, generate and run e2e tests + visual checklist                                                        |
-| `aitk:claude-ux-audit`       | Audit existing UI surfaces for missing states, edge cases, inconsistencies                                             |
-| `aitk:claude-autoship`       | After plan approval, chain implement → verify → review → draft PR                                                      |
-| `aitk:systematic-debugging`  | When a test fails or bug surfaces, enforce root-cause investigation before fixes                                       |
-| `aitk:git-ship`              | Post-feature: sync docs, commit, rename branch, open PR                                                                |
+| Skill                        | When to use                                                                                                          |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `aitk:claude-groundwork`     | Before a plan is warranted, measure an unknown in a scratch folder under `.claude/.tmp/groundwork/`                  |
+| `aitk:claude-feature`        | Before implementation, scan for conflicts and ambiguities                                                            |
+| `aitk:claude-roadmap`        | Sequence MVP scope into ordered versions in `.claude/ROADMAP.md`                                                     |
+| `aitk:claude-orchestrate`    | Assert the orchestrator role, refill the ready queue, and dispatch the roadmap, feature, and review skills           |
+| `aitk:claude-diagram`        | Draft per-kind mermaid entries under `.claude/diagrams/` from architecture and code, then verify each rendered image |
+| `aitk:claude-design-extract` | Draft `.claude/DESIGN.md`, sourcing tokens from existing UI code or proposing them from requirements on day one      |
+| `aitk:claude-review`         | In a fresh session, review all changes since main                                                                    |
+| `aitk:claude-pr-review`      | Review an open PR from an independent session, then close the review out against the commits added since             |
+| `aitk:claude-address-review` | Address PR findings and CI status, refresh stale docs, then push a follow-up                                         |
+| `aitk:claude-tasks`          | Add a task to `.claude/tasks/` or archive a shipped one out of the folder                                            |
+| `aitk:claude-docs`           | When decisions diverged from plan, update `.claude/` docs                                                            |
+| `aitk:claude-ui-test`        | After UI changes, generate and run e2e tests + visual checklist                                                      |
+| `aitk:claude-ux-audit`       | Audit existing UI surfaces for missing states, edge cases, inconsistencies                                           |
+| `aitk:claude-autoship`       | After plan approval, chain implement → verify → review → draft PR                                                    |
+| `aitk:systematic-debugging`  | When a test fails or bug surfaces, enforce root-cause investigation before fixes                                     |
+| `aitk:git-ship`              | Post-feature: sync docs, commit, rename branch, open PR                                                              |
 
 ## Feedback routing
 

package/docs/target-projects.md

@@ -56,7 +56,7 @@ Keep the `## Scripts` table in `.claude/context/development.md` current as scrip
 Scaffold installs tooling and seeds. It does not fill the planning docs or the design system. Complete those before the first feature session:
 
 1. Fill `.claude/REQUIREMENTS.md` and `.claude/ARCHITECTURE.md`. The seed provides the files, the scope and decisions are yours to write.
-2. For a UI project, invoke `aitk:claude-design-propose` to draft `.claude/DESIGN.md` from the requirements and a `## Personality` section. Skip for non-UI projects.
+2. For a UI project, invoke `aitk:claude-design-extract` to draft `.claude/DESIGN.md`. With no UI code yet it takes the greenfield path and proposes tokens from the requirements and a `## Personality` section. Skip for non-UI projects.
 3. Optionally invoke `aitk:claude-diagram` to draft entries under `.claude/diagrams/` from the architecture and the requirements. One file per diagram kind, so a later refresh of one kind leaves the others untouched. It renders each diagram it writes to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds. A machine without a renderer still gets the diagrams and is told which check was skipped. Each entry records the commit and date it was last verified against, and `aitk:claude-docs` maintains that record on every ship: it annotates an entry whose cited code path left the tree and stubs a kind whose source signal arrived uncovered. The sweep writes frontmatter only, so a diagram's picture and prose change when you redraw them and at no other time.
 4. Start the feature loop. See [AI workflow](ai-workflow.md) for the per-feature sequence.
 

package/docs/visual-design-workflow.md

@@ -18,7 +18,7 @@ The default. `.claude/DESIGN.md` holds visual intent as prose plus token tables
 
 ### Seed shape
 
-The toolkit seed in `tooling/claude/seeds/.claude/DESIGN.md` ships a token-table template. The `aitk:claude-design-extract` skill drafts the file from a project's existing prose and CLI UI surfaces. `aitk design render` writes an HTML plus CSS preview to `.claude/review/design/` for eyeballing the current system without leaving Claude Code. See `.claude/context/design.md`.
+The toolkit seed in `tooling/claude/seeds/.claude/DESIGN.md` ships a token-table template. The `aitk:claude-design-extract` skill drafts the file, sourcing tokens from a project's existing prose and CLI UI surfaces, or proposing them from `.claude/REQUIREMENTS.md` and a `## Personality` paragraph when no UI code exists yet. `aitk design render` writes an HTML plus CSS preview to `.claude/review/design/` for eyeballing the current system without leaving Claude Code. See `.claude/context/design.md`.
 
 ### Tools
 
@@ -27,7 +27,7 @@ The toolkit seed in `tooling/claude/seeds/.claude/DESIGN.md` ships a token-table
 
 ### Skills
 
-- `aitk:claude-design-extract` to draft `.claude/DESIGN.md` from existing project signals
+- `aitk:claude-design-extract` to draft `.claude/DESIGN.md`, from existing project signals or from requirements alone on day one
 - `aitk:claude-ui-test` for e2e test generation after UI changes
 - `aitk:claude-ux-audit` for UX gap detection on existing surfaces
 - Anthropic's `frontend-design` plugin optional for light visual steering

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/lib/sandbox-path.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+
+# The sandbox tree lives outside the toolkit worktree. `scripts/sandbox/run.sh`
+# sets cwd to it for `claude -p`, and every `CLAUDE.md` between that cwd and the
+# filesystem root loads into the session. Under the repository the toolkit's own
+# instructions join that chain beside the seeded copy the scenario installed,
+# both carry the rule sending shared session scratch to the main worktree root,
+# and nothing decides which root wins. A session picking the toolkit writes its
+# output where no manifest reads it, so the run reports success while the verdict
+# reports no writes at all. `scripts/eval/run.sh` keeps its fixture outside the
+# repository for the same reason.
+#
+# Twin of `SANDBOX_DIR` in `src/commands/sandbox.ts`. The exec boundary rules out
+# a shared constant, so a change to the default lands on both sides.
+resolve_sandbox_dir() {
+  if [ -n "${AITK_SANDBOX_DIR:-}" ]; then
+    printf '%s\n' "$AITK_SANDBOX_DIR"
+    return 0
+  fi
+
+  printf '%s/aitk/sandbox\n' "${XDG_STATE_HOME:-$HOME/.local/state}"
+}
+
+# Collapses repeated separators and strips every trailing one, leaving a bare
+# root as `/`. Every comparison below is a string test, so `//` and `$HOME//`
+# would otherwise read as paths no rule names.
+normalize_sandbox_path() {
+  local path="$1"
+
+  while [ "$path" != "${path//\/\//\/}" ]; do
+    path="${path//\/\//\/}"
+  done
+
+  while [ "${#path}" -gt 1 ] && [ "${path%/}" != "$path" ]; do
+    path="${path%/}"
+  done
+
+  printf '%s' "$path"
+}
+
+# Whether `candidate` is `target` or a directory containing it. Removing the
+# former removes the latter, which is what makes an ancestor as dangerous as an
+# exact match.
+is_at_or_above() {
+  local candidate="$1"
+  local target="$2"
+
+  [ "$candidate" = "$target" ] || [ "${target#"$candidate"/}" != "$target" ]
+}
+
+# Prints the reason a location is unusable and returns non-zero, so the caller
+# reports one message naming the path rather than a bare refusal.
+#
+# Provisioning runs `rm -rf` on this path at three sites before staging, so the
+# test is an allowlist rather than a list of paths to refuse. A blocklist has to
+# name every system directory to be right once and stays wrong as soon as one is
+# missed, while requiring a strict descendant of the home directory or of the
+# temp root admits the default and every reasonable override and refuses `/`,
+# `/usr`, `/etc`, and `$HOME` itself without naming any of them.
+#
+# The repository test is separate and runs both ways. A path under the worktree
+# restores the ancestor chain the relocation removed, and a path above it is one
+# `rm -rf` away from deleting the repository. It resolves the main worktree root
+# rather than trusting `$PROJECT_ROOT`, since a linked worktree is itself inside
+# that root.
+assert_sandbox_dir_safe() {
+  local raw="$1"
+  local root="${2:-${PROJECT_ROOT:-$PWD}}"
+
+  if [ -z "$raw" ] || [ "${raw#/}" = "$raw" ]; then
+    printf 'AITK_SANDBOX_DIR must be an absolute path, got: %s\n' "${raw:-<empty>}"
+    return 1
+  fi
+
+  local dir home temp
+  dir="$(normalize_sandbox_path "$raw")"
+  home="$(normalize_sandbox_path "${HOME:-/root}")"
+  temp="$(normalize_sandbox_path "${TMPDIR:-/tmp}")"
+
+  if ! is_at_or_above "$home" "$dir" && ! is_at_or_above "$temp" "$dir"; then
+    printf 'Refusing %s as the sandbox. Provisioning removes the tree first, so the path has to sit under %s or %s.\n' "$raw" "$home" "$temp"
+    return 1
+  fi
+
+  if [ "$dir" = "$home" ] || [ "$dir" = "$temp" ]; then
+    printf 'Refusing %s as the sandbox. Provisioning removes the tree first, so the path has to sit under %s rather than be it.\n' "$raw" "$dir"
+    return 1
+  fi
+
+  local main_root
+  main_root="$(git -C "$root" worktree list --porcelain 2>/dev/null |
+    grep -m 1 '^worktree ' | cut -d' ' -f2-)"
+  main_root="$(normalize_sandbox_path "${main_root:-$root}")"
+
+  if is_at_or_above "$dir" "$main_root"; then
+    printf 'Refusing %s as the sandbox. Provisioning removes the tree first, and that path contains %s.\n' "$raw" "$main_root"
+    return 1
+  fi
+
+  case "$dir" in
+  "$main_root"/*)
+    printf 'Sandbox at %s sits inside %s, which puts the toolkit CLAUDE.md back on the session ancestor chain. Point AITK_SANDBOX_DIR outside the repository.\n' "$raw" "$main_root"
+    return 1
+    ;;
+  esac
+
+  return 0
+}

package/scripts/lib/ui.sh

@@ -6,6 +6,12 @@ if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
   exit 1
 fi
 
+# Resolved from this file's own location rather than `$PROJECT_ROOT`, because
+# `require_project_root` is what several scripts call before anything has
+# established a root.
+# shellcheck source=/dev/null
+source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/sandbox-path.sh"
+
 GREEN='\033[0;32m'
 RED='\033[0;31m'
 YELLOW='\033[0;33m'
@@ -46,7 +52,9 @@ guard_root() {
 }
 
 require_project_root() {
-  if [[ "$PWD" == *".sandbox"* ]]; then
+  local sandbox
+  sandbox="$(resolve_sandbox_dir)"
+  if [[ "$PWD" == "$sandbox" || "$PWD" == "$sandbox"/* ]]; then
     echo -e "${GREY}┌${NC}" >&2
     log_error "Execution restricted: Command cannot be run from inside the sandbox environment."
   fi

package/scripts/manage-sandbox.sh

@@ -8,6 +8,7 @@ export PROJECT_ROOT
 
 source "$PROJECT_ROOT/scripts/config.sh"
 source "$PROJECT_ROOT/scripts/lib/ui.sh"
+source "$PROJECT_ROOT/scripts/lib/sandbox-path.sh"
 source "$PROJECT_ROOT/scripts/lib/sandbox-git.sh"
 source "$PROJECT_ROOT/scripts/lib/sandbox-fixtures.sh"
 
@@ -135,8 +136,8 @@ validate_environment() {
     log_error "Sandbox directory not found at: $SANDBOX_DIR"
   fi
 
-  if [[ "$PWD" == *".sandbox"* ]]; then
-    log_warn "Detected execution inside .sandbox. Switching to project root..."
+  if [[ "$PWD" == "$SANDBOX" || "$PWD" == "$SANDBOX"/* ]]; then
+    log_warn "Detected execution inside the sandbox. Switching to project root..."
     cd "$PROJECT_ROOT" || log_error "Failed to switch to project root."
   fi
 }
@@ -324,7 +325,7 @@ finalize_sandbox_run() {
 cmd_clean() {
   log_step "Removing sandbox"
   rm -rf "$SANDBOX"
-  log_rem ".sandbox/"
+  log_rem "$SANDBOX"
   trap - EXIT
   close_timeline
   echo "" >&2
@@ -422,9 +423,14 @@ main() {
     log_error "Context error: you must run this command from inside the toolkit repository."
   fi
 
-  SANDBOX="$PROJECT_ROOT/.sandbox"
+  SANDBOX="$(resolve_sandbox_dir)"
   SANDBOX_DIR="$PROJECT_ROOT/scripts/sandbox"
 
+  local unsafe
+  if ! unsafe="$(assert_sandbox_dir_safe "$SANDBOX" "$PROJECT_ROOT")"; then
+    log_error "$unsafe"
+  fi
+
   if [[ "$1" == "reset" ]]; then
     reset_sandbox
     exit 0

package/src/commands/sandbox.ts

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
 import { join } from 'node:path'
 import type { Command } from 'commander'
 import { PROJECT_ROOT, execScript } from '@/exec'
@@ -28,6 +29,29 @@ import {
 
 const SANDBOX_DIR = join(PROJECT_ROOT, 'scripts', 'sandbox')
 
+/**
+ * The provisioned tree, as opposed to `SANDBOX_DIR` above, which holds the
+ * scenario scripts. It sits outside the toolkit worktree so the toolkit's own
+ * `CLAUDE.md` stays off the ancestor chain of the session `run.sh` spawns with
+ * cwd here.
+ *
+ * Twin of `resolve_sandbox_dir` in `scripts/lib/sandbox-path.sh`. The exec
+ * boundary rules out a shared constant, so a change to the default lands on both
+ * sides.
+ */
+function sandboxTree(): string {
+  const override = process.env.AITK_SANDBOX_DIR
+  if (override !== undefined && override !== '') return override
+
+  const state = process.env.XDG_STATE_HOME
+  const base =
+    state !== undefined && state !== ''
+      ? state
+      : join(homedir(), '.local', 'state')
+
+  return join(base, 'aitk', 'sandbox')
+}
+
 /**
  * Holds fixture content for scenarios rather than scenarios of its own.
  * Twin of the `-not -name fixtures` filter in `scripts/manage-sandbox.sh`.
@@ -224,7 +248,7 @@ function runCheck(
   // A sandbox that was never provisioned fails every path assertion, reading as a
   // skill that did nothing rather than a caller that ran check too early. The
   // whole point of a verdict is that it means what it says.
-  const sandboxDir = join(PROJECT_ROOT, '.sandbox')
+  const sandboxDir = sandboxTree()
   if (!existsSync(sandboxDir)) {
     logError(`No sandbox at ${sandboxDir}. Provision one with aitk sandbox.`)
     outro()

package/src/sandbox/expect.ts

@@ -141,9 +141,33 @@ function contentArray(value: unknown): ContentAssertion[] {
     if (typeof entry !== 'object' || entry === null) continue
 
     const record = entry as Record<string, unknown>
+
+    // Dropping a half-written entry rather than throwing is deliberate, and it
+    // reads as the opposite of the stray-key check below. An entry missing its
+    // path or pattern declares no assertion to lose, and `checkExpectation`
+    // fails an arm whose surviving declaration asserts nothing, so the vacuous
+    // pass is already closed one level up. A stray key is the reverse: the entry
+    // is well-formed and the declaration around it silently lost a key it
+    // appears to carry, which nothing downstream can see.
     if (typeof record.path !== 'string' || record.path === '') continue
     if (typeof record.pattern !== 'string' || record.pattern === '') continue
 
+    // A bare key written below a `[[content]]` header belongs to that table in
+    // TOML, not to the document, so a declaration listing `manual` or
+    // `max_turns` after its content blocks parses clean and silently asserts
+    // neither. The `claude/ui-test` arm shipped that way: a turn ceiling that
+    // never ran and five manual entries that never reached the unchecked count,
+    // while `aitk sandbox coverage` counted the arm as armed. Nothing at the
+    // top level can see the difference, so the check belongs here.
+    const stray = Object.keys(record).filter(
+      (key) => key !== 'path' && key !== 'pattern',
+    )
+    if (stray.length > 0) {
+      throw new Error(
+        `content entry for ${record.path} carries ${stray.join(', ')}. Move top-level keys above the first [[content]] block.`,
+      )
+    }
+
     assertions.push({ path: record.path, pattern: record.pattern })
   }
 
@@ -257,6 +281,20 @@ function checkWriteScope(
     }
   }
 
+  // A scope produces one result per write, so a run that wrote nothing produces
+  // none, and without this the declaration vanishes from the verdict entirely:
+  // no result, no skipped entry, and no contribution to the unchecked count that
+  // exists to surface exactly this. The `undefined` branch above cannot stand in,
+  // since `run.sh` always passes `--writes` and `readWrites` returns `[]` for an
+  // empty file. An arm whose output escaped the snapshot reads as a clean run,
+  // which is the vacuous pass the harness exists to remove.
+  if (writes.length === 0) {
+    return {
+      results: [],
+      skipped: ['write scope: the run wrote nothing, so no path was checked'],
+    }
+  }
+
   const globs = expectation.writeScope.map((glob) => new Bun.Glob(glob))
 
   return {

package/standards/bundled/snippets.md

@@ -1,7 +1,7 @@
 ---
 title: Snippet reference
 description: Snippet reference and authoring conventions
-consumers: create-snippet
+consumers: create-standard
 ---
 
 # Snippet reference