dialectic 0.1.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "dialectic",
+  "version": "0.1.0",
+  "description": "",
+  "main": "index.js",
+  "bin": {
+    "dialectic": "./dialectic.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/cli/index.ts",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "prepare": "npm run build"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.0.0",
+    "dotenv": "^16.3.1",
+    "openai": "^4.52.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^24.6.2",
+    "jest": "^29.7.0",
+    "nodemon": "^3.1.10",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}

package/sanity-check-problem.txt

@@ -0,0 +1,9 @@
+Design a simple in-memory cache system with the following requirements:
+
+1. Store key-value pairs where keys are strings and values can be any object
+2. Support TTL (time-to-live) expiration for cache entries
+3. Implement LRU (Least Recently Used) eviction policy when cache reaches capacity
+4. Provide thread-safe operations for concurrent access
+5. Include basic metrics like hit rate and cache size
+
+The system should be lightweight and suitable for a web application handling moderate traffic.

package/src/agents/prompts/architect-prompts.ts

@@ -0,0 +1,203 @@
+import { RolePrompts } from './prompt-types';
+import { prependContext } from '../../utils/context-formatter';
+import { appendSharedInstructions, INSTRUCTION_TYPES } from './shared';
+import type { DebateContext } from '../../types/debate.types';
+
+
+const BASE_SYSTEM_PROMPT = `You are an expert software architect specializing in distributed systems and scalable architecture design.
+
+Your focus: scalability, performance, component boundaries, interfaces, architectural patterns, data flow, state management, and operational concerns.
+
+When proposing solutions:
+- Begin with the high-level architecture and rationale
+- Identify main components and their responsibilities
+- Describe communication and data flow
+- Highlight scalability, reliability, and observability considerations
+
+When critiquing:
+- Identify architectural bottlenecks or weaknesses
+- Assess clarity of component boundaries and data ownership
+- Examine scalability, fault tolerance, and operational complexity
+- Suggest concrete, principle-based improvements
+`;
+
+/**
+ * Prompts for the Architect role, specializing in software architecture and system design.
+ * 
+ * The architect focuses on scalability, component boundaries, architectural patterns,
+ * data flow, and operational concerns.
+ */
+export const architectPrompts: RolePrompts = {
+  systemPrompt: appendSharedInstructions(BASE_SYSTEM_PROMPT, INSTRUCTION_TYPES.SYSTEM),
+
+  proposePrompt: (problem: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => {
+    const basePrompt = `Problem to solve:
+${problem}
+
+As an architect, propose a comprehensive solution including approach, key components, challenges, and justification.
+
+Use the following Markdown structure in your response:
+### Architecture Overview
+(Provide a 3–5 sentence summary of the overall architecture, guiding principles, and key design intent.)
+
+### Key Components and Responsibilities
+(List major components/services and describe each one’s main role.)
+
+### Data Flow and Interactions
+(Describe how data and control flow between components. Mention APIs, events, or message flows if relevant.)
+
+### Architectural Patterns and Rationale
+(State which design or architectural patterns are used — e.g., microservices, CQRS, event-driven — and justify why they fit this problem.)
+
+### Non-Functional Considerations
+#### Scalability and Performance
+(Discuss scaling strategy, bottleneck mitigation, and performance aspects.)
+#### Security
+(Outline authentication, authorization, and data protection strategies.)
+#### Maintainability and Evolvability
+(Describe modularity, extensibility, and how the design supports change.)
+#### Operational Concerns
+(Deployment, monitoring, resilience, observability.)
+#### Regulatory/Compliance (if applicable)
+(Discuss awareness of relevant compliance concerns, or note "Not applicable.")
+
+### Key Challenges and Trade-offs
+(Identify main architectural trade-offs, risks, or limitations.)
+
+### Optional: Technology Choices
+(If specific technologies clarify the design intent, list them briefly here.)
+
+---
+
+Respond **only** in this structured format.
+Avoid generalities — make concrete architectural claims and reasoning.
+`;
+    const promptWithContext = prependContext(basePrompt, context, agentId, includeFullHistory);
+    return appendSharedInstructions(promptWithContext, INSTRUCTION_TYPES.PROPOSAL);
+  },
+
+  critiquePrompt: (proposalContent: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => {
+    const basePrompt = `Review this proposal from an architectural perspective.
+
+Proposal:
+${proposalContent}
+
+Use the following Markdown structure for your critique:
+
+### Architectural Strengths
+(List the strongest aspects — e.g., clear component boundaries, good scalability strategy, sound data design.)
+
+### Weaknesses and Risks
+(Identify architectural issues: missing components, unclear data ownership, poor fault tolerance, coupling issues, etc.)
+
+### Improvement Suggestions
+(Suggest specific, actionable architectural changes or refinements.)
+
+### Critical Issues
+(Highlight any major flaws that could cause operational, performance, or correctness problems if not addressed.)
+
+### Overall Assessment
+(Brief summary judgment: Is the design sound overall? Why or why not?)
+
+---
+
+Your tone should be professional and evidence-based.  
+Avoid vague comments — reason from architectural principles.
+`;
+    const promptWithContext = prependContext(basePrompt, context, agentId, includeFullHistory);
+    return appendSharedInstructions(promptWithContext, INSTRUCTION_TYPES.CRITIQUE);
+  },
+
+  refinePrompt: (originalContent: string, critiquesText: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => {
+    const basePrompt = `Original proposal:
+${originalContent}
+
+Critiques:
+${critiquesText}
+
+Refine your proposal by addressing valid concerns, incorporating good suggestions, and strengthening the solution.
+
+Refine the original design using the following Markdown structure in your response:
+
+### Updated Architecture Overview
+(Summarize how the design has evolved, referencing key feedback addressed.)
+
+### Revised Components and Changes
+(Describe specific improvements or restructuring made to components.)
+
+### Addressed Issues
+(List the critiques or concerns that have been directly resolved.)
+
+### Remaining Open Questions
+(If some critiques were invalid, unclear, or intentionally left unaddressed, explain why.)
+
+### Final Architectural Summary
+(Provide the improved architecture in concise form, integrating new insights while maintaining coherence.)
+
+---
+
+The goal is to produce a **stronger, more defensible design** — not just edits.
+Be explicit about what changed and why.
+`
+    const promptWithContext = prependContext(basePrompt, context, agentId, includeFullHistory);
+    return appendSharedInstructions(promptWithContext, INSTRUCTION_TYPES.REFINEMENT);
+  },
+
+  summarizePrompt: (content: string, maxLength: number) => {
+    const basePrompt = `You are summarizing the debate history from an architectural perspective. Focus on key architectural decisions, component designs, scalability concerns, and design patterns that have been discussed.
+
+Debate history to summarize:
+${content}
+
+Create a concise summary (maximum ${maxLength} characters) that preserves the most important architectural insights, decisions, and open questions. Focus on information that will be useful for future rounds of the debate.
+
+### Key Architectural Decisions
+(List the most significant decisions made so far — component structure, communication patterns, technology direction.)
+
+### Major Trade-offs Discussed
+(Summarize debates around scalability, consistency, or performance vs. complexity.)
+
+### Unresolved Questions or Conflicts
+(Identify points that remain debated or need further exploration.)
+
+### Emerging Consensus
+(Briefly describe what the participants seem to agree upon.)
+
+### Lessons Learned or Insights
+(Capture meta-level architectural reasoning or patterns discovered.)
+
+---
+
+Keep it concise, factual, and focused on architectural reasoning.
+`;
+    return appendSharedInstructions(basePrompt, INSTRUCTION_TYPES.SUMMARIZATION);
+  },
+
+  clarifyPrompt: (problem: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => {
+    const basePrompt = `You are preparing clarifying questions from an **architectural perspective**.
+
+Problem to clarify:
+${problem}
+
+Your goal is to identify missing, ambiguous, or underspecified information that would significantly influence architectural decisions. 
+Focus on questions that would meaningfully improve the quality of a future software architecture proposal.
+
+When thinking about what to ask, consider:
+- Scalability (e.g., expected load, traffic patterns, horizontal vs. vertical scaling)
+- Performance (latency, throughput, resource constraints)
+- Component boundaries and interfaces (APIs, responsibilities, integrations)
+- Architectural patterns and styles (event-driven, layered, microservices, etc.)
+- Data flow and state management (data ownership, consistency model, persistence)
+- Operational and deployment concerns (availability, fault tolerance, monitoring)
+- Security or compliance constraints (authentication, data protection, privacy)
+
+Guidelines:
+- Prefer **high-signal, clarifying questions** that would directly impact architectural direction.
+- Avoid trivial or redundant questions (e.g., restating information already in the problem).
+- If the problem is already well-specified, you may return no questions.
+- Each question must be **concise and independent** — do not bundle multiple subquestions.`;
+    const promptWithContext = prependContext(basePrompt, context, agentId, includeFullHistory);
+    return appendSharedInstructions(promptWithContext, INSTRUCTION_TYPES.CLARIFICATION);
+  },
+};
+

package/src/agents/prompts/generalist-prompts.ts

@@ -0,0 +1,157 @@
+import { RolePrompts } from './prompt-types';
+import { prependContext } from '../../utils/context-formatter';
+import { appendSharedInstructions, INSTRUCTION_TYPES } from './shared';
+import type { DebateContext } from '../../types/debate.types';
+
+/**
+ * Prompts for the Generalist role, providing balanced multi-perspective analysis.
+ * 
+ * The generalist focuses on overall solution quality, balancing trade-offs across
+ * different concerns (architecture, performance, security, testing).
+ */
+export const generalistPrompts: RolePrompts = {
+  systemPrompt: appendSharedInstructions(`You are an expert **software systems generalist**, experienced in integrating architectural, performance, security, and testing perspectives into cohesive system designs.
+
+Your focus areas:
+- Holistic systems reasoning and trade-off analysis
+- Balancing functionality, scalability, and maintainability
+- Evaluating design coherence and integration of specialist concerns
+- Identifying conflicts between architectural priorities
+- Synthesizing complex inputs into consistent and feasible designs
+
+When proposing solutions:
+- Integrate ideas across multiple domains (architecture, performance, security, testability)
+- Explain how components, flows, and responsibilities align as a unified system
+- Highlight trade-offs explicitly and justify them
+
+When critiquing:
+- Evaluate overall design coherence and consistency between subsystems
+- Identify missing integration points or contradictions between specialist recommendations
+- Provide balanced, reasoned guidance that reconciles differing perspectives`, INSTRUCTION_TYPES.SYSTEM),
+
+  proposePrompt: (problem: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => {
+    const basePrompt = `Problem to solve:
+${problem}
+
+As a generalist, propose a cohesive solution that balances architecture, performance, security, and testability concerns.
+
+Use this structure:
+## Overall Approach
+Summarize the high-level concept and rationale.
+
+## Key Components & Interactions
+Outline main system components and their relationships.
+
+## Cross-Domain Integration
+Explain how architectural, performance, security, and testability requirements are balanced.
+
+## Trade-offs & Conflicts
+Discuss trade-offs made between conflicting design goals.
+
+## Risks & Mitigation
+Identify key risks (technical, organizational, operational) and how they are mitigated.
+
+## Expected Benefits
+Summarize expected advantages and outcomes of the proposed design.
+
+`;
+    const promptWithContext = prependContext(basePrompt, context, agentId, includeFullHistory);
+    return appendSharedInstructions(promptWithContext, INSTRUCTION_TYPES.PROPOSAL);
+  },
+
+  critiquePrompt: (proposalContent: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => {
+    const basePrompt = `Review this proposal from a systems generalist perspective.
+
+Proposal:
+${proposalContent}
+
+Structure your response as follows:
+## Strengths
+Identify coherence, balanced trade-offs, and effective integration across domains.
+
+## Weaknesses
+Highlight inconsistencies, missing dependencies, or unresolved trade-offs.
+
+## Suggested Improvements
+Propose ways to better align performance, security, scalability, and maintainability goals.
+
+## Integration Risks
+List potential conflicts or risks arising from domain misalignment (e.g., security vs. usability, performance vs. maintainability).
+`;
+    const promptWithContext = prependContext(basePrompt, context, agentId, includeFullHistory);
+    return appendSharedInstructions(promptWithContext, INSTRUCTION_TYPES.CRITIQUE);
+  },
+
+  refinePrompt: (originalContent: string, critiquesText: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => {
+    const basePrompt = `Original proposal:
+${originalContent}
+
+Critiques:
+${critiquesText}
+
+Refine your proposal to achieve better cross-domain coherence and balance.
+
+Use this structure:
+## Revised Integrated Design
+Summarize how the updated solution improves system-wide balance and alignment.
+
+## Changes Made
+List modifications and the rationale behind them.
+
+## Improved Trade-offs
+Explain how the design better balances competing goals (e.g., security vs. performance).
+
+## Remaining Conflicts
+Note any unresolved tensions or design questions that still need consideration.
+
+`;
+    const promptWithContext = prependContext(basePrompt, context, agentId, includeFullHistory);
+    return appendSharedInstructions(promptWithContext, INSTRUCTION_TYPES.REFINEMENT);
+  },
+
+  summarizePrompt: (content: string, maxLength: number) => {
+    const basePrompt = `You are summarizing the debate history from a generalist systems perspective.
+
+Debate history to summarize:
+${content}
+
+Summarize the discussion focusing on cross-domain integration, design coherence, and trade-offs.
+
+Format:
+## System Overview
+Summarize the overall design direction and intent.
+
+## Key Agreements
+List areas of consensus across domain specialists.
+
+## Trade-offs & Balances
+Describe how major conflicts were resolved or balanced.
+
+## Open Issues
+Identify unresolved design tensions or open questions for future consideration.
+
+Limit the summary to a maximum of ${maxLength} characters.`;
+    return appendSharedInstructions(basePrompt, INSTRUCTION_TYPES.SUMMARIZATION);
+  },
+
+  clarifyPrompt: (problem: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => {
+    const basePrompt = `You are preparing clarifying questions from a systems generalist perspective.
+
+Problem to clarify:
+${problem}
+
+Ask zero or more concise, high-value questions that help integrate or clarify cross-domain concerns.
+
+Focus on:
+- High-level functional goals and scope
+- Interactions between architectural, performance, and security aspects
+- Ambiguous responsibilities or unclear data ownership
+- Expected evolution and maintainability
+- System boundaries and dependencies
+
+`;
+    const promptWithContext = prependContext(basePrompt, context, agentId, includeFullHistory);
+    return appendSharedInstructions(promptWithContext, INSTRUCTION_TYPES.CLARIFICATION);
+  },
+};
+

package/src/agents/prompts/index.ts

@@ -0,0 +1,41 @@
+import { architectPrompts } from './architect-prompts';
+import { performancePrompts } from './performance-prompts';
+import { securityPrompts } from './security-prompts';
+import { testingPrompts } from './testing-prompts';
+import { generalistPrompts } from './generalist-prompts';
+import { kissPrompts } from './kiss-prompts';
+import { RolePrompts } from './prompt-types';
+import { AGENT_ROLES, AgentRole } from '../../types/agent.types';
+
+/**
+ * Internal registry mapping agent roles to their corresponding prompt configurations.
+ * 
+ * This centralized registry allows for easy lookup of role-specific prompts
+ * without needing separate agent classes for each role.
+ * 
+ */
+const ROLE_PROMPTS_REGISTRY: Partial<Record<AgentRole, RolePrompts>> = {
+  [AGENT_ROLES.ARCHITECT]: architectPrompts,
+  [AGENT_ROLES.PERFORMANCE]: performancePrompts,
+  [AGENT_ROLES.SECURITY]: securityPrompts,
+  [AGENT_ROLES.TESTING]: testingPrompts,
+  [AGENT_ROLES.GENERALIST]: generalistPrompts,
+  [AGENT_ROLES.KISS]: kissPrompts,
+};
+
+/**
+ * Retrieves the prompt configuration for a given agent role.
+ * 
+ * If the role is not found in the registry, defaults to architect prompts
+ * to maintain backward compatibility and ensure system stability.
+ * 
+ * @param role - The agent role to get prompts for.
+ * @returns The RolePrompts configuration for the specified role.
+ */
+export function getPromptsForRole(role: AgentRole): RolePrompts {
+  return ROLE_PROMPTS_REGISTRY[role] ?? architectPrompts;
+}
+
+// Re-export types for convenience
+export type { RolePrompts } from './prompt-types';
+

package/src/agents/prompts/judge-prompts.ts

@@ -0,0 +1,19 @@
+/**
+ * Default summary prompt for the judge when summarizing debate history for synthesis.
+ * 
+ * The judge's perspective is different from agents - it focuses on extracting key decisions,
+ * trade-offs, and recommendations from the debate to inform the final synthesis.
+ */
+export const DEFAULT_JUDGE_SUMMARY_PROMPT = (content: string, maxLength: number): string => 
+  `You are a technical judge preparing to synthesize a final solution from a debate. Summarize the following debate history, focusing on the most important decisions, trade-offs, and recommendations that will inform the final synthesis.
+
+Debate history to summarize:
+${content}
+
+Create a concise summary (maximum ${maxLength} characters) that captures:
+- Key architectural decisions and their rationale
+- Important trade-offs identified across different perspectives
+- Critical recommendations and concerns raised
+- Evolution of the solution through the debate rounds
+
+Focus on information that will be essential for creating a well-informed final synthesis.`;