create-agent-rig 0.1.0 → 0.3.0

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

@@ -42,12 +42,72 @@ 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"). 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.
-- **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; `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. 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.
+
+## 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
+packages/db/src/
+.claude/
+.github/workflows/
+```
+
+`.claude/` and `.github/workflows/` 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. `packages/db/src/` is the one the generated shape
+has.
+
+**They are a seed, not a law — the list is yours to extend.** It is what every
+generated shape has; a real project accumulates more (auth handlers, billing, a
+credentials module, a migration directory). Add a path the same day you add the
+code, because the gap between the two is exactly the window in which a change
+slips through unreviewed.
+
+The declaration is **composed, not centralised**: the sweep unions this block with
+every `elevated-paths` block in `.claude/rules/`, so a stack layer declares the
+paths that only exist in its shape. A gate declared over a directory this project
+does not have would report "clean" while looking nowhere.
+
+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
 

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

@@ -0,0 +1,53 @@
+# __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
+
+Newest first, date-free — order carries the sequence. Prune freely: this is
+operational memory, not an archive. An unattended run writes an entry at every
+stop **and** at checkpoints along the way, because a run that dies unexpectedly
+must not take its history with it.
+
+The fields exist so an entry can be visibly **incomplete**. A journal with no
+stated shape decays into a diary that reads fine and proves nothing.
+
+<!-- Template — copy the block, drop the fields that do not apply:
+
+### <one-line summary of the session>
+
+- **done** — what landed, one line each, with the PR reference
+- **escalated** — what stopped, and the diagnosis: what failed, what was tried,
+  the current hypothesis, and the one question whose answer unblocks it
+- **reviewed** — changes that went through a reviewer gate, and what it returned
+- **stopped at** — which stop condition ended the session (or "checkpoint,
+  still running")
+- **queue hygiene** — queue items fixed in passing: stale state, a dependency
+  that was already satisfied, an item that describes work already done
+- **cost** — the counts the session actually observed: reviewer subagents run,
+  CI runs consumed (re-runs included — the cheapest signal that a task fought
+  its tests), deploys triggered
+
+     A field the session cannot observe stays **visibly empty — never estimated**.
+     A plausible number will be believed, by the next reader and by the next run
+     reasoning about its own budget. Leave the gap; it is information.
+-->

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

@@ -0,0 +1,40 @@
+{
+  "process": [
+    ".claude/rules/workflow.md",
+    ".claude/rules/autonomy.md",
+    ".claude/rules/invariants.md",
+    ".claude/skills/new-invariant/SKILL.md",
+    ".claude/skills/new-invariant/guard-invariant.example.mjs",
+    ".claude/skills/new-invariant/guard-invariant.example.test.mjs",
+    ".claude/agents/test-writer.md",
+    ".claude/agents/code-reviewer.md",
+    ".claude/agents/security-scanner.md",
+    ".claude/hooks/block-no-verify.mjs",
+    ".claude/hooks/guard-bash.mjs",
+    ".claude/hooks/gate-stop-dod.mjs",
+    ".claude/hooks/inject-rules.mjs",
+    ".claude/skills/pr-ship/SKILL.md",
+    ".claude/skills/loop/SKILL.md",
+    ".claude/skills/worktree-task/SKILL.md",
+    ".claude/scripts/detect-missed-gate.mjs",
+    ".claude/scripts/reconcile-external-prs.mjs",
+    ".claude/scripts/stop-flag.mjs",
+    ".claude/scripts/preflight.mjs",
+    ".claude/scripts/queue/core.mjs",
+    ".claude/scripts/queue/plan-md.mjs",
+    ".claude/scripts/queue/github-issues.mjs",
+    ".claude/scripts/queue/jira.mjs",
+    ".claude/scripts/queue/index.mjs",
+    ".claude/queue.json",
+    "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/ci.yml

@@ -1,5 +1,10 @@
 name: CI
 
+# The default token is read-only for this job: CI needs nothing else, and a
+# workflow that can write is a workflow a compromised dependency can write with.
+permissions:
+  contents: read
+
 on:
   push:
   pull_request:
@@ -16,7 +21,7 @@ jobs:
         with:
           node-version: 22
           cache: pnpm
-      - run: pnpm install --no-frozen-lockfile
+      - run: pnpm install --frozen-lockfile
       - run: pnpm lint
       - run: pnpm typecheck
       - run: pnpm test

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/aws-serverless/gitignore

@@ -7,3 +7,11 @@ cdk.out/
 .next/
 out/
 next-env.d.ts
+.claude/worktrees/
+
+# secrets — never commit these
+.env
+.env.*
+!.env.example
+*.pem
+*.key

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

@@ -1,5 +1,10 @@
 name: CI
 
+# The default token is read-only for this job: CI needs nothing else, and a
+# workflow that can write is a workflow a compromised dependency can write with.
+permissions:
+  contents: read
+
 on:
   push:
   pull_request:
@@ -16,7 +21,7 @@ jobs:
         with:
           node-version: 22
           cache: pnpm
-      - run: pnpm install --no-frozen-lockfile
+      - run: pnpm install --frozen-lockfile
       - run: pnpm lint
       - run: pnpm typecheck
       - run: pnpm test

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,12 @@ var/
 .next/
 out/
 next-env.d.ts
+dist/
+.claude/worktrees/
+
+# secrets — never commit these
+.env
+.env.*
+!.env.example
+*.pem
+*.key

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);
+});