telos-framework 0.9.2 → 0.10.1

package/lib/installers/slash-commands.js

@@ -1,89 +1,170 @@
 const fs = require('fs').promises;
 const path = require('path');
+const { 
+  COMMAND_METADATA, 
+  getPlatformConfig, 
+  hasNativeCommands,
+  transformForRulesFile 
+} = require('./platform-adapters');
 
+/**
+ * Read centralized command template
+ */
+async function readCommandTemplate(commandName) {
+  const templatePath = path.join(__dirname, '../../templates/commands', `${commandName}.md`);
+  return fs.readFile(templatePath, 'utf-8');
+}
+
+/**
+ * Ensure command directory exists
+ */
 async function ensureDirectories(projectRoot, platform) {
-  const commandsDir = platform === 'claude' 
-    ? path.join(projectRoot, '.claude', 'commands', 'telos')
-    : path.join(projectRoot, '.opencode', 'command');
+  const config = getPlatformConfig(platform);
+  if (!config || !config.hasNativeCommands) return null;
   
+  const commandsDir = path.join(projectRoot, config.commandDir);
   await fs.mkdir(commandsDir, { recursive: true });
   return commandsDir;
 }
 
-async function addFrontmatterToContent(content, filename) {
-  const descriptions = {
-    'telos-init.md': 'Initialize Telos multi-agent system for this project',
-    'telos-quick.md': 'Quick Telos initialization with auto-accepted AI proposals',
-    'telos-validate.md': 'Validate current code against Telos purpose hierarchy',
-    'telos-status.md': 'Show current Telos configuration and hierarchy',
-    'telos-reset.md': 'Clear existing Telos installation and reinitialize'
-  };
-  
-  const description = descriptions[filename] || 'Telos command';
-  
-  if (content.startsWith('---')) {
-    return content;
+/**
+ * Install slash commands for platforms with native command support
+ */
+async function installNativeCommands(projectRoot, platform) {
+  const config = getPlatformConfig(platform);
+  if (!config || !config.hasNativeCommands) {
+    return [];
   }
-  
-  return `---\ndescription: ${description}\n---\n\n${content}`;
-}
 
-async function copyCommandFiles(projectRoot, platform) {
-  const sourceDir = path.join(__dirname, '../../.claude/commands/telos');
   const targetDir = await ensureDirectories(projectRoot, platform);
-  
-  const commandFiles = [
-    'init.md',
-    'quick.md',
-    'reset.md',
-    'validate.md',
-    'status.md'
-  ];
-  
+  const commandNames = Object.keys(COMMAND_METADATA);
   const results = [];
-  for (const file of commandFiles) {
-    const sourcePath = path.join(sourceDir, file);
-    
-    let targetFile = file;
-    if (platform === 'opencode') {
-      targetFile = file.replace('.md', '').replace(/^/, 'telos-') + '.md';
-    }
-    
-    const targetPath = path.join(targetDir, targetFile);
-    
+
+  for (const commandName of commandNames) {
     try {
-      let content = await fs.readFile(sourcePath, 'utf-8');
+      // Read centralized template
+      const content = await readCommandTemplate(commandName);
       
-      if (platform === 'opencode') {
-        content = await addFrontmatterToContent(content, targetFile);
-      }
+      // Transform for platform
+      const transformed = config.transform(content, commandName);
       
-      await fs.writeFile(targetPath, content);
+      // Write to target
+      const targetFile = config.fileNaming(commandName);
+      const targetPath = path.join(targetDir, targetFile);
+      
+      await fs.writeFile(targetPath, transformed);
       results.push({ file: targetFile, success: true, path: targetPath });
     } catch (error) {
-      results.push({ file: targetFile, success: false, error: error.message });
+      results.push({ file: commandName, success: false, error: error.message });
     }
   }
-  
+
   return results;
 }
 
+/**
+ * Generate embedded command instructions for platforms without native commands
+ */
+async function generateEmbeddedCommands() {
+  const commands = {};
+  const commandNames = Object.keys(COMMAND_METADATA);
+
+  for (const commandName of commandNames) {
+    try {
+      commands[commandName] = await readCommandTemplate(commandName);
+    } catch (error) {
+      console.warn(`Warning: Could not read template for ${commandName}: ${error.message}`);
+    }
+  }
+
+  return transformForRulesFile(commands);
+}
+
+/**
+ * Embed commands into a config file for platforms without native slash commands
+ */
+async function embedCommandsInConfig(projectRoot, platform) {
+  const config = getPlatformConfig(platform);
+  if (!config || config.hasNativeCommands) {
+    return { success: false, reason: 'platform-has-native-commands' };
+  }
+
+  const configPath = path.join(projectRoot, config.configFile);
+  const embeddedContent = await generateEmbeddedCommands();
+  
+  try {
+    // Check if config file exists
+    let existingContent = '';
+    try {
+      existingContent = await fs.readFile(configPath, 'utf-8');
+    } catch (e) {
+      // File doesn't exist, will create new
+    }
+
+    // Check if commands already embedded
+    if (existingContent.includes('## Telos Commands')) {
+      // Replace existing Telos Commands section
+      const beforeTelos = existingContent.split('## Telos Commands')[0];
+      const afterTelos = existingContent.split('## Telos Commands')[1];
+      
+      // Find end of Telos section (next ## heading or end of file)
+      const nextHeadingMatch = afterTelos?.match(/\n## [^T]/);
+      const afterTelosSection = nextHeadingMatch 
+        ? afterTelos.substring(nextHeadingMatch.index) 
+        : '';
+      
+      const newContent = beforeTelos + embeddedContent + afterTelosSection;
+      await fs.writeFile(configPath, newContent);
+      return { success: true, updated: true, path: configPath };
+    } else {
+      // Append to existing content
+      const newContent = existingContent + '\n\n' + embeddedContent;
+      await fs.writeFile(configPath, newContent);
+      return { success: true, created: !existingContent, updated: !!existingContent, path: configPath };
+    }
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Install slash commands for selected platforms
+ * - Platforms with native commands: Creates command files
+ * - Platforms without native commands: Embeds in config files
+ */
 async function installSlashCommands(projectRoot, selectedPlatforms = ['claude']) {
   const platforms = Array.isArray(selectedPlatforms) ? selectedPlatforms : [selectedPlatforms];
-  
-  const commandPlatforms = platforms.filter(p => p === 'claude' || p === 'opencode');
-  
   const allResults = [];
-  for (const platform of commandPlatforms) {
-    const results = await copyCommandFiles(projectRoot, platform);
-    allResults.push({ platform, results });
+
+  for (const platform of platforms) {
+    if (hasNativeCommands(platform)) {
+      // Install native command files
+      const results = await installNativeCommands(projectRoot, platform);
+      allResults.push({ platform, type: 'native', results });
+    } else if (getPlatformConfig(platform)) {
+      // Embed in config file
+      const result = await embedCommandsInConfig(projectRoot, platform);
+      allResults.push({ platform, type: 'embedded', results: [result] });
+    }
+    // Skip unknown platforms silently
   }
-  
+
   return allResults;
 }
 
+/**
+ * Copy command files (legacy API - kept for backwards compatibility)
+ */
+async function copyCommandFiles(projectRoot, platform) {
+  return installNativeCommands(projectRoot, platform);
+}
+
 module.exports = {
   ensureDirectories,
   copyCommandFiles,
-  installSlashCommands
+  installSlashCommands,
+  installNativeCommands,
+  embedCommandsInConfig,
+  generateEmbeddedCommands,
+  readCommandTemplate
 };

package/lib/sdd/spec-templates.js

@@ -244,43 +244,26 @@ function generateSpec(level, data = {}) {
  * @returns {string} TELOS.md content
  */
 function generateTelosEntry(data = {}) {
+  // Generate experiences list if provided
+  const experiencesList = data.experiences?.length > 0
+    ? data.experiences.map(e => `- [${e.title}](specs/L3-experience/${e.file})`).join('\n')
+    : '_No experiences defined yet. Run `/telos:init` to add user journeys._';
+
   return `# TELOS: ${data.projectName || 'Project Name'}
 
 > Purpose-driven development with spec-code traceability
 
-## Quick Start
-
-\`\`\`bash
-telos validate        # Validate all specs and links
-telos context <id>    # Load recursive context for AI
-telos coverage        # Show spec-test coverage
-telos orphans         # Find unlinked code
-\`\`\`
-
 ## Purpose
 
 ${data.purpose || '[Your project purpose - see L4:purpose spec]'}
 
 See: [Full Purpose Spec](specs/L4-purpose/purpose.md)
 
-## Spec Hierarchy
+## User Experiences (L3)
 
-\`\`\`
-L4:purpose ─────────────────────────────────────────────────────┐
-│ ${data.purposeTitle || 'Project Purpose'}                     │
-│                                                                │
-├── L3:experience ──────────────────────────────────────────────┤
-│   User journeys, UX requirements, analytics                   │
-│                                                                │
-├── L2:contract ────────────────────────────────────────────────┤
-│   API contracts, component interfaces                         │
-│                                                                │
-└── L1:function ────────────────────────────────────────────────┤
-    Individual functions with TDD scenarios                      │
-└────────────────────────────────────────────────────────────────┘
-\`\`\`
+${experiencesList}
 
-## Spec Levels
+## Spec Hierarchy
 
 | Level | Name | Description | Count |
 |-------|------|-------------|-------|
@@ -289,43 +272,96 @@ L4:purpose ───────────────────────
 | L2 | Contract | APIs + component interfaces | ${data.l2Count || 0} |
 | L1 | Function | Functions with TDD | ${data.l1Count || 0} |
 
-## Code Style
+---
+
+## 🚨 IMPORTANT: Feature Request Workflow
+
+**When the user requests a new feature, you MUST follow this workflow:**
+
+### Step 1: Check Impact on Experiences (L3)
+
+Ask: "Does this feature affect any existing user journeys, or create a new one?"
+
+- If **new journey**: Create a new L3 spec in \`telos/specs/L3-experience/\`
+- If **modifies journey**: Update the relevant L3 spec first
+- If **no journey impact**: Proceed to Step 2
+
+### Step 2: Define or Update Contracts (L2)
+
+Before writing ANY code, create/update L2 contract specs:
+
+- **New API endpoint?** → Create \`telos/specs/L2-contract/api-[name].md\`
+- **New component?** → Create \`telos/specs/L2-contract/component-[name].md\`
+- **Modifying existing?** → Update the relevant L2 spec
+
+L2 specs must include:
+- Interface/API signature
+- Input/output contracts
+- Error handling
+- Parent L3 experience reference
+
+### Step 3: Define Functions (L1)
 
-Style enforcement handled by existing tooling:
-${data.linters?.map(l => `- **${l.name}**: \`${l.config}\``).join('\n') || `- **ESLint**: \`.eslintrc.js\`
-- **Prettier**: \`.prettierrc\`
-- **TypeScript**: \`tsconfig.json\``}
+For each function needed to implement the L2 contracts:
 
-## Annotation Format
+1. Create L1 spec in \`telos/specs/L1-function/\`
+2. Include TDD scenarios (given/when/then)
+3. Reference parent L2 contract
+
+### Step 4: Generate Tests
+
+\`\`\`bash
+telos spec generate-tests L1:function:[spec-id]
+\`\`\`
+
+Or manually create tests with \`@telos-test\` annotations.
+
+### Step 5: Implement with Annotations
 
 \`\`\`${data.primaryLanguage || 'typescript'}
 // @telos L1:function:src/module:functionName
 export function functionName() {
   // implementation
 }
+\`\`\`
+
+### Step 6: Validate Before Commit
 
+\`\`\`bash
+telos validate
+\`\`\`
+
+---
+
+## Quick Reference
+
+**Commands:**
+- \`/telos:validate\` - Validate specs, code links, and tests
+- \`/telos:status\` - Show current spec counts and health
+- \`/telos:sdd-discover\` - Generate specs from existing code
+- \`/telos:sdd-context <spec-id>\` - Load context for a spec
+- \`/telos:sdd-generate-tests <spec-id>\` - Generate tests from scenarios
+
+**Annotation Format:**
+\`\`\`${data.primaryLanguage || 'typescript'}
+// @telos L1:function:src/module:functionName
 // @telos-test L1:function:src/module:functionName
-describe('functionName', () => {
-  // @telos-scenario L1:function:src/module:functionName:success-case
-  it('should handle success case', () => {
-    // test
-  });
-});
+// @telos-scenario L1:function:src/module:functionName:scenario-name
 \`\`\`
 
-## Workflow
+**Spec ID Format:** \`L[level]:[type]:[path]:[name]\`
 
-1. **Create Spec** → Define requirements and scenarios
-2. **Generate Tests** → \`telos spec generate-tests <spec-id>\`
-3. **Run Tests** → Tests fail (Red)
-4. **Implement Code** → Add @telos annotation
-5. **Run Tests** → Tests pass (Green)
-6. **Validate** → \`telos validate\`
-7. **Commit** → Pre-commit hook verifies
+Examples:
+- \`L4:purpose\`
+- \`L3:experience:user-signup-flow\`
+- \`L2:contract:api-auth\`
+- \`L1:function:src/auth/validation:validateToken\`
+
+---
 
 ## Links
 
-- [Full Documentation](https://github.com/telos-framework/init)
+- [Telos Documentation](https://github.com/telos-framework/init)
 - [Spec-Driven Development Guide](https://telos-framework.dev/sdd)
 `;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "telos-framework",
-  "version": "0.9.2",
+  "version": "0.10.1",
   "description": "Telos-driven Multi-Agent Development Framework - A philosophically-grounded AI collective for purpose-aligned software development",
   "main": "index.js",
   "bin": {

package/templates/TELOS_CORE.md

@@ -6,6 +6,15 @@ This project uses the **Telos Framework** with **Spec-Driven Development
 **CRITICAL**: All code must trace back to specifications. Every function needs a
 `@telos` annotation linking it to a spec.
 
+## ⚠️ IMPORTANT: Read telos/TELOS.md First
+
+Before making any changes, **always read `telos/TELOS.md`** for:
+
+- Project purpose and success metrics
+- User experiences (L3 journeys)
+- Feature request workflow (MUST follow for new features)
+- Current spec counts and health
+
 ## Spec-Driven Development (SDD)
 
 This project enforces a 4-level spec hierarchy: