telos

name

telos

description

Stand up a project's Promptus stores under a single `.promptus/` namespace, Telos first — and maintain the Telos as direction shifts. Use when initializing Promptus in a repo, AND whenever about to edit `.promptus/TELOS.md`: Telos edits are OPERATOR-TRIGGERED — the agent registers evidence in the research ledger (kb-add) and proposes; the boundary routes everything else to the ledger, NOW-header, or memory. Drives the templates/ scaffolds.

telos — scaffold the stores, keep the compass clean

Portable path rule: in commands below, replace <plugin-root> with the absolute plugin root two directories above this SKILL.md. Resolve it from the loaded skill path; do not assume a host-specific environment variable exists in the project shell.

Initialize Promptus in a project, in dependency order. Everything Promptus owns lives under one .promptus/ namespace, so it never collides with the host project's own docs/, memory/, or build files. Telos first: every other store answers to the direction it sets. Be idempotent — detect an already-initialized repo and never clobber an existing store; report and stop instead.

Procedure

1. Telos first. Copy <plugin-root>/templates/TELOS.md → <repo>/.promptus/TELOS.md and fill it with the operator: the north star (what this project is trying to find out, and for whom) and any project-specific lines under the invariant. The scripts locate the project root by finding .promptus/.
2. Ledger. Copy <plugin-root>/templates/ledger/RESEARCH-LEDGER.md → <repo>/.promptus/ledger/RESEARCH-LEDGER.md, keeping the NOW-header skeleton and the <!-- kb:append-point --> sentinel that kb-add targets. Fill the Mandate/Thesis/Guardrails from the Telos.
3. Vocab. Copy <plugin-root>/templates/schema/kb-vocab.json → <repo>/.promptus/schema/kb-vocab.json — the controlled vocabulary the gate validates against (tune the extended sets per project).
4. Knowledge. Create .promptus/docs/ and .promptus/docs/lit/ with their INDEX.md stubs (from <plugin-root>/templates/).
5. Memory. Create .promptus/memory/ with MEMORY.md (its sentinel + index header) from the template. Memory is per-project — each project owns what it has settled.
6. Leave .promptus/cache/ to be generated by kb-index (derived + gitignored). Add /.promptus/cache/ to the repo's .gitignore if absent.

After scaffolding

Hand off to the research-ledger skill so recording starts immediately, and drop the standing cadence into the project's root AGENTS.md (template: templates/AGENTS.md) — agents look for it there, so it stays out of the namespace. Then store the first unit — the operator's mandate — as kb-add --substrate ledger --kind DECISION, and run bun "<plugin-root>/scripts/kb-index.ts" to prove the loop closes.

Pairs with the promptus-init skill (and its Claude Code command adapter), which runs this end to end.

Maintaining the Telos — the boundary

The Telos is the one freehand store, which makes it the one store that can silently rot: with no gate, live state gravitates into it ("where the frontier is now", dated amendments, session stamps) until the compass reads like a dashboard. The rule: the Telos holds direction only — the north star, the commitments, scope, the rules that never bend — and when direction changes it is REWRITTEN in place, never amended with a date. The history of the change is the ledger's job, not the Telos's.

Who edits it: the operator triggers, the agent proposes. The agent never rewrites the Telos on its own initiative. When the work suggests the direction shifted, register the evidence in the research ledger first (the research-ledger skill owns the habit; kb-add is the gate) and propose the Telos change — the rewrite happens on the operator's word. At a checkpoint the Telos is read (the drift check), never written; memory is what gets refreshed there.

Route by what you are about to type:

you are about to write…	it belongs in
"this happened / we ran / we measured / we decided"	the ledger — the research-ledger skill / kb-add --substrate ledger (the gate owns the date)
"where we are now / the frontier / next actions"	the ledger NOW-header — kb-now (never a Telos section)
a settled, durable fact the project should never relearn	memory — kb-add --substrate memory (kept fresh by the checkpoint workflow)
a date, an event-… id, a session stamp (cont.N), "Updated:"	nowhere in the Telos — each is a ledger line in disguise
a genuine change of direction	record a ledger DECISION (the date, the why, the [[links]]) and propose; on the operator's word, rewrite the Telos section in place

The tell: if you are typing a date into TELOS.md, you are writing a ledger line into the wrong store. promptus-doctor check flags event-shaped Telos lines (dates, event ids, session stamps, NOW-shaped headings) with this routing — report-only; moving the content is judgment, usually one kb-now refresh plus a few kb-adds, then deleting the lines from the Telos.