---
name: Plan Sparring
slug: bcc-plan-spar
category: Quality
description: Align, lock, and review a PLAN.md coding contract through human Q&A and automated plan critique, ensuring a clear plan before implementation.
github: "https://github.com/bo-cao/breaking-coding-chaos/tree/master/skills/bcc-plan-spar"
language: Python
stars: 20
forks: 0
install: "git clone https://github.com/bo-cao/breaking-coding-chaos"
added: 2026-07-16T13:43:21.824Z
last_synced: 2026-07-18T04:41:49.829Z
canonical_url: "https://dirskills.com/skills/bcc-plan-spar"
---

# Plan Sparring

Align, lock, and review a PLAN.md coding contract through human Q&A and automated plan critique, ensuring a clear plan before implementation.

**Install:** `git clone https://github.com/bo-cao/breaking-coding-chaos`

## README

# bcc-plan-spar

**Job:** solid coding contract for one slice —

1. **Human grill** (Q&A until **clear enough** — no default turn quota) → clear sub-plan intent  
2. **Lock** `PLAN.md` (+ `CONTEXT` / ADRs)  
3. **Auto review** (**`rounds`** = review budget, multi-backend) → live results → main agent **iterates PLAN**  
4. **Human final gate** → APPROVE / amend / stop  
5. Hand off to **`bcc-clean-cut`** (implement — not this skill)

**Deep source:** `grill-with-docs` Act 1 (grill + domain) + Act 2 (bounded review, CLI fallback).  
**Formats:** [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md), [ADR-FORMAT.md](./ADR-FORMAT.md), [PLAN-FORMAT.md](./PLAN-FORMAT.md).

---

## Workflow preflight (required — before Phase 0/1)

**Do not** start grilling or rewriting `PLAN.md` until this check runs.  
If anything is ambiguous → **ask the user one clear question** (with a recommended answer). Do not invent workflow state.

### 1. Snapshot disk (read if present)

| Path | Ask |
|------|-----|
| `plans.md` / `progress.md` / `findings.md` | Is there a **global** endeavor map? Where are we? |
| `PLAN.md` | Is there an **active coding brief**? Draft or locked? Which slice? |
| `CONTEXT.md` / `docs/adr/*` | Domain language already started? |
| `.bcc/session.json` | Active slice / prior approve (see [SESSION.md](../bcc-breaking-coding-chaos/references/SESSION.md)) |
| Chat this session | Did user already APPROVE implement / skip align? |

Echo a one-line status, e.g.:

`preflight · throughline=yes|no · PLAN=missing|draft|locked|stale? · slice=? · session=… · recommend=grill|reuse-PLAN|hand-off-clean-cut|ask-user`

### 2. Hard rule: **throughline before plan-spar**

| Check | Required |
|-------|----------|
| `plans.md` exists with a non-empty **Goal** (and preferably a hardpoint map) | **Yes** |

If missing or empty:

1. **Do not** start Phase 1 grill for a multi-step endeavor.  
2. Tell user: *“bcc-plan-spar runs only after throughline. Run `/bcc-throughline` first (or Mode A `/bcc-breaking-coding-chaos`).”*  
3. Offer to load **bcc-throughline** now.  

Exception: user explicitly says **one-off micro task** and refuses a cockpit — then ask once to confirm; if they insist, proceed but still create a minimal `plans.md` Goal line when possible (preferred) rather than silent skip.

### 3. Is **bcc-plan-spar** the right skill right now?

| Situation | Suitable? | Do this |
|-----------|-----------|---------|
| No usable throughline (`plans.md`) | **No** | **bcc-throughline** first (hard rule above) |
| User wants **status / reprioritize only** | **No** | **`bcc-throughline`** or main skill status |
| User wants **code now** and PLAN locked + APPROVED | **No** | **`bcc-clean-cut`** |
| User wants **code now** but PLAN missing / draft | **Yes** | Align/lock here (after throughline OK) |
| User names a hardpoint on the map | **Yes** | Proceed; **update single root `PLAN.md` in place** for that work |
| Existing `PLAN.md` is for previous work | **Yes** | **Overwrite/refresh** `PLAN.md` for the new hardpoint (global history stays in throughline trio — not in PLAN) |
| Trivial one-liner / pure discussion | **Usually no** | Skip or ask |

**No formal state machine.** Infer from docs + chat; **suggest** next step if wrong skill.

### 4. Ask the user when uncertain

One question + recommended default:

1. Throughline missing — create now?  
2. Which hardpoint on the map?  
3. Refresh `PLAN.md` for this hardpoint (yes)?  
4. Align vs code (plan-spar vs clean-cut)?

### 5. After preflight OK → Phase 0

Only then: scope hardpoint, then Phase 1 grill / lock.

---

## Tunables

Parse from invocation (e.g. `/bcc-plan-spar auth rounds=3 review=auto`):

| Arg | Default | Meaning |
|-----|---------|---------|
| **`rounds`** / `MAX_REVIEW_ROUNDS` | `3` | **Only budgeted loop:** auto-**review** rounds after PLAN is locked. Set at spar start. `0` = skip auto review (human gate still required). |
| `review` | `auto` when `rounds>0`, else `off` | Review backend (see below) |
| `PLAN_FILE` | `PLAN.md` | Coding brief path |
| `LOG_FILE` | `PLAN-REVIEW-LOG.md` | Append-only live review transcript |

**Not a tunable by default:** Phase 1 human Q&A has **no default turn quota**. Grill until the agent judges **clear enough** (or the human locks / stops).  
Optional override only if the user explicitly passes `grill_rounds=N` / `MAX_GRILL_ROUNDS=N` — treat as a soft safety ceiling, not a target to fill. Do **not** invent or announce a default grill cap.

### `review` modes (simplified)

| Mode | Who reviews | When to use |
|------|-------------|-------------|
| **`auto`** | **subagent** if spawn works; else **self**. If user set `review=cli` and a CLI exists, may use CLI | Default |
| **`subagent`** | Fresh reviewer subagent (read-only) — preferred isolation | Stronger critique vs builder |
| **`self`** | Same agent, critic stance only | Always available 保底 |
| **`cli`** | Optional local CLI (e.g. `codex exec -s read-only` if installed) | User opts in; **fallback to self** on failure |
| **`off`** | Skip auto review | Human gate only after lock |

Do **not** require multi-agent products or cross-org setups. One host + optional subagent/CLI is enough.

Echo once before Act 1 (grill has no round count):

`bcc-plan-spar · topic=… · review_rounds=3 · review=auto · PLAN_FILE=PLAN.md · LOG_FILE=PLAN-REVIEW-LOG.md`

---

## Flow (fixed order)

```text
Preflight  Workflow fitness (throughline? PLAN? right skill?) — ask if unsure
Phase 0    Scope slice (+ read throughline)
Phase 1    Human grill ↔ agent until clear enough (no default Q&A quota)
           + CONTEXT/ADR → lock PLAN.md
Phase 2    Auto review loop (≤ rounds from invocation)  [unless review=off or rounds=0]
           each round: REVIEWER → VERDICT REVISE|APPROVED → live log
           if REVISE: BUILDER updates PLAN; if APPROVED: stop auto loop early OK
           fallbacks if backend fails (保底)
           NOTE: auto VERDICT: APPROVED ≠ permission to code
Phase 3    Human final gate ONLY decides bcc-clean-cut:
           APPROVE implement → bcc-clean-cut | amend | stop
```

**No product code** in bcc-plan-spar. **Only the human** starts `bcc-clean-cut` (or explicit skip-to-implement).

---

## Artifact separation

| File | Role |
|------|------|
| **`plans.md` / `progress.md` / `findings.md`** | **Only** global endeavor maintenance (throughline) |
| **`PLAN.md`** | **Single** living coding brief for **whatever is active now** — always updated in place; **no** per-slice PLAN files required |
| `CONTEXT.md` / `docs/adr/*` | Glossary / hard decisions assisting PLAN |
| `PLAN-REVIEW-LOG.md` | Optional review transcript (append or refresh per cycle) |

When starting a **new** hardpoint: rewrite `PLAN.md` for that work; move finished narrative into **progress.md**, not a second PLAN path.

---

## Phase 0 — Scope

- Name hardpoint (user topic or next from `plans.md`).  
- Throughline already required (preflight).  
- Read existing CONTEXT/ADR/code.  
- If old PLAN remains from a previous hardpoint: **replace** with the new brief when locking (after grill), after a one-line note in `progress.md` that the prior PLAN was superseded.

---

## Phase 1 — Human grill + lock PLAN (grill-with-docs Act 1)

### Purpose

Obtain **explicit information** from the human for this **sub-plan** — not silent guessing.  
**Stop when clear enough** — there is **no default Q&A round budget**. Prefer few high-signal questions; never pad to fill a quota.

### Interview rules

- **One question at a time.** Wait.  
- Each question: give a **recommended answer**.  
- Facts in codebase → look up; do not ask.  
- Decisions → user.  
- Do **not** track or announce “turn N of 10” (or any default cap).  
- Optional: only if user set `grill_rounds=N`, treat as soft ceiling; at that ceiling, summarize and ask lock / continue / stop.

### Stop & lock triggers (required)

| Who | Can do |
|-----|--------|
| **Agent** | When **clear-enough** criteria hold: **proactively propose lock**, e.g. *“这块已经够清楚，可以锁 PLAN 并进入 review（rounds=…）——现在锁、继续问、还是改？”* Do **not** keep asking “for completeness.” Do **not** lock silently unless user already said “lock when ready” / “够了就锁”. |
| **Human** | Interrupt **anytime**: “够了 / lock PLAN / 写 PLAN / 进入 review / stop” → lock or stop as asked. Do not keep grilling. |
| **Optional cap** | Only if user set `grill_rounds=N` and it is hit → same as agent propose: summarize open branches; ask lock / continue / stop. |

### Domain (domain-modeling)

- Challenge/sharpen terms; update **`CONTEXT.md` inline**.  
- ADRs only when hard to reverse · surprising · real trade-off.  
- Cross-check claims vs code.

### Clear enough → lock `PLAN.md`

Agent judges clear enough when **all** of the following hold (or user forces lock / interrupt lock):

1. Goal one paragraph  
2. Concrete numbered approach  
3. Contestable decisions resolved or parked under Risks  
4. Out of scope  
5. Checklist with implied verification each  
6. User confirmed understanding **or** accepted agent’s “clear enough — lock now?” **or** interrupted with lock  

Drafts: `_Draft — not locked_`. Prefer ubiquitous language from CONTEXT.

Announce: `PLAN.md locked via bcc-plan-spar for <slice>.`

### PLAN hygiene

Throughout Phase 1–2: **update + 约减** — short living contract, not a diary, not a global roadmap (roadmap = `plans.md`).

### Light throughline note after lock

Append one line to `progress.md`: slice name + “PLAN locked”. Optionally set hardpoint `in_progress` on `plans.md`. Full close-out writeback is **bcc-clean-cut**’s job ([WRITEBACK.md](../bcc-breaking-coding-chaos/references/WRITEBACK.md)).

---

## Phase 2 — Auto review (simplified grill-me-codex / grill-with-docs Act 2)

Inspired by adversarial plan review (e.g. grill-me-codex / grill-with-docs): **critic → verdict → builder revises PLAN → repeat**, with a **live log**.  
**Default stays in-process** (self or **subagent**). Optional **Codex CLI** if present — **not** required; no multi-vendor orchestration needed.

Runs when `MAX_REVIEW_ROUNDS > 0` and `review != off`, on a **non-draft** locked PLAN.

### Init log

Create/append `LOG_FILE`:

```markdown
# Plan Review Log: <slice>
bcc-plan-spar Act 1 complete — PLAN locked; CONTEXT/ADRs updated.
MAX_REVIEW_ROUNDS=<n> · review=<mode> · started=<timestamp>
```

### Reviewer stance (every round, every backend)

Skeptical and specific. Find: security, races, missing edges, schema conflicts, domain-language mismatch vs CONTEXT, wrong assumptions, unverifiable checklist items, simpler alternatives.

For each issue: **one-line fix**. End with exactly:

`VERDICT: APPROVED`  
or  
`VERDICT: REVISE`

**Read-only for external reviewers:** subagent / codex must **not** write repo files. Only the **main agent (builder)** edits `PLAN.md` / CONTEXT / ADR after a REVISE.

### Live results (required)

After **each** review round, the main agent must:

1. Surface the critique to the user **in chat** (summary + verdict) — do not hide it only in the log.  
2. Append full critique under `## Round <n> — Reviewer (<backend>)` in `LOG_FILE`.  
3. If `REVISE`: main agent as **builder** updates `PLAN.md` (material fixes only; reject bad nits with reason); append `### Builder response` (changed / rejected + why); **约减** PLAN; show user what changed.  
4. If `APPROVED` (from **agent/reviewer**): treat as **auto-review finished successfully** → Resolution → **still Phase 3 human gate**.  
   - Agent may say: *“Auto review APPROVED after N rounds. Ready for you to start bcc-clean-cut?”*  
   - **Do not** start `bcc-clean-cut` on auto APPROVED alone.

### Loop

For `ROUND = 1..MAX_REVIEW_ROUNDS`:

1. Run reviewer via active backend (below).  
2. Live log + chat surface (`VERDICT: REVISE` or `VERDICT: APPROVED` from the **reviewer agent/backend**).  
3. Reviewer APPROVED → Resolution (auto phase ends).  
4. Reviewer REVISE → builder iterates PLAN → next round.  
5. Cap without reviewer APPROVED → Resolution (deadlock) — list open issues. Never fake APPROVED.  

**Either way, bcc-clean-cut only after Phase 3 human decision.**

---

### Backend: `self`

Main agent plays **critic only** (not the builder voice of the previous turn). Same as grill-with-docs self mode.

### Backend: `subagent`

If the host supports spawning a subagent / separate reviewer:

1. Spawn **read-only** reviewer with prompt (below).  
2. No file writes from the child.  
3. Parent collects critique + verdict.  
4. On spawn failure / no subagent API: **fallback** (保底链).

### Backend: `cli` (optional)

Only if user asked `review=cli` (or auto tries after subagent fails and a known CLI exists):

- e.g. `codex exec` read-only with the review prompt (grill-me-codex style).  
- CLI must **not** write repo files.  
- On missing CLI / failure: notify and **fallback to self** — never hang.

### Backend: `auto` (default)

1. **subagent** if available  
2. else **self**  
3. optional **cli** only if already configured/requested  

### 保底机制

| Guarantee | Behavior |
|-----------|----------|
| **Fallback** | subagent → self (and cli → self); never block |
| **≥1 self pass** | If `rounds≥1` and fancy backends fail |
| **No fake APPROVED** | Cap → human decides |
| **Builder arbiter on REVISE** | Good fixes in; bad nits rejected with reason |
| **Human final gate** | Reviewer verdict ≠ permission to code |
| **Log** | Each round in chat + `PLAN-REVIEW-LOG.md` |

### Reviewer prompt core (subagent / codex / self)

> Adversarial reviewer for an implementation plan. Read `PLAN.md`, `CONTEXT.md`, ADRs, and needed repo files (**read-only**). Find concrete flaws; one-line fix each. Do not modify files. End with exactly `VERDICT: APPROVED` or `VERDICT: REVISE`.

### Resolution (end of Phase 2)

- **Reviewer APPROVED:** Present final PLAN + up to 3 bullets on what review improved + round count + backends used. State clearly: *auto review passed; waiting for your decision to implement.* → Phase 3.  
- **Deadlock / only REVISE left:** List unresolved points + builder counters. → Phase 3; human may still APPROVE implement with known risks, amend, or stop.

---

## Phase 3 — Human final gate (only path into bcc-clean-cut)

Always after Phase 2 (or after lock if review skipped). **This is the only default path that starts execution.**

Reviewer/agent may have said APPROVED or REVISE — that is **advisory** for the plan quality loop.

Ask:

> Auto review result: `<APPROVED | mixed | deadlock>`.  
> **Your call:** **APPROVE implement** (`bcc-clean-cut`) · **amend** plan · **stop**

| Human says | Agent does |
|------------|------------|
| **APPROVE implement** / “开写” / “bcc-clean-cut” | **Write `.bcc/session.json`** (approved_for=clean-cut, plan_sha256, active_slice, status=approved) per [SESSION.md](../bcc-breaking-coding-chaos/references/SESSION.md); then load **`bcc-clean-cut`** |
| **amend** | Update PLAN/CONTEXT/ADR; clear approve fields in session if PLAN hash will change; optionally re-enter Phase 2 |
| **stop** | Optional throughline note; **do not** bcc-clean-cut; session `approved_for=none` |
| Explicit **skip gate** earlier (“review then implement without asking”) | Same session write as APPROVE, then bcc-clean-cut |

Never treat Phase 2 `VERDICT: APPROVED` as automatic bcc-clean-cut.

### Session write on APPROVE (required)

After human APPROVE implement (or explicit skip-gate):

1. Ensure directory `.bcc/` exists.  
2. Hash current `PLAN.md` (SHA-256 of file bytes).  
3. Write/update `.bcc/session.json` with `active_slice`, `plan_path`, `plan_sha256`, `approved_at`, `approved_for=clean-cut`, `status=approved`.  

This lets a **new chat** still pass bcc-clean-cut preflight without re-deriving APPROVE from chat memory.

---

## Handoff

```text
bcc-plan-spar (align + auto review + human APPROVE)
    → bcc-clean-cut (minimal implement + verify + PLAN 约减 + throughline writeback)
```

---

## Invocation examples

```text
/bcc-plan-spar redesign checkout
→ grill until clear enough; lock PLAN; default rounds=3 auto review; human decides bcc-clean-cut

/bcc-plan-spar payments rounds=5 review=cli
→ grill until clear enough; 5 review rounds via CLI (fallback self); human gate

/bcc-plan-spar slice-x rounds=3 review=subagent
→ grill until clear enough; subagent reviewer ×3 max; fallback chain on failure

/bcc-plan-spar hotfix rounds=0 review=off
→ grill until clear enough + lock only; no auto review; still human gate before clean-cut

/bcc-plan-spar auth rounds=2 grill_rounds=6
→ optional soft grill ceiling 6 (user-set only); review rounds=2
```

Chat: "bcc-plan-spar", "对齐并锁 PLAN", "spar the plan rounds=5".

**`rounds` is the spar review budget** — the number to set when starting spar. Grill is not round-counted by default.

---

## Hard rules

1. **Preflight first**; **throughline (`plans.md`) before plan-spar** (hard).  
2. **Single `PLAN.md`** updated in place; global progress only in the three throughline files.  
3. Human grill before lock (unless draft/user forces).  
4. Phase 1: **no default grill quota** — stop when clear enough (or human lock/stop).  
5. **`rounds`** budgets Phase 2 auto review only; backends fail → **fallback**.  
6. Live chat + log every review round.  
7. Only main agent writes PLAN after REVISE; external reviewers read-only.  
8. **Never implement product code** here.  
9. Human final decision before bcc-clean-cut.  
10. Review caps terminate Phase 2 loops; never fake APPROVED.  
11. Infer next steps from context/docs; **suggest** to user — no heavy formal state machine.

## What NOT to do

- Don't run plan-spar before throughline.  
- Don't invent a default grill turn budget (e.g. “10 rounds”) or pad questions to fill one.  
- Don't create `PLAN-01.md` / per-case PLAN trees for global bookkeeping.  
- Don't skip preflight; don't code after auto APPROVED alone.  
- Don't invent CLI review success; fallback to self.  
- Don't dump coding checklists into `plans.md`.