Sirtheoracle Forge Toolkit Adversarial Implementation

Adversarial Implementation Framework

Overview

This skill takes a final-plan.md (typically from the adversarial-proposal skill) and produces a complete, vetted implementation.md with exact code diffs, test specifications, and a coverage matrix that proves every plan item is addressed.

The same adversarial process that works for planning applies here: two agents independently produce implementation documents from the same plan, a synthesizer merges the best of both, the original agents critique the synthesis, and the synthesizer reconciles into a final implementation document.

The critical output is the coverage matrix — a table mapping every plan item to a specific code diff and a specific test. Zero gaps allowed.

When to Use

• After adversarial-proposal produces a final-plan.md
• When you have any implementation plan and want vetted, exact diffs before coding
• When previous implementations have missed items from the plan
• When testing coverage is critical

Prerequisites

This skill requires Agent Teams (TeammateTool, SendMessage). Enable with:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

If Agent Teams is not available, see references/subagent-fallback.md for an alternative using the Task tool with file-based coordination.

Architecture

INPUT: final-plan.md (from adversarial-proposal or any plan)
─────────────────────────────────────────────────

ROUND 0: Setup
─────────────────────────────────────────────────
  Lead reads final-plan.md → extracts source files + plan items
  Strategy pair: A=Surgical, B=Coverage

ROUND 1: Independent Implementation Planning (parallel)
─────────────────────────────────────────────────
  Agent A (Surgical)              Agent B (Coverage Guardian)
  ┌──────────────────┐            ┌──────────────────┐
  │ Own context       │            │ Own context       │
  │                   │            │                   │
  │ Sees ONLY:        │            │ Sees ONLY:        │
  │ - final-plan.md   │            │ - final-plan.md   │
  │ - Source files    │            │ - Source files     │
  │ - Test files      │            │ - Test files       │
  │                   │            │                   │
  │ Focus: minimal    │            │ Focus: complete    │
  │ diffs, correct    │            │ coverage, tests    │
  │ ordering          │            │ for everything     │
  │                   │            │                   │
  │ CANNOT see B ─────┼── ✗ ──────┼── CANNOT see A    │
  │                   │            │                   │
  │ → impl-A.md       │            │ → impl-B.md       │
  └───────────────────┘            └───────────────────┘

  ◄── Quality check + Convergence check ──►

ROUND 2: Synthesis
─────────────────────────────────────────────────
  Synthesizer C
  ┌──────────────────────────────────────┐
  │ Phase 0: Reads plan + source files   │
  │ Phase 1-2: Reads impl-A + impl-B    │
  │ Phase 3: Verifies diffs against src  │
  │ Phase 4: Merges into impl-C.md      │
  │ Phase 5: Writes isolated reviews     │
  │                                      │
  │ → impl-C.md       (lead-only)       │
  │ → review-for-A.md (A's eyes only)   │
  │ → review-for-B.md (B's eyes only)   │
  └──────────────────────────────────────┘

ROUND 3: Feedback (parallel, ISOLATED)
─────────────────────────────────────────────────
  Agent A                          Agent B
  ┌──────────────────┐             ┌──────────────────┐
  │ Reads ONLY:       │             │ Reads ONLY:       │
  │ - review-for-A.md │             │ - review-for-B.md │
  │ + own impl-A.md   │             │ + own impl-B.md   │
  │                   │             │                   │
  │ → feedback        │             │ → feedback        │
  └──────────────────┘             └──────────────────┘

ROUND 4: Reconciliation
─────────────────────────────────────────────────
  Synthesizer C
  ┌──────────────────────────────────────┐
  │ Receives feedback from A and B       │
  │ Verifies disputed diffs against src  │
  │ Reconciles into implementation.md    │
  │ → implementation.md                  │
  └──────────────────────────────────────┘

OUTPUT: implementation.md (in same directory as final-plan.md)

Why Two Strategies

The natural tension: A wants to do less, B wants to cover more. The synthesis finds the right balance — every plan item addressed, but no unnecessary bloat.

How to Execute

When the user triggers this skill, you (the lead) orchestrate the entire workflow.

Step 0: Gather Context

1. Get the path to final-plan.md from the user's command
2. Read the final plan — extract:
   • All source file paths referenced
   • All test file paths referenced (or derive them from source paths)
   • Every discrete plan item (these become the coverage matrix rows)
3. Determine output directory — same directory as final-plan.md
4. Rename existing review files if they exist from the proposal phase:
   • review-for-A.md → proposal-review-for-A.md
   • review-for-B.md → proposal-review-for-B.md
5. Read the agent role files to embed in prompts:
   • agents/implementer.md
   • agents/guardian.md
   • agents/synthesizer.md
   • agents/critic.md
   • agents/reconciler.md
   • references/implementation-format.md

Step 1: Round 1 — Spawn A and B (Parallel)

Spawn both agents in the same turn for parallel execution.

Agent A prompt must include:

• Full content of final-plan.md
• List of source file paths to read and verify
• Implementer role (from agents/implementer.md)
• Implementation format (from references/implementation-format.md)
• Strategy assignment: Surgical — minimal diffs, correct ordering
• Output path: {output_dir}/impl-A.md
• Investigation notes path: {output_dir}/impl-notes-A.md
• Isolation rule: do NOT read impl-B.md or any other impl files

Agent B prompt must include:

• Same plan and source files
• Guardian role (from agents/guardian.md)
• Same implementation format
• Strategy assignment: Coverage — complete tests, nothing dropped
• Output path: {output_dir}/impl-B.md
• Investigation notes path: {output_dir}/impl-notes-B.md
• Isolation rule: do NOT read impl-A.md or any other impl files

Both prompts must instruct the agent to WAIT after completing, not exit.

Monitor inbox for "done" messages from both.

After both arrive: quality check (coverage matrix present, diffs included, tests specified) then convergence check.

Step 1.5: Quality Check

Verify each implementation doc has:

1. Plan items inventory — all items from the plan listed
2. Implementation steps with exact old_string → new_string diffs
3. Coverage matrix with Status column
4. Test specifications (new and modified)
5. Commit groups
6. Definition of done

If a doc fails, message the agent with specific feedback and request revision.

Step 1.6: Convergence Check

If both implementations produce the same diffs and same tests for all plan items, skip Rounds 2-3. Spawn C for a lightweight review (verify diffs against source, check for missed items), then produce implementation.md directly.

Step 2: Round 2 — Spawn C

Spawn synthesizer with:
- Instruction to read source files FIRST (Phase 0)
- Then read impl-A.md and impl-B.md
- Synthesizer role (from agents/synthesizer.md)
- Produce THREE files: impl-C.md, review-for-A.md, review-for-B.md
- Isolation rules for review files
- Wait for instructions

Step 3: Round 3 — Message A and B

When C completes, message both agents with their review files. Same isolation rules as the proposal skill.

Step 4: Round 4 — Forward Feedback to C

When both feedback messages arrive, forward to C with the reconciler role. C produces implementation.md.

Step 5: Cleanup and Present

Shutdown all agents. Present implementation.md to the user. Offer to:

• Show the full deliberation trail
• Explain specific decisions
• Proceed to execute the implementation
• Re-run any round

Building the Agent Prompts

Each prompt must be self-contained — embed everything inline.

What to Embed in Every Prompt

1. The full content of final-plan.md — verbatim
2. Source file paths — explicit list of every file to read and verify
3. Test file paths — existing tests that may need updating
4. The agent role — full content from the relevant agents/*.md file
5. The implementation format — full content from references/implementation-format.md
6. The output path and filename — exact save location
7. The isolation rule — for A and B in Rounds 1 and 3
8. The strategy assignment — Surgical for A, Coverage for B
9. The "wait" instruction — tell agents to wait after completing

Critical Instruction for All Agents

"You MUST read every source file referenced in the plan BEFORE writing any diffs. Verify that line numbers, function signatures, and variable names in the plan match the actual code. If they don't, use the actual code — do not copy stale references from the plan."

Error Handling

Agent Timeout / Exit Recovery

Quality Gate Failures

If an implementation doc fails the quality check after Round 1, message the agent with specific feedback and request revision before proceeding.

Known Tradeoffs

Reconciler bias toward own synthesis: Same as the proposal skill — C naturally favors its own impl-C.md when reconciling. The reconciler role includes bias awareness guidance, but for critical implementations, review the synthesis yourself before feedback rounds.

Diff staleness: Between the time agents read source files and the time implementation.md is produced, the source code could change (if someone is actively coding). The implementation doc captures a point-in-time snapshot. If the code changes, diffs may need re-verification.

Invoking the Skill

Direct Prompt

/adversarial-implementation .dev/proposals/caption-audio-sync-drift/final-plan.md

As a Claude Code Command

Save as .claude/commands/adversarial-implementation.md:

Read the adversarial implementation skill at .claude/skills/adversarial-implementation/SKILL.md.
Use the workflow described to produce an implementation document from the given plan.

Create a 3-agent team: implementer-a (Surgical) and implementer-b (Coverage Guardian) work
independently (FULLY ISOLATED), synthesizer-c reviews both and produces a synthesis. Then A
and B critique C. C reconciles into a final implementation.md.

Plan path: $ARGUMENTS

Output Directory

Files are saved in the same directory as the input final-plan.md:

{project}/.dev/proposals/{issue-slug}/
├── final-plan.md                ← Input
├── impl-A.md                   ← Round 1: Surgical Implementer
├── impl-B.md                   ← Round 1: Coverage Guardian
├── impl-notes-A.md             ← Round 1: A's investigation notes (subagent fallback)
├── impl-notes-B.md             ← Round 1: B's investigation notes (subagent fallback)
├── impl-C.md                   ← Round 2: Synthesis (lead-only)
├── review-for-A.md             ← Round 2: C's review for A
├── review-for-B.md             ← Round 2: C's review for B
├── impl-feedback-A.md          ← Round 3: A's feedback (subagent fallback)
├── impl-feedback-B.md          ← Round 3: B's feedback (subagent fallback)
└── implementation.md            ← Round 4: FINAL DELIVERABLE

Reference Files

Agent Roles Summary

Source: SirTheOracle/forge-toolkit — distributed by TomeVault.