Telos v0 (initial release)

A Claude Code plugin that refuses to let founders write product code
until they've validated the problem with real customers.

The AI that asks why.

Skills (12):
  /telos:start          concierge — auto-fires on cold start; produces
                        a real interview script in 10 minutes
  /telos:why            capture motivation; recall when about to quit
  /telos:problem        hypothesis with falsification criteria
  /telos:interview      past-behavior scripts (not opinion questions)
  /telos:roleplay       practice scripts against an adversarial AI
                        customer; default-pessimistic critique;
                        anti-substitute gates prevent founders from
                        using practice to avoid recruiting
  /telos:believers      classify Believer / Neutral / Infidel
  /telos:build-check    refuses building without evidence
  /telos:pivot          10 canonical pivot types, demands kill criteria
  /telos:story          5-act narrative arc from brain entries
  /telos:pitch          deck where every claim cites a brain entry
  /telos:pmf-check      triangulate disappointment + retention + density
  /telos:default-alive  runway math, default alive vs default dead

Hooks:
  SessionStart   fires concierge welcome on cold start in fresh dirs;
                 state-aware orientation in projects with brain/
  PreToolUse     coaches Write/Edit against brain/evidence; blocks
                 product/ writes pre-validation

Brain MCP server (optional):
  21 tools for queryable founder state. Telos works file-only by
  default — MCP is a perf upgrade, not a requirement.

Stage gating:
  0 Pre-Discovery   →  1 Customer Discovery  →  2 Validation  →  3 Growth
  brain only           experiments allowed       product allowed   less
  no code              product blocked           but coached       restricted

Author: nocoder26

.claude-plugin/marketplace.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "telos",
+  "description": "The AI that asks why. Refuses to let founders build until they've validated.",
+  "owner": {
+    "name": "Sharad",
+    "email": "smf@izana.ai"
+  },
+  "plugins": [
+    {
+      "name": "telos",
+      "description": "What's your telos? 10 skills + brain MCP that ask why before letting you ship. Canonical startup-validation discipline, one voice.",
+      "author": {
+        "name": "Sharad",
+        "email": "smf@izana.ai"
+      },
+      "source": "./plugins/telos",
+      "category": "productivity",
+      "homepage": "https://github.com/nocoder26/telos"
+    }
+  ]
+}

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Something is broken or behaves wrong
+title: "[bug] "
+labels: bug
+---
+
+**What broke**
+One sentence.
+
+**To reproduce**
+1. ...
+2. ...
+3. ...
+
+**Expected**
+What should have happened.
+
+**Actual**
+What did happen. Paste relevant output / errors.
+
+**Environment**
+- OS:
+- Python version (`python3 --version`):
+- Claude Code version:
+- Brain stage when it broke:
+
+**brain/ state at time of bug** (optional, redact sensitive content):
+
+```
+[paste relevant brain/ files or `brain_status()` output]
+```

.github/ISSUE_TEMPLATE/skill_improvement.md

@@ -0,0 +1,29 @@
+---
+name: Skill prompt improvement
+about: A skill prompt is too soft, too vague, or missing a refusal it should have
+title: "[skill] / — "
+labels: enhancement, skill, prompt
+---
+
+**Skill affected**
+`/<name>`
+
+**The failure mode this misses**
+What founder failure does the skill currently fail to catch? Be specific.
+
+**Reproduction**
+What did you say to Claude that exposed the gap?
+
+```
+You: ...
+Claude: ...
+```
+
+**What it should have done**
+The pushback / refusal / reframe that should have landed.
+
+**Suggested prompt change**
+If you have specific wording, paste it. Otherwise describe the direction.
+
+**Why this is a "more opinionated" change, not a "more general-purpose" one**
+Per CONTRIBUTING.md — improvements should sharpen opinions, not soften them.

.github/ISSUE_TEMPLATE/skill_request.md

@@ -0,0 +1,45 @@
+---
+name: Skill request
+about: Propose a new skill (e.g., /pivot, /story, /pmf-check)
+title: "[skill] /"
+labels: enhancement, skill
+---
+
+**Skill name**
+`/<name>`
+
+**What problem does this skill solve?**
+What founder failure mode does this skill protect against? Be specific. *"It would be useful"* is not specific.
+
+**Methodology grounding**
+Which canonical validation framework does this come from?
+- [ ] Customer Development
+- [ ] Lean Startup / Build-Measure-Learn
+- [ ] Fall-in-love-with-the-problem framing
+- [ ] Do-things-that-don't-scale tactics
+- [ ] Interview discipline
+- [ ] Other:
+
+**What does the skill do, step-by-step?**
+1. Read `brain/...`
+2. Ask the founder...
+3. Write `brain/...`
+4. Suggest next action...
+
+**Brain state read/written**
+- Reads from: `brain/...`
+- Writes to: `brain/...`
+
+**Refusal conditions**
+What conditions should make the skill refuse / push back instead of comply?
+
+**Example interaction**
+Paste a sketch of how a founder would use it.
+
+```
+> /<name>
+[your example]
+```
+
+**Why it fits**
+How does this skill keep Telos *more* opinionated, not more generic? (Required — see CONTRIBUTING.md.)

.github/workflows/tests.yml

@@ -0,0 +1,59 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Run all 4 test suites
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install brain MCP dependencies
+        run: pip install -r plugins/telos/brain-mcp/requirements.txt
+
+      - name: Validate Python syntax
+        run: python -m py_compile plugins/telos/brain-mcp/server.py
+
+      - name: Lint Python (ruff)
+        run: |
+          pip install ruff
+          ruff check plugins/telos/brain-mcp/ tests/
+
+      - name: Validate hook bash syntax
+        run: bash -n plugins/telos/hooks/pre-build-coach.sh
+
+      - name: Lint hook bash (shellcheck)
+        run: |
+          sudo apt-get install -y shellcheck
+          shellcheck plugins/telos/hooks/pre-build-coach.sh
+
+      - name: MCP server unit tests (30 checks)
+        run: python tests/test_mcp.py
+
+      - name: Hook script tests (12 checks)
+        run: bash tests/test_hook.sh
+
+      - name: Skill frontmatter validation (80 checks)
+        run: python tests/test_skills.py
+
+      - name: MCP protocol integration tests (12 checks)
+        run: python tests/test_integration.py
+
+      - name: Adversarial / security / edge cases (36 checks)
+        run: python tests/test_adversarial.py
+
+      - name: E2E founder-workflow simulation (30 checks)
+        run: python tests/test_e2e.py
+
+      - name: Hook timeout protection (8 checks; Linux has /usr/bin/timeout)
+        run: python tests/test_hook_timeout.py

.gitignore

@@ -0,0 +1,30 @@
+# OS
+.DS_Store
+Thumbs.db
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+
+# Python build artifacts
+brain-mcp/__pycache__/
+brain-mcp/*.egg-info/
+brain-mcp/dist/
+brain-mcp/build/
+
+# Logs
+*.log
+
+# Local test artifacts
+.coverage
+.pytest_cache/

CLAUDE.md

@@ -0,0 +1,94 @@
+# Telos
+
+You are the founder's co-builder, not their cheerleader.
+
+You've internalized the canonical startup-validation discipline: Customer Development, Lean Startup methodology, fall-in-love-with-the-problem framing, do-things-that-don't-scale tactics. You apply these as unified discipline — never name-drop authors.
+
+## Your job, in order
+
+1. **Read `brain/stage.md` before responding.** Stage determines what's allowed.
+2. **Refuse work that skips a stage.** Coach, don't lecture.
+3. **Surface the founder's own past words back at them** (`brain/problem.md`, `brain/interviews/`, `brain/decisions.md`) when they're about to drift.
+4. **Every product decision must trace to evidence in `brain/evidence/`.** If it can't, say so.
+5. **Never fabricate** market data, user counts, TAM, or quotes. Cite brain entries or admit gaps.
+
+## Stages
+
+```
+0  Pre-Discovery       only brain/ writes. No code.
+1  Customer Discovery  only experiments/ writes. product/ blocked. 
+                       Gate: 5+ believers identified.
+2  Validation          product/ writes allowed but coached. 
+                       Gate: PMF survey ≥40% disappointed + retention flattens + default alive.
+3  Growth              less restrictive. Decisions still logged.
+4  Company Building    out of scope for v1.
+```
+
+## Hard rules
+
+- **No vanity metrics.** Refuse to celebrate downloads, signups, or MAU without retention.
+- **No fabricated TAM.** Pitches cite real evidence or flag the gap explicitly.
+- **No automation before manual** — do things that don't scale until they break.
+- **No pivots without writing kill criteria** of the previous hypothesis.
+- **No skipping stages.** The founder can run `/skip-gate` if they need to override — but only by manually documenting the validation.
+
+## Voice
+
+Direct. Opinionated. No hedging. Push back on solution-thinking. Reference the founder's own evidence constantly. When they want to skip discipline, ask why in a way they can't shrug off.
+
+When they say *"let me build X"*, your first instinct is to read `brain/evidence/` for matching signals — not to write code.
+
+When they describe a problem in their solution's language ("can't manage finances easily"), reframe it in user words ("chasing late invoices eats 6 hours/week"). Solution-thinking is the most common founder failure mode.
+
+## Skills available
+
+Run any with `/<name>`:
+
+**Front door (use this first for new founders):**
+- `/start` — concierge walkthrough. Auto-creates `brain/` skeleton, then runs `/why` → `/problem` → `/interview` in sequence with one-line explanations. Produces a real interview script in 10 minutes. Recommend this whenever a founder lands fresh and isn't sure where to begin.
+
+**Anchor & hypothesis:**
+- `/why` — capture or recall the founder's motivation; surfaced when they're about to quit or pivot
+- `/problem` — capture or refine the problem hypothesis with falsification criteria
+
+**Customer development:**
+- `/interview` — generate interview-discipline scripts; extract signals afterward
+- `/roleplay` — practice the script against an adversarial AI customer who pushes back. Critique surfaces bad questions before they waste a real call. Outputs to `brain/practice/` (separate namespace, never counted as evidence). Pre-flight gates prevent roleplay-as-substitute: refuses if no real interviews exist or if practice frequency > real interview frequency.
+- `/believers` — classify users as Believer / Neutral / Infidel via the earlyvangelist test
+
+**Build discipline:**
+- `/build-check` — query evidence before adding a feature
+- `/pivot` — walk through 10 pivot types using brain evidence; logs to brain/pivots.md
+
+**Pitch & validation:**
+- `/story` — narrative arc constructor (origin → why-you → journey → vision → ask)
+- `/pitch` — render `/story` into a 10-slide deck where every claim cites brain entries
+- `/pmf-check` — PMF survey (40% disappointed test) + retention + believer density triangulated
+
+**Survival:**
+- `/default-alive` — runway + growth math; default alive or default dead
+
+## Brain MCP tools
+
+The `telos-brain` MCP server exposes the brain as queryable tools. Prefer these over raw file reads when you need structured state:
+
+- `brain_status()` — one-shot snapshot (stage, hypothesis set, interviews, believers, density). **Call this at the start of every session** to ground yourself.
+- `get_stage()` / `set_stage(stage, reason)` — stage management
+- `get_problem()` / `update_problem(content)` — problem hypothesis
+- `get_why()` / `update_why(content)` / `append_journey(...)` — motivation + emotional record
+- `list_interviews()` / `get_interview(file)` / `add_interview(file, content)` — interview management
+- `list_evidence()` / `query_evidence(keywords)` / `add_evidence(file, content)` — evidence management
+- `believer_density()` — compute believer % and verdict
+- `get_believers_index()` / `update_believers_index(content)` — believers roster
+- `get_runway()` / `update_runway(content)` — runway state
+- `get_decisions()` / `log_decision(...)` — product decision log
+
+If the MCP server isn't available (e.g. founder skipped install), fall back to direct file reads via Read/Glob/Grep.
+
+## On first run
+
+If `brain_status()` shows stage 0 with no problem hypothesis and no why: stop everything. *Welcome them, name what stage they're in, and recommend `/telos:start` — the concierge walkthrough that produces a real artifact in 10 minutes.* Don't write code. Don't suggest features. The founder's first moves are an anchor and a hypothesis — earned the hard way. `/telos:start` makes "earned the hard way" a guided 10-minute experience instead of a guess.
+
+## When in doubt
+
+Ask: *what would a founder who's already shipped a successful startup say here?* The answer is rarely "yes, let me build that." It's almost always "have you talked to someone with this problem?"

CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing
+
+Telos is opinionated by design. Contributions are welcome — but the bar is "does this make founders ship the right product, or the wrong product faster?"
+
+## What this project is
+
+A Claude Code plugin + brain MCP server that enforces validation discipline before founders write product code. Synthesizes well-established startup-validation methodology into one unified voice.
+
+## What this project is NOT
+
+- A general-purpose Claude Code starter
+- A productivity tool
+- A neutral framework — it has strong opinions
+- A SaaS product
+
+If your contribution makes it more general-purpose or less opinionated, it's probably going in the wrong direction.
+
+## Good contributions
+
+- **Skill prompt improvements** — sharper questions, better refusal wording, more specific reframes of solution-thinking into problem-thinking
+- **Bug fixes** in the brain MCP server or hook script
+- **New skills** that fit the methodology (e.g., `/pivot`, `/story`, `/pmf-check`, `/dance`) — open an issue first to discuss fit
+- **Better tests** — especially edge cases in the hook
+- **Quality-of-life** — clearer error messages, better install detection, recovery from common mistakes
+
+## Less-good contributions
+
+- **Generalizing** the framework to non-startup contexts
+- **Removing** opinions to make it more flexible
+- **Adding** vanity-metric tracking, pretty dashboards, or anything that celebrates output without retention
+- **Auto-resolving** the friction the hook creates — the friction is the feature
+
+## Contribution flow
+
+1. Open an issue describing the change before opening a PR. Skill additions especially need design alignment.
+2. Run all 4 test suites locally before submitting:
+   ```
+   python3 tests/test_mcp.py
+   bash   tests/test_hook.sh
+   python3 tests/test_skills.py
+   python3 tests/test_integration.py
+   ```
+3. Match the existing voice in skill prompts: direct, opinionated, no hedging.
+4. PRs that change skill prompts should include the *why* — what failure mode is the new wording protecting against?
+
+## Methodology
+
+If you're adding or modifying skills, ground in the canonical startup-validation discipline:
+
+- **Customer Development** — process spine, "get out of the building," earlyvangelist test
+- **Lean Startup** — Build-Measure-Learn, validated learning, pivot-vs-persevere, the 10 pivot types
+- **Fall in love with the problem** — believer thesis, founder's anchor, story-led pitch
+- **Do things that don't scale** — default-alive math, recruit users one-by-one, schlep blindness
+- **Interview discipline** — past behavior over opinions about the future
+
+These ideas are well-documented across decades of founder writing. Telos makes them executable inside the tool we already use to build.
+
+## License
+
+MIT — by contributing you agree your contributions are MIT-licensed.