telos-framework 0.1.0

package/lib/generators/agents-md-generator.js

@@ -0,0 +1,73 @@
+const fs = require('fs').promises;
+const path = require('path');
+
+async function consolidateAgents(agentsDir, outputPath) {
+  let content = `# Telos Multi-Agent Collective
+
+**Generated**: ${new Date().toISOString()}
+
+This document consolidates all 9 agent definitions for the Telos framework. Each agent operates at a specific ontological level in Boulding's hierarchy.
+
+---
+
+`;
+
+  const agentFiles = [
+    'l9-telos-guardian.md',
+    'l8-market-analyst.md',
+    'l7-insight-synthesizer.md',
+    'l6-ux-simulator.md',
+    'l5-journey-validator.md',
+    'l4-integration-contractor.md',
+    'l3-component-architect.md',
+    'l2-function-author.md',
+    'l1-syntax-linter.md'
+  ];
+
+  for (const filename of agentFiles) {
+    const filePath = path.join(agentsDir, filename);
+    
+    try {
+      const agentContent = await fs.readFile(filePath, 'utf8');
+      content += agentContent + '\n\n---\n\n';
+    } catch (error) {
+      content += `# ${filename}\n\n*Agent definition not yet generated*\n\n---\n\n`;
+    }
+  }
+
+  content += `## Using the Agents
+
+These agents work together as an orchestrated collective managed by Logos. You typically won't invoke individual agents directly—instead, Logos routes work to the appropriate level based on the task.
+
+### Agent Hierarchy
+
+\`\`\`
+L9 (Strategic) ← Telos-Guardian
+L8 (Business)  ← Market-Analyst
+L7 (Insight)   ← Insight-Synthesizer
+L6 (UX)        ← UX-Simulator
+L5 (Journey)   ← Journey-Validator
+L4 (API)       ← Integration-Contractor
+L3 (Component) ← Component-Architect
+L2 (Function)  ← Function-Author
+L1 (Syntax)    ← Syntax-Linter
+\`\`\`
+
+### Workflow
+
+1. **Request** enters at L9 (Telos validation)
+2. **Decomposition** cascades L9→L1
+3. **Implementation** occurs at appropriate levels
+4. **Validation** cascades L1→L9
+5. **Approval** from L9 Telos-Guardian
+
+See LOGOS.md for orchestration details.
+`;
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.writeFile(outputPath, content, 'utf8');
+  
+  return outputPath;
+}
+
+module.exports = { consolidateAgents };

package/lib/generators/all-agents-generator.js

@@ -0,0 +1,196 @@
+const fs = require('fs').promises;
+const path = require('path');
+
+async function generateAllAgents(hierarchy, levelTools, outputDir) {
+  const agents = [];
+
+  agents.push(await generateAgent('L3', hierarchy.L3, levelTools.L3.tools, outputDir, {
+    role: 'Component Architect',
+    focus: 'Component design and composition'
+  }));
+
+  agents.push(await generateAgent('L4', hierarchy.L4, levelTools.L4.tools, outputDir, {
+    role: 'Integration Contractor',
+    focus: 'API contracts and service boundaries'
+  }));
+
+  agents.push(await generateAgent('L5', hierarchy.L5, levelTools.L5.tools, outputDir, {
+    role: 'Journey Validator',
+    focus: 'End-to-end workflows and integration testing'
+  }));
+
+  agents.push(await generateAgent('L6', hierarchy.L6, levelTools.L6.tools, outputDir, {
+    role: 'UX Simulator',
+    focus: 'User experience and accessibility'
+  }));
+
+  agents.push(await generateAgent('L7', hierarchy.L7, levelTools.L7.tools, outputDir, {
+    role: 'Insight Synthesizer',
+    focus: 'User behavior and feedback analysis'
+  }));
+
+  agents.push(await generateAgent('L8', hierarchy.L8, levelTools.L8.tools, outputDir, {
+    role: 'Market Analyst',
+    focus: 'Business metrics and KPIs'
+  }));
+
+  return agents;
+}
+
+async function generateAgent(level, hierarchyData, tools, outputDir, meta) {
+  const toolsList = tools.length > 0
+    ? tools.map(t => `- **${t.name}** (${t.category}): ${t.capability}`).join('\n')
+    : `- *No specific tools detected for ${level}*`;
+
+  const content = `# ${level}: ${hierarchyData.name}
+
+**Role**: ${meta.role}
+
+## Your Mandate
+
+You are the ${hierarchyData.name}, responsible for ${meta.focus}. Your purpose:
+
+> **${hierarchyData.purpose}**
+
+This serves the ultimate Telos through its contribution to the overall system hierarchy.
+
+## Your Responsibilities
+
+${getResponsibilities(level)}
+
+## Available Tools
+
+${toolsList}
+
+## When You Are Invoked
+
+${getInvocationTriggers(level)}
+
+## Communication Protocol
+
+### Input Format
+\`\`\`
+${level.toUpperCase()} REQUEST
+Context: [what needs to be done]
+Serves: [higher-level purpose]
+REQUEST: [specific action]
+\`\`\`
+
+### Output Format
+\`\`\`
+${level.toUpperCase()} RESPONSE
+Result: [what was accomplished]
+Validation: [how it was verified]
+Status: [PASS | FAIL]
+Serves: [confirms higher-level contribution]
+\`\`\`
+
+## Integration with Other Levels
+
+${getIntegration(level)}
+
+## Remember
+
+Your work at ${level} is essential to the hierarchy. Maintain quality and alignment with the purpose: "${hierarchyData.purpose}"
+`;
+
+  const filename = `${level.toLowerCase()}-${hierarchyData.name.toLowerCase().replace(/\s+/g, '-')}.md`;
+  const outputPath = path.join(outputDir, filename);
+  
+  await fs.mkdir(outputDir, { recursive: true });
+  await fs.writeFile(outputPath, content, 'utf8');
+  
+  return outputPath;
+}
+
+function getResponsibilities(level) {
+  const responsibilities = {
+    L3: `1. **Component Design**: Create modular, reusable components
+2. **Composition Patterns**: Establish how components interact
+3. **State Management**: Define component-level state
+4. **Component Testing**: Test components in isolation`,
+    L4: `1. **API Contract Definition**: Specify service interfaces
+2. **Integration Points**: Define system boundaries
+3. **Contract Testing**: Validate API contracts
+4. **Dependency Management**: Manage service dependencies`,
+    L5: `1. **End-to-End Testing**: Validate complete user journeys
+2. **Integration Validation**: Ensure services work together
+3. **Workflow Testing**: Test multi-step processes
+4. **Performance Testing**: Validate system-wide performance`,
+    L6: `1. **UX Design Validation**: Ensure usability standards
+2. **Accessibility**: WCAG compliance and keyboard navigation
+3. **User Journey Mapping**: Optimize user flows
+4. **Visual Consistency**: Maintain design system coherence`,
+    L7: `1. **Behavior Analysis**: Understand user patterns
+2. **Feedback Synthesis**: Process user feedback
+3. **A/B Testing**: Experiment with variations
+4. **Insight Reporting**: Communicate findings to L8`,
+    L8: `1. **Metrics Definition**: Establish KPIs and success criteria
+2. **Business Analysis**: Evaluate business impact
+3. **ROI Tracking**: Monitor return on investment
+4. **Strategic Reporting**: Communicate to L9 Telos-Guardian`
+  };
+  return responsibilities[level] || '';
+}
+
+function getInvocationTriggers(level) {
+  const triggers = {
+    L3: `- Implementing new UI/business components
+- Refactoring component architecture
+- Component integration issues
+- State management decisions`,
+    L4: `- Defining new service contracts
+- API versioning decisions
+- Service integration points
+- Contract breaking changes`,
+    L5: `- New feature complete flows
+- Integration testing needs
+- Performance validation
+- Release readiness checks`,
+    L6: `- New user interfaces
+- Accessibility audits
+- User journey optimization
+- Design system updates`,
+    L7: `- Analyzing user behavior data
+- Processing user feedback
+- A/B test evaluation
+- Feature usage analysis`,
+    L8: `- Quarterly business reviews
+- Feature prioritization
+- ROI analysis
+- Strategic planning sessions`
+  };
+  return triggers[level] || '';
+}
+
+function getIntegration(level) {
+  const integration = {
+    L3: `- Receives specs from **L4 Integration-Contractor**
+- Uses functions from **L2 Function-Author**
+- Validated by **L1 Syntax-Linter**
+- Feeds into **L4** contracts`,
+    L4: `- Receives requirements from **L5 Journey-Validator**
+- Composed of **L3** components
+- Defines contracts for **L3**
+- Reports to **L5** on integration status`,
+    L5: `- Receives journeys from **L6 UX-Simulator**
+- Validates **L4** integrations
+- Tests **L3** component interactions
+- Reports to **L6** on workflow quality`,
+    L6: `- Receives insights from **L7 Insight-Synthesizer**
+- Defines journeys for **L5**
+- Guides **L3** component design
+- Reports to **L7** on UX metrics`,
+    L7: `- Receives goals from **L8 Market-Analyst**
+- Analyzes **L6** user interactions
+- Informs **L6** design decisions
+- Reports to **L8** on user insights`,
+    L8: `- Receives strategy from **L9 Telos-Guardian**
+- Defines success metrics for **L7**
+- Evaluates **L7** insights against business goals
+- Reports to **L9** on business alignment`
+  };
+  return integration[level] || '';
+}
+
+module.exports = { generateAllAgents };

package/lib/generators/logos-md-generator.js

@@ -0,0 +1,192 @@
+const fs = require('fs').promises;
+const path = require('path');
+
+async function generateLogosMd(outputPath) {
+  const content = `# Logos: Rational Orchestrator
+
+**Role**: Central orchestration engine for the Telos multi-agent collective
+
+## What is Logos?
+
+Logos (Greek: λόγος) means "reason," "discourse," or "rational principle." In the Telos framework, Logos is the orchestrator that maintains coherence across all 9 agent levels through rational dialogue and systematic decomposition.
+
+## Core Responsibilities
+
+1. **Top-Down Decomposition**: Break strategic goals (L9) into tactical implementations (L1)
+2. **Bottom-Up Validation**: Verify implementations (L1) align with strategic purpose (L9)
+3. **Middle-Out Reconciliation**: Resolve conflicts between levels by appealing to higher purpose
+4. **State Management**: Track development state, active agents, and validation cascades
+
+## Orchestration Flows
+
+### Flow 1: Top-Down Decomposition
+
+\`\`\`
+User Request → L9 Telos-Guardian
+  ↓ (Does this serve our Telos?)
+L8 Market-Analyst (What business value?)
+  ↓
+L7 Insight-Synthesizer (What user insights needed?)
+  ↓
+L6 UX-Simulator (What UX required?)
+  ↓
+L5 Journey-Validator (What workflows?)
+  ↓
+L4 Integration-Contractor (What APIs?)
+  ↓
+L3 Component-Architect (What components?)
+  ↓
+L2 Function-Author (What functions?)
+  ↓
+L1 Syntax-Linter (Code quality check)
+  ↓
+Implementation
+\`\`\`
+
+### Flow 2: Bottom-Up Validation
+
+\`\`\`
+Implementation Complete
+  ↓
+L1 Syntax-Linter validates structure
+  ↓ (PASS → continue)
+L2 Function-Author validates logic & tests
+  ↓ (PASS → continue)
+L3 Component-Architect validates composition
+  ↓ (PASS → continue)
+L4 Integration-Contractor validates contracts
+  ↓ (PASS → continue)
+L5 Journey-Validator validates workflows
+  ↓ (PASS → continue)
+L6 UX-Simulator validates UX
+  ↓ (PASS → continue)
+L7 Insight-Synthesizer validates insights
+  ↓ (PASS → continue)
+L8 Market-Analyst validates business value
+  ↓ (PASS → continue)
+L9 Telos-Guardian validates Telos alignment
+  ↓
+APPROVED ✓
+\`\`\`
+
+### Flow 3: Middle-Out Reconciliation
+
+When conflicts arise between levels:
+
+\`\`\`
+Conflict Detected (e.g., L3 vs L5)
+  ↓
+Logos identifies higher authority (L4)
+  ↓
+L4 Integration-Contractor reconciles
+  ↓
+If unresolved, escalate to L6
+  ↓
+Continue up hierarchy until resolved
+  ↓
+Resolution cascades back down
+\`\`\`
+
+## State Management
+
+Logos maintains state in \`.telos/state.json\`:
+
+\`\`\`json
+{
+  "activeAgents": [
+    { "level": "L2", "task": "implement-auth", "status": "in-progress" }
+  ],
+  "decompositionStack": [
+    { "level": "L9", "spec": "...", "children": [...] }
+  ],
+  "validationQueue": [
+    { "level": "L1", "validation": {...}, "status": "pending" }
+  ],
+  "conflicts": [
+    { "levelA": "L3", "levelB": "L5", "resolved": false }
+  ]
+}
+\`\`\`
+
+## Agent Delegation Protocol
+
+Logos delegates to agents using structured messages:
+
+### Request Format
+\`\`\`
+AGENT REQUEST
+Level: [L1-L9]
+Type: [decompose | validate | reconcile | implement]
+Context: [relevant information]
+Parent Purpose: [higher-level goal this serves]
+REQUEST: [specific action]
+\`\`\`
+
+### Response Format
+\`\`\`
+AGENT RESPONSE
+Level: [L1-L9]
+Status: [PASS | FAIL | CONDITIONAL]
+Result: [what was accomplished]
+Validation: [how it was verified]
+Serves: [confirms contribution to higher purpose]
+Issues: [if any]
+\`\`\`
+
+## Integration with OpenSpec
+
+Logos creates and manages OpenSpec proposals for all changes:
+
+1. **Proposal Creation**: L9 validates alignment, creates OpenSpec proposal
+2. **Task Generation**: Logos decomposes into tasks (L9→L1)
+3. **Implementation**: Agents work through tasks
+4. **Validation**: Bottom-up verification
+5. **Archive**: Completed proposals archived with lineage
+
+## Session Management
+
+Each development session:
+- Gets unique session ID
+- Tracks all agent invocations
+- Maintains decomposition history
+- Preserves validation results
+- Enables resumption after interruption
+
+## Usage
+
+Logos is invoked automatically by the Telos system when:
+- User creates new feature request
+- Code changes are proposed
+- Conflicts arise between agents
+- Validation is required
+
+You typically don't invoke Logos directly—agents and the system do this for you.
+
+## Philosophy
+
+Logos embodies the principle that **rational discourse** maintains coherence in complex systems. By enforcing:
+
+- Top-down purpose alignment
+- Bottom-up integrity verification
+- Middle-out conflict resolution
+
+...Logos ensures every line of code serves the ultimate Telos while maintaining implementation quality at every level.
+
+## Remember
+
+Logos is not a command-and-control system. It's a **dialogue facilitator** that:
+- Asks the right questions at the right levels
+- Routes information to appropriate agents
+- Maintains traceability from Telos to implementation
+- Enables emergence through structured interaction
+
+Trust the process. Trust the hierarchy. Trust Logos.
+`;
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.writeFile(outputPath, content, 'utf8');
+  
+  return outputPath;
+}
+
+module.exports = { generateLogosMd };

package/lib/generators/telos-md-generator.js

@@ -0,0 +1,121 @@
+const fs = require('fs').promises;
+const path = require('path');
+
+async function generateTelosMd(hierarchy, outputPath) {
+  const content = `# Project Telos
+
+**Generated**: ${new Date().toISOString()}
+
+## Ultimate Purpose (L9)
+
+${hierarchy.L9.purpose}
+
+**Beneficiaries**: ${hierarchy.L9.beneficiaries}
+
+**Success Impact**: ${hierarchy.L9.impact}
+
+**Constraints**: ${hierarchy.L9.constraints}
+
+---
+
+## Purpose Hierarchy
+
+The 9-level decomposition from ultimate purpose to implementation:
+
+### L9: ${hierarchy.L9.name} - Transcendent Purpose
+
+**Purpose**: ${hierarchy.L9.purpose}
+
+${hierarchy.L9.description}
+
+### L8: ${hierarchy.L8.name} - Business/Social Value
+
+**Purpose**: ${hierarchy.L8.purpose}
+
+${hierarchy.L8.description}
+
+**Serves**: L9 Telos
+
+### L7: ${hierarchy.L7.name} - User Insight
+
+**Purpose**: ${hierarchy.L7.purpose}
+
+${hierarchy.L7.description}
+
+**Serves**: L8 Business Value
+
+### L6: ${hierarchy.L6.name} - User Experience
+
+**Purpose**: ${hierarchy.L6.purpose}
+
+${hierarchy.L6.description}
+
+**Serves**: L7 User Insight
+
+### L5: ${hierarchy.L5.name} - System Integration
+
+**Purpose**: ${hierarchy.L5.purpose}
+
+${hierarchy.L5.description}
+
+**Serves**: L6 User Experience
+
+### L4: ${hierarchy.L4.name} - API Contracts
+
+**Purpose**: ${hierarchy.L4.purpose}
+
+${hierarchy.L4.description}
+
+**Serves**: L5 System Integration
+
+### L3: ${hierarchy.L3.name} - Component Design
+
+**Purpose**: ${hierarchy.L3.purpose}
+
+${hierarchy.L3.description}
+
+**Serves**: L4 API Contracts
+
+### L2: ${hierarchy.L2.name} - Function Logic
+
+**Purpose**: ${hierarchy.L2.purpose}
+
+${hierarchy.L2.description}
+
+**Serves**: L3 Component Design
+
+### L1: ${hierarchy.L1.name} - Code Structure
+
+**Purpose**: ${hierarchy.L1.purpose}
+
+${hierarchy.L1.description}
+
+**Serves**: L2 Function Logic
+
+---
+
+## Validation
+
+Every change must trace upward through this hierarchy to the ultimate Telos.
+
+Ask at each level:
+- **L1**: Does this meet code quality standards?
+- **L2**: Does this function serve the component correctly?
+- **L3**: Does this component fit the architecture?
+- **L4**: Does this respect API contracts?
+- **L5**: Does this integrate into workflows properly?
+- **L6**: Does this enhance user experience?
+- **L7**: Does this respond to user insights?
+- **L8**: Does this advance business objectives?
+- **L9**: Does this serve the ultimate Telos?
+
+If the answer is "no" at any level, the change requires revision.
+`;
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.writeFile(outputPath, content, 'utf8');
+  
+  return outputPath;
+}
+
+module.exports = { generateTelosMd };