Registry / ai-ml / telos-framework

telos-framework

library0.10.1jsnpmunverified

Telos Framework (v0.10.1) is a philosophically-grounded multi-agent development framework that enforces spec-driven development in AI-assisted coding. It embeds a four-level purpose hierarchy (Purpose, Experience, Contract, Function) and uses `@telos` annotations to link every function to requirements. The CLI detects AI coding platforms (Claude Code, OpenCode, Cursor, etc.) and installs slash commands like `/telos:init`, `/telos:validate`, and `/telos:sdd-discover`. It is released under MIT, requires Node >=16, and is actively maintained with weekly releases on npm.

ai-ml devops

npm install telos-framework

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TELOS-FRAMEWORK

telos-framework

ai-mljavascriptv0.10.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

telos-framework (CLI)

✓ npx telos-framework init

✗ npm install -g telos-framework (not intended for global install)

Package is primarily a CLI tool; use npx to run without installing globally.

/telos:* commands

✓ /telos:init in AI assistant

✗ (no common wrong pattern)

Commands are slash commands inside AI coding assistants (Claude Code, Cursor, etc.), not terminal commands.

@telos annotation

✓ // @telos L1:function:src/auth/validation:validateToken

✗ /* @telos L1:function:validateToken */ (missing path)

Annotation must follow the pattern: L{level}:{type}:{path}:{name} with colons separating segments.

Creates a new project with spec-driven development structure and installs AI assistant slash commands. Run inside your project directory.

npx telos-framework init

Debug

Known issues

gotcha`@telos` annotation format is strict: `L{level}:{type}:{path}:{name}`. Missing or extra colons break spec linking.

fix

Use the exact format: `// @telos L1:function:src/file.ts:functionName`

affects: >=0.1.0

gotchaSlash commands only work in supported AI coding assistants (Claude Code, OpenCode, Cursor). Not available in generic terminals or chat UIs.

fix

Open your project in a supported AI coding assistant before running slash commands.

affects: >=0.1.0

breakingVersion 0.10.0 changed the CLI entry point from `telos` to `telos-framework`. `npx telos` no longer works.

fix

Use `npx telos-framework` instead of `npx telos`.

affects: >=0.10.0

deprecatedThe legacy `@telos:init` annotation (with colon) is deprecated as of v0.9.0.

fix

Use `@telos` alone (without colon) as the annotation prefix.

affects: >=0.9.0

gotchaBrownfield projects (existing codebases) require an additional `/telos:sdd-discover` step after init, or spec generation will be skipped.

fix

After `npx telos-framework init`, run `/telos:sdd-discover` in your AI assistant to generate specs from existing code.

affects: >=0.1.0

gotchaThe framework requires Node.js >=16.0.0. Older versions will fail to install or run.

fix

Upgrade Node.js to version 16 or later.

affects: >=0.1.0

Errors

Common errors & fixes

Command 'telos' not found

Using `npx telos` instead of `npx telos-framework` (changed in v0.10.0).

fix

Run `npx telos-framework init` instead.

Error: Invalid @telos annotation format: L1:function:validateToken

Missing the file path segment in the @telos annotation (requires 4 colon-separated parts).

fix

Add the file path: `// @telos L1:function:src/auth/validation:validateToken`

telos-framework: Slash commands are not available in this environment

Running slash commands in a terminal or unsupported AI assistant.

fix

Open your project in Claude Code, OpenCode, or Cursor, then type `/telos:init` in the assistant chat.

Upgrade

Version history

0.10.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/telos-framework/init ↗

packagetelos-framework ↗

homepagehttps://github.com/telos-framework/init#readme ↗