telos-kit 0.5.1

Spec-first development plugins for Codex and Claude Code

Telos

Spec-first plugins for Codex and Claude Code.

Telos adds a lightweight workflow around a project-root SPEC.md:

• define the contract first
• implement against the frozen spec
• evaluate against measurable acceptance criteria

The repository ships:

• a Python CLI package: telos-kit
• a Codex plugin
• a Claude Code plugin marketplace bundle

For Korean documentation, see README_KR.md.

What Telos does

Telos is built around three commands/skills:

• spec: clarify requirements and write SPEC.md
• impl: implement strictly from a frozen SPEC.md
• eval: verify the implementation against the spec

It also installs non-blocking hooks that warn when code is edited without a frozen SPEC.md.

By default, Telos treats the command entrypoint as a thin orchestrator and prefers fresh worker agents for spec, impl, and eval when the surface supports them cleanly. If a surface cannot support that path, Telos falls back to the current session without skipping the spec or evaluation gates.

Requirements

• Python 3.10+
• Codex CLI for Codex plugin installation
• Claude CLI / Claude Code for Claude plugin installation

If a CLI is missing, Telos still copies the plugin files and prints the manual next step.

Installation

Install the package from PyPI:

python3 -m pip install telos-kit

Install plugins:

telos install codex
telos install claude
telos install all

This repository also keeps shell wrappers for GitHub-based installation:

bash install.sh codex
bash install.sh claude
bash install.sh all

Those wrappers install the local package first when possible, then run the same CLI flow.

Installed plugin locations

Codex

Telos installs the Codex plugin into:

~/plugins/telos/
~/.agents/plugins/marketplace.json

After installation or update, restart Codex completely and review the Telos hook with /hooks.

Codex command surface:

$spec
$impl
$eval

Claude Code

Telos installs the Claude marketplace bundle into:

~/.telos/claude-marketplace/

The user plugin id is:

telos@telos-kit

Claude command surface:

/telos:spec
/telos:impl
/telos:eval

During installation, Telos removes its own legacy global Claude files and hook entries, but leaves unrelated user settings in place.

Workflow

Architecture

Telos is designed around:

• a thin orchestrator at the command entrypoint
• a spec worker that owns requirement clarification
• an implementation worker that starts from the frozen spec
• an evaluator worker that stays independent from the implementation worker

The orchestrator should manage state transitions and handoffs, not re-implement or re-evaluate the work itself.

1. Create or refine the spec

Start with the spec command for feature work:

$spec
/telos:spec

The spec flow asks focused questions, fills SPEC.md, and only marks the spec as frozen after the ambiguity check passes. When worker agents are available, Telos prefers a fresh spec worker and relays user answers with minimal reinterpretation.

2. Implement from the frozen spec

$impl
/telos:impl

The implementation flow expects:

• SPEC.md to exist in the current project root
• the status to be frozen
• acceptance criteria to be concrete enough to implement against

When worker agents are available, Telos prefers a fresh implementation worker so coding starts from SPEC.md and the relevant codebase instead of the full requirement discussion history.

3. Evaluate against the spec

$eval
/telos:eval

The evaluation flow runs:

1. mechanical checks first
2. semantic review against acceptance criteria
3. optional consensus review for high-risk or uncertain cases

The semantic review should stay independent from the implementation worker and should receive evidence, not implementation intent.

Hooks

Telos installs non-blocking hooks for code edits.

Behavior:

• if SPEC.md is missing, warn
• if SPEC.md is still draft, warn
• if the file edit is not code-like, do nothing

These hooks are advisory. They do not block edits.

Updating

There are two separate layers to update:

1. the telos-kit package
2. the installed plugin files in the user environment

Reapply plugin files from the current package

Use:

telos update codex
telos update claude
telos update all

telos update reuses the install flow. It reapplies the plugin files from the currently installed telos-kit package.

Upgrade the package, then reapply plugins

To move to the latest published package first:

python3 -m pip install --upgrade telos-kit
telos update all

Check update status

Use:

telos update-status codex
telos update-status claude
telos update-status all
telos update-status all --json

Important: update-status compares the installed plugin against the versions recorded in a Telos repository checkout. By default it looks for:

./src/telos_kit/kit_versions.json

That means it is most useful when run from this repository, or when --project-root points to a Telos checkout:

telos update-status all --project-root /path/to/telos

JSON output uses a per-target status object:

[
  {
    "target": "codex",
    "status": "up-to-date",
    "installed_version": "0.4.0",
    "latest_version": "0.4.0",
    "update_available": false
  }
]

Possible status values:

• up-to-date
• update-available
• not-installed
• unknown

Version model

Telos tracks separate versions for:

• the Python package
• the Codex plugin bundle
• the Claude plugin bundle

Installed plugins record their applied version in:

.telos-version.json

The source of truth for packaged plugin versions in this repository is:

src/telos_kit/kit_versions.json

Repository layout

src/telos_kit/
  cli.py
  installers.py
  update_status.py
  resources/
    codex/telos/
    claude-marketplace/plugins/telos/
tests/
install.sh

Development

Run the test suite used by the package:

PYTHONPATH=src python3 -m unittest

Or run a narrower set while iterating:

PYTHONPATH=src python3 -m unittest tests.test_cli tests.test_installers tests.test_update_status tests.test_versions

Run the CLI from the repository without installing it globally:

PYTHONPATH=src python3 -m telos_kit --version
PYTHONPATH=src python3 -m telos_kit install codex

Release notes for maintainers

When publishing a new version, keep these version sources aligned:

• src/telos_kit/__init__.py
• src/telos_kit/kit_versions.json
• Codex plugin manifest version
• Claude plugin manifest version

The repository also includes release validation helpers under scripts/.