Telos

• Personal TELOS changes only through the Update intent's tool: each change lands in the right file (and section, on a section-structured TELOS.md) with existing content preserved, a timestamped backup taken first, and a line in the changelog. The one other writer, the dashboard template's file save, keeps the same guarantees: it holds the shared TELOS lock, copies the file to Backups/<name>.dashboard-<stamp> first, logs the change, and refuses any edit inside an AUTOMATED region.
• Advice and analysis rest on the TELOS or project files as they are now, read in this run, and every claim traces to a file; nothing comes from cached knowledge.
• A project analysis surfaces the dependency chains PROBLEMS→GOALS→STRATEGIES→PROJECTS, the bottlenecks, alignment with stated objectives, progress and risk areas, delivered in the format asked for: report, narrative, dashboard, JSON or executive summary.
• Personal TELOS never leaves the private tree: it is never included in public repos, skills, or outputs. Project material may be sensitive, so it is shared outward only with the principal's yes, sensitive details are redacted in examples, and individual names are reduced to roles in anything board-facing.

General project analysis, dashboards, dependency mapping and executive summaries have no intent file; the skill handles them directly (§ Project TELOS Analysis, § Building Dashboards).

All personal TELOS files live at ~/.claude/LIFEOS/USER/TELOS/, in the USER tree, not under the Telos skill directory. updates.md is the changelog of every TELOS update and Backups/ holds the timestamped backups. The optional report theme (ReportTheme.ts, Fonts/, PREFERENCES.md § Report design) lives at <configRoot>/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/Telos/. Setup: Setup.md.

An install that keeps TELOS unified holds the categories as H2 sections of TELOS.md, including the Ideal State and Current State sections, and its updates target TELOS.md with --section. The machine-owned AUTOMATED regions inside the Current State and Ideal State sections change only through --region current|ideal (Update.md § Tool contract). An install may also keep per-domain IDEAL_STATE/ and CURRENT_STATE/ directories beside it; the Update tool cannot write those (Update.md § Gotchas).

The split-file taxonomy below is the canonical file list, and the Update tool's VALID_FILES validates file names against it. A fresh install's starter scaffold ships a subset, and the tool creates a valid file on first write.

Point the skill at a project directory (named project, explicit path, or common location). The analysis covers every .md/.csv file in the target tree (e.g. ~/Projects/<your-org-tree>), with no required structure and no fixed file list:

find $TARGET_DIR -type f \( -name "*.md" -o -name "*.csv" \)

Deliver in whatever format was asked: markdown report (Mermaid diagrams), interactive web dashboard, JSON export, or executive summary.

The deliverable is an interactive Next.js dashboard that renders the analysis with dependency graphs (Mermaid or D3.js), sortable and filterable progress tables, metrics cards (KPIs, stats), timeline visualizations and relationship networks. Start from the shipped scaffold at DashboardTemplate/ (working Next.js app: file browser, markdown/CSV rendering, dependency views — see its README for the copy-and-run steps) rather than from scratch, then adapt pages to the analysis. Its stack (Next.js 15, TypeScript, shadcn/ui, Tailwind CSS) and its Tokyo Night Day design tokens in DashboardTemplate/app/globals.css are the dashboard's. Fan the build out across parallel agents wherever the work splits cleanly: data-parsing lib, shared components, per-page views, theme, integration. (Template wired per public issue #1555, @tzioup.)

• Project dashboards pull from multiple sources. Verify data freshness before presenting.

Example 1: Change the ideal state

User: "add to ideal state: publish one book a year"
--> Update intent
--> The entry sits under its heading in TELOS.md's Ideal State section (written with --section), a backup is in Backups/, and updates.md logs the change

Example 2: Analyze project with TELOS

User: "analyze ~/Projects/MyApp with TELOS"
--> Project TELOS analysis over every .md and .csv file in the tree
--> Dependency chains, bottlenecks, alignment and progress metrics, each traced to its file

Example 3: Board report from an assessment

User: "create a TELOS report for Acme Corp"
--> WriteReport intent
--> A running Next.js report app in the output directory, nine sections, role-based sources, print-ready