@erclx/aitk 0.8.0

package/claude/skills/git-ship/REQUIREMENT.md

@@ -0,0 +1,34 @@
+---
+name: git-ship
+description: What the ship chain is for, the gaps it closes, and why it does not implement or review
+---
+
+# Git ship requirement
+
+## Gap
+
+Without this skill, the post-feature sequence runs from memory. Doc sync gets skipped, so the pull request ships with planning docs describing the previous scope, or it runs after staging has already closed and its output never reaches a commit. Chaining by hand is also where a session narrates between steps, which turns one flow into a conversation and invites a decision at every boundary.
+
+## Must
+
+- Invoke each step through the Skill tool in the stated order and continue without waiting
+- Stage after the sync skills write, so what they produced reaches a commit
+- Emit no text between steps. The sequence is the unit and prose inside it reopens settled decisions.
+- Watch continuous integration to a terminal state, and stop on a failure naming the check
+- Stop memory work at the Propose phase
+
+## Must not
+
+- Auto-trigger. Shipping is a decision the user takes, which is what the disabled model invocation encodes.
+- Fix a failing check. The stop is the point, since a green pull request reached by auto-fix hides what broke.
+- Run the memory Apply phase. Promoting an entry changes how the agent operates and ships as its own change.
+- Implement, verify, or review. This chain starts from work already believed done.
+
+## Guards
+
+- A failing check stops the sequence. This is the one place text is allowed between steps.
+
+## Out of scope
+
+- Implementation, verification, and review, which `claude-autoship` chains ahead of this same sequence. That skill is the full pipeline and this one is the resume point after a stop, which is why the two overlap by design.
+- The behavior of each step, owned by the skill invoked. This skill owns the order and nothing else.

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

@@ -0,0 +1,39 @@
+---
+name: git-ship
+description: Runs the full post-feature workflow by syncing docs, staging commits, renaming the branch, and opening a PR. Use after implementing a feature, or when asked to "ship", "ship this", or "ship it".
+disable-model-invocation: true
+---
+
+# Ship
+
+Run the full post-feature workflow by invoking each skill in sequence using the Skill tool. After each skill returns, invoke the next step immediately in the same response. Do not output any text between steps and do not wait for user input. Tool permission dialogs are the only interrupts allowed. The final output is `✅ Shipped`.
+
+## Pre-check
+
+Run `git diff --cached --name-only 2>/dev/null` to check for staged files. If output is empty and there are unstaged changes, run `git add -A` to stage everything before proceeding.
+
+## Sequence
+
+1. Invoke `aitk:claude-docs` to sync internal planning docs against session decisions
+2. Invoke `aitk:docs-sync` to sync public docs against changes since main
+3. Run `git add -A` to stage any files the sync skills wrote
+4. Invoke `aitk:git-stage` to group staged changes and commit by concern
+5. Invoke `aitk:git-branch` to rename branch to match conventional format
+6. Invoke `aitk:git-pr` to push branch and open pull request
+7. After the PR opens, watch CI. Poll `gh pr checks <number>` until no check is pending, then read the final status. On all-pass, continue. On any failure, stop the sequence and report the failing check with its URL. Do not auto-fix. This step may output on failure, the one exception to the no-text-between-steps rule.
+8. Invoke `aitk:claude-memory-capture` to extract durable patterns from the session into `.claude/memory/`
+9. If `claude-memory-capture` wrote or updated at least one entry this session, invoke `aitk:claude-memory-review` scoped to those entries to propose fixes while session context is fresh. If capture wrote nothing, skip this step.
+
+Stop at the Propose phase. Do not run Apply. Promoting an entry to `CLAUDE.md` or a skill body ships as its own change, separate from this feature.
+
+## After completion
+
+Output up to three lines:
+
+```plaintext
+✅ Shipped
+<N memories captured in .claude/memory/>
+<Memory proposal at .claude/review/memory-review-<slug>.md>
+```
+
+Omit the second and third lines if `claude-memory-capture` wrote nothing this session, since no captures means no scoped review and no proposal.

package/claude/skills/git-split/REQUIREMENT.md

@@ -0,0 +1,38 @@
+---
+name: git-split
+description: What branch splitting is for, the gaps it closes, and how it differs from grouping a staged diff
+---
+
+# Git split requirement
+
+## Gap
+
+Without this skill, a branch carrying unrelated commits ships as one pull request, which a reviewer reads by skimming because no single concern holds it together. Split by hand, commits get cherry-picked in an order that leaves a branch missing something it depends on. Merge order is the sharpest failure: merging the wrong branch first lands every other branch's content on main and leaves the remaining pull requests empty after rebase, with no signal that anything went wrong.
+
+## Must
+
+- Refuse a dirty tree, since cherry-picking across branches abandons uncommitted work with no record of it
+- Group by concern from both the commit messages and the file paths, preferring fewer branches over a branch per commit
+- Classify the groups as independent or stacked before generating any command, because the base of every branch follows from that one call
+- Account for every commit ahead of main in the preview
+- State the merge order and the reason behind it, since the order is not recoverable from reading the pull requests afterward
+- Carry the restack loop for stacked mode, where each branch is rebased onto main once the one below it merges
+
+## Must not
+
+- Split when one concern already covers the branch
+- Rename a branch whose name already matches its concern
+- Leave a commit unaccounted for. A dropped commit is silent and the branch it came from may already be gone.
+- Merge the pull requests it opens
+
+## Guards
+
+- Dirty working tree: stop and name both recoveries
+- On `main`: stop
+- No commits ahead of main: stop
+
+## Out of scope
+
+- Partitioning a staged diff into commits, which `git-stage` owns. The two resemble each other and take different input: this one starts from commits that already exist and emits branches.
+- The message on each commit, which `git-commit` owns
+- Merging, which stays the user's call. The skill states the order and stops.

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

@@ -0,0 +1,160 @@
+---
+name: git-split
+description: Splits a mixed-commit branch into focused branches off main using cherry-pick. Use when a branch has unrelated commits, asking "split this branch", or needing to separate concerns into reviewable PRs.
+---
+
+# Git split
+
+Before proposing a split, read in parallel:
+
+- `${CLAUDE_SKILL_DIR}/references/branch.md`: format, types, length limit, and constraints
+- `${CLAUDE_SKILL_DIR}/references/pr.md`: PR title format, body sections, and content rules
+
+Follow both exactly.
+
+## Context
+
+Run these commands in parallel to gather git context:
+
+- `git status --porcelain 2>/dev/null || echo "NO_STATUS"`
+- `git branch --show-current 2>/dev/null || echo "NO_BRANCH"`
+- `git log main..HEAD --oneline --no-decorate --stat 2>/dev/null || echo "NO_COMMITS"`
+
+## Guards
+
+- If working tree is dirty (non-empty `git status --porcelain`), stop:
+  `❌ Working tree is dirty. Commit or stash changes before splitting.`
+- If current branch is `main` or `master`, stop:
+  `❌ Already on main. Nothing to split.`
+- If no commits ahead of main, stop:
+  `❌ No commits ahead of main. Nothing to split.`
+
+## Grouping rules
+
+- Group commits by concern using both commit messages and file paths.
+- Prefer fewer branches: combine related commits into one branch.
+- Only split into separate branches when concerns are clearly independent.
+- Identify the primary concern of the current branch. Rename it using `git branch -m` if the current name does not already match. Skip the rename if it already matches. Secondary concerns are extracted as new focused branches via cherry-pick.
+- If no single concern dominates (dumping-ground branch with no clear primary), split all commits into new focused branches and add `git branch -d <current>` to delete the original.
+- Propose one new branch per secondary concern following branch.md format.
+- Classify groups as independent or stacked before generating commands.
+- Independent groups: each group's commits apply to `main` without the others. Base every branch on `main`.
+- Stacked groups: groups are ordered and each depends on the commits before it. Base each branch on the previous group's branch. Cherry-pick only that group's commits onto it. The base branch already carries all prior commits.
+
+## Response format
+
+### Preview
+
+**Current branch:** <branch_name>
+**Total commits ahead of main:** <count>
+**Mode:** Independent | Stacked
+
+| Group     | Branch               | Base           | Commits | Count |
+| --------- | -------------------- | -------------- | ------- | ----- |
+| <concern> | <type>/<description> | main           | <shas>  | <n>   |
+| <concern> | <type>/<description> | <prior-branch> | <shas>  | <n>   |
+
+**All <total> commits accounted for.**
+
+- For the primary concern (the current branch), show `<current_branch> → <new_name>` only when renaming. Show just `<current_branch>` if the existing name already matches the concern.
+- For stacked mode, list rows in merge order: branches based on `main` first, then each layer above. For independent mode, list the primary concern first.
+
+If Mode is Stacked, append this line to the preview:
+
+`🔁 Sequential squash-merge loop. Squash-merge each PR bottom-up with --delete-branch. After each merge, signal me so I can restack the next branch onto main before you merge it.`
+
+If Mode is Independent, append this line to the preview:
+
+`🔁 Squash-merge secondaries first, primary last. The primary keeps every cherry-picked commit, so merging it first lands every secondary's content on main and leaves the secondary PRs empty after rebase.`
+
+After outputting the preview, execute the final commands immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+
+### Final commands
+
+For independent mode, base every branch on `main`:
+
+```bash
+# Rename current branch to reflect primary concern
+git branch -m <current_branch> <new_name>
+
+# Create, cherry-pick, push, and open PR for each secondary branch
+mkdir -p .claude/.tmp/pr-split
+git switch -c <branch> main && git cherry-pick <sha> <sha> \
+  && git push -u origin <branch> \
+  && (cat <<'BODY' > .claude/.tmp/pr-split/<branch>.md
+<body following pr.md template, written from the cherry-picked commits>
+BODY
+) && gh pr create --title "<title>" --body-file .claude/.tmp/pr-split/<branch>.md \
+  && rm .claude/.tmp/pr-split/<branch>.md
+
+# Return to primary branch, push, and open its PR
+git checkout <new_name> && git push -u origin <new_name> \
+  && (cat <<'BODY' > .claude/.tmp/pr-split/<new_name>.md
+<body following pr.md template, written from the primary's commits>
+BODY
+) && gh pr create --title "<title>" --body-file .claude/.tmp/pr-split/<new_name>.md \
+  && rm .claude/.tmp/pr-split/<new_name>.md
+
+# Clean up the body-file dir if all PRs succeeded (no-op when non-empty)
+rmdir .claude/.tmp/pr-split 2>/dev/null || true
+```
+
+For stacked mode, base each branch on the previous and cherry-pick only that group's commits:
+
+```bash
+# Rename current branch to reflect primary concern
+git branch -m <current_branch> <new_name>
+
+mkdir -p .claude/.tmp/pr-split
+
+# Group 1: based on main
+git switch -c <branch-1> main && git cherry-pick <g1-sha> <g1-sha> \
+  && git push -u origin <branch-1> \
+  && (cat <<'BODY' > .claude/.tmp/pr-split/<branch-1>.md
+<body following pr.md template, written from the cherry-picked commits>
+BODY
+) && gh pr create --title "<title>" --body-file .claude/.tmp/pr-split/<branch-1>.md \
+  && rm .claude/.tmp/pr-split/<branch-1>.md
+
+# Group 2: based on <branch-1>, this group's commits only
+git checkout -b <branch-2> && git cherry-pick <g2-sha> <g2-sha> \
+  && git push -u origin <branch-2> \
+  && (cat <<'BODY' > .claude/.tmp/pr-split/<branch-2>.md
+<body following pr.md template, written from the cherry-picked commits>
+BODY
+) && gh pr create --title "<title>" --body-file .claude/.tmp/pr-split/<branch-2>.md \
+  && rm .claude/.tmp/pr-split/<branch-2>.md
+
+# Return to primary branch, push, and open its PR
+git checkout <new_name> && git push -u origin <new_name> \
+  && (cat <<'BODY' > .claude/.tmp/pr-split/<new_name>.md
+<body following pr.md template, written from the primary's commits>
+BODY
+) && gh pr create --title "<title>" --body-file .claude/.tmp/pr-split/<new_name>.md \
+  && rm .claude/.tmp/pr-split/<new_name>.md
+
+# Clean up the body-file dir if all PRs succeeded (no-op when non-empty)
+rmdir .claude/.tmp/pr-split 2>/dev/null || true
+```
+
+## After execution
+
+Respond with exactly one line:
+
+`✅ Renamed: <old> → <new> | PRs: <primary-url>, <url1>, <url2>`
+
+Do not add any other text.
+
+## Stacked merge loop
+
+When the user signals the previous stacked PR has merged, restack the next one.
+
+1. Rebase and push. The own-commit-count comes from the original split table.
+   `git fetch origin main && git checkout <branch> && git rebase --onto origin/main HEAD~<own-commit-count> && git push --force-with-lease`
+2. Verify the PR's base auto-retargeted to main with `gh pr view <num> --json baseRefName`. If not, `gh pr edit <num> --base main`.
+3. Reply: `✅ <branch> rebased onto main. Ready for squash-merge.`
+
+Edge cases:
+
+- If this branch's commits modify a file added by an unmerged upstream PR, wait for that PR to merge before rebasing.
+- If the PR was orphaned by base-branch deletion, recreate it with `gh pr create --base main --head <branch>` and a regenerated body.

package/claude/skills/git-split/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/git-split/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/git-stage/REQUIREMENT.md

@@ -0,0 +1,36 @@
+---
+name: git-stage
+description: What commit grouping is for, the gaps it closes, and how it differs from splitting a branch
+---
+
+# Git stage requirement
+
+## Gap
+
+Without this skill, a staged diff spanning several concerns lands as one commit, so a later revert takes unrelated work with it. A renamed file staged as two separate paths records an add and a delete, losing the rename git would otherwise detect. Commits also land in the order the files happened to be listed rather than the order they depend on, so a bisect stops on a commit that cannot build.
+
+## Must
+
+- Read the commit format reference and the prose standard before generating
+- Derive the groups from the staged diff, with lockfiles excluded from the derivation context
+- Account for every staged file in the preview, so a dropped file is visible before execution
+- Order the commits so a dependency lands before the file that imports it
+- Keep a rename pair in one group and restage both paths together, so git still detects the rename at commit time
+- Unstage everything first, then restage per group, since the incoming staged set is one undifferentiated blob
+- Count each subject against the length limit and shorten before executing
+
+## Must not
+
+- Stage a file the user did not stage. The staged set is the input and widening it changes what ships.
+- Split a rename pair across groups
+- Emit anything after the result line. This runs inside a longer flow and prose here buries the next step.
+
+## Guards
+
+- Nothing staged: stop and name the command that stages
+
+## Out of scope
+
+- Composing a single commit from the whole staged diff, which `git-commit` owns
+- Splitting commits across branches, which `git-split` owns. The two partition different things: this one takes a staged diff and emits commits, that one takes commits and emits branches.
+- Pushing and opening the pull request, which `git-pr` owns

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

@@ -0,0 +1,74 @@
+---
+name: git-stage
+description: Groups staged files by concern and generates one conventional commit per group. Use when staged changes span multiple concerns and need to ship as separate commits.
+---
+
+# Git stage
+
+Read these files in parallel:
+
+- `${CLAUDE_SKILL_DIR}/references/commit.md`: format, types, scopes, and constraints
+- `.claude/standards/prose.md` from the project root: prose conventions for all generated text
+
+Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
+
+## Context
+
+Run these commands in parallel to gather git context:
+
+- `git diff --cached --name-status 2>/dev/null || echo "NO_STAGED_FILES"`
+- `git diff --cached -- . ':(exclude)*.lock' ':(exclude)*-lock.json' 2>/dev/null || echo "NO_DIFF"`
+
+## Guards
+
+- If staged files output is `NO_STAGED_FILES`, stop and output:
+  `❌ No staged files. Stage files first with git add before committing.`
+
+## Grouping rules
+
+- Analyze the diff to understand what each file changes and why.
+- Group files by shared concern. A group is a single commit.
+- Files belong together when they implement or modify the same logical unit.
+- A file that clearly stands alone is its own group.
+- Order commits by dependency: commit dependencies before the files that import them.
+- Prefix the full command sequence with `git restore --staged .` to unstage everything, then stage and commit each group in order.
+- For `D` status files, use `git rm <file>`. For `A` or `M` files, use `git add <file>`.
+- For `R<score>` status rows, `--name-status` emits three tab-separated fields: `R<score>\t<old>\t<new>`. Treat the pair as one file, keep both paths in the same group, and restage them together with `git add <old> <new>` so git detects the rename at commit time. Splitting the pair across groups produces an add-plus-delete pair instead of a rename.
+
+## Response format
+
+### Preview
+
+**Staged files:** <total count>
+**Proposed commits:** <group count>
+
+| #   | Commit                       | Files       | Count |
+| --- | ---------------------------- | ----------- | ----- |
+| 1   | `<type>(<scope>): <subject>` | <filenames> | <n>   |
+| 2   | `<type>(<scope>): <subject>` | <filenames> | <n>   |
+
+**All <total> files accounted for.**
+
+Count characters in each `<type>(<scope>): <subject>` line. Shorten any subject that exceeds 72 characters and update the table.
+
+After outputting the preview, execute the final command immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+
+### Final command
+
+```bash
+git restore --staged .
+# Commit 1: <subject>
+git add <file1> <file2> && git commit -m "<type>(<scope>): <subject>"
+# Commit 2: <subject>
+git rm <deleted1> && git add <file3> && git commit -m "<type>(<scope>): <subject>"
+# Commit 3 (rename): <subject>
+git add <old> <new> && git commit -m "<type>(<scope>): <subject>"
+```
+
+## After execution
+
+Respond with exactly one line:
+
+`✅ Committed: <n> commits`
+
+Do not add any other text.

package/claude/skills/git-stage/references/commit.md

@@ -0,0 +1,63 @@
+---
+title: Commit reference
+description: Commit message format and type conventions
+consumers: git-commit, git-stage
+---
+
+# Commit message reference
+
+## Format
+
+- Structure: `<type>(<scope>): <subject>`
+- Casing: lowercase for `<type>`, `<scope>`, and first word of `<subject>`
+- Subject: 72 characters maximum, no trailing period
+
+## 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
+
+## Scope
+
+- Single lowercase word representing a system component
+- Prefer single word
+- Use kebab-case only when two words are genuinely needed for specificity
+- Do not use specific filenames as scopes
+- Do not use a scope that duplicates the type
+- Write scopes for release readability. They surface in `changelogithub` release notes.
+
+## Subject
+
+- Use imperative mood (`add` not `added`)
+- Describe the actual technical change, not that something changed
+- Do not use vague verbs (`improve`, `refine`, `enhance`)
+- Do not repeat the scope in the subject line
+- Use single quotes if quoting
+- No backslash escaping or internal double quotes
+- No conversational filler or introductory phrases
+
+## Examples
+
+### Correct
+
+```plaintext
+feat(api): add retry logic for failed webhooks       # specific verb + clear change
+fix(auth): update 'UserSession' validation logic     # scoped + imperative + single quotes
+```
+
+### Incorrect
+
+```plaintext
+fix(user-auth): Fixed the redirect loop.    # wrong casing + period + multi-word scope
+docs(docs): update the readme.              # duplicate scope + period
+docs(api): improve documentation            # vague verb + lacks specificity
+```

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

@@ -0,0 +1,37 @@
+---
+name: git-worktree
+description: What worktree listing and cleanup is for, the gaps it closes, and why entry lives elsewhere
+---
+
+# Git worktree requirement
+
+## Gap
+
+Without this skill, linked worktrees accumulate past the point where any of them is remembered. Merge state does not appear in the worktree list, so a cleanup either removes a worktree still holding unmerged work or, lacking a way to tell, removes nothing. Removing a worktree also leaves its local branch behind, so the branch list keeps growing even when cleanup runs.
+
+## Must
+
+- Resolve merge state per branch from the pull request first, and fall back to local ancestry when no pull request exists
+- Match the ancestry fallback against the branch name alone. `git branch --merged` decorates the current branch and every branch checked out in a linked worktree, which is the whole set this skill enumerates.
+- Remove the worktree and its local branch together, since either one left alone is the state the skill exists to prevent
+- Exclude the main root, the current session's worktree, and any dirty tree from the remove set
+- Give every skipped row a one-word reason, so the skip is a decision the user can overturn rather than a silence
+- Pick exactly one mode. Listing and removing are different requests and inferring both from one invocation removes worktrees the user meant to read about.
+
+## Must not
+
+- Enter or create a worktree. The description states the boundary so the model routes entry elsewhere rather than discovering it here.
+- Remove a worktree with uncommitted work, whatever its merge state
+- Remove the worktree the session is currently running in
+- Emit anything after the result line
+
+## Guards
+
+- Not a git repository: stop
+- Remove set is empty: stop and say why every row was held back
+
+## Out of scope
+
+- Entering a worktree, which `claude-worktree` owns. That skill derives the name and aligns the branch, and this one never creates.
+- Deciding which features can run in parallel, which is a planning call rather than a git operation
+- The pull request lifecycle, which `git-pr` and `git-followup` own. This skill reads pull request state and never writes it.