haac-aikit 0.1.0

package/catalog/skills/tier1/using-git-worktrees.md

@@ -0,0 +1,43 @@
+---
+name: using-git-worktrees
+description: Use when starting work on a new feature, experiment, or large refactor that should be isolated from the current working tree. Prevents clobbering in-progress work and enables parallel development across multiple branches simultaneously.
+version: "1.0.0"
+source: obra/superpowers
+license: MIT
+---
+
+## When to use
+- Starting a feature that will take multiple sessions
+- Running a risky refactor you might want to abandon
+- Exploring an approach in parallel with the current code
+- When the human says "try this in isolation" or "don't touch the main branch"
+
+## Setup
+
+```bash
+# Create a new worktree for a feature branch
+git worktree add ../my-repo-feature feature/my-feature
+
+# Work in the isolated tree
+cd ../my-repo-feature
+
+# When done, remove the worktree
+cd ../my-repo
+git worktree remove ../my-repo-feature
+```
+
+## Rules
+
+1. **Name worktrees clearly**: `<repo>-<branch-slug>` in a sibling directory, not a subdirectory of the main repo.
+
+2. **One branch per worktree**: git enforces this — the same branch cannot be checked out in two worktrees simultaneously.
+
+3. **Don't commit from the wrong tree**: confirm `git branch` shows the expected branch before committing.
+
+4. **Clean up after merging**: `git worktree list` shows dangling worktrees; remove them with `git worktree remove`.
+
+5. **Shared objects, separate index**: changes in a worktree do not affect the main tree's index or stash. You can run tests, build, and experiment without touching the main tree's state.
+
+## When NOT to use
+- Small, low-risk changes — a worktree adds overhead for a 5-minute fix
+- When you need the full IDE toolchain to be pointed at the worktree (some tools don't follow worktrees well)

package/catalog/skills/tier1/verification-before-completion.md

@@ -0,0 +1,46 @@
+---
+name: verification-before-completion
+description: Use before reporting any task as complete. Ensures claims of success are backed by evidence, not assumption. Prevents marking work done when it compiles but doesn't actually do what was asked.
+version: "1.0.0"
+source: obra/superpowers
+license: MIT
+---
+
+## When to use
+- Before saying "done", "complete", "implemented", "fixed"
+- After any code change that was meant to achieve a specific outcome
+- Before handing off to the human for review
+
+## Verification checklist
+
+Before claiming completion, provide evidence for each applicable item:
+
+**1. The change does what was requested**
+- Run the affected test(s) — paste the output
+- Or run the specific command / endpoint that demonstrates the behaviour
+- Do not assert "this should work" — show that it does
+
+**2. Nothing else broke**
+- Run the full test suite (or the relevant subset) — paste the pass/fail count
+- If tests are slow, run at minimum: the directly affected tests + integration tests
+
+**3. Type safety is maintained**
+- `tsc --noEmit` passes without error
+- No `@ts-ignore` was added without a documented justification
+
+**4. The code is in the right shape**
+- Dead code removed from the path you modified
+- No debug logging (`console.log`) left in
+- No TODO comments introduced without a corresponding issue
+
+## Reporting completion
+
+Structure:
+```
+Done. Evidence:
+- [test name]: PASS (output: ...)
+- Full suite: X passed, 0 failed
+- TypeScript: clean
+```
+
+Do not say "this should work" or "I believe this is correct." Show the output.

package/catalog/skills/tier1/writing-commits.md

@@ -0,0 +1,52 @@
+---
+name: writing-commits
+description: Use when creating a git commit. Enforces Conventional Commits format, prevents committing secrets or debug artifacts, and ensures the commit message explains why rather than what. Never use --no-verify or --amend on published commits.
+version: "1.0.0"
+source: haac-aikit
+license: MIT
+---
+
+## Commit format
+
+```
+type(scope): description
+
+[optional body: one paragraph explaining WHY, not WHAT]
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+**Types**: `feat` `fix` `refactor` `test` `docs` `chore` `perf`
+**Scope**: the module, file group, or feature area (e.g. `auth`, `api`, `cli`)
+**Description**: imperative mood, ≤72 chars, no period
+
+## Pre-commit checklist
+
+Before staging:
+1. `git diff --staged` — confirm no `.env*`, `secrets/`, `*.pem`, `id_rsa*` files
+2. No `console.log` / debug output left in
+3. No `// @ts-ignore` added without a comment explaining why
+4. No TODO comments pointing at unresolved issues introduced in this commit
+
+## Creating the commit
+
+Always use HEREDOC to preserve newlines:
+```bash
+git commit -m "$(cat <<'EOF'
+feat(auth): add refresh token rotation
+
+Refresh tokens are now single-use; each use issues a new token pair.
+This prevents replay attacks from stolen refresh tokens while keeping
+sessions alive without re-authentication.
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
+## Safety rules
+
+- **Never** `git push --force` to `main`/`master`/`develop`
+- **Never** `git commit --no-verify`
+- **Never** `git commit --amend` on a commit that has been pushed
+- If a pre-commit hook fails: fix the underlying issue, re-stage, create a NEW commit

package/catalog/skills/tier1/writing-plans.md

@@ -0,0 +1,42 @@
+---
+name: writing-plans
+description: Use when starting a multi-step implementation task, before entering plan mode, or when the human asks you to plan. Turns an approved approach into a sequenced, bite-sized plan that a second agent could execute without further clarification.
+version: "1.0.0"
+source: obra/superpowers
+license: MIT
+---
+
+## When to use
+- Any task that touches more than 2 files or has more than 3 steps
+- Before running /execute or dispatching an implementer agent
+- When the human says "plan this" or "let's plan before we build"
+
+## Plan structure
+
+```
+PLAN:
+1. [concrete action] — [why: what it enables]
+2. [concrete action] — [why: dependency or risk managed]
+...
+N. [concrete action] — [why]
+→ Executing unless you redirect.
+```
+
+## Rules for a good plan
+
+**Each step must be**:
+- An action that produces a verifiable artifact (file created, test passes, function deleted)
+- Independently reversible without undoing prior steps
+- Executable by someone who hasn't read the previous steps
+
+**Order steps by dependency**: if step N needs step N-1 to be done first, they are sequential. Steps with no dependency on each other can be done in parallel (mark them explicitly).
+
+**Include a verification step** at the end: "Run tests; confirm no regressions."
+
+## What not to include
+- Vague steps like "refactor the auth module" — decompose until atomic
+- Steps that say "figure out how X works" — that's exploration, not a plan step
+- More than 10 steps — if the plan is longer, split into phases
+
+## Before executing
+Present the full plan to the human. Confirm they approve before taking any action. If they redirect, revise the plan before executing.

package/catalog/skills/tier2/claude-md-improver.md

@@ -0,0 +1,42 @@
+---
+name: claude-md-improver
+description: Use when CLAUDE.md (or AGENTS.md) has grown stale, too long, or needs reorganisation. Audits the file against the ≤200 line budget, removes noise, promotes high-signal rules, and restructures to put critical rules at the front and back (primacy + recency bias).
+version: "1.0.0"
+source: anthropics/skills
+license: Apache-2.0
+---
+
+## When to use
+- CLAUDE.md is over 150 lines and growing
+- Rules are being ignored by the agent despite being written down
+- After a significant architectural change makes old rules stale
+- When the human says "clean up CLAUDE.md" or "update AGENTS.md"
+
+## Audit checklist
+
+### Size gate (≤200 lines per Anthropic guidance)
+- Count lines: `wc -l CLAUDE.md`
+- If over 200: identify candidates for removal or migration to skills
+
+### Content that should be removed
+- [ ] Rules the agent never violates (no-ops — remove them)
+- [ ] Rules duplicating linter/formatter enforcement (let tooling own it)
+- [ ] Historical context that belongs in the PR description, not here
+- [ ] Vague rules like "write good code" — if it can't be violated, it's not a rule
+- [ ] Stack-specific details that belong in a skill, not global context
+
+### Content that should stay
+- [ ] Non-negotiable project-specific rules (things the agent gets wrong repeatedly)
+- [ ] Security constraints that must fire every session
+- [ ] Domain vocabulary the agent needs to understand
+
+### Structure
+Reorder rules so:
+1. **First 5 lines**: the single most critical constraint
+2. **Middle**: supporting rules
+3. **Last 5 lines**: the second most critical constraint (recency bias)
+
+## After editing
+- Confirm: `wc -l CLAUDE.md` ≤200
+- Run a test session to confirm critical rules are still followed
+- Commit with `docs(claude): trim CLAUDE.md to [N] lines`

package/catalog/skills/tier2/dependency-hygiene.md

@@ -0,0 +1,52 @@
+---
+name: dependency-hygiene
+description: Use before installing any new package. Evaluates whether the dependency is necessary, checks for existing alternatives in the codebase, assesses license compatibility and maintenance health. Prevents dependency bloat and security surface expansion.
+version: "1.0.0"
+source: haac-aikit
+license: MIT
+---
+
+## When to use
+- Before `npm install`, `pip install`, `go get`, `cargo add`
+- When the human says "we need a library for X"
+- When refactoring and wondering if a dep can be removed
+
+## Pre-install checklist
+
+### 1. Is it already covered?
+```bash
+# Check if the functionality is already available
+grep -r "require\|import" src/ | grep -i "<keyword>"
+cat package.json | grep -i "<keyword>"
+```
+Check built-in language APIs first — `node:crypto`, `node:fs`, standard library.
+
+### 2. What does this dep cost?
+```bash
+npx cost-of-modules <package>   # or bundlephobia.com
+npm info <package> | head -20   # version, maintainers, last publish
+```
+- Bundle size impact (for browser code)
+- Transitive dependency count
+- Last published date (>2 years without activity is a yellow flag)
+
+### 3. License check
+- MIT, Apache 2.0, BSD: generally safe
+- GPL, AGPL: may require open-sourcing your code — confirm with policy
+- Proprietary: requires explicit approval
+- Check: `npm info <package> license`
+
+### 4. Maintenance health
+- Stars + recent activity on GitHub (not a hard requirement, but signals)
+- Open CVEs: `npm audit` after install, or check Snyk/OSV
+
+## Decision output
+```
+Dependency assessment: <package>
+- Existing coverage: [none / partial via X]
+- Bundle size: [Xkb / not applicable]
+- License: [MIT / ...]
+- Last release: [date]
+- Verdict: [INSTALL / USE_BUILTIN(X) / DEFER / REJECT]
+- Reason: [one sentence]
+```

package/catalog/skills/tier2/dispatching-parallel-agents.md

@@ -0,0 +1,43 @@
+---
+name: dispatching-parallel-agents
+description: Use when a task can be decomposed into independent sub-tasks that don't share state. Fan out to fresh subagents to work in parallel, then synthesise results. Prevents serialising work that could run concurrently and wastes wall-clock time.
+version: "1.0.0"
+source: obra/superpowers
+license: MIT
+---
+
+## When to use
+- Research across multiple files/modules that don't depend on each other
+- Running the same operation on several independent targets (e.g. reviewing 4 services)
+- Gathering information from multiple sources simultaneously
+
+## Decomposition rules
+
+A sub-task is safe to parallelise if:
+1. It requires no output from another concurrent sub-task
+2. It does not write to shared state (files, databases, branches)
+3. Its result is a summary or report, not a mutation
+
+If any sub-task writes files: do not parallelise — writing conflicts produce unpredictable results.
+
+## Dispatch format
+
+```
+Dispatching [N] parallel agents:
+- Agent 1: [role] — [specific task] — returns: [expected output format]
+- Agent 2: [role] — [specific task] — returns: [expected output format]
+- Agent N: [role] — [specific task] — returns: [expected output format]
+```
+
+Each agent brief must be self-contained — include file paths, relevant context, and the exact question to answer. The agent has no memory of this conversation.
+
+## Synthesis
+
+After all agents return:
+1. Identify agreements and conflicts across their outputs
+2. Resolve conflicts explicitly (don't average or ignore them)
+3. Produce a unified summary with sources attributed
+
+## Tool
+
+Use the `Agent` tool with `run_in_background: true` for genuinely parallel tasks. Send multiple tool calls in a single message.

package/catalog/skills/tier2/finishing-a-development-branch.md

@@ -0,0 +1,48 @@
+---
+name: finishing-a-development-branch
+description: Use when a feature or fix is complete and needs to be merged. Guides the merge/PR/cleanup decision tree to ensure branches land cleanly, CI passes, and the branch is removed after merging.
+version: "1.0.0"
+source: obra/superpowers
+license: MIT
+---
+
+## When to use
+- "I think this is ready to merge"
+- "How do I finish this branch?"
+- After verification-before-completion confirms the implementation is correct
+
+## Decision tree
+
+### 1. Is the branch up to date with the base?
+```bash
+git fetch origin
+git log HEAD..origin/main --oneline
+```
+If behind: `git rebase origin/main` (preferred over merge for feature branches).
+
+### 2. Are all tests passing?
+Run the full suite. If not: fix before merging.
+
+### 3. Is the diff clean?
+```bash
+git diff main...HEAD --stat
+```
+- No unintended files (build artifacts, `.env*`, debug code)
+- Commit messages are conventional and meaningful
+
+### 4. Create or update the PR
+If no PR exists: use the `writing-pull-requests` skill.
+If PR exists: push, confirm CI is green before requesting review.
+
+### 5. After merge
+```bash
+git checkout main
+git pull
+git branch -d feature/my-feature        # local cleanup
+git push origin --delete feature/my-feature  # remote cleanup (if not auto-deleted)
+```
+
+## Protected branch rules
+- Never merge directly to `main`/`master` without a PR unless the repo explicitly allows it
+- Never `git push --force` to a protected branch
+- If a PR is squash-merged, the feature branch commits disappear — that's expected

package/catalog/skills/tier2/receiving-code-review.md

@@ -0,0 +1,49 @@
+---
+name: receiving-code-review
+description: Use when processing code review feedback. Ensures each finding is genuinely addressed with verification, not performatively acknowledged. Prevents the pattern of saying "good point, fixed!" without actually making the change or thinking through its implications.
+version: "1.0.0"
+source: obra/superpowers
+license: MIT
+---
+
+## When to use
+- After receiving review comments on a PR
+- After a code-reviewer agent returns findings
+- When the human gives feedback on code you wrote
+
+## Processing protocol
+
+### 1. Triage each finding
+
+For each finding, classify:
+- **Must fix**: correctness issue, security vulnerability, broken contract
+- **Should fix**: code quality, maintainability, convention violation
+- **Consider**: style preference, subjective tradeoff, nice-to-have
+
+### 2. For each finding you're addressing
+
+1. Understand *why* the reviewer flagged it (not just what they said)
+2. Make the change
+3. Verify: run the affected tests, confirm the finding is resolved
+4. Note what you changed in a brief summary
+
+### 3. For each finding you're declining
+
+1. State your reasoning clearly (one sentence)
+2. If you disagree with a Must fix, defer to the human — do not override
+3. If it's a style preference and you have a documented reason, explain once
+
+### 4. Report back
+
+```
+Review addressed:
+✓ [finding 1]: [what changed]
+✓ [finding 2]: [what changed]
+→ [finding 3]: declined — [reason]
+```
+
+## Anti-patterns to avoid
+- "Good catch, fixed!" without showing the fix
+- Addressing the symptom the reviewer mentioned without fixing the underlying issue
+- Defensive explanations that don't lead to a resolution
+- Marking all findings as acknowledged without changing anything

package/catalog/skills/tier2/refactoring-simplify.md

@@ -0,0 +1,40 @@
+---
+name: refactoring-simplify
+description: Use when reviewing code for over-engineering, duplication, or dead code. Identifies unnecessary abstractions, premature generalisations, and code that should be deleted. Three similar lines is better than a premature abstraction — this skill enforces that principle.
+version: "1.0.0"
+source: anthropics/skills
+license: Apache-2.0
+---
+
+## When to use
+- After a feature is complete and tests are green
+- When the human says "clean this up" or "simplify this"
+- When code review finds the abstraction is unclear
+
+## Simplification checklist
+
+### Duplication
+- [ ] Is the same logic copy-pasted in ≥3 places? → extract a function
+- [ ] Is the same logic copy-pasted in 2 places? → leave it; wait for a third before abstracting
+- [ ] Are there near-identical functions that differ by one variable? → parameterise
+
+### Over-abstraction
+- [ ] Does the abstraction have only one caller? → inline it
+- [ ] Does the abstraction require understanding 3+ files to use? → likely too abstract
+- [ ] Is there an interface with only one implementation? → remove the interface
+
+### Dead code
+- [ ] Functions that are never called (check with grep + TypeScript `noUnusedLocals`)
+- [ ] Branches that can never be reached (check for impossible conditions)
+- [ ] Feature flags that are always true or always false
+- [ ] Commented-out code blocks → delete (git history preserves history)
+
+### Naming
+- [ ] Misleading names: a function named `getUser` that also creates a user
+- [ ] Generic names (`data`, `result`, `temp`, `obj`) that could be more descriptive
+- [ ] Abbreviations that aren't universally understood in this domain
+
+## Rules
+- Do not refactor without green tests first
+- Do not mix refactoring commits with behaviour changes
+- Do not extract an abstraction "for future use" — YAGNI

package/catalog/skills/tier2/security-review.md

@@ -0,0 +1,48 @@
+---
+name: security-review
+description: Use before committing code that handles user input, authentication, file operations, external API calls, or environment variables. Performs an OWASP-aligned sweep to catch injection, auth, secrets, and access-control vulnerabilities before they reach main.
+version: "1.0.0"
+source: haac-aikit
+license: MIT
+---
+
+## When to use
+- Before creating a PR that touches auth, API endpoints, file I/O, or env handling
+- When the human asks for a security review
+- After adding any new external-facing surface
+
+## Review checklist
+
+### Injection (A03)
+- [ ] All SQL queries use parameterised statements / ORM — no string concatenation
+- [ ] Shell commands use `execFile`/`spawnFile` with arg arrays — never pass user data to shell-form exec
+- [ ] Template rendering sanitises HTML — no direct `innerHTML = userInput`
+- [ ] File paths constructed from user input are canonicalised and bounded
+
+### Authentication & session (A07)
+- [ ] Tokens are not logged or included in error responses
+- [ ] Session IDs are regenerated on privilege escalation
+- [ ] Password resets use time-limited, single-use tokens
+
+### Sensitive data (A02)
+- [ ] No secrets, API keys, or credentials in source code
+- [ ] No secrets in log output
+- [ ] Env vars are validated at startup — missing required secrets fail fast
+- [ ] `console.log(req)` or `console.log(user)` that might expose sensitive fields
+
+### Access control (A01)
+- [ ] Every endpoint/route checks authorisation — not just authentication
+- [ ] Resource ownership is verified (user can only access their own resources)
+- [ ] Admin/privileged routes are explicitly gated
+
+### Supply chain (A06)
+- [ ] No new dependencies installed without `dependency-hygiene` review
+- [ ] `npm audit` / `pip-audit` passes
+
+## Output format
+```
+Security sweep: [scope]
+✓ No issues found in [category]
+⚠ [category]: [finding] at [file:line] — [recommended fix]
+✗ [critical finding] — MUST fix before merge
+```

package/catalog/skills/tier2/writing-pull-requests.md

@@ -0,0 +1,47 @@
+---
+name: writing-pull-requests
+description: Use when creating a pull request. Produces a PR title under 70 characters and a body with Summary and Test Plan sections that give reviewers everything they need without having to read the full diff.
+version: "1.0.0"
+source: haac-aikit
+license: MIT
+---
+
+## When to use
+- After finishing a branch and all tests pass
+- When the human says "create a PR" or "open a PR"
+
+## PR format
+
+```bash
+gh pr create --title "<type>(scope): short description" --body "$(cat <<'EOF'
+## Summary
+- [What changed — bullet per logical unit]
+- [Why it was needed]
+- [Any breaking changes or migration steps]
+
+## Test plan
+- [ ] [How to verify behaviour 1]
+- [ ] [How to verify behaviour 2]
+- [ ] Full suite: `npm test` passes
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+## Title rules
+- ≤70 characters
+- Conventional Commits format: `type(scope): description`
+- Imperative mood: "add auth middleware", not "added" or "adds"
+- Describes the change, not the solution: "fix session expiry bug", not "fix tokenStore.refresh logic"
+
+## Body rules
+- Summary is bullets — not prose paragraphs
+- Test plan is a checklist the reviewer can actually run
+- Include migration steps if there are schema changes, config changes, or required env vars
+- Do not include the full commit history or a timeline of how you got here
+
+## Pre-create checklist
+1. `git log main...HEAD --oneline` — confirm commits are clean
+2. `gh pr list --head $(git branch --show-current)` — confirm no duplicate PR
+3. CI is green on the branch (check with `gh pr checks`)