telos-framework

Telos: Purpose-Driven Multi-Agent Development Framework

A philosophically-grounded AI framework that embeds purpose hierarchy and spec-driven development into AI-assisted coding. Every line of code traces back to requirements, and every requirement traces back to ultimate purpose.

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.

Once you install the Telos framework, your AI coding assistant becomes the Logos orchestrator itself. It ensures that:

• Every feature has a spec before code is written
• Every function links to a requirement via @telos annotation
• Every requirement traces to purpose through the spec hierarchy
• Every change is validated against the spec structure

Quick Start

npx telos-framework init

This one command:

• Detects your AI coding platform (Claude Code, OpenCode, Cursor, etc.)
• Installs slash commands and platform-specific configuration
• Sets up the spec-driven development structure

After installation, open your project in your AI coding assistant and run:

/telos:init

That's it! Your AI assistant now follows the Telos workflow automatically.

How It Works

The Spec Hierarchy (4 Levels)

Level	Name	Description
L4	Purpose	Why does this project exist? Success metrics?
L3	Experience	User journeys, UX requirements, analytics needs
L2	Contract	API contracts, component interfaces, boundaries
L1	Function	Individual functions with TDD scenarios

Code-to-Spec Linking

Every function must have a @telos annotation:

// @telos L1:function:src/auth/validation:validateToken
export function validateToken(token: string): TokenValidation {
  // implementation
}

Every test must link to the same spec:

// @telos-test L1:function:src/auth/validation:validateToken
describe("validateToken", () => {
  // @telos-scenario L1:function:src/auth/validation:validateToken:valid-token
  it("should validate properly signed tokens", () => {
    // test implementation
  });
});

TDD Workflow

• Spec First: Create spec with requirements and scenarios
• Generate Tests: AI generates tests from spec scenarios
• Red: Tests fail (no implementation yet)
• Implement: AI writes code with @telos annotation
• Green: Tests pass
• Validate: AI validates before commit

Installation

New Projects

npx telos-framework init

Then in your AI coding assistant:

/telos:init

Existing Projects (Brownfield)

npx telos-framework init

Then in your AI coding assistant:

/telos:sdd-discover

This scans your codebase and proposes a spec structure based on existing code.

Slash Commands

All interaction happens through slash commands in your AI coding assistant.

Claude Code

Command	Description
/telos:init	Initialize Telos with AI guidance
/telos:quick	Quick init (auto-accept proposals)
/telos:validate	Validate specs, links, tests
/telos:status	Show current configuration
/telos:sdd-discover	Generate specs from existing code
/telos:sdd-context	Load spec context before changes
/telos:sdd-generate-tests	Generate tests from spec scenarios

OpenCode

Command	Description
/telos-init	Initialize Telos with AI guidance
/telos-quick	Quick init (auto-accept proposals)
/telos-validate	Validate specs, links, tests
/telos-status	Show current configuration
/telos-sdd-discover	Generate specs from existing code
/telos-sdd-context	Load spec context before changes
/telos-sdd-generate-tests	Generate tests from spec scenarios

Other Platforms

For Cursor, Cline, Windsurf, and other platforms, ask your AI assistant:

• "Initialize Telos" or "Run Telos init"
• "Validate my specs"
• "Generate specs from my code"

The AI reads the installed configuration and knows what to do.

Project Structure

After initialization:

your-project/
├── telos/
│   ├── TELOS.md                 # Entry point and navigation
│   ├── .telosrc.json            # Configuration
│   ├── index.json               # Spec registry (auto-generated)
│   └── specs/
│       ├── L4-purpose/
│       │   └── purpose.md       # Project purpose + metrics
│       ├── L3-experience/
│       │   └── *.md             # User journey specs
│       ├── L2-contract/
│       │   └── *.md             # API/component contracts
│       └── L1-function/
│           └── *.md             # Function specs with TDD scenarios
├── .claude/commands/telos/      # Slash commands (Claude Code)
├── AGENTS.md                    # AI assistant instructions
├── CLAUDE.md                    # Claude-specific instructions
└── src/
    └── **/*.ts                  # Code with @telos annotations

Multi-Platform Support

Works with any AI coding assistant:

• Claude Code
• OpenCode
• Cursor
• Cline
• Windsurf
• GitHub Copilot
• Google Gemini

Single source of truth with platform-specific configuration files.

Validation

Your AI assistant validates before commits:

Check	Description
Specs	Structure integrity, parent-child links
Links	All @telos annotations point to valid specs
Tests	All L1 specs have @telos-test annotations
Orphans	All functions have @telos annotations

Run /telos:validate (Claude) or /telos-validate (OpenCode) to check.

Configuration

Configure enforcement in telos/.telosrc.json:

{
  "enforcement": {
    "specs": "hard",
    "links": "hard",
    "tests": "hard",
    "orphans": "hard"
  },
  "languages": {
    "typescript": {
      "testPatterns": ["**/*.test.ts", "**/*.spec.ts"]
    }
  }
}

Examples

See /examples for:

• Simple web app initialization
• Existing codebase integration
• Multi-platform usage demonstration

Philosophy Deep Dive

See PHILOSOPHY.md for:

• Aristotelian teleology in software
• Boulding's hierarchy applied to development
• Why spec-driven development matters

Troubleshooting

See TROUBLESHOOTING.md for common issues.

Contributing

See CONTRIBUTING.md for how to contribute.

License

MIT License - see LICENSE

Transform AI-assisted development from vibe-coding to purpose-driven, spec-traced creation.

GitHub Repository | Report Issues