@erclx/aitk 0.8.0

package/claude/skills/setup-indexes/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: setup-indexes
+description: Bootstraps the toolkit's `index.md` system in a target project. Scans for markdown-heavy folders, drafts `title` and `description` frontmatter, scaffolds `index.md` per chosen folder, and runs `aitk indexes regen` to validate. Use when asked to "set up indexes", "bootstrap indexes", "add index.md to this project", or "install indexes". Assumes the `aitk` CLI is on PATH.
+---
+
+# Indexes install
+
+Adds the index.md system to a project that does not have it. Operates in the active Claude session: Claude reads files, drafts frontmatter, confirms with the user, and writes. The CLI handles validation and regeneration only.
+
+Read `.claude/context/indexes.md` from the toolkit if context on the system is needed before scanning.
+
+## Scope
+
+- Bootstrap un-indexed folders only. Skip folders that already contain an `index.md`.
+- All-or-nothing per chosen folder. Every `*.md` sibling in a chosen folder gets `title` and `description` injected, or none does. Partial migration creates folders that hard-error on regen.
+
+## Scan
+
+Walk the project root for folders containing three or more sibling `*.md` files. Prune `.git`, `node_modules`, `.claude`, `snippets`, anything matched by `.gitignore`, and any folder that already contains an `index.md`.
+
+Skip `.claude/snippets/`. Snippets are invoked by reference (`@snippet-name`) rather than browsed, so they need neither `index.md` nor per-file frontmatter. Adding them creates noise that targets keep reporting.
+
+For each candidate, capture:
+
+- Folder path relative to project root
+- Sibling count
+- Existing frontmatter coverage (how many siblings already carry `title` and `description`)
+
+## Present candidates
+
+Output one line per candidate:
+
+```plaintext
+- docs/         (8 files, 0/8 with frontmatter)
+- guides/       (5 files, 2/5 with frontmatter)
+- references/   (3 files, 0/3 with frontmatter)
+```
+
+Ask the user which to bootstrap. Accept folder paths, `all`, or `none`. The user can also force a folder with fewer than three siblings by naming it explicitly.
+
+## Draft frontmatter
+
+For each chosen folder, read every `*.md` sibling and draft frontmatter:
+
+- `title`: derived from the first H1. If absent, derive from the filename in sentence case.
+- `description`: one line summarizing the file's purpose, drawn from the first paragraph after the H1. Follow `.claude/standards/prose.md` § Frontmatter descriptions for length and style, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it.
+
+Surface every drafted entry to the user grouped by file:
+
+```plaintext
+docs/architecture.md
+  title: Architecture
+  description: System boundaries, data flow, and module responsibilities
+```
+
+The user accepts, edits, or rejects per file. Offer "accept all remaining" once the user confirms two in a row to keep the loop short.
+
+Never write drafts before the user confirms. Drafted text is a proposal, not a commit.
+
+## Scaffold the folder index
+
+Compose `index.md` for each chosen folder with:
+
+```markdown
+---
+title: <folder name in sentence case, user-editable>
+subtitle: <one-line folder purpose, user-editable>
+---
+```
+
+Surface the proposed `title` and `subtitle` and let the user edit before writing.
+
+## Inject
+
+After all confirmations, write frontmatter into each sibling and `index.md` into each folder. Use a single batched write per file. Preserve existing content below the frontmatter block. If a sibling already has frontmatter without `title` or `description`, merge in the missing fields. Do not touch files the user rejected.
+
+## Validate
+
+Run from the project root:
+
+```bash
+aitk indexes regen --dry-run --json
+```
+
+Parse the JSON. On any `error` action, surface the file and reason and stop. On `would-write` for the bootstrapped folders, the dry-run is healthy. Run for real:
+
+```bash
+aitk indexes regen
+```
+
+Report the `written` count.
+
+## Offer the convention seed
+
+First check whether `CLAUDE.md` exists in the project root. If absent, do not scaffold one. Skip the seed install with this exact message:
+
+```plaintext
+No CLAUDE.md in the project. Skipping convention seed.
+To add the convention later, run `aitk tooling sync` or `aitk init`,
+then re-invoke this skill.
+```
+
+If `CLAUDE.md` exists, check it for an existing `## Indexes` section:
+
+```bash
+grep -l '^## Indexes' CLAUDE.md 2>/dev/null
+```
+
+If the section is present, skip the seed silently.
+
+If `CLAUDE.md` exists but has no `## Indexes` section, offer to install the canonical convention block. The text below is the source of truth and is mirrored in `tooling/claude/seeds/CLAUDE.md`. Paste it verbatim. Do not rewrite, paraphrase, condense, or add punctuation.
+
+```markdown
+- When a folder has an `index.md`, check it before reading individual files in that folder.
+- For folders where an agent browses to pick a document, `index.md` is regenerated from each file's frontmatter. Do not hand-edit `index.md`. Code folders and scratch folders do not need one.
+- Every `index.md` carries its own frontmatter (`title`, `subtitle`) that the walker preserves. To keep a folder's `index.md` hand-edited, add `auto: false` to its frontmatter.
+```
+
+Append a new `## Indexes` section at the end of the file containing the three lines. Do not touch any other section.
+
+## Closeout
+
+Always emit this block as the final message of the skill run. Do not skip it regardless of how the seed step concluded (installed, already present, declined, or skipped because no `CLAUDE.md` exists). Output exactly one closeout, even if the seed step paused for user input. Resume the flow after the user responds and emit the closeout next.
+
+Format:
+
+```plaintext
+Bootstrap complete.
+
+Folders bootstrapped:
+- <path> (<n> files)
+
+Drafts: <n> accepted, <n> edited, <n> rejected
+Convention seed: <installed | already present | declined | skipped (no CLAUDE.md)>
+
+Optional maintenance (opt in, the skill does not configure these):
+- lint-staged entry in .lintstagedrc.json:
+    "**/*.md": "aitk indexes regen"
+- Claude Code PostToolUse hook on Edit and Write matching **/*.md running:
+    aitk indexes regen
+```
+
+Replace bracketed values with the values from this run. Drop the "Folders bootstrapped" line if zero folders were chosen.
+
+## Reference
+
+- `.claude/context/indexes.md`: system rationale, frontmatter contract, when to adopt
+- `docs/agents.md`: `aitk indexes regen` flags, exit codes, JSON shape

package/claude/skills/setup-init/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: setup-init
+description: Detects a new project's type and runs `aitk init` with a resolved stack and snippets in one shot. Use when bootstrapping a new project with the toolkit, or when asked to "init this project", "bootstrap the toolkit", "set up toolkit", or "one-shot install". Assumes the `aitk` CLI is on PATH. Do NOT use when only installing governance rules. Use `setup-gov` instead.
+---
+
+# Init project
+
+Orchestrates the onboarding chain. Detects project type, resolves per-domain arguments, previews the chain, then runs `aitk init` with flags. The CLI holds the install logic. This skill only resolves and previews.
+
+## Scope
+
+- This skill and `aitk init` run once on a fresh scaffold, never on an existing project. They do not guard against clobbering existing configs. When tempted to add guards, mode switches, or an existing-project branch, stop. Extend the per-domain `aitk <domain> install` or `aitk sync` paths instead.
+
+## Read catalogs
+
+Run in parallel. Never hardcode stack, rule, snippet, or standards names. Run from the target project's current directory. Do not cd into the toolkit source tree. The `aitk` CLI is global.
+
+```bash
+aitk gov list --json 2>/dev/null
+aitk snippets list --json 2>/dev/null
+aitk standards list --json 2>/dev/null
+aitk tooling list --json 2>/dev/null
+```
+
+## Detect
+
+Read these from the project root in parallel, skipping any that do not exist:
+
+- `package.json`: `dependencies` and `devDependencies`
+- Root configs: `astro.config.*`, `next.config.*`, `vite.config.*`, `tailwind.config.*`, `tsconfig.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`
+- `.claude/REQUIREMENTS.md` and `.claude/ARCHITECTURE.md` if present
+- Directory structure via `ls -1` of the project root and `src/` if present
+
+## Resolve arguments
+
+- **Stack:** pick the closest governance stack by matching detected runtime or framework against stack names in the catalog. If nothing matches, fall back to `base`.
+- **Tooling stack:** pick the closest tooling stack from `aitk tooling list --json` (e.g. `vite-react`, `astro`). Distinct from the governance stack. Fall back to `base` if no framework match.
+- **Extras:** identify technologies not already covered by the picked stack. For each, find a rule whose `description` or `paths` points at that technology and pass it via `--add`. Do not add a rule the stack already pulls in.
+- **Snippets:** default to `all`. Narrow only if the user asked for a specific category.
+- **Skip (`--skip`):** `standards` and `wiki` are core and install by default. Add `--skip standards` or `--skip wiki` only when the user explicitly wants them left out.
+
+## Gap handling
+
+If a detected technology has no matching rule or stack, do not guess. Surface the gap and either:
+
+1. Defer to `setup-gov`. Author a rule in the toolkit, then re-run this skill.
+2. Proceed with the matched layer, listing the gap in the final report.
+
+Rules, snippets, and stacks are authored in the toolkit repo, never in the target project on the fly.
+
+## Preview
+
+Before executing, output:
+
+- **Detected:** each technology with its evidence file
+- **Stack:** picked governance stack + resolved rule count
+- **Tooling stack:** picked tooling stack
+- **Extras:** each `--add` rule with a one-line reason
+- **Snippets:** resolved category
+- **Skip:** any `--skip` entries with reason
+- **Target:** resolved target path
+- **Commands:** the full chain that will run
+
+## Execute
+
+Run the chain in order. Each step's permission dialog is the confirmation gate. Run from the target project's current directory.
+
+Step 1: `aitk init` installs base tooling, claude seeds, governance rules, standards, snippets, and wiki.
+
+```bash
+AITK_NON_INTERACTIVE=1 aitk init \
+  --stack <stack> \
+  --add <rules> \
+  --snippets <category> \
+  <target>
+```
+
+Omit any flag whose resolved value is empty.
+
+Step 2: `aitk tooling sync <tooling-stack>` installs stack deps, scripts, gitignore entries, seeds, golden configs, and drops the reference doc. The extends chain is walked, so syncing `vite-react` also pulls `web` and `base` configs. Skip if the tooling stack is `base` (already synced by `aitk init`).
+
+```bash
+AITK_NON_INTERACTIVE=1 aitk tooling sync <tooling-stack> <target>
+```
+
+Monorepo with multiple language roots: run `aitk init` once at the repo root so `base` (husky, prettier, cspell, commitlint, CI) lands single, then sync each subtree with `--skip base` so the shared layer is not re-dropped.
+
+```bash
+AITK_NON_INTERACTIVE=1 aitk tooling sync vite-react ./frontend --skip base
+AITK_NON_INTERACTIVE=1 aitk tooling sync python ./backend --skip base
+```
+
+Without `--skip base`, each subtree re-drops husky, and git honors only one `core.hooksPath`, so the extra hook dirs silently break. Each subtree keeps its own framework configs and its own `.claude/tooling/<stack>.md` audit docs.
+
+Step 3: post-sync fixups. Golden configs arrive from sync, so no config generation is required. But a few items may need a one-time touch:
+
+- **ESLint version pin.** If `bun create vite` installed `eslint@^10` and the manifest pins `eslint@^9`, sync does not override a present dep. Run `bun add -d eslint@^9` if `bun run lint:fix` fails with `Class extends value undefined`.
+- **File naming.** `bun create vite`'s `App.tsx` violates the `KEBAB_CASE` rule. Rename to `app.tsx` and update the import in `main.tsx`.
+- **Docs.** Open `<target>/.claude/tooling/<tooling-stack>.md` and `<target>/.claude/tooling/web.md` for any stack-specific follow-ups (Chrome extension overrides, setup script details).
+
+Do not generate ESLint, Vitest, or Playwright configs. They ship as golden files. Generating from prose duplicates what sync already installed.
+
+Step 4: invoke `setup-verify`. Runs the `package.json` scripts and reports pass/fail.
+
+## Report
+
+After the chain, report:
+
+- Domains installed with a check per domain
+- Tooling stack synced (or skipped). Name the layers pulled via the extends chain.
+- Any post-sync fixups applied (ESLint pin, filename renames)
+- `setup-verify` outcome
+- Any domains or scripts that failed
+- Any detection gaps surfaced during resolve

package/claude/skills/setup-plugins/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: setup-plugins
+description: Installs curated community and official Claude Code plugins user-scoped on the current machine via the `claude plugin` CLI. Use when asked to "install plugins", "set up plugins", "install the frontend/design/security/debugging plugins", "provision plugins on this machine", or when setting up Claude Code on a new computer. Do NOT use to install toolkit workflow skills, which load live via `--plugin-dir`. Assumes the `claude` CLI is on PATH.
+---
+
+# Setup plugins
+
+Automates plugin installs by reading the curated catalog, detecting what is already
+installed, and shelling out to the `claude plugin` CLI with `--scope user` so the
+plugins are available in every project on this machine.
+
+Domain-knowledge plugins install once per machine. They are not copied into any
+project. Toolkit workflow skills are a separate concern and load live through
+`--plugin-dir`, so never install those here.
+
+## Guards
+
+- If the `claude` CLI is not on PATH, stop: `❌ claude CLI not found. Install Claude Code first.`
+
+## Read the catalog
+
+Read the curated list from the skill folder. Use `${CLAUDE_SKILL_DIR}`, which
+expands to this skill's own directory, so the path resolves from any project. Never
+invent plugin names or install strings that are not in it.
+
+- `${CLAUDE_SKILL_DIR}/references/plugin-catalog.md`: verified plugins, marketplace sources, and the recommended default set
+
+## Detect what is installed
+
+Run this to skip plugins already present. Do not reinstall an installed plugin.
+
+```bash
+claude plugin list 2>/dev/null || echo "NONE"
+```
+
+## Select
+
+When plugin names are passed as arguments, install exactly those and skip the prompt.
+
+When invoked bare, present the catalog grouped by category with the recommended
+default marked, then ask which to install. Accept a bulk answer:
+
+- `recommended`: the default set from the catalog
+- `all`: every catalog row not already installed
+- a specific list of plugin names
+
+## Preview
+
+Before executing, output:
+
+- **Installed:** plugins already present, skipped
+- **To install:** each chosen plugin with its category and marketplace source
+- **Scope:** `user` (every project on this machine)
+- **Commands:** the exact shell commands to run
+
+## Execute
+
+For each chosen plugin, add its marketplace source if it is not already added, then
+install the plugin user-scoped. Run each install independently so one failure does
+not abort the batch.
+
+```bash
+claude plugin marketplace add <source> 2>/dev/null || true
+claude plugin install <name> --scope user
+```
+
+For a catalog entry listed under "Installs outside the claude plugin CLI", skip the
+marketplace step and run its installer command verbatim instead.
+
+Claude Code's tool permission dialog is the confirmation gate. Do not pause for a
+separate confirmation.
+
+## Response
+
+After execution, report:
+
+- Plugins installed, each with its marketplace
+- Plugins skipped as already installed
+- Any install that failed, with the CLI error
+- A reload note: installed plugins apply on the next session or after `/reload-plugins`
+- A tuning note: if a plugin over-triggers, set `skillOverrides` in settings to `name-only`, `user-invocable-only`, or `off` rather than uninstalling

package/claude/skills/setup-plugins/references/plugin-catalog.md

@@ -0,0 +1,53 @@
+---
+title: Plugin catalog
+description: Curated community and official Claude Code plugins that setup-plugins installs
+---
+
+# Plugin catalog
+
+Curated domain-knowledge plugins the `setup-plugins` skill installs user-scoped.
+Each row is verified to install through the `claude plugin` CLI. This file holds
+only the actionable install data.
+
+## Install data
+
+Add the marketplace source once, then install the plugin by name. The CLI resolves
+the plugin across added marketplaces, so `<name>@<marketplace>` is only needed to
+disambiguate a name that exists in more than one marketplace.
+
+| Plugin              | Category  | Marketplace source       | Why                                                                  |
+| ------------------- | --------- | ------------------------ | -------------------------------------------------------------------- |
+| `frontend-design`   | design    | `anthropics/claude-code` | Steers UI generation toward intentional typography, hierarchy, color |
+| `security-guidance` | security  | `anthropics/claude-code` | Security-aware authoring guidance during code generation             |
+| `code-review`       | review    | `anthropics/claude-code` | Multi-agent PR review across compliance, bugs, history, and comments |
+| `superpowers`       | debugging | `obra/superpowers`       | Methodology skills: systematic-debugging, root-cause-tracing         |
+
+## Recommended default
+
+The `design` and `security` categories cover the common gaps for a new machine.
+When the user asks for a recommended set, propose `frontend-design` and
+`security-guidance`. Offer `code-review` and `superpowers` as additions.
+
+`code-review` overlaps the toolkit's own `claude-review` skill. They run in
+different places, the plugin on a PR and the toolkit skill on a local diff. Install
+`code-review` only when the user wants the GitHub-side flow too.
+
+## Installs outside the claude plugin CLI
+
+Some strong plugins do not distribute through a marketplace, so the `claude plugin`
+path does not reach them. List them here with their real installer. Surface them to
+the user during selection, but do not run their install through the marketplace
+step above. Run the installer command verbatim only when the user picks it.
+
+| Plugin       | Category | Installer                       | Why                                                               |
+| ------------ | -------- | ------------------------------- | ----------------------------------------------------------------- |
+| `impeccable` | design   | `npx impeccable skills install` | Curated anti-slop reference files, sharper than `frontend-design` |
+
+`npx impeccable skills install` detects the Claude Code harness and installs into
+`.claude/`. It may prompt, so it is not fully non-interactive. After install, run
+`/impeccable init` and reload.
+
+Install per project, not per machine. The skill invokes its scripts through paths
+relative to the current project (`.claude/skills/impeccable/scripts/*.mjs`), so a
+copy under `~/.claude/` cannot locate them once the working directory is a
+different project. Re-run the installer in each project that wants impeccable.

package/claude/skills/setup-verify/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: setup-verify
+description: Verifies a freshly scaffolded project by running its `package.json` scripts in order and reporting pass/fail per script. Use after the agent has followed a tooling stack reference and generated configs, or when asked to "verify the scaffold", "check the setup", "run verify", or "make sure everything works". Do NOT use on a project without `package.json`, or to run E2E or dev servers.
+---
+
+# Verify scaffold
+
+Runs the local verification chain against a freshly scaffolded project. Catches config typos, missing deps, and wiring mistakes before the user ever sees them.
+
+## Guards
+
+- If `package.json` does not exist at the project root, stop: `❌ No package.json found. Cannot verify.`
+- If `node_modules/` does not exist, run `bun install` first, then proceed.
+
+## Step 1: read scripts
+
+Read `package.json` from the project root and extract the `scripts` block. Do not hardcode script names. Different stacks expose different scripts.
+
+## Step 2: run the chain
+
+Run the scripts below in order. Stop on the first failure and surface the error. Each script is a leaf command so failures point at the exact break.
+
+| Order | Script      | Skip if                     |
+| ----- | ----------- | --------------------------- |
+| 1     | `lint:fix`  | absent                      |
+| 2     | `typecheck` | absent                      |
+| 3     | `check`     | absent                      |
+| 4     | `test:run`  | absent, fall back to `test` |
+| 5     | `build`     | absent                      |
+
+Skip any script not present in `package.json`. Do not invent a fallback command. Do not run composite scripts like `check:full`. Do not run `dev`, `preview`, `test:e2e`, `test:ui`, `screenshot`.
+
+Run each as `bun run <script>` from the project root.
+
+## Step 3: report
+
+For each script run, report one of:
+
+- `✅ <script>`
+- `❌ <script>` followed by the failing output (last 40 lines)
+
+End with a summary line:
+
+- On pass: `✅ Scaffold verified (<n> scripts passed).`
+- On fail: `❌ Scaffold failed at <script>. Fix the error and re-run setup-verify.`
+
+## Out of scope
+
+- Dev server and preview server smoke tests. Too flaky for a scaffold check, where a slow start reads as a failure. Use `project-commands` to start one on request.
+- Playwright E2E tests. Require browser install and a running server.
+- CI workflow validation. Runs in GitHub Actions on PR, not locally.

package/claude/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: systematic-debugging
+description: Forces root-cause investigation before any fix when a test fails, a bug surfaces, or unexpected behavior appears. Auto-triggers on "test is failing", "it's broken", "why does X happen", "this isn't working". Do NOT use for trivial typo fixes or when the cause is already agreed on.
+---
+
+# Systematic debugging
+
+Random fixes waste time and create new bugs. Before proposing any fix, complete the four phases below in order.
+
+## The rule
+
+No fixes without root-cause investigation first. If phase 1 is incomplete, no fix may be proposed.
+
+## Phase 1: investigate
+
+1. Read every line of the error, stack trace, and log output. Note file paths, line numbers, error codes.
+2. Reproduce the failure. If it is not consistently reproducible, gather more data before guessing.
+3. Check what changed. Run `git diff` and `git log --oneline -10` from the project root to see recent changes.
+4. For multi-component systems, add instrumentation at each component boundary and run once to see which layer fails before investigating further.
+5. Trace bad values backward to their source. Fix at the origin, not the symptom.
+
+## Phase 2: find the pattern
+
+1. Locate similar working code in the same codebase. Compare it to the broken code line by line.
+2. If following a reference implementation, read it completely before adapting. No skimming.
+3. List every difference between working and broken, no matter how small.
+
+## Phase 3: hypothesize and test
+
+1. State one hypothesis: "I think X is the root cause because Y". Be specific.
+2. Make the smallest possible change to test it. One variable at a time.
+3. If the change does not resolve the issue, form a new hypothesis. Do not stack another fix.
+4. If you do not understand something, say so. Do not pretend.
+
+## Phase 4: fix
+
+1. Write a failing test case that reproduces the issue before fixing.
+2. Make one change that addresses the root cause. No bundled refactors, no "while I'm here" improvements.
+3. Verify the test passes and no other tests break.
+
+## Three-fix circuit breaker
+
+After three failed fix attempts, stop. This pattern indicates an architectural problem, not a bug:
+
+- Each fix reveals a new problem somewhere else.
+- Each fix requires refactoring elsewhere to apply.
+- Symptoms keep moving.
+
+When this happens, stop fixing and ask the user whether the underlying pattern should be reconsidered.
+
+## Red flags that mean "return to phase 1"
+
+- "Quick fix for now, investigate later"
+- "Just try X and see if it works"
+- "It's probably Y, let me change that"
+- Proposing a fix before tracing data flow
+- Adding multiple changes and running tests to see what sticks
+- Skipping the failing test "because I'll verify manually"
+
+Any of these means phase 1 is not complete. Return to it.
+
+## When investigation reveals no root cause
+
+Rarely, an issue is genuinely environmental, timing-dependent, or external. In that case:
+
+1. Document what was investigated and ruled out.
+2. Implement appropriate handling: retry, timeout, explicit error.
+3. Add logging so the next occurrence can be investigated.
+
+Most "no root cause" conclusions are incomplete investigations. Exhaust phase 1 before accepting them.

package/claude/skills/toolkit-cli/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: toolkit-cli
+description: Reference for what aitk sync and install commands overwrite, merge, or leave untouched in a target project. Use before running `aitk tooling`, `aitk standards`, `aitk claude sync`, or `aitk init`, or when asked "will this overwrite my changes". Do NOT use to run the commands, only to know their effect.
+---
+
+# Toolkit CLI contract
+
+What each `aitk` sync or install command does to existing files in a target project. Consult before running one, then warn the user about anything destructive. This skill is reference only. It does not run commands.
+
+## Overwrite contract
+
+| Surface                                                  | Command                  | Effect on existing files                                         |
+| -------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------- |
+| Golden configs (eslint, prettier, vite, tsconfig, ruff)  | `aitk tooling sync`      | Always overwritten. Local edits are lost. Drift is intentional.  |
+| Dictionary seeds (`.cspell/*.txt`)                       | `aitk tooling sync`      | Merged and sorted. Existing terms preserved.                     |
+| Other seeds (`cspell.json`, `.lintstagedrc`, state docs) | `aitk tooling sync`      | Copy-once. Dropped on first install, untouched after.            |
+| Standards                                                | `aitk standards install` | All overwritten.                                                 |
+| Standards                                                | `aitk standards sync`    | Only files already present are updated. None are added.          |
+| Seed docs and `CLAUDE.md`                                | `aitk claude init`       | Skipped when present. Never overwritten.                         |
+| Seed docs                                                | `aitk claude sync`       | Never touched. Only `.gitignore` is written.                     |
+| References (`.claude/tooling/<stack>.md`)                | `aitk tooling ref`       | Overwritten.                                                     |
+| `.gitignore`, deps, scripts                              | any sync                 | Additive. Existing entries preserved. Deps re-pin on major skew. |
+| Generated `index.md`                                     | any sync or regen        | Rewritten from target state. Hand edits are lost.                |
+
+## Rules
+
+- Before `aitk tooling sync`, know golden configs always overwrite. When the project carries local edits to a golden config, warn the user before running it.
+- Seeds are user-owned. Dictionary `.txt` files merge and sort. Other seeds are copy-once, so re-seeding a structured file means deleting it and syncing again.
+- Prefer `aitk standards sync` over `install` on an existing project. `install` overwrites every standard.
+- For section-level customizations of a standard or seed doc, use the `claude-seed-sync` skill, not `aitk ... sync`. It diffs per section and preserves edits.
+
+## CLAUDE.md
+
+- `CLAUDE.md` is a copy-once seed. No `aitk` sync command ever updates it. Reconcile it with the `claude-seed-sync` skill, which diffs the preamble and each section and preserves customizations by default.
+
+## Source of truth
+
+- Full semantics live in the toolkit's `.claude/context/tooling.md`, `standards.md`, and `claude-plugin.md`. This skill is the target-session summary. When they disagree, the context docs win.

package/claude/skills/toolkit-feedback/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: toolkit-feedback
+description: Format a paste-back report about something broken, missing, or off in aitk and write it directly to the toolkit's `.claude/review/` folder via `aitk feedback`. Use when asked to "send this to the toolkit", "report this to aitk", "file toolkit feedback", or "give the toolkit feedback about X". Do NOT use for general complaints about other tooling, IDE issues, or in-project bugs that do not implicate aitk surfaces.
+---
+
+# Toolkit feedback
+
+Format a `## Toolkit feedback` block from the current session, then ship it to the toolkit repo without manual copy-paste.
+
+## Guards
+
+- If nothing in session context points to a toolkit issue, stop: `❌ No toolkit issue in session context. Describe what broke, then re-invoke.`
+- If the surface type is ambiguous (snippet vs. plugin skill vs. CLI vs. seed), ask one line before formatting.
+- Do not probe the project, list files, grep, or read toolkit surfaces. Use only what the session already contains.
+
+## Step 1: build the block
+
+From the conversation so far, identify:
+
+- Target project name or path
+- Toolkit surface and its type (plugin skill, snippet, tooling config, governance rule, seed, or CLI)
+- Specific toolkit file or name when the session cites one
+- Observed behavior
+- Expected behavior, or `unclear`
+- Repro details already in context (commands run, files touched), or `none`
+- Proposed fix when the user stated one, or `open`
+
+Format as a single fenced markdown block:
+
+```markdown
+## Toolkit feedback
+
+**From project:** <name or path>
+**Surface:** <type>, <file path or name>
+**Observed:** <one or two lines>
+**Expected:** <one or two lines, or "unclear">
+**Repro:** <commands or steps, or "none">
+**Proposed fix:** <one line, or "open">
+```
+
+Keep each field to one or two lines. Write the literal fallback shown above when a field has nothing.
+
+## Step 2: ship to the toolkit
+
+Detect whether `aitk` is on PATH:
+
+```bash
+command -v aitk >/dev/null 2>&1
+```
+
+If present, pipe the block to `aitk feedback`. The CLI writes to its own repo's `.claude/review/feedback-<slug>-<ts>.md` and prints the absolute path on stdout:
+
+```bash
+cat <<'EOF' | aitk feedback
+## Toolkit feedback
+
+...
+EOF
+```
+
+Report the printed path back to the user on its own line so the terminal makes it clickable.
+
+For a durable, cross-machine report instead of local scratch, add `--github`. The CLI opens a GitHub issue on the toolkit repo and prints the issue URL. It needs `gh` authenticated, and falls back to local scratch with a warning when `gh` is absent.
+
+```bash
+cat <<'EOF' | aitk feedback --github
+## Toolkit feedback
+
+...
+EOF
+```
+
+Default to local scratch for a quick note. Use `--github` for a report worth tracking across sessions and machines.
+
+If `aitk` is not on PATH, fall back: print the block in chat and tell the user `📋 Copy the block above into a toolkit-repo session.`
+
+## Notes
+
+- `aitk feedback` resolves the toolkit root from the running `aitk` binary's source location. If multiple toolkit clones exist on the machine, the first `aitk` on PATH wins.
+- The destination `.claude/review/` is gitignored in the toolkit repo. Feedback lives as session scratch for the next toolkit-side triage, not as a durable archive.