create-agent-rig 0.1.0 → 0.3.0

package/templates/agent-os/stack/aws-cdk/.claude/skills/post-deploy-verify/SKILL.md

@@ -10,24 +10,37 @@ You verify runtime health after a deploy and return a **verdict**, not a vibe.
 You are read-only: you observe, you never fix. The autonomy rules
 (`.claude/rules/autonomy.md`, "Post-deploy verification") consume your verdict.
 
+Scope yourself to what this skeleton actually provisions — one API, one worker
+with one DLQ, two CloudFormation stacks. Do not invent signals it does not have.
+
 ## Steps — evidence for each, in order
 
-1. **Stack freshness.** Confirm the deploy you are judging actually landed.
-   `UPDATE_COMPLETE` **alone is stale evidence** — it persists from the
-   previous deploy. Authoritative is the deploy run's own conclusion plus a
-   freshness check: `LastUpdatedTime` from
-   `aws cloudformation describe-stacks` must postdate the deploy you are
-   verifying. Judging a stale stack is the classic false-HEALTHY.
-2. **Smoke the route.** POST a request through the API (the README's smoke
+1. **The deploy job's conclusion — the primary, always-available signal.**
+   Start here: did the deploy job itself succeed? This exists on every project
+   from day one, before any metric has data. A failed or absent deploy job is a
+   REGRESSION on its own; a successful one is necessary but not sufficient —
+   continue.
+2. **Stack status + freshness cross-check.** `UPDATE_COMPLETE` **alone is stale
+   evidence** — it persists from the previous deploy. Confirm `LastUpdatedTime`
+   from `aws cloudformation describe-stacks` postdates the deploy you are
+   judging. A fresh-looking status on a stale stack is the classic false-HEALTHY.
+3. **Smoke the route.** POST a request through the API (the README's smoke
    command). Expect the documented success response (201 with a body).
-3. **The async path.** Confirm the worker consumed the event this smoke
+4. **The async path.** Confirm the worker consumed the event this smoke
    produced: `aws logs filter-log-events` on the worker's log group for the
    processed-marker within the last few minutes.
-4. **Queue discipline.** The DLQ is empty and its alarm is quiet:
+5. **Queue discipline.** The skeleton's DLQ is empty and its alarm is quiet:
    `aws sqs get-queue-attributes` (ApproximateNumberOfMessages = 0) and
    `aws cloudwatch describe-alarms` (state OK, not ALARM).
-5. **Error noise.** Scan both functions' recent logs for new ERROR-level
-   entries that did not exist before the deploy.
+6. **Function errors** in the window after the deploy — scan the functions'
+   recent logs for new ERROR-level entries.
+
+🔴 **A vacuous result is "no signal", not a pass.** An empty metric or an empty
+log query means *there were no invocations*, not *there were no errors*. Never
+read absence-of-data as health — report it as "no signal" and, since you could
+not verify, it counts toward REGRESSION, never toward HEALTHY. The first
+HEALTHY verdict a user sees has to mean something, or the whole mechanism loses
+its credibility exactly when it should earn it.
 
 ## Verdict — the only two answers
 

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/stack/node-ts/.claude/hooks/dod-checks.json

@@ -0,0 +1 @@
+["pnpm lint", "pnpm typecheck", "pnpm test"]

package/templates/agent-os/stack/node-ts/.claude/rules/node-ts.md

@@ -37,3 +37,21 @@ are; this file says how they are expressed in TypeScript.
   string-match messages.
 - Logs are structured JSON lines through the shared logger — no bare
   `console.log` in service code.
+
+## Confirming the merge criterion (GitHub Actions)
+
+`workflow.md` states the criterion provider-neutrally: confirm the required
+check completed **for this commit**. Here that is concrete — and it matters
+because `gh pr checks --watch` can exit successfully while checks are still
+*unregistered*, reporting a green wall that has not been built yet.
+
+Poll the check runs for the PR's head SHA and require the named check to have
+`conclusion: success`, not merely "not failing":
+
+```sh
+SHA=$(gh pr view --json headRefOid -q .headRefOid)
+gh api "repos/{owner}/{repo}/commits/$SHA/check-runs" \
+  -q '.check_runs[] | select(.name=="ci") | .conclusion'
+# must print: success   (a result set containing only a scanner is NOT done)
+```
+

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. ' +

package/templates/agent-os/universal/.claude/hooks/gate-stop-dod.mjs

@@ -0,0 +1,66 @@
+// Stop hook: the Definition of Done as a mechanical gate. The session may not
+// end while a named DoD check fails — the checklist stops being a wish.
+//
+// The stack layer supplies the checks (.claude/hooks/dod-checks.json — an
+// array of shell commands, cheap and deterministic). Universal supplies only
+// the mechanism: no config → nothing to gate.
+//
+// Anti-loop discipline (the classic Stop-hook trap):
+//   - stop_hook_active in the payload means we already blocked this stop once
+//     — never block again, or an agent that cannot go green spins forever;
+//   - a clean git tree stops instantly: nothing changed, nothing to gate;
+//   - fail open on any hook error — a crashed gate must not make the session
+//     unquittable.
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+function main() {
+  let input;
+  try {
+    input = JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return 0;
+  }
+  if (input.hook_event_name !== 'Stop' && input.hook_event_name !== 'SubagentStop') return 0;
+  if (input.stop_hook_active) return 0;
+
+  try {
+    const status = execSync('git status --porcelain', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (status.trim() === '') return 0;
+  } catch {
+    // not a git repo — run the checks anyway
+  }
+
+  let checks;
+  try {
+    checks = JSON.parse(readFileSync(new URL('./dod-checks.json', import.meta.url), 'utf8'));
+  } catch {
+    return 0;
+  }
+  if (!Array.isArray(checks) || checks.length === 0) return 0;
+
+  for (const command of checks) {
+    try {
+      execSync(command, { stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (error) {
+      const tail = String(error.stdout ?? '')
+        .split('\n')
+        .slice(-15)
+        .join('\n');
+      process.stderr.write(
+        `STOP GATED — a Definition of Done check fails: ${command}\n` +
+          (tail.trim() ? `${tail}\n` : '') +
+          `Fix the failure before ending the session. If this failure has resisted ` +
+          `repeated attempts, follow the stop rules instead: end with a written ` +
+          `diagnosis (.claude/rules/autonomy.md). This gate never fires twice in a row.\n`,
+      );
+      return 2;
+    }
+  }
+  return 0;
+}
+
+process.exit(main());