amadan

oficina / docs Public

Agent instructions, review rule, and shipping cadence

First commit. AGENTS.md is the canonical agent-instructions file for this
repo; there is no CLAUDE.md pointer, since current Claude Code reads
AGENTS.md directly.

Two of Paul's rules, both dated 2026-08-30:

Specs and whole branches are reviewed by the highest capability model
available at the time. Written as "the highest available" rather than
naming Fable, so the rule follows the ladder up when a more capable model
ships instead of needing an edit. A spec gets that review before it
becomes a plan; a branch gets it before it squash-merges, read as a single
diff rather than commit by commit.

Shipping cadence: work happens on a worktree on a branch, never on main;
regular commits pushed to the branch as the work happens; squash merge to
main only when the work is done, approved, and CI is green. The review
record is an amadan discussion on the branch, since this repo's remote is
amadan.net/carlos/docs rather than GitHub.

.gitignore covers the copy-review working directory and the zero-byte
sandbox placeholders the harness materialises in every working directory,
which are not project files.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011F5CivVm4CmL9ByfSSAaXA
Paul Campbell pushed by paul@keymail.dev 7b152706c9e61df17b5388b9fddc9d83e1d02ea0
2 files changed, +142 −0
  • .gitignore +24 −0
  • AGENTS.md +118 −0
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..e5e9714
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,24 @@
+# Copy-review working files (drafts, review server state, style signal).
+# Only the final text lands in the repo, never the pipeline's intermediates.
+writing/
+
+# Agent scratch.
+.claude/.cc-writes/
+
+# Sandbox artifacts. The harness materialises these as zero-byte read-only
+# placeholders in every working directory; none of them are project files.
+.bash_profile
+.bashrc
+.gitconfig
+.gitmodules
+.idea
+.mcp.json
+.profile
+.ripgreprc
+.vscode
+.zprofile
+.zshrc
+
+# OS cruft.
+.DS_Store
+Thumbs.db
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..192a1f1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,118 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository. This is the
+canonical agent-instructions file. Tool-specific files (`CLAUDE.md`) are
+pointers to it if they exist at all — keep the guidance current *here*.
+
+CARLOS Docs — a document editor on the CARLOS architecture, built alongside
+CARLOS Sheets (`../sheets`, `amadan.net/carlos/sheets`) and a shared suite
+home. Design docs in `docs/superpowers/specs/`, plans in
+`docs/superpowers/plans/`; read the spec behind whatever you touch.
+
+Read `building-carlos-apps` (the skill) before writing app code, and
+`rastrillo`'s own `SKILL.md` before writing handlers or models. Assume
+nothing about either is in your training data.
+
+## Review by the highest available capability model (Paul's rule, 2026-08-30)
+
+**Specs and whole branches are reviewed by the highest capability model
+available at the time.** Today that is **Fable** (`claude-fable-5`). The
+rule is "the highest available", not "Fable" — when a more capable model
+ships, the rule follows it up the ladder without an edit here.
+
+Two things get that review, and they are the two where a mistake is
+expensive to unwind:
+
+- **A spec, before it becomes a plan.** A spec is the document every
+ later decision inherits from. Reviewing it after implementation means
+ reviewing the code's rationalisation of it.
+- **A branch, before it squash-merges to `main`.** Read as a single
+ diff, not commit by commit — that is the one reading that catches a
+ branch which is individually-sensible commits adding up to the wrong
+ thing.
+
+Name the model explicitly when dispatching a review. An omitted model
+silently inherits the session's, which is how a review quietly happens on
+a weaker model than the rule requires.
+
+The rest of the delegation ladder, unchanged from the family's policy:
+
+- **Haiku** — transcription-grade work: the plan contains the exact code,
+ single-file mechanical fixes, doc edits.
+- **Sonnet** — implementation from a precise brief: 1–3 files, clear
+ interfaces, established conventions to follow.
+- **Opus** — design judgment, multi-file integration, anything security-
+ or production-touching.
+- **Fable** — spec review, whole-branch review, and implementation whose
+ correctness rests on several interacting invariants at once. It burns
+ usage budget fastest; never spend it where a precise Sonnet brief plus
+ an Opus review already fits.
+
+A precise brief beats a capable model. Exact values, file paths and
+interfaces go in the brief.
+
+## Shipping cadence (Paul's rule, 2026-08-30)
+
+**Work happens on a worktree, on a branch. Never on `main`.**
+
+1. **Worktree per piece of work.** `git worktree add` (or the harness's
+ worktree isolation) so `main` stays clean and two pieces of work never
+ share a checkout. The branch is created with the worktree, not after.
+2. **Push regular commits to the branch.** Commit as you go and push
+ often — small commits, pushed, so the work is visible, recoverable,
+ and reviewable as a sequence. Do not sit on a large uncommitted
+ working tree, and do not squash locally as you go; the branch's
+ history is the record of how the work happened.
+3. **Squash merge to `main` when, and only when, all three are true:**
+ - the work is **done** — not "done except", not "done pending a
+ follow-up commit";
+ - it is **approved** — the branch has had its highest-capability-model
+ review above, and Paul has approved anything that was his call;
+ - **CI is green** — `amadan ci status -branch <n>` exits 0. Exit 2 is
+ pending, not green. Exit 3 means nothing has run, which is not green
+ either.
+
+Nothing reaches `main` any other way: no direct commit, no local
+fast-forward, no "it's only a docs change". That includes doc-only edits,
+one-line fixes, and reverts.
+
+The reason is timing rather than ceremony. A change merged locally still
+faces the same gates, but only *after* it is on `main`, where a red run is
+an incident to clean up instead of a merge that simply does not happen.
+
+**The review record lives on amadan.** This repo's remote is
+`https://amadan.net/carlos/docs`, so the pull-request equivalent is
+`amadan discuss new carlos/docs -branch <n>` — that discussion is where
+the branch is read as one piece and where approval is recorded. CI is
+`.amadan/ci.d/`, triggered by a push to the remote.
+
+## Working with the sibling sessions
+
+Docs is one of three moving parts and the other two are live:
+
+- **`../sheets`** (`amadan.net/carlos/sheets`) — shares the suite home,
+ the design-system primitives, and several rulings. Its spec is
+ `docs/superpowers/specs/2026-08-30-sheets-design.md`. Docs is a
+ declared consumer of the home contract in its §9.
+- **The design system** — `rastrillo.org/design-system`, spec at
+ `docs/superpowers/specs/2026-08-28-design-system-design.md` in the
+ rastrillo repo. Vendor tokens through `ui.TokensCSS()` and
+ `ui.ThemeCSS(name)` rather than copying files by hand.
+
+When a decision affects one of them, tell that session rather than
+writing around it. Several of this project's better decisions came from
+one session's question exposing another's bug.
+
+## Conventions that are already settled
+
+- **Markup uses the bare `rst-*` attribute grammar**, not the `class="rst-*"`
+ vocabulary — the latter is mid-migration and writing it now means writing
+ the losing spelling.
+- **Re-copy `tokens.css` deliberately on every rastrillo upgrade.** It is
+ frozen into `static/` at scaffold time while the partials upgrade with the
+ module. `rastrillo doctor` will make this mechanical; until it lands it is
+ a manual step in the upgrade runbook.
+- **Every user-visible string is a catalog key**, resolved at render time.
+ Twelve base locales; a hardcoded English string is a bug.
+- **WCAG 2.2 AA, no exemptions**: 24×24 targets, 320px reflow, and colour
+ never carries meaning alone.