Dialectical Loop

Dialectical Loop

Run a bounded, adversarial coding workflow rather than single-turn “vibe coding”.

Core idea

• Architect turns high-level intent (REQUIREMENTS.md) into an actionable contract (SPECIFICATION.md).
• Player implements the specification and runs verification commands.
• Coach adversarially evaluates compliance and blocks until it’s correct.

This keeps attention bounded, forces explicit plans, and adds a strict review gate.

Inputs / outputs

• Input: REQUIREMENTS.md (recommended)
• Generated/optional input: SPECIFICATION.md
• Output: code edits + command outputs per turn

Agent prompts (no manual install)

This skill ships its role prompts inside the skill folder:

• agents/architect.md
• agents/player.md
• agents/coach.md

The orchestrator loads these files automatically at runtime. You do not need to “install agents” separately or configure them in OpenSkills.

Key Features

• Bounded iteration: --max-turns prevents runaway token usage
• Fast-fail optimization: Skip Coach if verification fails (save tokens)
• Auto-context switching: Full snapshot turn 1 → git-changed thereafter
• Token-optimized: --lean-mode activates all savings (fast-fail, coach-focus-recent, auto-fix)
• Production observability: JSON logs with token estimates, loop health metrics, inter-agent communication tracking

Prerequisites

• Python 3.10+
• GitHub CLI authenticated (gh auth login or GITHUB_TOKEN set)
• GitHub Copilot CLI available as copilot command

Essential Options

• --max-turns N — Bound the loop (required)

• --lean-mode — Activate all token optimizations (recommended)

• --verbose — Detailed debug output

• --quiet — Minimal output (final summary only)

• --skip-architect — Use existing SPECIFICATION.md

• --architect-model, --player-model, --coach-model — Override defaults

Recommended Models (GitHub Copilot CLI)

Tier 1 (Balanced): claude-sonnet-4.5 for all roles (38 units/5 turns) Tier 2 (Budget): gemini-3-pro-preview Architect, claude-haiku-4.5 Player, claude-sonnet-4.5 Coach (26 units) Tier 3 (Premium): claude-opus-4.5 Architect/Coach, claude-sonnet-4.5 Player (~79 units)

Observability

Automatic JSON logs (dialectical-loop-TIMESTAMP.json) include:

• Per-turn events (agent, model, tokens, duration)
• Loop health metrics (zero-edit streaks, fast-fail spirals)
• Inter-agent communication tracking (feedback coverage, error persistence)
• Real-time warnings for stuck patterns

Usage Examples

# Basic usage
python ~/.claude/skills/dialectical-loop/scripts/dialectical_loop.py --max-turns 10

# Token-optimized
python ~/.claude/skills/dialectical-loop/scripts/dialectical_loop.py --max-turns 10 --lean-mode

# With existing spec
python ~/.claude/skills/dialectical-loop/scripts/dialectical_loop.py --skip-architect --max-turns 5

Complete Documentation

See README.md for:

• Installation instructions
• Complete options reference
• Model selection guide (3 tiers with cost analysis)
• Token-saving strategies
• Dynamic spec pruning
• Verification configuration
• Troubleshooting
• Cross-platform shell configuration