Project Structure

Telesis creates and manages files in two locations: the .telesis/ directory for internal state, and docs/ for project documentation.

The .telesis/ Directory

This directory is the local state store. It’s created by telesis init and grows as you use Telesis features.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
.telesis/
├── config.yml              # Project metadata and configuration
├── telemetry.jsonl         # Model call log (append-only)
├── interview-state.json    # Interview session state (for resume)
├── pricing.yml             # Model pricing for cost derivation
├── notes.jsonl             # Development notes (append-only)
├── journal.jsonl           # Design journal entries (append-only)
├── dismissals.jsonl        # Dismissed review findings (append-only)
├── reviews/                # Review session data
│   └── <ref>-<timestamp>.jsonl
├── sessions/               # Agent dispatch sessions
│   ├── <id>.meta.json
│   └── <id>.events.jsonl
├── intake/                 # Work items from external sources
│   └── <source>-<id>.json
├── plans/                  # Decomposed task plans
│   └── <plan-id>.json
├── agents/                 # Observer policy files
│   ├── reviewer.md
│   ├── architect.md
│   └── chronicler.md
├── daemon.sock             # Unix socket for IPC
└── daemon.pid              # Daemon PID file

File Formats

Most Telesis data uses JSONL (JSON Lines) — one JSON object per line. This format is append-only by design: data is never modified or deleted, only appended. This makes files safe for concurrent writes and provides a natural audit trail.

Configuration uses YAML for human readability.

Observer policies use Markdown with YAML frontmatter — the frontmatter defines observer configuration, the markdown body is the system prompt.

What to Commit

The .telesis/ directory is typically added to .gitignore (Telesis configures this during init). The data here is local to your machine — session logs, telemetry, daemon state.

However, some teams choose to commit specific files for shared context:

config.yml — share project configuration across the team
dismissals.jsonl — share review triage decisions
agents/ — share observer policies

The docs/ Directory

Project documentation lives here. All files are generated by telesis init and maintained throughout the project’s lifecycle.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
docs/
├── VISION.md               # Foundational intent — what and why
├── PRD.md                  # Requirements, user journeys, commands
├── ARCHITECTURE.md         # System design, structure, data flows
├── MILESTONES.md           # Development roadmap with acceptance criteria
├── adr/                    # Architectural Decision Records
│   ├── ADR-001-slug.md
│   └── ADR-002-slug.md
├── tdd/                    # Technical Design Documents
│   ├── TDD-001-slug.md
│   └── TDD-002-slug.md
└── context/                # Custom CLAUDE.md sections
    └── working-conventions.md

Living Documents

These documents are not artifacts that get written once. They evolve:

VISION.md changes when the project’s direction changes (rarely).
PRD.md grows with each feature added.
ARCHITECTURE.md is updated when the system structure evolves.
MILESTONES.md tracks progress — milestones are completed, new ones are added.
ADRs are immutable once accepted; superseded by newer ADRs when revisited.
TDDs are accepted when the implementation matches the design.

The context/ Directory

Files in docs/context/ are included verbatim in the generated CLAUDE.md. This is where you put project-specific conventions, working agreements, and context that doesn’t fit in the standard documents.

For example, docs/context/working-conventions.md might contain your team’s coding standards, commit message format, or PR expectations. This content is automatically included in every AI assistant’s context window.

CLAUDE.md

The root-level CLAUDE.md is a generated file. It’s created by telesis context and aggregates content from all project documents into a single context injection file optimized for AI assistants.

Do not edit CLAUDE.md directly. Your changes will be overwritten the next time telesis context runs. Instead, edit the source documents or add files to docs/context/.

package.json

Telesis reads and writes the version field in package.json. During milestone completion, the version is bumped to match the milestone version. The cli-version-sync drift check verifies that the CLI reports this same version.

Documentation