# Telos

Telos turns Goal Specifications into running software. Use the Telos CLI or
web UI to create and manage Goal Specs through the same API. Run them locally,
or deploy them to Telos Cloud as continuously reconciled software services.

## Goal Specifications

A goal is a desired end state. A Goal Specification, or Goal Spec, is the
durable artifact that declares that state: the service interface, behavior,
constraints, and quality bar.

Goal Specs are markdown files with YAML frontmatter for identity and plain
English for intent. They are the source of truth. The generated code is an
implementation of the Goal Spec and can change whenever a better
implementation is needed.

```markdown
---
version: 0.1.0
name: hello-service
platform: cloud
---

# Goal

Run an HTTP service with a `/healthz` endpoint, tests, and a documented API.
```

[Read the CLI guide](/docs/cli) for the complete file format and command
reference.

## Skills

Skills package reusable expertise, instructions, and standards. A Goal Spec
can compose skills for implementation guidance and mark skills as required
verification rubrics.

This keeps the Goal Spec focused on the desired outcome while letting teams
reuse their engineering practices, domain knowledge, and quality gates.

## CLI and web UI

The CLI and web UI are peer control surfaces for the same Telos API. Both can
create and update Goal Specs, start and manage sessions, inspect status and
evidence, and operate Telos Cloud resources.

Use the CLI when you are working from a repository, terminal, script, or coding
agent. Use the web UI when you want to author Goal Specs and operate sessions
visually. Work started in one surface is visible and manageable in the other.

## Sessions

A session is the execution record for a Goal Spec. It tracks lifecycle state,
agent activity, verification verdicts, evidence, cost, and the resulting
service.

`telos run` creates a bounded session that meets the Goal Spec once. `telos
apply` creates or updates a durable session that keeps the Goal Spec true.

## Verification

Implementation and acceptance are separate. After an implementation agent
makes a change, an independent evaluation agent checks the result against the
Goal Spec and any required skill rubrics. Telos accepts the change only when
that evaluation passes.

Every session records the verdict and its evidence. The record of what was
verified is part of the product, not an afterthought.

## Reconciliation

Goal Specs support two lifecycles. Run a Goal Spec to meet it once, or apply it
as persistent desired state. Applied Goal Specs are continuously reconciled:
Telos verifies the service, repairs drift, records evidence, and repeats.

Local execution gives developers a direct path into the runtime. [Telos
Cloud](/docs/cloud) provides managed environments, agent compute, deployment,
and continuous operation.