An Engineering Operating System

Distilled from 750+ hours of hands-on production engineering with these agents in the loop,
compared to 150+ other skills & frameworks and used over 10 million tokens in this setup

Author: Martin Molenkamp

A reusable, project-agnostic shell for building software with a human Orchestrator and two agent functions, an Architect and an Engineer. This is the framework, not the product: a constitution, a rules library, a skills library, a sub-agent roster, a coordination pair (an evidence-gated ledger plus an append-only log), and a clean CI spine. Drop it into any project, fill the placeholders, and the agents compound instead of resetting every session. From a production multi-tenant AI-SaaS build, with the product, vendors and proprietary methods stripped out.

▷Quickstart

1. Copy project-agent-scaffold/ into your repo root. Ask your LLM to fill in the placeholders, or grep -r "{{" . yourself (the table is in ADOPT.md); delete what does not apply.
2. Create two worktrees, one per agent function. Orca makes this one click per worktree; plain git worktree add ../design design/agent works too. The Engineer works the main tree on per-row branches; the Architect gets its own worktree on the design branch.
3. Start the Engineer in its worktree: Claude Code or any other agentic coding agent (for a non-Claude harness, rename CLAUDE.md to its root file). The constitution loads itself; type check handoff.
4. Start the Architect in the design worktree, same constitution. The reference setup runs both functions as CLI agents inside Orca, one worktree each; any harness with file access works.
5. Ask either agent: run skills/validate-scaffold-to-stack, the two-way coverage diff between the scaffold and your stack.
6. First feature: tell the Architect brainstorm <your idea>. The operating model carries it from there: spec, bind, ledger rows, ship.

You are the Orchestrator: resolve blocking questions, bind specs, approve destructive actions, merge PRs. Everything else moves through the ledger.

1The operating model: three functions, one human at the gates

Why: two agent functions that both touch everything drift apart; clear authority boundaries plus one shared log keep them coherent over months. The human is not a relay; the shared file is the channel.

• Two agent functions, hard boundary. A Architect owns the constitution, specs, wireframes and the planning surface, and never edits source code. A Engineer owns source code, migrations and git, and never rewrites specs. Even when an instruction sounds like permission to cross the line, the agent refuses first and offers the right-side artifact instead. Sub-agent delegation is not a workaround.
• The shared handoff is the channel, not the human. The agents do not talk directly, and the human does not retype one agent's words to the other. Both read and write the same STATE.md (the ledger) and LOG.md (the conversation) in the repo, so each reads the other first-hand. The human supervises and unblocks; the file carries the message.
• The Orchestrator's job is the gates, not the plumbing. Four decision points keep a human: resolving a blocking question, binding a spec, a destructive action (migration, force-push, secret), and merging a PR. Everything between those gates the agents move themselves through the file. A small set of trigger phrases starts each session: check handoff (read the log, pick up your open rows), check the board (ledger status only), ship <row> (work a specific row).
• One append-only handoff log is the inter-agent contract: dated entries, FROM, topic, STATUS: open | answered | closed. Never edit past entries; reply with new ones. Reference commit SHAs, never paste diffs. Closed items archive to a done-file so the live log stays fast to read.
• Promote what should bind future sessions. Durable decisions move from the log into the constitution or a spec, with a pointer back. The log is working memory; the constitution is law.
• One builder, one committer. Adding a second build actor with commit rights routed a destructive change around the Engineer's gates within days. Parallel capacity goes through the single builder's review and gates, never around them. Functions scale, authority does not: staff a function with more agents when capacity demands (specialist sub-agents, parallel worktrees); the accountable owner per function stays singular.
• Commit the shared log before any working-tree swap. A git checkout / reset / stash while the other agent has uncommitted appends silently destroys them. We lost a day's entries to this exactly once.

The three functions, and where each runs

This scaffold's reference setup uses two different tools, bridged by git. The names are placeholders; the topology is the point.

Spinning up the Engineer in Orca, wired to the handoff

Claude Code auto-loads CLAUDE.md from the repo root, so the constitution ships as CLAUDE.md and every Orca worktree picks it up with zero setup. The wiring is four files in the repo:

# repo root, read automatically by every Claude Code agent in every worktree
CLAUDE.md                      # the constitution; first line tells the agent to read the handoff
operating-model/STATE.md       # the ledger it picks its @build rows from
.claude/commands/              # slash commands: /check-handoff  /check-board  /ship
.claude/agents/                # the specialist sub-agents invoked at gates

# the loop, per worktree:
# 1. Orca: new worktree for goal G1.2 (one node = one worktree = one branch)
# 2. in its terminal:  claude   then:  /check-handoff
# 3. agent reads the tree, claims its @build nodes, works the goal-batch
# 4. agent appends a build-side handoff entry + opens a PR  (a human gate)
# 5. you review the diff in Orca, merge; the design side reads the entry next session

The /check-handoff command is a short prompt file that says: read operating-model/STATE.md, find open rows owned by @build, pick up the lowest-numbered unblocked one and its goal-batch, reconcile against the other tree's copy before writing, and reply in the log with what you are taking. That single command is the whole "correct handoff" entry point; the constitution makes reading the handoff the first action of every session anyway.

Making context visible, and keeping dialogue two-way added

An agent's context is invisible: the human cannot see which agent is replying, whether it loaded the rules, or whether it pushed back. Two cheap conventions surface it.

Context markers. Every agent reply opens with a marker, stacked space-separated, in the chat reply only (never in committed prose, where the no-inline-emoji house style still binds). It makes the operating state scannable at a glance.

Dialogue habits. Two reflexes keep the human and the agents in dialogue rather than one dictating. "You do it": when an agent asks the human to run, test or deploy-prep something, the default answer is "you do it", the agent has broad tool access and usually finds a way, which reinforces remote-only execution. Reverse the direction: when an agent hands the human a decision, the human flips it ("show me a few options"); when the human is stuck dictating, the agent asks "what questions do you have?" instead of guessing.

2The ledger and the log: two files, two lifetimes v2.2

Why: a separate kanban file is a second source of truth that drifts. But collapsing everything into one file is the opposite failure: state buried in an archivable log gets archived, and open work disappears with it. So the split is by LIFETIME, not by topic. LOG.md is finished the moment an entry is written, so it archives. STATE.md lives until the work is done, so it never does.

• Work is a tree: Goal → Subgoal → Task → Subtask. A goal is an outcome a human would name ("the engine builds a dense radar"). Subgoals are the few moves that get there. Tasks are a single agent's unit of pickup. Subtasks are the checklist inside a task. Depth stops at four; if you need a fifth level, the goal was two goals.
• Two files, never one, never three. There is no Tasks.md. STATE.md is the ledger, the only home of open and done, edited in place and never archived. LOG.md is the append-only conversation and carries zero state. The ledger is the what and who; the log is the why. Anything a log entry announces as open lands as a ledger row in the same commit.
• Every row carries id, status, owner, ask, gate and evidence. Owners are @design, @build, @human. Statuses: open, in-progress, blocked, done. A row moves to done only when its children are done.
• Anyone creates a row, only its owner changes its status. The owner is whoever holds the primary evidence, so @build closes on a SHA, @design on a bound spec, @human on an ack. An audit by a non-owner writes its finding into the evidence field as an explicit claim and routes it; it never flips the status. The line that matters is create versus mutate, not design versus build, because appends merge cleanly and status edits collide.
• done is unwritable without primary evidence. A SHA, a run id, an applied migration, a DB read. An action log alone is secondary, and a gap in one is a logging bug, never proof that something did not happen.
• Picking up a row locks it. Claiming sets in-progress and adds a claim: <branch> @ <timestamp> token. A claimed row is read-only to everyone but the claimant: its ask, scope and children are frozen, and anyone else with something to say appends to the log referencing the row, never edits it. The claimant releases by moving to blocked (PR open) or done (merged); only @human clears a stale claim. No two agents ever edit the same work.
• Done rows carry their evidence inline. A finished task cites the SHA or artifact that closed it, so the ledger doubles as a shipped-state index without paraphrasing git.
• Closed rows are immutable. A done row is never reopened, reused or repurposed. A regression or follow-up gets a NEW row that references the closed one; pointing new work at a done row erases its audit trail and hides that the change regressed. New problem, new row.
• Blocked-class rows name the question. A blocked row states the open question and the surface it touches; if that surface is one of the five hard surfaces (§3), it gates dependent rows until resolved.
• Goal-batches, not piecemeal asks. The router hands an agent a goal or subgoal, not a scattered list of tasks. Bundling related work into one coherent pickup keeps the agent's context whole; fragmented asks fragment its flow.
• Only the log archives. Closed log entries date-cut into LOG-ARCHIVE.md as a verbatim move, never a summary, and an archive commit never touches the ledger. Completed rows stay in STATE.md: a ledger you can archive is a ledger you can lose, which is exactly how five open obligations once vanished in a cleanup.

# STATE.md  -- the ledger (edited in place, never archived)

| id     | status      | owner   | ask                          | gate            | evidence          |
| G1     | in-progress | @build  | Engine builds a dense radar  | G1.2            | -                 |
| G1.1   | done        | @build  | One database, two schemas    | shipped         | a1b2c3d PR #8     |
| G1.2   | in-progress | @build  | Recover typed discovery      | claim: feature/g1-2 @ 1410 | -      |
| G1.2.1 | done        | @build  | Port the seven channels      | shipped         | e4f5a6b, run 9f2e |
| G1.2.2 | open        | @build  | Bound the gather to 12       | G1.2.1          | -                 |
| G1.3   | blocked     | @design | Stage mechanism              | open Q: votes vs prior? touches scoring | - |

# LOG.md  -- the conversation (append-only, never edited, archivable)

### 2026-06-20-1410 - FROM: design - RE: G1.3 stage call - STATUS: open
Picking ONE stage mechanism. Leaning the prior-with-clamps path. @build, hold G1.3 children.
# this entry is OPEN, so G1.3 exists as a row above, in this same commit

The four-column board (Orca)

Orca shows each worktree with its agent's live state. The ledger's four statuses map one-to-one onto a four-column board, so the ledger and Orca read the same picture: a row's status is its column.

How the ledger stays one ledger across worktrees v2.2

Worktrees share one .git but each has its own working copy of STATE.md on its own branch. That second copy is the price of the separation that protects design work from a build-side checkout, and it has to be reconciled rather than assumed away. The convention that keeps the copies converged:

• The ledger is multi-writer but single-owner-per-row. Both sides write STATE.md; only a row's owner changes that row's status. The two sides touch different lines, so git merges them cleanly instead of colliding. An earlier version of this model made the ledger single-writer and gave the Architect no git at all, which does prevent forks but leaves uncommitted design work exposed to a build-side reset. That trade is now paid explicitly instead of silently.
• Read the other tree's copy before writing your own, and let CI prove you did. Check (d) fails a commit whose STATE.md is missing a row id the other tree has; check (e) fails a commit that changes the status of a row this agent does not own. Neither can pass until the copies are reconciled, which turns "sync first" from a habit into a precondition of committing.
• Claiming is the lock, and it is a tiny serialised edit. Set in-progress plus the claim: branch @ time token and push it before starting, so no two worktrees take the same row. The human may claim on the agent's behalf when routing.
• /check-handoff reads the ledger from the integration ref (git show {{INTEGRATION_BRANCH}}:operating-model/STATE.md), so an agent always sees the current rows and current claims, never a stale snapshot from branch time.
• The Engineer's reply is the PR: title names the row, body is the build-side entry with SHAs. At merge (the human gate) the row's owner flips it to done with the SHA cited as evidence.
• Refresh by rebasing on the integration branch (one click in Orca) to pull the latest ledger and claims.

3Specs and decisions

Why: the failure mode is code shipping against a question that was still open, then paying for a reconciliation migration.

• Spec lifecycle: Draft → Binding. Every authoring, amendment or promotion ships a paired handoff entry in the same session: the spec name, version delta, decisions baked in, and explicit asks for the Engineer. (Adopted after a spec drifted seven versions ahead of the Engineer's last acknowledgement.)
• Blocking-question discipline. Open questions touching the five hard surfaces, schema, dispatch shape, tenant isolation, billing primitives, the LLM call-site contract, are blocking-class by default. Specs on a blocked surface do not get authored; ship announcements list which blocking questions are open; the Architect refuses to acknowledge a ship that lands on a blocked surface.
• Gate reviews before binding. A spec promoting to Binding passes a systems-architecture review, a principal-engineer review (18-month consequence, simpler-shape test, incident pattern-match), and a database review (isolation, policies, migration safety), as independent passes, not self-review.
• Spec writing, six rules: state positive fact only (no DON'T-lists, no defer-to-future); each fact lives in exactly one file, others link; no diff-versus-prior-version framing in the body; no process citations in the body; visualise over prose; open questions live in a design-direction file, never in the spec.
• Reconciliation needs an impact analysis. When a blocking question resolves after dependent code shipped, the aligning migration is preceded by a written enumeration of every reference to the stale shape, acknowledged before it ships.
• The review pipeline is auto-chained v1.1. At promotion the relevant gate sub-agents run in sequence (architecture, principal-engineer, database, spec-critic, plus a security-reviewer pass when the surface is security-relevant, plus design and accessibility when the surface is customer-facing), each reading the prior pass; the pipeline auto-detects which gates apply. Only taste calls and blocking-question resolutions surface for the bind, clean passes are summarised not replayed. The human binds on the surfaced decisions, not the whole transcript.
• A dedicated security-reviewer owns the boundary lens v1.3. Architecture, principal, and database lenses each see part of the security picture, but none owns "is this trust boundary authenticated end-to-end against the threat model", which is exactly how an authenticated-dispatch envelope gets dropped when a transport changes and slips every other gate. The security-reviewer agent runs at the bind gate on any security-relevant surface (boundary, endpoint, dispatch, secret, external content to a model, authZ, tenant data), checks six things (authenticated boundaries; tenant isolation with read-visibility separated from write-authority; secrets in the store; untrusted input stays data; authZ at the call site; replay-idempotency), and reports zero-noise (every finding carries an exploit scenario and maps to an abuse case or it is hygiene). The standing goals it audits against live in SECURITY-HARDENING.md, the checklist every project's goal tree adopts. It pairs with the code-level /security-review on the diff.
• Decision guards for counter-intuitive code. A deliberate-but-wrong-looking choice (a denormalised column, a missing FK, a sync call on a hot path) gets a short // DEC-NN marker pointing at a root DECISIONS.md entry, so a later agent reads the rationale before "fixing" it. It is the one allowed exception to the no-pointers-from-code rule, because it points at a decisions log, not a design doc. Reserve it for code that looks wrong but is not; if the log grows faster than the codebase, the markers lose force.

4Git, CI and deploy expanded

Why: deploys should be boring, attributable, and never depend on someone's laptop; CI should be a small set of composable jobs anyone can read.

• Push is the deploy. A push to the production branch triggers the web deploy and the worker deploy. Production state = HEAD of that branch; verify shipped state from git log or the code itself, never from tags or prose.
• Production lives on a dedicated release branch, never the default. main is integration: CI, previews, day-to-day agent pushes. Production deploys only from release, promoted deliberately from a green main. Because agents and humans default-push to main, separating the branches means an accidental or broken push can never reach production: the default target and the production target are structurally different refs.
• CI watch-and-fix. Every push is followed by watching the run in the same session. Auto-fixable failures (lint, format, typo, missing import) get fixed and re-pushed, max two retries. Architecture-class failures (policy coverage, security headers, migration conflicts, threshold misses) escalate immediately to the human with a root-cause hypothesis and two fix paths, zero auto-retries. Flaky failures re-run once. Nothing is "shipped" until CI is green.
• CI gates are scripts, not vigilance. Every recurring review comment becomes a script, all in one gates/ folder, run as one CI job. The scaffold ships six starters: RLS-coverage (policy in the same migration), no-cron-dispatch, security-headers, no-direct-LLM-SDK (enforces the one-gateway rule), no-em-dash (house style), and event-contract (every event carries an id and a version).
• Branch protection makes push-is-the-deploy safe. The production branch requires the ci workflow green and takes no direct pushes; the integration branch requires green CI to merge. Without this, "a broken push can never reach production" is a wish, not a structural fact. This is a required adoption step, not optional.
• Commits and PRs link to the ledger row, both directions. A PR names the row it closes (row: G1.2.2); the row cites the closing SHA as its evidence when it merges. From a row you find its commits; from a commit you find its row. A PR template carries the verification checklist.
• Checkpoint the reasoning, not just the code v1.2. While working a node, the Engineer auto-commits WIP: checkpoints with a structured body, the decisions made, the work remaining, and the approaches already tried and rejected, so a crash or context reset reconstructs from them instead of re-deriving and repeating a dead end. The WIP: commits filter-squash before the PR (history and bisect stay clean); local by default, push is opt-in. The checkpoint doubles as the commit git-discipline requires before any tree swap.
• Secrets live remote only. No local execution that depends on a locally-set secret; never ask a human to paste keys into chat. One-shot jobs ship as remotely-invokable functions reading the platform secret store. This is also what makes the from-zero recovery playbook real.
• Latest stable at scaffold time. No pinning to old majors "because the spec was drafted against version X". SBOM and CVE patching assume supported versions; exceptions are documented with a reason and a bump ticket.

The clean CI spine

Five composable jobs, each a single responsibility, wired so a project swaps the inside of a job without touching the shape. Agnostic by placeholder; one filled reference per stack ships alongside. The gates job runs ten scripts as of v2.6.

# .github/workflows/ci.yml  -- integration branch, every push
jobs:
  lint:      # format + lint, zero-warning budget
  typecheck: # static types across the workspace
  test:      # unit + integration; real DB for policy negatives
  gates:     # run every script in gates/ ; one job, many checks
  build:     # compile / package ; artifact, no deploy

# .github/workflows/deploy.yml  -- production branch only
on: { push: { branches: [release] } }
jobs:
  migrate:  # apply numbered migrations via CLI (never the web editor)
  web:      # deploy the app surface
  workers:  # deploy the compute surface

# .github/workflows/scheduled.yml  -- whitelisted QA + safety-net only
# a CI gate refuses new cron decorators outside this whitelist

5Schema and data discipline

Why: multi-tenant data integrity is won or lost in the migration layer, not the app layer.

• Migrations are the only schema truth. Numbered files applied by CLI; never the web SQL editor for schema writes (reads are fine). Drift between environments starts the day you break this.
• Change live tables by expand / contract. A deploy and a migration are not atomic, so never rename or retype a column in place. Add the new alongside the old, dual-write and dual-read, backfill in a separate restartable job, then drop the old in a later migration. Each step is its own migration and deploy.
• Four layers of tenant defence: a signed job-context envelope on every queue message (HMAC over the tenant identifiers, ULID job id), then row-level security via array-returning auth helpers (col = ANY(auth_ids())), then code-path checks, then an append-only audit log. Each layer assumes the others can fail.
• Soft-delete is an RLS concern. Suppress soft-deleted entities inside the auth helper functions (parent chain included), not in per-query WHERE clauses. One place that propagates to every policy, instead of a leak waiting for the one query that forgets. Pair it with an integration-test negative: archive as service role, read as member, assert gone.
• Idempotency at three layers: run-level request ids, stage-level markers, event-level ULIDs with a processed-ledger (INSERT ... ON CONFLICT DO NOTHING in the same transaction as the effect).
• Dual writes get an outbox. Writing two systems that do not share a transaction: commit the intent rows in the same local transaction, drain after commit. Never "emit then commit".
• Counter honesty. Tallies use relative-delta updates (row locks make them concurrency-safe). Distinct-counts cannot be maintained by blind plus-or-minus one: keep a membership table or declare the counter approximate and name the reconciliation job.
• Config versioning. Behaviour-shaping configuration ships as a pinned, versioned bundle; rollback is one atomic re-pin with one audit trail; nothing is hot-edited in production. At most one active version, enforced by a partial unique index.
• Registry over enum. Extensible vocabularies (source types, job purposes, output formats) are registry tables with handler dispatch, not CHECK enums that need a migration per addition.
• History is a first-class concept, and audit history outlives the entities it audits (no cascading FK from audit rows; identifiers on audit rows are pseudonymous so retention never fights erasure).

6Events and dispatch

Why: cron-and-poll architectures rot into invisible coupling; user trust dies the first time automation edits their data.

• Event-driven, not cron. User-facing work triggers from events (user actions, state transitions), adaptive per-entity schedules (a next_x_at column), or piggybacks on natural completion events. Cron survives only as whitelisted QA jobs or documented safety-net sweepers with sunset criteria; a CI check refuses new cron decorators outside the whitelist.
• No automation writes user-curated state. Workers and background jobs write to parallel *_candidate tables (pending / attached / rejected / expired); the user explicitly attaches. CI-enforced.
• System-initiated actions default OFF. Anything the system does to a user surface unprompted ships behind a per-user opt-in. "Default on because users will want it" requires named user-research evidence.
• Integration topology first. Before any slice in a multi-service chain, name the trigger primitive that wakes the next service (pg_notify, realtime subscriptions, persistent listeners, platform schedulers), platform-native primitives over custom polling or fire-and-forget HTTP between your own services. Slice plans without a trigger-primitives section do not get acknowledged.
• Every dispatch spec answers three questions before binding: trigger pattern, user-control surface (default state + opt-in), write-target shape (direct / candidate-staged / propose-to-user / system-internal).
• Queue consumers handle failure, not just the happy path. A bounded retry with backoff, then a dead-letter queue (monitored, not an infinite redrive); poison messages recognised and DLQ'd fast with their failure reason captured; back-pressure via a max in-flight; visibility timeout sized longer than the slowest message.

7LLM engineering

Why: LLM call sites multiply; without one gateway and hard output contracts, costs, providers and prompts sprawl untracked.

• One gateway, addressed by purpose. Every LLM and search call goes through a single gateway that resolves a named purpose to a provider chain. No call site constructs a vendor SDK directly (CI-checked). Swapping providers is a registry edit, not a code change.
• Draw the agent / deterministic boundary first. Before a stage is built, classify each operation: structural identity, counting, fixed-vocabulary classification and config-honouring are deterministic and the model must not do them; only meaning-extraction, naming a genuinely new concept, and irreducible semantic judgement are LLM. A stage that hands mechanical work to the model fails non-deterministically. This is the single most important LLM rule and it has its own skill.
• Chains, not single providers: primary, fallback, backstop, rotating on 429 / 5xx / timeout. Underneath, the shared transport does exponential backoff (base doubling, hard cap, Retry-After honoured, non-retryable 4xx short-circuit).
• Models, prices and rate caps live in registry tables, edited from an admin surface, read at runtime. Never adapter constants.
• No uncached call at scale. Cacheable outputs persist keyed by content × config × provider × model; provider and model belong in the key because the same input through a different chain is a different output. Cache misses on chain rotation are correct, not a bug.
• Determinism within a version. LLM judgments that must be stable (classifications, adjudications) run at temperature zero and persist their verdict once; re-deriving happens only under a new calibration version, atomically re-pinned, reversible.
• Guard the vocabulary at persist. An LLM asked to emit from a fixed vocabulary will eventually paraphrase. The prompt instructs verbatim use; the persist layer normalises and coerces stragglers to the nearest valid value, and counts coercions; a counter that fires every run is a prompt-defect signal.
• Pre-scan external content before it reaches a model: layered prompt-injection detection (instruction-override, role-impersonation, exfiltration, encoding-evasion, social-engineering) with clean / suspect / block outcomes and a quarantine path, plus an eval harness against a labelled fixture set.
• Provider hygiene: no model or vendor names on customer surfaces (generic Primary / Fallback labels); every provider that touches customer-typed content joins the public sub-processor list in the same SHA it joins a production chain.

8Code quality and release

Why: style rules belong to machines; human review time is reserved for judgement.

• Lint + format + type-check are the style rulebook, run in CI with zero-warning budgets. A style rule that cannot be a lint rule lives in PR review, not in the constitution.
• Production comments explain what and why-this-shape, never "see <design-doc>" pointers, which break on every doc reorganisation. Temporal grounding by date stamp or SHA is fine.
• The wireframe port loop. The wireframe is the visual contract. Build ports or creates the surface in code (consuming the shared design tokens, not look-alike values), cleans it up, and ships an element-by-element audit diff in the same SHA: landed / deferred-with-named-node / deviation-pending-ack. Build hands the diff off through the handoff; the Architect finalises by validating against the source design, not the audit's self-report, and acks. The next node holds until that ack. No silent omissions, additions, or renames.
• Design tokens have one source. Colour, type, spacing, radius and motion live in one place that both the wireframe and the code read, so they cannot diverge into two slightly different blues. A raw hex or px that is not a token is a review-time failure, on the wireframe as much as in the code.
• Release discipline: every release ships at least one user-verifiable UI surface for every new backend concept; admin-grade fidelity is fine, SQL-only verification is not.
• Version the external API the way events are versioned. Additive changes (new optional field, new endpoint) are free; a breaking change ships as a new version and keeps the old one serving, never a mutation of the existing shape; deprecation gets a named window, not a cliff.
• Shippable contract: day-one constraints every UI component satisfies (tenancy wiring, i18n, theme tokens, logical CSS, locale-aware formatters), CI-enforced, so "we will internationalise later" never happens.
• TDD for domain logic (aggregates, scoring, pipeline stages); a five-layer test strategy (unit / integration / E2E / calibration-evals / smoke) with real-database integration tests for security policies. A policy that exists but does not block is invisible to coverage checks; only a negative test catches it.
• Verification before completion, always: the agent demonstrates the thing works (test, screenshot, fetch, diff) before presenting it as done.
• Docs match the diff on every ship v1.1. Closing a node includes a doc-drift pass: cross-reference the diff against the docs that describe the changed surface (constitution, the matching rules, the spec set, READMEs, wireframe-derived copy) and reconcile what drifted. Each side fixes the docs it owns; cross-boundary drift (a code ship that staled a spec) is flagged in the handoff as a paired design-side node, never crossed. "Docs match the diff" sits on the verification checklist next to "tests green."

9Security practice

Why: audits without a threat model produce hygiene findings and miss cross-tenant bugs.

• A written threat model anchors everything: named adversaries, assets, trust boundaries, enumerated abuse cases, high-risk surfaces, and an honest list of what static analysis cannot find (routed to DAST or manual review). Findings that map to no abuse case are hygiene, not criticals.
• The audit prompt wraps the threat model and names multi-tenant isolation explicitly. LLM-based static analysis has a documented 30 to 50 percent false-negative rate on cross-file authorisation, so it gets a dedicated section, plus business-logic and insecure-design review. Code scanning runs on every push; DAST against staging and an annual third-party pentest are scheduled milestones, not aspirations.
• Audit output is zero-noise v1.1. A finding ships only above a high-confidence bar; an explicit false-positive exclusion list suppresses the known-benign patterns; every reported finding carries a concrete exploit scenario (the adversary's steps) and is independently verified before it is reported. A finding without an exploit scenario or above-bar confidence is a draft, not a report, noise trains the reader to ignore the audit.
• A destructive-actions registry gates the Engineer's runtime: a push to the production branch (push-is-the-deploy ships production), schema applies, policy edits, secret rotation, prod deletes, force-pushes, CI disables, plugin installs, each class needs explicit human confirmation in-session and a line in an action log. Shell commands are tiered safe / moderate / blocked.
• An ISMS that matches reality: a scored risk register seeded from the threat model (likelihood times impact, owners, treatment plan anchored to milestones), reviewed on triggers (new sub-processor, new public surface, incidents). Document generation buys audit-readiness; only operating the system over time buys the certificate.

10The agent setup: the four pillars

Why: this is the shell that makes AI-assisted development compound instead of reset every session. Four files-on-disk pillars, no hidden state.

Retro: learning compounds into the rules v1.1

When a goal closes, after an incident, or on the human's call, each participant (Architect, Engineer, human) answers the same fixed question set independently, then the answers are laid side by side. The confluence, the agreements and the recurring frictions, is synthesised into proposed new ways of working, and each adopted item is promoted into a spec, a rule, or the operating model with a paired handoff entry and the human's bind. A retro that promotes no change was theatre. This is the memory-to-rules path on a cadence: a lesson that recurs and generalises stops being a per-session reminder and becomes a loaded rule.

11Skills: what we have, what we lack, how to stay agnostic gap analysis

Why: the scaffold is only as portable as its skills. A skill that names a product, a vendor, or a table is not reusable. This is the honest inventory.

Have, and already agnostic

• agent-deterministic-boundary ship as-is The discipline behind §7: draw the agent / deterministic line for a stage before building it. Already product-neutral; the reference example is genericised.

Built for this scaffold (the gaps, now filled)

• brainstorming, writing-plans, verification-before-completion shipped The three mandatory-at-entry skills, written out in full so a fresh project is never missing its required entry skills. The constitution's entry mandate is no longer hollow.
• specs-pin-exact-contracts shipped Referenced by the boundary skill. Pins an LLM call's output shape, controlled vocabulary (invented keys forbidden), cardinality, and failure mode, so the output is validated, never trusted raw.
• goal-tree-planning shipped Structures a request into the Goal / Subgoal / Task / Subtask rows of the ledger, with owners, status and evidence, replacing the old plan-file-plus-board split. Assigns the owner at creation, since the owner is the only party who may later close the row.
• handoff-discipline shipped How to write a good log entry, a paired spec-promotion entry, and when to promote a decision into the constitution.
• ci-gate-authoring shipped Turn a recurring review comment into a CI gate script in gates/. The mechanism that keeps human review for judgement.
• planning-with-files, codebase-audit-pre-push, systematic-debugging port Useful, not blocking; port from the source build as standalone procedure files.

Reuse from the platform, do not re-author

• doc-coauthoring, mcp-builder, document skills (pdf / docx / xlsx / pptx) reference Provided by the host environment; the scaffold points at them rather than vendoring copies.

From the market, patterns worth our own version

A scan of the public skills directories surfaces a few patterns this three-function-plus-Orca setup will want. Adopt the pattern, author our own product-neutral version rather than installing a third-party skill that names a vendor or a CI shape:

• Parallel-work merge / consolidation shipped The market's "team merge" pattern: consolidate several agents' parallel output, verify the quality gates, sync status. Directly relevant to Orca's fan-out-then-merge loop; shipped as consolidate-parallel-work, driving the goal tree and our gates, not a JIRA-specific one.
• Issue-to-PR auto-fix pattern The "GH issues auto-fixer" pattern (spawn a sub-agent, fix, open PR, resolve review comments) is what /ship <node> plus the Engineer already do; keep ours, do not add a parallel one.
• Lint-and-fix-before-commit have Covered by ci-watch-and-fix and the lint gate; no third-party skill needed.
• Make context visible + decision guards shipped From the augmented-coding-patterns catalog: context markers (which agent, what rules loaded, did it push back), the "you do it" / reverse-direction dialogue habits (§1), and decision guards (DEC-NN over a root DECISIONS.md, §3). Authored as our own product-neutral version in the operating model and rules, not installed.

12The scaffold layout what gets generated

The reusable template is one folder. Drop it into a new project, run the adoption checklist in ADOPT.md, fill the placeholders, delete what does not apply.

project-agent-scaffold/
  ADOPT.md                     # init checklist: fill placeholders, sequence (sect 13)
  CLAUDE.md                    # the constitution; auto-loaded by name in every Claude Code worktree
  ARCHITECTURE-PRINCIPLES.md   # Appendix A: invariants every PR holds
  DECISIONS.md                 # counter-intuitive deliberate choices, guarded inline by DEC-NN markers
  .gitignore
  .claude/
    settings.json             # hooks: executable discipline
    hooks/                     # session-start (surface open rows), guard-destructive (block)
    commands/                  # /check-handoff  /check-board  /ship
  operating-model/
    OPERATING-MODEL.md         # the functions, triggers, the ledger mechanics
    STATE.md                   # the ledger: only home of open/done, owner-closed, evidence-gated
    LOG.md                     # append-only conversation, carries zero state
    LOG-ARCHIVE.md             # verbatim date-cut moves out of LOG.md (never STATE)
    EXAMPLE.md                 # one scenario shown in both files, to copy the shape from
  specs/
    README.md                  # lifecycle + the six writing rules
    TEMPLATE.md                # spec template with the promotion checklist
    000-example-spec.md        # one worked, agnostic example
  rules/
    INDEX.md                   # the full rules library, one line each + file-pattern map
    *.md                       # 16 core rules in full (incl. 5 promoted from memory, + decision-guards); rest stubbed
  agents/
    ROSTER.md                  # the sub-agent roster + when-to-invoke gates
    *.md                       # 10 specialist reviewer definitions
  skills/
    SKILLS.md                  # mandatory set, full library, the gap analysis (sect 11)
    */SKILL.md                 # 9 skills incl. the 3 mandatory + the gap skills, all shipped
  ci/
    workflows/                 # ci.yml, deploy.yml, scheduled.yml (agnostic)
    gates/                     # 6 gate scripts: one folder, run as one CI job
    pull_request_template.md   # node link + verification checklist (copy to .github/)
    REFERENCE.md               # one filled stack reference (Node + Python + Postgres)
  memory/
    MEMORY.md                  # the durable-facts index template
    RECOVERY.md                # the from-zero restore playbook template

13Adoption order

Sequence, not schedule. Each step depends on the ones above it; there are no dates.

• 1. The constitution (CLAUDE.md), the handoff with its goal tree, the Architect / Engineer boundary, push-is-the-deploy, remote-only secrets.
• 2. Wire the Engineer in Orca: .claude/commands + .claude/agents, the /check-handoff entry point, one node per worktree.
• 3. First schema: the RLS-same-migration invariant + its CI script, migrations-as-truth, the idempotency layers.
• 4. First feature: spec lifecycle with paired handoffs, blocking-question discipline, the three mandatory skills (brainstorm / plan / verify), design-port audits.
• 5. The CI gate scripts, the threat model, the destructive-actions registry, the gateway and the agent / deterministic boundary if LLMs are in play.
• Continuously: promote durable decisions from the log to the constitution; turn every repeated review comment into a CI script; let the memory compound.

AAppendix · Architecture principles & build invariants

The constitution-level list, genericised in name.

• Domain-driven design with explicit bounded contexts. Each aggregate root owns its data; nothing reaches into another context's tables.
• Event-driven between contexts. No synchronous cross-context calls on the critical path. Every event carries a ULID id (idempotency) and a semver schema version, and is replayable inside a fixed window; breaking renames ship as new event names, never mutations.
• The tenancy model. Tenant-private entities scoped by tenant id, enforced by row-level security through array-returning auth helpers (col = ANY(auth_ids())); a role-based default-visibility cascade (org admin sees all, workspace roles see their slice, a billing role sees no content); shared platform knowledge in a separate service-role-only store with zero tenant data; four layers of defence (signed envelope, RLS, code-path checks, audit log).
• History entities are first-class domain concepts, modelled and queried, not an afterthought audit log.
• Admin is a role, not a separate app. Staff surfaces live in the one shell behind a role gate (plus a staff flag for platform pages). No second app, no separate domain.
• Operational knobs live in registries, not code. Model choices, pricing, rate caps, backend priorities: registry tables, edited from an admin surface, read at runtime. New providers are an INSERT, never an adapter constant.
• No uncached expensive call at scale. Cache key = content × config × provider × model; invalidation is explicit and classified; cache misses on provider rotation are correct behaviour.
• Five invariants every PR holds: (1) signed job-context envelope on every queue message + RLS on every tenant table; (2) cross-context comms by versioned, replayable events only; (3) idempotent billable gates (request ids; quota exhaustion = 429 + reset header); (4) quality thresholds gate releases in CI, production runs are never blocked by validation, and thresholds are never relaxed to pass; (5) behaviour configs ship as pinned bundles with atomic, audited re-pin as the only rollback.
• Staff surfaces render opaque ids, never customer-given names.
• Domain naming: entities are named for what they are, never for what state they are in (state lives in scores or status fields); a clear line between sources (surfaces that produce content) and content (the items they produce).

BAppendix · The rules library

The topical rule files, loaded by file-pattern when an agent touches the matching surface. One line each; every one exists as a standalone doc. Core (shipped in full in the scaffold) is marked.

The eight rows marked "from memory" were promoted out of the source project's operating memory (the running list of how-we-work corrections) into standalone, product-neutral rules. This is the memory-to-rules path in action: a correction that recurs and generalises stops being a per-session reminder and becomes a loaded rule.

CAppendix · Skills & sub-agent roster

Skills are reusable procedure files; sub-agents are isolated specialist reviewers invoked at gates.

Skills, mandatory at task entry: brainstorming (before any new feature or architecture decision), writing-plans (before any code), verification-before-completion (before presenting any work).

Skills, the scaffold's own library: system-health v2.7 (the scan of the scaffold itself: enforcement ratio, orphan rules, growth-against-effect, family collisions, gate yield, dead gates; every step a command that prints a number, every admissible action a subtraction) · agent-deterministic-boundary · specs-pin-exact-contracts · goal-tree-planning · handoff-discipline · ci-gate-authoring · consolidate-parallel-work · planning-with-files · test-driven-development · codebase-audit-pre-push · systematic-debugging · create-pr · technical-change-tracker. Document and MCP skills are referenced from the host platform, not vendored.

Skills adopted from community, cherry-picked and adapted v1.7: improve-codebase-architecture (find shallow modules, deepen them, applies the deep-modules rule as a procedure) and grill-plan (stress-test a plan against existing bindings one question at a time, the narrowing counterpart to brainstorming). Both rewired to the scaffold's goal-tree / handoff, DECISIONS.md + decision-guards, and the Explore agent; bodies kept agnostic. Adapted from Matt Pocock's improve-codebase-architecture and grill-with-docs, per plugin-and-skill-adoption (cherry-pick, never install wholesale).

Sub-agents, engineering gates: system-architect (before any spec binds; topology + fault lines) · principal-engineer (18-month consequence, simpler-shape, incident pattern-match; every release-scope decision) · database-architect (every migration, policy edit, isolation question) · test-strategist (which layer tests what) · integration-test-designer (real-database security negatives, replay / idempotency) · security-reviewer v1.3 (the end-to-end boundary lens on any security-relevant surface, anchored on the threat model + SECURITY-HARDENING.md) · accessibility-reviewer (the accessibility floor on every customer surface) · incident-responder (mitigate, communicate, investigate; postmortem inside 48h) · spec-critic (the six spec-writing rules + dispatch questions) · design-critic (the visual floor rules) · prompt-engineer (designs and evals the per-purpose prompts) · adversarial-verifier v2.7 (takes ONE load-bearing claim, not an artifact, and tries to refute it; defaults to refuted when uncertain and returns survives rather than confirmed, because every other reviewer defaulting to accept reproduces the author's blind spot).

Sub-agents, research bench: a general research analyst plus optional domain specialists the design side delegates to. Default is to delegate when a task matches a specialist; isolated context, conclusions reported back.

□Changelog

What changed in this operating system, newest first. The detail lives in the rules and the operating model; this is the index of what moved.

• v3.0 current The release cut: three functions, a quickstart, a license, and the two-pass corpus sweep behind them. The roles rename from the two-agent vocabulary to three functions, because the old names read as a headcount and the boundary was never about headcount: the Orchestrator (the human, owner of the four gates), the Architect (design function, previously the Design agent), the Engineer (build function, previously the Build agent). Boundary rules untouched; the change is that a function now scales out loud: staff it with more agents when capacity demands, while each function keeps one accountable owner and parallel work goes through that owner's gates, never around them, the one-builder-one-committer lesson generalised. Swept on every live surface; changelog history keeps the old names per the append-only discipline, and the machine names survive: @design / @build handles, placeholder tokens, sub-agent filenames. A Quickstart opens both documents (copy the template, fill placeholders, two worktrees via Orca or plain git worktree, both functions as CLI agents inside Orca in the reference setup, check handoff, validate-scaffold-to-stack, brainstorm). And the repo ships MIT at the root, with community-skill attribution already recorded in skills/SKILLS.md: a freebie without a license file is all-rights-reserved by default, the opposite of a freebie. Shipped alongside: skills/validate-scaffold-to-stack, a DRAFT: the two-way coverage diff between an adoption's manifest-inventoried stack and the rules library; uncovered surfaces become stubs with triggers, rules and file-pattern rows with no matching surface leave the instance, output capped at three actions; promotes after five successful runs, wired as ADOPT.md step 6, making "delete what does not apply" countable. Also assessed: openai/codex-security, whose scans-compare (findings matched by root cause: new / persisting / reopened / resolved) is the v1.9 regression spine implemented mechanically; not a port (a vendor service installation; the port target already exists as /security-review plus security-reviewer) but a per-project findings source under platform-findings-backstop and the natural second-vendor lens for the queued cross-model diff gate; sending source to a second vendor is a human bind, never an agent default. An intake sweep of a 139-link external corpus in two passes, and the three defects it found at home. Thirty-nine in-domain links vetted at mechanism level by five parallel reviewers, every headline claim re-verified first-hand (the v1.9 synthesizer discipline); the title-only triage of the remaining hundred was then challenged as judgment from appearance, and a second pass opened every remaining link: 79 bins held, 14 flagged links got the same mechanism-level vetting, one flag died on vetting, and eleven sources now clear the v2.7 admission test, every one a fold or a CI convert, zero new rules. Fixed in this entry: guard-destructive.sh failed open silently (an unparseable payload was allowed with no record, so guard-down was indistinguishable from guard-pass; now jq-first parsing with the sed fallback, every decision logged append-only to a gitignored .claude/guard-log.jsonl, system-health step 9 counting the fail-opens, and the injected-defect test extended to the hook, verified before this entry was written: an unparseable payload logs parse-fail, and a multiline command hiding a hard reset on its second line is decoded and blocked; named by comparison against mayankjain0141/nixis); the constitution's file-pattern table listed spec-discipline three times in one row, sediment of the v2.6 merge sweep, kept on record as the dead-reference gate's named evidence; and the README changelog had drifted two versions behind this handbook, the folder-only miss framework-mirror-to-scaffold exists to prevent, backfilled and recorded. The adoption queue, each landing with its own wiring and the skill with its five-run trial: a test-ratchet gate (delete or weaken a failing test to fake green; two independent namings), diagnosing-bugs into the systematic-debugging port slot, the cross-model gate extended from spec bind to the pre-PR diff (the v2.4 measurement was only ever applied to specs), a dead-reference gate plus a commit-relative staleness number in system-health, a visual baseline behind the wireframe-port ack, a WCAG contrast-matrix gate over the token source, a declare-even-if-empty negative-space spec slot (what must NOT be done or touched, against overperformance), a hedge-lexicon spec gate validated against the corpus first per v2.6's 165-false-findings lesson, and a credential-path / read-piped-to-egress registry row, plus from the second pass a named-defaults deny-lexicon gate over the token source and committed CSS (VibeCurb: keyword easings, AI-purple gradients, display-font misuse, the drift the wireframe contract is silent on). Deliberately not adopted: every installation; review daemons, policy engines and the memory-infra shelf answer as infrastructure what this scaffold treats as discipline, ccpm's shared-worktree parallelism is the v2.2 incident productized, and chorus's regex verdict parsing with its documented false approvals is the recorded dead end binding that a gate reviewer returns a structured verdict token, never prose. The second pass added four one-line notes (weakest-provenance inheritance, discrete anchored scales, the stale-blocked row check held for a recorded miss, a dormant prefix-cache clause), a placeholder-residue line on the queued dead-reference gate, and two corroborations: hermes-agent's own write guards against its ungated skill loop, and the session-resume author converging on checkpoints the next agent just reads, the ledger design independently arrived at.
  Corpus reviewed at mechanism level: mattpocock/skills (adopt) · PiLastDigit/TRIP-workflow (adopt) · theDakshJaitly/mex (adopt) · jrpease/throughline (adopt) · codeswithroh/tastemaker (adopt) · gszhangwei/open-spdd (adopt) · murilobauck/specsmith (adopt) · mayankjain0141/nixis (adopt; the guard fix executed here) · addyo.substack.com/p/long-running-agents (adopt: test ratchet) · blog.tedivm.com Beyond the Vibes (corroborates the ratchet) · chorus-codes/chorus (note) · Cappe6969/Architect-Builder-Reviewer (note) · openclaw/clawsweeper (note) · garrytan/gbrain (note) · martinfowler.com SDD three tools (evidence) · israynotarray.com hooks guide (note) · o11y-dev/opentelemetry-skill (note) · martinfowler.com SPDD (covered) · ryanthedev/code-foundations (covered) · automazeio/ccpm (covered; dead end) · r/WebAfterAI layered-defence post (covered; the consumed source) · moazakramkhan1/assumption-auditor (covered) · sahilsaleem2907/sift (covered) · kid-sid/claude-spellbook (covered) · faizanmohiuddin482/bullpen (covered) · evilayman/opencode-raven (covered) · VoltAgent/awesome-claude-code-subagents (noise) · GetBindu/awesome-claude-code-and-skills (noise) · MengTo/Skills (noise) · HusseinLab/codex-operating-system-community (noise) · Mathews-Tom/Agentic-Design-Patterns (noise) · ergon-automation-labs/ergon-wrong-turn-logger (noise) · agix-ai/agix-aos (noise) · raia-live/amfs (noise) · chopratejas/headroom (noise) · mnemosyne-oss/mnemosyne (noise) · syncable-dev/memtrace-public (noise) · srihari7070/lore-map (noise) · Shah-in-alam/LiveArch (noise) · ShopDevX/adeptlydev (rejected same session) · Yu-369/VibeCurb (2nd pass: adopt, deny-lexicon gate) · JetXu-LLM/DocMason (2nd pass: note) · safishamsi/graphify (2nd pass: note) · esengine/deepseek-reasonix (2nd pass: dormant note) · rockthemike712/mission-control-board (2nd pass: note, held) · Hamosian/marketing-brain-starter (2nd pass: covered) · antigravity.google (2nd pass: covered) · nousresearch/hermes-agent (2nd pass: covered, the named anti-pattern) · agno-agi/dash (2nd pass: covered) · oxbshw/watch-skill (2nd pass: covered) · moa.chat (2nd pass: covered) · r/ClaudeCode CCMeter (2nd pass: noise) · r/claudeskills agent-session-resume (2nd pass: covered) · r/WebAfterAI shepherd (2nd pass: covered)The remainder of the corpus, each bin confirmed in the second pass by opening every link: already mined or in daily use (5): garrytan/gstack · Sanexxxx777/curated-claude-code · stablyai/orca · lexler.github.io/augmented-coding-patterns · lexler.github.io/pattern-catalog   deep links of vetted repos (2): mattpocock/skills/skills · mattpocock/skills/engineering   agent frameworks, the surface the LLM-gateway rule abstracts over (11): BuilderIO/agent-native · foundationagents/metagpt · huggingface/smolagents · langchain-ai/deepagents · langchain-ai/langgraph · langchain-ai/open_deep_research · mastra-ai/mastra · significant-gravitas/autogpt · stanfordnlp/dspy · tauricresearch/tradingagents · pydantic.dev/overview   observability platforms, per platform-findings-backstop a per-project pick (4): arize.com/phoenix · comet-ml/opik · comet-ml/opik (dup) · langfuse.com   memory infrastructure, the file-based stance holds (5): getzep.com/graphiti · angelnicolasc/graymatter · NevaMind-AI/memU · plastic-labs/honcho · unbody-io/adapt   products and hosted platforms (33): 21st.dev/home · dify.ai · eigent.ai · 0-AI-UG/cate · 666ghj/MiroFish · alibaba/page-agent · BotCoder254/limboo · idolaman/galactic · msitarzewski/agency-agents · nesquena/hermes-webui · OpenSenseNova/SenseNova-Skills · paperclipai/paperclip · heygen-com/hyperframes · JCodesMore/ai-website-cloner-template · khoj-ai/pipali · Mintplex-Labs/anything-llm · ruvnet/ruflo · techhorizonlabs/thl-open · twentyhq/twenty · Vizards/deepseek-v4-for-copilot · wende/claude-max-api-proxy · glideapps.com/new · graperoot.dev · gumloop.com · hermes-agent.nousresearch.com · hermes-agent.nousresearch.com/skills · musterr.dev · openclaw.ai · opencode.ai · openwork.software · z.ai/subscribe · bloom500/feral · companion-inc/feynman   tools and utilities (5): ChromeDevTools/chrome-devtools-mcp · Cocoon-AI/architecture-diagram-generator · oraios/serena · taisei-ide-0123/pluckmd · huggingface.co/harness-1   reference collections and how-tos (2): CodeBoarding/awesome-architecture-mds · medium.com/how-to-use-git-worktree-for-   listicles, explainers, setup tours, off-topic (19): aisera.com/agentic-workflows · cnbc.com/these-are-the-5-most-valuabl · edenai.co/best-ai-agent-harnesses-comp · reddit WebAfterAI: 1uehxc0 · reddit WebAfterAI: 1unek5m · reddit promptingmagic: 1ucjmq9 · reddit hermesagent: 1ustnra · reddit WebAfterAI: 1tuymto · reddit hermesagent: 1v03vab · reddit aiagents: 1ub20yq · reddit Markdown: 1u9fs8k · reddit hermesagent: 1u9fa2w · reddit hermesagent: 1uevy29 · reddit WebAfterAI: 1t0xjs5 · reddit LLMDevs: 1uz6aee · snyk.io/top-claude-skills-finance-qu · swarm-organisation.com · vectorize.io/gbrain-alternatives · wearenotch.com/agentic-ai-explained
• v2.9 Refs-not-bodies gains its one honest exception. observability-instrumentation clause 4 stated "no prompt, completion, page body, or PII string in any span attribute" as an absolute, and the source project bound a fenced full-text trace mode that falsified it - the clause now names the exception instead of being silently contradicted: a bound spec may open ONE gated body path onto model-call spans, entered through a single attach seam under a committed conjunction (flag, pinned self-host sink identity, tenant allowlist, absolute expiry, live retention probe), TTL-bounded, with committed attribute keys - and log records and labels stay absolute in every mode. The generalisable lesson is the editing discipline, not the mode: when an amendment falsifies a bound absolute, the absolute is edited in the same bind to name the conditional honestly, never left standing to assert P while the amendment asserts not-P one section below. The mode itself earned its shape through two adversarial gate rounds whose second round was fix-induced, triggering the stop-and-shrink pattern: scope shrank to a time-boxed debug window and the full posture deferred to the release gate that already owned it.
• v2.8 Third-party surfaces: docs first, execute to verify. Folded into epistemic-discipline rather than added as a file, per the v2.6 freeze - the verify-before-asserting family already owns this. The evidence, from the source project's vendor-service standup: five deploy failures in a row built from recollection (a CLI flag the binary does not have, an illegal comment token in a config format, healthchecks probing localhost on an IPv4-only bridge, an env placeholder never passed into its container, a wrong export endpoint), every one answerable by reading the vendor's current documentation or by executing the artifact once, at the cost of six deploy rounds of the human's time. Three clauses. (1) Docs first: before writing code against any third-party API, SDK, config format or container image, fetch the vendor's CURRENT docs; a recollection is not a citation, and a vendor claim gets the same verify-this-turn treatment as a codebase claim. (2) Execute to verify: verification executes the artifact (parse the config, boot the container, run the probe), before the push, not after the human hits the failure; and read the result back through the CONSUMER, because a producer's acknowledgement proves acceptance, not existence. (3) Verifiers exit non-zero: a green result that means "did not crash" will be read as "passed"; a check that cannot fail loudly is not verification. The build side had already shipped the mechanical half before the rule landed (probes that exit non-zero, a read-back through the consumer API, and four config/execution CI gates each guarding one of the failures), which is the v2.7 admission test satisfied the intended way: the procedure solved the problem before it was written down. One precedence call bound with it: vendor docs and vendor skills inform implementation; they never override a bound spec. The recorded instance is a vendor skill preferring its native SDK over the neutral telemetry seam the specs bind; the seam won because its repoint-the-backend swap property had just been exercised for real, and a genuine conflict routes to the handoff as a design question, never a silent switch.
• v2.7 Three adoptions from an independently-built harness that reached v2.6's conclusion from the other direction. github.com/Sanexxxx777/curated-claude-code states it as "curated, not dumped" and "a harness that grows is worth more than a harness that's big", and ships 8 skills, 2 agents and 5 rules deliberately. Three things it had that this scaffold did not, all folds rather than additions. (1) adversarial-verifier, a new roster agent, and the load-bearing detail is its DEFAULT: refuted when uncertain. Every other reviewer here defaults to accepting, which reproduces the author's blind spot; this one takes a single claim, states what would falsify it before looking, tries the awkward cases (empty set, second call, other arrival order, after a regroup, at 100x), and returns survives rather than confirmed, because surviving one attack is not verification. It takes ONE claim, never an artifact, which is what keeps it distinct from the cross-model gate. (2) An admission test in front of the freeze. v2.6 said which MOVES were allowed (convert, fold, replace) and never said what QUALIFIES, which is how a library reaches 58 entries: a candidate now needs verified correctness, a NAMED failure pattern ("good practice in general" fails this), recorded ruled-out dead ends, and five successful runs before a procedure is promoted to a skill. Their phrasing is the one to keep: confident guesses never get enshrined as truth. (3) system-health, a scan of the scaffold rather than the product, and it is the most valuable of the three because it is v2.6's audit made repeatable. That audit was run by hand, once, a month after the drift started. Every step is now a command that prints a number: the enforcement ratio (rules with an executable check over total, and the interesting figure is the FRACTION, not the count), orphan rules with no retrieval trigger, growth-against-effect (rules sorted by birth date beside size, where the red flag is the newest also being the largest), family collisions, gate yield and the fix-induced trend, cadence actually running, mirror drift, and dead gates that have never failed and must be tested with an injected defect. Its output is capped at three actions and every admissible action subtracts, or the scan becomes the thing it exists to catch. Deliberately NOT adopted: their pre-push and ship-secure (our gates job and the security rule family already cover these), konsilium (the gate panel is the same shape), goal (the state ledger), and above all their rule count: five rules cannot carry tenant isolation, data protection, disaster recovery and supply-chain hardening for a multi-tenant product. The intake discipline transfers; the size does not. Their vet plus tool-scout pair remains the reference implementation for this scaffold's plugin-and-skill-adoption stub, to be filled the first time an external skill is actually taken.
• v2.6 Subtraction. The scaffold stopped growing and started measuring, because the growth was concentrated exactly where the effect was zero. The audit that forced it, run against the scaffold's own files rather than from impression: 58 rules, 1,324 lines, and 9 rules with any executable enforcement. One retro ever, against a bound retro-cadence. And no record of gate yield anywhere, against a rule that mandates measuring it, so the question "which of these rules earn their place" was unanswerable from the scaffold's own records. The sharpest finding is in the birth dates: the two largest rules in the library were the two newest, both about the spec process, and both had a measured effect of zero. One's own text recorded that all ten of its clauses were bound before the last three recurrences it existed to prevent; the other's headline detector recurred four times in the round that added it, missed by the author who had just written it. Process grew fastest exactly where it worked least, which is what over-engineering looks like from the inside. Four changes, all subtraction. (1) The library is frozen. rules/INDEX.md now opens with it: a lesson converts to a CI check, folds into the rule that owns its family, or replaces a file. A genuinely new surface enters as a stub with a trigger, not an essay. (2) Four rules became one. spec-lifecycle + spec-authoring-discipline + gate-findings-learning-loop + implementer-questions-are-doc-bugs, 210 lines, one capability family, are now spec-discipline. What survived the merge is what had evidence: the lifecycle, the non-optional cross-model gate, the corpus, the stop condition, the six writing rules. What was cut was the war-story tables and the eight prose clauses that a gate now checks. (3) Three detectors became CI gates. spec-deliverable-check.py, spec-propagation-check.py, spec-citation-check.py, covering eleven recorded recurrences between them. They were run against a real corpus before being trusted and produced 165 findings of which every single one was false: one entire check was deleted (asserting that every field declared in a Data section is read in the same spec is simply wrong in a system that centralises its schema), the identifier pattern had to accept dotted qualifiers, and retired specs and checklist lines are skipped. That measurement is the reason to trust the three that remain. (4) The gate got a log. operating-model/gate-log.md, one row per gate, and the load-bearing column is fix-induced: findings created by the previous round's fixes. Two consecutive non-zero rows is the stop condition, and on the programme this came from that count went 1, 2, 4 while blockers went 1, 2, 2, so the number that mattered was rising the whole time redrafting felt like progress. Two gaps closed alongside. Capability families get one representative each, because rules that share a family compete at retrieval and the retriever cannot tell them apart: the benchmark result behind it is a baseline retriever surfacing the wrong sibling from the right family in the top 3 69% of the time, fixed by selecting one representative per family before ranking. Eleven families are now named in the index with their front rule. And retro-cadence gets two countable triggers (any second consecutive fix-induced row, and every tenth row) because the discretionary trigger produced one retro in a month, and a retro is exactly the thing that would have caught all of the above. The honest note the scaffold keeps about itself: the two rules deleted here were written two days before they were deleted, by the agent that wrote this entry.
• v2.5 A learning loop for gate findings, because writing rules did not stop them recurring. New gate-findings-learning-loop rule, and it is not a new discipline: eval-guards-a-lesson already binds that every lesson from a real miss ships the regression check that would have caught it, and that had only ever been applied to CODE defects. Applying it to SPEC defects is the whole change. The evidence that forced it: across four spec drafts and six independent gate rounds on one programme, the same classes recurred - unproducible deliverable (3x), unchecked consumer invariant (4x), a defect class correctly diagnosed in prose and then committed in the adjacent section (3x), unbounded at 100x (4x). All ten rules of the spec-authoring discipline were already bound when the last three recurrences happened, so a written rule prevented none of them: a rule is read once at the start, and the defect is committed in the middle of writing something else. The loop puts the specific prior finding in front of the author at the section that would repeat it. A findings corpus tagged by class and by section-kind; a detector column carrying the concrete question that surfaces the class, which is what turns a war story into an asset; retrieval at AUTHORING time; and a mechanical pre-gate check generated from the corpus. Two deliberate design calls. The independent gate is NOT seeded from the corpus, because a seeded reviewer checks the list and stops, and reasoning from the artifact is the property that works - known classes are the pre-gate's job, novel ones are the gate's. And recurrence after a class has a corpus row means the DETECTOR is bad, not the author careless, so the detector gets rewritten; without that the corpus grows into a checklist nobody runs. No vector store: at fifty findings this is a grep against a two-screen table, and what matters is WHEN retrieval fires, not how clever the index is. A corpus template ships with the classes and detectors pre-seeded and no project instances. Three existing rules amended in the same pass rather than a fourth rule added, which is the discipline the session was about: epistemic-discipline gains the loophole it was falling through - its verify-before-asserting list named the codebase, paths, flags, APIs, columns and command output but never what one of our own bound specs asserts, and that is where it was broken repeatedly, because an external source feels like it needs checking and our own spec feels like knowledge; internal claims are not safer than external ones, they are less verified. spec-authoring-discipline rule 9 extends from the bind set to AUTHORING volume, because error density rose with artifacts-per-turn and the artifacts that failed hardest were the largest and fastest-written, so volume is a defect signal to act on rather than a productivity signal to enjoy. And the learning loop gains a stop condition: stop on the FIRST fix-induced defect, not the third - if a gate round's findings were created by the previous round's fixes, the problem is not in the drafting and drafting again is the one response guaranteed not to address it. The stop is the deliverable.
• v2.4 Spec-authoring discipline, derived from a measured error record rather than from principle. New spec-authoring-discipline rule, ten items, each naming the specific failure it prevents. The evidence that produced it: a design agent self-reviewed three of its own specs and found nine findings; an independent-model gate on the same three found twenty-two, including five blockers, of which the self-review had found zero. Two of those blockers were defect classes the author had correctly diagnosed in prose one paragraph earlier and then committed in the adjacent table, which is why the rule treats self-review as structurally weak rather than merely insufficient. The load-bearing items: a claim about your own system cites file:line or it does not ship (internal claims are not safer than external ones, they are less verified, because external ones feel like they need checking); a cross-model gate before any bind, non-optional, the only rule here that addresses the general case rather than an instance already seen; a finding is not closed until its defect CLASS is swept, not just its instance; trace the deliverable end-to-end before writing prose, because prose is about what a thing means rather than how it is obtained, and the sharpest blocker found was a spec whose deliverable was uncomputable from its own schema; read the consumer's bound invariants before touching its surface; and a semantics change invalidates every downstream coefficient. The rule keeps its own honest limit rather than dropping it: none of the ten fixes the deepest failure, naming a defect class and then committing it, which only the cross-model gate catches. Wired into the spec file-pattern row and the TEMPLATE promotion checklist, where the cross-model gate and the deliverable trace are the two with teeth. Same entry, the drift catch-up the mirror rule mandates: a drift check found human-binds-never-operates had been bound in the source project and never mirrored here, so it lands now with its own wiring. It is the boundary rule every gate checks first: the human is a designer and binder, never a runtime operator, no running stage asks a person to decide a per-item outcome, and the one sanctioned input to output-math is the design-time bind of a DERIVED value. Rule set drift is now zero.
• v2.3 The observability gate lens, and a rule that ends the drift catch-ups. New observability-instrumentation rule: observability is declared by construction. A mandatory declare-even-if-empty spec Observability slot (mirroring Dispatch / LLM call sites) makes the author state which spans and metric families the surface emits, so cardinality is a review-time decision, not a production discovery; a build gate then reconciles declared-vs-emitted families, lints label cardinality against the rule-of-100 (a run id or a raw path is never a metric label, it rides a span), checks the semantic-convention keys, and holds the refs-not-bodies line. Built from a broad OpenTelemetry pass on the principle that the project's own observability spec owns the measurement set, so the rule references it and never restates it, the design-tokens-single-source discipline applied to telemetry. New framework-mirror-to-scaffold rule, the structural fix for the pattern this changelog keeps recording: a change to how-we-engineer mirrors into the scaffold the same session, generified, carrying its INDEX / file-pattern / template / handbook wiring, and a drift check runs at every retro and audit, so a rule can no longer sit folder-only. Same entry, the drift catch-up that rule now prevents: traceability and web-sql-column-check had been added to the source project but never mirrored here, caught by the first drift check the new rule mandates.
• v2.2 The state ledger gets an owner model and an anti-fork gate. The v2.0 split was not enough, and the second incident proved it: once STATE.md existed it forked. The human corrected a row on the build branch, the correction never reached the design branch because the merge topology ran one way only, and the design agent then reconciled off a stale copy, re-opening a row the human had already closed and dropping a row it had never seen. Splitting state out of the log answered WHERE state lives; it never answered WHO may write a given row, or how two copies re-converge. Three rules added to handoff-log-state-split: the owner closes (only a row's owner mutates its status, since the owner is who holds the primary evidence; a non-owner audit writes a CLAIM into the evidence field and routes it, never flips; adopting a status the owner already recorded is a sync, not a close), anyone creates, only the owner mutates (the line is create vs mutate, not design vs build, because appends merge cleanly and status edits collide), and read the other tree's copy before writing your own. Two CI checks give them teeth: (d) this branch's STATE must contain every row id in the other tree's copy, catching the silent drop, and (e) any row whose status differs from the other copy must be owned by this branch's agent, catching the cross-owner close. Both compare against the other copy, so neither passes until the two are reconciled: syncing stops being something an agent remembers and becomes a precondition of committing. The generalisable lesson is the shape of the miss, not the fix: a rule was written, declared solved, and never tested against the topology it had to survive. The scaffold now embodies the split instead of only describing it, which it did not before: operating-model/ ships STATE.md + LOG.md + LOG-ARCHIVE.md + a worked EXAMPLE.md (the single HANDOFF.md is retired), and ci/gates/handoff-state-check.py exists at last, with all five checks and the CI wiring they need (fetch-depth: 2 for the archive diff, the other tree's ref for the anti-fork pair). Every surface that named the old file was swept: the constitution, the adoption guide, the three slash commands, the session-start hook, git-discipline, and four skills. Two pre-existing defects surfaced while verifying and were fixed in the same pass: no-direct-llm-sdk-check.py matched its own pattern strings and so failed on any clean repo, and two rules files broke the house em-dash gate. The scaffold now passes all seven of its own gates, which is the only claim of consistency worth making.
• v2.1 Dependency-update cadence. A recurring Mode-B audit found Dependabot configured but its PRs untriaged, plus a stale ignore comment justified by a breakage a later bump had already disproven. New dependency-update-cadence rule: security-flagged updates triaged the next session, non-security batched on a fixed cadence, a staleness ceiling past which no PR sits without a recorded merge / hold-with-reason / close; a scheduled check surfaces the open queue so the decision happens on a clock, not at the next audit; majors ship with an equivalence harness in the same change (the pinned-lock plus HHEM score-equivalence battery is the reference), and a hold-with-reason expires when its reason does. Sits on top of cicd-supply-chain-hardening (which keeps the PRs coming) and reuses eval-guards-a-lesson for the equivalence gate.
• v2.0 The handoff system redesigned: log/state lifecycle split. A real incident forced it: an archive cleanup of the single handoff file dropped five open obligations and inverted two facts (an unapplied migration recorded as applied; a superseded model pick still named), because one file mixed three lifecycles and state lived only as prose inside an archivable log. New handoff-log-state-split rule: LOG.md is append-only conversation, archivable only as a verbatim date-cut move; STATE.md is the single home of open/done, every item carrying owner, gate, and an evidence field, with done unwritable without a cited SHA or applied-log line; decisions and bound facts keep their existing homes. A mechanical CI gate enforces all three invariants at commit time. Companion disciplines bound in the same incident window: no assertions about the other agent's tree state without the verifying command cited in the same entry, and every routed spec names its branch commit SHA so the reader verifies by content, never by asking.
• v1.9 The audit becomes a standing protocol, plus a doc-drift catch-up. New due-diligence-audit rule, distilled from a real full-project audit: two modes (Mode A conformance-vs-bound-specs with CONFORMS / DEVIATES / NOT-IMPLEMENTED / STRICTER-THAN-BOUND verdicts; Mode B the twelve-heading scored due-diligence with a production go/no-go), method invariants (literal code never claims, since comments and migration text claimed guards the call sites did not pass; parallel read-only domain agents with a synthesizer that re-verifies every headline finding first-hand; honest credit for what conforms), and the regression spine that makes audits compound: every later audit opens by re-verifying the prior audit's Criticals (a re-opened finding is BLOCK-class and leads the report), scores ratchet against the pinned baseline, findings route as goal-per-heading in the goal tree, and every closed finding ships the CI gate or test that keeps it closed. Cadence: launch gate, every release gate, after any serious incident; Mode A whenever a bound-amendment program ships. Same entry, the drift catch-up: feature-flag-lifecycle, output-grounding-verification, and implementer-questions-are-doc-bugs were added to the rules folder in earlier sessions but never listed here; the miss is itself the lesson this handbook's doc-drift-on-ship rule names, recorded rather than hidden.
• v1.8 Three working-ways promoted from a retro. spec-lifecycle gains blueprint-before-a-large-or-novel-spec: a research-grounded pre-spec blueprint precedes the binding spec for a large / novel / research-dependent slice, so the shape and trade-offs are argued cheaply before a schema and a test list are committed (a small slice skips it). deep-modules gains turn the deletion test on your own proposals: the strongest over-build is the entity or abstraction you are about to author, so run the test on your own new module before presenting it, not only on existing code. threat-model gains SSRF as a first-class abuse case for any stage that fetches a web-discovered URL: scheme allow-list, deny the resolved internal / metadata IP re-checked per redirect hop, no internal egress from a headless render of untrusted pages, and stream-and-abort resource bounds. All three came from a real session where the gate review repeatedly caught what a first draft missed.
• v1.7 Resilience + infra-hardening rules, and two adapted skills. New resilience-engineering rule: degrade-don't-die patterns (timeouts, circuit breaker, bulkhead, load-shed, designed degraded modes, kill-switch, bounded jittered retry), extending queue-failure-handling from the async path to the in-request path. New infra-hardening rule: the running surface is least-privilege and pinned (non-root, digest-pinned scanned images, minimal runtime identity, remote+locked IaC state with plan-as-gate, federated short-lived deployer), the runtime counterpart to cicd-supply-chain-hardening. Two skills vendored and adapted: improve-codebase-architecture (deepen shallow modules) and grill-plan (stress-test a plan against existing bindings), rewired to the scaffold's rules and workflow rather than installed wholesale. This raised the bias: a strong, comprehensive scaffold over a minimal one, cherry-picking generously but adapting every import to the house conventions.
• v1.6 Deep-module discipline + an ADR gate, cherry-picked from a skills review. New deep-modules rule: depth over module count, the vocabulary (module / interface / depth / seam / adapter) and the heuristics (deletion test, interface-is-the-test-surface, one-adapter-is-hypothetical-two-make-it-real, no speculative abstraction for a single implementation). It is the concrete form of the principal-engineer simpler-shape test. decision-guards gains a three-criteria gate for when a decision earns a DECISIONS.md/ADR entry (hard to reverse AND surprising-without-context AND a real trade-off), keeping the log small so the markers stay forceful. Adopted as rules, not as vendored skills: the value is the heuristics and the artifact-discipline, and the interactive procedures already exist in our Explore agent + brainstorming + the gate reviewers; per plugin-and-skill-adoption, cherry-pick the idea, do not install wholesale.
• v1.5 Eight disciplines adopted from a senior-engineering-partner skill review. phase-aware-rigor-ladder: effort tiers (prototype / MVP / production) with a security floor constant at every tier and named promotion triggers. epistemic-discipline: verify environment claims from a tool run this turn, never invent flags / paths / APIs, mechanize anything checkable in a script. eval-guards-a-lesson: every lesson bound from a real miss ships the regression check that would have caught it, so it cannot silently regress. secret-rotation-lifecycle: zero-downtime rotation, KEK re-wrap, rotation as a gated action. data-protection-as-code: DSAR export, cascading erasure, job-enforced retention, DPIA. disaster-recovery: immutable tested backups (3-2-1-1-0), verified PITR, restore drills, named RTO/RPO. cicd-supply-chain-hardening: least-privilege permissions, digest-pinned actions, SBOM + provenance + signing, short-lived OIDC. leakage-guard: keep the portable core free of secrets and environment identifiers, enforced by a two-tier CI denylist. Stack-specific references from the source skill (GCP, Terraform, Apps Script, FastAPI, macOS) were deliberately not adopted; the scaffold stays agnostic.
• v1.4 Platform findings + output-math binding + a checklist-honesty fix. New platform-findings-backstop rule: each platform emits its own security and quality findings (the code host's scanner, dependency and secret scanning, the database or host linter, the cloud security advisor) out of band from our CI, and we consume them as a standing backstop, triaged like the threat model, trust-boundary criticals escalated, never left unread; the discipline is the invariant, the tools are per-architecture, name your own platforms and do not inherit a vendor. New output-math-requires-binding rule: the build agent never introduces or changes output-affecting math (ranking / scoring formulas and weights, calibration, thresholds, filters, precedence) without a bound spec and a human bind, it proposes and hands off; the numbers a user reads are a bound decision, not a build-time edit. spec-lifecycle gains a checklist-honesty clause: a gate-checklist line is written only from a review that has run and returned, never pre-filled with an expected verdict, a BLOCK is resolved and re-run before any box is checked, and the BLOCK-then-resolved history is recorded not hidden.
• v1.3 Security review as its own gate (§3, Appendix C). New security-reviewer sub-agent owns the end-to-end boundary lens no other gate held (it is how an authenticated-dispatch envelope got dropped on a transport change and slipped five lenses); wired into the auto-chained pipeline for any security-relevant surface. New SECURITY-HARDENING.md: the standing security goals (authenticated boundaries, read-visibility separated from write-authority, definer-function hardening, call-site authZ, named staff predicate, secrets in the store, untrusted-input-stays-data, idempotency) every project's goal tree adopts. New no-fake-data rule and a wireframe-port-audit clause: live surfaces render real data with honest empty states, the wireframe is the visual target only; a ported sample value is a deviation. Build invariant 1 generalised: the signed envelope rides every dispatch into compute (queue or HTTP), and read-visibility never grants writes.
• v1.2 Continuous checkpoint mode (§4): the build agent auto-commits WIP: checkpoints with a structured body (decisions, remaining work, rejected approaches), reconstructs session state from them on crash or resume, and filter-squashes them before the PR; local by default. From the gstack review.
• v1.1 Adopted from two pattern reviews (the augmented-coding-patterns catalog, and gstack). Context markers and dialogue habits (you-do-it, reverse-direction) in the operating model (§1). Decision guards, DEC-NN markers over a root DECISIONS.md (§3). doc-drift-on-ship, a ship reconciles the docs the diff drifted (§8). Auto-chained review pipeline at spec promotion (§3). Audit output discipline, zero-noise: confidence bar, exploit scenario, independent verification (§9). Retro cadence and template (§10): each participant answers independently, the confluence becomes new bound ways of working. Git bindings made explicit in §1: the build agent commits both sides, the human never touches git, closed nodes are immutable.
• v1 Baseline: the two-agent boundary, the goal-tree handoff with no separate board, spec lifecycle with gate reviews, the CI spine, schema and tenancy discipline, the LLM gateway and agent / deterministic boundary, the rules library and sub-agent roster.

The Project Agent Scaffold · v3.0 · recreated as the agnostic blueprint for a reusable three-function operating system. Names are placeholders; the disciplines are the deliverable. No em-dash used, per house style. This HTML is the blueprint; the folder is generated from it. MIT licensed, see LICENSE. Provided as is, without warranty of any kind: use at your own discretion and risk. Author: Martin Molenkamp.