faberun 0.3.0

package/skills/faberun/references/workflow.md

@@ -0,0 +1,23 @@
+# Workflow: worktrees, commits, scope
+
+**Detach and resume.** `run --detach <contract.json>` forks a controller that
+outlives this session; if it dies before the run is terminal, the next
+`resume --detach <run-dir>` takes over its stale lock and adopts or restarts
+whatever it left running. `maxParallel` above one dispatches every ready node
+concurrently, each in its own attempt worktree; integration stays serialized.
+The target repo must ignore `.runs/`.
+
+**Resume, do not restart.** A node marked `running` with no runner process is
+an orphan. `resume --detach <run-dir>` re-judges finished work instead of
+re-implementing it; take a new run id only when routing or the graph changes.
+
+Never overwrite an existing run directory; choose a new run id. One controller
+lock per run directory. Treat `STATUS.md` and node JSON as state; logs are
+diagnostics. Attempt worktrees, sealing commits, integration, and the lock
+mechanics: [operations.md](operations.md).
+
+**Name things for what they do.** A campaign, run, phase or node id says
+what the work is (`become-faberun-2-cli-product`, `brand-and-banner`), never
+only when it ran; a date is a tie-break suffix, not the meaning. An operator
+reading `.runs/`, a branch list or a `HANDOFF.md` must understand the campaign
+without opening it.

package/skills/init-agentkit/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: init-agentkit
+description: Installs the docs + agent kit into a repository - canonical AGENTS.md with CLAUDE.md/GEMINI.md/CURSOR.md symlinks, docs/ (VISION, ARCHITECTURE, ABSTRACTIONS, GETTING-STARTED), ADRs with template and index, Sentrux structural quality gate (.sentrux/rules.toml + baseline), CI, a create-adr slash command, and githooks. Use when the user says "install the agent kit", "init-agentkit", "set up docs/ADR/sentrux", or wants to bootstrap engineering standards in a new repo.
+---
+
+# init-agentkit
+
+Bootstraps the **docs + agent kit** in a repository. Structural gate by
+[Sentrux](https://github.com/sentrux/sentrux). The playbook consolidates what is in
+use in [phai](https://github.com/feliperun/phai) and
+[cueme](https://github.com/feliperun/cueme).
+
+## What it installs
+
+| Artifact | Role |
+|----------|------|
+| `AGENTS.md` | Canonical playbook (minimum-code rules, repository rules, workflow, gates, gotchas) |
+| `CLAUDE.md` `GEMINI.md` `CURSOR.md` `AGENT.md` | **symlinks** → `AGENTS.md` (single source) |
+| `docs/VISION.md` `ARCHITECTURE.md` `ABSTRACTIONS.md` `GETTING-STARTED.md` | base docs |
+| `docs/adr/` | ADRs with `README.md` (template + index + status lifecycle) |
+| `docs/adr/0001..0003` | meta-ADRs documenting the kit itself |
+| `docs/sentrux.md` | structural quality gate reference |
+| `.sentrux/rules.toml` | absolute limits (`sentrux check`) |
+| `.sentrux/baseline.json` | anti-regression reference (`sentrux gate`) |
+| `.claude/commands/create-adr.md` | slash command that creates a numbered ADR and updates the index |
+| `.github/workflows/quality.yml` | CI: typecheck + test + sentrux |
+| `githooks/pre-commit` | local hook: secrets scan + sentrux check/gate |
+| `githooks/commit-msg` | validates Conventional Commits |
+
+## Before running: ask which compatibility rule applies
+
+Rule 1 of the generated `AGENTS.md` ships in two variants, and the choice changes how
+every future agent treats published contracts. **Always ask the user before running
+the installer** — do not pick a default silently:
+
+| Variant | Rule 1 | Fits |
+|---------|--------|------|
+| `--greenfield` (default) | *Do not preserve backward compatibility.* Obsolete paths are removed, not wrapped in compatibility layers. | New projects with no published consumers. Keeps a greenfield codebase free of dead weight. |
+| `--stable` | Published surfaces (public API, CLI contract, persisted format, integrations) stay compatible; breaking one needs a migration path and a `feat!:` / `BREAKING CHANGE:` commit. Unpublished internals are still removed freely. | Anything with real consumers, a released package, or production data. |
+
+Ask with a two-option question ("greenfield: break freely" vs. "stable: preserve
+published contracts"), then pass the matching flag. The installer prints the selected
+variant before writing.
+
+## Usage
+
+```bash
+# from the target repo directory (or pass the path):
+~/.agents/skills/init-agentkit/scripts/install-agentkit.sh [target-dir]
+
+# compatibility rule (ask the user first — see above):
+install-agentkit.sh --greenfield     # break freely (default)
+install-agentkit.sh --stable         # preserve published contracts
+
+# preview without writing:
+install-agentkit.sh --dry-run
+
+# overwrite existing files (default: never overwrites, only warns):
+install-agentkit.sh --force
+
+# skip git hook installation:
+install-agentkit.sh --no-hooks
+```
+
+The installer:
+
+1. Detects the **project name** (repo basename) and the **stack**
+   (`package.json`→node, `Cargo.toml`→rust, `pyproject.toml`→python) to fill in
+   the check commands in `AGENTS.md` and CI, and resolves rule 1 from the selected
+   variant.
+2. Copies the templates **without overwriting** existing files (use `--force`).
+3. Creates the `CLAUDE.md`/`GEMINI.md`/`CURSOR.md`/`AGENT.md` symlinks → `AGENTS.md`.
+4. If the `sentrux` CLI is installed, runs `sentrux gate --save .` to generate the
+   real `baseline.json`; otherwise leaves a placeholder with instructions.
+5. Installs the hooks via `core.hooksPath` (never touches `.git/hooks` directly).
+6. Is **idempotent** — running it again only fills in what is missing.
+
+## After installing
+
+1. Fill in the `TODO`s in `docs/VISION.md` and `docs/ARCHITECTURE.md` (the rest is
+   generic structure that fits any repo).
+2. Install the Sentrux CLI and run `sentrux gate --save .` if no baseline was
+   generated yet (see `docs/sentrux.md`).
+3. Fill in the **gotchas** section of `AGENTS.md` as failures surface — it is the
+   highest-value part of the file.
+4. Commit everything as a single `chore: bootstrap agent kit (init-agentkit)`.
+5. Enable the gate in CI (the workflow ships ready; adjust the Sentrux version).
+
+## Conventions
+
+- **`AGENTS.md` is the single source** of guidance; never edit the symlinks.
+- **ADRs are immutable**: one decision per file, `NNNN-title.md`, monotonic
+  numbering; an active ADR is never edited — supersede it.
+- **Sentrux is a ratchet**: thresholds only tighten; loosening requires a
+  superseding ADR. Boy Scout Rule — every file you touch leaves with an
+  equal-or-better score.
+- **E2E is mandatory** for key features or user-visible changes; unit tests do not
+  replace it.
+- **Never `--no-verify`**; never silence a rule to pass the gate.
+- **Destructive actions** (merge, force-push, schema drop) require explicit human
+  sign-off in the moment — the agent hands off to the user instead of routing
+  around it.
+
+## References
+
+- Gate: [Sentrux](https://github.com/sentrux/sentrux)
+- Applied in: [phai](https://github.com/feliperun/phai),
+  [cueme](https://github.com/feliperun/cueme)

package/skills/init-agentkit/scripts/install-agentkit.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+#
+# init-agentkit — installs the docs + agent kit into a repo.
+#
+# Usage:
+#   install-agentkit.sh [target-dir]     # default: cwd
+#   install-agentkit.sh --dry-run        # preview without writing
+#   install-agentkit.sh --force          # overwrite existing files
+#   install-agentkit.sh --no-hooks       # skip git hook installation
+#   install-agentkit.sh --stable         # compatibility-preserving rule 1
+#   install-agentkit.sh --greenfield     # break-freely rule 1 (default)
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEMPLATES="$SCRIPT_DIR/../templates"
+SENTRUX_VERSION_DEFAULT="v0.5.7"
+
+DRY_RUN=0; FORCE=0; NO_HOOKS=0; TARGET=""; VARIANT="greenfield"
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=1 ;;
+    --force)   FORCE=1 ;;
+    --no-hooks) NO_HOOKS=1 ;;
+    --stable)     VARIANT="stable" ;;
+    --greenfield) VARIANT="greenfield" ;;
+    -*) echo "unknown flag: $arg" >&2; exit 2 ;;
+    *) TARGET="$arg" ;;
+  esac
+done
+TARGET="${TARGET:-$(pwd)}"
+TARGET="$(cd "$TARGET" && pwd)"
+
+# colors
+G='\033[32m'; Y='\033[33m'; B='\033[34m'; R='\033[31m'; D='\033[2m'; C='\033[36m'; Z='\033[0m'
+say(){ printf "%b\n" "${2:-}$1$Z"; }
+
+[ -d "$TEMPLATES" ] || { say "templates not found: $TEMPLATES" "$R"; exit 1; }
+
+# --- repo context --------------------------------------------------------
+PROJECT="$(basename "$(git -C "$TARGET" rev-parse --show-toplevel 2>/dev/null || echo "$TARGET")")"
+DATE="$(date +%F)"
+SENTRUX_VERSION="${SENTRUX_VERSION:-$SENTRUX_VERSION_DEFAULT}"
+
+# stack → check suite
+if   [ -f "$TARGET/package.json" ]; then CHECK_SUITE="npm run typecheck && npm test"
+elif [ -f "$TARGET/Cargo.toml" ];   then CHECK_SUITE="cargo check && cargo test"
+elif [ -f "$TARGET/pyproject.toml" ];then CHECK_SUITE="ruff check . && pytest"
+else CHECK_SUITE="echo 'TODO: define the check suite (typecheck + test)'"; fi
+
+say "\n🏗  init-agentkit → $PROJECT${DRY_RUN:+}" "$C"
+say "   target: $TARGET" "$D"
+say "   stack check: $CHECK_SUITE" "$D"
+say "   compatibility rule: $VARIANT" "$D"
+say "   sentrux: $SENTRUX_VERSION$( [ $DRY_RUN = 1 ] && echo '  (dry-run)')\n" "$D"
+
+# escape & and \ for the sed replacement side
+esc(){ printf '%s' "$1" | sed -e 's/[&\\]/\\&/g'; }
+# drop the unselected <!-- variant:NAME:start/end --> block, then the surviving markers
+DROP="$( [ "$VARIANT" = stable ] && echo greenfield || echo stable )"
+variant(){ sed -e "/<!-- variant:$DROP:start -->/,/<!-- variant:$DROP:end -->/d" \
+               -e "/<!-- variant:$VARIANT:start -->/d" \
+               -e "/<!-- variant:$VARIANT:end -->/d"; }
+subst(){ sed -e "s|{{PROJECT}}|$(esc "$PROJECT")|g" -e "s|{{DATE}}|$(esc "$DATE")|g" \
+             -e "s|{{SENTRUX_VERSION}}|$(esc "$SENTRUX_VERSION")|g" \
+             -e "s|{{CHECK_SUITE}}|$(esc "$CHECK_SUITE")|g" | variant; }
+
+# --- copy templates (never overwriting, unless --force) -----------------------
+copied=0; skipped=0
+while IFS= read -r src; do
+  rel="${src#"$TEMPLATES"/}"
+  dest="$TARGET/$rel"
+  if [ -e "$dest" ] && [ "$FORCE" = 0 ]; then
+    say "  = $rel (exists, kept)" "$D"; skipped=$((skipped+1)); continue
+  fi
+  if [ "$DRY_RUN" = 1 ]; then
+    say "  + $rel" "$G"; copied=$((copied+1)); continue
+  fi
+  mkdir -p "$(dirname "$dest")"
+  subst < "$src" > "$dest"
+  say "  + $rel" "$G"; copied=$((copied+1))
+done < <(find "$TEMPLATES" -type f)
+
+# --- guidance symlinks → AGENTS.md --------------------------------------------
+say "\n② Guidance symlinks → AGENTS.md" "$B"
+for f in CLAUDE.md GEMINI.md CURSOR.md AGENT.md; do
+  link="$TARGET/$f"
+  # relative target: one ../ per directory level below the repo root
+  case "$f" in */*) dest="../AGENTS.md" ;; *) dest="AGENTS.md" ;; esac
+  if [ -L "$link" ] && [ "$(readlink "$link")" = "$dest" ]; then
+    say "  = $f (ok)" "$D"; continue
+  fi
+  if [ -e "$link" ] && [ ! -L "$link" ] && [ "$FORCE" = 0 ]; then
+    say "  ! $f exists (real file) — use --force to replace it with a symlink" "$Y"; continue
+  fi
+  if [ "$DRY_RUN" = 0 ]; then
+    mkdir -p "$(dirname "$link")"
+    ( cd "$(dirname "$link")" && rm -f "$(basename "$f")" && ln -s "$dest" "$(basename "$f")" )
+  fi
+  say "  + $f → $dest" "$G"
+done
+
+# --- git hook via core.hooksPath --------------------------------------------
+if [ "$NO_HOOKS" = 0 ] && git -C "$TARGET" rev-parse --git-dir >/dev/null 2>&1; then
+  say "\n③ Git hook (core.hooksPath=githooks)" "$B"
+  if [ "$DRY_RUN" = 0 ]; then
+    chmod +x "$TARGET"/githooks/* 2>/dev/null || true
+    git -C "$TARGET" config core.hooksPath githooks
+  fi
+  say "  + pre-commit (secrets + sentrux) and commit-msg (Conventional Commits) active" "$G"
+fi
+
+# --- sentrux baseline -----------------------------------------------------
+say "\n④ Sentrux baseline" "$B"
+if command -v sentrux >/dev/null 2>&1; then
+  if [ "$DRY_RUN" = 0 ]; then
+    ( cd "$TARGET" && sentrux gate --save . ) && say "  + baseline.json generated" "$G" \
+      || say "  ! sentrux gate --save failed — generate it manually" "$Y"
+  else say "  + would run: sentrux gate --save ." "$G"; fi
+else
+  say "  ! sentrux CLI missing — baseline.json is a placeholder; install it and run 'sentrux gate --save .' (docs/sentrux.md)" "$Y"
+fi
+
+say "\n────────────────────────────────────────" "$D"
+say "✅ agent kit installed: $copied created, $skipped kept$( [ $DRY_RUN = 1 ] && echo ' (dry-run)')" "$G"
+say "   next: fill in the TODOs in docs/VISION.md and docs/ARCHITECTURE.md," "$D"
+say "   commit as 'chore: bootstrap agent kit (init-agentkit)'\n" "$D"

package/skills/init-agentkit/templates/.claude/commands/create-adr.md

@@ -0,0 +1,44 @@
+---
+description: Create a new Architecture Decision Record under docs/adr/
+---
+
+Create a new ADR in `docs/adr/` documenting a structural decision for {{PROJECT}}.
+
+## Steps
+
+1. **Read [docs/adr/README.md](../../docs/adr/README.md)** for the format, lifecycle rules, and the current index. Note the next available number (max existing + 1, four-digit zero-padded).
+
+2. **Confirm the decision is ADR-worthy.** ADRs document:
+   - New dependencies that change the surface area (new backend, new external service, new provider).
+   - Storage strategy or schema convention changes.
+   - New platform target or distribution channel.
+   - Core abstractions (new trait/protocol, new domain model, change to a central store).
+   - Hosting or secrets strategy changes.
+   - Cross-cutting patterns future contributors must follow.
+
+   ADRs do **not** document bug fixes, behavior-preserving refactors, dependency version bumps, or formatting changes. If the change is one of those, do not create an ADR — explain why and stop.
+
+3. **Gather the inputs** before writing. Ask the user (or read context) for:
+   - A short title (≤ 70 chars).
+   - The forces / constraints that led to the decision (context).
+   - The decision in one or two sentences.
+   - At least two alternatives considered, with the chosen one marked.
+   - Consequences — what gets easier, what gets harder, what invariants the codebase must now hold, what would trigger re-evaluation.
+
+4. **Create the file** at `docs/adr/NNNN-short-title.md` using the template from [docs/adr/0000-template.md](../../docs/adr/0000-template.md). Use `kebab-case` for the slug. Frontmatter:
+   - `id: "NNNN"` (four-digit, quoted)
+   - `status: active` (new ADRs default to `active` when the decision has been made; use `proposed` only if it's still under discussion)
+   - `date: YYYY-MM-DD` (today)
+   - Omit `superseded_by` unless this ADR supersedes a previous one (in which case also update the previous ADR to `status: superseded` + `superseded_by` link in the same commit).
+
+5. **Update the index** in [docs/adr/README.md](../../docs/adr/README.md): add a row to the index table at the bottom in numeric order.
+
+6. **Update [docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md) if the decision changes the active architecture state.** ARCHITECTURE.md reflects active decisions only — a superseded decision must be replaced, not appended.
+
+7. **Commit in a single Conventional Commit** with the rest of the change that implements the decision:
+   ```
+   docs(adr): NNNN <short title>
+   ```
+   or as part of a `feat:` / `refactor:` commit if landing the implementation in the same change.
+
+8. **Never edit an active ADR.** If the decision changes, create a new ADR that supersedes the previous one and update the previous ADR's frontmatter only to record `status: superseded` and `superseded_by`.

package/skills/init-agentkit/templates/.github/workflows/quality.yml

@@ -0,0 +1,43 @@
+name: quality
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # gate needs the merge base
+
+      # --- Stack toolchain (adjust to your project) -------------------------
+      # node:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22.13"
+      - run: npm ci
+      # ----------------------------------------------------------------------
+
+      - name: Type + test
+        run: |
+          {{CHECK_SUITE}}
+
+      - name: Install Sentrux
+        env:
+          SENTRUX_VERSION: {{SENTRUX_VERSION}}
+        run: |
+          mkdir -p "$HOME/.sentrux/bin"
+          curl -fsSL "https://github.com/sentrux/sentrux/releases/download/${SENTRUX_VERSION}/sentrux-linux-x86_64" \
+            -o "$HOME/.sentrux/bin/sentrux"
+          chmod +x "$HOME/.sentrux/bin/sentrux"
+          echo "$HOME/.sentrux/bin" >> "$GITHUB_PATH"
+
+      - name: Sentrux check (absolute rules)
+        run: sentrux check .
+
+      - name: Sentrux gate (no regression)
+        if: github.event_name == 'pull_request'
+        run: sentrux gate .

package/skills/init-agentkit/templates/.sentrux/baseline.json

@@ -0,0 +1,9 @@
+{
+  "_comment": "PLACEHOLDER — replace by running `sentrux gate --save .` at the repo root with the Sentrux CLI installed (see docs/sentrux.md). Commit the real baseline.",
+  "_generated_by": "init-agentkit placeholder",
+  "quality_signal": null,
+  "coupling_score": null,
+  "cycle_count": 0,
+  "god_file_count": 0,
+  "complex_fn_count": 0
+}

package/skills/init-agentkit/templates/.sentrux/rules.toml

@@ -0,0 +1,21 @@
+# Sentrux architectural constraints for {{PROJECT}}.
+#
+# Ratchet against the current layout. Tighten thresholds as the codebase grows —
+# never loosen without an ADR (see docs/adr/0003-sentrux-structural-quality-gates.md).
+#
+# Run `sentrux check .` locally before pushing.
+# Run `sentrux gate --save .` before starting a refactor;
+# run `sentrux gate .` before committing it.
+
+[constraints]
+# No import cycles.
+max_cycles = 0
+
+# Keep coupling healthy as the module count grows.
+max_coupling = "B"
+
+# Per-function cyclomatic complexity ceiling.
+max_cc = 25
+
+# Flag new god files early while the repo is small.
+no_god_files = true

package/skills/init-agentkit/templates/AGENTS.md

@@ -0,0 +1,110 @@
+# AGENTS.md — {{PROJECT}}
+
+> [Architecture](docs/ARCHITECTURE.md) · [Abstractions](docs/ABSTRACTIONS.md) · [Vision](docs/VISION.md) · [Getting Started](docs/GETTING-STARTED.md) · [ADRs](docs/adr/README.md) · [Sentrux](docs/sentrux.md)
+
+Write the minimum code that runs. No fluff, no gold-plating.
+
+<!-- variant:greenfield:start -->
+- Do not preserve backward compatibility. Remove obsolete paths instead of adding
+  compatibility layers, fallbacks, or migrations.
+<!-- variant:greenfield:end -->
+<!-- variant:stable:start -->
+- Preserve backward compatibility for anything already published — public APIs, CLI
+  contracts, persisted formats, integrations. Breaking one requires a migration path
+  and a `feat!:` / `BREAKING CHANGE:` commit. Everything not yet published is fair
+  game: remove obsolete internal paths instead of adding compatibility layers.
+<!-- variant:stable:end -->
+- Choose the simplest implementation that fully meets the current requirements.
+  Avoid speculative abstractions, configuration, and indirection.
+- Grow the system in layers. Start from the smallest version that works end to end,
+  and add each new capability on top of a product that already works. Never trade a
+  working product for unfinished complexity.
+- Keep components modular and concerns clearly separated.
+- Prefer established, well-maintained libraries when they reduce overall complexity
+  or improve reliability. Do not reimplement common functionality without a clear reason.
+- Lean on the dependencies already in the project before writing your own
+  implementation or adding packages. Do not assume a library lacks a capability
+  without checking its documentation and types.
+- Make architectural decisions for the long term. Do not accept a stopgap that only
+  works for now and is meant to be replaced later.
+- Study how established products solve the problem before designing a solution. Adopt
+  their proven patterns and conventions rather than inventing an approach from scratch.
+
+## Repository rules
+
+- **`AGENTS.md` is the single source of guidance.** `CLAUDE.md`, `GEMINI.md`,
+  `CURSOR.md` and `AGENT.md` are symlinks to it.
+  Never edit a symlink; never let one drift into a real file.
+- **Continuity beats restart.** Before starting new work, check `.runs/` and the
+  managed signal block at the bottom of this file: an active campaign or a
+  non-terminal run is work to continue — read its `HANDOFF.md`/`STATUS.md`,
+  re-attach the session, and `resume` or `supervise` — not to redo.
+- **Never commit secrets.** Tokens, credentials, and service-account JSON stay in a
+  secret manager or a gitignored `.env`. The `pre-commit` hook scans the staged diff;
+  do not work around it.
+- **No personal or production-derived data in source**, migrations, fixtures, tests,
+  or docs. Committed fixtures are synthetic. User-specific values belong in runtime
+  configuration.
+- **Never expose internals to users.** No stack traces, internal URLs, or env var
+  names in user-facing copy.
+- **Conventional Commits required.** `feat:`, `fix:`, `docs:`, `refactor:`, `test:`,
+  `chore:`. One logical change per commit; one bounded scope per PR. Release tooling
+  parses them — a break in a published contract ships as `feat!:` or carries a
+  `BREAKING CHANGE:` footer, never as a plain `feat:`.
+- **Never `--no-verify`.** If a hook blocks, fix the underlying issue.
+- **Code, comments, and identifiers in English.** Surgical changes — no opportunistic
+  refactors in feature PRs, no suppression comments to silence a linter.
+- **Shell scripts** run under `set -euo pipefail` and are idempotent — re-running
+  completes what is missing instead of duplicating or destroying.
+
+## Workflow
+
+- Check `docs/adr/` before any structural choice. Branch from `main`.
+- **TDD for behavior changes**: red → green → refactor → commit. Bug fixes start with
+  a failing regression test. Exception: pure docs, formatting, or copy changes.
+- **E2E for key features**: any user-visible change to a primary workflow adds or
+  updates a deterministic E2E scenario, isolated from real data and credentials.
+  Unit tests do not replace it.
+- **ADRs** live in `docs/adr/`, one decision per file, created in the same commit as
+  the code (`/create-adr`). Never edit an active ADR — supersede it. Required for a
+  new dependency that changes surface area, a storage or schema convention, a core
+  abstraction, a hosting or secrets strategy, or a cross-cutting pattern. Not for
+  behavior-preserving fixes, refactors, version bumps, or copy tweaks. After a
+  structural change, update `docs/ARCHITECTURE.md` in the same commit — it reflects
+  **active** decisions only.
+- **Destructive actions** — merging, force-pushing, changing repository permissions,
+  dropping schema, deleting data — require explicit human sign-off in the moment.
+  An agent that hits this gate hands off to the user rather than routing around it.
+
+## Gates
+
+```bash
+{{CHECK_SUITE}}           # types + tests
+sentrux check .           # absolute limits (.sentrux/rules.toml)
+sentrux gate .            # no structural regression vs .sentrux/baseline.json
+```
+
+CI mirrors this (`.github/workflows/quality.yml`). Before touching existing files run
+`sentrux gate --save .` to capture the baseline; before committing run `sentrux gate .`
+— degradation on a touched file means refactor, not commit. New files pass
+`sentrux check .` clean. **Never silence a rule to pass** — the gate is a ratchet, and
+every file you touch leaves with an equal-or-better score.
+
+Done means: gates pass locally, CI is green, no secrets or personal data in the diff,
+`README.md` updated if a public contract changed, ADR written if a structural decision
+was made.
+
+## {{PROJECT}} gotchas
+
+Record every failure that cost real debugging time, with the invariant that prevents
+it and a link to the ADR or code that must not be undone. Highest-value part of this
+file — keep appending.
+
+- _(none yet)_
+
+---
+
+Adapted from [Marcos Hernanz](https://x.com/MarcosHernanz/status/2083954734487212511).
+Structural gate by [Sentrux](https://github.com/sentrux/sentrux).
+`CLAUDE.md`, `GEMINI.md`, `CURSOR.md` and `AGENT.md`
+are symlinks to this file — edit `AGENTS.md` only.

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

@@ -0,0 +1,30 @@
+# Abstractions
+
+> The vocabulary of this codebase: the core types/modules and the contracts
+> between them. Read this before adding a new module — reuse an abstraction
+> before inventing one.
+
+## Core layers
+
+TODO — name each layer (e.g. transport / domain / lib) and its single responsibility.
+
+## External systems
+
+TODO — every system this repo talks to, and the boundary type that wraps it.
+
+## Contracts & invariants
+
+TODO — the rules that must always hold (validation points, error/UX contracts).
+
+## Quality & governance
+
+- Structural limits live in `.sentrux/rules.toml`; regression baseline in `.sentrux/baseline.json`.
+- Architecture decisions are recorded as [ADRs](adr/README.md).
+
+## Adding a new module — checklist
+
+- [ ] Does an existing abstraction already cover this? Reuse it.
+- [ ] Inputs/outputs validated at the boundary.
+- [ ] Unit tests close to the change.
+- [ ] `sentrux gate .` shows no degradation.
+- [ ] ADR if it introduces a cross-cutting pattern or external dependency.

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

@@ -0,0 +1,31 @@
+# Architecture
+
+> Current-state summary. ADRs in [adr/](adr/README.md) hold the history and the
+> *why*; this file reflects only **active** decisions. Update it in the same
+> commit as any structural change.
+
+## High-level flow
+
+TODO — diagram or prose of the main request/data path.
+
+## Components
+
+TODO — the major modules and their responsibilities.
+
+## Runtime & hosting
+
+TODO — where it runs, how it's deployed.
+
+## Observability & quality
+
+- Type checks + tests run on every push (see [Getting Started](GETTING-STARTED.md)).
+- Structural health gated by [Sentrux](sentrux.md).
+- Errors/telemetry: TODO.
+
+## Security model
+
+TODO — authn/authz, secret handling, data sensitivity.
+
+## Related docs
+
+- [Vision](VISION.md) · [Abstractions](ABSTRACTIONS.md) · [ADRs](adr/README.md) · [Sentrux](sentrux.md)

package/skills/init-agentkit/templates/docs/GETTING-STARTED.md

@@ -0,0 +1,44 @@
+# Getting Started
+
+## Prerequisites
+
+- TODO — runtime/toolchain versions.
+- [Sentrux CLI](sentrux.md#install) for the structural quality gate.
+
+## Quick start
+
+```bash
+# TODO: install deps
+# TODO: configure secrets (.env from .env.example)
+# TODO: run locally
+```
+
+## Daily commands
+
+```bash
+{{CHECK_SUITE}}            # types + tests
+sentrux check .           # architectural rules
+sentrux gate .            # no structural regression
+```
+
+## Worktree workflow
+
+```bash
+# Create a worktree for a task (keeps main clean):
+git worktree add ../{{PROJECT}}-<task> -b <dev>/<issue>-<slug>
+```
+
+## Documentation map
+
+- [Vision](VISION.md) — why this exists
+- [Architecture](ARCHITECTURE.md) — current-state structure
+- [Abstractions](ABSTRACTIONS.md) — the vocabulary
+- [ADRs](adr/README.md) — decision history
+- [Sentrux](sentrux.md) — the quality gate
+- [AGENTS.md](../AGENTS.md) — the contributor/agent playbook
+
+## First contribution checklist
+
+- [ ] Read [AGENTS.md](../AGENTS.md).
+- [ ] Run the check suite locally and confirm it's green.
+- [ ] `sentrux gate --save .` before touching existing files.

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

@@ -0,0 +1,33 @@
+# {{PROJECT}} — Product Vision
+
+> TODO: replace the placeholders below with the real vision. Keep it short and
+> opinionated — this is the "why", not the "how".
+
+## Why this, why now
+
+TODO — the moment that makes this worth building.
+
+## The problem
+
+TODO — who hurts, and how, today.
+
+## The insight
+
+TODO — the non-obvious bet this project makes.
+
+## Principles
+
+- TODO — a constraint you will not trade away.
+- TODO — a default you optimize for.
+
+## Near-term horizon
+
+TODO — what "done" looks like for the next milestone.
+
+## Non-goals (for now)
+
+- TODO — what you are explicitly not building yet.
+
+## Related docs
+
+- [Architecture](ARCHITECTURE.md) · [Abstractions](ABSTRACTIONS.md) · [ADRs](adr/README.md)