@erclx/aitk 0.8.0

package/docs/ai-workflow.md

@@ -0,0 +1,157 @@
+---
+title: AI workflow
+description: Overarching AI workflow across domains
+category: Agent surface
+---
+
+# AI workflow reference
+
+A concise reference for when to reach for which tool, organized by what you're trying to do.
+
+> **Mental model:** Claude Code for everything: planning, implementation, review, docs, git, and release.
+
+## Documents
+
+Project docs live in `.claude/` at the project root.
+
+```plaintext
+.claude/
+├── REQUIREMENTS.md  ← goals, non-goals, MVP scope
+├── ARCHITECTURE.md  ← technical design decisions
+├── DESIGN.md        ← visual intent and token decisions (UI projects)
+├── WIREFRAMES.md    ← ASCII wireframes: layout, UI copy, and interaction rules (UI projects)
+├── tasks/           ← one file per task with a generated index.md, gitignored local scratch
+├── context/         ← per-domain narrative loaded on demand via index.md
+└── rules/           ← path-scoped governance rules, written by aitk gov install
+```
+
+Three tiers of context load with different cost: always-loaded (root `CLAUDE.md`, `.claude/REQUIREMENTS.md`, `.claude/ARCHITECTURE.md`), path-scoped lazy (`.claude/rules/<scope>.md` with `paths:` glob), and on-demand lookup (`.claude/context/<domain>.md` discovered via `.claude/context/index.md`). See [the context model](../.claude/context/context-model.md) for the full picture.
+
+Run `aitk init` to seed the `.claude/` directory, a root `CLAUDE.md` file, and `.claude/rules/` in one pass. `aitk init` chains claude init and governance install. Claude Code auto-loads every file in `.claude/rules/` at session start, applying always-on rules unconditionally and path-scoped rules to files matching their `paths:` glob.
+
+## Scenarios
+
+### Bootstrap a new project
+
+See [target projects](target-projects.md) for the scaffold decision, core domains and skips, and the full lifecycle across scaffold, add-a-domain-later, and upstream sync.
+
+### New feature
+
+One session works for most features. Prefer splitting across two sessions only when the feature is large enough that you want a cold, independent reviewer on the diff. Plan and implement in session 1, then review and ship in session 2.
+
+#### Session 1
+
+Work in Claude Code directly. It reads `CLAUDE.md` automatically and has full file access, no pasting needed.
+
+- When the current state is unmeasured and more than one approach is live, invoke `aitk:claude-groundwork` first. It opens a scratch folder under `.claude/.tmp/groundwork/<slug>/` and ends in a decision, which may be to do nothing. Skip it when the approach is already settled. A track may run experiments to settle a question, writing a fixture it reads itself under `.claude/.tmp/groundwork-fixtures/<slug>/` and spawning up to three billed headless runs before it asks. A fixture a headless run is pointed at sits outside the repository, since a session started under the project root inherits that project's `CLAUDE.md` and rules and would measure them instead of the arm.
+- Invoke `aitk:claude-feature` to scan for code-level conflicts and ambiguities, confirm approach before proceeding
+- Implement the feature, then Claude Code runs the commands defined in `CLAUDE.md`, fixes failures, and iterates until all pass
+- For UI changes, invoke `aitk:claude-ui-test` to generate and run Playwright e2e tests
+  End the session once the feature works and tests pass. Invoke `aitk:claude-docs` to capture any decisions made during implementation before closing.
+
+#### Session 2
+
+Start a fresh Claude Code session. The diff is sufficient context for both review and ship.
+
+- Invoke `aitk:claude-review` to review all changes since main and output a findings report
+- Fix any valid findings
+- Invoke `aitk:git-ship` to sync docs, commit by concern, rename branch, and open PR
+
+### Parallel features
+
+When features are independent, run them in parallel instead of sequentially. Use one git worktree per feature so each session has its own working tree and branch.
+
+- Create a worktree per feature, then start a Claude Code session in each
+- Invoke `aitk:claude-feature` in each session. Plans land at the main worktree root as `.claude/plans/feature-<slug>.md`, one per feature, no collisions. Small features stay in chat and skip the file.
+- Implement, verify, and review each feature independently. `claude-review` and `claude-ui-test` write per-branch files at the main worktree root (`review-<branch>.md`, `ui-checklist-<branch>.md`), so parallel sessions do not overwrite each other
+- Ship each worktree separately with `aitk:git-ship`
+- For full autonomy per worktree, invoke `aitk:claude-autoship` instead of the manual chain. Approve the plan, walk away, come back to draft PRs.
+
+To run several worktrees as a coordinated flow rather than ad hoc, assert the orchestrator role in one warm session with `aitk:claude-orchestrate`. It owns the roadmap via `aitk:claude-roadmap`, plans each feature, refills the ready queue so a free worker never waits, and reviews each worker's PR with `aitk:claude-pr-review`, while workers address the posted findings with `aitk:claude-address-review`. The human launches workers and merges. See [operating model](operating-model.md) for the full loop.
+
+Roadmap ownership holds while a scope exists to sequence. Once the MVP list in `.claude/REQUIREMENTS.md` has shipped, later work arrives as discrete items and the orchestrator reads `.claude/tasks/priority.md` for execution order instead.
+
+Run one orchestrator at a time. The board is gitignored, so a second session reads none of the first one's writes and the two collide on labels and archives. No fixed number caps the worker tracks underneath it. Collision between file sets is what binds, so a candidate opens only when its files are disjoint from every track in flight, and the ceiling in practice is how many outputs one session can still review properly.
+
+Before a handoff, the orchestrator checks the plan against the tree rather than reading it: grep each construct it names and count the sites, confirm every phase label it cites is still open, and open each file it describes. A plan goes stale from whatever merged after it was written, and reading cannot catch that.
+
+`.claude/plans/`, `.claude/review/`, and `.claude/memory/` all resolve at the main worktree root, so artifacts created in any session are visible from any sibling worktree. See [Claude Code and git worktrees](../wiki/claude-worktrees.md) for the full rule and the domain-level fan-out guidance.
+
+A plan that ships is archived, never deleted. `aitk:claude-docs` moves it to `.claude/.tmp/plans-archive/` and retargets the task file's `Plan:` line at the new location, so a completed task still leads to the reasoning behind it. Both folders are gitignored, which is why a deleted plan had no recovery path. A plan cited by more than one task stays put until the last of them closes, since moving it early would strand every other pointer.
+
+The sweep reads the whole board rather than the tasks the session touched. It is the one place the skill reaches past its own rule against editing a task file the session did not change, because a task that closed while an earlier run missed its archive is exactly what the sweep exists to clear. Reaching it is safe: the archive moves the plan and retargets the pointer in the same pass, so an untouched task ends up with a working link rather than a broken one.
+
+`aitk:claude-docs` decides which task closed by reading the diff rather than the conversation. It resolves a merge base against `origin/main`, unions the committed diff with the working tree and untracked files, then matches unchecked outcomes on the board against what shipped. A task that shipped without ever being discussed still gets marked. Requirements, architecture, and design stay session-sourced, because a diff cannot carry a judgment.
+
+`.claude/tasks/` is gitignored and resolves at the main worktree root, so every session shares one board. One file per task is what keeps concurrent sessions from overwriting each other, since a gitignored board has no history to recover a lost write from. Its `index.md` is generated by a hook rather than by `bun run check`, because the whole-repo index walk skips gitignored folders. A hand-maintained `priority.md` sits beside it carrying execution order and what each task is waiting on, which the alphabetical index cannot express.
+
+`aitk:claude-tasks` owns the two operations that bracket a task's life. It creates the file, holding the filename convention and the frontmatter contract so a malformed write cannot break the index for every sibling, and it moves a shipped task to `.claude/.tmp/task-archive/`. Creation is where the origin invariant is enforced: every task names a plan, a groundwork folder, or an issue, since a task with no origin is either lost context or work nobody decided to do. Archiving a task leaves its plan alone, because `aitk:claude-docs` owns the plans sweep and already holds the last-live-citation rule. That makes the order load-bearing, so the archive verb refuses to run while the `Plan:` line still points into `.claude/plans/`. The sweep only reaches tasks still in the live folder, and archiving the task first would strand the plan there with nothing citing it.
+
+Nothing chained that archive until the `post-merge` git hook landed. Every earlier step fires from `aitk:claude-autoship` or `aitk:git-ship`, both of which finish while the pull request is still open, so a task archived there would close for work that may be abandoned. The board is gitignored, which rules out reading it from anywhere but the machine that pulled. The hook names the board's archive candidates and stays silent otherwise, including on a project with no board.
+
+Candidates rather than closed tasks, because outcomes are marked on the branch. A task can read all `[x]` while its pull request is still open, so `aitk:claude-tasks` confirms the work reached `main` before it moves anything, and the hook's own output says that check is still owed. A companion `post-rewrite` hook carries the same announcement for anyone pulling with rebase, which fires that event instead of `post-merge`.
+
+It announces and moves nothing, so `aitk:claude-tasks` stays the only writer. A shell-side archive would change a gitignored board with no diff to review and no session watching, and `index.md` regenerates from a session hook that a shell `mv` never fires. Both hooks ship with the `base` tooling stack, so a target project running this workflow gets the same trigger.
+
+### Autonomous ship
+
+For features on a mature stack, chain the post-plan pipeline in one session. Approve the plan, invoke `aitk:claude-autoship`, and the skill runs implement → verify → review → ship sequentially.
+
+- Use when the plan is tight and the stack has real verify commands and test coverage
+- Autoship stops on: verify failure after one fix attempt, UI manual checklist non-empty, any review finding above minor, no diff baseline resolving against `main`, an empty changed-file list, or hook failure
+- Review is skipped entirely when the diff is prose-only (every changed file matches `*.md` or `*.txt`). Prose changes are gated by `docs-sync`, `claude-standards-audit`, and pre-push hooks.
+- An empty changed-file list stops the chain rather than counting as prose-only. The filename test passes vacuously on an empty set, which routed a branch past review instead of through it.
+- Every stop leaves recoverable state. Fix and resume with `/git-ship`
+- Skip autoship for auth, migrations, security-sensitive changes, or work where the plan itself is uncertain
+- After the PR is open, both `autoship` and `git-ship` invoke `claude-memory-capture` to write session patterns into `.claude/memory/`. If capture wrote at least one entry, `claude-memory-review` then proposes a decision-ready fix scoped to those captures while context is fresh, otherwise it is skipped. They stop at Propose. Review the receipt and run Apply yourself, on its own commit separate from the feature. Run `claude-memory-review` standalone to curate the whole pen.
+
+### UI polish
+
+Verify the change manually in the browser. Invoke `aitk:claude-ui-test` if you need e2e tests and a visual verification checklist for the session. For the fix itself, describe the change in Claude Code directly.
+
+### Quick fix
+
+- Verify failure or isolated bug → continue in Claude Code (it has the implementation context)
+- Design or planning conflict → escalate to a new Claude chat session with the relevant plan context
+- Fast file edit (a task file, config, renaming) → Claude Code directly, no chat needed
+
+### Review
+
+Invoke `aitk:claude-review` at the start of session 2. It reads all changed files and outputs a findings report. Fix valid findings before invoking `aitk:git-ship`. If nothing is valid, skip directly to ship.
+
+### UI-heavy project
+
+Before the first feature session on a UI-heavy project, pick a design tier. The tier determines seed shape, installed MCP servers, and installed plugin skills. See [visual design workflow](visual-design-workflow.md) for the framework and decision guide.
+
+## 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 `.claude/DIAGRAMS.md` with mermaid 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                                                                |
+
+## Feedback routing
+
+```plaintext
+verify fails  → Session 1 (it has implementation context)
+design fails  → new Claude chat session (planning problem)
+review finds  → Session 2 (fix alongside review, before ship)
+```
+
+## Snippets
+
+For the full list of snippets that complement this workflow, see `.claude/context/snippets.md`.

package/docs/index.md

@@ -0,0 +1,20 @@
+---
+title: Docs
+subtitle: One-line reference for each doc in this folder.
+---
+
+# Docs
+
+One-line reference for each doc in this folder.
+
+## Agent surface
+
+- [Agents](agents.md): CLI catalog and invocation rules for agents
+- [AI workflow](ai-workflow.md): Overarching AI workflow across domains
+- [Target projects](target-projects.md): Scaffold, add domains later, and sync upstream drift in a toolkit-managed project
+
+## Workflow
+
+- [Operating model](operating-model.md): Orchestrator and worker roles for building across parallel sessions
+- [Visual design workflow](visual-design-workflow.md): Tiered guide for design and wireframe authoring with Claude Code
+- [Zshrc aliases for Claude Code](zshrc-aliases.md): Shell aliases that shorten common Claude Code invocations

package/docs/operating-model.md

@@ -0,0 +1,106 @@
+---
+title: Operating model
+description: Orchestrator and worker roles for building across parallel sessions
+category: Workflow
+---
+
+# Operating model
+
+A way to build fast and reliably across parallel Claude Code sessions without a
+loop and without losing the human review gate. One warm session plans and
+reviews. Cold worker sessions build. The human launches workers and merges. This
+page covers the roles and the loop. For the worktree mechanism (isolation, merge
+order, port collisions), see [Claude Code and git worktrees](../wiki/claude-worktrees.md).
+
+## Two roles
+
+The split is by vantage, not by capability. Both are Claude Code sessions.
+
+| Role         | Session                               | Owns                                           | Does not                  |
+| ------------ | ------------------------------------- | ---------------------------------------------- | ------------------------- |
+| Orchestrator | One warm, long-lived session          | Roadmap, planning, deep PR review, merge order | Build features, merge PRs |
+| Worker       | One cold worktree session per feature | Implement, self-check, open PR                 | Question the plan, merge  |
+
+The orchestrator is worth asserting explicitly at the start of a session with
+`claude-orchestrate`, which loads the loop and its boundaries. It is framing and
+dispatch, not logic.
+
+## The loop
+
+One feature travels this path end to end.
+
+1. Orchestrator drafts or resequences the roadmap with `claude-roadmap`, reading scope from `.claude/REQUIREMENTS.md`. The skill stops when that file carries a later scope section, since the MVP list it sequences has shipped and a fresh requirements pass owns what follows.
+2. Orchestrator plans the next feature with `claude-feature`, writing a plan to `.claude/plans/`. Planning stays in the warm session because good planning is cross-feature. It needs the contract other features consume and the shared wiring seam. A cold session would re-derive or guess.
+3. The human opens a worker worktree with `claude-worktree` and runs `claude-autoship` against the plan. The worker builds, self-checks, opens a PR, and stops at the PR boundary.
+4. Orchestrator reviews the PR with `claude-pr-review` and posts findings to it.
+5. Worker addresses the findings with `claude-address-review`, then pushes a follow-up.
+6. Orchestrator closes the review out with `claude-pr-review` again. The second pass reads only the commits the follow-up added and posts under `## Review closed`, so the thread shows one review ending rather than a second one opening.
+7. The human reads the result and merges. The orchestrator tells any trailing worker to rebase when its branch shares a seam with the merged one.
+
+There is no loop construct here. Each worker is a single build that halts at the
+PR. The merge stays a manual human gate. Reliability comes from the plan being
+complete enough that the cold session does not come back with questions, and
+from merging promptly so the next PR does not rot against a moving main.
+
+## Two review layers
+
+The worker's self-review and the orchestrator's review are not the same pass run
+twice. They differ by vantage.
+
+- Worker self-review, inside `claude-autoship`: the session that wrote the code. Its job is "did I build the plan and does it pass?" Mechanical, and structurally blind to its own misreadings, because the same misreading wrote both the code and the review. This is the green gate that decides whether the PR opens.
+- Orchestrator review, via `claude-pr-review`: a fresh session with cross-feature context (the roadmap, a sibling PR in flight, a downstream contract). Its job is "is this right and does it fit?" It can question the plan itself. This is the merge gate.
+
+They collide only if the worker also runs a deep pass. Keep the worker's review
+light and let the orchestrator own the deep, independent one. The human read at
+merge is the final gate. No layer repeats another.
+
+## The review channel
+
+Review travels on the PR, not through chat. `claude-pr-review` posts findings to
+the PR. `claude-address-review` reads them back, fixes each, replies or resolves
+the threads, and pushes a follow-up. `claude-pr-review` then runs a second time
+to close the review out, reading only what the follow-up added.
+
+The two passes carry different headings, `## Review` and `## Review closed`, so
+a thread can be scanned for state without opening either comment. The feedback
+becomes a durable artifact both sessions read, survives a session ending, and
+anchors to the change. That removes the copy-paste that otherwise routes review
+through the human between two sessions.
+
+## Feature sizing
+
+The unit is fixed by the ceremony: one feature is one plan, one worktree, one
+PR, one review sitting. Split a feature down when a backend contract and its
+consumer both change, landing the contract first so no UI is built on a shaky
+contract. Merge a change up into an ordinary edit when it is a few lines with no
+new contract, skipping the plan and worktree entirely. The smell test: if the
+whole change does not fit in your head at review time it was too big, and if the
+coordination costs more than the change it was too small.
+
+## Where work comes from
+
+Three tiers hold work at different altitudes.
+
+- Roadmap (`.claude/ROADMAP.md`): versions as themes, sequenced. Committed, low churn. Shape governed by `standards/bundled/roadmap.md`.
+- Tasks (`.claude/tasks/`): the active few pulled into the current turn, one file each. Gitignored, high churn. Shape governed by `standards/tasks.md`.
+- Edits: a few lines, done immediately with no ceremony.
+
+Pre-MVP the roadmap is the backlog, because the scope is finite and known.
+Post-MVP the backlog moves to tracked issues, per item, and the roadmap thins to
+occasional theme-setting.
+
+## Parallelism
+
+The binding constraint is the human and the shared files, not the roadmap. Cap
+at two or three worker tracks and split them across the stack so they do not
+collide on the same files. Unit checks run freely in many worktrees at once.
+Only fixed-port work (a dev server, an end-to-end run, a screenshot) and
+singleton resources (one local model server, one GPU) serialize. See
+[Claude Code and git worktrees](../wiki/claude-worktrees.md) for merge order and the
+port-collision detail.
+
+## Related
+
+- [Claude Code and git worktrees](../wiki/claude-worktrees.md) for the isolation and fan-out mechanics
+- [Claude Code subagents](../wiki/claude-subagents.md) for in-session parallelism without worktrees
+- `.claude/context/claude-plugin.md` for how the skills in the loop are categorized

package/docs/target-projects.md

@@ -0,0 +1,183 @@
+---
+title: Target projects
+description: Scaffold, add domains later, and sync upstream drift in a toolkit-managed project
+category: Agent surface
+---
+
+# Target projects
+
+How a project outside this repo consumes the toolkit across its lifecycle. Three phases: scaffold once, add a domain later when a new need appears, and sync when the upstream toolkit moves.
+
+This doc stays at the narrative layer. For command flags and JSON shapes, see [agents](agents.md). For per-domain mechanics, see each `.claude/context/<domain>.md`.
+
+## Getting the skills
+
+The skills reach a session through a marketplace install, once per machine. Every session on that machine carries them afterward, and updates arrive on release, so an upstream push does not reach an installed copy.
+
+```bash
+claude plugin marketplace add https://github.com/erclx/aitk
+claude plugin install aitk@aitk
+```
+
+The URL form clones over HTTPS. The `erclx/aitk` shorthand resolves to SSH and fails on a machine with no key configured.
+
+The `aitk` CLI is separate. Twenty skills invoke it in a command position, and a marketplace install does not put it on `PATH`, so it installs from the registry as its own step.
+
+```bash
+bun install --global @erclx/aitk
+```
+
+The package ships the catalogs the CLI reads, not only `src/`, so `aitk init` resolves standards, snippets, governance, tooling, and the seeds from wherever the package landed.
+
+Pointing Claude Code at a checkout stays the development path, where a local skill edit overrides the installed copy for that session.
+
+```bash
+claude --plugin-dir <toolkit>/claude
+```
+
+## Scaffold
+
+Two steps, in order:
+
+1. Run the framework's own scaffold if the project needs one, such as `bun init`, `npm create vite`, or `npm create astro`. The toolkit does not wrap framework scaffolding.
+2. Invoke `aitk:setup-init` in Claude Code. The skill detects the stack, resolves flags, previews the full chain, and runs it end-to-end.
+
+The chain is:
+
+- `aitk init` installs base tooling, Claude seeds, and governance rules into `.claude/rules/` in the same pass
+- `aitk tooling sync <stack>` adds stack-specific deps, scripts, gitignore entries, and drops `.claude/tooling/<stack>.md` (plus parents) as the agent's audit context
+- The agent follows the reference to generate eslint, vitest, playwright configs and the stack's setup script, and extends `.claude/context/ci.md` and `.claude/context/development.md` per the reference's extend sections
+- `setup-verify` runs the installed `package.json` scripts (lint, typecheck, check, test, build) and reports pass or fail
+
+Keep the `## Scripts` table in `.claude/context/development.md` current as scripts are added. Base tooling seeds that entry with the commands it installs, and each stack reference extends the table. `project-commands` reads it to start the app or run a check on request, so a command missing from the table cannot be run that way.
+
+### From scaffold to first feature
+
+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.
+3. Optionally invoke `aitk:claude-diagram` to draft `.claude/DIAGRAMS.md` from the architecture. It renders each diagram 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.
+4. Start the feature loop. See [AI workflow](ai-workflow.md) for the per-feature sequence.
+
+### Stack decision
+
+The default path is `base`. `aitk init` on `base` installs base tooling configs, Claude seeds, governance core rules, and snippets, and scaffolds an empty `.claude/wiki/`. Most projects need nothing more.
+
+Escalate only for real web apps. The `setup-init` skill reads `package.json` and root configs, then picks the matching tooling stack (`vite-react` today) and the matching governance stack (`react`, `astro`, `node`).
+
+Markdown-heavy projects, CLI tools, docs sites, research notebooks, and scripting repos stay on `base`. Escalation is a ceiling move, not a default.
+
+Run `aitk tooling list --json` and `aitk gov list --json` to see the current catalogs. Never hardcode stack names.
+
+### Core domains and skips
+
+`aitk init` installs base tooling, Claude workflow, governance, standards, and snippets, and scaffolds `.claude/wiki/`. Governance defaults to the `base` stack, so a bare init carries the rules that route to the standards it installs alongside them. Pass `--stack <name>` to install a framework stack instead.
+
+`governance`, `standards`, and `wiki` are skippable:
+
+- `--skip governance`: leave `.claude/rules/` empty. Standards still install, so `.claude/standards/prose.md` lands with nothing pointing at it and no coding standard loads on a file match. The preview names any `--add` rules the skip drops, and the run prints the `aitk gov install <stack> <path>` command to add rules afterward, carrying those extras so one paste restores what the skip declined.
+- `--skip standards`: leave standards out. The governance rules still reference `.claude/standards/`, so their authority lines resolve to nothing. Toolkit skills are unaffected, since each falls back to the copy in its own plugin root.
+- `--skip wiki`: skip the `.claude/wiki/` scaffold. A target that already carries a root `wiki/` keeps it, since the verb reports that folder rather than migrating it.
+
+## Add a domain later
+
+When a new need appears after scaffold, install the one domain without re-running `aitk init`.
+
+- Governance rule for a newly adopted library: invoke `aitk:setup-gov`, or run `aitk gov install <stack> --add <rule> <path>`
+- Project-specific rule the toolkit does not ship: invoke `aitk:create-rule`. It scaffolds a rule into `.claude/rules/` with a non-colliding number, and `aitk gov sync` leaves it untouched.
+- Index.md system for a markdown-heavy folder that emerged: invoke `aitk:setup-indexes`
+- A snippet preset or category: `aitk snippets install <preset|category|all> <path>`. The argument is required, since the picker refuses headlessly rather than choosing for the caller
+- A single standard: `aitk standards install <name> <path>`
+
+Per-domain mechanics live in the corresponding `docs/<domain>.md`. The skill body in `claude/skills/<skill>/SKILL.md` covers detection and preview.
+
+## Sync upstream drift
+
+When the toolkit updates, target projects pull changes per domain. There is one catch-all and several targeted entry points.
+
+### Check first
+
+`aitk sync --check <path>` reports what has drifted without writing anything. It splits each difference by cause, which is the question that decides what to do next. A `stale` file still matches what the toolkit installed, so the update is mechanical. A `customized` file carries local edits, so taking the upstream version is a decision and `aitk:claude-seed-sync` is the tool for it. A `stranded` file sits where an older toolkit installed it and the toolkit has since moved, which is what `aitk:migration-standards` handles.
+
+That attribution comes from `.claude/aitk.json`, a stamp every install and sync writes recording a hash per installed file. Each domain holds its own toolkit commit, so syncing governance today does not move the revision standards measures against, and each domain reports the upstream commits touching its own source path. A project that has never synced under a toolkit new enough to write a stamp reports every difference as `drifted`, the unattributed verdict. Running any sync stamps that domain, and the report names the ones still unstamped.
+
+Add `--json` for the machine-readable report, and `--exit-code` to fail a CI job when a target falls behind. Files the project authored itself never count toward that exit code.
+
+Tooling is not covered by the stamp. Reconcile those configs with `aitk tooling <stack> <path>`.
+
+### Catch-all
+
+`aitk sync <path>` runs every installed domain's sync in sequence. Safe to run on a cadence. It never touches user-owned seed files. Governance rules in `.claude/rules/`, tooling configs, and reference docs refresh in place. Stale `.claude/GOV.md` from earlier installs is removed.
+
+Standards are the exception inside that run, and the stamp narrows it. A standard the project customized is reported and left alone rather than overwritten. A standard still matching what was installed carries no local edits to lose, so a headless run updates it. On an unstamped project the old blanket rule holds and every drifted standard is left alone. To take the upstream version of a customized file, run `aitk standards sync <path>` interactively, or use `aitk:claude-seed-sync` below to merge section by section.
+
+### Targeted
+
+- Claude seed docs such as `CLAUDE.md` and `.claude/REQUIREMENTS.md`, plus installed standards under `.claude/standards/`: invoke `aitk:claude-seed-sync`. The skill splits each file into a preamble (between the H1 and the first H2) plus one part per `##` section, then diffs part by part across both surfaces and proposes per-part edits. User customizations are preserved.
+- Governance rules already installed: `aitk gov sync <path>` diffs and applies, and never adds new rules
+- Standards already installed: `aitk standards sync <path>` diffs and applies whole files, and refuses to apply without a prompt
+- Tooling configs and seeds: `aitk tooling <stack> <path>` overwrites golden configs and merges seeds
+- Reference docs for a stack: `aitk tooling ref <stack> <path>`
+- Index regeneration after markdown edits: `aitk indexes regen`
+
+Use a targeted entry point when only one surface moved upstream. Use the catch-all when the toolkit lands a bundled release.
+
+## Verify a sync
+
+Before running a sync against a real project, run the relevant sandbox scenario. The sandbox provisions a representative project state and routes `SANDBOX_SCENARIO=sync` through the domain flow. See [sandbox](../.claude/context/sandbox.md) for the scenario catalog and routing patterns.
+
+## Scenarios
+
+### Markdown-heavy project
+
+```bash
+cd <your-project>
+claude
+```
+
+In the session, invoke `aitk:setup-init`. The skill detects no framework, resolves tooling to `base`, governance to `base`, snippets to `all`, and auto-enables `standards` if `docs/` exists. It previews the chain, then runs `aitk init`.
+
+Ongoing: run `aitk sync --check .` to see what has drifted, then invoke `aitk:claude-seed-sync` for seed drift or `aitk sync .` for a catch-all refresh.
+
+### Web application
+
+```bash
+bun create vite my-app && cd my-app
+claude
+```
+
+Invoke `aitk:setup-init`. The skill reads `package.json` and the Vite config, resolves tooling to `vite-react` and governance to `react`, and runs `aitk init` with the resolved flags.
+
+Ongoing maintenance:
+
+- What has drifted: `aitk sync --check .`
+- Seed drift: invoke `aitk:claude-seed-sync`
+- Catch-all sync: `aitk sync .`
+- Governance rule refresh only: `aitk gov sync .`
+- Layer a new rule on top, for example `260-shadcn` after adopting shadcn: `aitk gov install react --add 260-shadcn .`
+
+### Monorepo with multiple language roots
+
+The repo root owns the shared `base` layer, and each language lives in its own subfolder.
+
+```bash
+aitk init --stack react .
+aitk tooling sync vite-react ./frontend --skip base
+aitk tooling sync python ./backend --skip base
+```
+
+`--skip base` drops the `base` layer from each subtree sync, so husky, prettier, cspell, commitlint, and CI stay single at the repo root. Without it, every subtree re-drops husky, and since git honors only one `core.hooksPath` the extra hook dirs silently break. Each subtree still gets its own framework configs (eslint, vitest, tsconfig, vite) and its own `.claude/tooling/<stack>.md` audit docs.
+
+## Running sync from an agent session
+
+`aitk sync .` applies every installed domain sync, then offers to commit the result and open a pull request. That last step needs a terminal. Under `AITK_NON_INTERACTIVE=1`, which is how an agent runs it, the domain syncs still apply and the git workflow is refused: the command reports the branch and commit it would have created, writes nothing to git, and exits 0. Review the working tree and commit it yourself, or rerun interactively to reach the commit and pull request options.
+
+Sync also refuses a target whose working tree is dirty, so commit or stash before running it. `aitk sync --check .` has neither restriction, since it writes nothing.
+
+## Related
+
+- [agents](agents.md): CLI flags, exit codes, and JSON output shapes
+- [AI workflow](ai-workflow.md): feature-development loop inside a toolkit-managed project
+- [tooling](../.claude/context/tooling.md), [governance](../.claude/context/governance.md), [claude plugin](../.claude/context/claude-plugin.md), [indexes](../.claude/context/indexes.md), [snippets](../.claude/context/snippets.md), [standards](../.claude/context/standards.md): per-domain mechanics
+- [sandbox](../.claude/context/sandbox.md): scenario catalog for verifying domain flows

package/docs/visual-design-workflow.md

@@ -0,0 +1,136 @@
+---
+title: Visual design workflow
+description: Tiered guide for design and wireframe authoring with Claude Code
+category: Workflow
+---
+
+# Visual design workflow
+
+Three tiers cover the range from prose-only design docs to a fully graphical design source of truth. Pick one per project based on how UI-heavy the work is, whether stakeholders review visuals, and whether a designer is involved. Tiers stack, so moving up does not invalidate work done at a lower tier.
+
+The tier framework sits alongside [Claude Design](../wiki/claude-design.md), [visual wireframes](../wiki/visual-wireframes.md), [community skills and plugins](../wiki/community-skills.md), and [community MCP servers](../wiki/community-mcp-servers.md). Those pages catalog the tooling. This page decides when to reach for what.
+
+Two tools anchor tier 1 and tier 2. [Stitch](../wiki/stitch.md) is the agent-addressable default through its MCP server at `stitch.googleapis.com/mcp`, with a free tier of 400 daily credits that covers daily iteration. [Claude Design](../wiki/claude-design.md), released 2026-04-17 and priced inside Claude subscriptions, is the ceiling tool reserved for codebase extraction and the richly annotated handoff bundle. Each covers a different job, they are not swappable.
+
+## Tier 0: prose only
+
+The default. `.claude/DESIGN.md` holds visual intent as prose plus token tables for color, typography, spacing, borders, motion, and iconography. `.claude/WIREFRAMES.md` holds ASCII layouts. Claude Code reads both and writes the implementation. Works for CLI tools, internal dashboards, admin panels, and backend-focused projects.
+
+### 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`.
+
+### Tools
+
+- None beyond Claude Code itself
+- Playwright CLI optional for verifying form submissions and interactive surfaces. See [`claude-ui-test`](../claude/skills/claude-ui-test/SKILL.md).
+
+### Skills
+
+- `aitk:claude-design-extract` to draft `.claude/DESIGN.md` from existing project signals
+- `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
+
+### When to pick
+
+- UI is not the core product
+- Design decisions are few and can be written as sentences
+- No designer on the project
+- Stakeholders review code or behavior rather than mockups
+
+## Tier 1: visual companion
+
+ASCII and prose stay as source of truth. Add a visual render as a feedback surface for the agent and for human review. Stitch via MCP handles agent-driven generation of prototypes and design systems. Excalidraw handles agent-driven wireframes when the round-trip canvas loop matters. Claude Design joins only when codebase extraction or the annotated handoff bundle is worth the ceiling cost. All three produce derived artifacts, so human edits are review annotations rather than source changes.
+
+### Seed shape
+
+Same as tier 0 with two additions. `WIREFRAMES.md` opts into Excalidraw rendering via a top-of-file marker like `<!-- excalidraw: WIREFRAMES.excalidraw -->`. `DESIGN.md` stays human-maintained, and its content is what the toolkit provisions into Stitch via `create_design_system` when visual generation is needed.
+
+Impeccable, if installed, keeps its own root `DESIGN.md` and `PRODUCT.md` in the Stitch DESIGN.md spec format. These are separate files from the toolkit's `.claude/DESIGN.md` and are not synced with it. Treat impeccable's pair as its own source of truth for its commands, and the toolkit's `.claude/DESIGN.md` as the source other toolkit skills read.
+
+### Tools
+
+- Stitch via MCP at `stitch.googleapis.com/mcp`. Default pick for agent-driven visual generation. Free tier of 400 daily credits. See [Stitch](../wiki/stitch.md).
+- Excalidraw canvas server on localhost plus the `yctimlin/mcp_excalidraw` MCP shim, for projects that need an agent to draw, read back, and revise a canvas. See [visual wireframes](../wiki/visual-wireframes.md) for setup and footguns.
+- Playwright MCP for browser-side verification. See [Playwright](../wiki/community-mcp-servers.md#playwright-microsoft).
+- Chrome DevTools MCP for live frontend debugging. See [Chrome DevTools](../wiki/community-mcp-servers.md#chrome-devtools-google).
+- Claude Design as the ceiling option for codebase extraction or polished handoff bundles. See [Claude Design](../wiki/claude-design.md).
+
+### Skills
+
+- Everything from tier 0
+- A frontend design skill to steer visual quality. Pick one of [Impeccable](../wiki/community-skills.md#pbakausimpeccable), [UI/UX Pro Max](../wiki/community-skills.md#nextlevelbuilderui-ux-pro-max-skill), or Anthropic's `frontend-design` plugin. Impeccable is the strongest default because of its curated anti-patterns.
+
+### When to pick
+
+- UI is a meaningful part of the product but not the entire product
+- Stakeholders want to see layout proposals before code exists
+- Design decisions benefit from visual inspection
+- A single contributor owns both design and implementation
+
+### Stitch vs Excalidraw vs Claude Design in tier 1
+
+The three tools solve non-overlapping halves of the visual companion problem.
+
+Stitch via MCP generates polished prototypes from text and a provisioned design system, scripted from a Claude Code session. Output is human-facing and lives in Stitch. Free daily quota makes it the right pick for frequent iteration.
+
+Excalidraw gives the agent a canvas it can read back over MCP. Output is agent-facing and persists as a JSON file in the repo. Pick it when Claude Code needs to iterate on wireframes autonomously, not when a human needs polished review artifacts.
+
+Claude Design reads the raw codebase without prose curation and produces a polished handoff bundle with chat history. Weekly quota makes it expensive, so reserve it for the extraction pass or the final handoff moment, not daily iteration.
+
+Most tier 1 projects pick one. Projects with a messy codebase and no curated `DESIGN.md` may want Claude Design once for the initial extraction, then move to Stitch for ongoing work.
+
+## Tier 2: visual as source of truth
+
+Design happens in a graphical tool. `.claude/DESIGN.md` either regenerates from the graphical source or takes a secondary role as agent-facing summary. Implementation follows the graphical source, either through an MCP round-trip or a one-way handoff bundle. Fits teams with a dedicated designer or projects where design iteration outpaces code changes.
+
+### Seed shape
+
+`.claude/DESIGN.md` becomes a generated artifact. A top-of-file note identifies the upstream source, either a Claude Design project ID or a Figma file URL. Manual edits in the seed carry a warning tag because they will not survive regeneration.
+
+### Tools
+
+- Figma desktop app with the [Figma Dev Mode MCP](../wiki/community-skills.md#figma-mcp-and-code-to-canvas) for teams with a dedicated designer already on Figma. Bidirectional sync and Code to Canvas capture.
+- Claude Design with its Claude Code handoff bundle for teams without an existing Figma investment and for solo founders or PMs driving design themselves. One-way handoff, no bidirectional sync. See [Claude Design](../wiki/claude-design.md).
+- Stitch via MCP as a low-cost complement to either, used for bulk screen generation driven by Claude Code. See [Stitch](../wiki/stitch.md).
+- Playwright and Chrome DevTools MCPs as in tier 1
+
+### Skills
+
+- Everything from tier 1
+
+### When to pick
+
+- UI is the product or a major differentiator
+- A dedicated designer is on the project or will join
+- Design review happens in the graphical tool rather than in code
+- Design changes more often than implementation
+
+### Figma vs Claude Design in tier 2
+
+Figma wins when a dedicated designer already owns a Figma file, external collaborators expect Figma for review, or the workflow needs the agent to capture a running Claude Code UI and push it back as editable frames via Code to Canvas. Figma's MCP is bidirectional.
+
+Claude Design wins when nobody on the team has a Figma workflow yet and the handoff bundle with chat history is the intended implementation path. Claude Design's handoff is one-way, and its quota limits daily iteration, so it is most useful for the initial extraction pass and the final handoff moment rather than day-to-day design work.
+
+Either of the above pairs cleanly with Stitch via MCP for agent-driven screen generation between the two anchor moments.
+
+## Decision guide
+
+Four questions. Each yes weighs toward a higher tier.
+
+- Is the UI the product rather than a thin interface over a backend?
+- Do non-engineers review visual proposals before code exists?
+- Is there a dedicated designer, or will there be one?
+- Does design iterate independently of code?
+
+Zero or one yes: tier 0. Two or three: tier 1. Four: tier 2. Resist over-tiering early. Moving up is cheap because tiers stack. Moving down means abandoning tooling and confusing collaborators.
+
+## References
+
+- [Stitch](../wiki/stitch.md): Gemini-powered design product with the MCP server that anchors tier 1
+- [Claude Design](../wiki/claude-design.md): first-party hosted design product and handoff bundle
+- `.claude/context/claude-plugin.md`: how to decide between workflow and domain-knowledge skills
+- [Visual wireframes](../wiki/visual-wireframes.md): Excalidraw research and setup for the tier 1 wireframe companion
+- [Community skills and plugins](../wiki/community-skills.md): catalog of frontend design skills and integrations
+- [Community MCP servers](../wiki/community-mcp-servers.md): catalog of MCPs referenced across all tiers