create-agent-rig 0.1.0 → 0.2.0

package/README.md

@@ -4,38 +4,66 @@ Scaffold a project that ships with an **agent operating system** — rules,
 gates, and hooks that hold the architecture mechanically, not by prose.
 
 ```sh
-npx create-agent-rig my-app
+npx create-agent-rig my-app                        # choose a target interactively
+npx create-agent-rig my-app --target node-service  # or name it up front
 ```
 
+Two coherent targets — `aws-serverless` (the default) and `node-service`. On a
+terminal the CLI prompts; in CI it wants `--target` explicitly. `--no-git`
+skips the initial baseline commit; `--no-color` (and `NO_COLOR`) plainens the
+output.
+
+Already have a repo? Install just the **process layer** into it — no
+architecture assumptions, no skeleton:
+
+```sh
+npx create-agent-rig init            # rules, gates, stop rules into the current repo
+npx create-agent-rig init --dry-run  # print the plan, write nothing
+```
+
+`init` drops in the autonomy tiers, stop rules, workflow, and the enforcement
+hooks, and refuses to clobber an existing `CLAUDE.md`.
+
 ## What you get
 
 **A system of boundaries, each held by tooling.** An agent (or a human using
-one) cannot talk its way past them:
+one) cannot talk its way past them — each guard is a pre-write scan that stops
+the normal path cold (review and tests back it; the claim is stated exactly,
+never inflated). The hooks live in `.claude/hooks/` and are wired in
+`.claude/settings.json`:
 
 - **`guard-core-purity`** — refuses any edit that puts I/O, clock, randomness,
-  or environment access into the pure domain core;
+  environment access, or a non-allowlisted import into the pure domain core;
 - **`guard-web-boundary`** — refuses `db`/service imports from the frontend;
   the web talks to the backend over HTTP only;
 - **`block-no-verify`** — refuses bypassing pre-commit checks (and knows the
-  difference between using the flag and merely mentioning it in a message).
+  difference between using the `--no-verify`/`-n` flag and merely mentioning it
+  in a message);
+- **`gate-stop-dod`** — refuses to end the session while a Definition-of-Done
+  check is red; it fails open (a missing or corrupt config never makes the
+  session unquittable) and never blocks twice in a row;
+- **`inject-rules`** — re-injects the autonomy rules at session start, so they
+  survive compaction and resumes.
 
 Around the hooks, the operating system: **autonomy tiers** (what an agent does
 alone / after review / never), **stop rules** (three strikes, flaky ≠ retry,
 session staleness), **subagent gates** (`test-writer`, `code-reviewer`,
-`security-scanner`, `cdk-diff-reviewer`), **skills** (`pr-ship` pre-merge
-gate; `post-deploy-verify` with its binary HEALTHY/REGRESSION verdict), and a
-one-page `CLAUDE.md` map a fresh session orients by.
+`security-scanner`, and `cdk-diff-reviewer` on the AWS target), **skills**
+(`pr-ship` pre-merge gate; `loop` queue driver; `post-deploy-verify` with its
+binary HEALTHY/REGRESSION verdict on the AWS target), and a one-page
+`CLAUDE.md` map a fresh session orients by.
 
 The skeleton around it is real and runnable — pure core shared by server _and_
 browser (one schema validates on both sides of the wire), a mandatory usecase
-layer, a queue with DLQ discipline, tests at every layer.
+layer (`payload → handler → usecase → model`), a queue with DLQ discipline,
+tests at every layer.
 
 ## Targets
 
-| Target           | One line                                                                                                                                  |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `aws-serverless` | DynamoDB single-table, SQS + DLQ + alarm, three Lambdas behind an HTTP API, static web via S3 + CloudFront, CDK with least-privilege IAM  |
-| `node-service`   | `node:http` server that also serves the web bundle, JSON-file store behind the same model boundary, spool-directory queue, worker process |
+| Target           | One line                                                                                                                                                                                          |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `aws-serverless` | DynamoDB single-table, SQS + DLQ + CloudWatch alarm, three Lambdas (POST/GET `/notes` behind an HTTP API, plus an SQS worker), static web on S3 + CloudFront, CDK with least-privilege IAM grants |
+| `node-service`   | `node:http` server that also serves the built web bundle, atomic JSON-file store behind the same model boundary, spool-directory queue + DLQ, worker process                                      |
 
 Coherent alternatives, not a parameterized abstraction. Flexibility is
 **subtraction**: the generated project is yours — delete what you don't need.
@@ -56,9 +84,10 @@ gets fought. If you need one of these, add it — the project is yours.
 ./demo.sh   # from a clone of this repo
 ```
 
-generate → the generated project's own gates pass → **an attempted core-purity
-violation is refused live by the hook** → the service runs, a smoke request
-travels every layer, the worker drains the queue, the DLQ stays empty:
+generates the `node-service` target → the generated project's own gates pass →
+**an attempted core-purity violation is refused live by the hook** → the
+service runs, a smoke request travels every layer, the worker drains the queue,
+the DLQ stays empty:
 
 ```
 == 3/4 an agent tries to put I/O and clock access into the pure core… ==
@@ -71,17 +100,22 @@ Move the impure part behind the usecase layer or into an adapter.
 
 ## Requirements
 
-- Node ≥ 20 (pnpm recommended for the generated workspace)
+- Node ≥ 20 (pnpm recommended for the generated workspace). The CLI itself
+  carries zero runtime dependencies — the `npx github:…`, tarball, and
+  published-package paths all work.
 
 ## How it stays honest
 
-Every template is a real project tested in place on every push; every e2e run
-generates a project cold and runs the generated project's own full checks
-(install → lint → typecheck → test → build → synth); a grep-test keeps the
-universal rules free of any provider mention; the hook-blocking behavior
-itself is under test; and a weekly lockfile-free run catches upstream breakage
-early. This repo dogfoods its own rulebook — `CLAUDE.md` and `.claude/` are
-composed from the templates, and drift fails the suite.
+Every template is a real project, installed with a frozen lockfile and run in
+place on every push. Every e2e run generates a project cold and runs the
+generated project's own checks (install → lint → typecheck → test, plus
+`cdk synth` on the AWS target); the pack-path and git-path installs are both
+under test, because that is exactly where scaffolders break. A grep-test keeps
+the universal rules free of any provider mention; the hook-blocking behavior
+itself is under test; and a weekly lockfile-free run resolves each template's
+dependencies fresh to catch upstream breakage early. This repo dogfoods its own
+rulebook — `CLAUDE.md` and `.claude/` are composed from the templates, and
+drift fails the suite.
 
 Development: `pnpm test` (full), `pnpm test:unit` (fast loop),
 `pnpm template:check` (templates in place). The plan of record is `PLAN.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agent-rig",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Scaffold a new project with an agent operating system (rules, gates, hooks) and a runnable code skeleton",
   "keywords": [
     "create",

package/packages/cli/dist/commands/create.js

@@ -67,14 +67,20 @@ export async function createProject(dirArg, options) {
 }
 const run = promisify(execFile);
 async function initGitBaseline(projectDir) {
+    // Disable git's background maintenance for these one-shot commands: a commit
+    // can otherwise fork an auto-gc / maintenance process that keeps writing to
+    // .git/objects/pack after we return — a non-deterministic tail that races any
+    // caller cleaning up the directory, and pointless work on a one-commit repo.
+    const quiet = ['-c', 'gc.auto=0', '-c', 'maintenance.auto=false'];
     try {
-        await run('git', ['init', '--quiet'], { cwd: projectDir });
-        await run('git', ['add', '-A'], { cwd: projectDir });
+        await run('git', [...quiet, 'init', '--quiet'], { cwd: projectDir });
+        await run('git', [...quiet, 'add', '-A'], { cwd: projectDir });
         // Explicit identity: the baseline must commit even where git has no
         // global user configured (fresh machines, CI). --no-verify here shields
         // the baseline from the USER'S global hooks only — the generated
         // project's own gates do not exist yet, so nothing is being bypassed.
         await run('git', [
+            ...quiet,
             '-c',
             'user.name=create-agent-rig',
             '-c',

package/packages/cli/dist/commands/init.js

@@ -0,0 +1,72 @@
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { agentOsUniversalDir } from '../templates.js';
+/** A user-facing failure: message is printed as-is, no stack trace. */
+export class InitError extends Error {
+}
+async function loadManifest() {
+    const raw = await readFile(path.join(agentOsUniversalDir(), 'layers.json'), 'utf8');
+    return JSON.parse(raw);
+}
+/**
+ * `init` installs only the PROCESS layer (hooks-and-reach brief §3/§4): rules
+ * that assume nothing about the codebase shape. Architecture rules reference
+ * `packages/core` and friends — installing them into an arbitrary repo would
+ * describe a structure that does not exist, which is worse than no rule.
+ *
+ * CLAUDE.md is the meta file we bring, but never over an existing one.
+ */
+async function processFiles(manifest) {
+    // the process layer, plus CLAUDE.md as the map (guarded separately)
+    return [...manifest.process, 'CLAUDE.md'];
+}
+async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function planInit(repoDir) {
+    const manifest = await loadManifest();
+    const files = await processFiles(manifest);
+    const conflicts = [];
+    for (const rel of files) {
+        if (await exists(path.join(repoDir, rel)))
+            conflicts.push(rel);
+    }
+    return { files: files.map((p) => ({ path: p })), conflicts };
+}
+export async function initProject(repoDir, options) {
+    const manifest = await loadManifest();
+    const files = await processFiles(manifest);
+    const universal = agentOsUniversalDir();
+    // Refuse to clobber an existing CLAUDE.md unless forced — init edits
+    // someone's working repository (brief §4, non-negotiable).
+    if (!options.force && files.includes('CLAUDE.md')) {
+        if (await exists(path.join(repoDir, 'CLAUDE.md'))) {
+            throw new InitError('This repo already has a CLAUDE.md. Refusing to overwrite it. ' +
+                'Merge the agent-os map in by hand, or re-run with --force to replace it.');
+        }
+    }
+    const written = [];
+    const skipped = [];
+    const plannedCount = files.length;
+    for (const rel of files) {
+        const dest = path.join(repoDir, rel);
+        const isForceableMeta = rel === 'CLAUDE.md';
+        if ((await exists(dest)) && !(isForceableMeta && options.force)) {
+            // never overwrite a file init did not write (a user's own copy)
+            skipped.push(rel);
+            continue;
+        }
+        if (options.dryRun)
+            continue;
+        await mkdir(path.dirname(dest), { recursive: true });
+        await writeFile(dest, await readFile(path.join(universal, rel)));
+        written.push(rel);
+    }
+    return { written, skipped, plannedCount };
+}

package/packages/cli/dist/index.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { CreateError, createProject } from './commands/create.js';
+import { InitError, initProject, planInit } from './commands/init.js';
 import { makePalette } from './lib/colors.js';
 import { promptTarget } from './lib/prompts.js';
 import { collectGovernance, renderSummary } from './lib/summary.js';
@@ -20,7 +21,11 @@ Options
   --no-git          skip git init + the pristine-template baseline commit
   --no-color        plain output (NO_COLOR is respected too)
   --version         print the version
-  -h, --help        this text`;
+  -h, --help        this text
+
+Also: create-agent-rig init [--dry-run] [--force]
+  Install the process layer (rules, gates, stop rules — no architecture
+  assumptions) into the CURRENT existing repo. Refuses to clobber CLAUDE.md.`;
 async function packageVersion() {
     // dist/index.js lives three levels under the package root — same walk as
     // the templates resolver, valid in the repo and in the published package.
@@ -28,7 +33,44 @@ async function packageVersion() {
     const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
     return pkg.version;
 }
+async function runInit(rawArgs) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: rawArgs,
+            options: { 'dry-run': { type: 'boolean' }, force: { type: 'boolean' } },
+            allowPositionals: false,
+        }));
+    }
+    catch (error) {
+        process.stderr.write(`${error.message}\n\n${USAGE}\n`);
+        return 1;
+    }
+    const cwd = process.cwd();
+    const dryRun = values['dry-run'] === true;
+    const plan = await planInit(cwd);
+    process.stdout.write(`agent-rig init — process layer into ${cwd}\n\n` +
+        plan.files.map((f) => `  + ${f.path}`).join('\n') +
+        '\n');
+    if (plan.conflicts.length > 0) {
+        process.stdout.write(`\nAlready present (kept, not overwritten):\n` +
+            plan.conflicts.map((c) => `  · ${c}`).join('\n') +
+            '\n');
+    }
+    const result = await initProject(cwd, { dryRun, force: values.force === true });
+    if (dryRun) {
+        process.stdout.write(`\nDry run — nothing written (${result.plannedCount} files planned).\n`);
+        return 0;
+    }
+    process.stdout.write(`\nInstalled ${result.written.length} files` +
+        (result.skipped.length ? `, kept ${result.skipped.length} existing` : '') +
+        '.\n');
+    return 0;
+}
 async function main() {
+    if (process.argv[2] === 'init') {
+        return runInit(process.argv.slice(3));
+    }
     let positionals;
     let values;
     try {
@@ -92,7 +134,7 @@ main()
     process.exitCode = code;
 })
     .catch((error) => {
-    if (error instanceof CreateError) {
+    if (error instanceof CreateError || error instanceof InitError) {
         process.stderr.write(`${error.message}\n`);
     }
     else {

package/packages/cli/dist/lib/copy-tree.js

@@ -16,6 +16,8 @@ export const DEFAULT_IGNORE = [
     '.next',
     'out',
     'next-env.d.ts',
+    // the init-manifest of the universal layer — tooling metadata, not payload
+    'layers.json',
 ];
 /** A file is treated as binary if its first bytes contain a NUL byte. */
 function isBinary(buffer) {

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/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/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());

package/templates/agent-os/universal/.claude/hooks/inject-rules.mjs

@@ -0,0 +1,36 @@
+// SessionStart hook: the autonomy rules survive compaction and resumes.
+//
+// Long sessions compact their context, and project rules are exactly what
+// gets dropped — an unattended run would finish the night without the tiers
+// and stop rules that were supposed to govern it. SessionStart is one of the
+// few events whose stdout is added to the context Claude sees, and it re-runs
+// on resume and after compaction (source: "resume" / "compact"), so this
+// refreshes instead of going stale.
+//
+// The injected content is deliberately STATELESS — rules, never facts about
+// the moment (mid-session injections are replayed on resume, so timestamps
+// or SHAs here would lie). And it is only the load-bearing part, not the
+// whole rulebook: CLAUDE.md is already loaded by the tool itself.
+import { readFileSync } from 'node:fs';
+
+function main() {
+  let input;
+  try {
+    input = JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return 0;
+  }
+  if (input.hook_event_name !== 'SessionStart') return 0;
+
+  try {
+    const rules = readFileSync(new URL('../rules/autonomy.md', import.meta.url), 'utf8');
+    process.stdout.write(
+      `[agent-os] Autonomy rules refresh — in force regardless of compaction:\n\n${rules}\n`,
+    );
+  } catch {
+    // no rules file — nothing to inject, never an error
+  }
+  return 0;
+}
+
+process.exit(main());

package/templates/agent-os/universal/.claude/rules/architecture.md

@@ -67,6 +67,13 @@ This is not a convention you are trusted to follow; the
 you, the answer is to move the impure part out — never to look for a way around
 the hook.
 
+Precision about the claim, so it is never overstated: the guard is a
+**best-effort text scan of each edit fragment before it lands** — an `Edit`
+shows the hook its new text, not the whole resulting file. It stops the normal
+path cold; a determined evasion is caught by the layers behind it (review and
+tests), not by the hook. A rulebook that sells enforcement must describe its
+enforcement exactly.
+
 ## Storage has exactly one owner
 
 `packages/db/` is the only place that touches the storage SDK/driver. Every

package/templates/agent-os/universal/.claude/rules/workflow.md

@@ -23,8 +23,10 @@ that reproduces the bug.
 
 ## Branches and commits
 
-- Work happens on short-lived branches off the default branch; the default
-  branch stays releasable.
+- **One task, one branch.** Every unit of work gets its own short-lived branch
+  off the default branch. **Never commit work to the default branch** — it
+  stays releasable at all times. This isolation of a unit of work is the rule;
+  it holds even before there is a remote (local branches are enough).
 - Commits are small and single-purpose; the message says *why*, not just *what*.
 
 ## Review-context isolation
@@ -36,16 +38,40 @@ subagent with a fresh context, and why the `pr-ship` gate fans reviewers out
 instead of self-checking. This isolation is load-bearing, not ceremony — do
 not "optimise" it away by reviewing in the authoring session.
 
+## PR flow
+
+This applies **once the project has a remote and CI checks** — a freshly
+generated project has neither, and until it does the branch discipline above is
+the whole of it. When they exist, a human-review change (see `autonomy.md`)
+travels one path to merge, in this order:
+
+1. **Local checks** — the full suite, lint, typecheck, all green locally first.
+   A red check is information, never something to retry until green (`autonomy.md`).
+2. **Reviewer fan-out**, by what the change touches:
+   - the `code-reviewer` agent **always**;
+   - `security-scanner` when it touches auth, secrets/configuration, input
+     parsing, file handling, or outbound calls;
+   - an infrastructure review when it touches infrastructure (the stack layer
+     names the reviewing agent for the target).
+
+   The `pr-ship` skill drives this fan-out and returns a SHIP / HOLD verdict
+   with named blockers; blocking findings are resolved, not argued with.
+3. **Merge — on an explicit, non-lazy criterion.** Do not trust a watcher
+   command that can exit before the checks have even registered. Confirm that
+   the **required** check completed successfully **for this commit** — a list
+   that is merely "not failing yet" is not a pass. The concrete command is
+   stack-specific and lives in `stack/*`; the criterion here does not name one.
+
+**Post-merge tail:** verify the deployed surface is healthy (the target's
+post-deploy verdict — `autonomy.md`), then update `PLAN.md` (close the task,
+record any follow-up in a queue). Merge is not the finish line; a healthy
+runtime and an honest plan are.
+
 ## PR policy
 
 - One concern per PR. If the description needs the word "also", split it.
-- The `pr-ship` skill is the pre-merge gate: full checks, reviewer fan-out,
-  DoD walk, and a SHIP / HOLD verdict with named blockers.
 - The PR description states: intent, what changed, how it was verified, and any
   autonomy-tier judgment calls made (see `autonomy.md`).
-- The `code-reviewer` agent runs before a PR is opened; its blocking findings
-  are resolved, not argued with. The `security-scanner` agent runs whenever the
-  change touches auth, secrets, input parsing, or outbound calls.
 - CI must be green before merge. A red check is fixed or the PR is closed —
   never merged around.
 

package/templates/agent-os/universal/.claude/settings.json

@@ -23,6 +23,26 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/gate-stop-dod.mjs\""
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/inject-rules.mjs\""
+          }
+        ]
+      }
     ]
   }
 }

package/templates/agent-os/universal/.claude/skills/loop/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: loop
+description: The unattended work driver. Runs the Agent queue from PLAN.md task by task under the autonomy rules, journals progress, and ends the session when the queue is empty — never inventing work.
+argument-hint: [max-tasks]
+---
+
+You drive an unattended session. Work comes from one place only: the **Agent
+queue** in `PLAN.md`. The autonomy tiers and stop rules
+(`.claude/rules/autonomy.md`) govern every step; this skill adds the
+loop-level protocol around them.
+
+## The loop
+
+1. **Read `PLAN.md`.** If the Agent queue is empty → write a journal line
+   ("queue empty, session ended") and **end the session. Do not invent work:**
+   no unbidden refactors, no speculative polish, no "improvements". An empty
+   queue is a completed state, not a vacuum to fill.
+2. **Take the top task.** Judge its tier first: Tier 2 territory → move it to
+   the **Operator queue** with a short plan (what, why, risk, rollback) and
+   take the next task instead.
+3. **Do the work** under the standing rules: failing test first, gates before
+   any PR (`pr-ship`), boundaries enforced by the hooks.
+4. **Close the task:** remove it from the queue, add one journal line (what
+   moved, what it touched, any follow-up created — follow-ups go into a
+   queue, never into ad-hoc scope creep).
+5. Repeat from 1, within `max-tasks` if given.
+
+## Loop-level stop conditions (distinct from per-task ones)
+
+Stop the session — with the journal updated and a short diagnosis — when:
+
+- the Agent queue is empty (the normal, successful end);
+- **two consecutive tasks** ended in a per-task stop (N-strike, invariant
+  conflict, surprise scope) — the queue itself is probably mis-scoped; that
+  is operator information, not something to push through;
+- your context has degraded or files changed under you (the session-staleness
+  rule): write the summary, end, let a fresh session continue;
+- `max-tasks` is reached.
+
+## Journal discipline
+
+One line per event in the `Journal` section of `PLAN.md`, newest first,
+**stateless in form** (no timestamps needed — order carries the sequence).
+Prune freely: the journal is operational memory, not an archive that only
+grows.

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

@@ -42,12 +42,22 @@ them all; they are one rulebook.
 
 - **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").
 - **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.
-- **Enforcement is mechanical.** `guard-core-purity` refuses impure edits to
-  the core; `block-no-verify` refuses pre-commit bypasses. If a hook blocks
-  you, fix the cause; never route around a hook.
+  are resolved, not argued with. The `pr-ship` skill drives the gate.
+- **Enforcement is mechanical.** `guard-core-purity` catches an impure edit to
+  the core the moment it lands; `guard-web-boundary` keeps the frontend off the
+  backend; `block-no-verify` refuses pre-commit bypasses; `gate-stop-dod`
+  refuses to end the session while a Definition-of-Done check fails. If a hook
+  blocks you, fix the cause; never route around a hook.
+- **Work comes from the queue.** The Agent queue in `PLAN.md` is where
+  autonomous work is picked up (the `loop` skill drives it); an empty queue
+  ends the session — it is never a cue to invent work.
 
 ## Foot-guns
 

package/templates/agent-os/universal/PLAN.md

@@ -0,0 +1,27 @@
+# __PROJECT_NAME__ — plan and work queues
+
+Work in this project has a stated origin: one of the two queues below. An
+agent session picks from the **Agent queue** (see the `loop` skill); anything
+that needs a human decision waits in the **Operator queue**. An empty Agent
+queue means the session ends — it is never an invitation to improvise.
+
+Keep entries one line each, most valuable first. Delete done items — the
+journal records history; the queues state only what is next.
+
+## Agent queue
+
+<!-- Tasks an agent may pick up autonomously (Tier 0/1 — see
+     .claude/rules/autonomy.md). One line each, e.g.:
+- add a GET /notes/:id route through every layer (TDD)
+-->
+
+## Operator queue
+
+<!-- Decisions and Tier-2 work waiting on a human. State what is needed, e.g.:
+- decide: retention policy before real data (RemovalPolicy flip)
+-->
+
+## Journal
+
+<!-- One line per session, newest first: date-free, what moved, what blocked.
+     Prune freely — this is an operational log, not an archive. -->

package/templates/agent-os/universal/layers.json

@@ -0,0 +1,21 @@
+{
+  "process": [
+    ".claude/rules/workflow.md",
+    ".claude/rules/autonomy.md",
+    ".claude/agents/test-writer.md",
+    ".claude/agents/code-reviewer.md",
+    ".claude/agents/security-scanner.md",
+    ".claude/hooks/block-no-verify.mjs",
+    ".claude/hooks/gate-stop-dod.mjs",
+    ".claude/hooks/inject-rules.mjs",
+    ".claude/skills/pr-ship/SKILL.md",
+    ".claude/skills/loop/SKILL.md",
+    "PLAN.md"
+  ],
+  "architecture": [
+    ".claude/rules/architecture.md",
+    ".claude/hooks/guard-core-purity.mjs",
+    ".claude/hooks/guard-web-boundary.mjs"
+  ],
+  "meta": [".claude/settings.json", "CLAUDE.md"]
+}

package/templates/skeleton/aws-serverless/.github/workflows/deploy.yml

@@ -0,0 +1,57 @@
+name: Deploy (dev)
+
+# DEV deployment only. Production is a HUMAN step (see README) — the Never tier
+# (.claude/rules/autonomy.md) forbids an agent from triggering a production
+# deploy, so no production path exists in this workflow at all.
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+
+permissions:
+  # OIDC: assume a short-lived federated role. No long-lived keys in secrets —
+  # a starter multiplies whatever it ships, so it ships zero static credentials.
+  id-token: write
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Degrade cleanly: with no configured role this SKIPS with a message and
+      # the job stays green — never a red X on a fresh project with no cloud
+      # account. Enabling deployment is "add the AWS_DEPLOY_ROLE_ARN secret",
+      # not "edit this file".
+      - id: guard
+        env:
+          ROLE: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+        run: |
+          if [ -z "$ROLE" ]; then
+            echo "deploy skipped: no credentials configured — see README (Deploy)."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - if: steps.guard.outputs.skip != 'true'
+        uses: pnpm/action-setup@v4
+      - if: steps.guard.outputs.skip != 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - if: steps.guard.outputs.skip != 'true'
+        run: pnpm install --frozen-lockfile
+      - if: steps.guard.outputs.skip != 'true'
+        run: pnpm build:web
+        env:
+          NEXT_PUBLIC_API_URL: ${{ vars.API_URL }}
+
+      - if: steps.guard.outputs.skip != 'true'
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+          aws-region: ${{ vars.AWS_REGION || '__REGION__' }}
+
+      - if: steps.guard.outputs.skip != 'true'
+        run: pnpm --filter @app/infra exec cdk deploy AppStack WebStack --require-approval never

package/templates/skeleton/aws-serverless/README.md

@@ -36,20 +36,41 @@ pnpm check       # all of the above
 
 ## Deploy it
 
+### Dev — automated, on push (OIDC, no static keys)
+
+`.github/workflows/deploy.yml` runs a **dev** deploy on every push to the
+default branch. It ships with **no credentials**, so on a fresh repo it skips
+cleanly with a message — never a red X. To enable it, you *add a secret*, you
+do not edit the workflow:
+
+1. In AWS, create an IAM role your repo can assume via GitHub's OIDC provider
+   (`token.actions.githubusercontent.com`) — a short-lived federated role, no
+   long-lived access keys anywhere.
+2. Add its ARN as the repository secret **`AWS_DEPLOY_ROLE_ARN`** (and,
+   optionally, repo variables `AWS_REGION` and `API_URL`).
+
+The workflow then assumes the role, builds the web bundle, and runs
+`cdk deploy AppStack WebStack`. The web bundle is served from S3 + CloudFront
+(the `WebUrl` output).
+
+### Local / manual
+
 ```sh
 # needs AWS credentials; region comes from your profile (generator default: __REGION__)
 cd infra
 npx cdk bootstrap   # first time per account/region
-npx cdk deploy AppStack
-
-# the web bundle: build against the deployed API, then sync to the web stack
-cd ..
-NEXT_PUBLIC_API_URL=<ApiUrl output> pnpm build:web
-cd infra && npx cdk deploy WebStack
+npx cdk deploy AppStack WebStack
 aws s3 sync ../apps/web/out "s3://<WebBucketName output>"
-# the site is at the WebUrl output
 ```
 
+### Production — a human step, on purpose
+
+There is **no production deploy in this repo**, by design: the agent operating
+system's Never tier forbids an agent from triggering a production deploy, so
+shipping an automated prod path would contradict the rules on day one.
+Promote to production yourself — a separate account/role, a reviewed change,
+your own approval — reusing the dev workflow's OIDC pattern.
+
 ## Verify runtime health (CI-green ≠ runtime-healthy)
 
 After every deploy:

package/templates/skeleton/node-service/.github/workflows/deploy.yml

@@ -0,0 +1,29 @@
+name: Build artifact
+
+# node-service ships NO deploy destination — a container registry, a VPS, a
+# PaaS is the project owner's choice, not the starter's. This builds a runnable
+# artifact (dist/) and stops short of delivery: it produces something real,
+# then leaves shipping to you. Production is a HUMAN step (see README).
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+
+jobs:
+  build-artifact:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build:web
+      - run: pnpm build:artifact
+      - uses: actions/upload-artifact@v4
+        with:
+          name: server-bundle
+          path: dist/
+      - run: echo "Artifact built (dist/). Deploy destination is your choice — see README (Deploy)."

package/templates/skeleton/node-service/README.md

@@ -45,7 +45,27 @@ Open http://localhost:3000/ — the form validates with the same core schema
 the server applies again on POST.
 
 Configuration is environment-first (`PORT`, `DATA_DIR`, `QUEUE_DIR`, `DLQ_DIR`,
-`POLL_INTERVAL_MS`) with working defaults — see each service's `main.ts`.
+`POLL_INTERVAL_MS`, `STATIC_DIR`) with working defaults — see each service's
+`main.ts`.
+
+## Deploy it
+
+This target ships **no deploy destination** — a container registry, a VPS, a
+PaaS is your choice, not the starter's. What it ships is a **build that
+produces a runnable artifact** and stops there:
+
+```sh
+pnpm build:artifact                       # → dist/server.mjs + dist/public/
+STATIC_DIR=dist/public node dist/server.mjs   # run the artifact anywhere Node runs
+```
+
+`.github/workflows/deploy.yml` runs this on every push and uploads `dist/` as a
+build artifact — it produces something real and delivers it nowhere. Point it
+at your host of choice (add a `docker build`, an `scp`, a PaaS deploy step).
+
+**Production is a human step, on purpose.** The agent operating system's Never
+tier forbids an agent from triggering a production deploy, so no automated prod
+path ships here — promoting the artifact to production is your reviewed action.
 
 ## Verify runtime health (CI-green ≠ runtime-healthy)
 

package/templates/skeleton/node-service/gitignore

@@ -7,3 +7,4 @@ var/
 .next/
 out/
 next-env.d.ts
+dist/

package/templates/skeleton/node-service/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@app/root",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": true,
   "type": "module",
   "engines": {
@@ -11,13 +11,15 @@
     "lint": "eslint .",
     "typecheck": "tsc -p tsconfig.json && tsc -p apps/web/tsconfig.json",
     "build:web": "pnpm --filter @app/web build",
+    "build:artifact": "pnpm build:web && node scripts/build-artifact.mjs",
     "start:api": "pnpm --filter @app/api start",
     "start:worker": "pnpm --filter @app/worker start",
-    "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm build:web"
+    "check": "pnpm lint && pnpm typecheck && pnpm build:artifact && pnpm test"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^26.1.1",
+    "esbuild": "^0.28.1",
     "eslint": "^10.7.0",
     "globals": "^17.7.0",
     "tsx": "^4.23.1",

package/templates/skeleton/node-service/pnpm-lock.yaml

@@ -14,6 +14,9 @@ importers:
       '@types/node':
         specifier: ^26.1.1
         version: 26.1.1
+      esbuild:
+        specifier: ^0.28.1
+        version: 0.28.1
       eslint:
         specifier: ^10.7.0
         version: 10.7.0

package/templates/skeleton/node-service/scripts/build-artifact.mjs

@@ -0,0 +1,34 @@
+// Builds the deployable artifact: a bundled server plus the web public dir,
+// into dist/. It produces a real, runnable thing — it does not ship it
+// anywhere. Run it: STATIC_DIR=dist/public node dist/server.mjs
+import { build } from 'esbuild';
+import { cp, mkdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const dist = path.join(root, 'dist');
+
+await rm(dist, { recursive: true, force: true });
+await mkdir(dist, { recursive: true });
+
+await build({
+  entryPoints: [path.join(root, 'services', 'api', 'src', 'main.ts')],
+  outfile: path.join(dist, 'server.mjs'),
+  bundle: true,
+  platform: 'node',
+  format: 'esm',
+  target: 'node22',
+  // ESM-on-node output may reference require() from a dependency — shim it.
+  banner: {
+    js: "import { createRequire as __cr } from 'node:module'; const require = __cr(import.meta.url);",
+  },
+});
+
+// The built web bundle, if present (pnpm build:web). Served via STATIC_DIR.
+await cp(path.join(root, 'apps', 'web', 'out'), path.join(dist, 'public'), {
+  recursive: true,
+}).catch(() => {});
+
+console.log('artifact built: dist/server.mjs (+ dist/public if the web was built).');
+console.log('run it: STATIC_DIR=dist/public node dist/server.mjs');

package/templates/skeleton/node-service/services/api/test/artifact.test.ts

@@ -0,0 +1,93 @@
+// CD brief §2: node-service's deployable artifact must actually build and run.
+// This bundles the server, boots the bundle over a real socket, and closes the
+// path — proving the artifact is genuine, not a stub.
+import { execFile, spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import type { AddressInfo } from 'node:net';
+import { createServer } from 'node:net';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+const exec = promisify(execFile);
+const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const dist = path.join(projectRoot, 'dist');
+
+function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.listen(0, () => {
+      const { port } = srv.address() as AddressInfo;
+      srv.close(() => resolve(port));
+    });
+    srv.on('error', reject);
+  });
+}
+
+describe('deployable artifact (dist/)', () => {
+  let child: ReturnType<typeof spawn> | undefined;
+  let work: string;
+
+  beforeAll(async () => {
+    work = await mkdtemp(path.join(tmpdir(), 'artifact-'));
+    // `pnpm check` builds the artifact before tests; build it here only if a
+    // bare `pnpm test` run left no dist to boot.
+    const built = await stat(path.join(dist, 'server.mjs')).then(
+      () => true,
+      () => false,
+    );
+    if (!built) await exec('pnpm', ['build:artifact'], { cwd: projectRoot });
+  }, 180_000);
+
+  afterAll(async () => {
+    child?.kill();
+    await rm(work, { recursive: true, force: true });
+  });
+
+  it('produces a bundled server and the web public dir', async () => {
+    expect((await stat(path.join(dist, 'server.mjs'))).size).toBeGreaterThan(1000);
+    await expect(readFile(path.join(dist, 'public', 'index.html'), 'utf8')).resolves.toContain(
+      '<',
+    );
+  });
+
+  it('the bundle boots and serves the full request path', async () => {
+    const port = await freePort();
+    child = spawn(process.execPath, [path.join(dist, 'server.mjs')], {
+      env: {
+        ...process.env,
+        PORT: String(port),
+        DATA_DIR: path.join(work, 'data'),
+        QUEUE_DIR: path.join(work, 'queue'),
+        STATIC_DIR: path.join(dist, 'public'),
+      },
+      stdio: 'ignore',
+    });
+
+    const base = `http://127.0.0.1:${port}`;
+    // wait for readiness
+    for (let i = 0; i < 50; i++) {
+      try {
+        await fetch(base + '/notes');
+        break;
+      } catch {
+        await new Promise((r) => setTimeout(r, 100));
+      }
+    }
+
+    const created = await fetch(base + '/notes', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ title: 'artifact proof' }),
+    });
+    expect(created.status).toBe(201);
+    const listed = (await (await fetch(base + '/notes')).json()) as { notes: unknown[] };
+    expect(listed.notes).toHaveLength(1);
+    // the bundle also serves the web shell
+    const root = await fetch(base + '/');
+    expect(root.status).toBe(200);
+    expect(root.headers.get('content-type')).toContain('text/html');
+  }, 30_000);
+});