# Plan-Build Orchestrate Loop Use this workflow when `plan_build` hands Claude Code an implementation task. The goal is to keep Claude as the orchestrator while using Codex and CodeRabbit as independent review and validation agents. When `plan_build` supplies "Distribution mode: on", Codex and Kimi Code also become the implementers (backend and frontend respectively) via the Distributed Implementation variant of step 5. ## Operating Rules - Run from the project root. Treat the current working directory as the project to modify. - Preserve user work. Check `git status` before edits and do not revert unrelated changes. - Keep implementation scoped to the payload unless repository context proves a wider change is required. - Prefer existing project conventions, scripts, test commands, and dependency managers. - Do not call the task complete until validation has run or the reason it cannot run is documented. - If any agent reports a plausible correctness, security, data-loss, migration, or test risk, resolve it or explicitly document why it is not applicable. ## The 8-Step Workflow ### 1. Intake Read the user payload fully. Identify: - Objective and expected user-visible behavior. - Files, modules, commands, and frameworks likely involved. - Constraints from repository docs, package scripts, CI config, and existing patterns. - Any ambiguity that blocks safe execution. Only ask the user a question when no reasonable project-local assumption is safe. ### 2. Baseline Inspect the repository before changing files: ```bash git status --short rg --files ``` Then read the smallest useful set of files. Prefer `rg`, package manifests, tests, routing files, and nearby implementations over broad file dumps. ### 3. Plan Follow the planning mode supplied by `plan_build`: - `standard`: Create a short implementation plan with concrete steps and validation commands. - `brainstorm`: Invoke `superpowers:brainstorming`, honor its design and written-spec approval gates, and let it transition to `superpowers:writing-plans` after approval. - `writing-plan`: Invoke `superpowers:writing-plans` directly, treating the payload as the requirements or specification. - `grill`: Invoke `mattpocock-skills:grilling` to relentlessly stress-test the payload and your intended approach with the user. After grilling concludes, write the workflow's normal short implementation plan incorporating what survived. For either Superpowers mode, save the artifacts at the paths selected by the skills. In `grill` mode, the short implementation plan is the planning artifact. When `writing-plans` reaches its execution handoff, return to this workflow instead of starting implementation: Codex must review the plan first. If the user rejects or cancels a required approval, stop cleanly without modifying implementation files. If the task touches behavior, data, auth, payments, destructive actions, or shared infrastructure, include a rollback or compatibility note. ### 4. Codex Plan Review Run this step only for `brainstorm`, `writing-plan`, and `grill` modes. Ask Codex for an independent, read-only review of the approved spec, when present, and the implementation plan before touching implementation files. Provide the original payload and artifact paths. Ask it to focus on requirement coverage, incorrect assumptions, unsafe migrations, missing edge cases, inadequate tests, and steps that are too vague to execute. Recommended prompt shape: ```text Review these planning artifacts before implementation. Check requirement coverage, technical correctness, repository fit, edge cases, migration or rollback risk, test coverage, and whether every step is executable. Report concrete findings only; do not modify files. Task: Spec: Implementation plan: ``` Use a read-only, ephemeral Codex invocation. Resolve every valid finding in the artifacts and repeat the review if revisions are substantial. If an artifact is missing or empty, or Codex cannot complete the review, stop before implementation and report the failure. In `standard` mode, skip this step and continue directly to implementation. ### 5. Implement If `plan_build` supplied "Distribution mode: on", skip this step and step 6 and follow the Distributed Implementation variant (steps 5a–5c) below instead, then continue at step 7. Make the change in small, reviewable edits: - Follow existing style and abstractions. - Add or update tests when behavior changes. - Update docs only when user-facing usage changes. - Avoid unrelated refactors and formatting churn. After each meaningful edit group, re-check the diff for accidental changes. ### Distributed Implementation (distribution mode: on) In this variant you orchestrate and review only — you never implement, not even leftovers. Codex implements backend items; Kimi Code implements frontend items. #### 5a. Split And Confirm Tag every work item in the plan as `BE`, `FE`, or `unclear`. Present the full table to the user (AskUserQuestion) and have them confirm or reassign each item; `unclear` items must be assigned by the user to `BE` or `FE`. Dispatch nothing until every item is confirmed. #### 5b. Backend Phase (Codex) Check `git status` first so pre-existing work is never mixed in or reverted. Compose a self-contained brief: the task, constraints, the exact confirmed BE item list with file paths, project conventions, and validation commands. Dispatch: ```bash codex exec --full-auto "" ``` Then review the phase diff (`git diff`) yourself for correctness, scope, and convention fit. Send findings back to Codex as a new brief (findings plus the original context) — do not fix them yourself. Maximum 2 retry rounds; if valid findings remain after that, stop and report with the partial diff intact. An empty diff from a delegate counts as a failure: retry once with a sharpened brief, within the same 2-round bound. If the delegate CLI crashes or hangs, stop and report, preserving the partial diff. #### 5c. Frontend Phase (Kimi Code) Check `git status` again, then compose the FE brief the same way, and additionally include the now-implemented backend API surface (routes, types, request/response contracts) so the frontend builds against the real backend. Dispatch: ```bash kimi -p "" ``` (`-p` runs one prompt non-interactively and manages permissions itself; it cannot be combined with `--auto` or `--yolo`.) Review the phase diff and route findings back to Kimi under the same 2-round retry bound and failure rules as the backend phase. After both phases pass review, skip step 6 (the per-phase reviews above replace it — Codex cannot impartially review the half it wrote) and continue at step 7 with the combined diff. ### 6. Codex Code Review Pass Skip this step in distribution mode; the per-phase reviews in steps 5b–5c replace it. Ask Codex for an independent review of the local diff before finalizing. Provide the task, constraints, and current diff. Ask it to focus on bugs, edge cases, missing tests, regressions, and simpler project-native alternatives. Recommended prompt shape: ```text Review this change for correctness and risk. Prioritize bugs, regressions, missing tests, and mismatches with existing project patterns. Do not rewrite the whole solution unless a specific issue requires it. Task: Diff: ``` Apply fixes for valid findings, then repeat this review pass if the fixes are non-trivial. ### 7. CodeRabbit Review Pass Run CodeRabbit on the branch or diff when available. Treat its output as advisory but investigate every concrete finding. If CodeRabbit cannot run locally, record the command attempted and the failure. Continue with manual validation rather than blocking indefinitely. ### 8. Validate And Close Run the planned validation commands, such as: ```bash npm test npm run lint pytest cargo test go test ./... ``` Use the commands that actually exist in the project. If validation fails, fix the issue and rerun the relevant command. If a failure is unrelated or environmental, capture the evidence. Before final response: - Confirm `git diff` contains only intended changes. - Summarize what changed. - Report validation run and result. - Note any remaining risks or commands that could not run.