telos-framework 0.3.0 → 0.3.2

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

@@ -59,20 +59,94 @@ 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]           |
+Based on your analysis, propose a complete 9-level hierarchy. Present it using
+this block format:
+
+```
+═══════════════════════════════════════════════════════════════════════════
+                          PROPOSED TELOS HIERARCHY
+═══════════════════════════════════════════════════════════════════════════
+
+───────────────────────────────────────────────────────────────────────────
+L9 - Telos-Guardian (Ultimate Purpose)
+───────────────────────────────────────────────────────────────────────────
+Purpose: [Proposed ultimate purpose statement]
+
+Reasoning: [Why this is the ultimate purpose - based on README, project 
+description, and inferred mission]
+───────────────────────────────────────────────────────────────────────────
+
+───────────────────────────────────────────────────────────────────────────
+L8 - Market-Analyst (Business Value)
+───────────────────────────────────────────────────────────────────────────
+Purpose: [Proposed business value statement]
+
+Reasoning: [Business outcomes this project serves - based on metrics, KPIs,
+or market positioning mentioned in docs]
+───────────────────────────────────────────────────────────────────────────
+
+───────────────────────────────────────────────────────────────────────────
+L7 - Insight-Synthesizer (Product Strategy)
+───────────────────────────────────────────────────────────────────────────
+Purpose: [Proposed product strategy statement]
+
+Reasoning: [How it delivers user value - based on features, roadmap, or
+user-facing goals]
+───────────────────────────────────────────────────────────────────────────
+
+───────────────────────────────────────────────────────────────────────────
+L6 - UX-Simulator (Experience Philosophy)
+───────────────────────────────────────────────────────────────────────────
+Purpose: [Proposed UX philosophy statement]
+
+Reasoning: [User experience principles - based on UI framework, design
+system, or accessibility mentions]
+───────────────────────────────────────────────────────────────────────────
+
+───────────────────────────────────────────────────────────────────────────
+L5 - Journey-Validator (Workflow Validation)
+───────────────────────────────────────────────────────────────────────────
+Purpose: [Proposed workflow validation statement]
+
+Reasoning: [User journey requirements - based on E2E tests, integration
+tests, or workflow documentation]
+───────────────────────────────────────────────────────────────────────────
+
+───────────────────────────────────────────────────────────────────────────
+L4 - Integration-Contractor (API Contracts)
+───────────────────────────────────────────────────────────────────────────
+Purpose: [Proposed API contract statement]
+
+Reasoning: [Based on detected API frameworks, protocols, and integration
+patterns]
+───────────────────────────────────────────────────────────────────────────
+
+───────────────────────────────────────────────────────────────────────────
+L3 - Component-Architect (Component Design)
+───────────────────────────────────────────────────────────────────────────
+Purpose: [Proposed component architecture statement]
+
+Reasoning: [Based on detected UI framework, component patterns, and
+architectural choices]
+───────────────────────────────────────────────────────────────────────────
+
+───────────────────────────────────────────────────────────────────────────
+L2 - Function-Author (Function Implementation)
+───────────────────────────────────────────────────────────────────────────
+Purpose: [Proposed function implementation statement]
+
+Reasoning: [Based on detected test framework, testing strategy, and code
+coverage requirements]
+───────────────────────────────────────────────────────────────────────────
+
+───────────────────────────────────────────────────────────────────────────
+L1 - Syntax-Linter (Code Quality)
+───────────────────────────────────────────────────────────────────────────
+Purpose: [Proposed code quality statement]
+
+Reasoning: [Based on detected linters, formatters, and quality standards]
+═══════════════════════════════════════════════════════════════════════════
+```
 
 ### Auto-generation Guidelines for L1-L4:
 
@@ -136,7 +210,7 @@ Wait for user response. If they want refinements, engage conversationally:
 
 Once the hierarchy is finalized, create the following files:
 
-### 4.1 Create `telos/content/TELOS.md`
+### 4.1 Create `.telos/TELOS.md`
 
 ```markdown
 # Telos: Ultimate Purpose
@@ -186,7 +260,7 @@ Tools**: [Build systems]
 
 ### 4.2 Create Agent Files
 
-For each level (L9 → L1), create `telos/agents/l[N]-[agent-name].md`:
+For each level (L9 → L1), create `..telos/agents/l[N]-[agent-name].md`:
 
 **Template structure:**
 
@@ -265,14 +339,58 @@ For each level (L9 → L1), create `telos/agents/l[N]-[agent-name].md`:
 - Tools: [Detected linters - ESLint, Prettier, etc.]
 - Examples: Reject PR with linting errors
 
-### 4.3 Create Platform Integration
+### 4.3 Integrate with AI Assistant Configuration Files
+
+Check for and update existing AI assistant configuration files to reference
+`.telos/TELOS.md`:
+
+**Files to check:**
+
+- `AGENTS.md` - Unified standard (if exists, prepend Telos reference)
+- `CLAUDE.md` - Claude Code (if exists, prepend Telos reference)
+- `.cursorrules` - Cursor IDE (if exists, prepend Telos reference)
+- `.clinerules` - Cline/VS Code (if exists, prepend Telos reference)
+- `.windsurfrules` - Windsurf IDE (if exists, prepend Telos reference)
+- `.roo/config` or `.roocode` - Roo Code (if exists, prepend Telos reference)
+- `GEMINI.md` - Google Gemini (if exists, prepend Telos reference)
+
+**For each existing file, prepend this instruction:**
+
+```markdown
+## Telos Purpose Hierarchy
 
-If `.claude/` exists, create:
+**IMPORTANT**: Before making any significant changes to this project, consult
+the Telos purpose hierarchy defined in `.telos/TELOS.md`. This file contains the
+9-level purpose structure (L9: Ultimate Purpose → L1: Code Quality) that guides
+all development decisions.
 
-- `AGENTS.md` - Reference to Telos hierarchy
-- Update `CLAUDE.md` (if exists) with Telos instructions
+**When to reference Telos:**
 
-If `.opencode/` exists, do the same in that directory.
+- Before implementing new features (check L9-L5 strategic alignment)
+- Before refactoring code (ensure L1-L4 technical standards are maintained)
+- When resolving conflicts between requirements (appeal to higher-level purpose)
+- During code review (validate against appropriate agent level)
+
+**Quick reference:**
+
+- L9 (Telos-Guardian): Ultimate purpose - does this serve our mission?
+- L8 (Market-Analyst): Business value - does this deliver measurable outcomes?
+- L7 (Insight-Synthesizer): Product strategy - does this align with our roadmap?
+- L6 (UX-Simulator): Experience - does this meet UX standards?
+- L5 (Journey-Validator): Workflows - do user journeys work end-to-end?
+- L4 (Integration-Contractor): API contracts - are integrations maintained?
+- L3 (Component-Architect): Components - does this follow our patterns?
+- L2 (Function-Author): Functions - is this testable and maintainable?
+- L1 (Syntax-Linter): Code quality - does this pass linting/formatting?
+
+See `.telos/TELOS.md` for complete hierarchy and `..telos/agents/` for detailed
+agent definitions.
+
+---
+```
+
+**If no AI assistant config files exist**, create `AGENTS.md` with Telos
+content.
 
 ### 4.4 Create Orchestrator (Optional)
 
@@ -299,17 +417,21 @@ 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
+- `.telos/TELOS.md` - Ultimate purpose and hierarchy
+- `..telos/agents/l9-telos-guardian.md` through `l1-syntax-linter.md`
+- Updated AI assistant config files (AGENTS.md, CLAUDE.md, .cursorrules, etc.)
 - `logos/orchestrator.js` - Request router (if applicable)
 
 **Next steps:**
-1. Review the generated agent definitions in `telos/agents/`
+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!
 
+**Your AI assistant now knows about Telos!** All existing config files (AGENTS.md,
+CLAUDE.md, .cursorrules, etc.) have been updated to reference `.telos/TELOS.md`
+before making changes.
+
 **Slash commands available:**
 - `/telos-validate` - Check if current code aligns with Telos
 - `/telos-status` - Show current Telos configuration

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

@@ -38,8 +38,8 @@ Do NOT ask for user review - proceed directly to generation.
 
 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`
+- `.telos/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)
 
@@ -65,8 +65,8 @@ Once complete, show:
 | L1 | Syntax-Linter | [Purpose] |
 
 **Files created:**
-- `telos/content/TELOS.md`
-- `telos/agents/` (9 agent definitions)
+- `.telos/TELOS.md`
+- `.telos/agents/` (9 agent definitions)
 - `AGENTS.md`
 - `logos/orchestrator.js` (if applicable)
 

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

@@ -11,8 +11,8 @@ fresh.
 
 This command will **delete** the following:
 
-- `telos/content/TELOS.md`
-- `telos/agents/` directory (all L1-L9 agent files)
+- `.telos/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)
 
@@ -24,8 +24,8 @@ 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`
+- `.telos/TELOS.md`
+- `.telos/agents/l1-*.md` through `l9-*.md`
 - `logos/orchestrator.js`
 - Telos references in AGENTS.md / CLAUDE.md
 
@@ -44,8 +44,8 @@ If user confirms "yes":
 Delete the following files (if they exist):
 
 ```bash
-rm -rf telos/content/TELOS.md
-rm -rf telos/agents/
+rm -rf .telos/TELOS.md
+rm -rf .telos/agents/
 rm -rf logos/orchestrator.js
 ```
 

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

@@ -10,8 +10,8 @@ Display the current Telos configuration for this project.
 
 First, check if Telos is initialized:
 
-- Look for `telos/content/TELOS.md`
-- Look for `telos/agents/` directory
+- Look for `.telos/TELOS.md`
+- Look for `.telos/agents/` directory
 
 If not found, display:
 
@@ -27,7 +27,7 @@ If Telos is initialized, read and display:
 
 ### 1. Ultimate Purpose
 
-From `telos/content/TELOS.md`, extract and display:
+From `.telos/TELOS.md`, extract and display:
 
 ```
 🎯 **Ultimate Purpose (L9)**
@@ -55,7 +55,7 @@ Display all 9 levels:
 
 ### 3. Technology Stack
 
-From `telos/content/TELOS.md`, show detected stack:
+From `.telos/TELOS.md`, show detected stack:
 
 ```
 **Technology Stack**

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

@@ -11,8 +11,8 @@ purpose hierarchy.
 
 Check if Telos is initialized:
 
-- `telos/content/TELOS.md` must exist
-- At least some agent files in `telos/agents/` must exist
+- `.telos/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."
 
@@ -20,7 +20,7 @@ If not found, display: "❌ Telos not initialized. Run `/telos-init` first."
 
 ### Step 1: Load Telos Configuration
 
-Read `telos/content/TELOS.md` to extract:
+Read `.telos/TELOS.md` to extract:
 
 - Ultimate purpose (L9)
 - 9-level hierarchy definitions

package/lib/commands/init.js

@@ -60,7 +60,9 @@ async function initCommand(options) {
     console.log(chalk.bold.white('Next steps:\n'));
     console.log(chalk.white('1. Open this project in Claude Code (or your AI coding assistant)'));
     console.log(chalk.white('2. Run the slash command: ') + chalk.bold.green('/telos-init'));
-    console.log(chalk.white('3. Follow the interactive setup to configure your purpose hierarchy\n'));
+    console.log(chalk.white('3. AI will analyze your codebase and propose a 9-level purpose hierarchy'));
+    console.log(chalk.white('4. Review strategic layers (L9-L5) and provide refinements'));
+    console.log(chalk.white('5. AI generates .telos/TELOS.md and updates your config files\n'));
 
     console.log(chalk.dim('Available commands after initialization:'));
     console.log(chalk.dim('  /telos-init     - Initialize Telos with interactive review'));

package/package.json

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

package/templates/AGENTS.md

@@ -13,32 +13,32 @@ specialized agent.
 
 These agents handle high-level purpose, strategy, and user experience:
 
-- **L9: Telos-Guardian** (`telos/agents/l9-telos-guardian.md`) - Ultimate
+- **L9: Telos-Guardian** (`.telos/agents/l9-telos-guardian.md`) - Ultimate
   purpose keeper
-- **L8: Market-Analyst** (`telos/agents/l8-market-analyst.md`) - Business value
+- **L8: Market-Analyst** (`.telos/agents/l8-market-analyst.md`) - Business value
   measurer
-- **L7: Insight-Synthesizer** (`telos/agents/l7-insight-synthesizer.md`) -
+- **L7: Insight-Synthesizer** (`.telos/agents/l7-insight-synthesizer.md`) -
   Product strategist
-- **L6: UX-Simulator** (`telos/agents/l6-ux-simulator.md`) - Experience designer
-- **L5: Journey-Validator** (`telos/agents/l5-journey-validator.md`) - Workflow
+- **L6: UX-Simulator** (`.telos/agents/l6-ux-simulator.md`) - Experience designer
+- **L5: Journey-Validator** (`.telos/agents/l5-journey-validator.md`) - Workflow
   verifier
 
 ### Technical Layers (L4-L1)
 
 These agents handle implementation details and code quality:
 
-- **L4: Integration-Contractor** (`telos/agents/l4-integration-contractor.md`) -
+- **L4: Integration-Contractor** (`.telos/agents/l4-integration-contractor.md`) -
   API contract enforcer
-- **L3: Component-Architect** (`telos/agents/l3-component-architect.md`) -
+- **L3: Component-Architect** (`.telos/agents/l3-component-architect.md`) -
   Component designer
-- **L2: Function-Author** (`telos/agents/l2-function-author.md`) - Function
+- **L2: Function-Author** (`.telos/agents/l2-function-author.md`) - Function
   implementer
-- **L1: Syntax-Linter** (`telos/agents/l1-syntax-linter.md`) - Code quality
+- **L1: Syntax-Linter** (`.telos/agents/l1-syntax-linter.md`) - Code quality
   enforcer
 
 ## Telos-Logos System
 
-**Telos** (purpose) is defined in `telos/content/TELOS.md` - the ultimate goal
+**Telos** (purpose) is defined in `.telos/TELOS.md` - the ultimate goal
 this project serves.
 
 **Logos** (logic) is managed by the orchestrator in `logos/orchestrator.js` -

package/templates/CLAUDE.md

@@ -6,10 +6,10 @@ This project uses the **Telos Framework** for purpose-driven development.
 
 1. **Check Telos hierarchy**: Run `/telos-status` to see the 9-level purpose
    structure
-2. **Understand the purpose**: Read `telos/content/TELOS.md` for ultimate
+2. **Understand the purpose**: Read `.telos/TELOS.md` for ultimate
    project goals
 3. **Consult the right agent**: Check the appropriate agent definition in
-   `telos/agents/`
+   `.telos/agents/`
 
 ## Agent Responsibilities
 
@@ -17,15 +17,15 @@ When working on different types of tasks, reference the corresponding agent:
 
 | Task Type                   | Consult Agent               | File                                        |
 | --------------------------- | --------------------------- | ------------------------------------------- |
-| Project direction decisions | Telos-Guardian (L9)         | `telos/agents/l9-telos-guardian.md`         |
-| Business value questions    | Market-Analyst (L8)         | `telos/agents/l8-market-analyst.md`         |
-| Product strategy            | Insight-Synthesizer (L7)    | `telos/agents/l7-insight-synthesizer.md`    |
-| UX/design decisions         | UX-Simulator (L6)           | `telos/agents/l6-ux-simulator.md`           |
-| User workflow validation    | Journey-Validator (L5)      | `telos/agents/l5-journey-validator.md`      |
-| API changes                 | Integration-Contractor (L4) | `telos/agents/l4-integration-contractor.md` |
-| Component design            | Component-Architect (L3)    | `telos/agents/l3-component-architect.md`    |
-| Function implementation     | Function-Author (L2)        | `telos/agents/l2-function-author.md`        |
-| Code quality                | Syntax-Linter (L1)          | `telos/agents/l1-syntax-linter.md`          |
+| Project direction decisions | Telos-Guardian (L9)         | `.telos/agents/l9-telos-guardian.md`         |
+| Business value questions    | Market-Analyst (L8)         | `.telos/agents/l8-market-analyst.md`         |
+| Product strategy            | Insight-Synthesizer (L7)    | `.telos/agents/l7-insight-synthesizer.md`    |
+| UX/design decisions         | UX-Simulator (L6)           | `.telos/agents/l6-ux-simulator.md`           |
+| User workflow validation    | Journey-Validator (L5)      | `.telos/agents/l5-journey-validator.md`      |
+| API changes                 | Integration-Contractor (L4) | `.telos/agents/l4-integration-contractor.md` |
+| Component design            | Component-Architect (L3)    | `.telos/agents/l3-component-architect.md`    |
+| Function implementation     | Function-Author (L2)        | `.telos/agents/l2-function-author.md`        |
+| Code quality                | Syntax-Linter (L1)          | `.telos/agents/l1-syntax-linter.md`          |
 
 ## Validation