kanban-system 1.0.0

package/.env.example

@@ -0,0 +1,76 @@
+# kanban-system — environment variables
+# Copy to .env, fill values, NEVER commit .env
+
+# ── Server ────────────────────────────────────────────────────────
+# Port the kanban dashboard listens on. Also set in config.js (config.js wins
+# if both are present unless PORT is exported).
+PORT=8080
+KANBAN_BASE=http://localhost:8080
+
+# ── Multi-agent / cross-validation policy ─────────────────────────
+# Severity threshold for auto-promoting single-runner tasks to `both`
+# (cross-validated). Values: low, medium, high, critical.
+CROSS_VALIDATION_THRESHOLD=medium
+
+# Daily cap on the second-model (Codex / GPT) invocations. Resets at UTC midnight.
+# When exceeded, runner=codex/both/reviewer:codex falls back to the primary model.
+DAILY_CODEX_BUDGET=200
+
+# Model fallback chain — comma-separated, priority order. First is most capable.
+MODEL_FALLBACK_CHAIN=claude-opus-4-7,claude-sonnet-4-6,claude-haiku-4-5
+
+# ── Watch + Detect ────────────────────────────────────────────────
+WATCH_INTERVAL_MS=300000
+WATCH_DRY_RUN=0
+# Comma-separated detector names. Empty = all enabled detectors in lib/detect/rules.json
+WATCH_ENABLED=
+
+# Sentry (optional — detector degrades gracefully when blank)
+SENTRY_AUTH_TOKEN=
+SENTRY_ORG_SLUG=
+SENTRY_PROJECT_SLUG=
+
+# Vercel (optional)
+VERCEL_TOKEN=
+VERCEL_PROJECT_ID=
+VERCEL_TEAM_ID=
+
+# ── Pre-deploy gate ───────────────────────────────────────────────
+GATE_TIMEOUT_MS=600000
+GATE_SKIP_E2E=0
+STRICT_BUNDLE=0
+# Disable the auto-created kanban task on gate failure (CI/scripts)
+GATE_NO_KANBAN=0
+
+# ── Slack (optional — start/progress/done reporting) ──────────────
+SLACK_BOT_TOKEN=
+SLACK_APP_TOKEN=
+SLACK_CHANNEL_ID=
+SLACK_AGENT_WEBHOOK=
+SLACK_ADMIN_USERS=
+SLACK_COMMAND=/kanban
+
+# ── Telegram (optional — Ops Thread mirror panel) ─────────────────
+# Drop in TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID and the kanban server starts
+# mirroring the right-side "Ops Thread" panel to that Telegram chat (outbound
+# via sendMessage, inbound via getUpdates long-poll). Both blank ⇒ the panel
+# still works locally as a kanban-only chat; nothing is sent to Telegram.
+#
+# How to get values:
+#   1. BotFather (@BotFather on Telegram) → /newbot → copy the token here.
+#   2. Send any DM to your new bot from your Telegram account.
+#   3. With the server running: curl http://localhost:8080/api/telegram/whoami
+#      → copy chat.id of your DM (a number like 6131488858) into TELEGRAM_CHAT_ID.
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_CHAT_ID=
+# Optional comma-separated allowlist (defaults to TELEGRAM_CHAT_ID only)
+TELEGRAM_ALLOWED_CHAT_IDS=
+# Set to 0 to disable the long-poll worker (you can still send outbound)
+TELEGRAM_POLL_ENABLED=1
+TELEGRAM_POLL_INTERVAL_MS=1500
+
+# ── Anthropic / OpenAI (only if you run the CLI adapters directly) ─
+# The runner adapters shell out to the `claude` / `codex` CLIs, which manage
+# their own auth. These are placeholders for setups that pass keys via env.
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=

package/CLAUDE.md

@@ -0,0 +1,108 @@
+# kanban-system — operating rules
+
+This repo is a **kanban board + multi-agent (Claude + Codex) ops/dev harness**: a
+kanban server with a REST API, an orchestrator + specialist agents, incident
+playbooks, a 24h watch/detect loop, a subagent runner, and a pre-deploy gate. It runs
+*alongside* an application repo (the one `config.js → repoPath` points at) and drives
+work on it — it does not contain that application's code.
+
+## Layout
+| Path | Purpose |
+|---|---|
+| `server/kanban.cjs` | Kanban dashboard + REST API + SSE. `npm start`. |
+| `ui/` | The dashboard HTML + token CSS. |
+| `agents/*.md` | Agent definitions — frontmatter (`name`, `mission`, `runner`, `owns`, …) + body. `_TEMPLATE.md` to add one. |
+| `playbooks/*.html` | One-page incident runbooks. `_TEMPLATE.html` to add one. |
+| `lib/config.cjs` | Config loader — reads `config.js` (or `config.example.js`) + `.env` + env overrides. |
+| `lib/watch/scheduler.cjs` | 24h watch loop — runs detectors, turns findings into tasks. |
+| `lib/detect/*` | Monitoring detectors (`sentry`, `vercel`, `_template`) + `rules.json`. |
+| `lib/runner/*` | Subagent runner — `claude` / `codex` / `both` / `reviewer:*` adapters, git worktrees, budget. |
+| `lib/gate/index.cjs` | Pre-deploy gate — runs `config.js → deployCommands` fail-fast. |
+| `hooks/` | `pre-push.sample` (installs the gate as a git hook), `launchd.plist.template` (24h daemon; cron line in the comment). |
+| `skills/` | Reusable Claude Code skill stubs — `/standup`, `/triage`, `/gate`, `/archive`. |
+| `docs/` | `the-pattern.md` (why), `adapting-to-your-project.md` (how), `example-apex.md` (a worked case study — the only place project-specific content lives). |
+| `config.example.js` / `config.js` | Per-project config. Copy the example to `config.js` (gitignored). |
+| `.env.example` / `.env` | Tokens (Slack / Sentry / Vercel / Telegram / …). Copy, fill, never commit `.env`. |
+
+## Ops Thread (Telegram mirror)
+The dashboard's right-side panel is an append-only thread the operator and the agents
+share. With `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID` set in `.env` it mirrors
+bidirectionally to a Telegram chat (outbound via `sendMessage`, inbound via long-poll
+`getUpdates`). The kanban server also posts `📋 #N` / `▶️ #N` / `✅ #N` on task create /
+start / complete to both sides. Agents append progress via `POST /api/ops-thread/append`
+(role: `claude` / `agent` / `system`). The operator types in the panel input or replies
+in Telegram. Both halves are best-effort — missing token/chatId disables the mirror but
+the panel still works locally. Setup is in README "Ops Thread (Telegram mirror)".
+
+## Server & config
+- Start: `npm start` (or `node server/kanban.cjs`). Default port 8080 (`PORT` env or
+  `config.js → kanbanPort`).
+- API base: `http://localhost:8080/api/`.
+- Config resolution: `config.js` → `config.example.js` (fallback so it boots) → env
+  overrides on top. `.env` at the repo root is loaded automatically (so launchd / cron
+  see the tokens).
+
+## Kanban-first instruction protocol — MUST FOLLOW
+Every user instruction becomes a kanban task **before** any work starts. This is the
+orchestrator's first duty (`agents/orchestrator.md`), and it applies to every agent.
+
+1. On receiving an instruction: `POST /api/tasks` — `{ subject, description, agent,
+   metadata.runner, priority }`. Capture the instruction verbatim in `description`.
+2. Set `agent` / `metadata.runner` / `priority` per the routing rules in
+   `agents/orchestrator.md`.
+3. Transition the task to `in_progress` **only then** start the work.
+4. On completion: set `reportPath` + `reportSummary`, then `completed`.
+5. Report start / key progress / done via `POST /api/tasks/{id}/slack` (not a raw webhook).
+
+**Exception — incident response**: a production-impacting incident or a 1-line,
+obviously-reversible hotfix may be done immediately, but you must register a post-hoc
+task within 1 hour tagged `metadata.source = "incident-response"` with what you did
+and any follow-up. Nothing else qualifies — refactors, docs, features, ordinary bugs
+all go through step 1 first. See `docs/the-pattern.md` → "Kanban-first".
+
+## Task lifecycle & API
+States: `pending` → `in_progress` → `in_review` → `completed`. Only the orchestrator
+writes status transitions. `completed` requires `reportPath` + `reportSummary`.
+
+| Method | Path | Body | Description |
+|---|---|---|---|
+| GET | `/api/tasks` | — | List all tasks |
+| POST | `/api/tasks` | `{ subject, description, agent?, priority?, metadata? }` | Create |
+| PUT | `/api/tasks/:id` | `{ status?, reportPath?, reportSummary?, metadata?, ... }` | Update |
+| DELETE | `/api/tasks/:id` | — | Delete |
+| POST | `/api/tasks/:id/slack` | `{ text }` | Post a note to Slack for this task |
+| GET | `/api/agents` | — | Agent registry (from `agents/*.md` frontmatter) |
+| GET | `/api/agents/:name/full` | — | One agent's full definition |
+| GET | `/api/activity?since=&limit=` | — | Activity log |
+| GET | `/events` | — | SSE stream of board updates |
+
+## Multi-agent cross-validation
+- `runner: claude` / `codex` — single model. For deterministic / mechanical work.
+- `runner: reviewer:codex` — Claude implements, Codex reviews. Default for implementation work.
+- `runner: both` — Claude + Codex independently, diffed. Disagreement → "needs human" column.
+  For high-stakes work (migrations, access-control, money paths). The disagreement is the safety feature.
+- Auto-promote: severity ≥ `CROSS_VALIDATION_THRESHOLD` bumps single-model → `both`.
+- Daily cap on the second model (`DAILY_CODEX_BUDGET`); fallback chain `MODEL_FALLBACK_CHAIN`.
+See `docs/the-pattern.md` → "Cross-validation".
+
+## Selvedge boundaries
+Each agent declares `owns:` globs (relative to `config.js → repoPath`). Agents stay on
+their side; the orchestrator routes by ownership. Shared surfaces (shared types,
+dependency manifests, migrations) require a cross-check → that's where `runner: both`
+earns its keep. Keep `owns:` globs non-overlapping.
+
+## Pre-deploy gate
+`lib/gate/index.cjs` runs `config.js → deployCommands` serially, fail-fast, from
+`config.js → repoPath`, then an optional bundle-size inspection. The `pre-push.sample`
+hook runs it on `git push` — fail → push blocked, "needs human" task auto-created. The
+only override is `git push --no-verify` or `KANBAN_GATE_BYPASS=1 git push` (the latter
+logged to `data/runs/overrides.jsonl`, reviewed at standup).
+
+## Absolute rules
+1. Don't ship without the gate passing (or an audited override).
+2. Don't force-push the main branch.
+3. Don't commit `.env` or `config.js` (both gitignored — keep it that way).
+4. Don't cross selvedge boundaries (an agent edits only what it `owns`).
+5. Don't store plaintext secrets in `data/`, logs, or committed files (use `.env`).
+6. Don't start work on a user instruction without a kanban task first (incident-response exception only).
+7. Don't auto-merge a `runner: both` disagreement — a human decides.

package/README.md

@@ -0,0 +1,272 @@
+# kanban-system
+
+A kanban board where **multi-agent operators (Claude + Codex, via their CLIs)** run
+24/7 ops and dev for a project: a person's instruction becomes a kanban task, the
+orchestrator routes it to a specialist agent with a verification level (single-model /
+review / independent cross-validation), the work happens in an isolated git worktree, a
+pre-deploy gate blocks anything that doesn't build/test, a 24h watch loop turns
+monitoring anomalies into tasks, and incident playbooks tell humans what to do when
+something breaks. It's a *template* — clone it, point `config.js` at your front-end /
+back-end repo, edit a few globs, and you have the "kanban + multi-agent" pattern
+running on your codebase.
+
+It runs *alongside* your application repo (it does not contain that app's code) and
+drives work on it.
+
+## Installation
+
+Two ways to get started:
+
+### Option A — GitHub Template (zero config, keeps update history)
+
+1. Open **[github.com/Zakedu/kanban-system](https://github.com/Zakedu/kanban-system)** and click **"Use this template"** → **"Create a new repository"**.
+2. Clone your new repo and jump straight to [Quick start](#quick-start).
+
+```bash
+gh repo create my-board --template Zakedu/kanban-system --private --clone
+cd my-board
+```
+
+### Option B — npx CLI (zero clone, no GitHub account required)
+
+```bash
+npx kanban-system init my-board
+cd my-board
+cp config.example.js config.js   # edit: repoPath, deployCommands
+cp .env.example .env             # (optional) Slack / Sentry / Vercel tokens
+npm install
+npm start                        # → http://localhost:8080
+```
+
+The CLI also exposes thin wrappers so you can run the harness commands from the
+published package without cloning the repo:
+
+```bash
+npx kanban-system start          # start the kanban server
+npx kanban-system watch          # run the 24h watch scheduler
+npx kanban-system gate           # run the pre-deploy gate
+npx kanban-system whoami         # find your Telegram chat id
+npx kanban-system --version
+```
+
+### Publishing to npm (maintainer only)
+
+```bash
+# bump version first
+npm version patch   # or minor / major
+
+npm publish --access public
+```
+
+`npm publish` requires being logged in (`npm login`) and having push access to the
+`Zakedu/kanban-system` repository. The `files` field in `package.json` controls what
+ships in the tarball.
+
+---
+
+## Architecture
+
+```
+                                  ┌─────────────────────────────┐
+   you / Slack / API ──────────▶  │  kanban server (REST + SSE) │  ◀── browser dashboard
+                                  │  server/kanban.cjs · ui/    │
+                                  └──────────────┬──────────────┘
+                                                 │ tasks
+                                       ┌─────────▼─────────┐
+                                       │   orchestrator    │  routes by `owns` globs,
+                                       │  agents/orch...md │  sets the `runner`, enforces
+                                       └─────────┬─────────┘  the task state machine
+                       ┌─────────────────────────┼─────────────────────────┐
+              ┌────────▼───────┐  ┌──────────────▼─────┐  ┌────────────────▼──────┐  ┌───────────▼────────┐
+              │ frontend-agent │  │   backend-agent    │  │  deploy-gate-agent    │  │   monitor-agent    │
+              │  pages, UI,    │  │  API, DB, migra-   │  │  runs the gate (build │  │  polls Sentry /    │
+              │  routing, i18n │  │  tions, authz      │  │  /test) before deploy │  │  Vercel / custom   │
+              └────────────────┘  └────────────────────┘  └───────────┬───────────┘  └─────────┬──────────┘
+                       │                    │                         │                        │
+                  reviewer:codex       runner: both              hard gate, no              anomalies → tasks
+                  (Claude impl,        (Claude + Codex          agent override          (lib/watch + lib/detect)
+                   Codex reviews)       independent, diffed)    (hooks/pre-push.sample)
+                       └────────────────────┴──── lib/runner (claude/codex/both/reviewer adapters, git worktrees, budget) ────┘
+
+   incident? ──▶ playbooks/*.html  (one-page runbooks: trigger → diagnose → decision tree → escalate → aftermath)
+```
+
+- **kanban server** (`server/kanban.cjs` + `ui/`) — a 4-column board (pending /
+  in progress / needs human / completed) with a REST API, SSE live updates, an agent
+  registry from `agents/*.md`, and an optional Slack bot.
+- **orchestrator** (`agents/orchestrator.md`) — the single decision-maker: turns every
+  instruction into a task, routes it (by `owns` glob, by severity), sets the `runner`,
+  owns the state machine. Never edits app code itself.
+- **specialist agents** (`agents/frontend-agent.md`, `backend-agent.md`,
+  `deploy-gate-agent.md`, `monitor-agent.md`, `reviewer-codex.md`) — each `owns` a
+  non-overlapping slice of your repo and declares a default `runner`. `_TEMPLATE.md` to
+  add more.
+- **playbooks** (`playbooks/*.html`) — scannable incident runbooks the agents/orchestrator
+  link from tasks. `_TEMPLATE.html` + four examples (`build-fail`, `e2e-regression`,
+  `sentry-spike`, `deploy-rollback`).
+- **watch + detect** (`lib/watch/scheduler.cjs`, `lib/detect/*`) — a 24h loop that runs
+  the enabled detectors (`sentry`, `vercel`, or your own from `_template.cjs`) and posts
+  findings as kanban tasks. Thresholds live in `lib/detect/rules.json` (hot-reloaded).
+- **runner** (`lib/runner/*`) — executes a task per its `runner`: spawns the `claude` /
+  `codex` CLI in an isolated git worktree, merges the results when `runner: both`, writes
+  the verdict + diff back to the task. Has a daily second-model budget with a fallback chain.
+- **gate** (`lib/gate/index.cjs`) — runs `config.js → deployCommands` fail-fast, inspects
+  bundle size, auto-creates a "needs human" task on failure. Installed as a git pre-push
+  hook via `hooks/pre-push.sample`.
+
+## Quick start
+
+Three ways to install — pick whichever fits.
+
+**A. `npx` (zero install, fastest)**
+```bash
+npx kanban-system init my-board
+cd my-board
+cp config.example.js config.js   # edit: repoPath, deployCommands
+cp .env.example .env             # (optional) TELEGRAM_BOT_TOKEN, SENTRY_TOKEN, ...
+npm install                      # virtually nothing
+npm start                        # → http://localhost:8080
+```
+
+**B. GitHub Template** — open the repo on GitHub and click **"Use this template" →
+"Create a new repository"**. Then `git clone` your new repo and follow steps from
+the `cp config.example.js …` line above. Best for team / long-running ops.
+
+**C. Plain `git clone`** — if you want to work directly on a fork:
+```bash
+git clone https://github.com/Zakedu/kanban-system.git
+cd kanban-system
+cp config.example.js config.js && cp .env.example .env
+npm install && npm start
+```
+
+Open `http://localhost:8080`. Create a task in the UI (or `curl -X POST
+http://localhost:8080/api/tasks -H 'Content-Type: application/json' -d '{"subject":"Try
+it"}'`) and watch it on the board. Run the gate: `npm run gate`. Run one watch sweep:
+`npm run watch:once`. (The `claude` / `codex` CLIs are optional — without them the runner
+falls back to deterministic stub verdicts.)
+
+## Adapting to your project (front-end / back-end)
+
+The full step-by-step is in **[docs/adapting-to-your-project.md](docs/adapting-to-your-project.md)**.
+In short:
+
+1. **`config.js`** — point `repoPath` at your repo; set `deployCommands` to your stack's
+   build/test chain (`npx tsc --noEmit` + `npm run build`, or `cargo build` + `cargo test`,
+   or `go vet` + `go test`, …); set `buildOutputDir` (or `null`).
+2. **`agents/`** — edit the `owns:` globs in `frontend-agent.md` / `backend-agent.md` to
+   match your directory layout. Copy `_TEMPLATE.md` for more roles.
+3. **`lib/detect/`** — enable the detector for your monitoring (`sentry` / `vercel` / your
+   own from `_template.cjs`) in `config.js → detectors`. No monitoring? Leave it empty.
+4. **`agents/deploy-gate-agent.md` + `lib/gate/`** — the gate runs `config.js →
+   deployCommands`; no code change needed, just review the agent doc so it matches.
+5. **`playbooks/`** — copy `_TEMPLATE.html` for each incident type you care about.
+6. **`hooks/`** — install `pre-push.sample` into your app repo's `.git/hooks/pre-push`;
+   schedule the 24h watch via `launchd.plist.template` (macOS) or the cron line in its comment.
+7. *(optional)* — wire a Slack bot token for start / progress / done reporting and the
+   `/kanban` slash command.
+8. *(optional)* — wire **Telegram** for 24h ops-from-anywhere. See the next section.
+
+## Ops Thread (Telegram mirror) — optional
+
+The kanban dashboard has a right-side **Ops Thread** chat panel. Everything in it is
+mirrored to a Telegram chat in both directions, so you can run 24h ops from your phone
+without leaving the kanban as the source of truth.
+
+```
+[ kanban dashboard ]                            [ your Telegram DM ]
+  Ops Thread panel  ◀──── /api/ops-thread ────▶   sendMessage / getUpdates
+       │                       │                          │
+       └── you type ───────────┘                          │
+                               └── operator replies ──────┘
+       task created / completed → 📋 / ✅ posted to both sides
+```
+
+**Setup** (~2 minutes, no PG / no external service):
+
+1. Open Telegram, message `@BotFather`, send `/newbot`, follow the prompts. Copy the
+   token you get.
+2. Send any DM to your new bot from your own Telegram account (this is what lets the
+   bot see you exist — Telegram won't deliver replies otherwise).
+3. Put the token + chat id in `.env`:
+   ```bash
+   TELEGRAM_BOT_TOKEN=123456:AA...your_token
+   TELEGRAM_CHAT_ID=    # leave blank for now
+   ```
+4. `npm start`, then in another terminal:
+   ```bash
+   curl http://localhost:8080/api/telegram/whoami
+   # → { "ok": true, "chats": [ { "id": 6131488858, "type": "private", ... } ] }
+   ```
+   Copy that `id` into `TELEGRAM_CHAT_ID` in `.env`, restart `npm start`.
+5. Done — type in the Ops Thread panel and it appears in Telegram; reply in Telegram
+   and it shows up in the panel. Task `created` → `📋 #N <subject>`, `in_progress` →
+   `▶️ #N`, `completed` → `✅ #N — <one-line report>`.
+
+**No Telegram?** Leave the env vars blank. The panel still works as a local kanban-only
+chat (and as a place where the server posts task lifecycle events).
+
+**Allowing only specific people**: set `TELEGRAM_ALLOWED_CHAT_IDS=id1,id2` to allow more
+than one chat. Empty list ⇒ only `TELEGRAM_CHAT_ID` is accepted (recommended for solo ops).
+
+**Endpoints** (you usually never call these — the UI does):
+- `GET  /api/ops-thread?since=<id>` — load thread (paginated by message id)
+- `POST /api/ops-thread/append { role, text, taskId? }` — agents append to the thread
+- `POST /api/ops-thread/send { text }` — you send (also mirrored to Telegram)
+- `GET  /api/telegram/status` — `{ configured, polling, chatId }`
+- `GET  /api/telegram/whoami` — debug: dump recent `getUpdates` so you can find a chat id
+
+## The kanban-first protocol
+
+Every user instruction becomes a kanban task **before** work starts: capture it
+verbatim, route it, set the `runner`, transition to `in_progress`, and only then start.
+On completion, set `reportPath` + `reportSummary`. The single exception is **incident
+response** — a production-impacting incident or a 1-line, obviously-reversible hotfix may
+be done immediately, but a post-hoc task must be registered within 1 hour, tagged
+`metadata.source = "incident-response"`. Nothing else qualifies. Rationale and the state
+machine: **[docs/the-pattern.md](docs/the-pattern.md)** → "Kanban-first".
+
+## Multi-agent cross-validation
+
+Pick the verification level per task via `runner`:
+- **single-model** (`claude` / `codex`) — deterministic / mechanical work (running tests,
+  polling an API, a state transition); a second opinion only adds latency.
+- **`reviewer:codex`** — Claude implements in an isolated worktree, Codex reviews the
+  result and can downgrade the verdict to `needs_human`. Default for implementation work.
+- **`both`** — Claude *and* Codex independently do the work from the same spec, in
+  separate worktrees; the orchestrator diffs them. Agreement → auto-merge; disagreement →
+  "needs human" column. For high-stakes work (schema migrations, access-control policies,
+  money paths) — the disagreement is the safety feature.
+
+The orchestrator auto-promotes single-model → `both` above a severity threshold; a daily
+second-model budget caps cost. Details: **[docs/the-pattern.md](docs/the-pattern.md)** →
+"Cross-validation".
+
+## Example: APEX
+
+APEX is an AI-skills certification exam platform (React/Vite front end, Supabase back
+end) that ran this harness in production under the codename "Sentinel": 8 generic
+ops/dev agents like the ones here plus a 6-agent domain group, an `exam-engine` selvedge
+boundary, a deliberately powerless "proctor" agent (detect-and-escalate, never enforce),
+`runner: both` on migrations / grading prompts / credential scoring, and the
+gate-before-push rule. Full write-up: **[docs/example-apex.md](docs/example-apex.md)** —
+the one place project-specific domain content lives.
+
+## CLI reference
+
+The `kanban-system` bin (also usable as `npx kanban-system <cmd>`):
+
+| Command | What it does |
+|---|---|
+| `init <name>` | Scaffold a fresh checkout into `./<name>` (config templates + all the harness files, minus the CLI itself) |
+| `start [--port N]` | Run `server/kanban.cjs`. Prefers the local checkout's server if present (so config.js / UI edits apply) |
+| `watch [--once]` | Run `lib/watch/scheduler.cjs` |
+| `gate` | Run `lib/gate/index.cjs` |
+| `whoami` | Probe a running server's `/api/telegram/whoami` (find your Telegram chat id) |
+| `--version` / `--help` | Self-explanatory |
+
+## License / status
+
+MIT. Status: extracted as a domain-agnostic template + npm CLI; the pieces are present
+and wired, but you'll want to exercise them against your own repo before relying on
+them in production.

package/agents/_TEMPLATE.md

@@ -0,0 +1,42 @@
+---
+# ── Required frontmatter ──────────────────────────────────────────────────────
+name: my-agent                       # slug; must match the file name without .md
+mission: >-                          # one sentence: what failure does this agent prevent?
+  Prevent <failure mode> in <area> by <what it does>.
+runner: claude                       # claude | codex | both | reviewer:codex | reviewer:claude
+model_default: claude-opus-4-7        # the model the runner uses by default
+auto_promote_on:                      # optional: when to bump a single-runner task to `both`
+  - severity: medium
+  - regression_window: 30d
+tools_allowed: [Read, Edit, Bash]     # the tools this agent may use
+worktree: isolated                    # isolated (own git worktree) | inline (works in place)
+escalation: human                     # human | other-agent:<name>
+owns:                                 # globs (relative to repoPath) this agent owns —
+  - src/feature/**                    # used by the orchestrator for "which agent owns this file?"
+---
+
+# My Agent
+
+One paragraph: what this agent is responsible for, and what it explicitly does NOT touch.
+
+## Triggers
+Concrete signals that create a task for this agent. Examples:
+- PR touches files matching `owns`.
+- A monitor detector routes an anomaly here.
+- A specific incident playbook escalates to this agent.
+
+## Inputs
+Data sources / file paths / API endpoints this agent reads.
+
+## Outputs
+Files/reports this agent produces. Convention: `data/runs/<task-id>/report.md`.
+
+## Cross-validation policy
+When (if ever) the second model verifies, and the decision rule when they disagree.
+See docs/the-pattern.md for the three modes (`both`, `reviewer:*`, single-model).
+
+## Failure handling
+Timeout, model unavailable, disagreement deadlock, build failure — what happens.
+
+## Example
+One sample task lifecycle: trigger → what the agent does → output → resolution.

package/agents/backend-agent.md

@@ -0,0 +1,81 @@
+---
+name: backend-agent
+mission: >-
+  Protect the server side — API handlers, database schema and migrations, access
+  policies, background jobs — where a bad change can corrupt or leak data.
+runner: both
+model_default: both
+tools_allowed: [Read, Edit, Write, Bash]
+worktree: isolated
+escalation: human
+owns:
+  # Edit to match YOUR layout. Examples:
+  #   Node API:        server/**, api/**, src/server/**, src/api/**
+  #   Migrations:      migrations/**, db/migrate/**, prisma/migrations/**
+  #   Supabase:        supabase/functions/**, supabase/migrations/**   (one possible backend)
+  #   Rails:           app/controllers/**, app/models/**, db/migrate/**
+  #   Go services:     internal/**, cmd/**
+  - server/**
+  - api/**
+  - db/**
+  - migrations/**
+  - lib/**
+  - functions/**
+---
+
+# Backend Agent
+
+High-stakes territory: a bad migration or access-control rule can corrupt data or
+leak it, so every change here runs cross-validated. Owns API/route handlers, the
+database schema and migrations, authz/RLS-style policies, shared server utilities,
+and background jobs. Does not touch the front end (that's `frontend-agent`).
+
+> The original of this template was built for a project that used Supabase
+> (Edge Functions + Postgres + RLS). Those specifics moved to `docs/example-apex.md`
+> as a worked example — keep this file stack-agnostic and write your own rules below.
+
+## Triggers
+- A PR touches files under `owns` — especially anything under a migrations path.
+- A monitor detector reports a server-side anomaly (5xx burst, function timeouts,
+  authz-denial spike) and routes it here.
+- Migration drift detected when applying to an environment.
+
+## Inputs
+- Handler / function source.
+- Migration files (forward and, ideally, backward).
+- Seed data.
+- A production schema snapshot (e.g. a `db dump`), so changes can be diffed against reality.
+
+## Outputs
+- A migration plan with forward + rollback steps.
+- An access-policy diff (which roles × which tables/resources change).
+- `data/runs/<task-id>/migration-plan.md` and `report.md`.
+
+## Cross-validation policy — `runner: both`
+Claude and Codex run in parallel from the same spec, independently:
+- Each writes the migration / handler code on its own.
+- The orchestrator diffs the two. If they produce a functionally equivalent change
+  (same schema delta, same policy set) → `agreed`, auto-merge.
+- If they differ on *which* columns to drop, *which* policy to add, or any DDL →
+  `disagreed` → human review is forced. (This is by design: server-side data changes
+  are exactly where you want two independent reads to converge before shipping.)
+
+Project-specific rules the cross-validation should enforce (fill these in):
+- No destructive migration (`DROP COLUMN`, `DROP TABLE`) without a deprecation window.
+- No access-policy change without an explicit, enumerated list of affected roles.
+- No deploy without the shared CORS / auth helpers imported.
+- Secrets / service-role keys never used outside the designated shared module.
+
+## Failure handling
+- Migration applies on staging but not on the production schema → block, escalate.
+- Build/deploy fails → block, log.
+- Any access-control test (anonymous / authenticated / service role) fails → block.
+
+## Example
+```
+Trigger: monitor-agent reports a 5xx spike on the payment webhook
+Claude:  reads logs → diagnoses a missing signature-header validation, writes the fix
+Codex:   reads logs independently → diagnoses the same root cause, plus suggests a rate-limit guard
+Diff:    agreed on root cause + fix; partial on the rate-limit (Codex extra)
+Resolve: merge the fix; file a follow-up task for the rate-limit guard
+```

package/agents/deploy-gate-agent.md

@@ -0,0 +1,73 @@
+---
+name: deploy-gate-agent
+mission: >-
+  Block any push that fails type-check, build, or the chosen test/E2E suite —
+  the last safety net before a deploy goes out.
+runner: reviewer:codex
+model_default: claude-opus-4-7
+tools_allowed: [Bash, Read]
+worktree: inline
+escalation: human
+owns:
+  - .git/hooks/pre-push
+  - lib/gate/**
+---
+
+# Deploy Gate Agent
+
+Runs the pre-deploy verification chain (see `lib/gate/index.cjs`). It is a *hard*
+gate — it cannot be bypassed without an explicit, audited override. It never edits
+application code; it only runs commands and reports.
+
+The commands it runs come from `config.js → deployCommands`, executed in order from
+`config.js → repoPath`, fail-fast. Set them to whatever "this builds and the smoke
+tests pass" means for your stack:
+
+```
+Node / Vite:   [{ name:"01-typecheck", cmd:"npx", args:["tsc","--noEmit"] },
+                { name:"02-build",     cmd:"npm", args:["run","build"] }]
+Rust:          [{ name:"build", cmd:"cargo", args:["build","--release"] },
+                { name:"test",  cmd:"cargo", args:["test"] }]
+Go:            [{ name:"vet",  cmd:"go", args:["vet","./..."] },
+                { name:"test", cmd:"go", args:["test","./..."] }]
+```
+
+## Triggers
+- `git push` (via the `pre-push` hook — see `hooks/pre-push.sample`).
+- A manual `/gate` invocation.
+- Before merging a release branch.
+
+## Inputs
+- The git diff (HEAD vs the upstream branch).
+- The commands from `config.js → deployCommands`.
+- The last successful gate run (`data/runs/last-gate.json`) for bundle-delta comparison.
+
+## Verification chain (serial, fail-fast)
+The chain is `deployCommands` in order, then an optional bundle-inspection stage
+(if `config.js → buildOutputDir` is set): walks the output directory, compares total
+size to the last passing run, and warns (or fails, if `STRICT_BUNDLE=1`) on a large
+regression.
+
+## Outputs
+- `data/runs/gate-<timestamp>/<stage>.log` per stage.
+- `data/runs/gate-<timestamp>/report.md` — pass/fail + duration per stage.
+- On failure: a kanban task is auto-created in the "needs human" column with the logs
+  linked (disable in CI with `GATE_NO_KANBAN=1`).
+
+## Cross-validation policy — `reviewer:codex`
+Claude runs the gate; Codex then reviews the build output for things a green build
+hides: unused exports, dynamic imports with no chunk hints, new `process.env` reads
+that aren't in `.env.example`, an accidentally-bundled heavy dependency. A Codex
+concern that isn't blocking the build still lets the gate pass — but it files a
+follow-up cleanup task.
+
+## Failure handling
+- A `deployCommands` stage fails → push blocked, full log saved, error returned to the
+  terminal with `file:line` where the tool provided it.
+- Bundle-inspection warning → push allowed, follow-up task created (unless `STRICT_BUNDLE=1`).
+
+## Override
+Only a human bypasses, via `git push --no-verify`. The `pre-push.sample` hook also
+honours `KANBAN_GATE_BYPASS=1 git push`, which logs an entry to
+`data/runs/overrides.jsonl` (timestamp, branch, user). Overrides are reviewed at the
+daily standup.