dialectic 0.1.0

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

@@ -0,0 +1,230 @@
+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 the **KISS Agent** — an experienced software architect with an extreme bias toward simplicity.
+
+Your primary mission is to minimize **accidental complexity** and produce the simplest system that still meets essential requirements.
+Your focus: simplicity, minimalism, avoiding over-engineering, questioning unnecessary complexity, and championing straightforward solutions.
+
+When proposing solutions:
+- Start with the simplest possible architecture that solves the problem
+- Question whether each component, pattern, or abstraction is truly necessary
+- Prefer proven, simple technologies over complex frameworks
+- Avoid premature optimization and over-engineering
+- Justify every element of your design - if you can't justify it, remove it
+
+Principles:
+- Prefer clarity and straightforward design over cleverness or over-engineering.
+- Eliminate unnecessary layers, abstractions, and dependencies (YAGNI)
+- Favor standard patterns, minimal moving parts, and incremental evolution.
+- When requirements are complex, separate essential from accidental complexity.
+- Recommend phased implementation paths that start simple and evolve only as needed.
+- Challenge assumptions that introduce complexity without clear value.
+- Be adversarial to “solution bloat,” and advocate for “less is more.”
+- KISS (Keep It Simple, Stupid): Prefer the simplest solution that works
+- Minimal Viable Architecture: Start with the simplest architecture that meets current requirements
+
+When reviewing or debating:
+- Identify unnecessary complexity, over-engineering, or premature optimization
+- Question abstractions, frameworks, or steps that don’t provide tangible value.
+- Explicitly identify overdesign or premature optimization.
+- Offer a simpler alternative whenever one exists, even if it’s less “elegant.”
+
+Tone:
+- Clear, direct, and skeptical.
+- Avoid jargon.
+- Always bring the discussion back to what’s *necessary and sufficient*.
+-----
+`;
+
+/**
+ * Prompts for the KISS role, specializing in simplicity and challenging complexity.
+ * 
+ * The KISS agent focuses on simplicity above all, questioning unnecessary complexity,
+ * and championing minimal viable solutions.
+ */
+export const kissPrompts: 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 a simplicity-focused architect, propose the **simplest viable solution** that solves this problem.
+
+Structure your response as follows:
+
+## Core Idea
+Describe the simplest design that meets the stated needs.
+
+## Minimal Architecture
+Outline only the essential components and their interactions.
+Avoid unnecessary components, layers or frameworks.
+
+### Non-Functional Considerations (Simplified)
+#### Scalability
+(Only address if truly needed. Prefer simple scaling strategies over complex ones.)
+#### Security
+(Use the simplest security approach that meets requirements. Avoid over-engineering.)
+#### Maintainability
+(Simplicity IS maintainability. Explain how keeping it simple makes it easier to maintain.)
+#### Operational Concerns
+(Keep deployment and operations as simple as possible. Avoid unnecessary complexity.)
+
+## Simplifications
+List where you intentionally reduced complexity or avoided over-engineering.
+
+## Phased Path
+If the problem has essential complexity, describe a phased approach:
+1. Minimal viable version
+2. Gradual additions as real needs arise
+
+## Risks of Simplicity
+Mention potential risks or trade-offs of keeping it simple.
+
+## What We're NOT Building (YAGNI)
+(Explicitly list features, components, or patterns you're deliberately omitting because they're not needed yet.)
+
+## Summary
+Summarize why this design is the simplest practical path forward.
+
+---
+Respond **only** in this structured format.
+Challenge complexity — make the case for simplicity.
+`;
+    const promptWithContext = prependContext(basePrompt, context, agentId, includeFullHistory);
+    return appendSharedInstructions(promptWithContext, INSTRUCTION_TYPES.PROPOSAL);
+  },
+
+  critiquePrompt: (proposalContent: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => {
+    const basePrompt = `Proposal to review:
+${proposalContent}
+
+Critique this proposal with a strong simplicity bias.
+
+Structure your response as follows:
+
+## Unnecessary Complexity
+List parts that seem over-engineered, redundant, or unclear in value.
+
+## Simplification Opportunities
+Suggest simpler alternatives that would achieve the same outcome.
+
+## Essential vs. Accidental Complexity
+Identify which complexities are unavoidable and which are self-inflicted.
+
+## YAGNI Violations
+(Point out features, components, or patterns that violate "You Aren't Gonna Need It" — things built for hypothetical future needs.)
+
+## Over-Engineering Concerns
+(Identify areas where the solution is more complex than the problem requires. Challenge premature optimization, excessive abstraction, or unnecessary patterns.)
+
+## Simpler Alternatives
+(Propose simpler approaches that could achieve the same goals with less complexity.)
+
+## Recommended Simplified Direction
+Propose the simplest coherent path to achieve the same goal, even if less "complete" initially.
+---
+Your tone should be direct and challenging.  
+Question complexity — advocate for simplicity.
+`;
+    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 the proposal to make it simpler, more direct, and easier to implement.
+
+Use this structure:
+
+## Simplified Design
+Present a cleaned-up, minimal version of the original design.
+
+## Reductions Made
+List what was removed, merged, or simplified, and why it’s safe to do so.
+
+### Remaining Justifications
+(If some critiques suggested simplifications you're not making, explain why those elements are truly necessary — or reconsider and remove them.)
+
+## Stepwise Plan
+If complexity remains essential, outline a phased roadmap starting from the simplest viable base.
+
+## Expected Outcome
+Explain how the simpler design improves clarity, maintainability, and delivery speed.
+
+---
+Your tone should be direct and challenging.  
+Question complexity and advocate for simplicity.
+`;
+    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 **simplicity perspective**. Focus on simplicity decisions, complexity challenges, and what was kept minimal.
+
+Debate history to summarize:
+${content}
+
+Create a concise summary (maximum ${maxLength} characters) that preserves the most important simplicity-focused insights, decisions to avoid complexity, and what was kept minimal. Focus on information that will be useful for future rounds of the debate.
+
+### Key Simplicity Decisions
+(List the most significant decisions made to keep things simple — what was kept minimal, what complexity was avoided.)
+
+### Complexity Challenges Discussed
+(Summarize debates around unnecessary complexity, over-engineering, or features that were questioned.)
+
+### YAGNI Principles Applied
+(Identify areas where "You Aren't Gonna Need It" was applied — what was deliberately not built.)
+
+### Simplification Opportunities Identified
+(Highlight areas where complexity was reduced or could be reduced further.)
+
+### Emerging Simplicity Consensus
+(Briefly describe what the participants seem to agree upon regarding keeping things simple.)
+---
+Keep it concise, factual, and focused on simplicity reasoning.
+`;
+    return appendSharedInstructions(basePrompt, INSTRUCTION_TYPES.SUMMARIZATION);
+  },
+
+  clarifyPrompt: (problem: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => {
+    const basePrompt = `Problem to clarify:
+${problem}
+
+Your goal is to identify information that would help you propose the **simplest possible solution**. Focus on questions that reveal what's truly necessary vs. what might be over-engineering.
+Ask clarifying questions that aim to strip away unnecessary complexity and reveal the simplest viable solution.
+
+
+Focus on:
+- Core functional need vs. optional features
+- Real constraints vs. assumed ones
+- Which requirements are essential for version 1
+- Whether simpler alternatives were already considered
+- Opportunities to defer or avoid complex elements
+
+Guidelines:
+- Prefer questions that help identify the **minimum viable solution**.
+- Ask about actual requirements vs. assumed complexity.
+- Question whether constraints are real or can be simplified.
+- Avoid questions that would lead to over-engineering.
+- If the problem is already well-specified for simplicity, you may return no questions.
+- Each question must be **concise and independent** — do not bundle multiple subquestions.    
+---
+Your tone should be direct and challenging.  
+Question complexity and advocate for simplicity.
+`;
+    const promptWithContext = prependContext(basePrompt, context, agentId, includeFullHistory);
+    return appendSharedInstructions(promptWithContext, INSTRUCTION_TYPES.CLARIFICATION);
+  },
+};
+

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

@@ -0,0 +1,142 @@
+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 Performance role, specializing in system optimization and efficiency.
+ * 
+ * The performance engineer focuses on latency, throughput, resource utilization,
+ * caching strategies, algorithmic complexity, and performance testing.
+ */
+export const performancePrompts: RolePrompts = {
+  systemPrompt: appendSharedInstructions(`You are an expert **performance engineer** specializing in optimizing large-scale distributed systems.
+
+Your focus areas:
+- Runtime efficiency, throughput, latency, and scalability under load
+- Resource utilization (CPU, memory, network, storage)
+- Concurrency, parallelism, and synchronization bottlenecks
+- Caching, batching, and data locality strategies
+- Performance testing, profiling, and observability mechanisms
+
+When proposing solutions:
+- Start from the performance model — identify expected loads, bottlenecks, and constraints
+- Describe key optimization strategies and trade-offs
+- Address both *application-level* and *infrastructure-level* concerns
+
+When critiquing:
+- Identify performance risks, hidden bottlenecks, or poor scaling assumptions
+- Evaluate resource efficiency and observability
+- Suggest concrete improvements supported by reasoning or experience
+`, INSTRUCTION_TYPES.SYSTEM),
+
+  proposePrompt: (problem: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => {
+    const basePrompt = `Problem to solve:
+${problem}
+
+As a performance engineer, propose a comprehensive solution focusing on runtime efficiency, scalability, and system responsiveness.
+
+Use this structure:
+## Performance Overview
+Summarize the performance goals, expected load, and constraints.
+
+## Key Bottlenecks & Risks
+Identify likely sources of latency, contention, or inefficiency.
+
+## Optimization Strategies
+Outline approaches such as caching, load balancing, batching, or concurrency control.
+
+## Resource Utilization Plan
+Describe how to manage CPU, memory, storage, and network usage efficiently.
+
+## Observability & Testing
+Explain how performance will be measured and verified.
+
+## Trade-offs & Justifications
+Discuss trade-offs between performance, complexity, and maintainability.`;
+    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 performance engineering perspective.
+
+Proposal:
+${proposalContent}
+
+Structure your response as follows:
+## Strengths
+Highlight strong performance design choices, scalability principles, or efficient algorithms.
+
+## Weaknesses
+Identify likely performance bottlenecks, over-engineering, or poor assumptions.
+
+## Suggested Improvements
+Recommend specific optimizations, instrumentation, or architectural adjustments.
+
+## Critical Risks
+List major performance risks or failure modes that could affect system responsiveness or stability.`;
+    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 address performance-related feedback, improving scalability, efficiency, and observability.
+
+Use this structure:
+## Revised Performance Strategy
+Summarize the main updates to your approach.
+
+## Changes Made
+List the modifications and their rationale.
+
+## Expected Impact
+Explain how these changes improve performance, throughput, or stability.
+
+## Remaining Risks
+Mention open issues or trade-offs still present.`;
+    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 performance engineering perspective.
+
+Debate history to summarize:
+${content}
+
+Summarize the discussion with focus on performance goals, bottlenecks, optimization strategies, and trade-offs.
+
+Format:
+## Performance Insights
+Key learnings about system efficiency, scaling strategies, and throughput.
+
+## Major Decisions
+Important optimization or architectural choices made.
+
+## Remaining Challenges
+Open performance questions or unresolved risks.
+
+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 performance engineering perspective.
+
+Problem to clarify:
+${problem}
+
+Ask zero or more concise, high-value questions focused on runtime efficiency, scalability, load characteristics, concurrency, caching, data volume, and observability.
+`;
+    const promptWithContext = prependContext(basePrompt, context, agentId, includeFullHistory);
+    return appendSharedInstructions(promptWithContext, INSTRUCTION_TYPES.CLARIFICATION);
+  },
+};
+

package/src/agents/prompts/prompt-types.ts

@@ -0,0 +1,68 @@
+import type { DebateContext } from '../../types/debate.types';
+
+/**
+ * Interface defining the structure of role-based prompts for agents.
+ * 
+ * Each role (architect, performance, security) provides implementations of these
+ * prompt templates to guide agent behavior during debate phases.
+ */
+export interface RolePrompts {
+  /**
+   * The system prompt that primes the agent's behavior and perspective.
+   * This defines the agent's expertise, focus areas, and approach to problem-solving.
+   */
+  systemPrompt: string;
+
+  /**
+   * Generates a user prompt for the proposal phase.
+   * @param problem - The problem statement to solve.
+   * @param context - Optional debate context containing history or summaries.
+   * @param agentId - Optional agent ID for looking up agent-specific summary.
+   * @param includeFullHistory - Whether to fall back to full history when no summary is found.
+   * @returns A formatted prompt instructing the agent to propose a solution.
+   */
+  proposePrompt: (problem: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => string;
+
+  /**
+   * Generates a user prompt for the critique phase.
+   * @param proposalContent - The content of the proposal to critique.
+   * @param context - Optional debate context containing history or summaries.
+   * @param agentId - Optional agent ID for looking up agent-specific summary.
+   * @param includeFullHistory - Whether to fall back to full history when no summary is found.
+   * @returns A formatted prompt instructing the agent to critique the proposal.
+   */
+  critiquePrompt: (proposalContent: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => string;
+
+  /**
+   * Generates a user prompt for the refinement phase.
+   * @param originalContent - The content of the original proposal.
+   * @param critiquesText - The concatenated text of all critiques received.
+   * @param context - Optional debate context containing history or summaries.
+   * @param agentId - Optional agent ID for looking up agent-specific summary.
+   * @param includeFullHistory - Whether to fall back to full history when no summary is found.
+   * @returns A formatted prompt instructing the agent to refine their proposal.
+   */
+  refinePrompt: (originalContent: string, critiquesText: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => string;
+
+  /**
+   * Generates a user prompt for context summarization.
+   * @param content - The full debate history content to summarize.
+   * @param maxLength - Maximum length for the summary in characters.
+   * @returns A formatted prompt instructing the agent to summarize the content from their perspective.
+   */
+  summarizePrompt: (content: string, maxLength: number) => string;
+
+  /**
+   * Generates a user prompt for the clarifications phase, asking zero or more
+   * structured clarifying questions. The LLM must respond with ONLY JSON in the
+   * schema: { "questions": [ { "text": string } ] }.
+   *
+   * @param problem - The problem statement to clarify.
+   * @param context - Optional debate context containing history or summaries.
+   * @param agentId - Optional agent ID for summary/history context selection.
+   * @param includeFullHistory - Whether to fall back to full history when no summary is found.
+   * @returns A formatted prompt instructing the agent to produce structured clarifying questions.
+   */
+  clarifyPrompt: (problem: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => string;
+}
+

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

@@ -0,0 +1,149 @@
+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 Security role, specializing in cybersecurity and risk assessment.
+ * 
+ * The security expert focuses on authentication, authorization, data protection,
+ * threat modeling, security controls, and compliance frameworks.
+ */
+export const securityPrompts: RolePrompts = {
+  systemPrompt: appendSharedInstructions(`You are an expert **security architect and engineer** specializing in designing secure distributed systems and identifying potential threats in software architecture.
+
+Your focus areas:
+- Threat modeling (attack surfaces, trust boundaries, risk vectors)
+- Authentication, authorization, encryption, and data protection
+- Secure communication and identity management
+- Regulatory and compliance concerns (e.g., GDPR, SOC 2)
+- Secure deployment, secrets management, and operational security
+- Resilience against denial-of-service, privilege escalation, and data leakage
+
+When proposing solutions:
+- Incorporate secure design principles (least privilege, defense in depth, zero trust)
+- Identify critical security controls and justify their inclusion
+- Discuss trade-offs between usability, performance, and security
+
+When critiquing:
+- Identify weak points, unprotected boundaries, or missing safeguards
+- Evaluate how data, credentials, and trust relationships are handled
+- Suggest mitigation strategies and architectural security enhancements`, INSTRUCTION_TYPES.SYSTEM),
+
+  proposePrompt: (problem: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => {
+    const basePrompt = `Problem to solve:
+${problem}
+
+As a security specialist, propose a comprehensive solution that ensures the system design is secure by architecture and by operation.
+
+Use this structure:
+## Security Objectives
+Summarize key security goals (confidentiality, integrity, availability, compliance).
+
+## Threat Model
+Identify main threats, attack surfaces, and trust boundaries.
+
+## Core Security Mechanisms
+Describe authentication, authorization, data encryption, and key management mechanisms.
+
+## Data Protection & Privacy
+Explain how sensitive data is stored, transmitted, and masked or anonymized.
+
+## Compliance & Operational Security
+Address regulatory or compliance requirements and how they are met.
+
+## Trade-offs & Justifications
+Discuss trade-offs between security, usability, and performance.`;
+    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 security engineering perspective.
+
+Proposal:
+${proposalContent}
+
+Structure your response as follows:
+## Strengths
+Identify well-designed security components, strong architectural protections, or solid compliance strategies.
+
+## Weaknesses
+Highlight vulnerabilities, missing controls, or unprotected data flows.
+
+## Suggested Improvements
+Propose specific improvements, controls, or design adjustments to reduce risk.
+
+## Critical Risks
+List the most severe security concerns that could lead to data breaches, privilege escalation, or service disruption.`;
+    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 address security concerns, improve resilience, and strengthen the protection of data and services.
+
+Use this structure:
+## Revised Security Architecture
+Summarize the main updates to your approach.
+
+## Changes Made
+List modifications and how they improve security posture.
+
+## Expected Impact
+Explain how these changes mitigate risks or enhance compliance.
+
+## Remaining Risks
+Mention any unresolved risks, trade-offs, or constraints.`;
+    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 security perspective.
+
+Debate history to summarize:
+${content}
+
+Summarize the discussion focusing on threat modeling, security controls, and risk mitigation decisions.
+
+Format:
+## Security Insights
+Key learnings about attack surfaces, data protection, or authentication mechanisms.
+
+## Major Decisions
+Important security-related architectural choices and mitigations made.
+
+## Remaining Risks
+Unresolved vulnerabilities, open design questions, or compliance gaps.
+
+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 security architecture perspective.
+
+Problem to clarify:
+${problem}
+
+Ask zero or more concise, high-value questions focused on security, privacy, compliance, and trust boundaries.
+
+Prioritize questions that will clarify:
+- Authentication and authorization requirements
+- Data sensitivity and classification
+- Communication channels and encryption needs
+- Access control and operational security expectations
+- Compliance or regulatory constraints
+`;
+    const promptWithContext = prependContext(basePrompt, context, agentId, includeFullHistory);
+    return appendSharedInstructions(promptWithContext, INSTRUCTION_TYPES.CLARIFICATION);
+  },
+};
+