dialectic 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lior Schejter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# Dialectic - Multi-Agent Debate
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Quickstart](#quickstart)
+  - [Setup](#setup)
+  - [Basic Command](#basic-command)
+- [Commands](#commands)
+  - [Debate Command](#debate-command)
+  - [Evaluator Command](#evaluator-command)
+  - [Report Command](#report-command)
+- [Configuration](#configuration)
+
+## Overview
+
+Dialectic is a CLI tool that orchestrates multi-agent debates to solve software design problems. Multiple AI agents with different perspectives (architecture, performance, security) debate a problem through structured rounds of proposals, critiques, and refinements, culminating in a synthesized solution from a judge agent.
+
+## Quickstart
+
+### Setup
+
+**Requirements:**
+- **Node.js** >= 18
+- **API Key**: Set `OPENAI_API_KEY` (for OpenAI) or `OPENROUTER_API_KEY` (for OpenRouter) in a `.env` file or as an environment variable
+
+**Installation:**
+
+For end users (when published to npm):
+```bash
+npm install -g dialectic
+```
+
+For local development:
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Link the dialectic command globally
+npm link
+```
+
+**API Key Setup:**
+
+Create a `.env` file in your project directory:
+```bash
+OPENAI_API_KEY=sk-your-key-here
+# OR
+OPENROUTER_API_KEY=sk-or-your-key-here
+```
+
+### Basic Command
+
+Run a debate with a problem statement:
+```bash
+dialectic debate "Design a rate limiting system"
+```
+
+Or use a problem description file:
+```bash
+dialectic debate --problemDescription problem.txt
+```
+
+## Commands
+
+Dialectic provides three main commands:
+
+- **`debate`** - Orchestrate a multi-agent debate to solve a design problem
+- **`eval`** - Evaluate a completed debate using evaluator agents
+- **`report`** - Generate a markdown report from a saved debate state
+
+For detailed command documentation, including all options and examples, see [docs/commands.md](docs/commands.md).
+
+### Debate Command
+
+The `debate` command orchestrates a multi-agent debate to solve a software design problem. You provide a problem statement (either inline or from a file), and multiple AI agents with different perspectives debate the problem through structured rounds. Each round consists of proposals, critiques, and refinements, culminating in a synthesized solution from a judge agent. The command supports various options for customizing agent roles, number of rounds, output format, and includes features like interactive clarifications and detailed reporting.
+
+### Evaluator Command
+
+The `eval` command evaluates a completed debate using evaluator agents. This allows you to assess the quality and effectiveness of a debate's outcome by running specialized evaluator agents that analyze the debate process and final solution. The evaluators provide structured feedback and scores across multiple dimensions, helping you understand the strengths and weaknesses of the debate outcome.
+
+### Report Command
+
+The `report` command generates a comprehensive markdown report from a saved debate state JSON file. This is useful when you want to create a detailed report from a previously completed debate without re-running it. The report includes the full debate transcript, agent contributions, clarifications (if any), and the final synthesis, formatted as a readable markdown document.
+
+## Configuration
+
+Debate behavior is configured via a JSON file (default: `./debate-config.json`). If the file is missing, built-in defaults are used.
+
+For detailed configuration documentation, including all fields, validation rules, and examples, see [docs/configuration.md](docs/configuration.md).

package/WARP.md

@@ -0,0 +1,113 @@
+# WARP.md
+
+This file provides guidance to WARP (warp.dev) when working with code in this repository.
+
+## Setup and prerequisites
+- Node.js >= 18
+- macOS/zsh (set OpenAI key):
+  ```sh
+  export OPENAI_API_KEY="{{OPENAI_API_KEY}}"
+  ```
+- Install dependencies:
+  ```sh
+  npm install
+  ```
+
+## Common commands
+- Build
+  ```sh
+  npm run build
+  ```
+- Lint
+  - No linter configured in this repo (no eslint/prettier config or npm scripts).
+- Tests
+  - All tests
+    ```sh
+    npm test
+    ```
+  - Watch mode
+    ```sh
+    npm run test:watch
+    ```
+  - Coverage
+    ```sh
+    npm run test:coverage
+    ```
+  - Single test file
+    ```sh
+    npx jest tests/<file>.spec.ts
+    # example:
+    npx jest tests/orchestrator.spec.ts
+    ```
+  - Single test by name
+    ```sh
+    npx jest -t "<test name substring>"
+    ```
+- Run the CLI during development (TypeScript, full command)
+  ```sh
+  # Inline problem text
+  npx ts-node src/cli/index.ts debate "Design a rate limiting system"
+
+  # File-based problem
+  npx ts-node src/cli/index.ts debate --problemDescription path/to/problem.txt
+
+  # Verbose and output examples
+  npx ts-node src/cli/index.ts debate "Design a rate limiting system" --verbose
+  npx ts-node src/cli/index.ts debate "Design a rate limiting system" --output result.json
+  npx ts-node src/cli/index.ts debate "Design a rate limiting system" --output solution.txt
+  ```
+- Run the built JavaScript CLI (after build)
+  ```sh
+  node dist/cli/index.js debate "Design a rate limiting system"
+  node dist/cli/index.js debate --problemDescription path/to/problem.txt --verbose
+  node dist/cli/index.js debate "Design a rate limiting system" --output result.json
+  node dist/cli/index.js debate "Design a rate limiting system" --output solution.txt
+  ```
+
+## Architecture overview
+- CLI layer
+  - `src/cli/index.ts` bootstraps Commander, registers the `debate` command, and centralizes stderr helpers (warnUser, infoUser, writeStderr). The published binary is `debate` (see package.json `bin`).
+- Debate command flow
+  - `src/cli/commands/debate.ts` parses args, enforces exactly-one of problem string vs `--problemDescription`, validates `OPENAI_API_KEY`, loads `SystemConfig` (defaults if missing/incomplete with warnings), filters agents, resolves system prompts (built-in vs file), records provenance, runs the orchestrator, and handles output.
+- Providers
+  - `src/providers/openai-provider.ts` exposes `complete()` with a two-tier strategy: OpenAI Responses API first, falling back to Chat Completions. Returns text, usage, and latency for contribution metadata.
+- Agents and Judge
+  - Role agents live under `src/agents/` and extend the base in `src/core/agent.ts`. The judge (`src/core/judge.ts`) synthesizes the final solution after all rounds complete.
+- Orchestration
+  - `src/core/orchestrator.ts` runs N full rounds: proposal → critique → refinement (all three every round), then judge synthesis. Optional hooks log phase completion in verbose mode.
+- State persistence
+  - `src/core/state-manager.ts` persists debate state JSON files under `./debates` after initialization, at round start, after each contribution, and on completion.
+- Output behavior
+  - By default, final solution text is written to stdout. If `--output` ends with `.json`, the full debate state is written; otherwise only the solution text. Verbose summaries and save-path notices go to stderr (pipe-friendly).
+
+## Configuration essentials
+- Full schema and defaults: see `docs/configuration.md`.
+- Default config path: `./debate-config.json` (resolved from current working directory).
+- If agents are missing/empty → built-in defaults are used (architect + performance) with warnings.
+- If judge/debate missing → they are filled from defaults (warning for judge).
+- `systemPromptPath` is resolved relative to the configuration file’s directory; if invalid/empty/unreadable, the built-in prompt is used and the chosen source is recorded once per debate.
+- Environment requirement: `OPENAI_API_KEY` must be set before invoking the CLI.
+
+## Execution flow at a glance
+- High-level steps (details and diagram in `docs/debate_flow.md`):
+  1) CLI parses arguments and resolves the problem (string or file)
+  2) Validates `OPENAI_API_KEY` and loads `SystemConfig`
+  3) Initializes provider, agents, and judge (with prompt provenance)
+  4) Orchestrator runs N rounds: proposal → critique → refinement (all three per round)
+  5) Judge synthesizes the final solution
+  6) State is saved throughout under `./debates/<debate-id>.json`
+  7) Output written to stdout or a file per `--output`
+
+## Debugging and logs
+- Saved debate path is written to stderr: `Saved debate to ./debates/<debate-id>.json`
+- Use `--verbose` for round-by-round summaries (to stderr), including latency and token stats when available.
+- Tests mock OpenAI; use `npm test` for fast iterations.
+- Git commit graph (if you use a global alias):
+  ```sh
+  git tree --all --decorate --oneline
+  ```
+
+## References
+- `README.md` (CLI usage, options, exit codes)
+- `docs/configuration.md` (complete configuration schema and defaults)
+- `docs/debate_flow.md` (sequence diagram and deeper flow)

package/dialectic.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+const { runCli } = require('./dist/cli/index.js');
+const { EXIT_GENERAL_ERROR } = require('./dist/utils/exit-codes.js');
+
+runCli(process.argv.slice(2)).catch((err) => {
+  const code = typeof err?.code === 'number' ? err.code : EXIT_GENERAL_ERROR;
+  const msg = err?.message || 'Unknown error';
+  process.stderr.write(msg + '\n');
+  process.exit(code);
+});

package/docs/commands.md

@@ -0,0 +1,375 @@
+# Dialectic Commands
+
+This document provides comprehensive documentation for all Dialectic CLI commands, including options, examples, and detailed usage information.
+
+## Table of Contents
+
+- [Debate Command](#debate-command)
+- [Evaluator Command](#evaluator-command)
+- [Report Command](#report-command)
+- [Exit Codes](#exit-codes)
+
+## Debate Command
+
+The `debate` command orchestrates a multi-agent debate to solve a software design problem. Multiple AI agents with different perspectives debate the problem through structured rounds of proposals, critiques, and refinements, culminating in a synthesized solution from a judge agent.
+
+### Basic Usage
+
+**Inline problem string:**
+```bash
+dialectic debate "Design a rate limiting system"
+```
+
+**With problem description file:**
+```bash
+dialectic debate --problemDescription problem.txt
+dialectic debate --problemDescription ./problems/rate-limiting.md
+```
+
+### Command Options
+
+- `[problem]` - Problem statement as inline string (mutually exclusive with `--problemDescription`)
+- `--problemDescription <path>` - Path to a text file containing the problem description
+  - **Encoding**: UTF-8
+  - **Format**: Any text format (plain text, markdown, etc.)
+  - **Content**: Must be non-empty (whitespace-only files are rejected)
+  - **Path resolution**: Relative paths resolved from current working directory
+  - **Mutual exclusivity**: Cannot provide both string problem and `--problemDescription` file
+- `--agents <list>` - Comma-separated agent roles to participate (default: `architect,performance,kiss`)
+  - Available roles: `architect`, `performance`, `security`, `testing`, `kiss`, `generalist`
+  - Filters agents from configuration file by role; uses defaults if no matches found
+- `--rounds <n>` - Number of debate rounds (default: `3`, minimum: `1`)
+- `--config <path>` - Path to configuration file (default: `./debate-config.json`)
+- `--env-file <path>` - Path to environment file (default: `.env`)
+- `--output <path>` - Output file path
+  - If ending with `.json`: writes full debate state
+  - Otherwise: writes final solution text only
+  - If omitted: solution written to stdout, state saved to `./debates/` directory
+- `--verbose` - Enable detailed logging with round-by-round breakdown
+  - Detailed summary written to `stderr` including:
+    - Round-by-round breakdown
+    - Individual contributions with metadata (tokens, latency)
+    - Total statistics (rounds, duration, token counts)
+- `--report <path>` - Generate a detailed Markdown report of the debate
+  - If the path does not end with `.md`, the extension is appended automatically
+  - Creates parent directories as needed
+  - Non-fatal on failure (debate still succeeds even if report generation fails)
+- `--clarify` - Run a one-time pre-debate clarifications phase
+  - Each agent can ask up to 5 clarifying questions (configurable)
+  - Interactive Q&A session before the debate begins
+  - Questions and answers are included in the debate context and final report
+
+### Examples
+
+**Basic debate:**
+```bash
+dialectic debate "Design a rate limiting system"
+```
+
+**With specific agent roles:**
+```bash
+dialectic debate "Design a secure authentication system" --agents architect,security
+dialectic debate "Build a high-performance API" --agents architect,performance,security
+```
+
+**With clarifications phase:**
+```bash
+dialectic debate "Design a rate limiting system" --clarify
+dialectic debate --problemDescription complex-problem.md --clarify --agents architect,security,performance
+```
+
+**With custom configuration:**
+```bash
+dialectic debate "Design a caching system" --config ./configs/production.json
+```
+
+**Save solution to file:**
+```bash
+dialectic debate "Design a system" --output solution.txt
+```
+
+**Save full debate state:**
+```bash
+dialectic debate "Design a system" --output debate-result.json
+```
+
+**Generate report:**
+```bash
+dialectic debate "Design a rate limiting system" --report ./reports/rate-limit
+dialectic debate --problemDescription problems/rate-limiting.md --verbose --report ./reports/rate-limit.md
+```
+
+**Complex example with all options:**
+```bash
+dialectic debate \
+  --problemDescription ./problems/rate-limiting.md \
+  --config ./configs/production.json \
+  --agents architect,performance,security \
+  --rounds 5 \
+  --output ./results/rate-limiting-solution.json \
+  --report ./reports/rate-limiting-report.md \
+  --verbose \
+  --clarify \
+  --env-file .env.production
+```
+
+### Output Behavior
+
+**Default behavior:**
+- Final solution text written to `stdout`
+- Complete debate state saved to `./debates/<debate-id>.json`
+- Save path notification written to `stderr`
+
+**With `--output` option:**
+- If path ends with `.json`: full debate state written to file
+- Otherwise: only final solution text written to file
+
+### Markdown Report (`--report`)
+
+Generate a comprehensive Markdown report capturing the full debate transcript and metadata.
+
+**Report contents:**
+- Problem Description
+- Agents table and Judge table
+- Clarifications (if `--clarify` was used):
+  - Questions and answers grouped by agent
+  - Includes "NA" responses for skipped questions
+- Rounds with sections:
+  - Proposals
+  - Critiques
+  - Refinements
+- Final Synthesis
+
+**Notes:**
+- When `--verbose` is provided, contribution titles include metadata such as latency and tokens.
+- If a section has no items, a succinct "No … in this round." line is shown.
+- The report path is normalized to `.md` and parent directories are created automatically.
+
+### Interactive Clarifications (`--clarify`)
+
+The `--clarify` option enables a pre-debate interactive clarification phase where agents can ask clarifying questions about the problem statement. This feature helps ensure all agents have a clear understanding before the debate begins.
+
+**How it works:**
+1. Each participating agent generates up to 5 clarifying questions (configurable via `clarificationsMaxPerAgent` in config)
+2. The CLI presents questions grouped by agent in an interactive session
+3. You can answer each question or press Enter to skip (recorded as "NA")
+4. Questions and answers are included in the debate context and final report
+5. The judge does not participate in the clarification phase
+
+**Configuration options:**
+- `debate.interactiveClarifications`: Enable clarifications by default (boolean, default: false)
+- `debate.clarificationsMaxPerAgent`: Maximum questions per agent (number, default: 5)
+- `AgentConfig.clarificationPromptPath`: Custom clarification prompt for specific agents
+
+**Example workflow:**
+```bash
+dialectic debate "Design a distributed cache system" --clarify
+# Agents ask questions like:
+# [Architect] Q1: What are the expected read/write ratios?
+# > 80% reads, 20% writes
+# [Performance] Q2: What's the target latency requirement?
+# > < 10ms for 95th percentile
+# [Security] Q3: What data sensitivity level?
+# > (press Enter to skip)
+# Q3: NA
+```
+
+### Technical Details
+
+**LLM Providers:**
+- **OpenAI**: Direct integration with OpenAI API using OpenAI SDK
+- **OpenRouter**: Integration with OpenRouter API using OpenAI SDK for compatibility
+- Both providers support Responses API with fallback to Chat Completions API
+
+**Debate Round Flow:**
+- Round 1: Proposals are generated via LLM, then critiques, then refinements.
+- Rounds ≥ 2: Each agent's proposal is the previous round's refinement (no LLM call). If a prior refinement is missing, the system warns to stderr and falls back to generating a proposal via LLM for that agent only. Critiques and refinements proceed as usual against the current round's proposals.
+
+**Debate Persistence:**
+- Debate states are saved to `./debates/` directory
+- Filename format: `deb-YYYYMMDD-HHMMSS-RAND.json`
+- Files are saved incrementally during execution and upon completion
+
+**Agent Roles:**
+- `architect`: System design and architecture perspective
+- `performance`: Performance optimization and efficiency perspective
+- `security`: Security and threat modeling perspective
+- `testing`: Testing strategy and quality assurance perspective (future use)
+- `kiss`: Simplicity-focused perspective, challenges complexity
+- `generalist`: General-purpose role (typically used for judge)
+
+**Context Summarization:**
+- Automatically manages debate history length to avoid context window limitations
+- Each agent independently summarizes their perspective-based history when it exceeds configured thresholds
+- Agent-specific summaries stored per round, keyed by agent ID for isolated access
+- Dynamic retrieval: agents always see their own most recent summary
+- Configurable at both system-wide and per-agent levels
+- Summaries preserve critical insights while reducing context size for subsequent rounds
+- Default threshold: 5000 characters, max summary length: 2500 characters
+- See `docs/configuration.md` and `docs/context_summarization.md` for detailed documentation
+
+## Evaluator Command
+
+The `eval` command evaluates a completed debate using evaluator agents. This allows you to assess the quality and effectiveness of a debate's outcome.
+
+**Basic usage:**
+```bash
+dialectic eval --config ./eval-config.json --debate ./debates/deb-YYYYMMDD-HHMMSS-XYZ.json
+```
+
+**With JSON output:**
+```bash
+dialectic eval \
+  --config ./eval-config.json \
+  --debate ./debates/deb-20250101-010203-ABC.json \
+  --output ./results/evaluation.json
+```
+
+**With verbose logs:**
+```bash
+dialectic eval \
+  --config ./eval-config.json \
+  --debate ./debates/deb-20250101-010203-ABC.json \
+  --verbose \
+  --env-file .env
+```
+
+### Command Options
+
+- `-c, --config <path>` - Evaluator configuration JSON (required)
+- `-d, --debate <path>` - Debate state JSON to evaluate (required)
+- `--env-file <path>` - Optional .env file path
+- `-v, --verbose` - Verbose diagnostic logs to stderr
+- `-o, --output <path>` - Output destination
+  - If ends with `.json`: writes aggregated JSON output
+  - Otherwise: writes Markdown table (or stdout by default)
+
+### Examples
+
+**Basic evaluation:**
+```bash
+dialectic eval --config ./eval-config.json --debate ./debates/deb-20250101-010203-ABC.json
+```
+
+**Evaluator with JSON output:**
+```bash
+dialectic eval \
+  --config ./eval-config.json \
+  --debate ./debates/deb-20250101-010203-ABC.json \
+  --output ./results/evaluation.json
+```
+
+**Evaluator with verbose logs:**
+```bash
+dialectic eval \
+  --config ./eval-config.json \
+  --debate ./debates/deb-20250101-010203-ABC.json \
+  --verbose \
+  --env-file .env
+```
+
+For detailed evaluator documentation, see [docs/evaluator.md](evaluator.md).
+
+## Report Command
+
+The `report` command generates a markdown report from a saved debate state JSON file. This command is useful when you want to create a report from a previously completed debate without re-running it.
+
+**Basic usage:**
+```bash
+# Generate report and write to stdout
+dialectic report --debate ./debates/deb-20250101-010203-ABC.json
+
+# Write report to a file
+dialectic report --debate ./debates/deb-20250101-010203-ABC.json --output ./reports/debate-report.md
+
+# With verbose metadata (latency, tokens in contribution titles)
+dialectic report --debate ./debates/deb-20250101-010203-ABC.json --verbose --output ./reports/debate-report.md
+
+# Use custom configuration file
+dialectic report --debate ./debates/debate.json --config ./custom-config.json --output report.md
+```
+
+### Command Options
+
+- `--debate <path>` - **Required**. Path to debate JSON file (DebateState format)
+- `--config <path>` - Optional. Path to configuration file
+  - If provided: loads configuration file and matches agent/judge configs with agent IDs found in debate state
+  - If not provided: creates minimal agent/judge configs from debate state (no validation of IDs)
+- `-o, --output <path>` - Optional. Path to output markdown file (default: stdout)
+  - If not provided, writes report to stdout (allows piping: `report --debate file.json > output.md`)
+  - Creates parent directories automatically if they don't exist
+  - Overwrites existing file if it exists
+- `-v, --verbose` - Optional. Enable verbose mode for report generation
+  - Includes metadata (latency, tokens) in contribution titles
+
+### Report Contents
+
+- Problem Description
+- Agents table (from configuration file if provided, or minimal configs from debate state)
+- Judge table (from configuration file if provided, or minimal config from debate state)
+- Clarifications (if any were collected during the debate)
+- Rounds with sections:
+  - Proposals
+  - Critiques
+  - Refinements
+- Final Synthesis
+
+### How It Works
+
+1. Loads and validates the debate state JSON file
+2. If `--config` is provided:
+   - Loads configuration file to get agent and judge configurations
+   - Matches agent configs with agent IDs found in the debate state contributions
+3. If `--config` is not provided:
+   - Creates minimal agent/judge configs from debate state (extracts agent IDs and roles from contributions)
+   - No validation of agent/judge IDs is performed
+4. Generates markdown report using the same generator as the `--report` option in the debate command
+5. Writes report to stdout or specified file
+
+### Differences from `--report` Option
+
+- `--report` in `debate` command: Generates report during an active debate from in-memory state
+- `report` command: Generates report from a saved debate state JSON file after the debate is complete
+- Both produce the same markdown format and content structure
+
+### Error Handling
+
+- Exits with error code 2 (EXIT_INVALID_ARGS) if:
+  - Debate file doesn't exist
+  - Debate file is invalid JSON
+  - Debate file is missing required fields (id, problem, status, rounds)
+  - Path is a directory instead of a file
+- Exits with error code 1 (EXIT_GENERAL_ERROR) for other errors
+
+### Examples
+
+```bash
+# Generate report from a saved debate and view it
+dialectic report --debate ./debates/deb-20250101-010203-ABC.json
+
+# Save report to file
+dialectic report --debate ./debates/deb-20250101-010203-ABC.json --output ./reports/my-debate-report.md
+
+# Generate report with verbose metadata and custom config
+dialectic report --debate ./debates/debate.json --config ./configs/production.json --verbose --output report.md
+
+# Pipe report to another command
+dialectic report --debate ./debates/debate.json | grep "Final Synthesis"
+```
+
+## Exit Codes
+
+| Code | Description |
+|------|-------------|
+| `0` | Success |
+| `1` | General error |
+| `2` | Invalid CLI arguments (e.g., missing problem, invalid rounds) |
+| `3` | Provider error (reserved for future use) |
+| `4` | Configuration error (e.g., missing `OPENAI_API_KEY`) |
+
+**Checking exit codes:**
+```bash
+dialectic debate "Design a system" && echo "Success!"
+dialectic debate "Design a system" || echo "Failed with code: $?"
+```
+