@erclx/aitk 0.37.0 → 0.38.0

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

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

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

@@ -0,0 +1,42 @@
+---
+name: claude-design-extract
+description: Why a design system is drafted from what the tree already holds, and how a proposed value is kept distinguishable from a sourced one
+---
+
+# Claude design extract requirement
+
+## Gap
+
+Without this skill, a session asked for a design system either invents token values with nothing behind them or refuses because the project ships no stylesheet. It writes over a `.claude/DESIGN.md` someone already filled. It fills every cell so the file looks complete, which leaves a reader unable to tell a hex sampled from the CLI apart from one the session made up, and a proposal nobody flagged gets built on. A trailing tag column added to mark that uncertainty breaks the render parser instead.
+
+The greenfield case is the one that fails quietly. A project with no UI code still has a personality paragraph and a stated platform, so values can be proposed against a signal rather than pulled from a default palette. A session that does not know this reports there is nothing to extract.
+
+## Must
+
+- Pick the source or greenfield path from what the project tree holds, never from a flag or an argument
+- Announce which path ran, since the two produce different-looking output from one skill
+- Fetch the seed template and keep every heading and table header intact, because the render parser reads them
+- Mark any cell not traced to a source value inline inside the cell value, and take the uncertainty into the sentence when the section is prose
+- Anchor every greenfield proposal to a personality or requirements signal rather than to a default
+- Render the preview and report its path, so the proposals get looked at before they are committed
+
+## Must not
+
+- Overwrite a `.claude/DESIGN.md` that already carries content beyond the seed
+- Guess a value on the source path when no signal exists. Leave the cell blank instead.
+- Invent a non-goal. A proposed motion line is correct when nothing rules motion out.
+- Put the verify tag in a trailing column, which breaks the row
+- Rewrite the transcribed personality paragraph, which is the one section that is not a proposal
+
+## Guards
+
+- `.claude/DESIGN.md` already populated: stop rather than mutating it
+- `aitk` not on PATH: stop, since the seed template and the render both need it
+- Greenfield path with no `.claude/REQUIREMENTS.md` or no `## Personality` section: stop, because there is nothing to propose against. Evaluate this only after Step 1 picks the path.
+
+## Out of scope
+
+- Mutating an existing design system, which is a direct edit of the file rather than a skill
+- Producing the HTML and CSS preview, which `aitk design render` owns
+- Auditing the implemented UI against the tokens, which `claude-ux-audit` owns
+- Architecture and flow diagrams, which `claude-diagram` owns

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

@@ -0,0 +1,45 @@
+---
+name: claude-diagram
+description: Why diagrams are a folder of per-kind entries rather than one file, and why the verified marker is spent only on a render that was read back
+---
+
+# Claude diagram requirement
+
+## Gap
+
+Without this skill, a session asked to refresh one view rewrites the whole surface, so four diagrams nobody checked change in the same commit and the reviewer cannot tell which one the pass was about. It picks a filename of its own, and the next refresh writes a duplicate beside the old entry instead of finding it. It reaches for C4, state, or class diagrams that render differently in every viewer.
+
+The verification failure is the expensive one. A mermaid source can satisfy every rule in the standard and still render as a picture that asserts something false about the system, so a session that judges the source and stamps the entry as verified has spent the only signal a reader has on a diagram nobody looked at. The standards hook toggles off inside a fenced block, so a banned character in a node label passes silently while the same character one line below is caught.
+
+## Must
+
+- Write one entry per kind under the filename and category the standard fixes, so a later refresh finds its target
+- Pick which entries this pass writes from whether the source signal exists and whether the pass has reason to touch it
+- Stay inside `flowchart` and `sequenceDiagram`
+- Render every entry this pass wrote and read the image back against what the entry means to say
+- Stamp the verified marker only on an entry whose render was read back and judged correct
+- Name every skipped render and every surviving defect in the output
+- Regenerate the catalog from sibling frontmatter after the last entry is written
+- Read the node labels by hand, since no hook checks inside a fence
+
+## Must not
+
+- Rewrite an entry this pass had no reason to touch, or report one as written when it was left alone
+- Stamp an untouched entry, a skipped render, or an entry whose defect survived
+- Report a clean verification when a check did not run
+- Commit a render, which is a verification artifact rather than a deliverable
+- Redraw a diagram during a migration pass, since a rewrite and a move landing together leaves no way to tell which one broke it
+- Loop on a defect past two correction passes
+
+## Guards
+
+- No architecture file, no requirements file, and no folder structure to scan: stop, because nothing anchors a diagram
+- Render fails for any reason: continue to the output and name the skipped check. A missing renderer degrades the loop rather than failing it.
+- `aitk` not on PATH: report the catalog as stale rather than hand-editing it
+
+## Out of scope
+
+- Design tokens and the visual system, which `claude-design-extract` owns
+- UI roughness, which `claude-ux-audit` owns
+- Writing the catalog file, which the index regen owns from frontmatter
+- Deleting a pre-split flat diagrams file after a migration, which stays the user's call

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

@@ -0,0 +1,44 @@
+---
+name: claude-groundwork
+description: Why a question that has not been measured gets a disposable folder instead of a plan, and the write scope that lets the track run without pausing
+---
+
+# Claude groundwork requirement
+
+## Gap
+
+Without this skill, a question nobody has measured is answered with a plan. The session commits to an approach before the current state is known, and the reasoning that produced it lives in a conversation that compacts away. A research pass that does run spreads its findings across chat, so the next session re-measures what this one already counted, or worse carries a figure from recall and states it as current.
+
+Two failure modes cost more than the rest. A track that fans out to subagents returns findings without the reasoning that makes the folder worth keeping, which turns a conversation into a search result. And an experiment fixture written under the project root loads that project's own instruction files through the ancestor chain, so the arm measures the repository instead of the question, and the result reads as evidence either way.
+
+## Must
+
+- Detect open, resume, and close from the folder itself, matching the topic against tracks already there before deriving a slug
+- Apply the qualifying test in open mode alone, so a track already measured is not refused by the test that admitted it
+- Measure the current state now rather than carrying a figure from a previous session
+- Carry a lean and the finding that would overturn it on every open question, or admit that a measurement is missing
+- Confine writes to the track folder, with the close-time task file and the experiment fixture as the only exceptions
+- Link every claim about a source outside the project, and list an unread source as a lead rather than citing it
+- Put a fixture a headless run is pointed at outside the repository
+- Write the next-session file self-contained, since the folder is unbacked and dies with the machine
+
+## Must not
+
+- Write a feature plan, a source change, a standard, a rule, or a reference doc
+- Dispatch subagents. A search too large to run inline is a finding that the question is too broad.
+- Close while an open question quietly fails an outcome, rather than resolving it or recording it as knowingly accepted
+- Spawn more than three billed headless runs without asking
+- Match a topic against the shared scratch directory, which holds folders that were never tracks
+- Pause for approval between steps, which the write scope is what makes safe
+
+## Guards
+
+- No topic given: stop rather than inferring one
+- Fewer than two of the three qualifying conditions hold in open mode: stop and route to the planning skill, because the decision is already made
+- Resume and close are exempt from that test by definition
+
+## Out of scope
+
+- Writing the plan the track concludes toward, which `claude-feature` owns
+- Implementing anything the track recommends
+- Persisting the folder. It is gitignored and disposable, which is what makes it the right container for an unanswered question.

package/claude/skills/claude-memory-capture/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: claude-memory-capture
+description: What earns a memory file at the end of a session, the threshold that keeps the folder signal-bearing, and why capture never curates
+---
+
+# Claude memory capture requirement
+
+## Gap
+
+Without this skill, what a session learned dies with it, and the correction the user made in message four is re-earned next week. What does get written is a narrative of how the session went wrong rather than a rule that fires again, so a reader gets a story and no instruction. A new file lands beside one already holding the same topic, and the folder grows two entries per subject until nothing in it can be trusted as current.
+
+The threshold is what the folder lives or dies on. A first-occurrence slip saved as feedback is noise that costs every later session a read, and a fact the repository already records is worse, because it duplicates a source that will be updated without it. From a linked worktree, writes resolved against `pwd` land in a second memory folder nothing else reads.
+
+## Must
+
+- Resolve every read and write at the main worktree root, so parallel worktrees write one folder
+- Classify each candidate as feedback, project, user, or reference before writing
+- Apply the save threshold, firing feedback only on an explicit correction or a pattern that repeated twice
+- Grep the folder for an existing file on the topic and update it in place rather than adding a second
+- Keep a feedback or project body to the rule, one line of why, and one line of when it fires next
+- Append the row to the index so the entry is discoverable
+- Report that nothing was worth capturing rather than manufacturing an entry to show work
+
+## Must not
+
+- Write a session narrative or a recovery account in place of the pattern
+- Save a first-occurrence slip as feedback
+- Create a second file on a topic the folder already holds
+- Save what the repository already records in code, git history, or its instruction files
+- Curate, promote, or delete an existing entry
+
+## Guards
+
+- No correction, confirmation, or context disclosure worth persisting: stop with a pass
+- Memory folder absent at the main root: create it rather than stopping
+
+## Out of scope
+
+- Curating what is already in the folder, which `claude-memory-review` owns
+- Promoting an entry into an instruction file or a skill body, which mutates how the agent operates and ships as its own change

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

@@ -0,0 +1,44 @@
+---
+name: claude-orchestrate
+description: What the one warm control session owns, why it plans and reviews without building or merging, and the collision rule that binds parallelism
+---
+
+# Claude orchestrate requirement
+
+## Gap
+
+Without this skill, the session holding the cross-feature picture starts building, and the picture goes with it. Two features land on the same wiring seam because nobody listed their file sets against each other, and the second pull request rebases onto a tree it was never planned against. Findings from a merged pull request stay in a thread nobody re-reads, so the rule they should have changed never changes.
+
+The queue fails in both directions. It empties and a free worker waits, or it fills with whatever is oldest rather than with what establishes a mechanism. A plan handed over unverified is the quiet one, since it goes stale from whatever merged after it was written, and a worker that trusts its account of the tree builds against a shape that no longer exists. A second orchestrator makes all of this unrecoverable, because the board is gitignored and neither session can read the other's writes.
+
+## Must
+
+- Read the priority file for execution order, since the index sorts by filename and states no order
+- Report the state of play so the human knows what to launch, what to review, and what to merge
+- Verify a plan against the tree before handing it over, counting the sites it claims and opening the files it describes
+- List a candidate's file set against every track in flight, and serialize when the sets are not disjoint
+- Place every finding a merged pull request produced against the surface that owns it
+- Date the roadmap line from that file's last commit, so an old sequence reads as old
+- Keep one planned, non-conflicting task in reserve beyond what is running
+
+## Must not
+
+- Implement a feature or edit any tracked file from this session
+- Merge. Recommend merge or changes and leave the gate to the human.
+- Spawn worker sessions with agents, since every build is meant to be an independent steerable stream
+- Hand a worker anything but a plan, because scope lives there
+- Run a second orchestrator against the same board
+- Promote a task to fill the queue when nothing qualifies. A thin queue is a real answer.
+
+## Guards
+
+- Priority file absent: report the queue and say the order is unrecorded rather than inferring it from the index
+- Roadmap absent: omit the roadmap line rather than asserting a version the file does not state
+- Roadmap present but never committed: report the date as uncommitted, since a blank reads as a formatting slip
+
+## Out of scope
+
+- Writing the plan itself, which `claude-feature` owns and this session runs rather than reimplements
+- Reviewing a worker's pull request, which `claude-pr-review` owns
+- Entering the worktree a build runs in, which the human opens
+- The operating model this enacts, which the toolkit's own docs hold

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

@@ -0,0 +1,41 @@
+---
+name: claude-roadmap
+description: Why versions are sequenced from the MVP list alone, what makes a version a usable increment, and the lifecycle gate that stops a second pass
+---
+
+# Claude roadmap requirement
+
+## Gap
+
+Without this skill, versions are invented from a sense of what should come next rather than sequenced from the scope the requirements already fixed. Each one reads as a milestone nobody can use, because the ordering follows what feels foundational instead of what a user can then do, and a version that de-risks nothing sits ahead of the subsystem the whole plan rests on. The roadmap then drifts into task-level steps, which duplicates the plan folder and goes stale the first time a file moves.
+
+An update is where the file quietly breaks. Rewriting rows that never changed hides the one line that moved, so a reader diffing the roadmap learns nothing from it. And a project whose MVP already shipped gets its later scope sequenced here, which puts a fresh requirements pass's work into a file that only ever sequenced the MVP.
+
+## Must
+
+- Sequence from the MVP list in the requirements file and name it as the source
+- Make every version a usable increment, stated as what the user can then do
+- Order by dependency and by de-risking, placing an unproven subsystem inside the version that first needs it
+- Preserve rows that still hold when updating, resequencing or splitting only where scope shifted
+- Follow the reference for the document shape and version format rather than inventing one
+- Report which versions changed on an update
+
+## Must not
+
+- Break a version into task-level steps or a file list
+- Rewrite a row that did not change
+- Sequence a later scope section without an explicit override from the caller
+- Stage or commit the file, which is tracked but belongs to the git skills
+
+## Guards
+
+- Requirements file absent or carrying no MVP features: stop, because there is nothing to sequence
+- A later scope section present after the MVP list: stop and name the override, since that scope belongs to a fresh requirements pass
+- Neither copy of the requirements standard resolves: draft without the lifecycle gate. Refusing on a rule that could not be read stops more than it protects.
+
+## Out of scope
+
+- Task-level steps and file lists, which `claude-feature` and the task board own
+- Writing the requirements being sequenced
+- Committing the file, which the git skills own
+- Deciding what to build next once the MVP list has shipped

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

@@ -0,0 +1,39 @@
+---
+name: claude-screencast
+description: Why a recording script ships pre-seeded rather than blank, what the four discovery questions buy, and why the draft stays stack-agnostic
+---
+
+# Claude screencast requirement
+
+## Gap
+
+Without this skill, a recording plan arrives as a wall of blank fields, so the user fills a template instead of editing a draft and the work the skill was meant to do lands back on them. The opposite failure costs more. A session that skips discovery guesses the audience, the length, and the hero moment, then writes five beats for a video nobody asked for, and every one of them has to be thrown away rather than edited.
+
+A draft that names the recording software, the editing software, or the window manager pins the script to one machine and one person's setup, so it stops being reusable the moment anyone else records. And re-invoking to refine silently overwrites the edits the user made in the file, which is the one failure that destroys work rather than wasting it.
+
+## Must
+
+- Read project context and recent commits before proposing, since what shipped recently is usually the subject
+- Ask exactly four discovery questions, each carrying a default derived from that context
+- Wait for answers rather than reading silence as acceptance
+- Pre-seed every section with concrete content so the draft is shippable as written and the user edits down
+- Derive the slug from the topic and the discovery answers
+- Write to the gitignored scratch path at the main worktree root and print that path on its own line
+
+## Must not
+
+- Name recording software, editing software, fonts, or window managers
+- Record, edit video, or generate captions
+- Re-run against an existing draft to refine it, since re-running overwrites
+- Infer the hero moment without asking, which is the beat the whole script is built around
+
+## Guards
+
+- No topic provided: stop rather than guessing what is being recorded
+
+## Out of scope
+
+- Producing the recording, which stops at the script by design
+- Refining an existing draft, which is a direct edit of the file
+- Slide decks, which `claude-slides-draft` owns
+- Where the recording ships, which the draft lists and the user decides

package/claude/skills/claude-slides-draft/REQUIREMENT.md

@@ -0,0 +1,39 @@
+---
+name: claude-slides-draft
+description: Why the skill owns deck content and the CLI owns layout, and why one render is read back before the deck is called done
+---
+
+# Claude slides draft requirement
+
+## Gap
+
+Without this skill, a deck request turns into hand-built layout. The session invents layout names the renderer does not have, so the render falls back or fails, and it writes centered body text and bullet lines that overflow the slide because nothing told it the type scale is fixed. Every slide comes out as a title over bullets, which is the shape that needs no decision and reads as a document rather than a deck.
+
+Reimplementing spacing and palette logic is the failure that survives the session. The CLI already owns both, so a deck that styles itself drifts from every other deck and stops being recognizable. And a first render shipped unread hands the audience the overlap and the overflow, since a source that looks correct says nothing about the picture it produces.
+
+## Must
+
+- Read the layout catalog from the CLI before drafting and pick only from what it returns
+- Match the content shape to the layout, since each one parses a different body
+- Vary layouts across the deck rather than repeating one
+- Size content to fit the fixed type scale, keeping titles short and bullet lines tight
+- Shell out to the render command for the deck itself
+- Run one QA pass over the rendered images and fix what it reports
+
+## Must not
+
+- Hardcode a layout name, which goes stale the moment the catalog changes
+- Reimplement layout, palette, or type scale, which the CLI owns
+- Write centered body text or content that overflows a slide
+- Loop on aesthetics past a single fix pass
+
+## Guards
+
+- Image conversion tools missing: skip the image pass and say so. Do not fail the render over a verification step.
+
+## Out of scope
+
+- Rendering, which the CLI owns end to end
+- The palette and the type scale, which live in the CLI rather than in the source
+- Writing the content the deck is about, which the caller brings
+- Recording a demo, which `claude-screencast` owns

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

@@ -0,0 +1,43 @@
+---
+name: claude-tasks
+description: Why creating and archiving a task file is one skill, the origin invariant enforceable only at creation, and why archiving routes through the command the merge hook calls
+---
+
+# Claude tasks requirement
+
+## Gap
+
+Without this skill, a task file gets a filename and frontmatter invented on the spot, so the board sorts wrong and the regenerated index reads fields that are not there. A task arrives with no origin, which is either lost context or work nobody decided to do, and by the time anyone notices there is no way to recover which it was. The phase label gets derived from a version file rather than from what the board already means, and a single-digit phase sorts after a double-digit one because nobody padded it.
+
+Archiving fails in two ways that both lose work. Moving the file, editing the ordering file, and regenerating the index as three separate acts drifts from the one command the merge hook calls, so the attended and unattended paths stop agreeing. And an all-`[x]` task gets archived while its pull request is still open, because marking outcomes happens on the branch as the first step of shipping. The board is gitignored, so nothing restores a task archived early.
+
+## Must
+
+- Resolve the board at the main worktree root, since a linked worktree writing to `pwd` creates a second board nothing reads
+- Read the tasks standard before writing, rather than working the filename and frontmatter from memory
+- Require an origin at creation, because that is the only moment the invariant is enforceable
+- Propose the phase label from what is already on the board and pad it to two digits
+- Confirm the work reached the default branch before archiving
+- Run the archive command and route on the reason it refuses, since each reason has one resolution
+- Report an origin that carries no task, as a list rather than a prompt
+
+## Must not
+
+- Mark an outcome complete or archive a plan
+- Hand-edit the index or the ordering file, or move the task file directly
+- Write a pull request line at creation, when any number is a guess at someone else's work
+- Archive around a refusal
+- Split the legacy single-file archive into per-task files nobody wrote
+
+## Guards
+
+- No task board at the main root: stop
+- The request fits neither creating nor archiving: stop rather than picking one
+- Work not yet on the default branch: stop, because the board has no history to restore from
+- No origin given and none offered: stop
+
+## Out of scope
+
+- Editing the contents of a task that already exists, which `claude-docs` owns along with marking outcomes and sweeping plans
+- Deciding what the task should argue. This owns the file's existence and its shape, not its content.
+- Relocating a plan, which one skill owns so two do not relocate it differently

package/claude/skills/claude-ui-test/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: claude-ui-test
+description: Why UI changes split into what a browser can assert and what only an eye can judge, and why the visual half is written to disk rather than printed
+---
+
+# Claude UI test requirement
+
+## Gap
+
+Without this skill, UI work ships on the confidence of the session that wrote it. What verification does happen mixes the two kinds without noticing, so a checklist item about spacing sits beside one about a form submission, and neither is done properly because they need different work from different people. Tests get written against a config the project does not use, or duplicate what a component test already covers.
+
+The visual half is where the record is lost. A checklist printed into chat scrolls away before anyone verifies it, so the ship step has nothing to gate on and the work reads as verified because a list was produced. Written from a linked worktree against `pwd`, the file lands where the caller does not look.
+
+## Must
+
+- Split every change into automatable and visual-only before writing anything
+- Read the project's existing test config and patterns before writing a test against them
+- Assert a user action and its outcome per test, covering the happy path and the key edge cases
+- Run the tests after writing them and fix what fails
+- Write a produced checklist to the branch-derived path at the main worktree root, overwriting
+- Report that everything is covered rather than manufacturing a checklist to show work
+
+## Must not
+
+- Try to assert a visual property programmatically
+- Re-test what unit or component tests written during implementation already cover
+- Repeat the full checklist in chat, which is what made it evaporate
+- Stage or commit the checklist, which is gitignored scratch
+
+## Guards
+
+- No implementation context in the session: stop, since there is nothing to derive tests from
+- Every change automatable: skip the file write and report the coverage
+
+## Out of scope
+
+- Judging whether the UI is any good, which `claude-ux-audit` owns
+- Unit and component tests, which belong to implementation
+- Deciding whether an outstanding checklist blocks the ship, which the calling pipeline gates on
+- Performing the visual verification, which needs a person

package/claude/skills/claude-ux-audit/REQUIREMENT.md

@@ -0,0 +1,39 @@
+---
+name: claude-ux-audit
+description: Why UI roughness is reported against stated intent rather than taste, and why the audit observes without fixing
+---
+
+# Claude UX audit requirement
+
+## Gap
+
+Without this skill, UI roughness is found by users. An audit that does run reports personal taste, because nothing anchors it to what the project intended, so the findings are arguable and get argued rather than fixed. It flags work the board already marks in progress, which spends the reader's attention on a surface nobody claimed was finished.
+
+The pass slides into fixing what it finds, and then the audit and the change land together with no record of which observation drove which edit, so neither can be reviewed. Reported into chat, the whole thing evaporates before anyone acts on it, and the next audit rediscovers the same list.
+
+## Must
+
+- Read the design system and the per-surface wireframes as ground truth for intent before flagging any drift
+- Group findings by surface, since a surface is what a person opens and fixes
+- Cover missing feedback states, unhandled edge cases, inconsistencies, and friction in daily use
+- Write the full report to the branch-derived path at the main worktree root, overwriting
+- Report no observations rather than filling the list to show work
+
+## Must not
+
+- Suggest an implementation or change any code
+- Flag a surface the task board marks in progress
+- Report a preference no stated intent supports
+- Repeat the full report in chat, which is what loses it
+- Stage or commit the report, which is gitignored scratch
+
+## Guards
+
+- No UI surfaces in the project: stop, since there is nothing to audit
+
+## Out of scope
+
+- Fixing what it found, which is a separate change with its own review
+- Feature planning, which `claude-feature` owns
+- Verifying one specific change, which `claude-ui-test` owns
+- Defining the intent it audits against, which `claude-design-extract` and the wireframes own

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

@@ -0,0 +1,41 @@
+---
+name: claude-worktree
+description: Why worktree entry is wrapped rather than called directly, covering name derivation, the branch rename downstream slugs depend on, and the shared-config repair
+---
+
+# Claude worktree requirement
+
+## Gap
+
+Without this skill, the user names the worktree by hand, and a name matching no plan breaks every slug derived from it afterward. The entry tool then creates the branch as `worktree-<name>`, which diverges from the name the folder carries, so the ship chain looks for a plan file under a slug that does not exist and stops with nothing wrong except the name.
+
+Entry also writes the bare flag into the shared config, which strands the main worktree. Every command run there fails while the files sit untouched on disk, and the linked worktree keeps working, so nothing surfaces until the operator returns to the main checkout and finds the repository broken. A rename onto a branch that already exists is the third failure, and it is the one that destroys work rather than blocking it.
+
+## Must
+
+- Derive the name from the plan matched to the current branch, falling through the ordered sources rather than picking
+- Validate and sanitize the derived name against what the entry tool accepts
+- Preview the resolved name and which source produced it before entering
+- Rename the created branch to match the worktree name, so downstream slug derivation resolves
+- Read the bare flag before writing it, and repair it on both sides of entry
+- Announce the repair only when a write actually happened
+
+## Must not
+
+- Pick between plans when more than one could match. Ask.
+- Enter on a name inferred from session context without confirmation
+- Delete or overwrite a branch that already carries the target name
+- Rename when the worktree was entered by path, since that branch already has its own identity
+- Invoke the exit path, which is the user's call
+
+## Guards
+
+- Already inside a linked worktree: stop rather than nesting
+- Not a git repository and no creation hook configured: stop
+- Target branch already exists: stop and leave it alone, since resolving it automatically risks the wrong branch
+
+## Out of scope
+
+- Listing, cleaning up, or rotating worktrees, which `git-worktree` owns
+- Leaving a worktree, which the user decides
+- What runs inside the worktree once entered, which the caller drives

package/claude/skills/cli-script/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: cli-script
+description: What a non-interactive automation script owes its caller, and the stdout contract that separates it from the human-facing generator
+---
+
+# CLI script requirement
+
+## Gap
+
+Without this skill, an automation script is written with an interactive tool's habits. Progress frames, icons, and color land on stdout, so the script stops composing in a pipe and the caller parses a spinner as data. The failure is invisible in a terminal and total in CI.
+
+The robustness failures are the ones that reach production. Without strict mode a failed stage inside a pipe exits zero and the script reports success on work that did not happen. An unset variable expands to nothing and a path built from it points somewhere nobody meant. Errors print and execution continues. And a single long `main()` holding every responsibility cannot be tested or reused, which is what turns a one-off script into one nobody will touch.
+
+## Must
+
+- Open with the strict-mode preamble, so a failed stage stops the script
+- Keep data on stdout and put every log line, progress message, and error on stderr
+- Exit non-zero with actionable context through one error helper
+- Default every variable expansion rather than relying on it being set
+- Guard a command that returns non-zero on a valid empty result
+- Decompose by responsibility, with the entry function orchestrating rather than doing
+- Implement usage and the help flags when the script takes arguments
+- Run the validation list before responding
+
+## Must not
+
+- Emit timeline frames, icons, color, or an interactive prompt
+- Put a log or progress line on stdout
+- Comment what the code already states
+- Leave stdout formatted for a human to read
+
+## Guards
+
+- No refusal condition. Every request within scope generates, and the boundary against the interactive generator is a routing call made at invocation rather than a runtime stop.
+
+## Out of scope
+
+- A human-facing interactive tool with prompts or a visual timeline UI, which `bash-script` owns
+- A GitHub Actions workflow file, which `ci-workflow` owns
+- Running, installing, or scheduling what it generates

package/claude/skills/create-rule/REQUIREMENT.md

@@ -0,0 +1,42 @@
+---
+name: create-rule
+description: Why a project-local rule needs a band, a number checked against two catalogs, and a scope key that decides when it fires
+---
+
+# Create rule requirement
+
+## Gap
+
+Without this skill, a project rule is written straight into the rules folder on a number already taken, so two rules collide and one loses. The subtler collision is with the toolkit itself. A number free in the target today can be the number a shipped rule lands on tomorrow, and the next install double-books it, so a rule the project wrote gets overwritten by one it never chose.
+
+The band gets picked by feel, so a UI copy rule lands in the always-on range and loads on every session for the rest of the project's life. The scope key fails in both directions. An always-on rule carrying a path scope fires only on files it was never about, and a path-scoped rule missing it loads constantly. Written from memory rather than from the rule standard, the body comes out in a shape the rest of the catalog does not share.
+
+## Must
+
+- Resolve what the rule enforces and where it applies, asking only for what the request leaves missing
+- Pick the band from the topic and take its number range and folder from that choice
+- Check both the target's used prefixes and the toolkit catalog before taking a number
+- Read the rule standard before writing the body
+- Emit the path scope for a path-scoped rule and omit the key entirely for an always-on one
+- Preview the resolved path, band, number, and frontmatter, then write without pausing
+- Say when the rule loads, since path-scoped and always-on rules behave differently
+
+## Must not
+
+- Edit a toolkit source rule, which is authored in the toolkit and would be overwritten here
+- Work the body shape or the frontmatter from memory
+- Take a number without checking the toolkit catalog, which is the collision that surfaces later
+- Write more than one topic into a single rule
+
+## Guards
+
+- No project Claude directory: stop, since there is nowhere for the rule to live
+- The request names no behavior to enforce: stop rather than inventing one
+- The toolkit CLI is not on PATH: scan the target alone and warn that a later install could collide
+
+## Out of scope
+
+- Editing a rule that already exists
+- Toolkit source rules, which are authored in the toolkit rather than in a target
+- Installing the rules the toolkit ships, which the governance setup path owns
+- A standard or a snippet, which `create-standard` owns

package/docs/agents.md

@@ -377,16 +377,21 @@ aitk context audit
 aitk context audit --json
 aitk context audit --citations-only
 aitk context audit --folder context,diagrams
+aitk context audit --folder docs
 ```
 
-| Option             | Behavior                                                                 |
-| ------------------ | ------------------------------------------------------------------------ |
-| `--json`           | Add a machine-readable record on stdout, keeping the frame               |
-| `--folder <list>`  | Comma-separated folder names under `.claude/` (default: the three below) |
-| `--citations-only` | Run the gating citation check alone, printing nothing when it passes     |
+| Option             | Behavior                                                             |
+| ------------------ | -------------------------------------------------------------------- |
+| `--json`           | Add a machine-readable record on stdout, keeping the frame           |
+| `--folder <list>`  | Comma-separated folder names (default: the three below)              |
+| `--citations-only` | Run the gating citation check alone, printing nothing when it passes |
 
 Scope defaults to `context`, `diagrams`, and `wireframes`, and a folder the project does not carry is skipped rather than reported. A domain that outgrew one file and split into `<domain>/` is audited as its own folder, so a split entry measures at the same grain as a flat one.
 
+A name passed to `--folder` resolves under `.claude/` first and at the project root second, which is what puts `docs/` and any later corpus in reach of the same engine. The root base is reached only by a name the caller passes, so the default list still resolves under `.claude/` alone and a project holding a root `wireframes/` is not audited against a standard it never adopted. The scope line prints the resolved path, so a project carrying both spellings reads which one was taken. The JSON record carries the base per folder as `folders[].base`.
+
+A run where no requested name resolves refuses, whichever list it read. Naming the absent ones narrows to `--folder`, since a project carrying one of the three default folders is the ordinary case and a name it never asked for is not a typo. The JSON record carries those names as `unresolvedFolders`.
+
 Exit codes are `0` for a clean run, `1` for a refusal, and `2` for an unresolved citation. Only the citation check sets a failing code. Required-section, length, depth, bullet weight, table, provenance, and index findings print and return `0`, because each is a judgment and failing a push on one would make the check something to route around.
 
 ### What each check reports
@@ -419,6 +424,8 @@ Three exclusions keep it from firing on prose about paths. Fenced blocks are ski
 
 What remains is a sentence naming a hypothetical entry to show the shape of a name, which no syntax separates from a real reference. Append `<!-- audit-ignore-citations -->` to that source line. The marker suppresses citation checking for its own line only.
 
+The pattern spells the `.claude/` prefix, so a folder resolved at the project root is measured by every other check and contributes nothing here. Widening it to a bare `docs/x.md` would match prose that references nothing, which is a separate decision from where entries come from. A run whose folders all resolved at the root says the check is out of scope rather than reporting that zero paths resolved, and the same run under `--citations-only` refuses, because a gate exiting clean on a scope it could not build is the failure the gate exists to catch.
+
 ## Runtime catalogs
 
 Use these to discover what's available instead of hardcoding names.

package/docs/operating-model.md

@@ -104,4 +104,4 @@ port-collision detail.
 
 - [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/skills.md` for how the skills in the loop are categorized
+- `.claude/context/claude-plugin/skill-strategy.md` for how the skills in the loop are categorized

package/docs/visual-design-workflow.md

@@ -130,7 +130,7 @@ Zero or one yes: tier 0. Two or three: tier 1. Four: tier 2. Resist over-tiering
 
 - [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/skills.md`: how to decide between workflow and domain-knowledge skills
+- `.claude/context/claude-plugin/skill-strategy.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

package/package.json

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

package/src/commands/context.ts

@@ -59,7 +59,10 @@ export function register(program: Command): void {
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Add a machine-readable record on stdout')
-    .option('--folder <list>', `Comma-separated folder names under .claude/`)
+    .option(
+      '--folder <list>',
+      'Comma-separated folder names, resolved under .claude/ then the project root',
+    )
     .option('--citations-only', 'Run the gating citation check alone')
     .addHelpText(
       'after',
@@ -78,6 +81,7 @@ export function register(program: Command): void {
         '  aitk context audit --json',
         '  aitk context audit --citations-only',
         '  aitk context audit --folder context,diagrams',
+        '  aitk context audit --folder docs',
         '',
       ].join('\n'),
     )
@@ -96,11 +100,11 @@ function parseFolders(list: string | undefined): string[] | string {
 
   if (names.length === 0) return 'Empty --folder list. Pass at least one name.'
 
-  // `..` would resolve the audited folder above `.claude/`, taking the scan
-  // and the citation pattern outside the tree the audit describes.
+  // `..` would resolve the audited folder above the project root, taking the
+  // scan and the citation pattern outside the tree the audit describes.
   const invalid = names.filter((name) => !FOLDER_NAME.test(name))
   if (invalid.length > 0) {
-    return `--folder takes folder names under .claude/, not paths: ${invalid.join(', ')}`
+    return `--folder takes folder names, not paths: ${invalid.join(', ')}`
   }
 
   return names
@@ -116,15 +120,38 @@ async function runAudit(
 
   if (typeof names === 'string') return refuse(names, gateOnly)
 
-  const folders = await resolveFolders(root, names)
+  // The root base is opt-in. A target carrying a root `wireframes/` would
+  // otherwise be audited against a standard it never adopted, on a bare run
+  // that named nothing.
+  const named = opts.folder !== undefined
+  const { folders, missing } = await resolveFolders(root, names, {
+    canResolveAtRoot: named,
+  })
   if (folders.length === 0) {
     return refuse(
-      `No audited folder found under .claude/. Looked for: ${names.join(', ')}.`,
+      `No audited folder found ${named ? 'under .claude/ or the project root' : 'under .claude/'}. Looked for: ${names.join(', ')}.`,
       gateOnly,
     )
   }
 
-  const citations = await auditCitations(root, presentNames(folders))
+  // A default folder a project does not carry is the ordinary case and stays
+  // silent. A name passed by hand that resolves nowhere is a typo, and the run
+  // measuring the names that did resolve reads as a pass against a folder it
+  // never opened.
+  const unresolved = named ? missing : []
+
+  // The gate runs one check. Letting it exit 0 against a scope it could not
+  // build reports a pass on nothing measured, which is the outcome a gate is
+  // there to prevent.
+  const cited = presentNames(folders)
+  if (gateOnly && cited.length === 0) {
+    return refuse(
+      `The citation check spells the .claude/ prefix and no audited folder resolved there. Looked for: ${names.join(', ')}.`,
+      gateOnly,
+    )
+  }
+
+  const citations = await auditCitations(root, cited)
   if (citations.kind === 'unavailable') {
     return refuse(
       'git could not list the tree, so no citation was checked. Run inside a git repository.',
@@ -140,8 +167,8 @@ async function runAudit(
     reportGate(citations)
   } else {
     intro('aitk context audit')
-    reportScope(folders)
-    reportCitations(citations)
+    reportScope(folders, unresolved)
+    reportCitations(citations, cited)
     reportSections(sections, folders)
     reportLength(entries)
     reportDepth(entries)
@@ -158,9 +185,11 @@ async function runAudit(
         root,
         folders: folders.map((folder) => ({
           path: folder.rel,
+          base: folder.base,
           entries: folder.entries.length,
           governsContent: governsContent(folder),
         })),
+        unresolvedFolders: unresolved,
         citations: {
           scanned: citations.scanned,
           total: citations.total,
@@ -228,18 +257,54 @@ function plural(count: number, noun: string): string {
   return `${count} ${noun}${count === 1 ? '' : 's'}`
 }
 
-function reportScope(folders: readonly AuditedFolder[]): void {
+/**
+ * Names the resolved path of every audited folder, plus the requested names
+ * that resolved nowhere.
+ *
+ * The path is what says which base a name was taken from, which matters once a
+ * name can resolve under `.claude/` or at the project root and a project may
+ * carry both.
+ */
+function reportScope(
+  folders: readonly AuditedFolder[],
+  unresolved: readonly string[],
+): void {
   logStep('Scope')
 
   for (const folder of folders) {
     logInfo(`${folder.rel}: ${folder.entries.length} entries`)
   }
+
+  if (unresolved.length === 0) return
+
+  logWarn(
+    `Under neither .claude/ nor the project root: ${unresolved.join(', ')}`,
+  )
 }
 
 type ScannedCitations = Extract<CitationReport, { kind: 'scanned' }>
 
-function reportCitations(report: ScannedCitations): void {
+/**
+ * States the reach before the count, for the reason the provenance report
+ * states its own.
+ *
+ * A run auditing a folder at the project root builds no pattern, and a count of
+ * zero followed by a line saying every path resolves is indistinguishable from
+ * a corpus that cites nothing.
+ */
+function reportCitations(
+  report: ScannedCitations,
+  cited: readonly string[],
+): void {
   logStep('Citations')
+
+  if (cited.length === 0) {
+    logInfo(
+      'Out of scope. The pattern spells the .claude/ prefix, and no audited folder resolved there.',
+    )
+    return
+  }
+
   logInfo(
     `${plural(report.total, 'cited path')} across ${plural(report.scanned, 'file')}, fixtures and fenced examples excluded`,
   )

package/src/context/folders.ts

@@ -17,6 +17,12 @@ export const DEFAULT_FOLDERS: readonly string[] = [
   'wireframes',
 ]
 
+/** The base every folder in the default list sits under. */
+const CLAUDE_BASE = '.claude'
+
+/** The project root, reached only by a name the caller asked for. */
+const ROOT_BASE = '.'
+
 export interface AuditedFolder {
   /**
    * The requested folder name this was resolved under, which is what says
@@ -25,6 +31,11 @@ export interface AuditedFolder {
    * `.claude/context/claude-plugin` is governed as `context`.
    */
   readonly name: string
+  /**
+   * The base the name resolved under, which is what says whether the folder is
+   * in the citation check's scope.
+   */
+  readonly base: string
   /** Repo-relative folder path, used verbatim in every report line. */
   readonly rel: string
   readonly indexPath: string
@@ -43,16 +54,28 @@ export interface AuditedFolder {
 }
 
 /**
- * Names the requested folders that actually exist, which is the citation
- * check's scope.
+ * Names the requested `.claude/` folders that actually exist, which is the
+ * citation check's scope.
  *
  * A skill or seed pointing into `.claude/wireframes/` is a live instruction for
  * a project that carries the folder and says nothing about one that does not.
  * Checking a path into an absent folder would fail eight shipped references
  * here for the sole reason that this repository has no wireframes.
+ *
+ * A folder resolved at the project root is measured and stays out of this. The
+ * pattern the citation check builds spells the `.claude/` prefix, so admitting
+ * a root name there would check `.claude/<name>/` paths the audit never read.
+ * Widening the pattern to the root spelling is a separate change, since a bare
+ * `docs/x.md` appears in prose that references nothing.
  */
 export function presentNames(folders: readonly AuditedFolder[]): string[] {
-  return [...new Set(folders.map((folder) => folder.name))]
+  return [
+    ...new Set(
+      folders
+        .filter((folder) => folder.base === CLAUDE_BASE)
+        .map((folder) => folder.name),
+    ),
+  ]
 }
 
 async function readEntries(dir: string): Promise<string[]> {
@@ -70,6 +93,40 @@ async function readEntries(dir: string): Promise<string[]> {
   return paths.sort()
 }
 
+export interface FolderResolution {
+  /** Every folder that resolved, with the nested splits beneath each. */
+  readonly folders: readonly AuditedFolder[]
+  /**
+   * Requested names that resolved under no base, reported rather than dropped.
+   * Which absences are worth saying out loud is the caller's judgment: a
+   * default folder a project does not carry is ordinary, and a name passed by
+   * hand that resolves nowhere is a typo that would otherwise read as a pass.
+   */
+  readonly missing: readonly string[]
+}
+
+export interface ResolveOptions {
+  /**
+   * Whether a name may resolve at the project root when `.claude/` does not
+   * carry it. False for the default list, which names three folders a project
+   * is expected to hold under `.claude/` and nowhere else.
+   */
+  readonly canResolveAtRoot?: boolean
+}
+
+function locate(
+  root: string,
+  name: string,
+  bases: readonly string[],
+): { readonly dir: string; readonly base: string } | undefined {
+  for (const base of bases) {
+    const dir = resolve(root, base, name)
+    if (existsSync(`${dir}/${INDEX_FILE}`)) return { dir, base }
+  }
+
+  return undefined
+}
+
 /**
  * Resolves the folders to audit under `root`.
  *
@@ -77,34 +134,49 @@ async function readEntries(dir: string): Promise<string[]> {
  * folder beneath it, so a domain that outgrew one file and split is audited at
  * the same grain as one that did not. Discovery of the nested folders runs
  * through the shared walker, which is what keeps `.gitignore` and the vendored
- * prune governing this scan as well as index regeneration.
+ * prune governing this scan as well as index regeneration. That prune is what
+ * lets a root folder be walked at all, since a name at the project root sits
+ * beside `node_modules` and a build output.
  *
- * A requested folder that does not exist is dropped rather than reported. The
- * default list names three folders and a project carrying one of them is the
- * ordinary case.
+ * The project root is reached only when the caller opts in, so a target holding
+ * a root `wireframes/` is not audited against a standard it never adopted by
+ * the mere act of running the command. `.claude/` still wins a name carried by
+ * both, and the scope line prints the resolved path so a caller reads which
+ * base was taken rather than inferring it.
+ *
+ * Nothing above this asks where a folder came from. A name that resolves at the
+ * root is measured by every rule that generalizes and gated out of the rules a
+ * single standard carries, which `governsContent` decides from the name.
  */
 export async function resolveFolders(
   root: string,
   names: readonly string[] = DEFAULT_FOLDERS,
-): Promise<AuditedFolder[]> {
+  { canResolveAtRoot = false }: ResolveOptions = {},
+): Promise<FolderResolution> {
+  const bases = canResolveAtRoot ? [CLAUDE_BASE, ROOT_BASE] : [CLAUDE_BASE]
   const folders: AuditedFolder[] = []
+  const missing: string[] = []
 
   for (const name of names) {
-    const dir = resolve(root, '.claude', name)
-    if (!existsSync(`${dir}/${INDEX_FILE}`)) continue
+    const found = locate(root, name, bases)
+    if (!found) {
+      missing.push(name)
+      continue
+    }
 
-    const dirs = [dir, ...(await listIndexes(dir)).map(dirname)]
+    const dirs = [found.dir, ...(await listIndexes(found.dir)).map(dirname)]
 
     for (const each of [...new Set(dirs)].sort()) {
       folders.push({
         name,
+        base: found.base,
         rel: relative(root, each),
         indexPath: `${each}/${INDEX_FILE}`,
         entries: await readEntries(each),
-        nested: each !== dir,
+        nested: each !== found.dir,
       })
     }
   }
 
-  return folders
+  return { folders, missing }
 }