create-agent-rig 0.1.0

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

@@ -0,0 +1,62 @@
+# Workflow — TDD, branches, PR policy, Definition of Done
+
+## TDD is the default motion
+
+Red → Green → Refactor, in that order, every time:
+
+1. **Red** — write the test that describes the behavior; run it; watch it fail.
+   Use the `test-writer` agent for this step: it writes the failing test and is
+   scoped so it cannot "helpfully" write the implementation too.
+2. **Green** — the minimum implementation that makes the test pass.
+3. **Refactor** — clean up with the tests staying green.
+
+No implementation before its failing test exists. A bug fix starts with a test
+that reproduces the bug.
+
+## Tests are load-bearing
+
+- Never delete, skip, or weaken a test to make a run green.
+- A flaky test is a defect to investigate, **not** a thing to re-run until it
+  passes (see stop rules in `autonomy.md`).
+- Fast checks run pre-commit; the full suite runs in CI. Bypassing pre-commit
+  (`--no-verify`) is refused by a hook — fix the failure instead.
+
+## Branches and commits
+
+- Work happens on short-lived branches off the default branch; the default
+  branch stays releasable.
+- Commits are small and single-purpose; the message says *why*, not just *what*.
+
+## Review-context isolation
+
+The session that wrote the code is measurably worse at reviewing it: it
+carries its own reasoning in context and will not challenge its own decisions
+the way a cold reader does. That is *why* `code-reviewer` is a separate
+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 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.
+
+## Definition of Done
+
+A change is done when **all** of these hold:
+
+- [ ] A test written first demonstrates the new behavior (and failed before the change)
+- [ ] The full test suite is green — nothing skipped, nothing weakened
+- [ ] Lint and typecheck are clean
+- [ ] Layer boundaries respected (no new cross-layer imports; core still pure)
+- [ ] No secrets, credentials, or personal data in code, config, or fixtures
+- [ ] Docs touched by the change (README, rules) are updated
+- [ ] The autonomy tier of the change was checked and honored (`autonomy.md`)

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

@@ -0,0 +1,28 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-core-purity.mjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-web-boundary.mjs\""
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/block-no-verify.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,53 @@
+---
+name: pr-ship
+description: The pre-merge gate. MUST run before a PR is opened or merged — runs the full check suite, fans out the reviewer gates, walks the DoD, and returns a SHIP / HOLD verdict with named blockers.
+allowed-tools: Read, Grep, Glob, Bash, Task
+argument-hint: [branch-or-pr]
+---
+
+You are the last gate before a change ships. You verify and report; you do not
+fix — a HOLD goes back to the author (usually the main session) with named
+blockers.
+
+## Steps
+
+1. **The diff first.** Establish what is actually shipping: fetch, then diff
+   against the **remote** default branch (`origin/<default>`), not a local
+   copy that may be behind — diagnosing from stale local code produces
+   confidently-wrong reviews. Everything below is scoped to this diff.
+2. **The project's own checks.** Run the full check suite the project defines
+   (see its README / package scripts). Any failure is an instant HOLD — never
+   argue with a red check, never rerun flakiness to green
+   (`.claude/rules/workflow.md`).
+3. **Reviewer fan-out.** Launch the `code-reviewer` agent on the diff — always.
+   Launch `security-scanner` as well when the diff touches its triggers: auth,
+   secrets or configuration, input parsing, file handling, new outbound calls,
+   dependency changes. Run them as subagents, in parallel — a fresh context
+   reviews better than the session that wrote the code (see
+   `.claude/rules/workflow.md`, "Review-context isolation").
+4. **DoD walk.** Check the Definition of Done list in
+   `.claude/rules/workflow.md` item by item — test-first evidence, nothing
+   skipped or weakened, boundaries respected, docs updated, autonomy tier
+   honored.
+5. **Named checks only.** The merge criterion is the project's *named* required
+   checks, all green. "Some checks passed" is not a criterion; an unnamed
+   green wall hides a red brick. Two traps here, both observed in the wild:
+   status watchers can exit while checks are **still unregistered** — poll the
+   head SHA's check runs and require each expected check *by name*; and a
+   result list containing only a scanner (no build, no tests) is **not** done,
+   it is a check set that has not arrived yet.
+
+## Verdict
+
+- `VERDICT: SHIP` — checks green, no blocking findings, DoD holds. Say so
+  explicitly; a clean gate is a real result.
+- `VERDICT: HOLD` — list every blocker: the failing check by name, the
+  reviewer finding with its file:line, or the DoD item that does not hold.
+  Blocking findings are resolved, not argued with; after fixes, the gate runs
+  again from step 1.
+
+## Boundaries
+
+- You never merge, push, or edit files — you gate. The merge itself stays with
+  whoever holds that authority under `.claude/rules/autonomy.md`.
+- One verdict per run. No "SHIP if you feel the tests are probably fine".

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

@@ -0,0 +1,62 @@
+# __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 project 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.
+
+This project 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.
+
+## If you read only four 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. **The request path** — the mandatory usecase layer and the pure core:
+   `.claude/rules/architecture.md`
+4. **Definition of Done** — the checklist a change must pass:
+   `.claude/rules/workflow.md` ("Definition of Done")
+
+## The map
+
+```
+packages/core/    pure domain logic — schemas + functions; no I/O, no clock,
+                  no randomness, no environment (hook-enforced)
+packages/shared/  logger, env loading, typed errors — cross-cutting, no domain
+packages/db/      the ONLY module that touches the storage SDK/driver
+services/         entrypoints; every request: payload → handler → usecase → model
+apps/web/         the frontend; imports core + shared ONLY, talks to services
+                  over HTTP (hook-enforced)
+```
+
+The target-specific details (how to run, deploy, and verify runtime health)
+live in `README.md`. Alongside the universal rules, `.claude/rules/` carries
+the stack-specific conventions composed in for this project's target — read
+them all; they are one rulebook.
+
+## How work happens here
+
+- **TDD, without exception.** The failing test comes first — use the
+  `test-writer` agent for it. See `.claude/rules/workflow.md`.
+- **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.
+
+## Foot-guns
+
+- Don't "simplify" a handler by calling a model directly — the usecase layer is
+  mandatory even when it looks like ceremony.
+- Don't inline `Date.now()`/randomness into the core "just this once" — inject
+  them; the hook will refuse anyway.
+- Don't weaken a failing test to get green — a red check is information, and
+  test integrity is a blocking review finding.
+- After a deploy, CI-green ≠ runtime-healthy: verify per the README, and on
+  regression revert first (`.claude/rules/autonomy.md`, "Post-deploy
+  verification").

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

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 11
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --no-frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm typecheck
+      - run: pnpm test
+      - run: pnpm synth

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

@@ -0,0 +1,78 @@
+# __PROJECT_NAME__
+
+A serverless notes service generated by `create-agent-rig`, target
+`aws-serverless`. It is deliberately the **smallest project that proves the
+architecture** — one HTTP route, one queue consumer — with every layer visible
+and every gate wired. This project is yours: **delete what you don't need.**
+
+## Layout
+
+```
+packages/core/     pure domain: zod schemas + createNote()  (no I/O — hook-enforced)
+packages/shared/   logger, loadEnv(zod), typed errors
+packages/db/       NoteModel — the only code touching the DynamoDB SDK
+services/api/      POST /notes + GET /notes: payload → handler → usecase → model
+services/worker/   note.created consumer (batchSize 1 → DLQ after 3 strikes)
+apps/web/          static Next export; validates with the SAME core schema the
+                   server trusts (imports core+shared only — hook-enforced)
+infra/             CDK stacks: table, queue+DLQ+alarm, three lambdas, HTTP API,
+                   and S3+CloudFront for the web bundle
+.claude/           the agent operating system: rules, gates, blocking hooks
+```
+
+The agent-facing map is `CLAUDE.md`; the rules live in `.claude/rules/`.
+
+## Run it
+
+```sh
+pnpm install
+pnpm test        # every layer, core exhaustively
+pnpm lint
+pnpm typecheck
+pnpm build:web   # static Next export → apps/web/out
+pnpm synth       # CloudFormation synth (no AWS credentials needed)
+pnpm check       # all of the above
+```
+
+## Deploy it
+
+```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
+aws s3 sync ../apps/web/out "s3://<WebBucketName output>"
+# the site is at the WebUrl output
+```
+
+## Verify runtime health (CI-green ≠ runtime-healthy)
+
+After every deploy:
+
+```sh
+curl -s -X POST "$API_URL/notes" \
+  -H 'content-type: application/json' \
+  -d '{"title":"smoke test","tags":["deploy"]}'
+# expect: HTTP 201 with { "note": { … } }
+```
+
+Then confirm the pipeline: the worker logs `note.created processed`, and the
+**DLQ alarm stays quiet**. If the smoke test regresses: `npx cdk deploy` the
+previous revision (or `git revert` and redeploy) **first**, diagnose second.
+
+## Boundaries (the short version)
+
+- Every request follows `payload → handler → usecase → model`. The usecase
+  layer is mandatory even when it looks like ceremony.
+- `packages/core` is pure — the `guard-core-purity` hook refuses I/O, clock,
+  randomness, and environment access at the tool layer.
+- `packages/db` is the only module that touches the storage SDK.
+- A failing queue message is poison: it throws, SQS retries ×3, the DLQ alarm
+  fires. Never wrap the worker in a broad catch.
+
+See `.claude/rules/architecture.md` for the full rules.

package/templates/skeleton/aws-serverless/apps/web/next.config.mjs

@@ -0,0 +1,17 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // Static export: one build, no second runtime — the API server (or a CDN)
+  // serves the bundle. See README for how this target serves it.
+  output: 'export',
+  // The core ships as TypeScript source; Next transpiles it for the browser.
+  transpilePackages: ['@app/core'],
+  // The core uses NodeNext-style relative imports ("./note.js" resolving to
+  // note.ts). Turbopack cannot map that, so the build runs webpack (see the
+  // build script) with the standard extension alias.
+  webpack: (config) => {
+    config.resolve.extensionAlias = { '.js': ['.ts', '.tsx', '.js'] };
+    return config;
+  },
+};
+
+export default nextConfig;

package/templates/skeleton/aws-serverless/apps/web/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@app/web",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --port 3001 --webpack",
+    "build": "next build --webpack"
+  },
+  "dependencies": {
+    "@app/core": "workspace:*",
+    "next": "^16.2.11",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3"
+  }
+}

package/templates/skeleton/aws-serverless/apps/web/src/app/layout.tsx

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+
+// Deliberately unstyled: a starter's frontend is scaffolding, not a product.
+// Polish belongs in the mechanism (the shared validation, the boundary hook),
+// not in the pixels — replace all of this freely.
+export const metadata = {
+  title: '__PROJECT_NAME__',
+  description: 'Notes — generated by create-agent-rig',
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/templates/skeleton/aws-serverless/apps/web/src/app/page.tsx

@@ -0,0 +1,96 @@
+'use client';
+// One page, one point: the SAME domain schema validates here (instant
+// feedback) and on the server (trust). See src/lib/validate.ts.
+import { useCallback, useEffect, useState } from 'react';
+import type { Note } from '@app/core';
+import { createNote, listNotes } from '../lib/api';
+import { validateNewNote } from '../lib/validate';
+
+export default function NotesPage() {
+  const [title, setTitle] = useState('');
+  const [tags, setTags] = useState('');
+  const [issues, setIssues] = useState<string[]>([]);
+  const [notes, setNotes] = useState<Note[]>([]);
+  const [status, setStatus] = useState<string>('');
+
+  const refresh = useCallback(async () => {
+    try {
+      setNotes(await listNotes());
+      setStatus('');
+    } catch (error) {
+      setStatus(`could not load notes: ${String(error)}`);
+    }
+  }, []);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  async function onSubmit(event: React.FormEvent) {
+    event.preventDefault();
+    const input = {
+      title,
+      tags: tags
+        .split(',')
+        .map((tag) => tag.trim())
+        .filter(Boolean),
+    };
+    // Client-side: the same core schema the server will apply again.
+    const verdict = validateNewNote(input);
+    setIssues(verdict.issues);
+    if (!verdict.ok) return;
+    try {
+      await createNote(input);
+      setTitle('');
+      setTags('');
+      await refresh();
+    } catch (error) {
+      setIssues([String(error)]);
+    }
+  }
+
+  return (
+    <main>
+      <h1>Notes</h1>
+      <p>
+        The form validates with the <em>same</em> core function the server
+        trusts — one schema, both sides of the wire.
+      </p>
+
+      <form onSubmit={onSubmit}>
+        <label>
+          Title{' '}
+          <input
+            name="title"
+            value={title}
+            onChange={(event) => setTitle(event.target.value)}
+          />
+        </label>{' '}
+        <label>
+          Tags (comma-separated){' '}
+          <input name="tags" value={tags} onChange={(event) => setTags(event.target.value)} />
+        </label>{' '}
+        <button type="submit">Create</button>
+      </form>
+
+      {issues.length > 0 && (
+        <ul role="alert">
+          {issues.map((issue) => (
+            <li key={issue}>{issue}</li>
+          ))}
+        </ul>
+      )}
+      {status && <p role="status">{status}</p>}
+
+      <h2>Existing</h2>
+      <ul>
+        {notes.map((note) => (
+          <li key={note.id}>
+            <strong>{note.title}</strong> <code>{note.slug}</code>{' '}
+            <small>{note.tags.join(', ')}</small>
+          </li>
+        ))}
+      </ul>
+    </main>
+  );
+}

package/templates/skeleton/aws-serverless/apps/web/src/lib/api.ts

@@ -0,0 +1,29 @@
+// The web talks to the backend over HTTP only — never by importing it
+// (the guard-web-boundary hook refuses such imports at the tool layer).
+import type { Note } from '@app/core';
+
+// Same-origin by default (the API server serves this bundle); set
+// NEXT_PUBLIC_API_URL at build time when the API lives elsewhere.
+const base = process.env.NEXT_PUBLIC_API_URL ?? '';
+
+export async function createNote(input: { title: string; tags: string[] }): Promise<Note> {
+  const response = await fetch(`${base}/notes`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(input),
+  });
+  const body = (await response.json()) as { note?: Note; error?: string; issues?: string[] };
+  if (!response.ok || !body.note) {
+    throw new Error(body.issues?.join('; ') ?? body.error ?? `HTTP ${response.status}`);
+  }
+  return body.note;
+}
+
+export async function listNotes(): Promise<Note[]> {
+  const response = await fetch(`${base}/notes`);
+  const body = (await response.json()) as { notes?: Note[]; error?: string };
+  if (!response.ok || !body.notes) {
+    throw new Error(body.error ?? `HTTP ${response.status}`);
+  }
+  return body.notes;
+}

package/templates/skeleton/aws-serverless/apps/web/src/lib/validate.ts

@@ -0,0 +1,23 @@
+// The load-bearing import of this whole app: the browser validates with the
+// SAME schema the server trusts. Client-side for instant feedback,
+// server-side for trust — one function, two sides of the wire. This is what
+// core purity buys: `@app/core` has no I/O, so it runs anywhere.
+import { NewNoteSchema } from '@app/core';
+
+export interface ValidationResult {
+  ok: boolean;
+  issues: string[];
+}
+
+export function validateNewNote(input: unknown): ValidationResult {
+  const parsed = NewNoteSchema.safeParse(input);
+  if (parsed.success) {
+    return { ok: true, issues: [] };
+  }
+  return {
+    ok: false,
+    issues: parsed.error.issues.map(
+      (issue) => `${issue.path.join('.') || 'input'}: ${issue.message}`,
+    ),
+  };
+}

package/templates/skeleton/aws-serverless/apps/web/test/shared-validation.test.ts

@@ -0,0 +1,38 @@
+// THE load-bearing test of the frontend (web brief §5): the browser-side
+// validator and the server-side schema must be the same decision procedure.
+// No jsdom, no rendering — the boundary is the point, not the pixels.
+import { InvalidNoteError, NewNoteSchema, createNote } from '@app/core';
+import { describe, expect, it } from 'vitest';
+import { validateNewNote } from '../src/lib/validate';
+
+const identity = { id: 'n1', createdAt: '2024-01-01T00:00:00.000Z' };
+
+const CASES: Array<{ name: string; input: unknown }> = [
+  { name: 'valid minimal', input: { title: 'Hello' } },
+  { name: 'valid with tags', input: { title: 'Hello', tags: ['a', 'b'] } },
+  { name: 'empty title', input: { title: '' } },
+  { name: 'whitespace title', input: { title: '   ' } },
+  { name: 'title too long', input: { title: 'x'.repeat(201) } },
+  { name: 'too many tags', input: { title: 'T', tags: Array.from({ length: 11 }, (_, i) => `${i}`) } },
+  { name: 'empty tag', input: { title: 'T', tags: [''] } },
+  { name: 'wrong types', input: { title: 42 } },
+  { name: 'not an object', input: 'nope' },
+];
+
+describe('one schema, both sides of the wire', () => {
+  for (const { name, input } of CASES) {
+    it(`web and core agree on: ${name}`, () => {
+      const webVerdict = validateNewNote(input);
+      const coreVerdict = NewNoteSchema.safeParse(input);
+      expect(webVerdict.ok).toBe(coreVerdict.success);
+
+      // …and the domain function (used by the API usecase) agrees with both.
+      if (coreVerdict.success) {
+        expect(() => createNote(input, identity)).not.toThrow();
+      } else {
+        expect(() => createNote(input, identity)).toThrow(InvalidNoteError);
+        expect(webVerdict.issues.length).toBeGreaterThan(0);
+      }
+    });
+  }
+});

package/templates/skeleton/aws-serverless/apps/web/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "jsx": "preserve",
+    "lib": ["dom", "dom.iterable", "es2022"],
+    "noEmit": true,
+    "allowJs": true,
+    "plugins": [{ "name": "next" }]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "test/**/*.ts"],
+  "exclude": ["node_modules", "out", ".next"]
+}

package/templates/skeleton/aws-serverless/eslint.config.mjs

@@ -0,0 +1,20 @@
+import eslint from '@eslint/js';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  {
+    ignores: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/cdk.out/**',
+      '**/coverage/**',
+      '**/.next/**',
+      '**/out/**',
+      '**/next-env.d.ts',
+    ],
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  { languageOptions: { globals: globals.node } },
+);

package/templates/skeleton/aws-serverless/gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+coverage/
+cdk.out/
+*.tsbuildinfo
+.DS_Store
+.next/
+out/
+next-env.d.ts

package/templates/skeleton/aws-serverless/infra/bin/app.ts

@@ -0,0 +1,19 @@
+import { App } from 'aws-cdk-lib';
+import { AppStack } from '../lib/app-stack.js';
+import { WebStack } from '../lib/web-stack.js';
+
+const app = new App();
+
+// Region-agnostic by default; `cdk deploy` uses your CLI profile. Pin it here
+// when the project settles (the generator's default region is __REGION__).
+const env = { region: process.env.CDK_DEFAULT_REGION };
+
+new AppStack(app, 'AppStack', {
+  description: 'API + worker for __PROJECT_NAME__ (generated by create-agent-rig)',
+  env,
+});
+
+new WebStack(app, 'WebStack', {
+  description: 'Static web serving for __PROJECT_NAME__ (generated by create-agent-rig)',
+  env,
+});

package/templates/skeleton/aws-serverless/infra/cdk.json

@@ -0,0 +1,3 @@
+{
+  "app": "npx tsx bin/app.ts"
+}