telos-framework 0.2.0 → 0.3.1

package/.claude/commands/telos/status.md

@@ -0,0 +1,170 @@
+---
+description: Show current Telos configuration and hierarchy
+---
+
+# Telos Status
+
+Display the current Telos configuration for this project.
+
+## Check Installation
+
+First, check if Telos is initialized:
+
+- Look for `telos/content/TELOS.md`
+- Look for `telos/agents/` directory
+
+If not found, display:
+
+```
+❌ Telos not initialized
+
+Run `/telos-init` to set up the multi-agent system.
+```
+
+## Display Configuration
+
+If Telos is initialized, read and display:
+
+### 1. Ultimate Purpose
+
+From `telos/content/TELOS.md`, extract and display:
+
+```
+🎯 **Ultimate Purpose (L9)**
+[L9 purpose statement from TELOS.md]
+
+**Beneficiaries**: [Who benefits]
+**Measurable Impact**: [Success metrics]
+```
+
+### 2. Purpose Hierarchy
+
+Display all 9 levels:
+
+| Level | Agent                  | Purpose   | Status                                      |
+| ----- | ---------------------- | --------- | ------------------------------------------- |
+| L9    | Telos-Guardian         | [Purpose] | [✅ if l9-telos-guardian.md exists]         |
+| L8    | Market-Analyst         | [Purpose] | [✅ if l8-market-analyst.md exists]         |
+| L7    | Insight-Synthesizer    | [Purpose] | [✅ if l7-insight-synthesizer.md exists]    |
+| L6    | UX-Simulator           | [Purpose] | [✅ if l6-ux-simulator.md exists]           |
+| L5    | Journey-Validator      | [Purpose] | [✅ if l5-journey-validator.md exists]      |
+| L4    | Integration-Contractor | [Purpose] | [✅ if l4-integration-contractor.md exists] |
+| L3    | Component-Architect    | [Purpose] | [✅ if l3-component-architect.md exists]    |
+| L2    | Function-Author        | [Purpose] | [✅ if l2-function-author.md exists]        |
+| L1    | Syntax-Linter          | [Purpose] | [✅ if l1-syntax-linter.md exists]          |
+
+### 3. Technology Stack
+
+From `telos/content/TELOS.md`, show detected stack:
+
+```
+**Technology Stack**
+- **Languages**: [Languages]
+- **Frameworks**: [Frameworks]
+- **Testing**: [Test frameworks]
+- **Linting**: [Linters]
+- **Build Tools**: [Build systems]
+```
+
+### 4. Installation Details
+
+Show metadata:
+
+```
+**Installation**
+- **Initialized**: [Date from TELOS.md]
+- **Method**: [AI Assistant / CLI]
+- **Agent Files**: [N]/9 present
+- **Orchestrator**: [✅ Present / ❌ Not found] (logos/orchestrator.js)
+```
+
+### 5. Platform Integration
+
+Check for platform-specific files:
+
+```
+**Platform Integration**
+- **Claude Code**: [✅ AGENTS.md exists / ❌ Not configured]
+- **OpenCode**: [✅ .opencode/ setup / ❌ Not configured]
+```
+
+## Health Check
+
+Perform a quick health check:
+
+**✅ Healthy**: All 9 agent files present, TELOS.md valid **⚠️ Incomplete**:
+Some agent files missing **❌ Corrupted**: TELOS.md missing or invalid
+
+If incomplete or corrupted:
+
+```
+⚠️  **Warning**: Telos installation is incomplete.
+
+**Missing files**:
+- [List missing agent files]
+
+**Suggestion**: Run `/telos-reset` then `/telos-init` to reinstall.
+```
+
+## Quick Actions
+
+Display available commands:
+
+```
+**Available Commands**
+- `/telos-validate` - Check code alignment with purpose
+- `/telos-reset` - Clear and reinitialize
+- `/telos-init` - Reconfigure interactively
+- `/telos-quick` - Fast reconfiguration
+```
+
+## Example Output
+
+Full example when healthy:
+
+```
+🎯 **Ultimate Purpose (L9)**
+Enable developers to build software with clear hierarchical purpose
+
+**Beneficiaries**: Software development teams using AI assistants
+**Measurable Impact**: Reduced technical debt, faster onboarding, purpose-aligned decisions
+
+**Purpose Hierarchy**
+
+| Level | Agent | Purpose | Status |
+|-------|-------|---------|--------|
+| L9 | Telos-Guardian | Enable purposeful software development | ✅ |
+| L8 | Market-Analyst | Maximize developer productivity and code quality | ✅ |
+| L7 | Insight-Synthesizer | Synthesize best practices into actionable guidance | ✅ |
+| L6 | UX-Simulator | Ensure intuitive developer experience | ✅ |
+| L5 | Journey-Validator | Validate developer workflows end-to-end | ✅ |
+| L4 | Integration-Contractor | Maintain clean API contracts | ✅ |
+| L3 | Component-Architect | Design modular component architecture | ✅ |
+| L2 | Function-Author | Write testable, maintainable functions | ✅ |
+| L1 | Syntax-Linter | Enforce code quality standards | ✅ |
+
+**Technology Stack**
+- **Languages**: JavaScript, Node.js
+- **Frameworks**: None (CLI tool)
+- **Testing**: Vitest
+- **Linting**: ESLint, Prettier
+- **Build Tools**: npm
+
+**Installation**
+- **Initialized**: 2025-01-15
+- **Method**: AI Assistant (/telos-init)
+- **Agent Files**: 9/9 present ✅
+- **Orchestrator**: ✅ Present
+
+**Platform Integration**
+- **Claude Code**: ✅ AGENTS.md configured
+- **OpenCode**: ✅ .opencode/ configured
+
+**Health**: ✅ Fully operational
+
+**Available Commands**
+- `/telos-validate` - Check code alignment with purpose
+- `/telos-reset` - Clear and reinitialize
+- `/telos-init` - Reconfigure interactively
+- `/telos-quick` - Fast reconfiguration
+```

package/.claude/commands/telos/validate.md

@@ -0,0 +1,143 @@
+---
+description: Validate current code against Telos purpose hierarchy
+---
+
+# Telos Validation
+
+This command checks if your current codebase aligns with the established Telos
+purpose hierarchy.
+
+## Prerequisites
+
+Check if Telos is initialized:
+
+- `telos/content/TELOS.md` must exist
+- At least some agent files in `telos/agents/` must exist
+
+If not found, display: "❌ Telos not initialized. Run `/telos-init` first."
+
+## Validation Process
+
+### Step 1: Load Telos Configuration
+
+Read `telos/content/TELOS.md` to extract:
+
+- Ultimate purpose (L9)
+- 9-level hierarchy definitions
+- Detected technology stack
+
+### Step 2: Analyze Current Codebase
+
+Check for alignment issues:
+
+#### L1 (Syntax-Linter) Validation
+
+- Run detected linters: `npm run lint` or equivalent
+- Check for linting errors
+- Report: ✅ Passes / ❌ Fails with [N] errors
+
+#### L2 (Function-Author) Validation
+
+- Run tests: `npm test` or equivalent
+- Check test coverage
+- Report: ✅ [X]% coverage / ❌ Below threshold
+
+#### L3 (Component-Architect) Validation
+
+- Check for components without proper structure
+- Look for components violating design patterns
+- Report: ✅ Components follow architecture / ⚠️ [N] components need refactoring
+
+#### L4 (Integration-Contractor) Validation
+
+- Check for API contract violations
+- Look for breaking changes without versioning
+- Report: ✅ API contracts maintained / ⚠️ [N] contract issues
+
+#### L5 (Journey-Validator) Validation
+
+- Look for missing E2E tests for critical flows
+- Check if user journeys are documented
+- Report: ✅ User journeys validated / ⚠️ [N] flows untested
+
+#### L6 (UX-Simulator) Validation
+
+- Check for accessibility issues (if tools available)
+- Look for UX inconsistencies
+- Report: ✅ UX standards met / ⚠️ [N] UX issues
+
+#### L7 (Insight-Synthesizer) Validation
+
+- Check if recent changes align with product strategy
+- Look for features without clear user value
+- Report: ✅ Strategy aligned / ⚠️ [N] strategic misalignments
+
+#### L8 (Market-Analyst) Validation
+
+- Check if metrics/analytics are tracked
+- Look for features without measurable outcomes
+- Report: ✅ Business value tracked / ⚠️ [N] untracked features
+
+#### L9 (Telos-Guardian) Validation
+
+- Review recent changes against ultimate purpose
+- Look for purpose drift
+- Report: ✅ Purpose aligned / ⚠️ Potential purpose drift detected
+
+## Validation Report
+
+Display results in a table:
+
+| Level | Agent                  | Status   | Issues        |
+| ----- | ---------------------- | -------- | ------------- |
+| L9    | Telos-Guardian         | ✅/⚠️/❌ | [Description] |
+| L8    | Market-Analyst         | ✅/⚠️/❌ | [Description] |
+| L7    | Insight-Synthesizer    | ✅/⚠️/❌ | [Description] |
+| L6    | UX-Simulator           | ✅/⚠️/❌ | [Description] |
+| L5    | Journey-Validator      | ✅/⚠️/❌ | [Description] |
+| L4    | Integration-Contractor | ✅/⚠️/❌ | [Description] |
+| L3    | Component-Architect    | ✅/⚠️/❌ | [Description] |
+| L2    | Function-Author        | ✅/⚠️/❌ | [Description] |
+| L1    | Syntax-Linter          | ✅/⚠️/❌ | [Description] |
+
+**Overall Status**: ✅ Fully aligned / ⚠️ Needs attention / ❌ Critical
+misalignment
+
+## Detailed Findings
+
+For each ⚠️ or ❌ status, provide:
+
+**[Level] - [Issue Description]**
+
+- **Problem**: What's misaligned
+- **Impact**: How it violates purpose
+- **Suggestion**: How to fix
+
+Example:
+
+```
+L2 (Function-Author) - Low Test Coverage
+- **Problem**: Test coverage is 45%, below 80% threshold
+- **Impact**: Violates L2 purpose of "Write TDD functions with Vitest coverage >80%"
+- **Suggestion**: Add tests for modules in src/utils/ and src/services/
+```
+
+## Next Steps
+
+If validation passes (all ✅): "🎉 Your codebase is fully aligned with Telos!
+Keep up the great work."
+
+If warnings found (⚠️): "⚠️ Some alignment issues detected. Address these to
+maintain Telos integrity."
+
+If critical issues (❌): "❌ Critical misalignment detected. These issues
+violate core Telos principles and should be addressed urgently."
+
+## Validation Frequency
+
+Recommend:
+
+- Run `/telos-validate` before major releases
+- Run after completing significant features
+- Run when onboarding new team members
+- Integrate into CI/CD pipeline (via CLI: `telos validate`)

package/.claude/commands/tm/add-dependency/add-dependency.md

@@ -0,0 +1,55 @@
+Add a dependency between tasks.
+
+Arguments: $ARGUMENTS
+
+Parse the task IDs to establish dependency relationship.
+
+## Adding Dependencies
+
+Creates a dependency where one task must be completed before another can start.
+
+## Argument Parsing
+
+Parse natural language or IDs:
+- "make 5 depend on 3" → task 5 depends on task 3
+- "5 needs 3" → task 5 depends on task 3
+- "5 3" → task 5 depends on task 3
+- "5 after 3" → task 5 depends on task 3
+
+## Execution
+
+```bash
+task-master add-dependency --id=<task-id> --depends-on=<dependency-id>
+```
+
+## Validation
+
+Before adding:
+1. **Verify both tasks exist**
+2. **Check for circular dependencies**
+3. **Ensure dependency makes logical sense**
+4. **Warn if creating complex chains**
+
+## Smart Features
+
+- Detect if dependency already exists
+- Suggest related dependencies
+- Show impact on task flow
+- Update task priorities if needed
+
+## Post-Addition
+
+After adding dependency:
+1. Show updated dependency graph
+2. Identify any newly blocked tasks
+3. Suggest task order changes
+4. Update project timeline
+
+## Example Flows
+
+```
+/project:tm/add-dependency 5 needs 3
+→ Task #5 now depends on Task #3
+→ Task #5 is now blocked until #3 completes
+→ Suggested: Also consider if #5 needs #4
+```

package/.claude/commands/tm/add-subtask/add-subtask.md

@@ -0,0 +1,76 @@
+Add a subtask to a parent task.
+
+Arguments: $ARGUMENTS
+
+Parse arguments to create a new subtask or convert existing task.
+
+## Adding Subtasks
+
+Creates subtasks to break down complex parent tasks into manageable pieces.
+
+## Argument Parsing
+
+Flexible natural language:
+- "add subtask to 5: implement login form"
+- "break down 5 with: setup, implement, test"
+- "subtask for 5: handle edge cases"
+- "5: validate user input" → adds subtask to task 5
+
+## Execution Modes
+
+### 1. Create New Subtask
+```bash
+task-master add-subtask --parent=<id> --title="<title>" --description="<desc>"
+```
+
+### 2. Convert Existing Task
+```bash
+task-master add-subtask --parent=<id> --task-id=<existing-id>
+```
+
+## Smart Features
+
+1. **Automatic Subtask Generation**
+   - If title contains "and" or commas, create multiple
+   - Suggest common subtask patterns
+   - Inherit parent's context
+
+2. **Intelligent Defaults**
+   - Priority based on parent
+   - Appropriate time estimates
+   - Logical dependencies between subtasks
+
+3. **Validation**
+   - Check parent task complexity
+   - Warn if too many subtasks
+   - Ensure subtask makes sense
+
+## Creation Process
+
+1. Parse parent task context
+2. Generate subtask with ID like "5.1"
+3. Set appropriate defaults
+4. Link to parent task
+5. Update parent's time estimate
+
+## Example Flows
+
+```
+/project:tm/add-subtask to 5: implement user authentication
+→ Created subtask #5.1: "implement user authentication"
+→ Parent task #5 now has 1 subtask
+→ Suggested next subtasks: tests, documentation
+
+/project:tm/add-subtask 5: setup, implement, test
+→ Created 3 subtasks:
+  #5.1: setup
+  #5.2: implement  
+  #5.3: test
+```
+
+## Post-Creation
+
+- Show updated task hierarchy
+- Suggest logical next subtasks
+- Update complexity estimates
+- Recommend subtask order

package/.claude/commands/tm/add-subtask/convert-task-to-subtask.md

@@ -0,0 +1,71 @@
+Convert an existing task into a subtask.
+
+Arguments: $ARGUMENTS
+
+Parse parent ID and task ID to convert.
+
+## Task Conversion
+
+Converts an existing standalone task into a subtask of another task.
+
+## Argument Parsing
+
+- "move task 8 under 5"
+- "make 8 a subtask of 5"
+- "nest 8 in 5"
+- "5 8" → make task 8 a subtask of task 5
+
+## Execution
+
+```bash
+task-master add-subtask --parent=<parent-id> --task-id=<task-to-convert>
+```
+
+## Pre-Conversion Checks
+
+1. **Validation**
+   - Both tasks exist and are valid
+   - No circular parent relationships
+   - Task isn't already a subtask
+   - Logical hierarchy makes sense
+
+2. **Impact Analysis**
+   - Dependencies that will be affected
+   - Tasks that depend on converting task
+   - Priority alignment needed
+   - Status compatibility
+
+## Conversion Process
+
+1. Change task ID from "8" to "5.1" (next available)
+2. Update all dependency references
+3. Inherit parent's context where appropriate
+4. Adjust priorities if needed
+5. Update time estimates
+
+## Smart Features
+
+- Preserve task history
+- Maintain dependencies
+- Update all references
+- Create conversion log
+
+## Example
+
+```
+/project:tm/add-subtask/from-task 5 8
+→ Converting: Task #8 becomes subtask #5.1
+→ Updated: 3 dependency references
+→ Parent task #5 now has 1 subtask
+→ Note: Subtask inherits parent's priority
+
+Before: #8 "Implement validation" (standalone)
+After:  #5.1 "Implement validation" (subtask of #5)
+```
+
+## Post-Conversion
+
+- Show new task hierarchy
+- List updated dependencies
+- Verify project integrity
+- Suggest related conversions

package/.claude/commands/tm/add-task/add-task.md

@@ -0,0 +1,78 @@
+Add new tasks with intelligent parsing and context awareness.
+
+Arguments: $ARGUMENTS
+
+## Smart Task Addition
+
+Parse natural language to create well-structured tasks.
+
+### 1. **Input Understanding**
+
+I'll intelligently parse your request:
+- Natural language → Structured task
+- Detect priority from keywords (urgent, ASAP, important)
+- Infer dependencies from context
+- Suggest complexity based on description
+- Determine task type (feature, bug, refactor, test, docs)
+
+### 2. **Smart Parsing Examples**
+
+**"Add urgent task to fix login bug"**
+→ Title: Fix login bug
+→ Priority: high
+→ Type: bug
+→ Suggested complexity: medium
+
+**"Create task for API documentation after task 23 is done"**
+→ Title: API documentation
+→ Dependencies: [23]
+→ Type: documentation
+→ Priority: medium
+
+**"Need to refactor auth module - depends on 12 and 15, high complexity"**
+→ Title: Refactor auth module
+→ Dependencies: [12, 15]
+→ Complexity: high
+→ Type: refactor
+
+### 3. **Context Enhancement**
+
+Based on current project state:
+- Suggest related existing tasks
+- Warn about potential conflicts
+- Recommend dependencies
+- Propose subtasks if complex
+
+### 4. **Interactive Refinement**
+
+```yaml
+Task Preview:
+─────────────
+Title: [Extracted title]
+Priority: [Inferred priority]
+Dependencies: [Detected dependencies]
+Complexity: [Estimated complexity]
+
+Suggestions:
+- Similar task #34 exists, consider as dependency?
+- This seems complex, break into subtasks?
+- Tasks #45-47 work on same module
+```
+
+### 5. **Validation & Creation**
+
+Before creating:
+- Validate dependencies exist
+- Check for duplicates
+- Ensure logical ordering
+- Verify task completeness
+
+### 6. **Smart Defaults**
+
+Intelligent defaults based on:
+- Task type patterns
+- Team conventions
+- Historical data
+- Current sprint/phase
+
+Result: High-quality tasks from minimal input.

package/.claude/commands/tm/analyze-complexity/analyze-complexity.md

@@ -0,0 +1,121 @@
+Analyze task complexity and generate expansion recommendations.
+
+Arguments: $ARGUMENTS
+
+Perform deep analysis of task complexity across the project.
+
+## Complexity Analysis
+
+Uses AI to analyze tasks and recommend which ones need breakdown.
+
+## Execution Options
+
+```bash
+task-master analyze-complexity [--research] [--threshold=5]
+```
+
+## Analysis Parameters
+
+- `--research` → Use research AI for deeper analysis
+- `--threshold=5` → Only flag tasks above complexity 5
+- Default: Analyze all pending tasks
+
+## Analysis Process
+
+### 1. **Task Evaluation**
+For each task, AI evaluates:
+- Technical complexity
+- Time requirements
+- Dependency complexity
+- Risk factors
+- Knowledge requirements
+
+### 2. **Complexity Scoring**
+Assigns score 1-10 based on:
+- Implementation difficulty
+- Integration challenges
+- Testing requirements
+- Unknown factors
+- Technical debt risk
+
+### 3. **Recommendations**
+For complex tasks:
+- Suggest expansion approach
+- Recommend subtask breakdown
+- Identify risk areas
+- Propose mitigation strategies
+
+## Smart Analysis Features
+
+1. **Pattern Recognition**
+   - Similar task comparisons
+   - Historical complexity accuracy
+   - Team velocity consideration
+   - Technology stack factors
+
+2. **Contextual Factors**
+   - Team expertise
+   - Available resources
+   - Timeline constraints
+   - Business criticality
+
+3. **Risk Assessment**
+   - Technical risks
+   - Timeline risks
+   - Dependency risks
+   - Knowledge gaps
+
+## Output Format
+
+```
+Task Complexity Analysis Report
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+High Complexity Tasks (>7):
+📍 #5 "Implement real-time sync" - Score: 9/10
+   Factors: WebSocket complexity, state management, conflict resolution
+   Recommendation: Expand into 5-7 subtasks
+   Risks: Performance, data consistency
+
+📍 #12 "Migrate database schema" - Score: 8/10
+   Factors: Data migration, zero downtime, rollback strategy
+   Recommendation: Expand into 4-5 subtasks
+   Risks: Data loss, downtime
+
+Medium Complexity Tasks (5-7):
+📍 #23 "Add export functionality" - Score: 6/10
+   Consider expansion if timeline tight
+
+Low Complexity Tasks (<5):
+✅ 15 tasks - No expansion needed
+
+Summary:
+- Expand immediately: 2 tasks
+- Consider expanding: 5 tasks
+- Keep as-is: 15 tasks
+```
+
+## Actionable Output
+
+For each high-complexity task:
+1. Complexity score with reasoning
+2. Specific expansion suggestions
+3. Risk mitigation approaches
+4. Recommended subtask structure
+
+## Integration
+
+Results are:
+- Saved to `.taskmaster/reports/complexity-analysis.md`
+- Used by expand command
+- Inform sprint planning
+- Guide resource allocation
+
+## Next Steps
+
+After analysis:
+```
+/project:tm/expand 5    # Expand specific task
+/project:tm/expand/all  # Expand all recommended
+/project:tm/complexity-report  # View detailed report
+```