name	dialectical-autocoder
description	Orchestrate adversarial player-coach loop for high-quality code synthesis. Based on dialectical autocoding methodology.
config	[object Object]

Dialectical Autocoder

Overview

This skill implements an adversarial cooperation pattern between two agents:

Player (tdd-developer): Implements code, writes tests, solves problems
Coach (coach): Validates against requirements, critiques, demands evidence

The loop continues until the coach approves or max turns are reached.

Prerequisites

Required:

Requirements document (PRD, spec, or detailed task description)
Clear acceptance criteria
Test infrastructure configured

Agents Used:

.claude/agents/tdd-developer.md - Player role
.claude/agents/coach.md - Coach role

Pre-Flight Checklist

Before starting a dialectical session, verify:

Requirements document exists and is complete
Acceptance criteria are explicit and testable
Test infrastructure is configured (test runner works)
Project has git initialized (for commit tracking)
tdd-developer and coach agents are available
No blocking technical issues exist

Orchestrator Implementation

When Claude Code executes this skill, it orchestrates the player-coach loop using the Task tool to launch fresh agent instances each turn.

Technical Flow

1. Load requirements document into context
2. Initialize: turn_count = 0, max_turns = 5, verdict = null

3. WHILE verdict != "APPROVED" AND turn_count < max_turns:
   a. turn_count += 1

   b. Launch Player (fresh instance):
      Task tool with subagent_type="general-purpose"
      Prompt includes:
      - Requirements document path
      - Previous coach feedback (if turn > 1)
      - List of issues to address
      - Request: implement and provide evidence

   c. Capture player output:
      - Files changed
      - Test results
      - Implementation summary
      - Evidence provided

   d. Launch Coach (fresh instance):
      Task tool with subagent_type="general-purpose"
      Prompt includes:
      - Requirements document path
      - Player's implementation summary
      - Files to review
      - Test output
      - Request: validate and issue verdict

   e. Parse coach verdict from output:
      Look for: <!-- VERDICT:APPROVED|REVISE|REJECTED -->

   f. If verdict == "APPROVED": break loop

4. IF verdict != "APPROVED":
   Trigger escalation protocol

5. Document turn history

Task Tool Invocation Example

Player Turn:

Task tool:
  subagent_type: "general-purpose"
  prompt: |
    You are the PLAYER in a dialectical autocoding session.

    Requirements: [path/to/requirements.md]
    Turn: 2 of 5

    Previous coach feedback:
    - Rate limiting not implemented
    - Account lockout missing

    Your task:
    1. Read the requirements document
    2. Address the coach's feedback
    3. Implement with TDD approach
    4. Run tests and ensure they pass
    5. Report: files changed, tests added, evidence

    Do NOT review your own work. The coach will validate.

Coach Turn:

Task tool:
  subagent_type: "general-purpose"
  prompt: |
    You are the COACH in a dialectical autocoding session.

    Requirements: [path/to/requirements.md]
    Turn: 2 of 5

    Player's implementation summary:
    - Added rate limiting to auth endpoints
    - Added account lockout after 10 failures
    - 12 new tests passing

    Files to review: [list of files]
    Test output: [test results]

    Your task:
    1. Compare implementation to EACH requirement
    2. Verify evidence provided
    3. Identify any gaps or issues
    4. Issue verdict with structured marker

    End your review with exactly one of:
    <!-- VERDICT:APPROVED -->
    <!-- VERDICT:REVISE -->
    <!-- VERDICT:REJECTED -->

Fresh Context Implementation

"Fresh context" means each agent turn uses a NEW Task tool invocation:

Previous conversation history is NOT included
Only structured data carries forward:
- Requirements document (constant)
- Previous verdict and specific feedback
- Files changed (for coach review)
This prevents:
- Context pollution from failed approaches
- Anchoring to previous attempts
- Accumulating confusion in long sessions

Turn Limit Enforcement

The orchestrator MUST:

Initialize turn counter at session start: turn = 0
Increment BEFORE each player turn: turn += 1
Check limit BEFORE starting new turn: if turn > max_turns: escalate()
Log each turn: "Turn X of Y - Player/Coach phase"
Automatically trigger escalation if limit exceeded
Never allow more than max_turns iterations

Key Concepts

Fresh Context Each Turn

Each turn starts with fresh context to prevent:

Context pollution from previous attempts
Anchoring to failed approaches
Accumulating confusion

The requirements document serves as the constant anchor across turns.

Bounded Turns

The loop has explicit limits:

Default: 5 turns maximum
Escalation: If not approved by max turns, requires human review
Each turn must show measurable progress

Requirements as Contract

The requirements document is the source of truth:

Player implements TO the requirements
Coach validates AGAINST the requirements
Disputes resolved by referring to requirements
Ambiguity in requirements = pause and clarify

Workflow

Phase 1: Initialization

Identify or create the requirements document
Extract acceptance criteria
Set turn limit (default: 5)
Initialize turn counter

Phase 2: Dialectical Loop

TURN 1:
├── Player: Read requirements, implement solution
├── Player: Write tests, run tests, commit
├── Coach: Review against requirements
├── Coach: Issue verdict (REJECTED/REVISE/APPROVED)
└── If not APPROVED → continue to Turn 2

TURN 2:
├── Player: Address coach feedback (fresh context)
├── Player: Fix issues, add tests, run tests
├── Coach: Re-review with fresh perspective
├── Coach: Issue verdict
└── If not APPROVED → continue to Turn 3

... (repeat until APPROVED or max turns)

FINAL:
├── If APPROVED: Proceed to merge
├── If max turns reached: Escalate to human
└── Document the turn history

Phase 3: Completion

When coach issues APPROVED:

Create PR with full implementation
Include turn history in PR description
Link to requirements document
Ready for human merge approval

Orchestration Commands

Starting a Dialectical Session

## Starting Dialectical Autocoding Session

**Requirements:** [path to PRD or spec]
**Max Turns:** 5
**Turn:** 1 of 5

### Player Task
Using the tdd-developer agent, implement the requirements:
1. Read the requirements document thoroughly
2. Implement the solution with TDD approach
3. Run all tests and ensure they pass
4. Commit your changes
5. Report what you've implemented

### Coach Review
After player completes, using the coach agent:
1. Review implementation against requirements
2. Check all acceptance criteria
3. Demand evidence for claims
4. Issue verdict: REJECTED, REVISE, or APPROVED

Turn Transition Template

## Turn [N] of [MAX]

### Previous Turn Summary
- **Verdict:** [REVISE/REJECTED]
- **Issues to address:**
  1. [Issue 1]
  2. [Issue 2]

### Player Task (Fresh Context)
Address the coach's feedback:
- Requirements document: [path]
- Issues to fix: [list from coach]
- Evidence to provide: [what coach demanded]

Implement fixes and provide evidence.

### Coach Review
Re-review with fresh perspective:
- Verify issues are actually fixed
- Check for new issues introduced
- Validate evidence provided
- Issue new verdict

Turn Limits and Escalation

Turn Budget

Turn	Expected State
1	Initial implementation, likely REVISE
2	Major issues fixed, minor remain
3	Most issues resolved
4	Polish and edge cases
5	Must be APPROVED or escalate

Escalation Protocol

If Turn 5 results in REVISE or REJECTED:

Document the impasse
- What requirements can't be met?
- What's blocking approval?
- Is this a requirements problem or implementation problem?
Human review required
- Present turn history
- Highlight unresolved issues
- Ask for guidance or requirements clarification
Options for human
- Clarify/modify requirements
- Accept current state with known issues
- Provide implementation guidance
- Assign to different approach

Integration with Task Processor

Dialectical autocoding can be used within task-processor workflows:

### Task 1.1: Implement Feature X
- **Agent:** dialectical-autocoder
- **Requirements:** docs/PRD_feature_x.md
- **Max Turns:** 5

The dialectical loop runs as a sub-workflow:
1. Player implements (tdd-developer)
2. Coach validates (coach)
3. Loop until approved
4. Then mark task complete

Best Practices

For Players

Read requirements completely before coding
Implement incrementally, test as you go
Provide clear evidence for each requirement
Address ALL coach feedback, not just some
Don't argue with coach—fix or clarify

For Coaches

Anchor everything to requirements
Be specific about what's wrong
Demand concrete evidence
Don't move goalposts between turns
Credit progress, not just criticize

For Orchestration

Keep turn history for context
Enforce fresh context strictly
Don't skip escalation at max turns
Document final state clearly
Requirements clarification pauses the loop

Example Session

Turn 1

Player Output:

Implemented user authentication per PRD section 3.2:
- Login endpoint at /api/auth/login
- JWT token generation
- Password hashing with bcrypt
- Tests: 15 passing

Evidence:
- Test: `bun test src/auth/__tests__/login.test.ts`
- All 15 assertions pass

Coach Review:

## Coach Review: Turn 1

### Requirements Checked
- [x] Login endpoint exists
- [x] JWT tokens generated
- [x] Password hashing used
- [ ] Rate limiting NOT IMPLEMENTED (PRD 3.2.4)
- [ ] Account lockout NOT IMPLEMENTED (PRD 3.2.5)

### Verdict: REVISE

**To proceed, player must:**
- [ ] Implement rate limiting (5 attempts/minute)
- [ ] Implement account lockout after 10 failed attempts
- [ ] Add tests for both features

Turn 2