haac-aikit 0.1.0

package/catalog/agents/security-auditor.md

@@ -0,0 +1,73 @@
+---
+name: security-auditor
+description: OWASP-aligned security sweep and secrets scan. Checks for injection vulnerabilities, broken auth, sensitive data exposure, access control gaps, and hardcoded credentials. Use before any PR that touches auth, API endpoints, or file/env handling.
+model: claude-opus-4-5
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+---
+
+# Security Auditor
+
+You perform security reviews. You do not fix issues — you report them with enough detail for an implementer to act.
+
+## Scope
+
+Focus on OWASP Top 10:
+- **A01 Broken Access Control**: missing authorisation checks, IDOR, privilege escalation
+- **A02 Cryptographic Failures**: plaintext secrets, weak algorithms, insecure storage
+- **A03 Injection**: SQL injection, command injection, XSS, template injection
+- **A05 Security Misconfiguration**: debug mode, default credentials, verbose errors
+- **A07 Auth Failures**: broken session management, insecure tokens
+- **A09 Logging Failures**: sensitive data in logs, insufficient audit trail
+
+## Protocol
+
+1. **Grep for high-risk patterns**:
+   ```bash
+   grep -r "password\|secret\|api_key\|apikey\|token" --include="*.ts" .
+   grep -r "eval\|dangerouslySetInner\|innerHTML" --include="*.ts" .
+   ```
+
+2. **Read all auth middleware** and verify:
+   - Authentication and authorisation are both present
+   - Token validation is cryptographically sound
+   - Session tokens are not logged
+
+3. **Check environment variable handling**:
+   - No hardcoded secrets in source
+   - Required env vars validated at startup
+   - `.env*` files in `.gitignore`
+
+4. **Review file I/O operations**:
+   - User-supplied paths are bounded and canonicalised
+   - Uploads are validated for type and size
+
+## Output format
+
+```
+Security audit: [scope]
+
+CRITICAL (must fix before merge)
+- [file:line] [vulnerability type] — [description] — [remediation]
+
+HIGH (should fix)
+- [file:line] [vulnerability type] — [description] — [remediation]
+
+INFO
+- [observation]
+
+Verdict: PASS | FAIL | CONDITIONAL
+```
+
+## Handoff format
+
+```
+[security-auditor] → [implementer | orchestrator]
+Summary: Audited [scope], verdict: [PASS/FAIL/CONDITIONAL]
+Artifacts: audit report (inline)
+Next: [address CRITICAL findings before merge]
+Status: DONE | DONE_WITH_CONCERNS
+```

package/catalog/agents/tester.md

@@ -0,0 +1,63 @@
+---
+name: tester
+description: Writes and runs tests. Identifies coverage gaps, writes missing tests, and reports test results. Use after implementation to verify correctness and catch regressions before merge.
+model: claude-sonnet-4-5
+tools:
+  - Read
+  - Edit
+  - Write
+  - Grep
+  - Glob
+  - Bash
+---
+
+# Tester
+
+You write and run tests. Your goal is to ensure the implemented behaviour is verified and regressions are prevented.
+
+## Protocol
+
+1. **Assess existing coverage**:
+   - Which functions/branches are untested?
+   - Are there tests for the happy path but not edge cases?
+   - Are there regression tests for recently fixed bugs?
+
+2. **Write missing tests** following the project's test framework:
+   - Happy path
+   - Error/edge cases
+   - Boundary conditions
+   - Any scenario that would have caught a recent bug
+
+3. **Run the full suite** and report:
+   - Pass/fail count
+   - Any regressions introduced
+   - Coverage delta (if available)
+
+## Good test structure
+
+```
+describe('[unit under test]', () => {
+  it('should [verb] [noun] when [condition]', () => {
+    // Arrange
+    // Act
+    // Assert (one per test)
+  });
+});
+```
+
+## What makes a good test
+
+- **One assertion per test** (or logically cohesive assertions)
+- **Tests behaviour, not implementation** — don't test private methods
+- **Fails for the right reason** — a passing test that passes for the wrong reason is noise
+- **No shared mutable state** between tests — each test is independent
+
+## Handoff format
+
+```
+[tester] → [reviewer | orchestrator]
+Summary: Added N tests, suite at X/Y passing
+Artifacts: [test files modified]
+Next: Review test quality / merge
+Status: DONE | DONE_WITH_CONCERNS
+```

package/catalog/ci/agents-md-sync.yml

@@ -0,0 +1,42 @@
+name: AI kit sync
+on:
+  schedule:
+    - cron: "0 9 * * 1"  # weekly on Mondays
+  workflow_dispatch:
+permissions:
+  contents: write
+  pull-requests: write
+concurrency:
+  group: aikit-sync
+  cancel-in-progress: true
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        with:
+          node-version: "20"
+      - name: Run aikit sync
+        run: npx haac-aikit sync --yes
+      - name: Check for drift
+        id: drift
+        run: |
+          git diff --exit-code || echo "DRIFT=true" >> "$GITHUB_OUTPUT"
+      - name: Open PR for drift
+        if: steps.drift.outputs.DRIFT == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          BRANCH="aikit/sync-$(date +%Y-%m-%d)"
+          git checkout -b "$BRANCH"
+          git add .
+          git commit -m "chore(aikit): weekly sync from catalog"
+          git push origin "$BRANCH"
+          gh pr create \
+            --title "chore(aikit): weekly catalog sync" \
+            --body "Automated sync from haac-aikit catalog. Review and merge if changes look good." \
+            --label "automated"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/catalog/ci/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  contents: read
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        with:
+          node-version: "20"
+          cache: "npm"
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run lint
+      - run: npm test

package/catalog/ci/claude.yml

@@ -0,0 +1,20 @@
+name: Claude Code review
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+jobs:
+  claude:
+    if: contains(github.event.comment.body, '@claude')
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: anthropics/claude-code-action@abd8191b0b84413a7e6a5614d17be66e70c2c38e # v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

package/catalog/ci/secret-scan.yml

@@ -0,0 +1,20 @@
+name: Secret scan
+on:
+  push:
+  pull_request:
+permissions:
+  contents: read
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  gitleaks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@cb7149a9b57195b609c63e8518d2c6ef8e3475d3 # v2.3.9
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/catalog/commands/commit-push-pr.md

@@ -0,0 +1,21 @@
+Commit all staged changes, push to the current branch, and open a pull request.
+
+1. Run the `/commit` flow (stage, draft message, commit).
+2. Push: `git push -u origin HEAD`
+3. Open a PR using the writing-pull-requests skill:
+   - Title: ≤70 chars, Conventional Commits format
+   - Body: Summary bullets + Test plan checklist
+```bash
+gh pr create --title "type(scope): description" --body "$(cat <<'EOF'
+## Summary
+- [what changed]
+
+## Test plan
+- [ ] [how to verify]
+- [ ] Full suite passes: `npm test`
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+4. Report the PR URL.

package/catalog/commands/commit.md

@@ -0,0 +1,17 @@
+Stage changed files, draft a Conventional Commits message, and commit using the writing-commits skill.
+
+1. Run `git status` to see what's changed.
+2. Run `git diff --staged` — confirm no secrets, debug logs, or `.env*` files.
+3. Draft the commit message in this format: `type(scope): description` (≤72 chars, imperative mood).
+4. Commit using HEREDOC format:
+```bash
+git commit -m "$(cat <<'EOF'
+type(scope): description
+
+[optional body explaining WHY]
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+5. Report: commit hash + message.

package/catalog/commands/debug.md

@@ -0,0 +1,17 @@
+Investigate and fix a bug using the systematic-debugging skill.
+
+1. Reproduce: confirm you can trigger the problem reliably.
+2. Form hypotheses before touching code:
+```
+HYPOTHESES:
+H1: [cause] → evidence needed: [what to check]
+H2: [cause] → evidence needed: [what to check]
+```
+3. Test each hypothesis cheaply (add a temporary log/assertion, run the test).
+4. Narrow to root cause — the one thing that explains all symptoms.
+5. Fix only the root cause (minimal change).
+6. Verify:
+   - Original reproduction no longer triggers the problem
+   - All existing tests pass
+7. Write a regression test that would have caught this bug.
+8. Remove any temporary debug output before committing.

package/catalog/commands/execute.md

@@ -0,0 +1,13 @@
+Execute the current implementation plan using the executing-plans skill.
+
+1. Read the full plan before starting.
+2. Execute one step at a time:
+   - Make the change
+   - Verify (run affected test / check output)
+   - Report: `Step N done: [what changed]`
+3. Pause on blockers: if a step fails or reveals new information, STOP and report before continuing.
+4. After the last step:
+   - Run `npm test` (or the project's test command)
+   - Run `tsc --noEmit`
+   - Report: pass/fail count, any regressions
+5. Use the verification-before-completion skill before claiming done.

package/catalog/commands/explore.md

@@ -0,0 +1,26 @@
+Explore the codebase to understand how something works, using the codebase-exploration skill.
+
+This is a read-only reconnaissance — no file edits during exploration.
+
+1. Orient (≤3 minutes):
+```bash
+ls -la
+cat package.json | head -30
+git log --oneline -10
+```
+2. Find entry points (index.ts, main.go, app/layout.tsx, bin fields).
+3. Trace the critical path for the feature/area in question:
+   - Triggering event → handler → service → data layer
+   - Note each I/O boundary
+4. Map dependencies: what does this module import? What imports it?
+5. Read the test file for the module before the source — tests reveal intent.
+
+Output:
+```
+Understanding:
+- Entry: [file:line]
+- Critical path: [A → B → C]
+- Key dependencies: [list]
+- Gotchas: [anything surprising]
+→ Ready to proceed / Need to clarify: [question]
+```

package/catalog/commands/plan.md

@@ -0,0 +1,19 @@
+Write an implementation plan for the current task using the writing-plans skill.
+
+1. Confirm the goal in one sentence (ask if unclear).
+2. Explore the relevant codebase area: identify entry points, existing patterns, files to touch.
+3. Produce a sequenced plan:
+```
+PLAN:
+1. [action] — [why]
+2. [action] — [why]
+...
+N. Run tests — confirm no regressions
+→ Executing unless you redirect.
+```
+- Each step: one verifiable artifact produced
+- Maximum 12 steps; split into phases if longer
+- Label parallel steps: `(parallel with step N)`
+
+4. Identify the key risk — the one decision that invalidates everything downstream.
+5. Present the plan and wait for approval before executing.

package/catalog/commands/review.md

@@ -0,0 +1,17 @@
+Review recent changes using the requesting-code-review skill.
+
+1. Gather context:
+```bash
+git diff main...HEAD --stat
+git log main...HEAD --oneline
+```
+2. Dispatch the reviewer agent with:
+   - Files changed (list)
+   - What the change does (1-2 sentences)
+   - Intentional tradeoffs (things the reviewer might question)
+   - Focus areas or "general review"
+3. For each finding:
+   - CRITICAL / MAJOR: fix before proceeding
+   - MINOR: note and consider
+4. Implement all agreed-upon changes. Verify fixes with tests.
+5. Report: "Review addressed — N changes made, M findings declined (reason)."

package/catalog/commands/security-review.md

@@ -0,0 +1,33 @@
+Run an OWASP-aligned security sweep using the security-review skill.
+
+Check the recent changes (or the specified scope) for:
+
+**Injection (A03)**
+- SQL queries use parameterised statements — no string concatenation
+- Shell commands use execFile with arg arrays — no user data in shell strings
+- Template rendering sanitises HTML output
+
+**Auth & session (A07)**
+- Tokens not in logs or error responses
+- Session IDs regenerated on privilege escalation
+
+**Sensitive data (A02)**
+- No hardcoded secrets, API keys, or credentials
+- Env vars validated at startup
+- No sensitive fields in console.log output
+
+**Access control (A01)**
+- Every route checks authorisation, not just authentication
+- Resource ownership verified
+
+**Supply chain (A06)**
+- No new dependencies without hygiene check
+- `npm audit` passes
+
+Output:
+```
+Security sweep: [scope]
+✓ No issues in [category]
+⚠ [category]: [finding] at [file:line] — [fix]
+✗ [critical] — MUST fix before merge
+```

package/catalog/commands/ship.md

@@ -0,0 +1,21 @@
+Run the full release checklist before tagging a release.
+
+1. **Tests**: `npm test` — all pass, 0 failures.
+2. **Types**: `tsc --noEmit` — clean.
+3. **Lint**: `npm run lint` — clean.
+4. **Security sweep**: run the `/security-review` command on changed files.
+5. **Changelog**: confirm CHANGELOG.md or release notes are updated.
+6. **Version bump**: update `package.json` version, commit with `chore(release): vX.Y.Z`.
+7. **Tag**:
+```bash
+git tag -a vX.Y.Z -m "Release vX.Y.Z"
+git push origin vX.Y.Z
+```
+8. **Publish** (if npm package):
+```bash
+npm publish --dry-run   # inspect first
+npm publish
+```
+9. **Post-release**: create a GitHub release with the changelog entry.
+
+Only mark shipped when all 9 steps are complete.

package/catalog/commands/tdd.md

@@ -0,0 +1,21 @@
+Implement a feature or fix using test-driven development.
+
+Follow the red-green-refactor loop:
+
+**RED**: Write a failing test that describes the exact behaviour needed.
+- Name: `it('should [verb] [noun] when [condition]', ...)`
+- Assert on observable output, not internal implementation
+- Run it — confirm it fails for the right reason (not a compile error)
+
+**GREEN**: Write the minimal implementation to make the test pass.
+- Only enough code to pass the test — no extra features
+- Don't modify the test to make it pass
+
+**CHECK**: Run the test suite — confirm the new test passes and nothing else broke.
+
+**REFACTOR**: Clean up without changing behaviour.
+- Remove duplication
+- Improve naming
+- Re-run tests after each change
+
+Done when: all tests pass, no test was modified to accommodate implementation, no production code exists without a covering test.

package/catalog/devcontainer/devcontainer.json

@@ -0,0 +1,24 @@
+{
+  "name": "AI-agentic dev container",
+  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-20-bullseye",
+  "features": {
+    "ghcr.io/devcontainers/features/git:1": {},
+    "ghcr.io/devcontainers/features/github-cli:1": {}
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "anthropic.claude-code"
+      ],
+      "settings": {
+        "terminal.integrated.defaultProfile.linux": "bash"
+      }
+    }
+  },
+  "forwardPorts": [],
+  "postCreateCommand": "npm install",
+  "remoteUser": "node",
+  "mounts": [
+    "source=${localEnv:HOME}/.ssh,target=/home/node/.ssh,type=bind,consistency=cached,readonly"
+  ]
+}

package/catalog/hooks/block-dangerous-bash.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Blocks destructive shell commands before they execute.
+# Fires on PreToolUse(Bash).
+
+set -euo pipefail
+
+INPUT="$(cat)"
+COMMAND="$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('command',''))" 2>/dev/null || echo "")"
+
+PATTERNS=(
+  "rm -rf /"
+  "rm -rf ~"
+  "rm -rf \*"
+  "dd if="
+  "mkfs"
+  ":(){:|:&};:"
+  "chmod -R 777"
+  "> /dev/sda"
+  "shred -"
+)
+
+for pattern in "${PATTERNS[@]}"; do
+  if echo "$COMMAND" | grep -qF "$pattern"; then
+    echo "BLOCKED: dangerous command pattern detected: $pattern" >&2
+    echo '{"decision":"block","reason":"Dangerous bash command blocked by haac-aikit safety hook"}'
+    exit 0
+  fi
+done
+
+echo '{"decision":"approve"}'

package/catalog/hooks/block-force-push-main.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Blocks force-push to protected branches.
+# Fires on PreToolUse(Bash).
+
+set -euo pipefail
+
+INPUT="$(cat)"
+COMMAND="$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('command',''))" 2>/dev/null || echo "")"
+
+PROTECTED_BRANCHES=("main" "master" "develop" "production" "staging")
+
+if echo "$COMMAND" | grep -qE "git push.*(--force|-f)"; then
+  for branch in "${PROTECTED_BRANCHES[@]}"; do
+    if echo "$COMMAND" | grep -qE "(^| )${branch}( |$)"; then
+      echo "BLOCKED: force-push to protected branch '$branch'" >&2
+      echo "{\"decision\":\"block\",\"reason\":\"Force-push to $branch is blocked by haac-aikit safety hook. Use a PR instead.\"}"
+      exit 0
+    fi
+  done
+fi
+
+echo '{"decision":"approve"}'

package/catalog/hooks/block-secrets-in-commits.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Blocks git commits when staged diff contains likely secrets.
+# Fires on PreToolUse(Bash) when the command contains 'git commit'.
+
+set -euo pipefail
+
+INPUT="$(cat)"
+COMMAND="$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('command',''))" 2>/dev/null || echo "")"
+
+if ! echo "$COMMAND" | grep -q "git commit"; then
+  echo '{"decision":"approve"}'
+  exit 0
+fi
+
+# Check staged diff for secret-like patterns
+DIFF="$(git diff --cached --unified=0 2>/dev/null || echo "")"
+
+SECRET_PATTERNS=(
+  "AKIA[0-9A-Z]{16}"              # AWS access key
+  "sk-[a-zA-Z0-9]{48}"            # OpenAI API key
+  "ghp_[a-zA-Z0-9]{36}"           # GitHub personal access token
+  "ghs_[a-zA-Z0-9]{36}"           # GitHub app token
+  "xoxb-[0-9A-Za-z-]+"            # Slack bot token
+  "password[[:space:]]*=[[:space:]]*['\"][^'\"]{8,}" # password = "..."
+  "secret[[:space:]]*=[[:space:]]*['\"][^'\"]{8,}"   # secret = "..."
+  "api_key[[:space:]]*=[[:space:]]*['\"][^'\"]{8,}"  # api_key = "..."
+)
+
+for pattern in "${SECRET_PATTERNS[@]}"; do
+  if echo "$DIFF" | grep -qP "^\+.*${pattern}" 2>/dev/null; then
+    echo "BLOCKED: potential secret detected in staged changes (pattern: $pattern)" >&2
+    echo "{\"decision\":\"block\",\"reason\":\"Potential secret in staged diff. Review with 'git diff --cached' before committing.\"}"
+    exit 0
+  fi
+done
+
+echo '{"decision":"approve"}'

package/catalog/hooks/compaction-preservation.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Writes a scratch file before compaction to preserve working state.
+# Fires on PreCompact.
+
+set -euo pipefail
+
+SCRATCH_FILE=".claude/pre-compact-state.md"
+mkdir -p .claude
+
+{
+  echo "# Pre-compaction state"
+  echo "## Timestamp: $(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  echo ""
+  echo "## Modified files"
+  git status --porcelain 2>/dev/null || echo "(not a git repo)"
+  echo ""
+  echo "## Recent commits"
+  git log --oneline -5 2>/dev/null || echo "(not a git repo)"
+  echo ""
+  echo "## Failing tests"
+  if [[ -f ".last-test-result" ]]; then
+    cat .last-test-result
+  else
+    echo "(no test result recorded)"
+  fi
+} > "$SCRATCH_FILE"
+
+echo "Pre-compact state saved to $SCRATCH_FILE"
+exit 0

package/catalog/hooks/file-guard.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Blocks reads and writes to sensitive files.
+# Fires on PreToolUse(Read|Edit|Write).
+
+set -euo pipefail
+
+INPUT="$(cat)"
+FILE_PATH="$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('file_path','') or d.get('path',''))" 2>/dev/null || echo "")"
+
+BLOCKED_PATTERNS=(
+  ".env"
+  "secrets/"
+  ".ssh/"
+  ".aws/"
+  "*.pem"
+  "id_rsa"
+  "id_ed25519"
+  ".netrc"
+  "credentials"
+)
+
+for pattern in "${BLOCKED_PATTERNS[@]}"; do
+  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
+    echo "BLOCKED: access to sensitive file: $FILE_PATH" >&2
+    echo "{\"decision\":\"block\",\"reason\":\"Access to sensitive file blocked: $pattern. Override in .claude/settings.local.json if needed.\"}"
+    exit 0
+  fi
+done
+
+echo '{"decision":"approve"}'