@erclx/aitk 3.10.0 → 3.11.0

package/claude/skills/git-issue/references/issue.md

@@ -1,95 +0,0 @@
----
-title: Issue reference
-description: GitHub issue title, labels, and body conventions
-consumers: git-issue
----
-
-# Issue reference
-
-## Scope
-
-Governs a tracker issue: its title, its labels, and the sections its body carries.
-
-Does not govern:
-
-- Pull request title and body: `pr.md`
-- Whether a phase label may appear in issue text: `versioning.md`
-- Voice, rhythm, and sentence construction in issue prose: the `write-human` skill
-- Punctuation, formatting, and banned words in issue prose: `markdown.md`
-
-## Title
-
-- Format: `<type>: <subject>`
-- Type is `bug` or `task`. Lowercase the type and the first word of the subject.
-- Length: 72 characters maximum, no trailing period.
-
-## Labels
-
-- Apply `bug` for a defect and `enhancement` for a task or improvement.
-- Both are GitHub default labels. A label that does not exist makes `gh` reject the issue. Create it once with `gh label create`.
-- One label per issue unless a second genuinely applies.
-
-## Content
-
-- Use imperative mood and describe the actual defect or work, not that something is wrong.
-- Do not open with "This issue," "I want," or "We should."
-- Do not use buzzwords or speculative future scope.
-- State observable behavior for a bug, not a guessed cause.
-
-## Sections
-
-- `## Summary`: one line naming what and why.
-- `## Details`: for a bug, what happens versus what is expected. For a task, what to build.
-- `## Context`: for a bug, repro steps or commands. For a task, the driving reason, or `none`.
-- `## Proposed` (optional): one line naming a fix or approach. Omit when open.
-
-## Formatting
-
-- End every bullet with a period.
-- Keep each section to one or two lines.
-
-## Examples
-
-### Correct (bug)
-
-```markdown
-## Summary
-
-Fix the feedback CLI so it applies the `feedback` label.
-
-## Details
-
-`aitk feedback --github` opens an issue with no label, so `toolkit-triage` never lists it.
-
-## Context
-
-Run a piped `aitk feedback --github`, then check the issue carries no `feedback` label.
-
-## Proposed
-
-Pass `--label feedback` through the shared issue helper.
-```
-
-### Correct (task)
-
-```markdown
-## Summary
-
-Add a git-issue skill so a session can file an issue on the current repo.
-
-## Details
-
-Format an issue from session context and file it with `gh issue create`, next to git-pr in the git family.
-
-## Context
-
-The toolkit-issue skill only files on the toolkit repo. A general path is needed for target projects.
-```
-
-### Incorrect
-
-```markdown
-## Summary
-
-This issue is about the feedback system being kind of broken, and we should probably make it more robust.
-```

package/claude/skills/git-pr/references/branch.md

@@ -1,60 +0,0 @@
----
-title: Branch reference
-description: Branch naming format and type conventions
-consumers: git-branch, git-split, git-pr, claude-worktree
----
-
-# Branch reference
-
-## Scope
-
-Governs a git branch name: its structure, its length, and the type vocabulary it draws from.
-
-Does not govern:
-
-- Commit subject format, which shares the type vocabulary: `commit.md`
-- Pull request title and body: `pr.md`
-- Whether a phase label may appear in a branch name: `versioning.md`
-- Deriving a slug from a branch name for use in an output filename: `slug.md`
-
-## 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-pr/references/pr.md

@@ -1,139 +0,0 @@
----
-title: Pull request reference
-description: Pull request title and body conventions
-consumers: git-split, git-pr
----
-
-# Pull request reference
-
-## Scope
-
-Governs a pull request title and body: their format and the sections the body carries.
-
-Does not govern:
-
-- Commit subject format, which shares the title form: `commit.md`
-- Branch naming: `branch.md`
-- Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
-- Voice, rhythm, and sentence construction in pull request prose: the `write-human` skill
-- Punctuation, formatting, and banned words in pull request prose: `markdown.md`
-
-## 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.
-- What makes a human required is a capability the agent lacks, never the cost of the run. Authorizing a spend is the operator's and performing the run is not, so an arm the repository ships a harness for gets driven once the operator has cleared the spend, and the box records what it returned.
-- A tool refusal that actually fired is a capability gap, and the line says which refusal rather than naming the cost behind it. A refusal predicted and never met is not one.
-- A live agent session is not a human. A box reading `needs a live session driving the skill` names the thing writing the description, so that run is owed rather than blocked.
-- 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-split/references/pr.md

@@ -1,139 +0,0 @@
----
-title: Pull request reference
-description: Pull request title and body conventions
-consumers: git-split, git-pr
----
-
-# Pull request reference
-
-## Scope
-
-Governs a pull request title and body: their format and the sections the body carries.
-
-Does not govern:
-
-- Commit subject format, which shares the title form: `commit.md`
-- Branch naming: `branch.md`
-- Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
-- Voice, rhythm, and sentence construction in pull request prose: the `write-human` skill
-- Punctuation, formatting, and banned words in pull request prose: `markdown.md`
-
-## 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.
-- What makes a human required is a capability the agent lacks, never the cost of the run. Authorizing a spend is the operator's and performing the run is not, so an arm the repository ships a harness for gets driven once the operator has cleared the spend, and the box records what it returned.
-- A tool refusal that actually fired is a capability gap, and the line says which refusal rather than naming the cost behind it. A refusal predicted and never met is not one.
-- A live agent session is not a human. A box reading `needs a live session driving the skill` names the thing writing the description, so that run is owed rather than blocked.
-- 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/references/commit.md

@@ -1,73 +0,0 @@
----
-title: Commit reference
-description: Commit message format and type conventions
-consumers: git-commit, git-stage
----
-
-# Commit message reference
-
-## Scope
-
-Governs a git commit message: subject structure, the type and scope vocabulary, and the body.
-
-Does not govern:
-
-- Branch naming, which shares the type vocabulary: `branch.md`
-- Pull request title and body, which share the subject form: `pr.md`
-- Whether a phase label or a semver tag may appear in a subject: `versioning.md`
-
-## 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 vocabulary
-
-- 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/scripts/core/regen-skill-references.sh

@@ -1,27 +0,0 @@
-#!/usr/bin/env bash
-set -e
-set -o pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
-
-source "$PROJECT_ROOT/scripts/lib/frontmatter.sh"
-
-BUNDLED_DIR="$PROJECT_ROOT/standards/bundled"
-SKILLS_DIR="$PROJECT_ROOT/claude/skills"
-
-[ -d "$BUNDLED_DIR" ] || exit 0
-
-while IFS= read -r file; do
-  filename="$(basename "$file")"
-  consumers="$(read_frontmatter_field "$file" "consumers")"
-  [ -z "$consumers" ] && continue
-  IFS=',' read -ra skills <<<"$consumers"
-  for skill in "${skills[@]}"; do
-    skill="${skill// /}"
-    [ -z "$skill" ] && continue
-    dest_dir="$SKILLS_DIR/$skill/references"
-    mkdir -p "$dest_dir"
-    cp "$file" "$dest_dir/$filename"
-  done
-done < <(find "$BUNDLED_DIR" -type f -name "*.md" | sort)

package/standards/bundled/branch.md

@@ -1,60 +0,0 @@
----
-title: Branch reference
-description: Branch naming format and type conventions
-consumers: git-branch, git-split, git-pr, claude-worktree
----
-
-# Branch reference
-
-## Scope
-
-Governs a git branch name: its structure, its length, and the type vocabulary it draws from.
-
-Does not govern:
-
-- Commit subject format, which shares the type vocabulary: `commit.md`
-- Pull request title and body: `pr.md`
-- Whether a phase label may appear in a branch name: `versioning.md`
-- Deriving a slug from a branch name for use in an output filename: `slug.md`
-
-## 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/standards/bundled/commit.md

@@ -1,73 +0,0 @@
----
-title: Commit reference
-description: Commit message format and type conventions
-consumers: git-commit, git-stage
----
-
-# Commit message reference
-
-## Scope
-
-Governs a git commit message: subject structure, the type and scope vocabulary, and the body.
-
-Does not govern:
-
-- Branch naming, which shares the type vocabulary: `branch.md`
-- Pull request title and body, which share the subject form: `pr.md`
-- Whether a phase label or a semver tag may appear in a subject: `versioning.md`
-
-## 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 vocabulary
-
-- 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
-```