McRitchie Agent Entry

This is the canonical source for the generated projects-root AGENTS.md.
McRitchie Studio owns this file so the agent operating model survives a wiped local machine and can be restored from GitHub.

Paths below are written for the generated file at /Users/alex/projects/AGENTS.md.

SOP Invocation Standard

SOPs are first-class registered commands in this workspace. The set is finite,
the names are stable, and every SOP name maps to a repo file. Do not treat an SOP
name as ordinary prose, generic GitHub triage, or a broad workflow request.

McRitchie operating procedures are normal repo docs, not installed skills. When
Mr. McRitchie names an SOP or heartbeat act such as pr-review, qa-release,
production-deploy, or full-cycle, resolve that phrase through the SOP
registry and directory convention here, read the mapped SOP, then execute it.

SOP locations:

Agent heartbeats live at mcritchie-studio/docs/agents/agents/<agent>/HEARTBEAT.md.
Agent-specific SOPs live at mcritchie-studio/docs/agents/agents/<agent>/sops/<sop>.md.
Shared primitives live under mcritchie-studio/docs/agents/modules/.

Invocation rule:

Open the required trajectory activity.
Resolve the invocation in the finite registry below, including legacy aliases.
Read the mapped HEARTBEAT.md or SOP file before queue inspection, --help probing, GitHub PR discovery, or tool/plugin selection.
Execute the procedure in that file. If it points to a shared primitive, read that primitive next.

SOP files stand alone. Each SOP is executable start-to-finish from its own
file — every command, gate, and decision rule is inline. An SOP may reference
only: (1) other registered SOPs at composition seams, (2) a registered shared
primitive such as modules/pr-review-sop.md, exactly one hop, and (3) an
explicitly marked "Background — not needed to execute" section. Design docs
such as system/devops-cycle-design.md are architecture — the why, never a
required execution path. Do not follow a Background reference to run an SOP.

Invocation	Owner	Read first
`pr-review`	Avi	`mcritchie-studio/docs/agents/agents/avi/sops/pr-review.md`
`pr-review-slow`	Avi	`mcritchie-studio/docs/agents/agents/avi/sops/pr-review-slow.md`
`pr-review-primary` (role SOP)	Avi	`mcritchie-studio/docs/agents/agents/avi/sops/pr-review-primary.md`
`pr-review-light` (role SOP)	Avi	`mcritchie-studio/docs/agents/agents/avi/sops/pr-review-light.md`
`production-deploy`	Avi	`mcritchie-studio/docs/agents/agents/avi/sops/production-deploy.md`
`deploy-with-task`	Avi	`mcritchie-studio/docs/agents/agents/avi/sops/deploy-with-task.md`
`Avi Heartbeat`	Avi	`mcritchie-studio/docs/agents/agents/avi/HEARTBEAT.md`
`qa-release`	Steffon	`mcritchie-studio/docs/agents/agents/steffon/sops/qa-release.md`
`qa-deploy`	Steffon	`mcritchie-studio/docs/agents/agents/steffon/sops/qa-release.md`
`archive-shipped`	Steffon	`mcritchie-studio/docs/agents/agents/steffon/sops/archive-shipped.md`
`archive-completed`	Steffon	`mcritchie-studio/docs/agents/agents/steffon/sops/archive-shipped.md`
`Steffon Heartbeat`	Steffon	`mcritchie-studio/docs/agents/agents/steffon/HEARTBEAT.md`
`full-cycle`	Alex	`mcritchie-studio/docs/agents/agents/alex/sops/full-cycle.md`
`grade-events`	Alex	`mcritchie-studio/docs/agents/agents/alex/sops/grade-events.md`
`share-insights`	Alex	`mcritchie-studio/docs/agents/agents/alex/sops/share-insights.md`
`Alex Heartbeat`	Alex	`mcritchie-studio/docs/agents/agents/alex/HEARTBEAT.md`

For pr-review, read Avi's pr-review.md and run the bounded review-only
supervisor described there. Approved work stops at reviewed; Steffon's
qa-release owns merge plus QA.

First Rules

Work from /Users/alex/projects unless Mr. McRitchie gives a different root.
Treat mcritchie-studio as the documentation and bootstrap anchor.
Keep repo-specific facts in the owning repo, but keep cross-repo operating rules here.
In agent docs and handoffs, Alex means the Alex agent/orchestrator. The owner/operator is Mr. McRitchie.
When editing active docs, fix nearby ambiguous references you notice: Alex for the agent/orchestrator, Mr. McRitchie for the owner/operator. Leave historical/archive snapshots alone unless you are already promoting or correcting that file.
Do not print secrets. Use named 1Password references and purpose-built scripts.
Do not hand Mr. McRitchie terminal chores. Run safe commands yourself; ask Mr. McRitchie for approvals, credentials, product judgment, or external access.
Prefer a concrete local result Mr. McRitchie can inspect: a URL, a diff, a passing command, or a short audit.
For feature work, identify the feature being requested and accumulate acceptance criteria until the agent and Mr. McRitchie are in sync on the goal. Do not start implementation from a fuzzy feature request unless the remaining ambiguity is low-risk and explicitly called out.
Worktrees are desks; primary checkouts are loading docks. If you will edit code or app docs, create or enter an isolated worktree with an allocated port before making changes unless Mr. McRitchie explicitly assigns you as the deploy owner for that repo.
A pushed feature branch preserves code. main is for reviewed integration, not backup. Feature agents push their own branch and graduate through PR/QA; review is review-only — Steffon's qa-release sweep merges reviewed work.

📣 Narrate your trajectory — REQUIRED, every session, unprompted

This is how you work here: as you work you MUST narrate your trajectory into
activities — without being asked. Narration is the default, not an add-on; a fresh
session with no explicit prompt still narrates from its first real unit of work.
Your raw tool-calls attribute server-side to whichever activity is currently open, so
a session with no activities reads as a wall of raw tool calls instead of "Explore:
find api issue → found the nil-guard". Do not wait to be told — your FIRST
activity opens BEFORE your first tool call: an Explore (or Plan) "orient" activity —
read the task, scan the code you'll touch — even on a small, pinpointed change. Go
straight to Edit and your orientation strands in the "Unlabeled" bucket, so the
"understand the task" beat is lost. Open the orient activity first, then keep the trail
going to handoff.

Open an activity at each natural work boundary:

bin/agent-activity start --category <Explore|Edit|Verify|Version|Workflow|Delegate|Clarify|Remote|Research|Plan> --reason "what am I doing"

When one unit of work ends and the next begins, roll the boundary in one call
— close the prior activity with its result and open the next together:

bin/agent-activity next --outcome "what just happened" --category <C> --reason "what's next"

Close the final open activity when the work (or the session) is done:

bin/agent-activity end --outcome "what happened"

bin/atomic-event remains a compatibility alias for existing hooks and older docs.
Lead with orient — your opening activity is Explore/Plan and opens BEFORE any tool runs; nothing should land in "Unlabeled" at the top of a session.
Keep activities meaningful — one per unit of work, not one per tool call (navigate cd and the bin/agent-activity/bin/atomic-event narration calls themselves are dropped automatically; opening a new activity auto-closes the prior one).
Stamp the task on your first activity — add --task <slug> to start/next so the activity is task-attributed immediately, instead of a blank TASK until a later bin/task/bind-task write lands. In a feat/<slug> worktree it's inferred from the branch, so --task is mainly for a primary/conductor checkout working a specific task.
Always give a result — every next/end records what actually happened ("Explore: find api issue → found the nil-guard"), not just the intent; an activity without a result is a wasted activity.
Log the activity's key method when it has one — add --key-method "<code>" (+ optional --key-lang bash|ruby|sql|js) to next/end when the completed activity had ONE load-bearing call worth copying — the line another agent (or the operator) would rerun, e.g. --key-method "User.find_by(email: ...)" --key-lang ruby. Most activities have none; skip it rather than invent one. It renders on the heartbeat rows as a copyable chip with a language badge. (Raw bash actions get theirs automatically — the capture hook logs each Bash call's command as its key_method and its description as its goal summary, so keep writing good Bash descriptions.)
Keep --reason/--outcome short (~4-7 words).
It's non-fatal — narration never blocks your work, and it powers the Alex learning heartbeat (/alex/heartbeat). There is no reason to skip it.

DevOps Routing — read before writing ANY code

If your work will produce a code diff — a feature, a bug, or a chore, even a
"small" one — you are a Feature agent and you follow the cycle. There is no
size exemption: "it's just a small change" is exactly when this gets skipped.

Before editing a single file:

Create the production task (bin/task create, or the board UI at https://mcritchie.studio) with kind and shape. The shape auto-selects the tests you must write (config/feature_shapes.yml): ui-only (copy/styling) · ui+db (UI that persists) · backend (job/service, no UI) · library (studio-engine / solana-studio) · onchain (turf-vault / Solana::*) · onchain-vertical (wallet+DB+UI+program).
Allocate an isolated worktree (bin/agent-worktree new <app> <task>) on an allocated port. Do not edit on a primary checkout.
Run bin/session-preflight <task> from the worktree before editing. Fix branch drift, latest blocker feedback, generated-doc drift, stale terminology, or PR overlap it reports before spending implementation time.

While building:

Write the test tiers your shape requires as you go, unit-first — this is how bugs get caught before PR, not after. Record them tier-tagged: bin/task update <task> --checks "[unit] ..." --checks "[integration] ...". For a bug, write the failing regression test FIRST, at the lowest tier that reproduces it.

Before handoff:

Run bin/dor-check <task> and fix whatever it flags — it refuses an under-tested PR.
Commit on the feature branch, push, open a PR into release (base release, not main) whose body leads with the task URL, then bin/task move <task> submitted.

The task lifecycle is two workflows (full spec:
docs/agents/system/devops-cycle-design.md):

Build (feature agent) — designed → building → submitted. You own designed through submitted (the seam); opening the PR hands off to DevOps.
Deploy (DevOps) — submitted → reviewed → assembled → shipped. Every repo keeps a persistent release branch (feature PRs target it, never main). Review is review-only: the submitted PR is approved → reviewed, or bin/task block <task> --kind rework --feedback "…" (back to you) — nobody merges at review. Steffon's self-healing qa-release sweep (bin/release prepare) merges reviewed tasks + assembled stragglers into release (stamping merged: "release"), deploys QA, and flips members assembled only on QA-green. Avi's production-deploy (bin/release ship) fast-forwards each repo's release → main (stamping merged: "main") → shipped.
blocked is the "not in the pipeline's court" side state (env blocker, QA rework, or a dependency); archived is terminal.

Sizing the work — the po/dev/actual trio. Avi is the default sizer: he sets
po_size when he creates and grooms the task (bin/task create … --po-size small|medium|large|xl). It is a forecast, not a hard gate — a task can be
created without one and backfilled later (bin/task update <task> --po-size …).
The per-task Pokémon stamps its own dev_size as it CLAIMS the task (bin/task move <task> building --dev-size <size>; optional). At ship, actual_size
auto-derives from the task's MEASURED usage (total tokens across its
TaskEvents, bucketed by Task::ACTUAL_SIZE_THRESHOLDS) — only when blank, never
clobbering a manual size. The trio (PO forecast vs. dev forecast vs. measured
actual) powers the sizing intelligence dashboard.

The task slug is the genesis. Creating it in step 1 trickles down to
everything: the worktree (bound by slug), the task URL
(https://mcritchie.studio/tasks/<slug>), and the terminal feature indicator —
bin/task writes the active-feature marker the status line reads (a worktree
session overrides it via its own .agent-context.json). Announce it every
session, not on request: open with one line — <app-slug> · <feature-slug> · <task URL> — so the active feature is visible in any tool (Claude's status bar,
Codex's output; the terminal auto-links the URL), and restate the task URL at
handoff.

Never push to main, merge, deploy, or publish gems unless Mr. McRitchie
assigns you that lane in this session. Full SOP + the two-workflow release model:
mcritchie-studio/docs/agents/system/devops-cycle-design.md.

Default Operating Context

Assume Mr. McRitchie starts agent sessions from /Users/alex/projects, and
that a plain feature request should be enough context to begin. The default
launch flow is:

Read this file, then mcritchie-studio/docs/ECOSYSTEM.md.
Identify the target repo and read its README/RUNBOOK/topic docs relevant to the request.
Pull/check main and inspect git status before editing.
If the work is a feature, bug, QA, release, cleanup, or active-doc change, create or update a production McRitchie Studio task-board item before implementation (see DevOps Routing above — no size exemption). Record devops["kind"], devops["shape"] (classifies the required tests), acceptance criteria, affected repos, risk tags, expected checks in devops["test_plan"], and devops["worktree_slug"]. Naming discipline (enforced by the create API): the title is 3-5 words and the slug derives from it (the readable /tasks/<slug> URL; seeds worktree_slug + feat/<slug> — pass --slug only to override); each acceptance bullet is 5-12 words. Put verbose detail/reasoning in --agent-context (free-form, for agent-to-agent communication). Move the task to building once the agent starts work.
If the task will change code or active docs, allocate an isolated worktree from McRitchie Studio and work there. Keep the primary checkout stable for integration, review, and deploys. Bind the generated production task URL to the worktree with bin/agent-worktree bind-task <app> <worktree-slug> <task-slug-or-url> so whereami, terminal context, snapshots, and PR bodies can lead from the task record.
Run bin/session-preflight <task-slug> from the worktree before editing; it surfaces latest task feedback, release-branch drift, PR state, same-file PR overlap, generated-doc drift, stale terminology, and required test tiers.
Use the managed port ranges: McRitchie Studio 3000-3099, Turf Monster 3100-3199, Tax Studio planned at 3200-3299, Rolio reserved at 3300-3399, and Chain Ops planned at 3400-3499.
Build the feature and, before opening the PR, mark any inspectable local UI or workflow as waiting on Mr. McRitchie's approval: bin/task update <task-slug> --local-url http://localhost:<port>/<path> --approval waiting. In chat, return Local Demo: http://localhost:<port>/<path> as a top-level line. For email/auth flows, also return Local Inbox: http://localhost:<port>/_studio/local_emails. Waiting-approval tasks float to the top of their stage and pulse on the board.
If behavior, workflow, env vars, ports, auth, email, deploys, or agent operations change, update the owning active docs in the same pass.
Run bin/dor-check <task-slug> and resolve anything it flags. Then commit and push the feature branch, and run bin/agent-worktree finish <app> <task-slug> to prepare PR/QA handoff. Update the task with branch, PR URL, local URL, tier-tagged devops["checks_run"] (e.g. [unit] ..., [integration] ...), and any changed acceptance criteria, then move it to submitted. Handoffs should include the task URL before the PR URL. Deploy or merge only when Mr. McRitchie assigned that lane or the task explicitly includes production rollout.

For a new feature session, Mr. McRitchie should only need to say the target app
and the feature. A good prompt is:

Work from /Users/alex/projects. Build this feature in <app>: <feature>.
Create the production McRitchie Studio task FIRST with kind=feature, the shape
(ui-only|ui+db|backend|library|onchain|onchain-vertical), acceptance criteria,
affected repos, risk tags, and expected checks in devops["test_plan"]. Use an
isolated worktree and allocated port before editing. Run bin/session-preflight
<task> from the worktree and fix any blockers it reports before implementation.
Write the test tiers your shape requires as you go (unit-first); record them
tier-tagged in devops["checks_run"]. Before PR handoff, mark local validation
with `bin/task update <task> --local-url http://localhost:<port>/<path>
--approval waiting`, return `Local Demo: http://localhost:<port>/<path>` in
chat, and wait for approval or requested changes. Update docs if behavior
changes. Before handoff run bin/dor-check <task> and fix what it flags, then
commit, push the branch, open a PR led by the task URL, and move the task to
submitted for Avi QA. Do not merge or deploy unless I explicitly assigned that
lane.

Start Here

Need	Read
Ecosystem map	`mcritchie-studio/docs/ECOSYSTEM.md`
Fresh-machine rebuild	`mcritchie-studio/docs/agents/system/house-burn-down.md`
Ecosystem build script	`mcritchie-studio/docs/agents/system/ecosystem-build.md`
Agent culture	`mcritchie-studio/docs/agents/modules/culture.md`
Credentials and 1Password	`mcritchie-studio/docs/agents/modules/credentials.md`
Credential item names	`mcritchie-studio/docs/agents/modules/credential-inventory.md`
Shared email operations	`mcritchie-studio/docs/agents/modules/email-operations.md`
Managed app registry	`mcritchie-studio/docs/agents/modules/app-registry.md`
New app onboarding (tiers + SOP)	`mcritchie-studio/docs/agents/system/new-app-onboarding-sop.md`
Ports, servers, callbacks	`mcritchie-studio/docs/agents/modules/ports-and-processes.md`
Parallel DevOps and QA graduation	`mcritchie-studio/docs/agents/modules/parallel-agent-devops.md`
Modular PR review SOP	`mcritchie-studio/docs/agents/modules/pr-review-sop.md`
Heartbeats (three soul launchers)	`mcritchie-studio/docs/agents/modules/heartbeats.md`
Avi heartbeat launcher	`mcritchie-studio/docs/agents/agents/avi/HEARTBEAT.md`
Avi production deploy SOP	`mcritchie-studio/docs/agents/agents/avi/sops/production-deploy.md`
Avi PR review SOP (supervisor)	`mcritchie-studio/docs/agents/agents/avi/sops/pr-review.md`
Avi slow PR review SOP	`mcritchie-studio/docs/agents/agents/avi/sops/pr-review-slow.md`
Avi primary reviewer role SOP	`mcritchie-studio/docs/agents/agents/avi/sops/pr-review-primary.md`
Avi light reviewer role SOP	`mcritchie-studio/docs/agents/agents/avi/sops/pr-review-light.md`
Avi deploy with task SOP	`mcritchie-studio/docs/agents/agents/avi/sops/deploy-with-task.md`
Steffon heartbeat launcher	`mcritchie-studio/docs/agents/agents/steffon/HEARTBEAT.md`
Steffon QA release SOP	`mcritchie-studio/docs/agents/agents/steffon/sops/qa-release.md`
Steffon archive shipped SOP	`mcritchie-studio/docs/agents/agents/steffon/sops/archive-shipped.md`
Alex heartbeat launcher	`mcritchie-studio/docs/agents/agents/alex/HEARTBEAT.md`
Alex grade events SOP	`mcritchie-studio/docs/agents/agents/alex/sops/grade-events.md`
Alex share insights SOP	`mcritchie-studio/docs/agents/agents/alex/sops/share-insights.md`
Alex full cycle SOP	`mcritchie-studio/docs/agents/agents/alex/sops/full-cycle.md`
DevOps task-board handoff	`mcritchie-studio/docs/agents/modules/devops-task-board.md`
Task-board API (auth + contract)	`mcritchie-studio/docs/agents/modules/task-board-api.md`
Parallel agents and worktrees	`mcritchie-studio/docs/agents/modules/worktrees.md`
LLM adapter policy	`mcritchie-studio/docs/agents/modules/llm-adapters.md`
Codex runtime updates	`mcritchie-studio/docs/agents/modules/codex-updates.md`
Backend discipline	`mcritchie-studio/docs/agents/modules/backend-discipline.md`
Tests	`mcritchie-studio/docs/agents/modules/testing.md`
Deploys	`mcritchie-studio/docs/agents/modules/deployment.md`
Keeping docs clean	`mcritchie-studio/docs/agents/modules/docs-maintenance.md`
Memory maintenance	`mcritchie-studio/docs/agents/modules/memory-maintenance.md`
Result distillation (findings not raw ops)	`mcritchie-studio/docs/agents/modules/result-distillation.md`
Audit playbook	`mcritchie-studio/docs/agents/modules/audit-playbook.md`
Shared SES production proof	`mcritchie-studio/docs/agents/audits/ses-production-proof-2026-06-14.md`
Current final closeout	`mcritchie-studio/docs/agents/audits/final-closeout-2026-06-17.md`
Session retrospective	`mcritchie-studio/docs/agents/audits/session-retrospective-2026-06-17.md`
Prior final audit	`mcritchie-studio/docs/agents/audits/fresh-final-audit-2026-06-15.md`
Prior ecosystem closeout	`mcritchie-studio/docs/agents/audits/final-closeout-2026-06-14.md`
Latest ecosystem audit	`mcritchie-studio/docs/agents/audits/broader-ecosystem-audit-2026-06-14.md`
Delete later ledger	`mcritchie-studio/docs/agents/maintenance/delete-later.md`

SOP Registry

This table repeats the top-level SOP registry for agents that jump straight to
the reference section. SOP invocations are plain text prompts, not installed
skills. When Mr. McRitchie says one of these phrases, read the owning soul's
HEARTBEAT.md when the phrase is a heartbeat launcher, then read the specific
SOP file linked below. A heartbeat may set agent attribution and choose the act
order, then it references the SOP. The SOP files are independent and do not
depend on the heartbeat.

Invocation	Owner	Read
`Avi Heartbeat`	Avi	`mcritchie-studio/docs/agents/agents/avi/HEARTBEAT.md`
`production-deploy`	Avi	`mcritchie-studio/docs/agents/agents/avi/sops/production-deploy.md`
`pr-review`	Avi	`mcritchie-studio/docs/agents/agents/avi/sops/pr-review.md`
`pr-review-slow`	Avi	`mcritchie-studio/docs/agents/agents/avi/sops/pr-review-slow.md`
`pr-review-primary` (role SOP)	Avi	`mcritchie-studio/docs/agents/agents/avi/sops/pr-review-primary.md`
`pr-review-light` (role SOP)	Avi	`mcritchie-studio/docs/agents/agents/avi/sops/pr-review-light.md`
`deploy-with-task`	Avi	`mcritchie-studio/docs/agents/agents/avi/sops/deploy-with-task.md`
`Steffon Heartbeat`	Steffon	`mcritchie-studio/docs/agents/agents/steffon/HEARTBEAT.md`
`archive-shipped`	Steffon	`mcritchie-studio/docs/agents/agents/steffon/sops/archive-shipped.md`
`archive-completed` (legacy alias)	Steffon	`mcritchie-studio/docs/agents/agents/steffon/sops/archive-shipped.md`
`qa-release`	Steffon	`mcritchie-studio/docs/agents/agents/steffon/sops/qa-release.md`
`qa-deploy` (legacy alias)	Steffon	`mcritchie-studio/docs/agents/agents/steffon/sops/qa-release.md`
`Alex Heartbeat`	Alex	`mcritchie-studio/docs/agents/agents/alex/HEARTBEAT.md`
`grade-events`	Alex	`mcritchie-studio/docs/agents/agents/alex/sops/grade-events.md`
`share-insights`	Alex	`mcritchie-studio/docs/agents/agents/alex/sops/share-insights.md`
`full-cycle`	Alex	`mcritchie-studio/docs/agents/agents/alex/sops/full-cycle.md`

Repos

Repo	Role	Local port
`mcritchie-studio`	Flagship hub, SSO source, recovery scripts, agent docs	3000
`turf-monster`	Sports pick'em satellite, payments, Solana integration	3100
`rolio`	Release-managed standalone with reserved satellite range	3300
`chain-ops`	Planned Solana localnet/QA/node operations control plane	3400
`studio-engine`	Shared Rails engine for auth, theme, error logs, SSO	none
`solana-studio`	Ruby Solana primitives	none
`turf-vault`	Anchor smart contract	none

Session Shape

Read this file first.
Read only the modules relevant to the task.
Check git status before editing.
If editing code or active docs, create or enter the task worktree first.
Make scoped changes in the correct repo or worktree.
Run meaningful verification yourself.
Hand back something inspectable: local URL, screenshot, test output summary, diff summary, or explicit blocker.
Update docs when behavior or workflow changes.

Parallel Work Quick Start

Concurrency cap — 5 at a time. Cap parallel work at 5 concurrent
operations per session — at most 5 agents / heroku run dynos / parallel
board-writing commands in flight at once. The prod board Postgres (essential-0)
has a 20 hard-connection limit, and a heavy fan-out (parallel review agents +
the ship's heroku run dynos + bin/task/bin/release CLI + web/worker pools)
once spiked past it → FATAL: too many connections → the board briefly 500'd.
Parallelism stays first-class (fan-out is still the default for devops) — just
bounded: fan out reviews and any other batch in waves of ≤5, never all at
once; when a queue is larger than 5, run it in successive waves.

For feature work, active-doc edits, or any task that might be committed, start
from McRitchie Studio, create or update the task-board item, then allocate a
worktree:

cd /Users/alex/projects/mcritchie-studio
bin/agent-worktree plan turf-monster task-slug
bin/agent-worktree new turf-monster task-slug
bin/agent-worktree bind-task turf-monster task-slug task-abc123def456
bin/session-preflight task-slug
bin/agent-worktree up turf-monster task-slug
bin/agent-worktree finish turf-monster task-slug

Return the printed http://localhost:<port> URL in the handoff.

Every feature or bug cycle must have a production McRitchie Studio task before
code or active-doc edits start. Keep the title 3-5 words (the slug derives
from it — the readable task URL — and seeds metadata["devops"]["worktree_slug"]
+ the feat/<slug> branch; --slug overrides) and each acceptance bullet
5-12 words; verbose detail goes in devops["agent_context"]. Bind the task
URL to the worktree.
Use metadata["devops"] to record affected repos, branch, PR URL, local URL,
QA URL, production URL when deployed, release slug, risk tags, acceptance
criteria, test plan, checks run in devops["checks_run"], and
approval_status when waiting for Mr. McRitchie's local validation.
bin/qa-intake helps Avi discover PR/worktree state, but it does not replace
the task-board record.

Primary checkouts are for reading, status checks, integration, and deployment.
Do not commit task work from a primary checkout unless you are explicitly acting
as the deploy owner. If a primary checkout becomes dirty or moves while you are
working, report the changed floor and continue from your worktree.

For local validation chat, use exact top-level labels so Mr. McRitchie never has
to hunt through prose:

Task: https://mcritchie.studio/tasks/<task-slug>
Local Demo: http://localhost:<port>/<path>

For email or auth flows, also return the printed local inbox:

Local Inbox: http://localhost:<port>/_studio/local_emails

Worktree stacks default to LOCAL_EMAIL_CAPTURE=1, so magic links and other emails are recorded there instead of sent to real inboxes.

Feature work graduates through PR/QA, not direct main pushes. Use
bin/agent-worktree finish <app> <task-slug> --push --pr when the branch is
ready for Avi review. The same handoff must update the task with the branch,
PR URL, local URL, and devops["checks_run"], then move the task to
submitted. Keep the worktree and branch until Avi confirms the PR was merged
or intentionally abandoned.

For a dedicated review/QA session, use the recurring QA intake prompt in
mcritchie-studio/docs/agents/modules/parallel-agent-devops.md. That cycle
stops after QA deployment; production rollout needs a separate explicit prompt
(production-deploy, or Alex's ship-authority full-cycle).
The conductor queue starts with:

cd /Users/alex/projects/mcritchie-studio
bin/qa-intake --refresh --apps mcritchie-studio,turf-monster,rolio

The command joins open GitHub PRs to the local worktree registry and labels
items as avi-ready, avi-ready-draft, checks-review, merge-risk,
needs-agent, missing-local-branch, or ready-to-open-pr. Each queue item
also prints an action: line; use it as the next owner handoff.

QA servers, once provisioned, are operated with mcritchie-studio/bin/qa-server.
They are release-candidate targets for Mr. McRitchie review before production;
production deploy remains separately ship-authority gated.

Before reusing or deleting worktrees, inspect lifecycle state:

bin/agent-worktree list
bin/agent-worktree doctor
bin/agent-worktree snapshot --write
bin/qa-intake --refresh --apps mcritchie-studio,turf-monster,rolio
bin/agent-worktree cleanup
bin/agent-worktree cleanup --reclaim [--yes]
bin/agent-worktree remove <app> <task-slug> --yes

snapshot --write refreshes the local non-secret worktree registry at
/Users/alex/projects/.agents/worktree-registry.json for QA/conductor
sessions. cleanup is dry-run only; cleanup --write only appends candidates
to the delete-later ledger. Actual removal stays approval-gated and should use
bin/agent-worktree remove <app> <task-slug> --yes so stack stop, ledger
update, Git worktree removal, local branch deletion, and registry refresh happen
together. cleanup --reclaim is the scale-down-on-close batch flow: the dry run
lists every worktree SAFE to auto-release (clean + merged/main-equivalent, never
the primary) with its Redis DB, and cleanup --reclaim --yes runs that same full
remove teardown for each candidate, then shrinks the Redis band toward the
floor. See mcritchie-studio/docs/agents/modules/worktrees.md.

The worktree launcher uses an elastic Redis band starting at DB 9. The band
idles at 20 slots, auto-grows by 10 (restart-free) when full while physical
room remains, and auto-shrinks by 10 (never below 20) as worktrees close
(remove, cleanup --write, and cleanup --reclaim --yes all trigger the
shrink).
Physical capacity is the Redis databases setting, fixed at startup; the band
can never exceed it. Inspect both with bin/agent-worktree scale status. If the
band is capped by physical room, run bin/agent-worktree scale --provision once
to raise Redis databases (this restarts Redis and bounces every running stack;
leave it for the QA/infra lane).

LLM Adapters

A generated root CLAUDE.md adapter is required because Claude Code auto-loads
that file, not AGENTS.md. Keep it thin: inline the DevOps gate, then @AGENTS.md.
Do not create root CODEX.md; Codex reads AGENTS.md natively. See
mcritchie-studio/docs/agents/modules/llm-adapters.md.

McRitchie Studio