telos-framework 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Telos Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,245 @@
+# Telos: Purpose-Driven Multi-Agent Development Framework
+
+A philosophically-grounded AI collective that embeds Aristotelian purpose
+hierarchy into software development. Every line of code serves your ultimate
+mission.
+
+## Philosophy
+
+**Telos** (Greek: τέλος) means "end," "purpose," or "goal"—the ultimate reason
+something exists.
+
+**Logos** (Greek: λόγος) means "reason," "discourse," or "rational
+principle"—the organizing intelligence that maintains coherent order.
+
+Most development tools focus on _how_ to code. Telos ensures you're building the
+_right_ thing by maintaining alignment between implementation and purpose across
+nine levels of abstraction—from syntax to transcendent meaning.
+
+Based on Kenneth Boulding's hierarchy of system complexity, Telos orchestrates
+specialized AI agents that operate coherently from low-level linting to
+strategic vision. The **Logos orchestrator** uses rational discourse to maintain
+top-down purpose alignment and bottom-up validation.
+
+## Architecture
+
+### The Nine Levels
+
+```
+L9: Telos-Guardian      → Strategic alignment with ultimate purpose
+L8: Market-Analyst      → Business metrics and KPIs
+L7: Insight-Synthesizer → User feedback and behavioral analytics
+L6: UX-Simulator        → User experience and accessibility
+L5: Journey-Validator   → End-to-end workflows and integration
+L4: Integration-Contractor → API contracts and service boundaries
+L3: Component-Architect → Component design and composition
+L2: Function-Author     → Unit logic and TDD
+L1: Syntax-Linter       → Code structure and formatting
+```
+
+### Logos Orchestrator
+
+The central orchestration engine implementing:
+
+- **Top-down decomposition**: Strategic goals cascade into tactical specs
+- **Bottom-up validation**: Implementation validates against purpose
+- **Middle-out reconciliation**: Conflicts resolved through rational dialogue
+- **Spec-driven workflow**: All changes flow through OpenSpec proposals
+
+## Installation
+
+```bash
+npx telos-framework init
+```
+
+Or install globally:
+
+```bash
+npm install -g telos-framework
+telos init
+```
+
+## Quick Start
+
+### 1. Initialize Your Project
+
+```bash
+cd your-project
+telos init
+```
+
+The interactive initialization will:
+
+- Capture your project's ultimate purpose (Telos)
+- Decompose it into a 9-level hierarchy
+- Discover available tools and MCP servers
+- Generate adapted agent definitions
+- Create platform-specific configurations
+
+### 2. Start Development
+
+Your AI assistants now operate as a coherent multi-agent collective:
+
+```
+User: "Add user authentication"
+  ↓
+L9 Telos-Guardian: Validates alignment with project purpose
+  ↓
+L8 Market-Analyst: Defines success metrics
+  ↓
+... (decomposition cascade)
+  ↓
+L2 Function-Author: Implements with TDD
+  ↓
+L1 Syntax-Linter: Ensures code quality
+  ↓
+(Bottom-up validation confirms alignment)
+```
+
+### 3. Validate Alignment
+
+```bash
+telos validate
+```
+
+Check that all work traces back to your ultimate Telos.
+
+## Features
+
+### Adaptive Tool Integration
+
+Telos discovers and integrates your existing tools:
+
+- Linters (ESLint, Ruff, etc.)
+- Test frameworks (Vitest, Jest, Playwright)
+- Analytics (PostHog, Amplitude)
+- MCP servers
+- Custom tooling
+
+### Multi-Platform Support
+
+Works with:
+
+- Claude (Code, Projects)
+- Cursor
+- GitHub Copilot
+- Google Gemini
+- Any AI coding assistant
+
+Single source of truth with platform-specific symlinks—no duplication.
+
+### OpenSpec Integration
+
+Full integration with [OpenSpec](https://openspec.dev) workflow:
+
+- Logos creates proposals for changes
+- Agents work through specs and tasks
+- Validation uses OpenSpec archive
+- Telos lineage tracked throughout
+
+### Technical Agent Delegation
+
+9-level agents can delegate to specialized technical agents from
+[Claude Collective](https://github.com/alan-colver/claude-code-collective):
+
+- `research-agent` for technical investigation
+- `quality-agent` for comprehensive reviews
+- `testing-implementation-agent` for test suites
+- `devops-agent` for deployment
+- And more specialized agents
+
+## Commands
+
+```bash
+telos init              # Initialize Telos in your project
+telos status            # Show current configuration
+telos rediscover        # Update tool detection
+telos validate          # Check Telos alignment
+telos --help            # Show all commands
+```
+
+## Project Structure
+
+After initialization:
+
+```
+your-project/
+├── telos/
+│   ├── content/
+│   │   ├── TELOS.md         # Your project's purpose hierarchy
+│   │   ├── AGENTS.md        # Consolidated agent definitions
+│   │   ├── LOGOS.md         # Orchestrator instructions
+│   │   └── TOOLS.md         # Tool registry and mappings
+│   ├── agents/              # Individual agent definitions (L1-L9)
+│   └── templates/           # Platform-specific configs
+├── .telos/                  # Runtime state (gitignored)
+├── TELOS.md                 # Symlink for visibility
+└── [platform symlinks]      # CLAUDE.md, .cursor/rules/, etc.
+```
+
+## Philosophy & Theory
+
+### Why Hierarchical Agents?
+
+Flat agent collectives lack governance—agents can work at cross-purposes.
+Hierarchical organization with clear level boundaries ensures:
+
+- Strategic coherence (top-down)
+- Implementation integrity (bottom-up)
+- Efficient specialization (right tool, right level)
+
+### Why Telos?
+
+Without explicit purpose capture, AI assistants optimize for immediate requests,
+not ultimate goals. Telos makes purpose explicit and traceable, enabling:
+
+- Alignment validation at every level
+- Conflict resolution through purpose appeal
+- Emergent strategic consistency
+
+### Why Logos?
+
+Unstructured agent communication devolves into noise. Logos enforces rational
+discourse through:
+
+- Spec-driven dialogue (OpenSpec format)
+- Structured reporting protocols
+- Level-appropriate context filtering
+
+## Examples
+
+See `/examples` for:
+
+- Simple web app initialization
+- Existing codebase integration
+- Multi-platform usage demonstration
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute to this project.
+
+## Philosophy Deep Dive
+
+See [PHILOSOPHY.md](PHILOSOPHY.md) for comprehensive explanation of:
+
+- Aristotelian teleology in software
+- Boulding's hierarchy applied to development
+- Logos as rational agent orchestration
+- Ontological levels and emergence
+
+## Troubleshooting
+
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues and solutions.
+
+## License
+
+MIT License - see [LICENSE](LICENSE)
+
+---
+
+**Transform AI-assisted development from reactive tool usage to coherent,
+purpose-aligned creation.**
+
+[GitHub Repository](https://github.com/telos-framework/telos) |
+[Documentation](https://telos-framework.dev) |
+[Report Issues](https://github.com/telos-framework/telos/issues)

package/USAGE.md

@@ -0,0 +1,337 @@
+# Telos CLI Usage Guide
+
+## Commands
+
+### `telos init`
+
+Initialize Telos in your project with interactive discovery.
+
+```bash
+telos init [options]
+```
+
+**Options:**
+
+- `-q, --quick` - Quick initialization with sensible defaults (skips interactive
+  prompts)
+- `-v, --verbose` - Show detailed output during initialization
+
+**What it does:**
+
+1. **Phase 1: Telos Discovery** - Interactive questions to capture your
+   project's ultimate purpose
+2. **Phase 2: Project Scan** - Detects languages, frameworks, and existing code
+3. **Phase 3: Tool Discovery** - Finds available MCP servers and development
+   tools
+4. **Phase 4: Agent Generation** - Creates 9 specialized agents adapted to your
+   tools
+5. **Phase 5: Platform Setup** - Configures symlinks for your AI platform
+   (Claude, Cursor, etc.)
+
+**Example:**
+
+```bash
+# Interactive initialization
+telos init
+
+# Quick start with defaults
+telos init --quick
+
+# Verbose output
+telos init --verbose
+```
+
+---
+
+### `telos status`
+
+Show current Telos configuration and initialization status.
+
+```bash
+telos status [options]
+```
+
+**Options:**
+
+- `-v, --verbose` - Show detailed configuration including Telos hierarchy
+  preview
+
+**What it shows:**
+
+- Initialization status
+- Number of agents configured
+- Number of tools discovered
+- Platform configuration
+- Initialization timestamp
+
+**Example:**
+
+```bash
+# Basic status
+telos status
+
+# Detailed status with Telos preview
+telos status --verbose
+```
+
+---
+
+### `telos rediscover`
+
+Re-run tool discovery and update agent configurations.
+
+Use this command after:
+
+- Installing new development tools
+- Adding new MCP servers
+- Changing project dependencies
+
+```bash
+telos rediscover [options]
+```
+
+**Options:**
+
+- `-v, --verbose` - Show detailed discovery output
+
+**What it does:**
+
+1. Re-scans project for languages and frameworks
+2. Re-discovers MCP servers
+3. Updates tool mappings
+4. Regenerates TOOLS.md
+5. Updates agent configurations with new tools
+
+**Example:**
+
+```bash
+# Rediscover tools
+telos rediscover
+
+# Verbose rediscovery
+telos rediscover --verbose
+```
+
+---
+
+### `telos validate`
+
+Validate Telos alignment across the project.
+
+```bash
+telos validate [options]
+```
+
+**Options:**
+
+- `-v, --verbose` - Show detailed validation results
+
+**What it validates:**
+
+- Telos hierarchy structure (L9 → L1)
+- Agent definitions (all 9 agents present)
+- Tool configuration (TOOLS.md exists)
+- Platform setup (AGENTS.md and symlinks)
+
+**Example:**
+
+```bash
+# Run validation
+telos validate
+
+# Detailed validation
+telos validate --verbose
+```
+
+**Exit codes:**
+
+- `0` - All validations passed
+- `1` - One or more validations failed
+
+---
+
+## Typical Workflows
+
+### First-Time Setup
+
+```bash
+# Clone telos into your project
+cd your-project
+git clone https://github.com/yourusername/telos.git .telos-framework
+cd .telos-framework
+
+# Initialize with interactive discovery
+npm install
+npm link
+cd ..
+telos init
+
+# Check status
+telos status
+```
+
+### Quick Setup (Existing Project)
+
+```bash
+cd your-project
+telos init --quick
+telos validate
+```
+
+### Adding New Tools
+
+```bash
+# Install new tool (e.g., Playwright)
+npm install -D @playwright/test
+
+# Rediscover tools
+telos rediscover
+
+# Verify update
+telos status
+```
+
+### Continuous Validation
+
+```bash
+# Add to your CI/CD pipeline
+telos validate || exit 1
+```
+
+---
+
+## Configuration Files
+
+After initialization, Telos creates:
+
+```
+your-project/
+├── .telos/
+│   ├── config.json          # Runtime configuration
+│   └── state.json           # Orchestrator state
+├── telos/
+│   ├── content/
+│   │   ├── TELOS.md        # Purpose hierarchy
+│   │   ├── AGENTS.md       # Consolidated agents
+│   │   ├── LOGOS.md        # Orchestrator docs
+│   │   └── TOOLS.md        # Tool inventory
+│   └── agents/
+│       ├── l1-syntax-linter.md
+│       ├── l2-function-author.md
+│       └── ... (9 total)
+└── TELOS.md                 # Symlink to telos/content/TELOS.md
+```
+
+---
+
+## Getting Help
+
+```bash
+# Show all commands
+telos --help
+
+# Show command-specific help
+telos init --help
+telos status --help
+telos rediscover --help
+telos validate --help
+```
+
+---
+
+## Troubleshooting
+
+### Telos Not Initialized
+
+**Error:** `✗ Telos not initialized`
+
+**Solution:**
+
+```bash
+telos init
+```
+
+### Tool Discovery Issues
+
+**Error:** Tools not being detected
+
+**Solution:**
+
+```bash
+# Ensure package.json exists
+# Install tools via package manager
+npm install -D eslint vitest
+
+# Rediscover
+telos rediscover
+```
+
+### Validation Failures
+
+**Error:** `✗ Agent Definitions`
+
+**Solution:**
+
+```bash
+# Re-run initialization
+telos init
+
+# Or regenerate agents
+telos rediscover
+```
+
+### Platform Symlink Issues (Windows)
+
+**Error:** Symlinks not working on Windows
+
+**Solution:**
+
+- Run terminal as Administrator
+- Or use directory junctions (automatically attempted)
+- Or manually copy `telos/content/AGENTS.md` to platform-specific location
+
+---
+
+## Advanced Usage
+
+### Custom Platform Configuration
+
+Edit `.telos/config.json` to customize platform-specific settings:
+
+```json
+{
+  "platform": "claude",
+  "timestamp": "2024-10-24T...",
+  "symlinks": {
+    "CLAUDE.md": "telos/content/AGENTS.md",
+    "TELOS.md": "telos/content/TELOS.md"
+  }
+}
+```
+
+### Manual Tool Addition
+
+Edit `telos/content/TOOLS.md` to manually add tools, then:
+
+```bash
+telos rediscover
+```
+
+### Agent Customization
+
+Edit individual agent files in `telos/agents/` to customize behavior. After
+editing:
+
+```bash
+# Regenerate consolidated AGENTS.md
+telos rediscover
+```
+
+---
+
+For more information, see:
+
+- [README.md](./README.md) - Philosophy and overview
+- [PHILOSOPHY.md](./PHILOSOPHY.md) - Theoretical foundation (if exists)
+- [GitHub Issues](https://github.com/yourusername/telos/issues) - Bug reports
+  and feature requests

package/bin/telos-cli.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const { initCommand } = require('../lib/commands/init');
+const { statusCommand } = require('../lib/commands/status');
+const { rediscoverCommand } = require('../lib/commands/rediscover');
+const { validateCommand } = require('../lib/commands/validate');
+
+const program = new Command();
+
+program
+  .name('telos')
+  .description('Telos-driven Multi-Agent Development Framework')
+  .version('0.1.0');
+
+program
+  .command('init')
+  .description('Initialize Telos in your project with interactive discovery')
+  .option('-q, --quick', 'Quick initialization with sensible defaults')
+  .option('-v, --verbose', 'Show detailed output')
+  .action(initCommand);
+
+program
+  .command('status')
+  .description('Show current Telos configuration')
+  .option('-v, --verbose', 'Show detailed configuration')
+  .action(statusCommand);
+
+program
+  .command('rediscover')
+  .description('Re-run tool discovery and update configurations')
+  .option('-v, --verbose', 'Show detailed output')
+  .action(rediscoverCommand);
+
+program
+  .command('validate')
+  .description('Validate Telos alignment across the project')
+  .option('-v, --verbose', 'Show detailed validation results')
+  .action(validateCommand);
+
+program.parse();