@erclx/aitk 0.8.0

package/claude/skills/claude-standards-audit/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: claude-standards-audit
+description: Audits changed markdown files against applicable authoring standards (prose, skill, readme, branch, pr) and reports violations without fixing. Maps each file to its standards, greps for banned tokens, and groups findings by file. Use when asked to "audit prose", "audit standards", "check standards", "standards audit", or after editing markdown where standards compliance matters. Do NOT fix violations. Reporting only.
+---
+
+# Claude standards audit
+
+## Guards
+
+- Resolve the base ref first, per Diff baseline below, then scope the file list exactly as Step 1 does, fallback included. If no markdown files changed, stop: `✅ No markdown changes to audit.` A guard that reads bare local `main`, or that skips the unusable-baseline fallback, passes the skill clean on a branch it never read.
+- If neither `.claude/standards/prose.md` nor `${CLAUDE_SKILL_DIR}/../../standards/prose.md` is present, stop: `❌ prose.md standard not found. Install toolkit standards first.` Test the file rather than the directory, since a project that installed standards before a given file existed keeps the directory without ever receiving that file.
+
+## Diff baseline
+
+Resolve the base ref once and reuse it in the guard and in Step 1:
+
+```bash
+git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
+```
+
+Prefer `origin/main` over local `main`. On `main` itself the local ref resolves to HEAD, so every committed change drops out of the set and the audit passes clean rather than admitting it cannot see the files.
+
+The baseline is unusable in two cases:
+
+- No merge base resolves against either ref.
+- The base equals HEAD, whichever ref resolved it. Nothing is committed ahead of the base to compare against. This is the ordinary shape on `main`, and on a feature branch before its first commit.
+
+An unusable baseline costs only the committed half. Audit `git diff HEAD --name-only` instead and lead the report with `⚠ Baseline unusable. Audited the uncommitted set only.`, so a clean result is never read as a clean branch.
+
+## Step 1: scope the audit
+
+Get the changed file list, substituting `git diff HEAD --name-only` when the baseline is unusable:
+
+```bash
+git diff <base> HEAD --name-only
+```
+
+Filter to markdown (`.md`). Drop generated files the project does not hand-author (`index.md` when `auto: false` is absent, any file in a gitignored directory).
+
+## Step 2: map files to standards
+
+For each changed markdown file, pick the applicable standards:
+
+- Any markdown with prose: `.claude/standards/prose.md`
+- `SKILL.md` under `.claude/skills/` or `claude/skills/`: also `.claude/standards/skill.md`
+- `README.md` at any level: also `.claude/standards/readme.md`
+- Branch names proposed in the session: `${CLAUDE_SKILL_DIR}/references/branch.md`
+- PR titles or bodies drafted in the session: `${CLAUDE_SKILL_DIR}/references/pr.md`
+
+Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
+
+## Step 3: read standards and audit
+
+Read each applicable standard once. For each changed file, audit against every rule:
+
+- **Pattern rules**: grep the file for every token the standard bans. Grep is authoritative. Reading alone misses occurrences.
+- **Judgment rules**: check each rule in context against the standard that states it.
+
+Every changed markdown file gets the prose pattern pass, since `.claude/standards/prose.md` applies to all of them. Take the banned tokens from that standard at read time rather than from a list held here.
+
+## Step 4: report
+
+Group findings by file with line references. Use this shape:
+
+```markdown
+path/to/file.md
+
+- L12: em dash in prose
+- L34: semicolon used to join clauses
+- L67: bullet ends with period but is a single fragment
+```
+
+If clean, respond with `✅ No violations.`
+
+Reporting only. Do not rewrite any file, swap any punctuation, or propose fixes inline. Fixes are a separate user-initiated step because lazy swaps (semicolon to period, em dash to comma) violate the prose rule against shallow substitution.
+
+## Output
+
+Chat output is the full report. This skill does not persist a file. The audit is a momentary check and living state is the diff itself.

package/claude/skills/claude-standards-audit/references/branch.md

@@ -0,0 +1,49 @@
+---
+title: Branch reference
+description: Branch naming format and type conventions
+consumers: git-branch, git-split, git-pr, claude-standards-audit
+---
+
+# Branch reference
+
+## Format
+
+- Structure: `<type>/<description>` or `<type>/<ticket>-<description>`
+- Length: 50 characters maximum
+- Casing: kebab-case only, no underscores or camelCase
+- Description: 2 words maximum, 3 only when genuinely needed for specificity
+- Capture the core change, not the commit message verbatim
+- For branches with multiple commits, use the unifying concern as the description.
+- Do not duplicate type in description (e.g., `feat/feature-login`)
+
+## Types
+
+- `feat`: new feature or capability
+- `fix`: bug fix
+- `refactor`: structural changes (not a fix or feature)
+- `docs`: documentation only (README)
+- `chore`: maintenance tasks (deps, tooling, configs)
+- `perf`: performance improvements
+- `test`: add or modify tests
+- `style`: code formatting (whitespace, semicolons)
+- `build`: build system changes (webpack, npm scripts)
+- `ci`: CI/CD pipeline changes (GitHub Actions)
+- `revert`: revert a previous commit
+
+## Examples
+
+### Correct
+
+```plaintext
+feat/jwt-expiration                    # clear feature scope
+fix/AUTH-123-connection-pool           # includes ticket ID
+refactor/remove-deprecated-endpoints   # clear refactor intent
+```
+
+### Incorrect
+
+```plaintext
+feature/auth_stuff                                        # wrong type + underscore
+feat/feature-add-login                                    # duplicates type in description
+fix/DB-456-fix-the-database-connection-pool-memory-leak   # exceeds 50 chars + verbatim message
+```

package/claude/skills/claude-standards-audit/references/pr.md

@@ -0,0 +1,124 @@
+---
+title: Pull request reference
+description: Pull request title and body conventions
+consumers: git-split, git-pr, claude-standards-audit
+---
+
+# Pull request reference
+
+## Title
+
+- Format: `<type>(<scope>): <subject>`
+- Casing: lowercase for `<type>`, `<scope>`, and first word of `<subject>`
+- Length: 72 characters maximum
+
+## Content
+
+- Use imperative mood for all content (`add`, `fix`, `refactor`)
+- Do not start with "This PR," "This commit," "Included are," or "I have"
+- Do not use buzzwords (`seamless`, `robust`, `game-changer`, `enhanced`)
+- Do not describe historical behavior or unchanged code. Describe new behavior only.
+- Do not include future promises or speculative documentation
+- Do not explain obvious changes (formatting, renaming variables)
+- Do not duplicate commit messages verbatim
+
+## Sections
+
+- `## Summary`: 1-2 sentences following `<Action Verb> <Direct Object> to <Result>`, expand for clarity if needed
+- `## Key Changes`: name actual files, functions, or modules (e.g., `AuthService.verify()` not "auth handler"). Always use bullet points, never prose.
+- `## Technical Context` (optional): 1-2 lines of architectural reasoning explaining why, not what
+- Omit Technical Context for docs, config, or trivial changes
+- Use bullet points for multiple reasons, one sentence for a single reason
+- `## Testing` (optional): specify exact commands or test cases run
+- Omit Testing for docs, config, or trivial sync changes
+- Use checkboxes, never prose. See Testing discipline for which box gets ticked.
+- `## For the reviewer` (optional): what the reviewer should confirm, one bullet per request
+- Visuals: include only when they clarify architecture, UI, or complex logic flows
+
+## Testing discipline
+
+- Run the check before writing its line. A `- [ ]` reports a check that has not run rather than one that is planned.
+- Tick the box and state the observed result. `- [x] npm test passes, 42 tests` beats `- [ ] run npm test`.
+- Quote the count or output the run reported, never a figure carried from elsewhere.
+- Leave a box unchecked only when a human is required, and name which human and why on the same line.
+- Human-only covers visual or aesthetic judgment, anything needing credentials or a live third-party service, anything needing a second machine or a fresh OS, and judgment about whether a boundary or an abstraction reads correctly. The agent runs everything else.
+- Put a request for the reviewer under `## For the reviewer`. It is a request rather than unfinished testing, so it never appears as an unchecked Testing box.
+
+## Formatting
+
+- End every bullet point with a period
+
+## Examples
+
+### Template
+
+```markdown
+## Summary
+
+<Action Verb> <Direct Object> to <Result>.
+
+## Key Changes
+
+- <Verb> <specific component/file/function> (<reason if non-obvious>)
+- <Verb> <specific component/file/function>
+
+## Technical Context
+
+- <Architectural reasoning explaining why, not what>
+
+## Testing
+
+- [x] <Command run> <observed result>
+- [x] <Edge case verified> <what was observed>
+- [ ] <Human-only check> (<which human, why>)
+
+## For the reviewer
+
+- <What the reviewer should confirm>
+```
+
+### Correct
+
+```markdown
+## Summary
+
+Update auth middleware to enforce jwt expiration checks. # imperative + direct object + result
+
+## Key Changes
+
+- Add `verifyExpiration()` to `src/auth/validators.ts`. # specific function + file path
+- Refactor `AuthService.authenticate()` to handle 401 codes. # named component + clear change
+
+## Technical Context
+
+- Migration to stateless session management for horizontal scalability. # why, not what
+
+## Testing
+
+- [x] `npm run test:auth` passes, 42 tests. # command run + observed result
+- [x] Expired token rejected with a 401 against a local server. # edge case + what happened
+- [ ] Staging smoke test (release owner, needs staging credentials). # unchecked + which human + why
+
+## For the reviewer
+
+- Confirm the 401 and 403 split reads correctly for the public API. # a request, not a test result
+```
+
+### Incorrect
+
+```markdown
+## Summary
+
+This PR updates the authentication system to be more robust. # "This PR" opener + buzzword
+
+## Key Changes
+
+- Updated auth middleware files # vague, no specific component, no period
+- The old system used to check tokens differently # describes historical behavior
+
+## Testing
+
+- Tested manually # no specific command or case
+- [ ] `npm run test:auth` # unchecked box for a check the agent can run
+- [ ] Reviewer confirms the error split reads correctly # a reviewer request, belongs under `## For the reviewer`
+```

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

@@ -0,0 +1,123 @@
+---
+name: claude-tasks
+description: Creates a task file in `.claude/tasks/` with the filename, phase label, and frontmatter the standard requires, and archives a shipped one out of the folder. Use when asked to "add a task", "create a task", "queue this", "put this on the board", "archive that task", or "close out a shipped task". Do NOT use to mark an outcome `[x]` or to archive a plan. That is `claude-docs`.
+---
+
+# Claude tasks
+
+Owns the two operations that bring a task file into existence and take it out of the folder. `claude-docs` edits the contents of a task that already exists, marking outcomes `[x]` and sweeping the plans those tasks cite. Do not mark outcomes here and do not archive a plan on its own.
+
+Read `.claude/standards/tasks.md` from the project root before writing any file, or `${CLAUDE_SKILL_DIR}/../../standards/tasks.md` when the project does not have it. It holds the filename convention, the frontmatter contract, and the file format. Do not work them from memory.
+
+## Guards
+
+- Resolve the board at the main worktree root, not `pwd`. Run `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd` outside a git repo. Every read and write below resolves against that root. The board is gitignored scratch shared across worktrees, so a linked worktree writing to its own `pwd` creates a second board nothing else reads.
+- If `.claude/tasks/` does not exist at that root, stop: `❌ No .claude/tasks/ board. Run aitk claude init to set it up.`
+- Route on the request rather than on a flag. Creating names work that does not exist yet, archiving names a task file already on the board. If the request fits neither, stop: `❌ Ambiguous. Say whether to create a task or archive one.`
+- Never hand-edit `.claude/tasks/index.md`. A hook regenerates it from sibling frontmatter after a write. Do not run the regen command directly.
+
+## Create
+
+### Step 1: require an origin
+
+Every task traces to a plan, a groundwork folder, or a GitHub issue. Ask for it when the request does not carry one, and stop rather than guessing: `❌ No origin. Name the plan, groundwork folder, or issue this task comes from.`
+
+A task with no origin is either lost context or work nobody decided to do. This is the only moment the invariant is enforceable, because it is the only moment a task file comes into existence.
+
+Accept work whose origin is the conversation itself only when the user says so explicitly, and record what it was in the intro paragraph instead of writing a link line to a file that does not exist.
+
+### Step 2: propose the phase label
+
+List the existing filenames in `.claude/tasks/` and read `index.md` for what each holds. Propose the next label from what is already on the board, and say which neighbors it sits between.
+
+Do not derive the label from a version file. `.claude/standards/versioning.md` permits free renumbering, so the board is the only surface that knows what a label currently means. Pad the phase to two digits in the filename, since index entries sort by filename alone and a bare `v9.0` sorts after `v15.0`.
+
+### Step 3: write the file
+
+Write `.claude/tasks/vXX.Y-<slug>.md` following the format in `.claude/standards/tasks.md`. Include a link line only when the file or folder it names exists. A link to a plan nobody has written yet is the broken pointer the archive rules exist to prevent.
+
+Write `Plan:` and `Groundwork:` as markdown links relative to `.claude/tasks/`, as in `Plan: [feature-<slug>](../plans/feature-<slug>.md)`. Leave `Issue:` a bare `#NNN`. A task written in the older bare-path form still parses, so it costs the board a clickable line rather than an archive, but it leaves the board in two shapes for every reader after.
+
+Never write a `Pull request:` line here. `git-pr` adds it when a pull request opens, and a number guessed at create time points at someone else's work.
+
+Write it immediately. Claude Code's tool permission dialog is the confirmation gate. Do not pause for approval.
+
+### Step 4: report unlinked origins
+
+Scan for work that has been decided and would otherwise be forgotten. List `.claude/.tmp/groundwork/` and run `gh issue list --state open` when a remote is configured, then grep the board for each track name and issue number. Report any with no task, one line each.
+
+Report rather than prompt. A track can be opened long after its task would have been written, so an offer to create one for each is noise on most runs.
+
+## Archive
+
+The `post-merge` git hook archives the task a merge closed, so a request arriving here is usually one the hook could not resolve on its own. Run the steps below against whatever the hook left in place.
+
+Do not move the file, edit `priority.md`, or regenerate the index by hand. `aitk tasks archive` owns all three as one unit and the hook calls the same command, so a hand-rolled move here drifts from the unattended path.
+
+### Step 1: confirm the work reached main
+
+`claude-docs` marks outcomes on the branch as step 1 of the ship chain, so an all-`[x]` task routinely describes a pull request that is still open. The command gates on the outcomes and cannot tell those two apart, which is what puts this check here:
+
+```bash
+git fetch origin main --quiet && git log origin/main --oneline -20
+```
+
+Match the shipped outcomes against that log, widening to `gh pr list --state merged --limit 20` when a remote is configured and the log does not settle it. When the work is not on `main`, name the task and stop: `❌ Work not on main. Archiving now loses the task if the pull request is abandoned.`
+
+The board is gitignored, so an archived task has no history behind it and nothing restores one archived early. Skip this check when the task carries a `Pull request:` line and that pull request is merged, since the number already proves what the log is being read for.
+
+### Step 2: run the archive
+
+Pass the task's filename stem, or the pull request number when the request names one:
+
+```bash
+aitk tasks archive <stem>
+```
+
+The command refuses rather than reports, so read its exit code. On success it prints what moved, what row it cleared, and whether the index changed.
+
+### Step 3: route on a refusal
+
+Each reason has one resolution and none of them is to archive around it:
+
+- `open-outcomes`: the named outcomes are unmarked or genuinely open. Run `claude-docs` when the work shipped and nothing marked it. Leave the task on the board when the outcome is real. Cut the outcomes first when the work is being abandoned, so the board records what was dropped.
+- `plan-unswept`: stop and route to `claude-docs`, which owns the plans sweep and the last-live-citation rule. `❌ Plan not yet swept. Run /claude-docs first, then archive.`
+- `ambiguous`: two tasks name one pull request, which is the misfile `.claude/standards/tasks.md` rules out. Resolve the citation by hand, since no sweep repairs it.
+- `no-match`: the stem or number names nothing on the board. Check the name against the listed stems.
+
+Do not move a plan from this skill. `claude-docs` owns that move. Two skills relocating the same file drift into relocating it differently.
+
+Leave `TASK-ARCHIVE.md` alone when it is present in the archive folder. It records the single-file era in the shape that era used, and splitting it would fabricate per-task files nobody wrote.
+
+### Step 4: clear prose naming the task
+
+The command drops the task's row from `.claude/tasks/priority.md` and leaves prose alone. Remove any sentence that still names the archived task or counts the rows that changed, since a stale count reads as board state.
+
+## Output
+
+Emit the full relative path from the project root for every file written or moved. Bare filenames are not clickable.
+
+Create:
+
+```plaintext
+✅ Created: .claude/tasks/vXX.Y-<slug>.md
+
+<label> sits between <neighbor> and <neighbor>.
+
+**Origin with no task:**
+
+- `.claude/.tmp/groundwork/<slug>/`: open, touched <date>
+- #NNN: <issue title>
+```
+
+Omit the origin block when everything is linked.
+
+Archive, reporting the paths the command returned:
+
+```plaintext
+📦 Archived: .claude/.tmp/task-archive/vXX.Y-<slug>.md
+
+<ordering and index disposition in one line>
+```
+
+A refusal reports the reason and the resolution Step 3 routes it to, on one line each.

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

@@ -0,0 +1,75 @@
+---
+name: claude-ui-test
+description: Generates and runs Playwright e2e tests for UI changes, with a manual checklist for visual-only items. Use after implementing UI changes, or when asked "what should I test", "what do I verify", or "give me a test checklist". Do NOT use in empty sessions with no implementation context.
+---
+
+# Claude UI test
+
+## Guards
+
+- If no implementation context exists in the session, stop: `❌ No implementation context. Describe what you built first.`
+
+## Analysis
+
+Review the session to identify what was built or changed. Categorize each change:
+
+- **Automatable:** interactions, state transitions, form submissions, keyboard navigation, conditional rendering, error states, empty states, loading states. These become Playwright e2e tests.
+- **Visual-only:** spacing, alignment, color, typography, layout proportions, animation timing. These become a manual checklist.
+
+Exclude anything already covered by unit or component tests written during implementation.
+
+## E2e tests
+
+Write Playwright tests for all automatable changes. Follow these rules:
+
+- Add tests to the existing e2e test file. If none exists, create `e2e/ui.test.ts`.
+- Use the project's existing Playwright config and test patterns. Read them first.
+- Each test should perform a user action and assert the expected outcome.
+- Cover both happy path and key edge cases (empty state, error state, boundary input).
+- For Chrome extensions: load the unpacked extension via Playwright's `--load-extension` flag and use the extension's sidepanel or popup URL as the test target.
+- Run the tests after writing them. Fix failures before finishing.
+
+Test structure:
+
+```typescript
+test('description of user flow', async ({ page }) => {
+  // Arrange: navigate, set up state
+  // Act: perform user action
+  // Assert: verify expected outcome
+})
+```
+
+## Manual checklist
+
+For visual-only items that cannot be asserted programmatically, produce a checklist. Group by feature area. Use `- [ ]` checkbox syntax.
+
+```markdown
+**What to verify visually:**
+
+**<Feature area>**
+
+- [ ] <action> → <expected visual result>
+```
+
+If all changes are automatable, skip the manual checklist:
+
+`✅ All changes covered by e2e tests. No manual verification needed.`
+
+### Persist the checklist
+
+Derive a slug from the current git branch: run `git branch --show-current` and replace any `/` with `-`. If the result is empty (detached HEAD), use `latest`.
+
+When a manual checklist is produced, write it directly to `.claude/review/ui-checklist-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist. Always overwrite.
+
+Skip the file write when all changes are covered by e2e tests and no checklist was produced.
+
+The `.claude/review/` directory is gitignored. Do not stage or commit the file.
+
+## Output order
+
+1. Write and run e2e tests (report pass/fail)
+2. If a manual checklist was produced, write it to file, then output only the file path in chat:
+   `📝 Wrote .claude/review/ui-checklist-<slug>.md`
+3. If no checklist was needed: `✅ All changes covered by e2e tests. No manual verification needed.`
+
+Do not repeat the full checklist in chat.

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

@@ -0,0 +1,78 @@
+---
+name: claude-ux-audit
+description: Audits the current UI for incomplete, inconsistent, or confusing patterns. Reads DESIGN.md and .claude/wireframes/ for intent, scans UI files, and outputs observations grouped by surface. Use when asked "audit the UX", "audit the UI", "UX audit", or "find UI roughness". Do NOT use for new feature planning or code changes.
+---
+
+# Claude UX audit
+
+## Guards
+
+- If no UI files exist in the project (no JSX, TSX, Vue, Svelte, or HTML under `src/`), stop: `❌ No UI surfaces found to audit.`
+
+## Step 1: read context
+
+Read these in parallel from the project root, skipping any that do not exist:
+
+- `CLAUDE.md`: project type and conventions
+- `.claude/DESIGN.md`: visual intent, tokens, typography, spacing rules
+- `.claude/wireframes/index.md` + every `.claude/wireframes/<surface>.md`: intended UI layout, UI copy, interaction rules. Surfaces are loaded one file at a time during Step 3. Per `.claude/standards/wireframes.md`, these carry layout and intent, not implementation detail.
+- `.claude/REQUIREMENTS.md`: feature scope and non-goals
+
+Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
+
+## Step 2: identify surfaces
+
+List the UI surfaces in the project. A surface is a distinct screen, page, panel, or major component (e.g. sidepanel, popup, settings page, empty state). Group files by surface. Do not audit speculative or unfinished code flagged in `.claude/tasks/` as in-progress.
+
+## Step 3: audit each surface
+
+For each surface, look for:
+
+1. **Missing feedback states**: loading, empty, error, disabled, in-progress
+2. **Unhandled edge cases**: long strings, overflow, zero items, many items, slow networks
+3. **Inconsistencies**: spacing, tone of voice, interaction patterns, icon use, keyboard affordances
+4. **Roughness in daily use**: friction, redundant steps, unclear affordances, ambiguous labels
+
+Use `.claude/DESIGN.md` and the per-surface `.claude/wireframes/<surface>.md` files as ground truth for intent. For each implementation surface, read the matching wireframe file before flagging drift. Observations only, no implementation suggestions or fixes.
+
+## Step 4: report and persist
+
+### Report format
+
+Start with a summary line. Group findings by surface. Omit surfaces with no findings.
+
+```markdown
+X observations across N surfaces.
+
+Surface: <name>
+
+- Missing feedback state: <observation>
+- Inconsistency: <observation>
+
+Surface: <other>
+
+- Edge case: <observation>
+```
+
+If nothing is wrong, use: `✅ No observations.`
+
+### Persist
+
+Derive a slug from the current git branch: run `git branch --show-current` and replace any `/` with `-`. If the result is empty (detached HEAD), use `latest`.
+
+Write the full report directly to `.claude/review/ux-audit-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist. Always overwrite.
+
+If there are no observations, write `✅ No observations.` to the file with a timestamp.
+
+The `.claude/review/` directory is gitignored. Do not stage or commit the file.
+
+### Chat output
+
+Output only the summary line and the file path. Do not repeat the full report in chat.
+
+```plaintext
+X observations across N surfaces.
+📝 Wrote .claude/review/ux-audit-<slug>.md
+```
+
+If no observations: `✅ No observations. Wrote .claude/review/ux-audit-<slug>.md`

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

@@ -0,0 +1,79 @@
+---
+name: claude-worktree
+description: Enters a Claude Code worktree at `.claude/worktrees/<name>/` with a name derived from the active plan or branch. Use when asked to "enter a worktree", "start a worktree", "work in a worktree", or at the plan-to-execute boundary after `/claude-feature`. Do NOT use to list, clean up, or rotate worktrees.
+---
+
+# Claude worktree
+
+Wrap the `EnterWorktree` entry path with name derivation so the user does not pick a name by hand.
+
+## Guards
+
+- If `git rev-parse --git-dir` and `git rev-parse --git-common-dir` differ, the session is already inside a linked worktree. Stop: `❌ Already in a worktree. Run ExitWorktree first.`
+- If neither command resolves, the session is not in a git repo and no `WorktreeCreate` hook is configured. Stop: `❌ Not a git repository. EnterWorktree needs git or a WorktreeCreate hook.`
+
+## Step 1: resolve the main worktree root
+
+Run in parallel:
+
+- `git worktree list --porcelain | awk '/^worktree /{print $2; exit}' 2>/dev/null || pwd`
+- `git branch --show-current 2>/dev/null || echo ""`
+- `git config --get core.bare 2>/dev/null || echo false`
+
+Plans always live at the main root, never inside a linked worktree. See Worktrees in `CLAUDE.md`.
+
+`EnterWorktree` writes `core.bare = true` into the shared config, and nothing restores it, so the repository can already be broken before this session arrives. Repair it before entering when the value is `true` and `<main-root>/.git` is a directory:
+
+```bash
+git config core.bare false
+```
+
+The directory test separates the defect from a genuinely bare repository, which keeps its objects at the root and has no `.git` directory. Announce the repair in one line naming the flag. Leave the file alone when the value is already `false`.
+
+## Step 2: derive the worktree name
+
+Try each source in order. Stop at the first match.
+
+1. **Plan matched to current branch.** Take the branch name and replace `/` with `-` to get `<slug>`. If `<main-root>/.claude/plans/feature-<slug>.md` exists, use `<slug>`.
+2. **Single plan file.** List `<main-root>/.claude/plans/feature-*.md`. If exactly one match, derive `<slug>` from the filename.
+3. **Multiple plan files, no branch match.** Ask the user which plan. Show the candidate slugs as a numbered list. Do not pick.
+4. **Current branch.** When no plan exists, use the branch name (with `/` replaced by `-`) if it is not `main` or `master`.
+   4b. **Session context.** When on `main` or `master` with no matching plan, read the current conversation to infer a kebab slug from the topic being discussed. Propose it: `Infer: <slug>. Confirm or rename?` Do not enter the worktree until the user confirms or provides a corrected name.
+5. **Ask.** None of the above applies. Ask the user for a name. Do not invent one.
+
+Validate the result: letters, digits, dots, underscores, dashes only, max 64 chars (`/` separators are also allowed). If the derived name violates the rule, sanitize by replacing invalid chars with `-` and truncating. Show the sanitized name in the preview before invoking.
+
+## Step 3: preview
+
+Output exactly:
+
+```plaintext
+Worktree: .claude/worktrees/<name>/
+Source: <plan|branch|user>
+```
+
+## Step 4: enter
+
+Call `EnterWorktree` with `name: "<name>"`. Claude Code's tool permission dialog is the confirmation gate. Do not pause for additional confirmation.
+
+## Step 5: align the branch name and repair the shared config
+
+`EnterWorktree` creates a branch named `worktree-<name>`, which diverges from `<name>` and breaks downstream slug derivation in `claude-autoship` and any skill that reads `git branch --show-current`. Rename it to match:
+
+```bash
+git branch -m worktree-<name> <name>
+```
+
+Before renaming, guard against a collision: if `git show-ref --verify --quiet refs/heads/<name>` succeeds, the target branch already exists. Stop: `❌ Branch <name> already exists. Resolve manually before continuing.` Do not delete the existing branch.
+
+Skip the rename if the worktree was entered via `path` rather than `name`, since the branch already exists under its own identity.
+
+Entry also sets `core.bare = true` in the shared config, which strands the main worktree. Every later command run there fails with `fatal: this operation must be run in a work tree` while the files sit untouched on disk. The linked worktree keeps working, so nothing surfaces until the operator returns to the main checkout. Repeat the Step 1 repair, which writes the parent's config even from inside the linked worktree:
+
+```bash
+git config core.bare false
+```
+
+The flag is not set on every entry, so read before writing and announce only when the write happened. Tracked upstream as `anthropics/claude-code#58345`, closed as not planned, so the repair stays until the tool changes.
+
+Do not invoke `ExitWorktree` from this skill. Exit is the user's call.

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

@@ -0,0 +1,47 @@
+---
+name: cli-script
+description: Generates non-interactive Bash scripts for automation, CI, and agent-run tasks. Lean functional style with structured logging, strict error handling, and a clean stdout, no interactive UI. Use when asked for an automation script, a CI or cron script, a pipeline helper, or a non-interactive shell script. Do NOT use for a human-facing interactive tool with prompts or a visual timeline UI, that is `bash-script`.
+---
+
+# CLI script
+
+Generate non-interactive Bash scripts for automation, CI, and agent-run workflows. Optimize for robustness and composability, not visual polish. For a human-facing interactive tool with prompts and a timeline UI, use `bash-script` instead.
+
+Load `${CLAUDE_SKILL_DIR}/references/template.md` for the base skeleton. Copy it and keep only what the task needs.
+
+## Script setup
+
+- Start with `#!/usr/bin/env bash` and `set -euo pipefail`.
+- Implement `usage()` and handle `-h` and `--help` when the script takes arguments.
+- Do not rely on unset variables. Use `${VAR:-default}`.
+
+## Output contract
+
+- Write data to stdout. Write logs, progress, and errors to stderr.
+- Keep stdout clean so the script composes in a pipe.
+- Do not emit timeline frames, icons, or color. Those belong in `bash-script`.
+
+## Error handling
+
+- Define `die()` that prints an error to stderr and exits non-zero.
+- Include actionable context in error messages.
+- Guard commands that return non-zero on a valid empty result with `|| true`.
+- Set explicit exit codes. Reserve 0 for success.
+
+## Code style
+
+- Decompose by responsibility. Each function does one thing, `main()` orchestrates.
+- Name functions verb-first: `parse_args`, `fetch_data`, `validate_input`.
+- Quote variables in expansions and test brackets.
+- Do not include comments except the shebang line.
+- Use 2-space indentation.
+
+## Validation
+
+Before responding, verify:
+
+- File starts with `#!/usr/bin/env bash` and `set -euo pipefail`.
+- Data goes to stdout, logs and errors go to stderr.
+- No timeline frames, icons, or interactive prompts.
+- Errors exit non-zero with context through `die()`.
+- Functions are single-responsibility and `main()` delegates.