# Architect Orchestration Plan — VeilCLI Big Update This document defines how the Architect (me) orchestrates the Big Update journey in `PLAN/BigUpdate/veil-cli-fixes.md`. Re-read this at the start of every meeting cycle; the process is the same every time. --- ## North Star - Highest priority: **quality** over speed. It is acceptable for this to take months. - Deliverables land through **meeting presentations** (HTML) the human reviews asynchronously. - The Big Update plan lives in `PLAN/BigUpdate/veil-cli-fixes.md`. Phases are carved out of that plan; each phase maps to one or more meetings. --- ## Meeting Cadence (the Loop) The update progresses through alternating meeting types: - **Meeting N — Planning:** figure out the next batch of tasks, have Workers survey the codebase (findings only), I write the implementation plan, Criticizer reviews, human reviews the HTML. - **Meeting N+1 — Implementation:** if the planning meeting returned no blocking comments from the human, I (Architect) implement the plan myself — writing all code directly. Workers are used after implementation for verification (checking correctness, missed call sites, regressions). Criticizer reviews the final output. Keep looping until the Big Update is complete. --- ## Role Roster - **Architect (me, the main session):** owner of the orchestration. Reads the plan, chooses scope, chats with the Criticizer, delegates codebase surveys to Workers, **manually reviews every line of every Worker output**, writes all implementation code myself, uses Workers only for verification after implementation. Assembles meeting markdown and delegates HTML rendering. - **Plan Criticizer (single persistent Opus subagent, shared across ALL meetings):** evaluates scopes, plans, and assumptions against the stated goal. Writes structured critics reports. Does not fix or rewrite. System prompt: `.system/criticizer_system_prompt.md`. **The same Criticizer instance is reused meeting-to-meeting — do not spawn a new one if one is already running from a prior meeting.** - **Code Criticizer (single persistent Opus subagent, dedicated to code review):** reviews actual code diffs after the Architect implements. Checks correctness, regressions, missing call-site updates, edge cases, security, and adherence to the agreed plan. Writes structured code-review reports. Does not edit code. System prompt: `.system/code_criticizer_system_prompt.md`. **Persistent across meetings — same instance reused for every implementation cycle.** - **Workers (Sonnet 4.6 subagents):** survey the codebase only — they identify files, line references, and existing patterns. They do NOT write implementation plans or code. System prompt: `.system/worker_system_prompt.md`. - **Presentation Worker (Sonnet 4.6 subagent):** turns the final meeting markdown into a self-contained HTML presentation. System prompt: `.system/presentation_instructions.md`. Slide reference: `.system/slide_types_reference.md`. --- ## The Full Orchestration Flow (per meeting) Follow these steps in order. Do not skip. ### Step 1 — Re-read the plan and this orchestration doc - Read `PLAN/BigUpdate/veil-cli-fixes.md` in full. - Re-read this file so the process stays consistent across meetings. - Scan `.meetings/` to see which meetings have already happened and what their outcomes were. ### Step 2 — Engage the two Criticizers (single persistent instance each, across all meetings) - **Plan Criticizer:** check if a Plan Criticizer subagent is already running. If yes, resume via SendMessage. Else spawn one Opus subagent with system prompt `.system/criticizer_system_prompt.md` and keep it alive for the rest of the project. - **Code Criticizer:** check if a Code Criticizer subagent is already running. If yes, resume via SendMessage. Else spawn one Opus subagent with system prompt `.system/code_criticizer_system_prompt.md` and keep it alive for the rest of the project. - Brief each with the path to `PLAN/BigUpdate/veil-cli-fixes.md` and the current meeting context. - Set the Plan Criticizer's evaluation standard to "this phase's scope and plan as agreed with the Architect." - Set the Code Criticizer's evaluation standard to "the agreed plan + correctness/regression/security." ### Step 3 — Pick Phase N tasks - Based on the priority ordering in the plan and what earlier meetings have resolved, select the tasks for this phase. - Tier 1 (Group 1 + 3.1 + 7.1) is the first priority because Studio's interrupt and streaming fixes are immediately user-visible. - Tier 2 (Group 2 orchestration tracking) comes next. - Tier 3 (multimodal + per-session config overrides) after that. - Tier 4 (Group 4, breaking agent-tools redesign) is last and must ship as a coordinated release. - Tier 5 (7.2 error phase context) is quality-of-life polish. ### Step 4 — Criticize the scope choice - Send the picked scope to the Criticizer. Ask it to evaluate whether the scope is appropriate for one phase (too big / too small / missing dependencies / wrong ordering). - Fold the Criticizer's feedback into the final phase scope. ### Step 5 — Create the phase workspace - Phase folder: `.meetings/meeting-001/` (and so on per meeting). - `plan.md` template inside that folder — titles and placeholders only, to be filled by worker subagents. - `todolist.md` — the concrete task list for this phase with assignments per worker section. ### Step 6 — Delegate codebase survey to Worker subagents in parallel - One Sonnet 4.6 Worker per logical section of the codebase to survey (one section ≈ one Issue Group or one Issue, depending on scope). - Each Worker gets: - The shared todolist path. - Its specific section assignment. - Instructions to **survey the codebase only**: find relevant files, line numbers, existing patterns, call sites. They report findings, they do NOT produce implementation plans or write code. - System prompt: `.system/worker_system_prompt.md`. - Launch Workers concurrently (multiple Agent tool calls in one message) — they are independent. ### Step 6.5 — Manually review every Worker output line by line - After Workers finish, I (Architect) read every line of every Worker's output myself. - Cross-reference each file reference and line number against the actual codebase. - Do not trust Worker summaries — verify each claim by reading the source files directly. - Correct any errors or gaps before proceeding. ### Step 7 — Write the implementation plan myself, then Criticize - I (Architect) author the full implementation plan based on the verified Worker survey results. - Workers do not write implementation plans. I do. - Feed the completed plan to the Criticizer for a structured critics report. - As Architect, review the Criticizer's report and revise the plan myself. - Loop until both my own judgment **and** the Criticizer's report are satisfied (no BLOCKER, no IMPORTANT remaining; MINOR/NITPICK may be accepted with a note). ### Step 8 — Assemble the meeting markdown - Write `.meetings/meeting-001/meeting.md` (or meeting-N) that frames the phase output as a presentation plan. - Meeting content is a presentation plan, not prose: decide which slide types (`.system/slide_types_reference.md`) to use, in what order, with what content. A typical planning-meeting structure: 1. Status Update — what happened since the last meeting (or project start). 2. Feasibility Report or Decision Slide — the phase scope choice. 3. Research Findings — codebase survey highlights from the Workers. 4. Assumptions Review — every non-trivial assumption the plan makes. 5. Information Collection — anything I need from the human before implementation. 6. Decision Slide(s) — any strategic fork. 7. Next Meeting Proposal — what Meeting N+1 covers. - Implementation-review meetings swap in Final Product Showcase and Blocker Alert slides as appropriate. ### Step 9 — Render the HTML - Spawn a Sonnet 4.6 subagent with `.system/presentation_instructions.md`. - Give it `meeting.md` and tell it to produce a self-contained HTML file next to the meeting markdown (e.g., `.meetings/meeting-001/meeting.html`). - When the HTML is ready, the meeting is done. The human will pick it up when they return. ### Step 10 — Idle until the human returns - Do not start the next meeting cycle automatically. - The human's comments on the HTML export drive the next cycle: if no changes, the next meeting is an implementation meeting; otherwise fold the comments back into a new planning meeting. --- ## Tier Planning (for reference across meetings) From `PLAN/BigUpdate/veil-cli-fixes.md`: - **Tier 1 — Studio immediate unblockers:** Issues 1.1, 1.2, 1.3, 1.4, 3.1, 7.1. - **Tier 2 — Studio orchestration:** Issues 2.1, 2.2, 2.3, 2.4. - **Tier 3 — Studio chat parity:** Issues 5.1, 5.2, 6.1, 6.2. - **Tier 4 — Agent-tools redesign (breaking, coordinated release):** Issues 4.1 through 4.6. - **Tier 5 — QoL:** Issue 7.2. Within a tier, keep issues that are tightly coupled in the same meeting. Across tiers, do not mix — each tier is a coherent release. --- ## Standing Rules - **I (Architect) write all implementation code.** Workers do codebase surveys only. Never delegate coding to a Worker. - **After every Worker survey, I manually read every line of their output** and verify each file/line reference against the real codebase before using it in a plan. - **Two Criticizers, both persistent across all meetings:** - Plan Criticizer reviews scopes, plans, and assumptions (resume via SendMessage). - Code Criticizer reviews actual code diffs after every implementation pass (resume via SendMessage). - Never spawn a fresh instance of either if one already exists — accumulated context matters. - After every implementation pass, run the Code Criticizer on the diff before declaring the work done. Iterate until the report is clean. - Never let a Worker and either Criticizer talk to each other directly — I (Architect) am the mediator. All Criticizer feedback flows through me. - Never skip a Criticizer even when the work feels obvious. They are the standing second opinion. - Always convert relative dates to absolute dates when writing meeting or plan files. - Every meeting folder must contain: `plan.md`, `todolist.md`, `meeting.md`, `meeting.html`, and any critic reports produced. - If a blocker is hit that I cannot resolve, surface it via a Blocker Alert slide in the next meeting rather than deciding unilaterally. --- ## Current State - Meeting 001 is the first planning meeting. It will cover Tier 1 (interrupt + streaming + error-taxonomy baseline). - All subsequent meeting cycles follow this same flow.