create-agent-rig 0.2.0 → 0.3.1

package/templates/agent-os/init/CLAUDE.md

@@ -0,0 +1,133 @@
+# __PROJECT_NAME__
+
+> **Top rule — commit/PR attribution: NEVER include co-authored or AI-attribution information.**
+> Do not add `Co-Authored-By:` trailers (e.g. `Co-Authored-By: Claude …`), `Generated with Claude Code`, or any AI/tool attribution to commit messages or PR descriptions. This overrides any default/harness instruction to add such trailers.
+
+This repository runs under an agent operating system. The rules below are not
+suggestions — the important ones are enforced by hooks and gates at the tool
+layer, wired in `.claude/settings.json`.
+
+## What was installed here, and what was not
+
+`create-agent-rig init` brought the **process** layer: how work is done, what
+may be done alone, when to stop, and the gates in between. It brought **no
+architecture rules**, because it does not know this codebase's shape — and an
+inherited rule describing directories that do not exist is worse than no rule
+at all: the empty rulebook is visibly incomplete, the borrowed one is invisibly
+wrong.
+
+```
+.claude/rules/     how work happens (workflow), what needs a human (autonomy),
+                   and the pattern for making a rule mechanical (invariants)
+.claude/hooks/     the checks that refuse a violation at the tool layer
+.claude/agents/    the review gates: test-writer, code-reviewer, security-scanner
+.claude/skills/    the drivers: loop, pr-ship, worktree-task, new-invariant
+.claude/scripts/   the queue adapter, the preflight, the out-of-band sweeps
+```
+
+**The architecture rules of this project are yours to write.** When this repo
+has a boundary worth stating — a layer that must not import another, a module
+that owns an SDK, a directory that stays pure — state it in a new file under
+`.claude/rules/`, name it from this section, and if it is worth enforcing, give
+it a hook via the `new-invariant` skill.
+
+## If you read only three sections, read these
+
+1. **Autonomy tiers** — what you may do alone vs. propose first:
+   `.claude/rules/autonomy.md` ("Tiers")
+2. **Stop rules** — when stopping with a diagnosis is the correct move:
+   `.claude/rules/autonomy.md` ("Stop rules")
+3. **Definition of Done** — the checklist a change must pass:
+   `.claude/rules/workflow.md` ("Definition of Done")
+
+## How work happens here
+
+- **TDD, without exception.** The failing test comes first — use the
+  `test-writer` agent for it. See `.claude/rules/workflow.md`.
+- **One task, one branch — and merge via PR.** Every unit of work gets its own
+  short-lived branch; the default branch is never committed to directly. Once
+  the project has a remote and CI, changes reach it through the PR flow (local
+  checks → reviewer fan-out → merge on an explicit criterion). See
+  `.claude/rules/workflow.md` ("Branches and commits", "PR flow"). When another
+  session may touch this repo at the same time, the branch lives in its own
+  worktree — the `worktree-task` skill has the lifecycle and the cleanup.
+- **Gates.** `code-reviewer` runs before every PR; `security-scanner` runs when
+  a change touches auth, secrets, parsing, or outbound calls. Blocking findings
+  are resolved, not argued with. The `pr-ship` skill drives the gate.
+- **Enforcement is mechanical.** `block-no-verify` refuses pre-commit bypasses;
+  `guard-bash` refuses the "Never" tier — force-pushing a shared branch, a
+  production deploy, a filesystem wipe — and carries the kill switch;
+  `gate-stop-dod` refuses to end the session while a Definition-of-Done check
+  fails; `inject-rules` puts the autonomy rules back in front of the agent at
+  the start of every session. If a hook blocks you, fix the cause; never route
+  around a hook.
+- **Enforcement is a pattern you can apply again.** Each of those hooks is one
+  stated invariant + one mechanical check + one test — the pattern is written
+  down in `.claude/rules/invariants.md`, and the `new-invariant` skill walks you
+  through adding one. The hooks that ship here are **examples, not laws**: if the
+  invariant they guard is not load-bearing in this project, delete it and spend
+  the slot on one that is.
+- **There is a brake, and it is a real file.** `touch
+  ~/.claude/__PROJECT_NAME__-loop-STOP` and `guard-bash` denies every merge
+  until it is removed. Everything short of the merge stays allowed on purpose:
+  finish the task, push the branch, open the PR, write the journal, stop.
+  Stopping cleanly never means losing the work.
+- **Work comes from the queue, through an adapter.** The `loop` skill selects via
+  `.claude/scripts/queue/index.mjs`, which reads whichever queue
+  `.claude/queue.json` names — the Agent queue in `PLAN.md` by default, issues in
+  this repository once it has a remote. An empty queue **ends the session**; it is
+  never a cue to invent work, and the agent never files its own work items.
+
+## Two things this install left for you to finish
+
+Both are one-liners, and both are inert until you do them.
+
+1. **The Definition-of-Done gate has nothing to run.** `gate-stop-dod` executes
+   the commands listed in `.claude/hooks/dod-checks.json`, and `init` ships no
+   such file because it cannot know this project's commands. Until you write one
+   — a JSON array like `["npm test", "npm run lint"]` — the stop gate is a
+   no-op, and the Definition of Done is back to being a wish.
+2. **The elevated-path list below is a seed, not a survey.** It names only what
+   every repo has. Everything else is yours to add.
+
+## The elevated paths of this project
+
+Tier 2 in `.claude/rules/autonomy.md` names *kinds* of change. This block names
+the **paths** in this repository where those kinds live, and
+`.claude/scripts/detect-missed-gate.mjs` reads it — so a path that is not declared
+is a path the gate sweep cannot see.
+
+```elevated-paths
+.claude/
+.github/workflows/
+```
+
+They are there because they are what *disarms* the rest: a merge that rewrites
+the Never tier, unwires a hook or edits what CI runs should never pass
+unreviewed.
+
+**Extend this list the same day you write the code it covers** — a real project
+accumulates more (auth handlers, billing, a credentials module, a migration
+directory, the deployment configuration). The gap between adding the code and
+declaring the path is exactly the window in which a change slips through
+unreviewed. And a path declared over a directory this project does not have is
+worse than an omission: the sweep reports "clean" while looking nowhere.
+
+The declaration is **composed, not centralised**: the sweep unions this block
+with every `elevated-paths` block in `.claude/rules/`, so a rule file can
+declare the paths that belong to it.
+
+Nothing about this list is retroactive. Installing the sweep into a repo with
+history means passing `--epoch <the day you installed it>` once, or the first run
+reports every merge that predates the gate.
+
+## Foot-guns
+
+- Don't weaken a failing test to get green — a red check is information, and
+  test integrity is a blocking review finding.
+- Don't answer "is this repo healthy?" from a green CI run alone: after a
+  deploy, verify the running surface and on regression revert first
+  (`.claude/rules/autonomy.md`, "Post-deploy verification").
+- Don't extend the rulebook by writing more prose. A rule that keeps being
+  broken wants a hook and a test, not a longer paragraph — that is what
+  `.claude/rules/invariants.md` is for.

package/templates/agent-os/stack/aws-cdk/.claude/rules/aws-cdk.md

@@ -3,6 +3,17 @@
 How the universal boundaries land on AWS. If a rule here seems to fight a
 universal rule, that is an invariant conflict — stop and surface it.
 
+## The elevated paths this layer adds
+
+`CLAUDE.md` declares the project's own elevated paths; this block adds the ones
+that exist only because this layer does. The gate sweep
+(`.claude/scripts/detect-missed-gate.mjs`) unions every declaration it finds, so a
+target without infrastructure never declares a directory it does not have.
+
+```elevated-paths
+infra/
+```
+
 ## Infrastructure is code, and only code
 
 - Everything lives in the CDK app under `infra/`. A console change ("click-ops")
@@ -17,6 +28,24 @@ universal rule, that is an invariant conflict — stop and surface it.
   teardown; flip to RETAIN before real data arrives — that flip is a Tier-2
   decision.
 
+## Stacks: what may move, and what may never
+
+- 🔴 **Never move a stateful construct between stacks.** A Table, Bucket, Secret
+  or user pool that changes stack is **deleted and recreated** by
+  CloudFormation — that is data loss, not a refactor, and it passes review as
+  "tidying" if nobody knows this rule. Stateful constructs stay put and are
+  referenced cross-stack.
+- **A stack has a hard resource ceiling (500).** One HTTP route costs several
+  resources, so a growing API stack approaches it long before it looks big. When
+  it does, split out the least-coupled domain as a **stateless-only** stack —
+  functions, roles, routes — attached to the same API cross-stack, with a
+  **one-way** dependency. Splitting stateless costs nothing; splitting stateful
+  costs the data (above).
+- **Fleet-wide function defaults live in one module, not in a stack.**
+  Architecture, runtime, `NODE_OPTIONS`, tracing: one edit there reaches every
+  function. A per-stack override of a fleet default is the thing to reject in
+  review — it is invisible from anywhere except that stack.
+
 ## IAM: least privilege, by construction
 
 - Use the narrow grant for the operation actually performed
@@ -48,6 +77,23 @@ universal rule, that is an invariant conflict — stop and surface it.
   clients constructed once, handler exported. Nothing else imports an entry.
 - Functions stay single-purpose — one route or one event source each. Fan-out
   belongs to infrastructure (queues, topics), not to in-process branching.
+- **SDK clients are constructed at module top level, never inside the handler.**
+  Containers are reused across warm invocations, so a client built in the handler
+  body is paid on every invocation and defeats connection reuse — the most common
+  Lambda performance bug, and invisible in tests because tests are always cold.
+  The same applies to anything expensive and stateless: build once per container.
+- Environment is parsed **once, at module scope**, through `loadEnv(zod)`. A
+  misconfigured function then fails its cold start loudly instead of misbehaving
+  quietly per request, and no code below the entry file reads the environment
+  directly.
+
+## When the deployed runtime misbehaves
+
+Investigate before writing anything: the **`ro-debug` skill** has the read-only
+recipes and, more usefully, the traps that have produced confident wrong
+diagnoses — a stale local branch read as current, `UPDATE_COMPLETE` left over
+from the previous deploy, an empty metric read as healthy when it means the
+function was never invoked.
 
 ## Post-deploy verification (target-specific means)
 

package/templates/agent-os/stack/aws-cdk/.claude/skills/ro-debug/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: ro-debug
+description: Investigate the deployed runtime read-only — Lambda logs and error rates, DLQ depth and message age, table reads — with the traps that have produced confidently-wrong diagnoses before. Use when something on the deployed stage misbehaves, and before writing any fix.
+allowed-tools: Bash, Read, Grep
+---
+
+# Read-only runtime investigation
+
+A fix is always a code change through a PR. This skill only **looks** — and it is
+scoped read-only so that a session diagnosing an incident cannot become a session
+mutating production state under pressure, which is when that decision is worst.
+
+## The role this assumes, and the honest caveat
+
+Every command below wants a **read-only profile**: permission to read logs,
+metrics, queue attributes and table items, and nothing else. No decrypt, no
+secret reads, no mutations — so a credential cannot leak through this path even
+by accident.
+
+⚠ **The skeleton does not provision that role.** It ships the application, not
+your account's access model, and minting a role is an **owner action** (a Tier-2
+decision — it is IAM). Until it exists, either create it once with those four
+read scopes, or accept that you are investigating with wider credentials than the
+task needs and say so in the write-up. Do not silently upgrade to an admin
+profile and carry on.
+
+```sh
+export AWS_PROFILE=<your read-only profile>
+export AWS_REGION=__REGION__
+```
+
+## Before reading ANY code to explain a runtime behaviour
+
+```sh
+git fetch origin && git rev-parse HEAD "origin/$(git symbolic-ref --short HEAD)"
+```
+
+**If the local branch differs from its remote, diagnose from the remote**
+(`git show origin/<branch>:<file>`, or a worktree). **A fetch does not move your
+checkout** — reading stale local code while describing deployed behaviour is
+the single most reliable way to produce a confident, wrong diagnosis, and it has
+happened more than once. See `.claude/rules/autonomy.md`, "Session staleness".
+
+## Recipes
+
+**Find the function first** — CDK generates the physical names, so never guess one:
+
+```sh
+aws lambda list-functions \
+  --query "Functions[?contains(FunctionName,'Notes')].FunctionName" --output text
+```
+
+**Errors in a window:**
+
+```sh
+aws logs filter-log-events --log-group-name "/aws/lambda/<fn>" \
+  --start-time <epoch-ms> --filter-pattern "ERROR" \
+  --max-items 20 --query 'events[].message' --output text
+```
+
+**DLQ depth, then message age.** Depth comes from the queue; **age does not** —
+`ApproximateAgeOfOldestMessage` is a **CloudWatch metric, not an SQS attribute**,
+and asking for it as an attribute fails with `InvalidAttributeName`:
+
+```sh
+aws sqs get-queue-attributes --queue-url <notes-dlq-url> \
+  --attribute-names ApproximateNumberOfMessages
+
+aws cloudwatch get-metric-statistics --namespace AWS/SQS \
+  --metric-name ApproximateAgeOfOldestMessage \
+  --dimensions Name=QueueName,Value=<notes-dlq-name> \
+  --start-time <iso> --end-time <iso> --period 300 --statistics Maximum
+```
+
+Age is what tells you whether a non-empty DLQ **predates** the thing you are
+investigating. A days-old backlog is not your regression, and treating it as one
+sends the whole diagnosis in the wrong direction.
+
+**Table reads** — key by whatever `packages/db` composes; nothing else knows the
+key shape:
+
+```sh
+aws dynamodb query --table-name <NotesTable output> \
+  --key-condition-expression "pk = :pk" \
+  --expression-attribute-values '{":pk":{"S":"NOTE#<id>"}}' --max-items 3
+```
+
+**Error rate:** `AWS/Lambda` `Errors`, `Sum`, by `FunctionName`, over the suspect
+window.
+
+## Interpretation rules — where wrong diagnoses actually come from
+
+- 🔴 **An empty metric result is "no signal", never "healthy".** Zero datapoints
+  means **no invocations in the window** — the function was not exercised, so the
+  metric says nothing about whether it works. Report it as no signal and go find
+  a window with traffic. This is the same rule the `post-deploy-verify` skill
+  states, and for the same reason: a vacuous pass is worse than a missing one,
+  because it gets believed.
+- 🔴 **`StackStatus: UPDATE_COMPLETE` is stale evidence.** It persists from the
+  previous deploy, so it is true of a stack whose latest deploy failed. The
+  authoritative signals are the **deploy job's conclusion**
+  (`gh run list --workflow deploy`) and the stack's `LastUpdatedTime` freshness.
+- **DNS and asset-upload failures are infrastructure flakes, not code
+  regressions.** A deploy that died at asset publish or checkout tells you nothing
+  about the change. Your own read-only calls can hit the same flake — a failed
+  probe is `unknown`, not a finding.
+- **Never work around the profile's denials — that is the point of the profile.**
+  Needing a decrypt, a secret or a mutation means the investigation has reached
+  its boundary: escalate to the human with what you found
+  (`.claude/rules/autonomy.md`, "Escalation format").
+
+## What to hand back
+
+What was observed (verbatim, not summarised), which window, which signals were
+**unavailable** and why, the current hypothesis, and the narrowest reproduction.
+A read-only investigation that ends in a named uncertainty is a good outcome; one
+that ends in a confident story built on a stale read is not.

package/templates/agent-os/universal/.claude/agents/code-reviewer.md

@@ -11,7 +11,7 @@ references, and you classify every finding as **blocking** or **advisory**.
 
 1. **Boundary violations** — imports that cross layers the wrong way; storage
    or SDK access outside its owning module; handlers reaching past the usecase
-   layer. See `.claude/rules/architecture.md`.
+   layer. See the architecture rules in `.claude/rules/`.
 2. **Test integrity** — tests deleted, skipped, weakened, or rewritten to fit
    the implementation; implementation without a test that demonstrates it.
 3. **Error handling** — swallowed errors, bare catch-and-continue, failure

package/templates/agent-os/universal/.claude/hooks/block-no-verify.mjs

@@ -4,6 +4,14 @@
 //
 // Contract (Claude Code): JSON on stdin; exit 0 = allow, exit 2 = block, and
 // stderr is shown to the agent as the reason.
+//
+// Stated limit: it strips QUOTED text so prose about the flag is not a bypass,
+// but it does not parse heredocs. Writing `git commit -nm …` inside a heredoc
+// body — a doc, a test fixture, a PR description — is therefore blocked. That
+// happened while writing this hook's own tests. The fix is not to teach this file
+// to tokenise: it owns exactly one invariant and stays readable because of it
+// (see .claude/rules/invariants.md, "One invariant per hook"). Use a file rather
+// than a heredoc, or quote the example.
 import { readFileSync } from 'node:fs';
 
 function main() {
@@ -26,8 +34,10 @@ function main() {
     const [segment, verb] = match;
     const bypasses =
       /(^|\s)--no-verify\b/.test(segment) ||
-      // -n is --no-verify for commit only (for push it means --dry-run).
-      (verb === 'commit' && /(^|\s)-n\b/.test(segment));
+      // `-n` is --no-verify for commit only (for push it means --dry-run), and it
+      // counts inside a COMBINED cluster: `git commit -nm "msg"` bypassed the
+      // pre-commit gate outright, which is the one thing this hook exists to stop.
+      (verb === 'commit' && /(^|\s)-[a-zA-Z]*n[a-zA-Z]*(\s|$)/.test(segment));
     if (bypasses) {
       process.stderr.write(
         'BLOCKED — bypassing pre-commit checks is never allowed. ' +