telos-framework 0.2.0 → 0.3.0

package/.claude/commands/reset-handoff.md

@@ -0,0 +1,59 @@
+# Reset Agent Handoff Workflow
+
+Reset the agent handoff system by cleaning up state files and logs.
+
+## What This Does
+
+Clears all handoff-related state files so you can start a fresh agent workflow:
+
+- Removes `.claude/handoff/NEXT_ACTION.json` (pending delegation context)
+- Clears handoff logs in `/tmp/test-driven-handoff.log` 
+- Resets any stuck delegation state
+- Prepares for clean workflow restart
+
+## Usage
+
+```bash
+# Remove handoff context files
+rm -f .claude/handoff/NEXT_ACTION.json
+
+# Clear handoff logs  
+> /tmp/test-driven-handoff.log
+
+# Optional: Clear any other temp handoff files
+rm -f .claude/handoff/*.json
+```
+
+## When to Use
+
+- **Stuck Handoffs**: When delegation gets stuck or loops
+- **Fresh Start**: Before beginning new agent workflow  
+- **Testing**: Between test runs to ensure clean state
+- **Debugging**: When investigating handoff issues
+
+## Files Cleaned
+
+- `.claude/handoff/NEXT_ACTION.json` - Current delegation context
+- `/tmp/test-driven-handoff.log` - Hook execution logs
+- `.claude/handoff/*.json` - Any other handoff state files
+
+## Safe Operation
+
+This only removes temporary state files, never:
+- TaskMaster data (`.taskmaster/tasks/`)
+- Agent definitions (`.claude/agents/`)
+- Hook scripts (`.claude/hooks/`)
+- Project files or code
+
+## Verification
+
+After reset, verify clean state:
+```bash
+ls .claude/handoff/     # Should be empty or not exist
+tail /tmp/test-driven-handoff.log  # Should be empty
+```
+
+Quick one-liner for complete reset:
+```bash
+rm -f .claude/handoff/*.json && > /tmp/test-driven-handoff.log && echo "Handoff workflow reset complete"
+```

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

@@ -0,0 +1,326 @@
+---
+description: Initialize Telos multi-agent system for this project
+---
+
+# Telos Initialization
+
+You are initializing the **Telos Framework** - a 9-level purpose-driven
+architecture for AI-assisted software development. Your role is to analyze this
+codebase, propose a complete hierarchy from ultimate purpose (L9) to code
+structure (L1), and generate all necessary files.
+
+## Step 1: Analyze Codebase
+
+Read and analyze the following to understand this project:
+
+### 1.1 Project Documentation
+
+- **README.md** - Extract:
+  - Project purpose and description
+  - Target users/beneficiaries
+  - Goals and success metrics
+  - Technology stack
+
+### 1.2 Package Configuration
+
+Check for and read (if exists):
+
+- **package.json** (Node.js) - Identify:
+  - Dependencies and frameworks (React, Express, Next.js, etc.)
+  - Dev dependencies (testing, linting, build tools)
+  - Scripts (test, lint, build commands)
+- **pyproject.toml** or **requirements.txt** (Python)
+- **Cargo.toml** (Rust)
+- **pom.xml** or **build.gradle** (Java)
+- **go.mod** (Go)
+
+### 1.3 Source Code Structure
+
+Scan the primary source directory:
+
+- Look for **src/**, **lib/**, **app/**, or similar
+- Identify:
+  - Component patterns (React components, Vue SFCs)
+  - API structure (routes, endpoints, controllers)
+  - Architectural patterns (MVC, microservices, monolith)
+  - Database integration (Prisma, Sequelize, MongoDB)
+
+### 1.4 Testing and Quality Tools
+
+Check for:
+
+- **Test frameworks**: Jest, Vitest, Pytest, RSpec, etc.
+- **Linters**: ESLint, Prettier, Ruff, Clippy, etc.
+- **Type checkers**: TypeScript, mypy, etc.
+
+### 1.5 Project State
+
+Run: `git status` to check if this is an active repository
+
+## Step 2: Propose Telos Hierarchy
+
+Based on your analysis, propose a complete 9-level hierarchy. Present it in a
+clear table:
+
+| Level  | Agent Name             | Purpose Statement                    | Reasoning                             |
+| ------ | ---------------------- | ------------------------------------ | ------------------------------------- |
+| **L9** | Telos-Guardian         | [Proposed ultimate purpose]          | [Why this is the ultimate purpose]    |
+| **L8** | Market-Analyst         | [Proposed business value]            | [Business outcomes this serves]       |
+| **L7** | Insight-Synthesizer    | [Proposed product strategy]          | [How it delivers user value]          |
+| **L6** | UX-Simulator           | [Proposed experience philosophy]     | [User experience principles]          |
+| **L5** | Journey-Validator      | [Proposed workflow validation]       | [User journey requirements]           |
+| **L4** | Integration-Contractor | [Proposed API/integration contracts] | [Based on detected APIs/integrations] |
+| **L3** | Component-Architect    | [Proposed component design]          | [Based on detected framework]         |
+| **L2** | Function-Author        | [Proposed function implementation]   | [Based on detected test framework]    |
+| **L1** | Syntax-Linter          | [Proposed code quality standard]     | [Based on detected linters]           |
+
+### Auto-generation Guidelines for L1-L4:
+
+**L1 (Syntax-Linter)** - Based on detected tools:
+
+- If ESLint found → "Ensure code passes ESLint strict mode with zero warnings"
+- If Prettier found → "Maintain consistent code formatting via Prettier"
+- If Ruff found (Python) → "Enforce Ruff linting rules for code quality"
+- If Clippy found (Rust) → "Pass all Clippy lints at deny level"
+
+**L2 (Function-Author)** - Based on test framework:
+
+- If Vitest found → "Write TDD functions with Vitest coverage >80%"
+- If Jest found → "Implement testable functions with Jest unit tests"
+- If Pytest found → "Write pure functions with pytest coverage"
+
+**L3 (Component-Architect)** - Based on framework:
+
+- If React found → "Design reusable React components following composition
+  patterns"
+- If Vue found → "Build modular Vue components with clear prop contracts"
+- If Flutter found → "Create widget hierarchies following Material/Cupertino
+  design"
+
+**L4 (Integration-Contractor)** - Based on detected APIs:
+
+- If Express found → "Maintain RESTful API contracts with OpenAPI docs"
+- If FastAPI found → "Define typed API endpoints with automatic validation"
+- If GraphQL found → "Maintain GraphQL schema contracts"
+
+## Step 3: User Review (Strategic Layers Only)
+
+After presenting the table, say:
+
+---
+**Strategic layers (L9-L5) define your project's purpose and require your input.**
+
+**Technical layers (L1-L4) are auto-generated based on your detected tooling:**
+- L1: [List detected linters]
+- L2: [List detected test frameworks]
+- L3: [List detected component frameworks]
+- L4: [List detected API frameworks]
+
+**Please review the strategic layers (L9-L5). Would you like to refine any of these?**
+
+Options:
+- "Accept all" - Proceed with generation
+- "Refine L9" - Edit ultimate purpose layer
+- "Refine L8" - Edit business value layer
+- "Refine all" - Walk through each strategic layer
+- "Restart" - Re-analyze with different focus
+---
+
+Wait for user response. If they want refinements, engage conversationally:
+
+- Ask for their vision for the specific layer
+- Propose updated purpose statement
+- Confirm before moving to next layer
+
+## Step 4: Generate Telos System
+
+Once the hierarchy is finalized, create the following files:
+
+### 4.1 Create `telos/content/TELOS.md`
+
+```markdown
+# Telos: Ultimate Purpose
+
+## Ultimate Purpose
+
+[L9 purpose statement]
+
+## Beneficiaries
+
+[Who benefits from this project - extracted from README or inferred]
+
+## Measurable Impact
+
+[Success metrics - extracted from README or project goals]
+
+## Ethical Constraints
+
+[Constraints on how purpose is achieved - inferred from domain]
+
+## 9-Level Hierarchy
+
+| Level | Agent                  | Purpose      |
+| ----- | ---------------------- | ------------ |
+| L9    | Telos-Guardian         | [L9 purpose] |
+| L8    | Market-Analyst         | [L8 purpose] |
+| L7    | Insight-Synthesizer    | [L7 purpose] |
+| L6    | UX-Simulator           | [L6 purpose] |
+| L5    | Journey-Validator      | [L5 purpose] |
+| L4    | Integration-Contractor | [L4 purpose] |
+| L3    | Component-Architect    | [L3 purpose] |
+| L2    | Function-Author        | [L2 purpose] |
+| L1    | Syntax-Linter          | [L1 purpose] |
+
+## Detected Technology Stack
+
+**Languages**: [Detected languages] **Frameworks**: [Detected frameworks]
+**Testing**: [Test frameworks] **Linting**: [Linters and formatters] **Build
+Tools**: [Build systems]
+
+## Initialization Metadata
+
+- **Initialized**: [Current date]
+- **AI Assistant**: Claude via Telos `/telos-init`
+- **Project Type**: [Inferred project type]
+```
+
+### 4.2 Create Agent Files
+
+For each level (L9 → L1), create `telos/agents/l[N]-[agent-name].md`:
+
+**Template structure:**
+
+```markdown
+# L[N]: [Agent Name]
+
+## Purpose
+
+[Purpose statement for this level]
+
+## Role
+
+[What this agent is responsible for]
+
+## Capabilities
+
+[What this agent can do]
+
+## Tools
+
+[List relevant tools based on detected stack]
+
+## Validation Criteria
+
+[How to verify this agent's output aligns with purpose]
+
+## Examples
+
+[2-3 examples of decisions this agent would make]
+```
+
+**Specific guidance per level:**
+
+**L9 (Telos-Guardian)**: Ultimate purpose keeper
+
+- Tools: Read access to all specs, ability to veto changes
+- Examples: Reject feature that violates core purpose
+
+**L8 (Market-Analyst)**: Business value measurer
+
+- Tools: Analytics, metrics dashboards, user feedback
+- Examples: Evaluate feature ROI against business goals
+
+**L7 (Insight-Synthesizer)**: Product strategist
+
+- Tools: User research, competitive analysis, roadmap planning
+- Examples: Prioritize features based on user insights
+
+**L6 (UX-Simulator)**: Experience designer
+
+- Tools: Figma, user testing, accessibility checkers
+- Examples: Ensure UI meets experience philosophy
+
+**L5 (Journey-Validator)**: Workflow verifier
+
+- Tools: E2E testing, user flow analysis, journey mapping
+- Examples: Validate checkout flow meets user expectations
+
+**L4 (Integration-Contractor)**: API contract enforcer
+
+- Tools: [Detected API tools - OpenAPI, GraphQL schema, etc.]
+- Examples: Ensure breaking changes follow versioning strategy
+
+**L3 (Component-Architect)**: UI component designer
+
+- Tools: [Detected framework - React, Vue, etc.], Storybook
+- Examples: Design reusable button component following design system
+
+**L2 (Function-Author)**: Function implementer
+
+- Tools: [Detected test framework], code coverage tools
+- Examples: Write TDD function with 100% coverage
+
+**L1 (Syntax-Linter)**: Code quality enforcer
+
+- Tools: [Detected linters - ESLint, Prettier, etc.]
+- Examples: Reject PR with linting errors
+
+### 4.3 Create Platform Integration
+
+If `.claude/` exists, create:
+
+- `AGENTS.md` - Reference to Telos hierarchy
+- Update `CLAUDE.md` (if exists) with Telos instructions
+
+If `.opencode/` exists, do the same in that directory.
+
+### 4.4 Create Orchestrator (Optional)
+
+If JavaScript/Node.js project, create `logos/orchestrator.js`:
+
+```javascript
+// Telos-Logos orchestrator
+// Routes requests to appropriate L1-L9 agents
+
+const hierarchy = [
+  { level: 9, name: "telos-guardian", role: "ultimate-purpose" },
+  { level: 8, name: "market-analyst", role: "business-value" },
+  // ... all 9 levels
+];
+
+module.exports = { hierarchy };
+```
+
+## Step 5: Completion
+
+Once all files are generated, display:
+
+---
+✅ **Telos initialization complete!**
+
+**Generated files:**
+- `telos/content/TELOS.md` - Ultimate purpose and hierarchy
+- `telos/agents/l9-telos-guardian.md` through `l1-syntax-linter.md`
+- `AGENTS.md` - Agent reference guide
+- `logos/orchestrator.js` - Request router (if applicable)
+
+**Next steps:**
+1. Review the generated agent definitions in `telos/agents/`
+2. Run `/telos-validate` to check alignment with current codebase
+3. Run `/telos-status` to see current configuration
+4. Start developing with purpose-driven AI assistance!
+
+**Slash commands available:**
+- `/telos-validate` - Check if current code aligns with Telos
+- `/telos-status` - Show current Telos configuration
+- `/telos-reset` - Clear and reinitialize
+---
+
+## Tips
+
+- If README is missing or vague, ask user for clarification before proposing L9
+- If no testing framework detected, suggest adding one in L2
+- If no linter detected, suggest adding one in L1
+- For empty/greenfield projects, ask user for project vision before proposing
+  hierarchy
+- Be conversational and collaborative - this is a dialogue, not a survey

package/.claude/commands/telos/quick.md

@@ -0,0 +1,90 @@
+---
+description: Quick Telos initialization with auto-accepted AI proposals
+---
+
+# Telos Quick Initialization
+
+This is the fast-track initialization mode that accepts all AI-proposed
+hierarchy levels without user review. Use this when you trust the AI analysis
+and want to get started immediately.
+
+## Process
+
+1. **Analyze codebase** (same as `/telos-init`)
+2. **Propose hierarchy** (auto-accept without showing to user)
+3. **Generate all files** immediately
+4. **Show summary** of what was created
+
+## Step 1: Silent Analysis
+
+Perform the same analysis as `/telos-init`:
+
+- Read README.md
+- Check package.json / pyproject.toml / Cargo.toml
+- Scan src/ or lib/ directory
+- Detect testing and linting tools
+- Check git status
+
+## Step 2: Auto-Generate Hierarchy
+
+Generate the 9-level hierarchy without user interaction:
+
+**L9-L5 (Strategic)**: Infer from README and project description **L4-L1
+(Technical)**: Auto-generate from detected tools
+
+Do NOT ask for user review - proceed directly to generation.
+
+## Step 3: Generate Files
+
+Create all files exactly as specified in `/telos-init` Step 4:
+
+- `telos/content/TELOS.md`
+- `telos/agents/l9-telos-guardian.md` through `l1-syntax-linter.md`
+- `AGENTS.md` (if `.claude/` or `.opencode/` exists)
+- `logos/orchestrator.js` (if Node.js project)
+
+## Step 4: Display Summary
+
+Once complete, show:
+
+---
+⚡ **Telos quick initialization complete!**
+
+**Generated hierarchy:**
+
+| Level | Agent | Purpose |
+|-------|-------|---------|
+| L9 | Telos-Guardian | [Purpose] |
+| L8 | Market-Analyst | [Purpose] |
+| L7 | Insight-Synthesizer | [Purpose] |
+| L6 | UX-Simulator | [Purpose] |
+| L5 | Journey-Validator | [Purpose] |
+| L4 | Integration-Contractor | [Purpose] |
+| L3 | Component-Architect | [Purpose] |
+| L2 | Function-Author | [Purpose] |
+| L1 | Syntax-Linter | [Purpose] |
+
+**Files created:**
+- `telos/content/TELOS.md`
+- `telos/agents/` (9 agent definitions)
+- `AGENTS.md`
+- `logos/orchestrator.js` (if applicable)
+
+**Not satisfied?** Run `/telos-reset` then `/telos-init` for interactive mode.
+---
+
+## When to Use Quick Mode
+
+✅ **Use quick mode when:**
+
+- Starting a new project with clear conventions
+- The codebase already has comprehensive README
+- You trust AI inference for strategic purpose
+- You want to iterate quickly and refine later
+
+❌ **Use full `/telos-init` when:**
+
+- Project has unique or nuanced purpose
+- Strategic direction needs human input
+- Multiple stakeholders need alignment
+- Initial setup must be perfect

package/.claude/commands/telos/reset.md

@@ -0,0 +1,100 @@
+---
+description: Clear existing Telos installation and reinitialize
+---
+
+# Telos Reset
+
+This command removes all existing Telos configuration and allows you to start
+fresh.
+
+## What Gets Removed
+
+This command will **delete** the following:
+
+- `telos/content/TELOS.md`
+- `telos/agents/` directory (all L1-L9 agent files)
+- `logos/orchestrator.js` (if present)
+- Telos sections in `AGENTS.md` and `CLAUDE.md` (if present)
+
+## Safety Check
+
+Before proceeding, ask the user:
+
+---
+⚠️  **Warning: This will delete all Telos configuration files.**
+
+**Files to be removed:**
+- `telos/content/TELOS.md`
+- `telos/agents/l1-*.md` through `l9-*.md`
+- `logos/orchestrator.js`
+- Telos references in AGENTS.md / CLAUDE.md
+
+**Are you sure you want to reset?** (yes/no)
+---
+
+If user responds "no" or anything other than "yes", abort with message: "Reset
+cancelled. Your Telos configuration is unchanged."
+
+## Reset Process
+
+If user confirms "yes":
+
+### Step 1: Remove Files
+
+Delete the following files (if they exist):
+
+```bash
+rm -rf telos/content/TELOS.md
+rm -rf telos/agents/
+rm -rf logos/orchestrator.js
+```
+
+### Step 2: Clean Memory Files
+
+If `AGENTS.md` exists:
+
+- Remove any sections with headers containing "Telos" or "L1-L9"
+- Keep all other content intact
+
+If `CLAUDE.md` exists:
+
+- Remove any sections referencing Telos
+- Keep all other project-specific content
+
+### Step 3: Clean State
+
+Remove any initialization state files:
+
+```bash
+rm -f .telos-init-state.json
+```
+
+### Step 4: Confirm Completion
+
+Display:
+
+---
+✅ **Telos reset complete.**
+
+**Removed:**
+- All Telos content and agent files
+- Telos references in AGENTS.md / CLAUDE.md
+- Initialization state
+
+**Next steps:**
+- Run `/telos-init` for full interactive setup
+- Run `/telos-quick` for fast auto-generation
+- Run `telos init` (CLI) to reinstall slash commands if needed
+---
+
+## Edge Cases
+
+**If no Telos files found:** Display: "No Telos installation detected. Nothing
+to reset."
+
+**If only partial installation found:** Remove what exists and notify: "Partial
+Telos installation found. Removed existing files. Run `/telos-init` to complete
+setup."
+
+**If git repository has uncommitted Telos files:** Warn: "You have uncommitted
+Telos files. Consider running `git status` before resetting."