@erclx/aitk 0.8.0

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

@@ -0,0 +1,120 @@
+---
+name: git-worktree
+description: Lists linked worktrees with PR state and cleans up merged ones. Use when asked to "list worktrees", "clean up worktrees", or after shipping a PR to reclaim slots. Do NOT use to enter a worktree from scratch (use `claude-worktree`).
+---
+
+# Git worktree
+
+List linked worktrees with their PR state and remove the merged ones. For entry, use `claude-worktree`.
+
+## Shipping order
+
+- Merge the branch with the smallest shared-file footprint first. A branch touching `CLAUDE.md`, a Claude context entry, or a regenerated `index.md` merges last.
+- Rebase each sibling worktree on `origin/main` after a PR merges and before the next one merges. Never merge a stale branch.
+- Run `cleanup` once a PR merges, so the worktree and its local branch go together
+
+## Mode selection
+
+Pick exactly one mode from the user's request:
+
+- `list`: show every worktree with its branch, PR state, and dirtiness ("list worktrees", "what worktrees do I have")
+- `cleanup`: remove worktrees whose branches are merged, then prune local branches ("clean up worktrees", "reclaim worktree slots")
+
+## Context
+
+Run in parallel:
+
+- `git rev-parse --git-dir 2>/dev/null || echo "NO_REPO"`
+- `git rev-parse --git-common-dir 2>/dev/null || echo "NO_REPO"`
+- `git worktree list --porcelain 2>/dev/null || echo "NO_REPO"`
+- `git fetch --prune origin 2>/dev/null || echo "NO_REMOTE"`
+
+Resolve `MAIN_ROOT` from the first `worktree` line of `git worktree list --porcelain`.
+
+## Guards
+
+- If either `git-dir` command returned `NO_REPO`, stop: `❌ Not a git repository.`
+
+## Enumeration (list and cleanup)
+
+Parse `git worktree list --porcelain` into rows. Each row has `path`, `branch`, `head`. Skip the `bare` row if present.
+
+For each row, determine merge state of its branch:
+
+1. Skip the main-root row. Mark it `main` with no PR lookup.
+2. Try `gh pr view <branch> --json state,number,url 2>/dev/null`:
+   - `MERGED`: state is `merged`, record PR number and URL.
+   - `OPEN`: state is `open`, record PR number and URL.
+   - `CLOSED`: state is `closed` (not merged), record PR number.
+   - Command fails or returns no PR: fall through.
+3. Fallback: `git branch --merged main --format='%(refname:short)' 2>/dev/null | grep -qx "<branch>"` to detect linear-merge ancestry. On match, mark `merged (local)`. Otherwise `unmerged`. Match the name alone. Without `--format`, git decorates the current branch with `*` and every branch checked out in a linked worktree with `+`, which is the whole set being enumerated.
+
+Determine dirtiness: `git -C <path> status --porcelain` non-empty means `dirty`.
+
+Determine current: the row whose `path` equals `git rev-parse --show-toplevel`. Resolve the root rather than comparing `pwd`, which equals the worktree root only when the session sits at the top of it. A session in any subdirectory would match no row, and the current-worktree exclusion in `cleanup` would pass its own worktree into the remove set.
+
+## `list` mode
+
+Print the enumeration as a table, then stop. `list` has no final command.
+
+```plaintext
+| #  | Path                               | Branch            | State    | PR     | Notes    |
+| -- | ---------------------------------- | ----------------- | -------- | ------ | -------- |
+```
+
+Notes column shows `current`, `dirty`, or empty. Show paths relative to `MAIN_ROOT` (`.claude/worktrees/<name>`).
+
+After the table, append a one-line hint:
+
+- If any row is `merged` and clean and not current: `Hint: /git-worktree cleanup to remove <count> merged worktrees.`
+- Otherwise: `Hint: no worktrees ready for cleanup.`
+
+## `cleanup` mode
+
+From the enumeration, include a worktree in the remove set when all hold:
+
+- Not the main row.
+- Not the current session's worktree.
+- State is `merged` or `merged (local)`.
+- Working tree is clean.
+
+Every other non-main row goes to the skip set with a one-word reason: `current`, `dirty`, `open`, `closed`, `unmerged`.
+
+### Preview
+
+```plaintext
+**Removing:** <count>
+
+| Path | Branch | PR |
+| ---- | ------ | -- |
+
+**Skipping:** <count>
+
+| Path | Branch | Reason |
+| ---- | ------ | ------ |
+```
+
+If the remove set is empty, stop with `❌ Nothing to remove. All linked worktrees are current, dirty, or unmerged.`
+
+### Final command
+
+After the preview, execute immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+
+```bash
+git -C <MAIN_ROOT> worktree remove <path1> \
+  && git -C <MAIN_ROOT> branch -D <branch1> \
+  && git -C <MAIN_ROOT> worktree remove <path2> \
+  && git -C <MAIN_ROOT> branch -D <branch2> \
+  && git -C <MAIN_ROOT> worktree prune
+```
+
+Chain one `worktree remove` + `branch -D` pair per row in the remove set, then a single `worktree prune` at the end.
+
+## After execution
+
+Respond with exactly one line:
+
+- `list`: `✅ <n> worktrees listed`
+- `cleanup`: `✅ Removed: <count> worktrees, <count> branches pruned`
+
+Do not add any other text.

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

@@ -0,0 +1,74 @@
+---
+name: migration-claude-md
+description: Classifies each section of a target project's bloated `CLAUDE.md` into the three-tier context model and proposes moves to path-scoped rules or context entries, keeping only always-load behavior in `CLAUDE.md`. Use when asked to "slim CLAUDE.md", "migrate CLAUDE.md to rules", "rebalance CLAUDE.md", or when a project's `CLAUDE.md` has grown large. Do NOT move `docs/` files (that is `migration-context`) and do NOT auto-execute. Proposal only.
+---
+
+# Claude md migrate
+
+Rebalance a large `CLAUDE.md` so only always-load behavior stays in it, path-scoped behavior becomes a rule, and domain narrative becomes a context entry. Every move is a proposal the user applies by hand.
+
+## Guards
+
+- If no `CLAUDE.md` exists at `pwd`, stop: `❌ No CLAUDE.md found at the project root.`
+- If `CLAUDE.md` has fewer than three `##` sections, stop: `✅ CLAUDE.md is already lean. Nothing to rebalance.`
+
+## Step 1: discover
+
+Run these in parallel from `pwd`:
+
+- Read `CLAUDE.md`
+- `ls .claude/rules/ 2>/dev/null`: existing rule subdirs and numbers for placement
+- `ls .claude/context/ 2>/dev/null`: existing context entries for conflict checks
+- `aitk claude seeds list --json 2>/dev/null`: the base seed set. Read the `CLAUDE.md` entry's `content` as the always-load baseline. Skip this input when `aitk` is not installed.
+
+## Step 2: classify each section
+
+Split `CLAUDE.md` by `##` heading. Score each section against this order:
+
+1. **Always-load.** Stays in `CLAUDE.md`. Signals: cross-cutting behavior that applies every session, output and formatting rules, project-wide invariants, conventions with no file scope. A section that matches the seed baseline is always-load by definition. Keep it and propose no move.
+2. **Path-scoped.** Propose a rule. Signals: behavior that only applies when working in a folder (`frontend/`, `backend/`) or on a file type, framework-specific conventions, "when editing X do Y" phrasing. Derive the glob from the named scope.
+3. **Domain narrative.** Propose a context entry. Signals: prose describing how a system or domain is built, decisions, gotchas, structure. Not do-or-do-not rules.
+4. **Mixed.** Both rule and narrative in one section. Flag as "needs manual split". Do not propose a single target.
+
+## Step 3: resolve targets
+
+For each section proposed for a move:
+
+- Path-scoped: propose `.claude/rules/<subdir>/<n>-<slug>.md` with a `paths:` glob. Pick the subdir and a free number the way `create-rule` does. If `.claude/rules/<subdir>/` already holds a rule on the topic, mark as "conflict" and skip.
+- Domain narrative: propose `.claude/context/<domain>.md`. If the entry already exists, propose appending rather than creating.
+
+## Step 4: output
+
+Print one grouped proposal block. Omit empty groups.
+
+```markdown
+## Keep in CLAUDE.md
+
+- `## <heading>` (<one-line reason: always-load behavior>)
+
+## Extract to a path-scoped rule
+
+- `## <heading>` → `.claude/rules/<subdir>/<n>-<slug>.md`, paths `<glob>` (<reason>)
+
+## Extract to a context entry
+
+- `## <heading>` → `.claude/context/<domain>.md` (<reason>)
+
+## Needs manual split
+
+- `## <heading>` (rule and narrative mixed)
+
+## Conflicts
+
+- `## <heading>` → `.claude/rules/<subdir>/<n>-<slug>.md` already exists. Skipping.
+
+## Reminder
+
+Scaffold each rule with create-rule and follow .claude/standards/rule.md.
+Follow .claude/standards/context.md for each new context entry.
+Run aitk indexes regen after adding context entries.
+```
+
+If every section classified as always-load, output: `✅ CLAUDE.md holds only always-load behavior. No moves proposed.`
+
+Do not edit `CLAUDE.md`, and do not create the rule or context files. The user reviews the proposal, then applies each move by hand.

package/claude/skills/migration-context/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: migration-context
+description: Classifies markdown files in a target project's `docs/` folder and proposes `git mv` commands to relocate agent-flavored content to `.claude/context/`. Use when asked to "migrate docs to context", "move docs to context", "split docs", or to align an existing project with the three-tier context model. Do NOT auto-execute moves or rewrite inbound links. Proposal only.
+---
+
+# Claude context migrate
+
+## Guards
+
+- If no `docs/` directory exists at `pwd`, stop: `❌ No docs/ directory found.`
+- If `docs/` contains no `.md` files at the top level, stop: `❌ No markdown files in docs/.`
+- This skill operates on flat `docs/*.md` only. Subfolders under `docs/` are listed in the output as "manual review needed" and skipped.
+
+## Step 1: discover
+
+Run these in parallel from `pwd`:
+
+- `ls docs/*.md 2>/dev/null`: list flat markdown files
+- `ls docs/*/ 2>/dev/null`: detect subfolders for the manual-review note
+- `ls .claude/context/ 2>/dev/null`: detect already-migrated content for conflict checks
+- `aitk claude seeds list --json 2>/dev/null`: get the canonical seed list to identify seed-derived files
+
+Read each discovered `docs/*.md` file in parallel.
+
+## Step 2: classify
+
+For each file, score against this rule order:
+
+1. **Seed-derived.** Filename matches `development.md` or `ci.md` and content shape resembles the toolkit's base seed (frontmatter plus a Setup or Triggers section plus tables for scripts or checks). These belong to the seed-migration path. Do not propose a move here.
+2. **Agent-flavored.** Score the following signals. Classify as agent-flavored when two or more match:
+   - Dense file paths in code fences
+   - Sections titled "Anti-patterns", "Layer responsibilities", "Conventions", or "Commands"
+   - Tables of CLI commands
+   - Explicit "do not" rules
+3. **Human-only.** Default fallback when no agent signals match. Typical signals:
+   - Tutorial prose
+   - Sections titled "Welcome", "Getting started", "Contributing", or "Installation"
+   - Second-person narrative aimed at new contributors
+4. **Mixed.** Both agent and human signals present. Flag as "needs manual split". Do not propose a move.
+
+## Step 3: check conflicts and inbound links
+
+For every file proposed for a move:
+
+- If `.claude/context/<filename>` already exists, mark as "conflict" and skip the move.
+- Run `git grep -n "docs/<filename>"` (or grep equivalent) to list inbound references in `CLAUDE.md`, `README.md`, and other markdown. Report each as a TODO line. Do not rewrite.
+
+## Step 4: output
+
+Print one grouped proposal block. Omit empty groups.
+
+```markdown
+## Move to .claude/context/
+
+- docs/<file>.md → .claude/context/<file>.md (<one-line reason>)
+
+## Keep in docs/
+
+- docs/<file>.md (<one-line reason>)
+
+## Defer to claude-seed-sync
+
+- docs/<file>.md (matches toolkit base seed)
+
+## Needs manual split
+
+- docs/<file>.md (mixed agent and human signals)
+
+## Conflicts
+
+- docs/<file>.md → .claude/context/<file>.md already exists. Skipping.
+
+## Subfolders (manual review)
+
+- docs/<subfolder>/
+
+## Suggested git mv commands
+
+git mv docs/<file>.md .claude/context/<file>.md
+
+## Inbound links to fix after moves
+
+- CLAUDE.md:42 references docs/<file>.md
+- README.md:17 references docs/<file>.md
+
+## Reminder
+
+Run aitk indexes regen to update .claude/context/index.md.
+```
+
+If every file classified as "Keep in docs/", output: `✅ All docs/ content is human-facing. No moves proposed.`
+
+Do not execute the `git mv` commands. Do not edit `CLAUDE.md` or `README.md`. The user runs the commands and fixes the links manually after reviewing.

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

@@ -0,0 +1,75 @@
+---
+name: migration-standards
+description: Proposes `git mv` commands to relocate a target project's root `standards/` and `snippets/` folders into `.claude/standards/` and `.claude/snippets/`, the install layout newer toolkit versions expect. Use when asked to "relocate standards", "move standards to .claude", "migrate snippets to .claude", or after a toolkit upgrade leaves rules pointing at `.claude/standards/` while the files sit at the root. Do NOT auto-execute moves or edit rule files. Proposal only.
+---
+
+# Claude standards relocate
+
+## Guards
+
+- If neither `standards/` nor `snippets/` exists at `pwd`, stop: `❌ No root standards/ or snippets/ to relocate.`
+- If `pwd` is not a git work tree, stop: `❌ Not a git repository. git mv needs version control.`
+
+## Step 1: discover
+
+Run these in parallel from the project root:
+
+- `ls standards/*.md 2>/dev/null`: root standards present
+- `ls snippets/ 2>/dev/null`: root snippets present
+- `ls .claude/standards/ 2>/dev/null`: detect an existing target copy
+- `ls .claude/snippets/ 2>/dev/null`: detect an existing target copy
+- `git status --short 2>/dev/null`: confirm a clean tree before proposing moves
+
+## Step 2: check conflicts
+
+- If `.claude/standards/` already holds `.md` files, mark standards as "already relocated" and skip its move.
+- If `.claude/snippets/` already holds `.md` files, mark snippets as "already relocated" and skip its move.
+- If `git status` is not clean, add a TODO line telling the user to commit or stash first. `git mv` on a dirty tree mixes the move with unrelated changes.
+
+## Step 3: find author-owned inbound references
+
+Toolkit-owned rules and skills are re-synced, so do not rewrite them. Surface only references the user authored:
+
+- `git grep -n "standards/" -- 'CLAUDE.md' '.claude/rules/**' 'docs/**' 2>/dev/null`
+- `git grep -n "snippets/" -- 'CLAUDE.md' '.claude/rules/**' 'docs/**' 2>/dev/null`
+
+Report each hit as a TODO line. Exclude paths already under `.claude/standards/` or `.claude/snippets/`.
+
+## Step 4: output
+
+Print one grouped proposal block. Omit empty groups.
+
+```markdown
+## Relocate
+
+- standards/ → .claude/standards/ (<count> files)
+- snippets/ → .claude/snippets/ (<count> files)
+
+## Already relocated
+
+- .claude/standards/ exists. Skipping.
+
+## Suggested git mv commands
+
+mkdir -p .claude
+git mv standards .claude/standards
+git mv snippets .claude/snippets
+
+## Re-sync after moving
+
+aitk standards sync .
+aitk gov sync .
+
+## Inbound references to verify
+
+- CLAUDE.md:42 references standards/prose.md
+- docs/contributing.md:8 references snippets/claude/feature
+
+## Reminder
+
+Re-syncing reinstalls toolkit-owned rules and standards at the new path. Author-owned references above need a manual one-line fix.
+```
+
+If both folders are already relocated, output: `✅ standards/ and snippets/ already live under .claude/. Nothing to relocate.`
+
+Do not run the `git mv` commands. Do not edit `CLAUDE.md`, rule files, or docs. The user runs the commands and fixes author-owned references after reviewing.

package/claude/skills/project-commands/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: project-commands
+description: Runs a command the project documents in `.claude/context/development.md` and stops there. Use when asked to "start the app", "start the dev server", "run the checks", "run the build", "spin it up", or "what commands does this project have". Do NOT use to confirm a change works in a running app, which needs verification past the launch. Do NOT use to deploy, publish, or release.
+---
+
+# Project commands
+
+Read `.claude/context/development.md` from the project root, run the command the user named, report where it landed, and stop.
+
+The value is the stop. A launch that continues into log inspection, browser checks, or unrelated defects is the failure this skill exists to avoid.
+
+## Guards
+
+- Check that `.claude/context/development.md` exists before anything else. If it does not, stop: `❌ No .claude/context/development.md. This project has no documented dev loop.` Name the missing file and let the user decide. Do not read another file to reconstruct it, because a guess is worse than a stop when the user cannot see it was a guess.
+- If the entry documents no command matching the request, stop and list what it does document. Do not infer a command from a filename or a framework.
+- If the resolved command has an effect that outlives the process and stopping it does not undo, print it for the user to run and stop. Deploying, publishing, releasing, migrating, and resetting are the common shapes, and the test is the effect rather than the name. A script called `infra:apply` or `promote` qualifies.
+
+## Step 1: read the entry
+
+Read `.claude/context/development.md` from the project root, the whole entry rather than a named section. That file and no others. A second file is a discovery chain, and this skill has none.
+
+## Step 2: resolve the command
+
+Match the request against what the entry documents, reading the stated purpose and not only the command name. A project that documents two similar commands separately means the distinction, and the purpose column is where it says which is which.
+
+When the request maps to more than one documented command, resolve all of them. A project that starts as a frontend and a backend has two rows in the table and one request covering both, and running one of the two reports success on half an app.
+
+State the resolved command before running it. One line, no rationale.
+
+## Step 3: run it
+
+Run each resolved command as the entry writes it, from the project root. When a command only works from a subdirectory, the entry has to say so, since the table gives the skill nothing else to go on.
+
+A command that terminates runs in the foreground. A command that stays up runs in the background, by setting the Bash tool's `run_in_background` parameter on the call. Nothing backgrounds a process on its own, and a foreground dev server blocks until the tool timeout kills it, which reports as a command that never came up and leaves nothing running.
+
+Decide from what the entry says the command does, not from its name. When the entry does not say, treat a server, watcher, or preview as staying up.
+
+- Read a backgrounded command's output back before checking anything against it. The call that starts it returns immediately and carries no port.
+- Report the port or URL each command prints, and the log location when one exists
+- Confirm a service came up with one check against what it reports listening on
+- Leave a process the skill did not start alone. Never stop, restart, or reconfigure one.
+- Do not tear down what the skill started. A session that starts a server and stops it has not done what was asked.
+
+If a command fails or never comes up, report the failure and the last output. Do not retry with a different command, and do not abandon the others.
+
+## Step 4: stop
+
+Report and end the turn. Specifically do not:
+
+- Run a second check after the first one passed
+- Read the startup log for anything beyond a failure
+- Open a browser, take a screenshot, or drive the running app
+- Report a defect noticed while starting up, however real
+
+Those belong to a verification request, which is a different ask. When one of them looks warranted, say so in one line and let the user decide.
+
+## Output
+
+```plaintext
+▶️ <resolved command>
+
+<what it reported: port, URL, or exit status>
+```
+
+One block per command when the request resolved to more than one.
+
+For a request with no command to run, list what the entry documents instead:
+
+```plaintext
+📋 Documented in .claude/context/development.md
+
+- `<command>`: <purpose as the entry states it>
+```

package/claude/skills/session-resume/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: session-resume
+description: Resumes a previous session by reading tracked work and relevant context. Use when starting a new session, or when asked to "pick up where we left off", "what was I working on", or "resume".
+---
+
+# Session resume
+
+## Step 1: read tracked work
+
+Resolve `.claude/plans/`, `.claude/memory/`, and `.claude/tasks/` at the main worktree root per Worktrees in `CLAUDE.md`.
+
+Read these in parallel, skipping any that do not exist:
+
+- `.claude/tasks/index.md`: the backlog, one line per task. Read this before any individual task file.
+- `.claude/plans/*.md`: execution detail for in-progress tasks
+- `.claude/memory/MEMORY.md` and any memory files relevant to the top backlog item
+
+Then read only the task files the summary needs, typically the top one. Do not read the whole folder.
+
+If all three surfaces are absent or empty, stop: `✅ No tracked work found. Start a new task.`
+
+## Step 2: summarize
+
+Output three sections:
+
+**Up next:** one line per entry in `.claude/tasks/index.md`, preserving order.
+
+**Active plans:** one line per file in `.claude/plans/`, linking each to its task file in `.claude/tasks/`. Say "None" if empty.
+
+**Relevant context:** two or three memory entries that inform the top backlog item. Skip if none apply.
+
+## Step 3: recommend
+
+End with one line: `Start with: <first Up next item>` and note whether it has a linked plan.
+
+Do not offer to remove entries. A completed task is archived out of `.claude/tasks/` when work ships. The git log is the authoritative record of shipped work. Plan files are archived per the plan lifecycle rule in `CLAUDE.md`. Memory is updated only when a recorded fact becomes wrong, never on resume.

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

@@ -0,0 +1,71 @@
+---
+name: setup-gov
+description: Detects a project's stack from its files and installs matching toolkit governance rules into `.claude/rules/`. Use after scaffolding a new project, when asked to "install gov rules", "install governance", "set up governance", or when a target project has no `.claude/rules/` yet. Assumes the `aitk` CLI is on PATH.
+---
+
+# Gov install
+
+Automates `aitk gov install` by inferring the stack and extras from the current project, then shelling out to the CLI with the resolved arguments.
+
+## Read the catalog
+
+Run this first to load the current stacks and rules. Never hardcode names. The catalog is the source of truth.
+
+```bash
+aitk gov list --json 2>/dev/null
+```
+
+## Detect the stack
+
+Read these from the project root in parallel:
+
+- `package.json`: dependencies and devDependencies
+- Root config files: `astro.config.*`, `next.config.*`, `vite.config.*`, `tailwind.config.*`, `tsconfig.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`
+- `.claude/REQUIREMENTS.md` and `.claude/ARCHITECTURE.md` if present
+- Directory structure via `ls -1` of the project root and `src/` if present
+
+## Match
+
+Match the detected evidence to the catalog:
+
+- Pick the closest stack. Match detected runtime or framework against stack names in the catalog.
+- Identify additional technologies not already covered by the picked stack. For each, find a rule whose `description` or `paths` points at that technology, then add it via `--add`.
+- Dedupe extras against stack rules. Do not add a rule the stack already pulls in.
+
+## Gap handling
+
+If a detected technology has no matching rule, stop and surface the gap. Do not guess.
+
+Present three options:
+
+1. Author a new rule in the toolkit at `governance/rules/<domain>/<num>-<name>.md` following `.claude/standards/rule.md`, or `${CLAUDE_SKILL_DIR}/../../standards/rule.md` when the project does not have it, commit, then re-run install.
+2. Install the matching non-<tech> rules and skip the tech-specific layer.
+3. Abort.
+
+Rules are authored in the toolkit repository, never in the target project on the fly.
+
+## Preview
+
+Before executing, output:
+
+- **Detected:** each technology with the file that evidenced it
+- **Stack:** picked stack name and total resolved rule count
+- **Extras:** each `--add` rule with a one-line reason
+- **Target:** resolved target path
+- **Command:** the exact shell command to run
+
+## Execute
+
+Run with `AITK_NON_INTERACTIVE=1` so no CLI picker prompts appear. Claude Code's tool permission dialog is the confirmation gate.
+
+```bash
+AITK_NON_INTERACTIVE=1 aitk gov install <stack> --add <extras> <target>
+```
+
+## Response
+
+After execution, report:
+
+- Rule count installed
+- Target path
+- Any rules that failed to resolve (the CLI warns on missing rule files)