Agentic Development Adoption Runbook

How to use this document. Give this page to a capable coding agent (Claude, Codex, or another) in a fresh session on the target repository with an instruction like:

"Follow the agentic adoption runbook to make this project AI-friendly. Work the Phase 0 prerequisite sequence in order (0A security preflight, 0B assessment, 0C baseline), report your scorecard and a tailored plan, and wait for my approval before writing anything."

The runbook distills the patterns proven in the Constellation platform into a phased checklist. Throughout, distinguish the portable control (what must be true, in any stack, with any agent) from the adapter (the tool-specific mechanism that implements it — a Claude skill, a Codex TOML agent, a CI script). Constellation is a TypeScript/Next.js/Turborepo/Postgres monorepo driven primarily by Claude Code; when a mechanism doesn't fit the target project, preserve the control and substitute the adapter. Constellation-specific choices below are reference patterns with selection criteria, not mandates. The document's order is executable: the prerequisite sequence (0A → 0B → 0C) runs first and in that order — a linear agent run must not inspect client code or change the workflow before its gates — then the maturity phases (1–11) follow, ordered by value-per-effort; you can stop after any maturity phase and still have a coherent setup.

Related: the Agent starter kit scaffolds a new or empty repo onto Constellation's coordination layer in minutes. This runbook is the complement — it retrofits an existing codebase's practices, docs, and CI for agentic development, whether or not it uses Constellation.

The eight principles (read first)

Every checklist item below exists to serve one of these. When adapting to a project where a specific mechanism doesn't fit, preserve the principle and substitute the mechanism.

Layer documentation by rate of change. Unchanging architectural invariants (a constitution) live separately from the weekly-changing operational playbook (AGENTS.md), which lives separately from on-demand topic deep-dives (skills) and per-module locals. Agents read cheap, stable layers first and load detail only when needed.
Critical deterministic invariants are mechanically enforced; judgment-based standards are evaluated through structured review, evidence, and outcome metrics. Every rule that can be machine-checked gets a CI gate — including checks that validate the agent-guidance docs themselves — because rules enforced only by prose drift within weeks. Rules that can't be reduced to a deterministic check (design quality, spec completeness, risk judgment) get a structured review role and measurable outcomes instead, not a pretend gate.
Memory compounds or the team re-learns. Corrections from code review and post-merge fixes go into an append-only lessons log that every future session reads. A curator process keeps it short and fresh.
Agents operate within explicit ownership, permission, and concurrency boundaries. Every change has one integrating owner; parallel work is limited to demonstrably disjoint scopes. Subagent definitions carry explicit edit-scope rules and refuse out-of-scope work; planning is a separate (read-only) role from implementing. Constellation's default is one agent, one module, one PR — legitimate cross-module changes get a single integrating owner who delegates bounded slices.
Spec before implementation, with traceability. Non-trivial changes get a written spec first; each acceptance criterion carries a machine-checkable anchor into the code that implements it.
Humans hold merge authority. Green CI, converged reviews, and resolved threads are necessary — never sufficient. An agent presents evidence and waits for explicit human approval. Production deployment, credential changes, destructive actions, and client communications are authorized separately from code merge.
Orientation must be cheap. A task-router table, an "orient" command, and canonical-ID files mean an agent gets productive in one read instead of scanning the repo.
Escape hatches are explicit, strict, and governed. Every bypassable gate has a documented [skip X]-style marker, matched strictly (own-line in PR bodies) so that documenting the bypass never triggers it — and each use carries a reason, lands in the auditable PR record, and shows up in skip-rate reporting. Security and data-isolation gates get no PR-text bypass at all.

The agent-adapter matrix

The controls below are agent-neutral; this table maps each to its concrete adapter for the two agent families we run today. For any other agent, find (or build) the equivalent — the control column is the requirement.

Portable control	Claude Code adapter	Codex adapter
Durable repo guidance, discoverable	`CLAUDE.md` (or symlink to `AGENTS.md`); per-directory locals	`AGENTS.md` natively — root-to-cwd chain, closer files override; combined budget `project_doc_max_bytes` defaults to 32 KiB, so keep it lean
On-demand topic knowledge (skills)	`.claude/skills/<topic>/SKILL.md` (`name` + trigger-oriented `description`)	`.agents/skills/<topic>/SKILL.md` — same frontmatter contract; matched from the `description`
Bounded subagent roles	`.claude/agents/<name>.md` (frontmatter: `name`, `description`, `tools`, model)	`.codex/agents/<name>.toml` (`name`, `description`, `developer_instructions`; optional model, reasoning effort, sandbox, MCP, skills)
Execution policy (sandbox/permissions)	permission modes + `.claude/settings.json`	`.codex/config.toml` — sandbox mode, approvals, network, MCP, model defaults; reviewers start `read-only`
MCP server wiring	project `.mcp.json` (copied per worktree)	MCP servers declared in trusted `.codex/config.toml` — no `.mcp.json`; reload after provisioning
Lifecycle hooks (DX, not the control)	`.claude/settings.json` hooks (`SessionStart`, `PreToolUse`, …)	`.codex/hooks.json` / hooks in `.codex/config.toml`; project hooks require explicit trust
Cross-model / second-opinion review	drives `codex review` via CLI/MCP	`codex review --base origin/<branch>` (no custom prompt with `--base`/`--commit`/`--uncommitted`)

Keep the agent-docs CI gate (Phase 7) aware of the adapters you actually ship: it should verify that referenced paths resolve and that the combined instruction payload stays within each agent's discovery budget (e.g. Codex's 32 KiB default).

Phase 0A — Security and data-governance preflight (human)

For any client-owned or client-adjacent project, close this gate before an agent reads the repository at all — an agent read is already a data-handling event (repository content enters model context), which is why this preflight is physically first. It is human-run: every item below can be answered from contracts, policy, and infrastructure configuration, with no repository access required. These are controls, and most have no PR-text bypass. Until 0A clears, an agent may work only from pre-approved metadata the human supplies (repo name, stack, tracker, CI provider).

Data classification. What client data lives in the repo, fixtures, tickets, and logs; what an agent may read, store in context, or send to a model provider.
Approved models and providers. Which model/provider pairs are contractually approved for this client; retention/training and data-residency terms verified — not assumed.
Secrets and PII rules. Where secrets live, what the agent may never echo into transcripts/PRs, secret-scanning in CI.
Least-privilege tooling. Agent tokens scoped to the minimum surface (repo, tracker project, environments); no shared human credentials.
Sandbox and network policy. Read-only for reviewers; workspace-scoped writes for implementers; network disabled unless the task requires an approved destination.
Prompt-injection handling. Content from tickets, web pages, and third-party docs is data, not instructions; the workflow states how injected instructions are surfaced instead of executed.
Audit and retention. Where agent-run records live (see Phase 11) and how long; who can access them.
Destructive-action approvals and a kill switch. Named human approval for deletes/migrations/deploys; a documented way to stop all agent activity immediately (revoke tokens, disable CI triggers).

Phase 0B — Assess the target project (scored self-assessment)

Runs after 0A. Produce a scorecard, not just an inventory, and report it to the human before writing anything. Do not skip this: the rest of the runbook is parameterized by these answers, and the score — together with the human's recorded judgment — sets how much autonomy the setup can safely grant.

Score each dimension 0 absent / 1 ad hoc / 2 documented / 3 enforced / 4 measured-and-improving, and record per row: evidence (file/link), confidence, risk if left as-is, target score, owner, and next action.

#	Dimension
1	Context and instruction discovery (guidance files, orientation cost)
2	Reproducible development environment (setup, seeds, containers)
3	Work decomposition and specification (tickets, specs, ACs)
4	Tool and tracker access (sanctioned interfaces, auth)
5	Security, privacy, and execution boundaries (sandbox, secrets, data)
6	Testing and verification (taxonomy, coverage of critical paths)
7	Review and merge governance (gates, branch protection, human authority)
8	Learning and knowledge management (lessons, KB, curation)
9	Observability and evaluations (agent-run instrumentation, metrics)
10	Operational resilience and rollback (releases, migrations, kill switch)

Also capture the qualitative facts the phases need: stack and layout; existing agent guidance (CLAUDE.md, AGENTS.md, .cursorrules, CONTRIBUTING.md — consolidate, don't duplicate); the 5–10 architecture invariants that must never be violated (these become the constitution); CI surface and branch protection; task tracker and its API/MCP reachability; review tooling; branching model.

Deliverable: the scorecard + a tailored phase plan ("we'll do Phases 1, 2, 4, 6, 7 now; skip 3 and 9 until there are subagents/MCP") + an explicit readiness level the human signs off with recorded rationale: read-only analysis → planning and recommendations → local implementation → PR creation → limited autonomous maintenance. The score informs the level; it does not decide it — and levels carry non-compensating floors (e.g. "PR creation" requires at least 2 (documented) on dimensions 5, 6, 7, and 10 — security, testing, governance, rollback — no matter how strong the other scores are; documentation maturity never compensates for weak verification or rollback). Production deployment, credential changes, destructive actions, and client communications remain separately authorized at every level. Get human sign-off before Phase 0C.

Phase 0C — Baseline capture

Before any workflow change, capture the pre-adoption baseline — otherwise Phase 11 has nothing honest to compare against. Record, over a recent representative window and segmented by task class: cycle time, review rounds and rework/revert rate, incident count, and delivery cadence. Human-supplied numbers or tracker/CI exports are fine; precision matters less than capturing them before Phase 1 changes the workflow. This closes the prerequisite sequence — the maturity phases below may begin.

Phase 1 — The documentation foundation

Goal: an agent cold-starting on a clean checkout can orient in ≤3 file reads, with zero network dependencies.

1.1 `AGENTS.md` — the operational playbook (repo root)

Create AGENTS.md at the repo root as the single operational playbook: process, workflow, commit conventions, tracker coordination, release flow. This file may change weekly.
Keep AGENTS.md canonical and give each agent family its entry point. Constellation's adapter is a symlink (ln -s AGENTS.md CLAUDE.md) — one source of truth, never edited directly. Where symlinks are awkward (Windows checkouts, some packaging systems), a generated minimal CLAUDE.md adapter that points at AGENTS.md is fine — with a CI drift check so the two can't diverge. Codex reads AGENTS.md natively (mind the 32 KiB combined-guidance default).
Include a Document Hierarchy table near the top: every guidance file, its scope, and what it contains (constitution, AGENTS.md, module locals, skills, agents, lessons, specs, ADRs, README). Agents use this to know where a fact should live.
Include a Task router table: "If you are doing X → read these files first → apply these rules." One row per recurring task type (adding an API route, adding a migration, publishing an event, writing tests, cutting a release, …). This is the highest-leverage section in the whole file — it replaces full-document reads with targeted ones.
Include the Pre-Push Checklist: the exact ordered commands that must pass locally before any push (format check, lint/typecheck/build/test, plus every custom gate from Phase 7). Mirror CI exactly — "the pipeline is the contract."
Keep AGENTS.md an index, not an encyclopedia: repo-wide rules and pointers. Topic depth goes to skills (Phase 2); module detail goes to module locals (1.3).

1.2 The constitution — unchanging invariants

Create .ai/constitution.md holding only the architectural invariants from Phase 0B that do not change between releases. Constellation's has 10 articles (tenancy scoping, schema-per-module, no cross-app imports, append-only event contracts, universal audit log, provider abstractions over vendor SDKs, mandatory route wrapping, no any/no swallowed errors, spec-driven development, pipeline-is-the-contract). Write the target project's equivalents.
Open with the authority statement: "Read this file once per session. If any other doc appears to contradict the constitution, the constitution wins and the other doc is the bug."
State the amendment process: changes require an ADR (see 1.4) and a specially-labelled PR. Operational rules stay in AGENTS.md and change freely.
Each article links to the skill/doc that elaborates it, and ends with a "What is NOT in the constitution" section pointing operational topics back to AGENTS.md.
End with a "Reading order for new agents": (1) constitution → (2) recent .ai/lessons.md entries (the corrections the next session is supposed to apply — a lessons log that isn't in the reading order is write-only) → (3) task router → (4) matching skill → (5) module AGENTS.md if inside a module.

1.3 Module-local guidance (monorepos / multi-service repos)

For each module/service: apps/<module>/AGENTS.md (current architecture, key files, local patterns and exceptions to repo rules) with the per-agent adapter beside it (symlinked CLAUDE.md; Codex picks up the local AGENTS.md in its directory chain automatically). Never duplicate repo-wide rules locally.
Optionally add apps/<module>/agentic/standalone-guide.md: a MUST/MUST-NOT single-task playbook with one worked example, the layer call-direction, and the common rookie mistakes for that module. This is the "I have one bounded task, get me productive now" document.

1.4 Decisions and specs directories

.ai/decisions/ — Architecture Decision Records, numbered (015-<slug>.md). Required for constitution changes and any contested architectural choice.
.ai/specs/ — per-feature design specs written before implementation (format defined in Phase 4).
.ai/lessons.md — the append-only lessons log (format defined in Phase 5).

Adaptation notes: In a single-package repo, skip 1.3 and fold everything into root AGENTS.md + constitution. If the team already has an AGENTS.md-like file under another name, converge on AGENTS.md + adapters rather than maintaining two.

Phase 2 — The skills library

Goal: topic-sized knowledge packs that agents load on demand instead of bloating every session's context.

Create one SKILL.md per recurring, gotcha-dense topic. Location is an adapter decision: .claude/skills/<topic>/ for Claude Code, .agents/skills/<topic>/ for Codex (which also reads user- and admin-scoped skill directories) — pick the location(s) matching the agents you run, or maintain the portable set in one place and generate the other. Constellation's set is a good menu to adapt: tenant/auth wrapping, audit logging, release + migrations, spec authoring, spec review, post-impl review, E2E testing, worktree setup, module-specific algorithms, cross-model review, agent output format.
Every SKILL.md starts with YAML frontmatter: name (kebab-case, matches directory) and description (2–4 sentences: what it covers and when to load it — both Claude and Codex select skills from the description, so write the trigger conditions into it and front-load the key use cases).
Keep each skill self-contained and topic-sized (one sitting to read). Long reference material goes in a sibling reference.md the SKILL.md links to.
A skill is the source of truth for its topic: AGENTS.md's router links to it; nothing else re-explains it. When a lesson (Phase 5) generalizes into a rule, promote it into the relevant skill.
Rule of thumb for extraction: when a topic in AGENTS.md exceeds ~2 paragraphs or acquires a second gotcha, move it to a skill and leave a router row behind.

Adaptation notes: For agents with no native skill mechanism, the same content works as docs/topics/*.md linked from the router — the one-topic-one-file, description-carries-the-trigger discipline is the control; the directory is the adapter.

Phase 3 — Subagents (bounded roles)

Goal: planning, implementing, and reviewing are separate roles with enforced boundaries, so parallel work can't collide and reviews can't be self-graded.

Define the roles in your agent's native format — .claude/agents/<name>.md (frontmatter: name, description written so a router can pick it automatically, tools allowlist, optional model) for Claude Code; .codex/agents/<name>.toml (name, description, developer_instructions, plus optional model/reasoning/sandbox/MCP/skills) for Codex. The two formats are not cross-compatible — if you run both families, treat one as source and generate the other, or maintain both under the agent-docs CI gate.
Per-module developer agents (<module>-developer): the core pattern is the Hard rules block:
1. Edit scope — every Edit/Write must land under apps/<module>/ (everything else read-only).
2. Pre-commit self-check — before staging, run git diff --name-only + git status --short; any out-of-scope path means stop, surface, hand back to the coordinator. This self-check is the early warning, not the boundary — the Phase 7 changed-path scope gate is what actually enforces it.
3. Allowed exceptions — an explicit short list (own spec file, changelog fragment, the module's own docs page).
4. No shared-package work — cross-cutting changes are split and delegated to the platform/infra specialist.
Include a per-agent "skills to load on demand" table mapping task shapes to Phase 2 skills.
The lifecycle triad: spec-author (drafts specs; writes no code), spec-reviewer (audits a spec against the constitution + format before implementation; read-only), post-impl-reviewer (audits the finished diff against the spec's ACs + hard rules after; read-only). Reviewers' tool allowlists omit Edit/Write and their sessions run under a read-only permission mode or sandbox (Claude permission mode; Codex sandbox_mode = "read-only") — an allowlist alone is not enough once Bash is granted (shell redirection, sed -i, or git commands can still mutate). Enforce the boundary; don't rely on the honor system.
A coordinator agent (<tracker>-coordinator): read-only planner for "what next / what's blocked / is this in flight" questions. It reads the tracker + repo state, returns a ranked recommendation with a decision point, and delegates to a developer agent only after human approval. It never implements.
A memory-curator agent: only edits .ai/lessons.md — promotes lessons from recent PR threads/commits, dedupes, marks stale. (Cadence in Phase 5.)
Standard structured output for all reviewing agents — the verdict bar: verdict is one of blocked | needs revision | merge-ready, plus required sections Scope / Verdict / Reason / Blockers / Risks / Suggestions / Checklist. Add a small parser script so orchestration can route on the verdict mechanically. Document the schema as its own skill (agent-output-format).
Concurrency rule. Start parallel agents on read-heavy work (exploration, testing, security review, log analysis). Permit parallel writers only for demonstrably disjoint scopes, with one agent owning integration — parallelism costs tokens and coordination, so it must earn its keep.

Adaptation notes: Start with just the triad + one developer agent for the highest-traffic module; add more as parallel agent sessions become common. In single-module repos the developer agent's edit scope is "src/ only, never CI/infra without delegation."

Phase 4 — Spec-driven development

Goal: non-trivial changes are designed in writing first, and every acceptance criterion is mechanically traceable to the code that implements it.

The rule (tune the thresholds to the project): any feature PR (feat:), any change above a size threshold (Constellation uses 3+ files — pick what fits the team's PR granularity), and any change adding a public surface (event, permission, endpoint) requires .ai/specs/SPEC-<ticket-lower>-<3-5-word-slug>.md written before implementation.
Spec format (CI-enforced in Phase 7):
- YAML frontmatter, all required: title, date, summary, task (ticket key), status (Draft | Approved | Implemented | Superseded), surfaces (list of paths the spec will touch — reviewers use this to know what to inspect).
- Required H2 sections: Problem, Decision (with optional ### Alternatives considered), Scope (explicit in/out bullets — the anti-scope-creep tool), Acceptance criteria (numbered), Implementation sketch (file-level outline, not pseudo-code).
AC anchors: every numbered AC ends with one of:
- → path/to/file.ts:symbol — CI verifies the file is in the PR's changed-file set and the symbol exists in the file's contents at HEAD (not a diff-hunk grep — an implementation that edits a function body far from its declaration must still trace);
- → path/to/file.md — non-code file must appear in the diff;
- →  — UI anchor, verified by E2E/manual;
- →  — explicit waiver.
⚠️ Enforce the numbered-list form in the checker and make it fail (or loudly report the traced count) when it parses 0 ACs — Constellation learned that a permissive parser silently passes green while checking nothing.
Status is forward-only (Draft → Approved → Implemented), and Approved — the spec-reviewer gate — is required before implementation begins. A release-time sweep script auto-advances only Approved specs whose ticket has shipped; a shipped ticket whose spec is still Draft is a missing-approval finding the sweep reports, never a silent Draft → Implemented promotion — so statuses stay honest without manual bookkeeping and a skipped approval stays visible.
Optionally: auto-publish merged specs to the team wiki/knowledge base (a small idempotent sync script on merge to the integration branch), with the repo as canonical. Skip until there is a wiki that agents actually query.

Phase 5 — The memory & learning loop

Goal: every review correction becomes a rule the next session applies automatically.

Create .ai/lessons.md with this contract, stated at the top of the file:
- Append-only, newest first, one entry per lesson.
- Entry format: ## YYYY-MM-DD — <one-line rule> then **Context.** (what triggered it, 1–2 sentences), **Rule.** (written to be applicable without the original context), optional **See also.** (PR/commit/doc links).
Wire consumption, not just capture: .ai/lessons.md sits in the Phase 1 reading order (and/or a session-start hook surfaces recent entries), so every new session actually loads the corrections before working.
Add the standing instruction to AGENTS.md: after any PR-review correction or post-merge fix, append a lesson before closing the task. This is the single highest-compounding habit in the whole system — the log captures the ways this codebase differs from public best practice, which no generic rule page covers.
Wire the curation cadence (memory-curator agent from Phase 3): weekly automated pass (opens a chore(memory): curator pass <date> PR promoting lessons from the week's merged PRs, deduping, marking stale entries), once per release, and ad-hoc after painful debugging sessions. The curator only edits .ai/lessons.md; lessons that imply an AGENTS.md/skill/constitution change surface as suggestions for a human-approved follow-up.
Client boundaries on knowledge promotion. A project lesson may contain client code fragments, incident details, or data shapes. Before promoting anything into a shared or cross-client knowledge base: sanitize (no client identifiers, code, or data), classify, keep provenance, respect retention terms, and get an explicit approval. Per-project lessons stay in the project by default.
(Later maturity) A queryable knowledge base — wiki pages with provenance, an ingest queue fed by shipped specs, a "consult the KB before non-trivial tasks, cite the pages you used" rule, and its own honesty loop (mechanical daily lint + per-release LLM judgement pass). Adopt only once the flat-file loop is habitual; the flat files remain the zero-dependency bootstrap layer either way.

Phase 6 — Task lifecycle & git workflow

Goal: every non-trivial change follows the same five steps, and concurrent agent sessions are kept from colliding as far as the mechanisms allow — worktrees isolate local checkouts, and ticket claiming reduces duplicate pickup (eliminating it only if the claim is atomic; see 6.2). The specific conventions here (worktrees, merge method, changelog fragments, synthetic users) are Constellation's reference patterns — each carries its selection criterion.

6.1 The five-step lifecycle (document in AGENTS.md)

Ticket first. Find or create the tracker ticket (search before create), confirm scope + acceptance criteria are written on it, transition to in-progress when starting. Agents implement approved, planned work items — never untriaged intake reports. Map that split to the tracker's own semantics: in Constellation, tasks vs issues are distinct entities; on a GitHub-Issues-only tracker, use a label or status split (an issue becomes implementable once it is triaged and carries acceptance criteria). A bug being fixed now is planned remediation with ACs; an unplanned defect report stays in the intake pile until a human promotes it.
Spec before implementation (Phase 4 rules).
Branch in a fresh worktree (reference pattern — worth it when multiple sessions or a dev server share one machine; a solo repo with one session can plain-branch). Always cut from the up-to-date integration branch identified in Phase 0B (git fetch && git worktree add .claude/worktrees/<slug> -b <type>/<slug> origin/<integration-branch> — develop in Constellation; main/trunk elsewhere), never checkout -b on top of the current checkout. Prerequisite: gitignore the worktree parent directory (e.g. .claude/worktrees/) — or place worktrees outside the repo — otherwise the nested checkout appears as untracked content and a stray git add -A can stage it as an embedded gitlink. Then copy untracked agent-local config (Claude Code's .mcp.json and .env.local as applicable — Codex needs no per-worktree MCP copy, since its servers come from the tracked .codex/config.toml) and install dependencies. Rationale: the main checkout stays usable, no killed dev servers, no two-session collisions.
Required links on the ticket: branch URL, PR URL, spec/wiki URL — in a ## Links block, so any human or agent can navigate the whole change from the ticket.
Cleanup after merge: update local integration branch, git worktree remove, delete the branch, confirm the ticket closed (webhook or manual).

6.2 Git & PR conventions

Branch model: short-lived (under 3 days) feat/* | fix/* | refactor/* | chore/* → integration branch via PR; releases via release/*; hotfixes via hotfix/*. Never push directly to protected branches. Rebase on the integration branch frequently.
Conventional Commits; PR title format <type>(<scope>): <summary> [<TICKET-KEY>]. If the tracker supports it, a webhook auto-closes the ticket on merge from the bracketed key.
Pick one merge method repo-wide and enforce it at the repo level. Constellation uses merge-commit-only because its release branches break under squash; a squash-and-trunk project should keep squash — the control is one method, repo-enforced, not the specific method.
Changelog fragments, not shared-file edits (reference pattern — adopt when parallel PRs conflict on a shared CHANGELOG; skip if the project doesn't keep one): each user-visible PR adds .changeset/<slug>.md (frontmatter: type: Added|Changed|Fixed|Infrastructure|Security; one-paragraph body); a release script renders fragments into CHANGELOG.md and deletes them.
Agent task-claiming (adopt once parallel agent sessions actually happen): agents claim tickets by assigning a synthetic user per agent class (agent+<class>@<domain>); the coordinator filters unclaimed work before proposing. Note this reduces collision risk rather than eliminating it — two sessions querying concurrently can still pick the same ticket before either assignment lands. For true exclusion, make the claim atomic (compare-and-set on the assignee, or a session-specific owner) and treat a lost race as "pick the next ticket".

6.3 The PR review loop (document in AGENTS.md; agents run it autonomously)

Iterate until clean: automated reviewer comments (Copilot/equivalent) → fix or refute each → resolve every thread with a reason (silent resolves forbidden — future readers need the why); static analysis (Sonar or equivalent) high/medium findings fixed, read via API/MCP rather than asking the human to paste them; all CI jobs green.
Cross-model second opinion (strongly recommended): run a different model family (Constellation uses OpenAI Codex in a read-only sandbox) as reviewer on every new source PR — same-model review shares the same blind spots. The convergence protocol: one strong independent review pass → triage every finding (confirmed / refuted / duplicate, with reasons) → fix confirmed ones → one targeted confirmation round on the fixes. Re-run only when the diff materially changes. Post findings as PR review comments anchored to code; resolve threads like any other review; a refuted finding that keeps recurring is a known false positive to record, not a reason to loop. Track the confirmed/refuted/duplicate split per round — it is the review precision metric for Phase 11.
The merge rule, verbatim: when everything is green, present the evidence (checks output, thread-resolution status, review convergence, self-review verdict) and wait for explicit human approval. Green CI is not merge authority, and a pre-authorization lapses if the PR content changes after it was given.

Phase 7 — CI enforcement (the gates)

Goal: every deterministic convention from Phases 1–6 is machine-checked. CI and branch protection are the authoritative controls — hooks (Phase 8) and agent self-discipline are conveniences layered on top. Build gates as standalone scripts (e.g. scripts/check-*.ts) callable both locally (pre-push checklist) and in CI.

Priority order:

Phase 8 — Hooks & automation

Goal: the rituals agents are told to follow fire automatically instead of relying on recall. Hooks are developer experience, not the authoritative control — they run client-side, require trust (Codex project hooks are explicitly trust-gated), and concurrent matching hooks aren't guaranteed to serialize, so the same policies must be backed by the Phase 7 gates.

SessionStart hooks (.claude/settings.json → hooks.SessionStart; Codex: .codex/hooks.json): provision per-worktree config automatically and verify env, especially for hosted/CI agent sessions where the manual ritual can't run. The MCP wiring is adapter-specific: Claude Code reads project .mcp.json (copy/mint it per worktree); Codex loads project MCP servers from its trusted .codex/config.toml instead — no .mcp.json involved. Either way, a session that was already running when config was provisioned must reconnect/reload before the servers appear.
Pre-PR self-review hook (hooks.PreToolUse on Bash): intercept gh pr create-style commands and require the post-impl-reviewer pass first (bypass marker: [skip self-review], own-line rules apply). The verdict bar gets embedded in the PR body inside a collapsible details block.
Scheduled curation: the weekly memory-curator pass (cron/scheduled workflow) and, if a KB exists, its daily mechanical lint. Keep expensive LLM judgement passes deliberate (per-release, human-triggered) rather than cron'd.
Check hook scripts into the adapter's directory and resolve paths so they work from any worktree: Claude hooks in .claude/hooks/, referenced via $CLAUDE_PROJECT_DIR; Codex hooks in .codex/hooks/, resolving the repo root explicitly (e.g. git rev-parse --show-toplevel) since Codex provides no project-dir variable.

Phase 9 — Tracker & tool access (MCP/CLI)

Goal: agents read and write the tracker (and every internal system) through sanctioned, least-privileged, auditable interfaces — and never through direct database access.

Expose the tracker (and other internal systems) to agents via an MCP server and/or a thin CLI — same auth, same surface. If the tracker is a SaaS with an official MCP (Linear, Jira, GitHub), use that; if in-house, build a small one (Zod-validated inputs, one file per tool, shared helpers).
Fallback policy — decide it explicitly. Constellation's choice is strict no-fallback: the MCP/CLI is the only agent-facing interface; a broken tool is a blocker to surface and fix, not to route around — silent fallbacks hide the breakage forever. If the project instead keeps an emergency API fallback, document its scope, who approves its use, and how uses are audited. Direct DB access is never the fallback.
An orientation command (Constellation: pt workspace) returning current user, active initiative, and top in-progress work — the mandated first call of any session that touches the tracker.
Canonical-IDs file (e.g. memory/pt-projects.md): project/board IDs, scope mapping ("which project owns which path"), with the rule never hardcode IDs — resolve via the find tool.
Document the auth-recovery procedure (token rotation → 401 → re-mint ritual) as part of the worktree skill, because it is the #1 "MCP is broken" cause.

Phase 10 — Testing & verification conventions

Goal: agents know exactly which tests to write and which are release-blocking.

Codify the test taxonomy in AGENTS.md: unit (mocked, innermost layer only), integration, property-based where the domain suits (with a minimum-iterations rule), contract tests for shared package/event surfaces. Constellation runs integration tests against a real Postgres because its core invariants (RLS tenancy) only exist there — apply the same criterion: test against real infrastructure wherever the invariant under test lives in the infrastructure, mock where it doesn't.
Tiered E2E: one smoke spec per critical GUI path is a required CI gate; everything else is advisory. Prefer programmatic login/setup over driving auth UI (Constellation mandates it; the selection criterion is flake-vs-coverage — auth UI gets its own dedicated spec, not a repeated prelude). Scope E2E runs to changed modules so docs-only PRs cost nothing.
The verification habit: after implementing, exercise the change end-to-end and present the observed behavior — never "should work" or asking the human to check manually.

Phase 11 — Instrumentation & outcome measurement

Goal: know whether the agentic setup is actually working. CI gates are controls, not instrumentation — this phase adds the measurement layer on top of the pre-adoption baseline captured in Phase 0C.

Record a privacy-safe run envelope per agent task:

run/task ID; task and risk class; repository and base/head SHA;
agent surface/model/reasoning; instruction/skill/config versions;
sandbox/network/tool policy; start/end/cost; human interventions;
check results; review findings and dispositions; merge/revert/incident outcome

Do not store raw prompts or client code by default (Phase 0A terms govern what may be retained at all).

Metrics, reported by task class and risk class — never as one aggregate productivity number: outcome quality (revert/rework rate, incidents traced to agent changes), cycle time, human-intervention rate, cost and latency per task, tool-failure rate, and review precision (the confirmed/refuted/duplicate split from Phase 6.3).
Anti-metrics: lines of code, commit count, and PR count are not success measures — they reward volume, which agents produce effortlessly.
Feed the numbers back: skip-rate reports into gate calibration (Phase 7), review-precision into reviewer prompts and rounds (Phase 6.3), intervention hotspots into new skills and lessons (Phases 2 and 5), and the whole picture into the readiness level (Phase 0B) when deciding whether to widen autonomy.

Rollout guide

Minimum viable (day 1, ~one session): the full prerequisite sequence in document order — 0A security preflight (human, no repo access), 0B scorecard + readiness sign-off, 0C baseline capture — then Phase 1 (AGENTS.md + adapter, constitution, task router, pre-push checklist) + .ai/lessons.md with its format header + the Phase 6.1 lifecycle text + the Phase 6.3 merge rule. This alone changes agent behavior materially.

Week 1: Phase 7's first three gates (PR requirements, spec format, changesets) + Phase 4 spec convention + 2–3 highest-value skills (whatever the target repo's equivalents of "tenant scoping" and "release ritual" are).

Week 2–4: Phase 3 triad + first developer agent, Phase 8 pre-PR hook, AC traceability + agent-docs meta-gate, cross-model review loop, first run-envelope reporting.

Later maturity: coordinator agent, task-claiming, KB layer, curation crons, per-module standalone guides, autonomy widening backed by Phase 11 evidence.

Throughout: write the lesson log entry every time an agent gets corrected — the system's compounding value comes from that loop, not from any single artifact.

Appendix — target directory layout

<repo>/
├── AGENTS.md                      # canonical cross-agent operating rules (weekly-changing)
├── CLAUDE.md -> AGENTS.md         # Claude adapter (symlink or generated + drift check)
├── .ai/
│   ├── constitution.md            # unchanging invariants; ADR to amend
│   ├── lessons.md                 # append-only, newest-first learning log
│   ├── specs/SPEC-<ticket>-<slug>.md
│   └── decisions/NNN-<slug>.md    # ADRs
├── .agents/skills/<topic>/SKILL.md  # portable skills (read natively by Codex)
├── .claude/                       # Claude Code adapters
│   ├── skills/<topic>/SKILL.md    # frontmatter: name + description(trigger)
│   ├── agents/<name>.md           # frontmatter: name, description, tools[, model]
│   ├── hooks/*.sh                 # session-start provisioning, pre-PR review
│   └── settings.json              # hook wiring + permissions
├── .codex/                        # Codex adapters
│   ├── config.toml                # execution policy: sandbox, approvals, network, MCP
│   ├── agents/<name>.toml         # name, description, developer_instructions
│   └── hooks.json                 # lifecycle hooks (trust-gated)
├── .changeset/<slug>.md           # per-PR changelog fragments
├── scripts/check-*.ts             # CI gates, runnable locally
├── memory/<canonical-ids>.md      # tracker IDs + scope mapping
└── apps|packages/<module>/
    ├── AGENTS.md                  # module locals + exceptions
    ├── CLAUDE.md -> AGENTS.md
    └── agentic/standalone-guide.md

The eight principles (read first)​

The agent-adapter matrix​

Phase 0A — Security and data-governance preflight (human)​

Phase 0B — Assess the target project (scored self-assessment)​

Phase 0C — Baseline capture​

Phase 1 — The documentation foundation​

1.1 AGENTS.md — the operational playbook (repo root)​

1.2 The constitution — unchanging invariants​

1.3 Module-local guidance (monorepos / multi-service repos)​

1.4 Decisions and specs directories​

Phase 2 — The skills library​

Phase 3 — Subagents (bounded roles)​

Phase 4 — Spec-driven development​

Phase 5 — The memory & learning loop​

Phase 6 — Task lifecycle & git workflow​

6.1 The five-step lifecycle (document in AGENTS.md)​

6.2 Git & PR conventions​

6.3 The PR review loop (document in AGENTS.md; agents run it autonomously)​

Phase 7 — CI enforcement (the gates)​

Phase 8 — Hooks & automation​

Phase 9 — Tracker & tool access (MCP/CLI)​

Phase 10 — Testing & verification conventions​

Phase 11 — Instrumentation & outcome measurement​

Rollout guide​

Appendix — target directory layout​