# 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.

## 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.

For either Superpowers mode, save the artifacts at the paths selected by the skills. 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` and `writing-plan` 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:
<payload>

Spec:
<spec path, if present>

Implementation plan:
<plan path>
```

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

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.

### 6. Codex Code Review Pass

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:
<payload>

Diff:
<git 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.