telos-framework 0.9.2 → 0.10.0

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

@@ -151,9 +151,113 @@ 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:
+
+**What are the key user journeys in your application?**
+
+Examples of user journeys:
+
+- "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: Update TELOS.md
+
+Update `telos/TELOS.md` to include the experiences. See the template in
+`lib/sdd/spec-templates.js` for the full format. Key sections to update:
+
+- **Experiences** section listing all L3 journeys
+- **Spec Levels** table with correct counts
+
+## Step 6: Explain the Workflow
+
+After saving specs, explain the SDD workflow:
 
 ---
 
@@ -162,25 +266,10 @@ After saving the purpose spec, explain the SDD workflow:
 **Your project now has:**
 
 - `telos/specs/L4-purpose/purpose.md` - Your project purpose
-- `telos/specs/L3-experience/` - For user journey specs
+- `telos/specs/L3-experience/*.md` - Your user journey specs
 - `telos/specs/L2-contract/` - For API/component contracts
 - `telos/specs/L1-function/` - For function specs with TDD scenarios
-
-**How Spec-Driven Development works:**
-
-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
-
-**Code annotation example:**
-
-```typescript
-// @telos L1:function:src/auth/validation:validateToken
-export function validateToken(token: string): TokenValidation {
-  // implementation
-}
-```
+- `telos/TELOS.md` - Entry point with workflow guidance
 
 **Available commands:**
 
@@ -192,8 +281,8 @@ export function validateToken(token: string): TokenValidation {
 
 **Next steps:**
 
-1. For existing code: Run `/telos:sdd-discover` to generate specs
-2. For new features: Create specs in `telos/specs/` before coding
+1. For existing code: Run `/telos:sdd-discover` to generate L2/L1 specs
+2. For new features: Follow the workflow in `telos/TELOS.md`
 3. Always add `@telos` annotations to link code to specs
 
 ---
@@ -201,6 +290,6 @@ export function validateToken(token: string): TokenValidation {
 ## 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 purpose and journeys
 - Be conversational - this is a dialogue, not a survey
 - Remind users that specs come before code

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.0",
   "description": "Telos-driven Multi-Agent Development Framework - A philosophically-grounded AI collective for purpose-aligned software development",
   "main": "index.js",
   "bin": {