adversarial-plan

Adversarial Plan

Spec → implementation plan. Two-role adversarial pipeline that takes a spec.md (from adversarial-spec) and optionally review findings (from adversarial-code-review), and produces a plan.md with ordered steps. To implement it with adversarial-code-loop, convert each step to a focused spec and run the steps in dependency order; adversarial-code-loop has no functional --plan mode.

Installation

Requires the adversarial-common sibling repo (shared engine). One-line install:

curl -fsSL https://raw.githubusercontent.com/chpomob/adversarial-plan/main/scripts/install.sh | bash

or, from an existing checkout:

bash scripts/install.sh

Both place adversarial-plan and adversarial-common side by side under ~/.hermes/skills (override the target with $1 or $HERMES_HOME).

Workflow

PREFLIGHT ──→ optional DEEP RESEARCH ──→ GIT SETUP
                                           │
                                           ├─ delegated success ──→ FINALIZE
                                           │
                                           └─ direct/fallback ──→ PLAN ──→ CHALLENGE
                                                                          │
                                               APPROVE + no findings ──────┤
                                                                          │
                                               otherwise ──→ REVISE ──→ VERIFY
                                                                  ↑          │
                                                                  └──────────┘ up to --max-loops
                                                                          │
                                                                      FINALIZE

There is one CHALLENGE phase and no CROSS_2 phase. A successful delegated run bypasses PLAN/CHALLENGE/REVISE/VERIFY; a delegated fallback enters the normal adversarial loop. FINALIZE squash-merges an approved plan unless --no-merge is set, or records a rejection marker when findings remain.

Prompt design

The CHALLENGE prompt references plan.md and spec.md on disk and instructs the challenger to read them from the current working directory (the phase workdir). No document text is embedded in the prompt; the provider runs with the phase workdir as its cwd, so filesystem-capable providers inspect both files and the cumulative branch diff directly.

CLI

Output format

plan.md with YAML frontmatter + ordered steps:

---
spec: "feature-name"
version: "1.0"
author: "adversarial-plan"
based-on: "adversarial-spec"
findings-input: false
---

## Steps

### P1: First task
- **Files:** [path/to/file.rs]
- **Description:** What changes in this file
- **Dependencies:** []
- **Tests:** What tests to write
- **Risks:** What could go wrong

### P2: Second task
- **Files:** [path/to/another.rs]
- **Description:** What changes
- **Dependencies:** [P1]
- **Tests:** Integration test
- **Risks:** Deadlock risk

Personas

Loaded from adversarial-common/personas/:

• plan-writer.md — reads spec.md + optional findings, writes plan.md
• plan-challenger.md — reads plan.md, outputs JSON findings (risks, order, gaps)

Exit codes

Integration with dev loop

IMPORTANT: --plan mode is not wired in adversarial-code-loop. Its parser accepts --spec, not a plan file.

Instead, execute each plan step as a separate code loop with a focused per-step spec. See Running plan steps without plan mode for the step-to-spec template, launch pattern, and pre-flight checklist.

# Example: running P1 of a plan
python3 ~/.hermes/skills/adversarial-code-loop/scripts/adversarial_loop.py \
  --spec /path/to/step-P1-spec.md \
  --workdir /path/to/target-repo \
  --dev-cmd "codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --sandbox workspace-write" \
  --review-cmd "python3 .../claude-tmux.py --timeout 900 --hard-timeout 1800 --cwd /path/to/target-repo" \
  --timeout 1800 --max-loops 3 --no-arbiter

Steps without dependencies targeting different repos can run in parallel (safe). Parallel on the same repo is forbidden (adversarial-code-loop pitfall #8).

Plan format constraints

• Plan validation is partial. It checks frontmatter, at least one step, contiguous step IDs, and requirement-ID coverage in the spec. It does NOT enforce step field schemas, parse dependency lists, detect cycles, topologically sort, validate file paths, or verify that review findings are addressed. Most semantic correctness is delegated to the challenger model.

Pitfalls

• The --findings flag does NOT accept adversarial-review's final.json as-is. That file contains finding counts ({blocker: 1, major: 2}), not finding objects. You must extract structured findings from the review synthesis report and craft a findings.json manually.
• Each step must have explicit dependencies (or empty list). Circular deps cause validation failure.
• If review findings are provided via --findings, the plan must address each finding in at least one step.
• Step order should respect dependencies (enforced manually; no automatic topological sort).
• The same code patterns as adversarial-code-loop v4: git branch isolation, phase modules, squash merge.
• For implementation, treat one plan step as one code-loop spec. Run steps in dependency order. Independent steps may run concurrently only when their code loops use different repositories.
• Plan parser is strict about bullet format. Files and Dependencies must be on a single line: - **Files:** /path1, /path2. Indented sub-lists are NOT parsed.
• CHALLENGE reads plan.md and spec.md from disk (provider file tools). The orchestrator validates both files are regular files and are UTF-8 decodable before running the phase (fail-fast on FIFOs, device nodes, or binary content).
• Stash pop may conflict if untracked files (e.g. findings.json) exist in the workdir at pipeline end. Fix: git add the file before launching, or pass --findings from outside the workdir.
• write_final_json() may crash if stash state is inconsistent at finish time. The squash-merge already succeeded; only the artifact write is lost.