Claude Code Plugins

Community-maintained marketplace

Feedback

dialectical-loop

@chipfox/dialetic-agents
0
0

Run a bounded adversarial cooperation coding loop (Architect -> Player <-> Coach). Use when implementing features from REQUIREMENTS.md, generating SPECIFICATION.md plans, and iterating with strict review until approved.

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

name dialectical-loop
description Run a bounded adversarial cooperation coding loop (Architect -> Player <-> Coach). Use when implementing features from REQUIREMENTS.md, generating SPECIFICATION.md plans, and iterating with strict review until approved.
version 1.0.3
tags coding, multi-agent, code-review, automation, dialectical, python, llm, workflow, github-copilot
author chipfox
repository https://github.com/chipfox/dialetic-agents
license MIT

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