assistant-telos

name	assistant-telos
description	Create or update Telos purpose, mission, goals, challenges, and strategies. Use for explicit purpose or Telos work.
effort	medium
triggers	[{"pattern":"telos|my purpose|why am I doing this|what matters most|my mission|update telos|strategic context","priority":65,"min_words":3,"reminder":"This request matches assistant-telos. Consider whether the Skill tool should be invoked with skill='assistant-telos' for purpose and strategic context management."}]

Telos — Deep Context Framework

Contracts

Contract	File	Purpose
Input	contracts/input.yaml	Action (create/update/review), entity type, focus sections
Output	contracts/output.yaml	TCF file, sections completed, review findings

Rules:

• Create action must produce a TCF with at minimum: problems, mission, goals
• Review action must assess every section's completeness
• Existing TCF must be located before update/review proceeds

Based on Daniel Miessler's Telos — an open-source framework for creating Deep Context about things that matter to humans.

Core idea: Help entities of any size — individuals, teams, organizations — articulate what they are about and how they're pursuing their purpose. The output is a Telos Context File (TCF) that gives AI agents strategic context about why you do what you do.

Goal

Create, update, or review Telos Context Files that connect problems, mission, goals, strategies, projects, and lived progress.

Success Criteria

• Create actions produce at least Problems, Mission, and Goals.
• Updates preserve existing sections and change only the requested focus areas.
• Reviews identify missing, weak, stale, or disconnected sections.
• Projects and strategies trace backward to mission and problems.

Constraints

• Do not invent personal values, goals, history, or organizational facts.
• Ask when a missing answer would change the user's mission, goals, or strategic framing.
• Keep sensitive personal content out of durable files unless the user explicitly provides and approves it.

The Explainability Chain

Problem  →  Mission  →  Narrative  →  Goal  →  Challenge  →  Strategy  →  Project  →  Journal
  (why)      (what)      (story)     (target)   (blocker)     (how)       (doing)     (living)

Every item traces backward. If a project can't connect to a problem, question why it exists.

Two TCF Types

Telos supports both personal and organizational context files. Both use the same core chain but differ in scope.

Personal TCF

Full sections (in order):

Section	Prefix	Purpose
Document Purpose	—	What this file is and how sections connect
History	—	Background that shapes your perspective
Problems	P1, P2...	Issues in the world that genuinely move you
Mission	M1, M2...	What you're building/doing to address the problems
Narratives	N1, N2...	How you explain yourself: "I believe [P] matters, so I'm [M]"
Goals	G1, G2...	Specific, time-bound targets (mix personal + professional)
Challenges	C1, C2...	Concrete obstacles blocking progress
Ideas	I1, I2...	Current beliefs, principles, and convictions
Predictions	—	Forecasts with confidence percentages
Wisdom	—	Distilled life lessons and principles
Metrics	K1, K2...	Measurable indicators of progress on goals
Projects	—	Active work, each linked to a strategy/goal
Journal/Log	—	Dated entries tracking the lived experience

Optional personal sections: Things I've Been Wrong About, Best Books, Best Movies, Traumas.

Corporate/Team TCF

Adds organizational structure on top of the core chain:

Section	Purpose
Company History	Origin story and market context
Company Mission	Organizational purpose
Company Goals	G1, G2... ranked by importance (each half as important as previous)
Company KPIs	K1, K2... measurable metrics tied to goals
Team Mission	Team-specific purpose within the organization
Team Goals	SG1, SG2... team objectives with deadlines
Team KPIs	SK1, SK2... team metrics (e.g., time-to-detect, remediation speed)
Risk Register	R1, R2... key organizational vulnerabilities
Strategies	Approaches addressing challenges and risks
Infrastructure Notes	Technology stack and platform details
Team	Members, skills, assignments (table format)
Projects	Active work with priority, timeline, status, cost (table format)
Current State	Timestamped activity log tracking KPI changes over time

Storage

Telos Context File lives at ~/{agent_state_dir}/telos.md — global, cross-project, loaded at every session start.

For team/corporate context in a specific repo, use {agent_state_dir}/telos.md at the project root.

Commands

Create (telos create / first time)

Ask: "Personal or team/project context?" Then walk through the relevant sections.

Personal TCF creation — walk through one section at a time:

Step 1 — History

"Tell me about your background — what shaped how you see the world?"

Brief biographical context. Keep it to what's relevant.

Step 2 — Problems

"What problems in the world genuinely bother you? Not theoretical — things you feel emotionally compelled to address."

Capture as P1, P2, etc. Each should be specific enough to act on.

Step 3 — Mission

"What are you building or working toward to address those problems?"

Capture as M1, M2, etc. Each mission should connect to a problem.

Step 4 — Narratives

"How would you explain this to someone? Format: 'I believe [problem] is important, which is why I'm [mission].'"

Capture as N1, N2, etc. These are the sentences you'd actually say.

Step 5 — Goals

"What does success look like? Be specific — include deadlines where possible."

Capture as G1, G2, etc. Mix personal and professional.

Step 6 — Challenges

"What's actually blocking you right now? Be concrete."

Capture as C1, C2, etc. Not "lack of time" but "spending 60% of time on ops instead of product."

Step 7 — Optional sections

Ask if they want to capture any of: Ideas (current beliefs), Predictions (with confidence %), Metrics (measurable KPIs), Wisdom (life principles).

Don't push — these are valuable but not required for a useful TCF.

Step 8 — Projects

"What are you actively working on? Each should connect back to a goal or mission."

List with connections to the chain.

After each step, confirm with the user before moving on. When complete, write ~/{agent_state_dir}/telos.md.

Corporate/Team TCF creation follows the same pattern but with organizational scope — company goals, team structure, KPIs, risk register, project tables.

Update (telos update / update telos)

Read the existing ~/{agent_state_dir}/telos.md, present it, and ask what changed. Common updates:

• New project → verify it connects to the chain
• Goal achieved → celebrate, remove or mark done, add next one
• Challenge resolved → update strategies
• Mission evolved → cascade changes down the chain
• Add a journal entry → dated log of what's happening
• Update predictions → adjust confidence percentages

Review (telos review / review telos)

Read ~/{agent_state_dir}/telos.md and check the explainability chain:

• Does every project trace back to a problem?
• Are there orphan projects (no chain connection)?
• Are there goals with no active projects (stalled)?
• Are there challenges with no strategies (unaddressed)?
• Are predictions aging? (check dates vs. confidence)
• Are metrics being tracked? (any stale KPIs)

Present findings as a health check, not a lecture.

Apply (telos apply / when starting work)

When beginning a task, optionally check it against telos:

• Which problem does this serve?
• Which goal does this advance?
• Is this the highest-leverage thing to work on right now?

This is a gentle filter, not a gate. The user decides.

Stop Rules

• Stop and ask before creating or rewriting mission-critical sections from assumptions.
• Stop and report gaps when no existing TCF can be found for update/review.
• Do not persist sensitive personal context unless the user explicitly asks to include it.

TCF File Format (Personal)

Use Daniel Miessler's prefixed identifier system:

# Telos Context File
*Last updated: YYYY-MM-DD*

## Document Purpose
This is my personal TCF. It captures what I'm about and how I'm pursuing my purpose.
Path: Problems → Mission → Narratives → Goals → Challenges → Strategies → Projects → Journal.

## History
- [biographical context]

## Problems
- P1: [problem]
- P2: [problem]

## Mission
- M1: [mission addressing P1]
- M2: [mission addressing P2]

## Narratives
- N1: I believe [P1] matters, which is why I'm [M1].

## Goals
- G1: [specific goal with deadline]
- G2: [specific goal with deadline]

## Challenges
- C1: [concrete obstacle]
- C2: [concrete obstacle]

## Ideas
- I1: [current belief or conviction]

## Predictions
- [prediction statement] ([confidence]%)

## Metrics
- K1: [measurable indicator tied to a goal]

## Projects
- [project name] — [description] → G1, M1

## Journal
- [DD/MM/YYYY]: [entry]

How Agents Use Telos

When ~/{agent_state_dir}/telos.md is loaded at session start:

• Ideation: Score ideas partly on telos alignment — does this serve the mission?
• Planning: When multiple approaches exist, prefer the one aligned with stated goals
• Prioritization: If the user asks "what should I work on?" — consult telos
• Reflection: At task completion, note if the work advanced a goal
• Context: Understand why the user cares about this project, not just what to build

Telos is context, not constraint. It informs decisions but never blocks work the user explicitly requests.

Output

Return:

• Action taken - created, updated, reviewed, applied, or no changes needed.
• TCF location - path to the Telos Context File read or changed.
• Sections - sections completed, updated, reviewed, or still missing.
• Findings - chain health, orphaned items, stale entries, or strategic alignment notes.
• Open questions - decisions or missing context needed before the next Telos update.
• Status - created, updated, reviewed, applied, or blocked by missing TCF/context.

Rules

• Conversational, not ceremonial — this should feel like useful reflection, not a form
• User's words, not yours — capture their language, don't rephrase into corporate-speak
• Prefixed identifiers — use P1/M1/G1/C1/K1 format for cross-referencing
• Living document — encourage regular updates; stale context is worse than no context
• No judgment — if a project doesn't connect to the chain, point it out gently
• Privacy first — TCF may contain personal aspirations and history; never share or log externally
• Right-sized — personal TCF should stay under 80 lines; include only sections that add value