telos-framework 0.9.2 → 0.10.1

package/.claude/commands/telos/init.md

@@ -151,56 +151,412 @@ title: [Project Name]
 - **Method**: /telos:init
 ```
 
-## Step 4: Explain the Workflow
+## Step 4: Define L3 Experiences (User Journeys)
 
-After saving the purpose spec, explain the SDD workflow:
+Now ask about key user experiences. These are the main things users DO with the
+application.
 
----
+Ask:
 
-✅ **Telos initialization complete!**
+**What are the key user journeys in your application?**
 
-**Your project now has:**
+Examples of user journeys:
 
-- `telos/specs/L4-purpose/purpose.md` - Your project purpose
-- `telos/specs/L3-experience/` - For user journey specs
-- `telos/specs/L2-contract/` - For API/component contracts
-- `telos/specs/L1-function/` - For function specs with TDD scenarios
+- "User signs up and creates their first project"
+- "User searches for products and completes checkout"
+- "Admin reviews and approves pending submissions"
+
+List 2-5 key journeys (or say "skip" if you want to define these later):
+
+**STOP and WAIT for user response.**
+
+### 4.1 Create L3 Experience Specs
+
+For each journey the user provides, create a spec file in
+`telos/specs/L3-experience/`:
+
+**Filename**: Convert journey to kebab-case (e.g., `user-signup-flow.md`)
+
+```markdown
+<!-- telos-metadata
+id: L3:experience:[filename-without-extension]
+level: 3
+title: [Journey Title]
+parent: L4:purpose
+-->
+
+# L3: [Journey Title]
+
+## Overview
+
+[Brief description of this user journey]
+
+## User Story
+
+As a [user type], I want to [action] so that [benefit].
+
+## Journey Steps
+
+1. **[Step 1 name]**
+   - User action: [What the user does]
+   - System response: [What happens]
+   - Success criteria: [How we know it worked]
+
+2. **[Step 2 name]**
+   - User action: [What the user does]
+   - System response: [What happens]
+   - Success criteria: [How we know it worked]
+
+[Continue for each step...]
+
+## Edge Cases
+
+- [Edge case 1]: [How it's handled]
+- [Edge case 2]: [How it's handled]
+
+## Analytics Events
+
+- `[event_name]`: [When it fires, what it tracks]
+
+## Related Specs
+
+- L2: [Related contracts - to be defined]
+- L1: [Related functions - to be defined]
+```
+
+### 4.2 Confirm Experiences
+
+After creating the L3 specs, summarize:
+
+```
+═══════════════════════════════════════════════════════════════════════════
+                      L3 EXPERIENCES CREATED
+═══════════════════════════════════════════════════════════════════════════
+
+Created [N] user journey specs:
+
+1. telos/specs/L3-experience/[journey-1].md
+   "[Journey 1 title]"
+
+2. telos/specs/L3-experience/[journey-2].md
+   "[Journey 2 title]"
+
+[etc...]
+
+These journeys will guide your L2 contracts and L1 functions.
+═══════════════════════════════════════════════════════════════════════════
+```
+
+## Step 5: Define L2 Contracts (APIs & Components)
+
+Now analyze the codebase for existing contracts OR ask the user about them.
+
+### 5.1 Check for Existing Code
+
+Scan for:
+
+- API routes/endpoints (Express, FastAPI, Next.js API routes, etc.)
+- React/Vue/Svelte components
+- Service classes
+- Database models/schemas
+
+### 5.2 If Code Exists → Propose Contracts
+
+If you found existing APIs/components, propose L2 specs:
+
+```
+═══════════════════════════════════════════════════════════════════════════
+                     DETECTED L2 CONTRACTS
+═══════════════════════════════════════════════════════════════════════════
+
+Based on your codebase, I found these contracts:
+
+APIs:
+- POST /api/auth/login → api-auth-login
+- GET /api/users/:id → api-users-get
+[etc...]
+
+Components:
+- LoginForm → component-login-form
+- UserProfile → component-user-profile
+[etc...]
+
+Should I create L2 specs for these? (yes/no/select specific ones)
+═══════════════════════════════════════════════════════════════════════════
+```
+
+**STOP and WAIT for user response.**
+
+### 5.3 If No Code OR Greenfield → Ask User
+
+If no existing code found, ask:
+
+**What are the main APIs or components you plan to build?**
+
+Examples:
+
+- "Authentication API (login, logout, register)"
+- "Product listing component"
+- "Payment processing service"
+
+List your key contracts (or say "skip" to define later):
+
+**STOP and WAIT for user response.**
+
+### 5.4 Create L2 Contract Specs
+
+For each contract, create a spec file in `telos/specs/L2-contract/`:
+
+**Filename**: `api-[name].md` or `component-[name].md`
+
+```markdown
+<!-- telos-metadata
+id: L2:contract:[filename-without-extension]
+level: 2
+title: [Contract Title]
+parent: L3:experience:[related-journey]
+-->
+
+# L2: [Contract Title]
+
+## Overview
+
+[What this API/component does]
+
+## Interface
+
+### [For APIs]
+
+**Endpoint:** `[METHOD] /api/[path]`
+
+**Request:** \`\`\`json { "field": "type" } \`\`\`
+
+**Response:** \`\`\`json { "field": "type" } \`\`\`
+
+**Errors:**
+
+- 400: [When/why]
+- 401: [When/why]
+- 404: [When/why]
+
+### [For Components]
+
+**Props:** \`\`\`typescript interface [ComponentName]Props { prop1: type; prop2:
+type; onEvent?: (data: type) => void; } \`\`\`
+
+## Behavior
 
-**How Spec-Driven Development works:**
+- [Behavior 1]
+- [Behavior 2]
 
-1. **Before coding**: Create a spec at the appropriate level
-2. **Write tests**: Generate tests from spec scenarios
-3. **Implement**: Write code with `@telos` annotation linking to spec
-4. **Validate**: Run `/telos:validate` before commits
+## Related Specs
 
-**Code annotation example:**
+- L3: [Parent experience]
+- L1: [Functions needed - to be defined]
+```
+
+### 5.5 Confirm Contracts
+
+After creating the L2 specs, summarize:
+
+```
+═══════════════════════════════════════════════════════════════════════════
+                       L2 CONTRACTS CREATED
+═══════════════════════════════════════════════════════════════════════════
+
+Created [N] contract specs:
+
+1. telos/specs/L2-contract/[contract-1].md
+   "[Contract 1 title]"
+
+2. telos/specs/L2-contract/[contract-2].md
+   "[Contract 2 title]"
+
+[etc...]
+═══════════════════════════════════════════════════════════════════════════
+```
+
+## Step 6: Define L1 Functions
+
+Now identify the key functions needed to implement the L2 contracts.
+
+### 6.1 Check for Existing Functions
+
+Scan for functions/methods in:
+
+- `src/`, `lib/`, `app/` directories
+- Look for exported functions, class methods
+- Focus on business logic, not utility functions
+
+### 6.2 If Functions Exist → Propose L1 Specs
+
+```
+═══════════════════════════════════════════════════════════════════════════
+                     DETECTED L1 FUNCTIONS
+═══════════════════════════════════════════════════════════════════════════
+
+Found key functions that need specs:
+
+From src/auth/:
+- validateToken() → L1:function:src/auth:validateToken
+- hashPassword() → L1:function:src/auth:hashPassword
+
+From src/users/:
+- createUser() → L1:function:src/users:createUser
+- getUserById() → L1:function:src/users:getUserById
+
+[etc...]
+
+Should I create L1 specs for these? (yes/no/select specific ones)
+═══════════════════════════════════════════════════════════════════════════
+```
+
+**STOP and WAIT for user response.**
+
+### 6.3 If No Functions OR Greenfield → Ask User
+
+If no existing functions found, ask:
+
+**What are the core functions your application needs?**
+
+Think about the L2 contracts you defined. What functions implement them?
+
+Examples:
+
+- "validateToken - checks if JWT is valid"
+- "processPayment - handles Stripe charges"
+- "sendNotification - sends push/email notifications"
+
+List key functions (or say "skip" to define later):
+
+**STOP and WAIT for user response.**
+
+### 6.4 Create L1 Function Specs
+
+For each function, create a spec file in `telos/specs/L1-function/`:
+
+**Filename**: `[module]-[function-name].md`
+
+```markdown
+<!-- telos-metadata
+id: L1:function:[path]:[functionName]
+level: 1
+title: [functionName]
+parent: L2:contract:[related-contract]
+-->
+
+# L1: [functionName]
+
+## Purpose
+
+[What this function does and why]
+
+## Signature
+
+\`\`\`typescript function [functionName]( param1: Type, param2: Type ):
+ReturnType \`\`\`
+
+## Parameters
+
+| Name   | Type | Description |
+| ------ | ---- | ----------- |
+| param1 | Type | Description |
+| param2 | Type | Description |
+
+## Returns
+
+| Type       | Description     |
+| ---------- | --------------- |
+| ReturnType | What it returns |
 
-```typescript
-// @telos L1:function:src/auth/validation:validateToken
-export function validateToken(token: string): TokenValidation {
-  // implementation
-}
+## TDD Scenarios
+
+### Scenario: [Happy path name]
+
+\`\`\`gherkin Given [precondition] When [action] Then [expected result] \`\`\`
+
+### Scenario: [Error case name]
+
+\`\`\`gherkin Given [precondition] When [action] Then [expected error] \`\`\`
+
+### Scenario: [Edge case name]
+
+\`\`\`gherkin Given [edge condition] When [action] Then [expected behavior]
+\`\`\`
+
+## Related Specs
+
+- L2: [Parent contract]
 ```
 
-**Available commands:**
+### 6.5 Confirm Functions
+
+After creating the L1 specs, summarize:
+
+```
+═══════════════════════════════════════════════════════════════════════════
+                       L1 FUNCTIONS CREATED
+═══════════════════════════════════════════════════════════════════════════
+
+Created [N] function specs:
+
+1. telos/specs/L1-function/[function-1].md
+   "[function1Name]" - [brief description]
+
+2. telos/specs/L1-function/[function-2].md
+   "[function2Name]" - [brief description]
+
+[etc...]
+═══════════════════════════════════════════════════════════════════════════
+```
+
+## Step 7: Update TELOS.md
+
+Update `telos/TELOS.md` with all the specs created:
+
+- **User Experiences** section listing all L3 journeys
+- **Spec Levels** table with correct counts for all levels
+- Verify all parent-child relationships are correct
+
+## Step 8: Final Summary
+
+After saving all specs, provide the final summary:
+
+---
+
+✅ **Telos initialization complete!**
+
+**Your project now has:**
+
+- `telos/specs/L4-purpose/purpose.md` - Your project purpose
+- `telos/specs/L3-experience/*.md` - [N] user journey specs
+- `telos/specs/L2-contract/*.md` - [N] API/component contracts
+- `telos/specs/L1-function/*.md` - [N] function specs with TDD scenarios
+- `telos/TELOS.md` - Entry point with workflow guidance
+
+**Spec Summary:**
 
-- `/telos:validate` - Validate specs, links, tests
-- `/telos:status` - Show current configuration
-- `/telos:sdd-discover` - Generate specs from existing code
-- `/telos:sdd-context` - Load spec context before changes
-- `/telos:sdd-generate-tests` - Generate tests from scenarios
+| Level | Count | Description |
+| ----- | ----- | ----------- |
+| L4    | 1     | Purpose     |
+| L3    | [N]   | Experiences |
+| L2    | [N]   | Contracts   |
+| L1    | [N]   | Functions   |
 
 **Next steps:**
 
-1. For existing code: Run `/telos:sdd-discover` to generate specs
-2. For new features: Create specs in `telos/specs/` before coding
-3. Always add `@telos` annotations to link code to specs
+1. Generate tests: `/telos:sdd-generate-tests` for any L1 spec
+2. Implement code with `@telos` annotations
+3. Validate before commits: `/telos:validate`
+4. For new features: Follow the workflow in `telos/TELOS.md`
 
 ---
 
 ## Tips
 
 - If README is missing or vague, ask user for clarification
-- For empty/greenfield projects, focus on defining clear purpose
+- For empty/greenfield projects, focus on defining clear specs before coding
+- For brownfield projects, propose specs based on detected code
 - Be conversational - this is a dialogue, not a survey
+- Users can say "skip" at any level to define specs later
 - Remind users that specs come before code

package/lib/installers/platform-adapters.js

@@ -0,0 +1,216 @@
+/**
+ * Platform Adapters for Telos Commands
+ * 
+ * Transforms centralized command definitions into platform-specific formats.
+ * 
+ * Supported platforms:
+ * - claude: .claude/commands/telos/*.md (with frontmatter)
+ * - opencode: .opencode/command/telos-*.md (with frontmatter)
+ * - cursor: Embedded in .cursorrules (no native slash commands)
+ * - cline: Embedded in .clinerules (no native slash commands)
+ * - windsurf: Embedded in .windsurfrules (no native slash commands)
+ * - roo: Embedded in .roocode (no native slash commands)
+ * - gemini: Embedded in GEMINI.md or uses native commands if supported
+ */
+
+const COMMAND_METADATA = {
+  // Core commands
+  init: {
+    description: 'Initialize Telos spec-driven development for this project',
+    aliases: ['telos-init', 'telos:init', 'initialize telos', 'setup telos']
+  },
+  validate: {
+    description: 'Validate specs, code links, and tests',
+    aliases: ['telos-validate', 'telos:validate', 'check telos', 'validate specs']
+  },
+  status: {
+    description: 'Show current Telos configuration and spec status',
+    aliases: ['telos-status', 'telos:status', 'telos info', 'show telos']
+  },
+  quick: {
+    description: 'Quick Telos initialization with auto-accepted AI proposals',
+    aliases: ['telos-quick', 'telos:quick', 'quick init', 'fast setup']
+  },
+  reset: {
+    description: 'Clear existing Telos installation and reinitialize',
+    aliases: ['telos-reset', 'telos:reset', 'clear telos', 'remove telos']
+  },
+  // SDD commands
+  'sdd-init': {
+    description: 'Initialize SDD structure (alternative to init)',
+    aliases: ['telos-sdd-init', 'telos:sdd-init', 'sdd init']
+  },
+  'sdd-discover': {
+    description: 'Generate specs from existing code',
+    aliases: ['telos-sdd-discover', 'telos:sdd-discover', 'discover specs', 'scan code']
+  },
+  'sdd-context': {
+    description: 'Load spec context for AI work',
+    aliases: ['telos-sdd-context', 'telos:sdd-context', 'load context', 'spec context']
+  },
+  'sdd-validate': {
+    description: 'Validate SDD structure and links',
+    aliases: ['telos-sdd-validate', 'telos:sdd-validate', 'validate sdd']
+  },
+  'sdd-generate-tests': {
+    description: 'Generate tests from spec scenarios',
+    aliases: ['telos-sdd-generate-tests', 'telos:sdd-generate-tests', 'generate tests']
+  }
+};
+
+/**
+ * Platform configurations
+ */
+const PLATFORM_CONFIG = {
+  claude: {
+    hasNativeCommands: true,
+    commandDir: '.claude/commands/telos',
+    fileNaming: (name) => `${name}.md`,
+    transform: transformForClaude
+  },
+  opencode: {
+    hasNativeCommands: true,
+    commandDir: '.opencode/command',
+    fileNaming: (name) => `telos-${name}.md`,
+    transform: transformForOpencode
+  },
+  cursor: {
+    hasNativeCommands: false,
+    configFile: '.cursorrules',
+    transform: transformForRulesFile
+  },
+  cline: {
+    hasNativeCommands: false,
+    configFile: '.clinerules',
+    transform: transformForRulesFile
+  },
+  windsurf: {
+    hasNativeCommands: false,
+    configFile: '.windsurfrules',
+    transform: transformForRulesFile
+  },
+  roo: {
+    hasNativeCommands: false,
+    configFile: '.roocode',
+    transform: transformForRulesFile
+  },
+  gemini: {
+    hasNativeCommands: false,
+    configFile: 'GEMINI.md',
+    transform: transformForRulesFile
+  }
+};
+
+/**
+ * Transform command for Claude Code
+ * Adds frontmatter with description
+ */
+function transformForClaude(content, commandName) {
+  const meta = COMMAND_METADATA[commandName];
+  return `---
+description: ${meta.description}
+---
+
+${content}`;
+}
+
+/**
+ * Transform command for OpenCode
+ * Adds frontmatter with description
+ */
+function transformForOpencode(content, commandName) {
+  const meta = COMMAND_METADATA[commandName];
+  return `---
+description: ${meta.description}
+---
+
+${content}`;
+}
+
+/**
+ * Transform commands for platforms without native slash commands
+ * Embeds command triggers and full instructions in config file
+ */
+function transformForRulesFile(commands) {
+  let output = `
+## Telos Commands
+
+When the user asks to run any of these commands, follow the instructions below:
+
+`;
+
+  for (const [name, content] of Object.entries(commands)) {
+    const meta = COMMAND_METADATA[name];
+    output += `### Command: ${name}
+
+**Triggers**: ${meta.aliases.map(a => `"${a}"`).join(', ')}
+
+**Description**: ${meta.description}
+
+<details>
+<summary>Full Instructions (click to expand)</summary>
+
+${content}
+
+</details>
+
+---
+
+`;
+  }
+
+  return output;
+}
+
+/**
+ * Get platform configuration
+ */
+function getPlatformConfig(platform) {
+  return PLATFORM_CONFIG[platform] || null;
+}
+
+/**
+ * Check if platform supports native slash commands
+ */
+function hasNativeCommands(platform) {
+  const config = PLATFORM_CONFIG[platform];
+  return config ? config.hasNativeCommands : false;
+}
+
+/**
+ * Get all supported platforms
+ */
+function getSupportedPlatforms() {
+  return Object.keys(PLATFORM_CONFIG);
+}
+
+/**
+ * Get platforms with native command support
+ */
+function getPlatformsWithNativeCommands() {
+  return Object.entries(PLATFORM_CONFIG)
+    .filter(([_, config]) => config.hasNativeCommands)
+    .map(([name, _]) => name);
+}
+
+/**
+ * Get platforms without native command support (need embedding)
+ */
+function getPlatformsWithoutNativeCommands() {
+  return Object.entries(PLATFORM_CONFIG)
+    .filter(([_, config]) => !config.hasNativeCommands)
+    .map(([name, _]) => name);
+}
+
+module.exports = {
+  COMMAND_METADATA,
+  PLATFORM_CONFIG,
+  transformForClaude,
+  transformForOpencode,
+  transformForRulesFile,
+  getPlatformConfig,
+  hasNativeCommands,
+  getSupportedPlatforms,
+  getPlatformsWithNativeCommands,
+  getPlatformsWithoutNativeCommands
+};