faberun 0.3.0

package/skills/init-agentkit/templates/docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,36 @@
+---
+type: ADR
+id: "0001"
+title: "Record architecture decisions"
+status: active
+date: {{DATE}}
+---
+
+## Context
+
+As {{PROJECT}} grows with multiple contributors and AI agents, decisions get
+scattered across chat history and commit messages, making it hard to know *why*
+the system looks the way it does.
+
+## Decision
+
+**Record every structural choice as an Architecture Decision Record in
+`docs/adr/`.** Each decision gets its own numbered, immutable file; a changed
+decision supersedes the prior ADR instead of editing it.
+
+## Options considered
+
+- **ADR folder with frontmatter** (chosen): versioned alongside the code it
+  explains, so a decision and its implementation move together; the frontmatter
+  is machine-readable, which lets agents filter by status; the index lives in
+  `README.md`.
+- **Only a learnings doc**: lightweight but mixes incidents with irreversible
+  architecture choices.
+- **Wiki / external docs**: fine for product, poor for version-controlled
+  coupling to code.
+
+## Consequences
+
+- New structural work adds or supersedes an ADR in the same PR.
+- `docs/ARCHITECTURE.md` summarizes current state; ADRs hold the history.
+- Agents read `docs/adr/` before large refactors (see `AGENTS.md`).

package/skills/init-agentkit/templates/docs/adr/0002-root-managed-ai-guidance.md

@@ -0,0 +1,37 @@
+---
+type: ADR
+id: "0002"
+title: "Root-managed AI guidance files"
+status: active
+date: {{DATE}}
+---
+
+## Context
+
+Multiple AI tools (Cursor, Claude Code, Gemini CLI) each expect their own
+instruction file at the repository root. Maintaining `CLAUDE.md`, `GEMINI.md`, and
+`CURSOR.md` as separate documents means every guardrail change has to land in each
+of them; in practice one gets updated and the rest drift, so different agents end
+up working under different rules in the same repo.
+
+## Decision
+
+**`AGENTS.md` at the repo root is the canonical AI + contributor guidance.
+Tool-specific files (`CLAUDE.md`, `GEMINI.md`, `CURSOR.md`, `AGENT.md`)
+are symlinks to `AGENTS.md`.** Update guidance in
+one place only.
+
+## Options considered
+
+- **AGENTS.md canonical + symlinks** (chosen): one source of truth, and drift is
+  impossible by construction rather than by discipline; `AGENTS.md` is the name
+  the ecosystem is converging on.
+- **CLAUDE.md only**: works for Claude; other tools miss shared guardrails.
+- **Separate full files per tool**: guaranteed drift.
+
+## Consequences
+
+- PRs that change workflow, checks, or guardrails edit `AGENTS.md` once.
+- Coding agents prefer links into `docs/` over inflating the root file.
+- A broken symlink on a platform without symlink support falls back to a regen
+  step (`init-agentkit --force`).

package/skills/init-agentkit/templates/docs/adr/0003-sentrux-structural-quality-gates.md

@@ -0,0 +1,49 @@
+---
+type: ADR
+id: "0003"
+title: "Sentrux structural quality gates"
+status: active
+date: {{DATE}}
+---
+
+## Context
+
+Type checks (`tsc`/equivalent) and tests catch type errors and behavior
+regressions, but they are **blind to structure**: rising coupling, import
+cycles, complexity hotspots, and files quietly turning into god objects. These
+are exactly what makes a small, healthy codebase slow and fragile a year later.
+
+[Sentrux](https://github.com/sentrux/sentrux) is a structural-quality sensor that
+scores the dependency/call graph and ratchets against regression. Adopting it now,
+while the repo is small, sets a clean baseline — retrofitting a gate onto an
+already-degraded codebase means either a baseline that locks in the damage or a
+backlog of refactors before the gate can go green.
+
+## Decision
+
+**Adopt Sentrux as a mandatory structural-quality gate**, in three parts:
+
+1. **`.sentrux/rules.toml`** — absolute hard limits (`check`).
+2. **`.sentrux/baseline.json`** — committed reference for regression detection (`gate`).
+3. **CI** — `sentrux check .` on every push/PR; `sentrux gate .` on PRs.
+
+The Boy Scout Rule applies: any file a change touches leaves with an
+equal-or-better structural score. Full reference: [../sentrux.md](../sentrux.md).
+
+## Options considered
+
+- **Sentrux with ratchet** (chosen): quantitative graph-level metrics; ships an
+  MCP server so AI agents optimize the same score; complements `tsc`/tests.
+- **Linter complexity rules only**: no project-wide coupling grade, no cycle
+  detection, no baseline ratchet.
+- **CodeScene**: richer but a hosted service, heavier than needed early.
+- **Manual review for structure**: does not scale, invisible to agents.
+
+## Consequences
+
+- Contributors run `sentrux gate --save .` before a refactor and
+  `sentrux check . && sentrux gate .` before committing.
+- CI failure on a Sentrux violation blocks merge.
+- Thresholds **only tighten**; loosening requires a superseding ADR. Never add
+  ignore rules to pass — fix the structure.
+- The committed baseline moves **up only**.

package/skills/init-agentkit/templates/docs/adr/README.md

@@ -0,0 +1,52 @@
+# Architecture Decision Records
+
+Architecture Decision Records (ADRs) for **{{PROJECT}}**.
+
+## Format
+
+Each ADR is markdown with YAML frontmatter:
+
+```markdown
+---
+type: ADR
+id: "0001"
+title: "Short decision title"
+status: proposed        # proposed | active | superseded | retired
+date: YYYY-MM-DD
+superseded_by: "0007"  # only if status: superseded
+---
+
+## Context
+...
+
+## Decision
+**What was decided.**
+
+## Options considered
+...
+
+## Consequences
+...
+```
+
+### Status lifecycle
+
+```
+proposed → active → superseded
+                 ↘ retired
+```
+
+## Rules
+
+- One decision per file.
+- Files named `NNNN-short-title.md` (monotonic numbering).
+- Once `active`, never edit — supersede instead.
+- [../ARCHITECTURE.md](../ARCHITECTURE.md) reflects active decisions only.
+
+## Index
+
+| ID | Title | Status |
+|----|-------|--------|
+| [0001](0001-record-architecture-decisions.md) | Record architecture decisions | active |
+| [0002](0002-root-managed-ai-guidance.md) | Root-managed AI guidance files | active |
+| [0003](0003-sentrux-structural-quality-gates.md) | Sentrux structural quality gates | active |

package/skills/init-agentkit/templates/docs/sentrux.md

@@ -0,0 +1,66 @@
+# Sentrux — structural quality gate
+
+[Sentrux](https://github.com/sentrux/sentrux) is the structural-quality sensor
+for this repo. It scores the dependency/call graph and **ratchets against
+regression**, complementing (not replacing) type checks and tests.
+
+## 1. Install
+
+```bash
+# macOS / Linux — pin the version to match CI (.github/workflows/quality.yml)
+SENTRUX_VERSION={{SENTRUX_VERSION}}
+mkdir -p "$HOME/.sentrux/bin"
+curl -fsSL "https://github.com/sentrux/sentrux/releases/download/${SENTRUX_VERSION}/sentrux-$(uname -s | tr A-Z a-z)-$(uname -m)" \
+  -o "$HOME/.sentrux/bin/sentrux" && chmod +x "$HOME/.sentrux/bin/sentrux"
+export PATH="$HOME/.sentrux/bin:$PATH"
+sentrux --version
+```
+
+## 2. What Sentrux measures
+
+- **Coupling grade** (A–F) over the import graph.
+- **Cycles** — import/dependency cycles (target: 0).
+- **God files** — files doing too much.
+- **Complexity** — per-function cyclomatic ceiling.
+- **Quality signal** — an aggregate score to optimize against.
+
+## 3. The two commands
+
+| Command | Enforces | Config |
+|---------|----------|--------|
+| `sentrux check .` | absolute hard limits | `.sentrux/rules.toml` |
+| `sentrux gate .` | no regression vs baseline | `.sentrux/baseline.json` |
+
+```bash
+sentrux check .           # exits 0 if rules pass, 1 if not
+sentrux gate --save .     # snapshot baseline (run before a refactor)
+sentrux gate .            # compare current vs baseline; fails on degradation
+```
+
+## 4. Our rules (`.sentrux/rules.toml`)
+
+Absolute ceilings. Tighten as the codebase grows — **never loosen without an ADR.**
+
+## 5. The baseline (`.sentrux/baseline.json`)
+
+Committed reference for `gate`. Move it **up only** — re-saving to mask a
+regression defeats the ratchet.
+
+## 6. Daily workflow
+
+```bash
+# 1. Before touching existing files, capture where you started:
+sentrux gate --save .
+# 2. Do the work…
+# 3. Before committing:
+sentrux check . && sentrux gate .
+```
+
+Boy Scout Rule: every file you touch leaves with an equal-or-better score.
+Never silence a rule to pass — fix the structure.
+
+## 7. CI integration
+
+`.github/workflows/quality.yml` installs the pinned Sentrux release, runs
+`sentrux check .` on every push, and `sentrux gate .` on PRs. A failing gate
+blocks merge.

package/skills/init-agentkit/templates/githooks/commit-msg

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# {{PROJECT}} commit-msg hook — enforce Conventional Commits.
+# Release tooling parses these; a wrong type breaks versioning. Don't bypass.
+set -euo pipefail
+
+msg_file="$1"
+subject="$(head -1 "$msg_file")"
+
+# allow merge/revert/fixup commits
+case "$subject" in
+  "Merge "*|"Revert "*|"fixup! "*|"squash! "*) exit 0 ;;
+esac
+
+# type(scope)!: description   — scope optional, ! optional
+pattern='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-z0-9_.-]+\))?!?: .+'
+if ! printf '%s' "$subject" | grep -qE "$pattern"; then
+  echo "✗ commit-msg: subject does not follow Conventional Commits."
+  echo "  got:      $subject"
+  echo "  expected: <type>(scope): description   (type ∈ feat|fix|docs|refactor|perf|test|build|ci|chore|revert)"
+  exit 1
+fi
+exit 0

package/skills/init-agentkit/templates/githooks/pre-commit

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# {{PROJECT}} pre-commit hook (installed via core.hooksPath).
+# Never bypass with --no-verify; fix the underlying issue instead.
+set -euo pipefail
+
+# Skip if nothing staged.
+git diff --cached --quiet && exit 0
+
+# --- secrets scan over the staged diff ---------------------------------------
+echo "▸ secrets scan"
+# exclude the hooks themselves (they contain the patterns as literals)
+DIFF="$(git diff --cached -U0 -- . ':(exclude)githooks/**')"
+PATTERNS='(AKIA[0-9A-Z]{16}|xox[baprs]-[0-9A-Za-z-]{10,}|gh[pousr]_[0-9A-Za-z]{20,}|-----BEGIN[ A-Z]*PRIVATE KEY-----|AIza[0-9A-Za-z_-]{30,}|"private_key":)'
+if printf '%s' "$DIFF" | grep -nEi "$PATTERNS" | grep -viE '(example|placeholder|dummy|fake|PATTERNS=)' | head -5 | grep -q .; then
+  echo "✗ possible secret in the staged diff — remove it before committing (use a gitignored .env)"; exit 1
+fi
+if git diff --cached --name-only | grep -E '(^|/)\.env($|\.)' | grep -vqE '\.env\.example'; then
+  echo "✗ .env file staged — do not commit secrets"; exit 1
+fi
+
+if [ -f .sentrux/rules.toml ] && command -v sentrux >/dev/null 2>&1; then
+  echo "▸ sentrux check"
+  sentrux check . || { echo "✗ sentrux check failed — fix structure before committing"; exit 1; }
+  if [ -f .sentrux/baseline.json ] && ! grep -q 'placeholder' .sentrux/baseline.json 2>/dev/null; then
+    echo "▸ sentrux gate"
+    sentrux gate . || { echo "✗ sentrux gate: structural regression on touched files"; exit 1; }
+  fi
+elif [ -f .sentrux/rules.toml ]; then
+  echo "⚠ sentrux not installed — skipping structural gate (see docs/sentrux.md)"
+fi
+
+exit 0