haac-aikit 0.1.0

package/catalog/hooks/format-on-save.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Auto-formats files after Edit/Write.
+# Fires on PostToolUse(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 "")"
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+EXT="${FILE_PATH##*.}"
+
+case "$EXT" in
+  ts|tsx|js|jsx|mjs|cjs)
+    if command -v biome &>/dev/null; then
+      biome format --write "$FILE_PATH" 2>/dev/null || true
+    elif command -v prettier &>/dev/null; then
+      prettier --write "$FILE_PATH" 2>/dev/null || true
+    fi
+    ;;
+  py)
+    if command -v black &>/dev/null; then
+      black "$FILE_PATH" 2>/dev/null || true
+    elif command -v ruff &>/dev/null; then
+      ruff format "$FILE_PATH" 2>/dev/null || true
+    fi
+    ;;
+  go)
+    if command -v gofmt &>/dev/null; then
+      gofmt -w "$FILE_PATH" 2>/dev/null || true
+    fi
+    ;;
+  rs)
+    if command -v rustfmt &>/dev/null; then
+      rustfmt "$FILE_PATH" 2>/dev/null || true
+    fi
+    ;;
+esac
+
+exit 0

package/catalog/hooks/hooks.json

@@ -0,0 +1,70 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/block-dangerous-bash.sh",
+            "description": "Block destructive shell commands"
+          },
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/block-force-push-main.sh",
+            "description": "Block force-push to protected branches"
+          },
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/block-secrets-in-commits.sh",
+            "description": "Block commits containing likely secrets"
+          }
+        ]
+      },
+      {
+        "matcher": "Read|Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/file-guard.sh",
+            "description": "Block access to sensitive files"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/format-on-save.sh",
+            "description": "Auto-format after file write"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/session-start-prime.sh",
+            "description": "Print session context (branch, dirty state, TODOs)"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/compaction-preservation.sh",
+            "description": "Save working state before context compaction"
+          }
+        ]
+      }
+    ]
+  }
+}

package/catalog/hooks/session-start-prime.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Prints useful context at session start.
+# Fires on SessionStart.
+
+set -euo pipefail
+
+echo "=== Session context ==="
+
+# Current branch
+BRANCH="$(git branch --show-current 2>/dev/null || echo 'not in a git repo')"
+echo "Branch: $BRANCH"
+
+# Uncommitted changes
+DIRTY="$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')"
+if [[ "$DIRTY" -gt 0 ]]; then
+  echo "Uncommitted changes: $DIRTY file(s)"
+fi
+
+# Recent failing tests (Jest/Vitest)
+if [[ -f ".last-test-result" ]]; then
+  echo "Last test run: $(cat .last-test-result)"
+fi
+
+# TODO count
+TODO_COUNT="$(grep -r 'TODO\|FIXME\|HACK' --include='*.ts' --include='*.js' --include='*.py' . 2>/dev/null | wc -l | tr -d ' ')"
+if [[ "$TODO_COUNT" -gt 0 ]]; then
+  echo "TODOs in codebase: $TODO_COUNT"
+fi
+
+echo "======================"
+exit 0

package/catalog/husky/commit-msg

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx --no -- commitlint --edit "$1"

package/catalog/husky/commitlint.config.js

@@ -0,0 +1,8 @@
+/** @type {import('@commitlint/types').UserConfig} */
+export default {
+  extends: ["@commitlint/config-conventional"],
+  rules: {
+    "subject-max-length": [2, "always", 72],
+    "body-max-line-length": [1, "always", 100],
+  },
+};

package/catalog/husky/gitleaks.toml

@@ -0,0 +1,10 @@
+[extend]
+useDefault = true
+
+[allowlist]
+description = "Project-specific allowlist"
+regexes = []
+paths = [
+  ".gitleaks.toml",
+  "ATTRIBUTIONS.md",
+]

package/catalog/husky/lintstagedrc.json

@@ -0,0 +1,5 @@
+{
+  "*.{ts,tsx,js,jsx,mjs}": ["eslint --fix", "prettier --write"],
+  "*.{json,md,yaml,yml}": ["prettier --write"],
+  "*.py": ["ruff format", "ruff check --fix"]
+}

package/catalog/husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx lint-staged

package/catalog/husky/pre-push

@@ -0,0 +1,18 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+# Block force-push to protected branches
+REMOTE="$1"
+URL="$2"
+
+while read local_ref local_sha remote_ref remote_sha; do
+  BRANCH="${remote_ref#refs/heads/}"
+  case "$BRANCH" in
+    main|master|develop|production|staging)
+      if git rev-parse --abbrev-ref HEAD | grep -q "^$BRANCH$"; then
+        echo "Error: direct push to '$BRANCH' is not allowed. Open a PR instead."
+        exit 1
+      fi
+      ;;
+  esac
+done

package/catalog/mcp/mcp.json

@@ -0,0 +1,19 @@
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
+      "env": {}
+    },
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"],
+      "env": {}
+    },
+    "fetch": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-fetch"],
+      "env": {}
+    }
+  }
+}

package/catalog/plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "{{projectName}}-aikit",
+  "version": "1.0.0",
+  "description": "AI-agentic-coding setup for {{projectName}}",
+  "vendor": "haac-aikit",
+  "skills": ".claude/skills",
+  "agents": ".claude/agents",
+  "commands": ".claude/commands",
+  "hooks": ".claude/hooks/hooks.json"
+}

package/catalog/rules/AGENTS.md.tmpl

@@ -0,0 +1,46 @@
+# {{projectName}}
+
+<!-- BEGIN:haac-aikit -->
+{{description}}
+
+## Setup
+TODO: Install dependencies (e.g., `npm install` / `pnpm install`)
+
+## Commands
+- Build: TODO
+- Dev:   TODO
+- Test:  TODO
+- Lint:  TODO
+
+## Code style
+TODO: Rules not enforceable by linter (naming patterns, file-organisation conventions, etc.)
+
+## Project layout
+TODO: 3-5 bullets on where things live.
+<!-- E.g.:
+- src/        Application source
+- src/lib/    Business logic (no UI imports)
+- test/       Co-located unit tests
+-->
+
+## Testing
+TODO: How to run a single test; framework quirks.
+
+## Commit & PR conventions
+- Conventional commits: `type(scope): description`
+- Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`
+- PR title < 70 characters; body: Summary + Test Plan.
+- Never force-push to `main`/`master`/`develop`.
+
+## Security
+Never read, write, or commit:
+- `.env*`, `secrets/`, `.ssh/`, `.aws/`, `*.pem`, `id_rsa*`
+
+Never force-push to `main`/`master`/`develop`.
+
+TODO: Project-specific security notes.
+
+## Gotchas
+<!-- High-signal section. Add things the agent repeatedly gets wrong. -->
+TODO
+<!-- END:haac-aikit -->

package/catalog/rules/CLAUDE.md.shim

@@ -0,0 +1,5 @@
+@AGENTS.md
+
+<!-- BEGIN:haac-aikit -->
+<!-- Claude Code overrides — add Claude-specific rules below this line -->
+<!-- END:haac-aikit -->

package/catalog/rules/GEMINI.md.shim

@@ -0,0 +1,5 @@
+@AGENTS.md
+
+<!-- BEGIN:haac-aikit -->
+<!-- Gemini CLI overrides — add Gemini-specific rules below this line -->
+<!-- END:haac-aikit -->

package/catalog/rules/aider-conventions.md

@@ -0,0 +1,5 @@
+# Conventions
+
+<!-- BEGIN:haac-aikit -->
+See AGENTS.md for the full project context, code style, commit conventions, and security rules.
+<!-- END:haac-aikit -->

package/catalog/rules/aider.conf.yml

@@ -0,0 +1,5 @@
+# BEGIN:haac-aikit
+read:
+  - AGENTS.md
+  - CONVENTIONS.md
+# END:haac-aikit

package/catalog/rules/copilot-instructions.md

@@ -0,0 +1,6 @@
+<!-- See AGENTS.md in the repository root for the full project context. -->
+<!-- BEGIN:haac-aikit -->
+@../AGENTS.md
+
+<!-- Copilot-specific overrides below -->
+<!-- END:haac-aikit -->

package/catalog/rules/cursor-base.mdc

@@ -0,0 +1,13 @@
+---
+description: Base project rules — see AGENTS.md for full context
+alwaysApply: true
+---
+
+<!-- BEGIN:haac-aikit -->
+See [AGENTS.md](../AGENTS.md) for the authoritative project rules.
+
+Key constraints:
+- Follow commit conventions from AGENTS.md
+- Never commit .env* or secrets/**
+- Never force-push to main/master/develop
+<!-- END:haac-aikit -->

package/catalog/rules/windsurf-rules.md

@@ -0,0 +1,7 @@
+---
+trigger: always_on
+---
+
+<!-- BEGIN:haac-aikit -->
+See AGENTS.md in the repository root for the full project context and rules.
+<!-- END:haac-aikit -->

package/catalog/settings/env.example

@@ -0,0 +1,7 @@
+# OTel telemetry (optional — remove this file if you don't want telemetry)
+# CLAUDE_CODE_ENABLE_TELEMETRY=1
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+# OTEL_SERVICE_NAME=my-project
+
+# API keys (never commit real values — use secrets management)
+# ANTHROPIC_API_KEY=

package/catalog/settings/settings.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(npm run *)",
+      "Bash(pnpm run *)",
+      "Bash(yarn run *)",
+      "Bash(bun run *)",
+      "Bash(git status)",
+      "Bash(git diff*)",
+      "Bash(git log*)",
+      "Bash(git branch*)",
+      "Read(./**)",
+      "Grep",
+      "Glob"
+    ],
+    "deny": [
+      "Read(./.env*)",
+      "Read(./secrets/**)",
+      "Read(./.ssh/**)",
+      "Read(./.aws/**)",
+      "Write(./.env*)",
+      "Bash(rm -rf /)",
+      "Bash(rm -rf ~)",
+      "Bash(rm -rf *)",
+      "Bash(sudo *)",
+      "Bash(curl * | bash)",
+      "Bash(wget * | bash)",
+      "Bash(dd if=*)",
+      "Bash(mkfs*)",
+      "Bash(chmod -R 777 *)"
+    ],
+    "ask": [
+      "Bash(git push *)",
+      "Bash(gh pr create*)",
+      "Bash(gh pr merge*)",
+      "Bash(npm publish*)",
+      "Bash(docker push*)"
+    ]
+  },
+  "enableAllProjectMcpServers": false,
+  "enabledMcpjsonServers": ["filesystem", "memory", "fetch"],
+  "includeCoAuthoredBy": true,
+  "cleanupPeriodDays": 30
+}

package/catalog/skills/tier1/brainstorming.md

@@ -0,0 +1,39 @@
+---
+name: brainstorming
+description: Use when a request is ambiguous, has multiple valid approaches, or involves a product/design decision. Clarifies requirements before writing any code or making irreversible changes. Prevents wasted implementation work caused by misunderstood intent.
+version: "1.0.0"
+source: obra/superpowers
+license: MIT
+---
+
+## When to use
+- Request is vague ("make this better", "add auth", "refactor this")
+- Multiple valid implementation approaches exist
+- The task involves a non-trivial architectural decision
+- You're unsure which of several files to modify
+
+## Process
+
+1. **State what you understand** — describe the goal in your own words (2-3 sentences).
+
+2. **Surface your assumptions** — list them explicitly:
+   ```
+   ASSUMPTIONS:
+   1. [assumption]
+   2. [assumption]
+   → Correct me now or I'll proceed with these.
+   ```
+
+3. **Identify the key decision** — the one choice that, if wrong, invalidates all following work. Name it.
+
+4. **Present 2-3 concrete approaches** (not more) — for each: one sentence on what it does, one on the main tradeoff. No implementation yet.
+
+5. **Make a recommendation** — state which you'd pick and why. Then stop. Let the human choose.
+
+6. **Confirm before implementing** — do not proceed until the human explicitly approves an approach.
+
+## Anti-patterns to avoid
+- Asking 5+ questions in sequence instead of synthesising a recommendation
+- Starting implementation before requirements are clear
+- Treating "do X" as unambiguous when X has multiple valid interpretations
+- Presenting approaches without tradeoffs (forces the human to do the analysis)

package/catalog/skills/tier1/codebase-exploration.md

@@ -0,0 +1,55 @@
+---
+name: codebase-exploration
+description: Use when starting work in an unfamiliar codebase or module, before editing any code, or when asked to understand how something works. Read-only reconnaissance before any editing prevents breaking changes caused by misunderstood dependencies.
+version: "1.0.0"
+source: haac-aikit
+license: MIT
+---
+
+## When to use
+- First session in a codebase
+- Moving into a module you haven't touched before
+- Before refactoring code you didn't write
+- When the human asks "how does X work?"
+
+## Exploration sequence
+
+### 1. Orient (2-3 minutes max)
+```bash
+ls -la                          # top-level structure
+cat package.json | head -30     # or Cargo.toml / go.mod / pyproject.toml
+git log --oneline -10           # recent activity
+git diff main...HEAD --stat     # if on a feature branch
+```
+
+### 2. Find the entry points
+- Web: `src/index.ts`, `app/layout.tsx`, `main.go`, `__main__.py`
+- CLI: look for the `bin` field in package.json, or `cmd/` directory
+- Library: `src/index.ts` exports
+
+### 3. Trace the critical path
+For the specific feature you need to touch:
+1. Identify the triggering event (HTTP request, CLI invocation, UI interaction)
+2. Follow the call chain: find the handler → service → data layer
+3. Note each boundary: where does I/O happen? Where does auth happen?
+
+### 4. Map dependencies
+- What does the module you're editing import?
+- What imports the module you're editing?
+- Are there hidden consumers (dynamic imports, reflection, DI containers)?
+
+### 5. Read tests before source
+Tests reveal intent. Read the test file for the module first — it shows expected behaviour without having to infer it from implementation.
+
+## Output format
+```
+Understanding:
+- Entry: [file:line]
+- Critical path: [A → B → C → D]
+- Key dependencies: [list]
+- Gotchas noticed: [anything surprising]
+→ Ready to proceed / Need to clarify: [question]
+```
+
+## Constraint
+No file edits during exploration. If you discover something that needs fixing while exploring, note it but do not fix it yet — complete the exploration first.

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

@@ -0,0 +1,34 @@
+---
+name: executing-plans
+description: Use when executing an approved implementation plan. Ensures each step is verified before moving to the next, surfaces blockers early, and prevents compounding errors from unverified intermediate states.
+version: "1.0.0"
+source: obra/superpowers
+license: MIT
+---
+
+## When to use
+- After a plan has been written and approved
+- When the human says "execute", "go ahead", or "implement it"
+- When running steps from a plan file
+
+## Execution protocol
+
+1. **Read the full plan** before starting. Identify which steps are sequential vs. parallelisable.
+
+2. **Execute one step at a time** — do not batch multiple steps unless they are explicitly parallel.
+
+3. **Verify after each step**:
+   - File changes: confirm the diff matches intent
+   - Code changes: run the relevant test / typecheck
+   - State changes: check the state (e.g. `git status`, output of a command)
+
+4. **Report progress**: after each step, one line: `Step N done: [what changed]`.
+
+5. **Pause on blocking issues**: if a step fails or reveals new information that invalidates subsequent steps, STOP. Report the situation and revised options. Do not barrel through.
+
+6. **Final verification**: after the last step, run the full test suite and report: pass/fail count and any regressions.
+
+## Do not
+- Skip verification to save time — unverified steps compound
+- Silently adapt from the approved plan — if the plan needs to change, say so
+- Continue past a failed step without explicit human direction

package/catalog/skills/tier1/requesting-code-review.md

@@ -0,0 +1,37 @@
+---
+name: requesting-code-review
+description: Use when implementation is complete and ready for review. Dispatches a code-reviewer subagent with precise context about what changed, what was intentional, and what to focus on. Produces actionable review feedback rather than generic observations.
+version: "1.0.0"
+source: obra/superpowers
+license: MIT
+---
+
+## When to use
+- After completing a feature, fix, or refactor
+- Before creating a PR
+- When the human says "review this"
+
+## Review request format
+
+```
+Dispatching code-reviewer with context:
+- Files changed: [list]
+- What the change does: [1-2 sentences]
+- Intentional tradeoffs: [list things reviewer might question but were deliberate]
+- Focus areas: [specific concerns, or "general review"]
+- Constraints: [test coverage requirement, performance budget, etc.]
+```
+
+## What to provide to the reviewer
+
+1. **The diff** — `git diff main...HEAD` or the specific files
+2. **The context** — why this change was made (not what it does — the diff shows that)
+3. **Exclusions** — "ignore the formatting changes in X; those are auto-generated"
+4. **Decision log** — "I chose approach A over B because..."
+
+## What to do with review output
+
+- For each finding: acknowledge, then either fix + confirm fix, or explain why it's intentional
+- Do not mark a finding as resolved without making the change
+- Do not argue with findings — if you disagree, say so once and defer to the human's judgment
+- Implement all agreed-upon changes before claiming review is addressed

package/catalog/skills/tier1/systematic-debugging.md

@@ -0,0 +1,50 @@
+---
+name: systematic-debugging
+description: Use when investigating a bug, unexpected behaviour, test failure, or error message. Prevents shotgun debugging — random code changes hoping something fixes it. Uses hypothesis-driven root cause investigation to find the actual problem before touching code.
+version: "1.0.0"
+source: obra/superpowers
+license: MIT
+---
+
+## When to use
+- A test is failing and you don't know why
+- An error is thrown at runtime
+- Behaviour is incorrect but no error is visible
+- A previous fix attempt made things worse
+
+## Protocol
+
+### 1. Reproduce first
+Before any code change, confirm you can reproduce the problem. If you can't reliably reproduce it, you can't verify a fix.
+
+### 2. Form hypotheses (before reading code)
+Write down 2-3 hypotheses:
+```
+HYPOTHESES:
+H1: [cause] → evidence needed to confirm/refute: [specific thing to check]
+H2: [cause] → evidence needed to confirm/refute: [specific thing to check]
+H3: [cause] → evidence needed to confirm/refute: [specific thing to check]
+```
+
+### 3. Test each hypothesis cheaply
+Order by ease of testing. For each:
+- Add a temporary log / assertion (not a permanent change)
+- Run the test / trigger the behaviour
+- Record: confirmed / refuted
+
+### 4. Narrow to root cause
+A root cause explains all symptoms. Keep eliminating hypotheses until one remains. If no hypothesis explains the full picture, generate new ones.
+
+### 5. Fix only the root cause
+Write the minimal change that addresses the root cause. Do not "clean up" adjacent code unless directly related. Do not fix symptoms while the root cause remains.
+
+### 6. Verify the fix
+- The original reproduction no longer triggers the problem
+- All existing tests pass
+- Write a regression test that would have caught this bug originally
+
+## Anti-patterns
+- Changing code without a hypothesis
+- "Trying things" sequentially until something works
+- Fixing the symptom (swallowing an exception) rather than the cause
+- Not writing a regression test — the bug will return

package/catalog/skills/tier1/test-driven-development.md

@@ -0,0 +1,44 @@
+---
+name: test-driven-development
+description: Use when implementing new behaviour, fixing a confirmed bug, or when the human asks for TDD. Enforces the red-green-refactor loop to ensure every behaviour is tested before implementation, preventing untested code from entering the codebase.
+version: "1.0.0"
+source: obra/superpowers
+license: MIT
+---
+
+## When to use
+- Any new function, method, or module
+- Bug fixes (write the failing regression test first)
+- When "add tests" would be harder after implementation
+
+## The loop
+
+```
+RED   → Write a failing test that describes the exact behaviour needed
+GREEN → Write the minimal implementation to make the test pass
+CHECK → Run the test; confirm it passes and only it (no new breakage)
+REFACTOR → Clean up without changing behaviour; re-run tests after each change
+```
+
+## RED — writing a good failing test
+
+- Name it: `it('should [verb] [noun] when [condition]', ...)`
+- Assert on the observable output, not the internal implementation
+- One behaviour per test — if you're using "and" in the name, split it
+- Run it: confirm it fails for the right reason (not a compile error or import failure)
+
+## GREEN — minimal implementation
+
+- Write only enough code to pass the test — no extra features
+- It's OK if the code is ugly; refactor comes next
+- Do not modify the test to make it pass
+
+## REFACTOR
+
+- Remove duplication
+- Improve naming
+- Extract helpers only when the abstraction is obvious
+- Each refactor step: change → run tests → if green, continue; if red, revert
+
+## Definition of done
+All tests pass. No test has been modified to accommodate implementation. No production code exists without a covering test.