How the Build Runs

Blender AI tutor: how the build runs (handoff)

Copied as it stood on 2026-10-12 from the Blender AI tutor plan, and kept up to date here since 2026-10-13. The code, test and production rules moved to the repo's CONTRIBUTING.md, and the Key Decisions to Decisions. The stage's briefs are in project-buddy-worktrees/accounts-briefs/; the retrospectives are on Retrospectives. The Issue pipeline has since replaced the staged build described here.

How the build runs

• The orchestrator only updates this plan, the retrospective log and the briefs, and delegates. Short-lived subagents do all implementation, tests, merges, migrations, deploys and reviews. The orchestrator briefs them, reads their reports and records the results here. This plan holds all the state, so record results here before moving on. A session may be compacted (/compact) or reset (/new) at any time when no async workflow is running; while one runs, only compact, because a new session can't receive its results or steer it. A new session starts by reading this plan, the retrospective log and the stage's briefs.
• Autumn decides (Autumn, 2026-10-12, replacing autonomous mode). The orchestrator doesn't decide questions for her and doesn't start work on its own.
  • Questions: design choices, lanes' out-of-path requests, failed gates and rule conflicts go to her in full: context, options and a recommendation. Work that depends on the answer waits, and the question is listed under Blocked.
  • Starting work: a round, workflow, deploy or stage starts only when she says so.
  • Production data may be lost (no one uses the site yet). Schema changes go only through migrations.
  • Marking decisions: Autumn's rulings are marked "(Autumn, )", with the options she rejected. Earlier rulings marked "(orchestrator, ; Autumn can reverse)" stand until she reverses them.
• Retrospective between stages (Autumn, 2026-10-12): after each stage's cleanup and before the next briefs, write a retrospective to Retrospectives (newest first): what cost time, the code that changed again (refactoring candidates), rule changes (removed, modified, added, aiming for balance), queued refactors, and the orchestrator's decisions. Apply its rule changes here and in the next briefs.
• When a stage closes, collapse its entry to the outcome, the deploy and any result that still constrains later work, in the same edit that writes its retrospective. Supervisor rulings live in the stage's briefs and reports; this plan keeps the ones that govern later work. Test counts and commit lists stay in the reports.
• Stages and lanes:
  • Lanes are grouped by the context they need and how likely they are to conflict, not by feature. A stage's lanes run in parallel, each a worker in a fresh context and its own worktree at ../project-buddy-worktrees/<lane>, on branch <stage>/<lane>, with a real node_modules from npm ci.
  • Thin lanes (Autumn, 2026-10-12): cut along file lines, never by use case; up to 6 lanes at once; about 5 items per lane.
  • Tolerated conflicts: two lanes may make small edits to one file (registry entries, a few lines of a src/ui/copy/ area module or a use-cases/ area file, an import and a call) when each brief names the file and the lines. The merge keeps both sides of a registry or list, with imports in Biome's order, and reports each conflict. A lane may not rewrite a module another lane depends on.
  • Moves and renames are the costly conflicts. A lane that moves, renames or deletes a shared file runs alone, or beside lanes that don't import it.
  • Tables: one lane per stage changes tables, and only it runs db:generate. drizzle/meta is never merged by hand; package-lock.json takes main's and is regenerated with npm install.
  • Any other edit outside a lane's owned paths needs approval. The lane asks through contact_supervisor, and the orchestrator takes the request to Autumn.
  • Rounds inside a stage: a round-merge worker (accounts-briefs/round-merge.md) merges each round on local main, predicts conflicts with git merge-tree --write-tree first, regenerates the baselines and runs every check twice. Nothing is pushed between rounds. The stage's after-merge workflow runs once, after the last round.
• Lane habits:
  • Settle policy questions before a lane starts and put the answers in the brief.
  • A known flake is fixed first, alone or in round 1, before the lanes that would trip on it.
  • Commit each finished item, and keep the report's facts in a notes file outside the repo (../project-buddy-worktrees/<stage>-<lane>-notes.md), so a compaction loses nothing. Pi compacts at about 175k tokens ($PI_CODING_AGENT_DIR/settings.json, default ~/.pi/agent: compaction.keepRecentTokens: 30000, compaction.modelOverrides.reserveTokens: 825000 for anthropic/claude-opus-5-5).
  • A failing command is information: fix it within the rules or ask with contact_supervisor; never end a run on a failed check.
  • Follow-up work goes to a fresh worker briefed with the lane's report, never by reopening the finished lane.
  • Summarise tool output before reading it: lint counts by rule, failures only from test runs, line ranges for reads. Use codemode.
  • A large mechanical lane is split by area after one shared config commit.
• Every brief contains: the plan path; the outcome, owned and forbidden paths; the use_case_* slugs; the shared test helpers to use (themeChoiceCookie, manualSection, src/viewports-test-kit.ts, the visual settle step, the e2e account sign-in), since the merge converts any hand-written copy; the rule not to edit the plan or push; and the report format (branch, worktree, commits, files, env vars, dependencies, checks, open risks, "For the integration agent", "For the next round").
• After every stage (template: chat-ui-and-mobile-briefs/; for rounds, accounts-briefs/):
  1. The integration (or last round-merge) worker merges, regenerates the visual baselines, runs npm run check and the e2e tests, writes the stage diff, and stops before pushing.
  2. Fresh agents then do the rest, each in its own context: screenshot reviewers (one per theme, plus one mobile reviewer, viewing only changed baselines and new pages; they gate the push), push, migrate production, deploy and smoke-test, sweep production (one per theme; the report ends Sweep verdict: OK or Sweep verdict: BROKEN), and clean up the worktrees.
  3. Fresh read-only design and rules reviewers check the stage diff, including mobile screenshots. They fix nothing; their findings become lanes in the next stage.
• Visual changes go through baselines: lanes run the visual projects, and an intended visual change commits its new baselines. A lane views at most one or two of its own images. Interaction probes check what the user sees (a screenshot or click({ trial: true })), not only computed styles.
• Conflict predictions are tested, not guessed: lane reports don't predict merges.
• Secrets: SITE_PASSPHRASE (renamed INVITE_CODE by round 4; see below) and RESEND_API_KEY are in the repo's .env (gitignored); .env.local holds the pulled Vercel variables (DATABASE_URL and others). Never print a .env* file; read one variable with node --env-file, or check presence with grep -c. Never copy a secret into plans, briefs, logs or commits.
• Production data: the one Neon database serves Production, Preview and Development. Agents never write test data to it, except the production smoke test, which labels its data "(delete me)" and deletes it.
• Deploys: CLI deploys run only from a clean git worktree. Never force Claude to be unavailable in a smoke test.
• Excluding a folder from a diff: ':!<dir>/**'.

Agent roles

All roles are pi's built-in native subagents, with codemode added through "defaultTools": ["+codemode"] and subagents.agentOverrides in $PI_CODING_AGENT_DIR/settings.json (default ~/.pi/agent) (each override hand-copies the agent's built-in tool list, so recheck after a pi-subagents update). Roles run on anthropic/claude-opus-5-5 unless named otherwise.

• scout (recon, writes only its own notes; anthropic/claude-sonnet-5-5): before a stage, reads the code its lanes depend on and writes a compressed context note that their briefs cite. One scout per distinct context.
• researcher (web docs): only for questions the repo can't answer; its brief is cited and dated to the installed versions.
• evidence-auditor: checks a researcher brief only when a lane would bet its design on one claim.
• worker (the only writer): each lane, merge, fix lane, after-merge step and deploy-v1. Uses contact_supervisor for decisions outside its brief.
• reviewer (read-only): design and rules reviewers after each stage, reporting findings with file and line. At deploy-v1, a third reviewer audits each item of the version 1 definition of done against the evidence. The runtime saves their inline output.
• oracle (forks the orchestrator's context, read-only): only when a lane's question touches a Key Decision or one of Autumn's rulings.
• Unused: delegate, and the external CLI agents. A failed native launch is reported, never silently replaced by an external CLI.
• Running them: async workflows, with the script written to a file, passed by path and checked with subagent({action:"validate"}) first. Don't poll; reply to supervisor requests with subagent_supervisor. Steer a running child with mode: "steer" (delivered after its current tool call); follow_up waits until it idles, which may be never. A workflow saves each child's final message over its output file, so a child that writes its report file must also return the report as its final message. A "bash open 240s" alert is usually a 3–8 minute Playwright run: check pgrep -f "playwright/test/cli.js test" and its cwd before acting.

Key Decision

delegated-staged-build

Since 2026-10-10 the system is built by short-lived subagents in staged parallel lanes, with the main session only maintaining this plan (Autumn). See "How the build runs".