telos-framework 0.1.0

package/lib/discovery/mcp-discovery.js

@@ -0,0 +1,90 @@
+const fs = require('fs').promises;
+const path = require('path');
+const os = require('os');
+
+async function discoverMcpServers() {
+  const servers = [];
+  
+  const configPaths = [
+    path.join(os.homedir(), '.config', 'claude', 'claude_desktop_config.json'),
+    path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
+    path.join(os.homedir(), 'AppData', 'Roaming', 'Claude', 'config.json')
+  ];
+
+  for (const configPath of configPaths) {
+    try {
+      const content = await fs.readFile(configPath, 'utf8');
+      const config = JSON.parse(content);
+      
+      if (config.mcpServers) {
+        for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
+          servers.push({
+            name,
+            command: serverConfig.command,
+            args: serverConfig.args || [],
+            env: serverConfig.env || {}
+          });
+        }
+        break;
+      }
+    } catch (error) {
+    }
+  }
+
+  return servers;
+}
+
+function mapMcpToCapabilities(servers) {
+  const capabilities = {
+    L1: [],
+    L2: [],
+    L3: [],
+    L4: [],
+    L5: [],
+    L6: [],
+    L7: [],
+    L8: [],
+    L9: []
+  };
+
+  for (const server of servers) {
+    const name = server.name.toLowerCase();
+    
+    if (name.includes('filesystem') || name.includes('file')) {
+      capabilities.L1.push({ server: server.name, capability: 'file-operations' });
+      capabilities.L2.push({ server: server.name, capability: 'file-read-write' });
+    }
+    
+    if (name.includes('github') || name.includes('git')) {
+      capabilities.L3.push({ server: server.name, capability: 'version-control' });
+      capabilities.L4.push({ server: server.name, capability: 'ci-cd-integration' });
+    }
+    
+    if (name.includes('brave') || name.includes('browser') || name.includes('chrome')) {
+      capabilities.L5.push({ server: server.name, capability: 'browser-automation' });
+      capabilities.L6.push({ server: server.name, capability: 'ux-testing' });
+    }
+    
+    if (name.includes('postgres') || name.includes('database') || name.includes('mysql')) {
+      capabilities.L4.push({ server: server.name, capability: 'database-access' });
+    }
+    
+    if (name.includes('fetch') || name.includes('web') || name.includes('http')) {
+      capabilities.L4.push({ server: server.name, capability: 'api-testing' });
+      capabilities.L7.push({ server: server.name, capability: 'web-research' });
+    }
+    
+    if (name.includes('slack') || name.includes('email')) {
+      capabilities.L7.push({ server: server.name, capability: 'user-feedback' });
+    }
+    
+    if (name.includes('analytics') || name.includes('metrics')) {
+      capabilities.L7.push({ server: server.name, capability: 'analytics' });
+      capabilities.L8.push({ server: server.name, capability: 'business-metrics' });
+    }
+  }
+
+  return capabilities;
+}
+
+module.exports = { discoverMcpServers, mapMcpToCapabilities };

package/lib/discovery/telos-discovery.js

@@ -0,0 +1,69 @@
+const inquirer = require('inquirer');
+const chalk = require('chalk');
+
+async function discoverTelos(options = {}) {
+  console.log(chalk.cyan('\n=== Telos Discovery ===\n'));
+  console.log('Let\'s discover the ultimate purpose of your software.\n');
+
+  const answers = {};
+
+  answers.purpose = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'value',
+      message: 'What is the ultimate purpose of your software?\n  (Why does this project exist?)',
+      validate: (input) => input.trim().length > 0 || 'Purpose cannot be empty'
+    }
+  ]).then(a => a.value);
+
+  answers.beneficiaries = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'value',
+      message: 'Who ultimately benefits from achieving this purpose?',
+      validate: (input) => input.trim().length > 0 || 'Beneficiaries cannot be empty'
+    }
+  ]).then(a => a.value);
+
+  answers.impact = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'value',
+      message: 'What measurable impact defines success?',
+      validate: (input) => input.trim().length > 0 || 'Impact cannot be empty'
+    }
+  ]).then(a => a.value);
+
+  answers.constraints = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'value',
+      message: 'What ethical or practical constraints guide this purpose?',
+      default: 'None specified'
+    }
+  ]).then(a => a.value);
+
+  const { confirm } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'confirm',
+      message: `\nYour Telos:\n  ${chalk.bold(answers.purpose)}\n\nIs this correct?`,
+      default: true
+    }
+  ]);
+
+  if (!confirm) {
+    console.log(chalk.yellow('Let\'s try again...\n'));
+    return discoverTelos(options);
+  }
+
+  return {
+    telos: answers.purpose,
+    beneficiaries: answers.beneficiaries,
+    impact: answers.impact,
+    constraints: answers.constraints,
+    timestamp: new Date().toISOString()
+  };
+}
+
+module.exports = { discoverTelos };

package/lib/discovery/tool-mapper.js

@@ -0,0 +1,151 @@
+function mapToolsToLevels(projectScan, mcpCapabilities) {
+  const levelTools = {
+    L1: {
+      level: 'L1',
+      name: 'Syntax-Linter',
+      tools: []
+    },
+    L2: {
+      level: 'L2',
+      name: 'Function-Author',
+      tools: []
+    },
+    L3: {
+      level: 'L3',
+      name: 'Component-Architect',
+      tools: []
+    },
+    L4: {
+      level: 'L4',
+      name: 'Integration-Contractor',
+      tools: []
+    },
+    L5: {
+      level: 'L5',
+      name: 'Journey-Validator',
+      tools: []
+    },
+    L6: {
+      level: 'L6',
+      name: 'UX-Simulator',
+      tools: []
+    },
+    L7: {
+      level: 'L7',
+      name: 'Insight-Synthesizer',
+      tools: []
+    },
+    L8: {
+      level: 'L8',
+      name: 'Market-Analyst',
+      tools: []
+    },
+    L9: {
+      level: 'L9',
+      name: 'Telos-Guardian',
+      tools: []
+    }
+  };
+
+  for (const linter of projectScan.linters || []) {
+    levelTools.L1.tools.push({
+      name: linter,
+      category: 'linter',
+      capability: 'static-analysis'
+    });
+  }
+
+  for (const testFw of projectScan.testFrameworks || []) {
+    if (testFw === 'Playwright' || testFw === 'Cypress') {
+      levelTools.L5.tools.push({
+        name: testFw,
+        category: 'e2e-testing',
+        capability: 'journey-validation'
+      });
+    } else {
+      levelTools.L2.tools.push({
+        name: testFw,
+        category: 'unit-testing',
+        capability: 'function-testing'
+      });
+      levelTools.L3.tools.push({
+        name: testFw,
+        category: 'component-testing',
+        capability: 'component-validation'
+      });
+    }
+  }
+
+  for (const framework of projectScan.frameworks || []) {
+    if (framework.includes('React') || framework.includes('Vue') || framework.includes('Svelte') || framework.includes('Angular')) {
+      levelTools.L3.tools.push({
+        name: framework,
+        category: 'ui-framework',
+        capability: 'component-building'
+      });
+      levelTools.L6.tools.push({
+        name: framework,
+        category: 'ux-framework',
+        capability: 'user-interface'
+      });
+    } else {
+      levelTools.L4.tools.push({
+        name: framework,
+        category: 'backend-framework',
+        capability: 'api-implementation'
+      });
+    }
+  }
+
+  for (const [level, caps] of Object.entries(mcpCapabilities)) {
+    for (const cap of caps) {
+      levelTools[level].tools.push({
+        name: cap.server,
+        category: 'mcp-server',
+        capability: cap.capability
+      });
+    }
+  }
+
+  return levelTools;
+}
+
+function getToolRecommendations(levelTools) {
+  const recommendations = [];
+
+  if (levelTools.L1.tools.length === 0) {
+    recommendations.push({
+      level: 'L1',
+      message: 'No linters detected. Consider adding ESLint or Prettier.',
+      priority: 'medium'
+    });
+  }
+
+  if (levelTools.L2.tools.length === 0) {
+    recommendations.push({
+      level: 'L2',
+      message: 'No test framework detected. Consider adding Vitest or Jest.',
+      priority: 'high'
+    });
+  }
+
+  if (levelTools.L5.tools.length === 0) {
+    recommendations.push({
+      level: 'L5',
+      message: 'No E2E testing framework detected. Consider adding Playwright.',
+      priority: 'medium'
+    });
+  }
+
+  if (levelTools.L7.tools.length === 0) {
+    recommendations.push({
+      level: 'L7',
+      message: 'No analytics tools detected. Consider user feedback mechanisms.',
+      priority: 'low'
+    });
+  }
+
+  return recommendations;
+}
+
+module.exports = { mapToolsToLevels, getToolRecommendations };

package/lib/generators/agent-generator.js

@@ -0,0 +1,374 @@
+const fs = require('fs').promises;
+const path = require('path');
+
+async function generateL9Agent(hierarchy, outputPath) {
+  const l9 = hierarchy.L9;
+  
+  const content = `# L9: Telos-Guardian
+
+**Role**: Strategic Alignment Validator
+
+## Your Mandate
+
+You are the Telos-Guardian, the highest-level agent in this multi-agent collective. Your purpose is to ensure that all development activities serve the ultimate Telos:
+
+> **${l9.purpose}**
+
+## Ultimate Purpose Details
+
+- **Beneficiaries**: ${l9.beneficiaries}
+- **Success Impact**: ${l9.impact}
+- **Constraints**: ${l9.constraints}
+
+## Your Responsibilities
+
+1. **Strategic Validation**: Review all major changes for alignment with the Telos
+2. **Purpose Clarification**: Resolve ambiguities by referring back to ultimate purpose
+3. **Conflict Resolution**: When lower levels conflict, appeal to Telos for guidance
+4. **Vision Protection**: Prevent scope creep and mission drift
+
+## When You Are Invoked
+
+- New feature proposals (validate strategic fit)
+- Architectural decisions with long-term implications
+- Conflicts between lower-level agents
+- Product direction questions
+- Quarterly/milestone reviews
+
+## Your Tools
+
+- Strategic documents (PRD, vision docs, roadmaps)
+- Business metrics and KPIs
+- User research and market analysis
+- Historical decision logs
+
+## Communication Protocol
+
+### Input Format
+You receive structured requests from Logos orchestrator:
+
+\`\`\`
+TELOS VALIDATION REQUEST
+Change: [description]
+Proposed by: [agent level]
+Rationale: [why this serves lower-level purpose]
+REQUEST: Does this serve our ultimate Telos?
+\`\`\`
+
+### Output Format
+Respond with structured validation:
+
+\`\`\`
+TELOS VALIDATION RESPONSE
+Change: [description]
+Alignment: [ALIGNED | MISALIGNED | CONDITIONAL]
+Reasoning: [explanation tied to Telos]
+Recommendation: [APPROVE | REJECT | MODIFY]
+Modification needed: [if CONDITIONAL/MODIFY]
+\`\`\`
+
+## Validation Criteria
+
+Ask these questions:
+1. Does this advance our stated purpose: "${l9.purpose}"?
+2. Does this benefit ${l9.beneficiaries}?
+3. Does this contribute to ${l9.impact}?
+4. Does this respect ${l9.constraints}?
+5. Is there a better alternative more aligned with our Telos?
+
+If any answer is "no," investigate why and recommend alternatives.
+
+## Examples
+
+### Aligned Change
+\`\`\`
+Change: Add accessibility features to core interface
+Alignment: ALIGNED
+Reasoning: Directly serves beneficiaries (${l9.beneficiaries}) by removing barriers to access, advancing our purpose of ${l9.purpose}
+Recommendation: APPROVE
+\`\`\`
+
+### Misaligned Change
+\`\`\`
+Change: Add social media sharing to increase virality
+Alignment: MISALIGNED
+Reasoning: While potentially increasing reach, this doesn't directly serve our Telos. Our purpose is ${l9.purpose}, not viral growth. Could distract from core mission.
+Recommendation: REJECT
+Alternative: Focus on core value delivery that organically attracts users
+\`\`\`
+
+### Conditional Change
+\`\`\`
+Change: Implement premium tier pricing
+Alignment: CONDITIONAL
+Reasoning: Could serve Telos if revenue funds mission-critical features, but risks excluding beneficiaries (${l9.beneficiaries})
+Recommendation: MODIFY
+Modification needed: Ensure free tier preserves core value; premium only for advanced features
+\`\`\`
+
+## Remember
+
+You are the guardian of meaning. Every line of code should ultimately serve our Telos. When in doubt, ask: "Why are we building this software?" The answer is always:
+
+**${l9.purpose}**
+
+Hold this truth immutable.
+`;
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.writeFile(outputPath, content, 'utf8');
+  
+  return outputPath;
+}
+
+async function generateL1Agent(hierarchy, tools, outputPath) {
+  const l1 = hierarchy.L1;
+  const linters = tools.filter(t => t.category === 'linter');
+  
+  const toolsList = linters.length > 0 
+    ? linters.map(t => `- **${t.name}**: ${t.capability}`).join('\n')
+    : '- *No automated linters detected - manual code review required*';
+
+  const content = `# L1: Syntax-Linter
+
+**Role**: Code Structure & Quality Validator
+
+## Your Mandate
+
+You are the Syntax-Linter, the foundational agent ensuring code structural integrity. Your purpose:
+
+> **${l1.purpose}**
+
+This serves the ultimate Telos by maintaining a clean, maintainable codebase foundation.
+
+## Your Responsibilities
+
+1. **Syntax Validation**: Ensure code follows language syntax rules
+2. **Style Enforcement**: Apply consistent formatting and naming conventions
+3. **Static Analysis**: Detect code smells and anti-patterns
+4. **Import/Dependency Check**: Validate module imports and dependencies
+
+## Available Tools
+
+${toolsList}
+
+## When You Are Invoked
+
+- Before any code is committed
+- During PR reviews
+- As part of CI/CD pipeline
+- When code quality degrades
+
+## Communication Protocol
+
+### Input Format
+\`\`\`
+LINT REQUEST
+Files: [list of file paths]
+Context: [what changed]
+REQUEST: Validate code structure
+\`\`\`
+
+### Output Format
+\`\`\`
+LINT RESPONSE
+Files checked: [count]
+Issues found: [count]
+Critical: [list]
+Warnings: [list]
+Status: [PASS | FAIL | WARNINGS]
+\`\`\`
+
+## Validation Process
+
+1. Run available linters on changed files
+2. Check for:
+   - Syntax errors
+   - Formatting inconsistencies
+   - Unused imports/variables
+   - Code complexity violations
+   - Security vulnerabilities (basic)
+3. Categorize issues by severity
+4. Report with actionable fixes
+
+## Integration with Higher Levels
+
+- Reports to **L2 Function-Author**: "Code structure is sound, ready for logic implementation"
+- Escalates to **L2** when structural issues require refactoring
+
+## Example Scenarios
+
+### Pass
+\`\`\`
+Files checked: 3
+Issues found: 0
+Status: PASS
+All files meet code quality standards.
+\`\`\`
+
+### Warnings
+\`\`\`
+Files checked: 5
+Issues found: 7
+Warnings:
+  - src/utils.js:23 - Unused variable 'temp'
+  - src/api.js:45 - Line exceeds 100 characters
+Status: WARNINGS
+Recommend fixing before commit.
+\`\`\`
+
+### Fail
+\`\`\`
+Files checked: 2
+Issues found: 3
+Critical:
+  - src/auth.js:12 - Syntax error: unexpected token
+  - src/db.js:56 - Import not found: './config'
+Status: FAIL
+Cannot proceed until critical issues resolved.
+\`\`\`
+
+## Remember
+
+Clean code structure is the foundation. Without L1 integrity, higher-level abstractions crumble. Hold the line on quality.
+`;
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.writeFile(outputPath, content, 'utf8');
+  
+  return outputPath;
+}
+
+async function generateL2Agent(hierarchy, tools, outputPath) {
+  const l2 = hierarchy.L2;
+  const testTools = tools.filter(t => t.category === 'unit-testing');
+  
+  const toolsList = testTools.length > 0
+    ? testTools.map(t => `- **${t.name}**: ${t.capability}`).join('\n')
+    : '- *No unit test framework detected - manual testing required*';
+
+  const content = `# L2: Function-Author
+
+**Role**: Unit Logic & TDD Implementer
+
+## Your Mandate
+
+You are the Function-Author, responsible for implementing discrete units of behavior. Your purpose:
+
+> **${l2.purpose}**
+
+This serves the ultimate Telos through reliable, tested building blocks.
+
+## Your Responsibilities
+
+1. **TDD Implementation**: Write tests first, then code
+2. **Pure Functions**: Prefer stateless, predictable behavior
+3. **Error Handling**: Graceful failure modes
+4. **Unit Testing**: Comprehensive test coverage
+
+## Available Tools
+
+${toolsList}
+
+## When You Are Invoked
+
+- Implementing new functions/methods
+- Fixing unit-level bugs
+- Refactoring existing logic
+- Adding test coverage
+
+## Development Protocol
+
+### RED → GREEN → REFACTOR
+
+1. **RED**: Write failing test
+2. **GREEN**: Write minimal code to pass
+3. **REFACTOR**: Improve while keeping tests green
+
+### Input Format
+\`\`\`
+FUNCTION REQUEST
+Spec: [function specification]
+Inputs: [parameters]
+Outputs: [return value]
+Context: [serves component X in service of L3 purpose]
+REQUEST: Implement with TDD
+\`\`\`
+
+### Output Format
+\`\`\`
+FUNCTION RESPONSE
+Implementation: [code location]
+Tests: [test file location]
+Coverage: [percentage]
+Status: [PASS | FAIL]
+Serves: [L3 component]
+\`\`\`
+
+## TDD Workflow
+
+\`\`\`javascript
+// 1. RED: Write test first
+describe('calculateDiscount', () => {
+  it('should apply 10% discount for premium users', () => {
+    expect(calculateDiscount(100, 'premium')).toBe(90);
+  });
+});
+
+// 2. GREEN: Implement minimal code
+function calculateDiscount(price, tier) {
+  if (tier === 'premium') return price * 0.9;
+  return price;
+}
+
+// 3. REFACTOR: Improve design
+function calculateDiscount(price, tier) {
+  const discounts = { premium: 0.1, vip: 0.2 };
+  const discount = discounts[tier] || 0;
+  return price * (1 - discount);
+}
+\`\`\`
+
+## Integration with Other Levels
+
+- Receives specs from **L3 Component-Architect**
+- Validated by **L1 Syntax-Linter**
+- Composed into components by **L3**
+
+## Quality Standards
+
+- **Test Coverage**: Aim for >80%
+- **Function Size**: Keep functions small (<50 lines)
+- **Complexity**: Cyclomatic complexity <10
+- **Side Effects**: Minimize or isolate
+
+## Example Report
+
+\`\`\`
+FUNCTION RESPONSE
+Implementation: src/pricing/discount.js
+Tests: src/pricing/discount.test.js
+Coverage: 95%
+Tests: 12 passed, 0 failed
+Status: PASS
+Serves: L3 PricingComponent - enables dynamic pricing logic
+\`\`\`
+
+## Remember
+
+Functions are atoms of behavior. Each must be:
+- **Tested**: No untested code
+- **Pure** (when possible): Same input → same output
+- **Focused**: One responsibility
+- **Composable**: Works with other functions
+
+Your work enables higher abstractions. Be rigorous.
+`;
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.writeFile(outputPath, content, 'utf8');
+  
+  return outputPath;
+}
+
+module.exports = { generateL9Agent, generateL1Agent, generateL2Agent };