Add /telos:start concierge skill, simplify install (MCP now optional)

New /telos:start is the front door for new users — auto-scaffolds brain/,
runs /why → /problem → /interview in sequence with one-line context, and
exits with a real interview script in 10 minutes.

Install collapses to 3 slash commands. Python MCP moves to optional
section: skills work file-only by default, MCP is a perf upgrade.

SessionStart pitch and CLAUDE.md updated to recommend /telos:start
when a founder lands fresh.

Author: nocoder26

CLAUDE.md

@@ -44,6 +44,9 @@ When they describe a problem in their solution's language ("can't manage finance
 
 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
@@ -83,7 +86,7 @@ If the MCP server isn't available (e.g. founder skipped install), fall back to d
 
 ## 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 tell them to run `/why` first, then `/problem`.* Don't write code. Don't suggest features. The founder's first moves are an anchor and a hypothesis — earned the hard way.
+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
 

README.md

@@ -121,53 +121,53 @@ If you disagree with any of these, this tool isn't for you.
 
 ## Install
 
-**One-time setup. In any Claude Code session, run these commands ONE AT A TIME** (Claude Code concatenates pasted multi-line input into a single broken command — paste each line, Enter, wait for confirmation, then the next):
+Three slash commands inside Claude Code. Run them **one at a time** — Claude Code concatenates pasted multi-line input.
 
 ```
 /plugin marketplace add https://github.com/nocoder26/telos.git
 ```
-
-Wait for *"Successfully added marketplace: telos"*, then:
-
 ```
 /plugin install telos@telos
 ```
-
-Wait for *"Installed telos. Run /reload-plugins to apply."*, then:
-
 ```
 /reload-plugins
 ```
 
-Confirm: *"Reloaded: 1 plugin · 5 agents · 2 hooks · 1 plugin MCP server"*.
+That's it. **No Python, no `pip`, no terminal setup required.** Telos works file-only by default.
 
-Then in a regular terminal (one-time, for the brain MCP server's Python deps):
+> Use the full HTTPS URL above — the `nocoder26/telos` shorthand defaults to SSH, which fails unless you have SSH keys configured for GitHub.
+
+### Optional: faster brain queries via Python MCP
+
+Telos ships a Python MCP server that turns the brain into queryable tools. It's a perf optimization, not a requirement — if you skip this, Claude reads `brain/` files directly via Read/Glob and everything still works.
+
+To enable:
 
 ```bash
 pip install fastmcp
 ```
 
-> **Use the full HTTPS URL** (`https://github.com/...git`) above — Claude Code's plugin manager defaults to SSH for the shorthand form (`nocoder26/telos`), which fails unless you've set up SSH keys for GitHub.
-
-Requires **Python 3.10+** and the **`claude` CLI** on your PATH.
+(Requires Python 3.10+.)
 
 ## Start using it
 
-Open a fresh project directory and start Claude:
+Open a fresh project directory, start Claude, and run **one command**:
 
 ```bash
 mkdir my-startup && cd my-startup && claude
 ```
 
-Now type **anything** (e.g., `hi`). Claude opens with a one-line pitch:
+Then in Claude:
 
-> *"Telos is loaded — it's like a senior co-founder who refuses to let you build until you've talked to customers. Want to use it here (run `/telos:why`) or normal session?"*
+```
+/telos:start
+```
 
-- Say **yes** (or invoke `/telos:why` directly) → walks you through the founder anchor + problem hypothesis
-- Say **no** → silenced for this directory forever, normal Claude Code session
-- Say **anything else** → assumes "no", normal session, no nag
+A 10-minute concierge walks you through capturing your motivation, your hypothesis (with kill criteria), and an interview script you can send today. You exit with a real artifact — `brain/why.md`, `brain/problem.md`, and a script to send to one customer. No fumbling for which skill to run first.
 
-The pitch fires **once per project** thanks to a per-project memory file. It also auto-skips directories that look like existing non-startup projects (have `.git`, `package.json`, `Cargo.toml`, etc.). To bootstrap an existing repo, run `/telos:why` manually.
+If you'd rather skip the walkthrough, run any specific skill (`/telos:why`, `/telos:problem`, `/telos:interview`) directly.
+
+The SessionStart hook also offers `/telos:start` automatically when you open a fresh project. The pitch fires **once per project** thanks to a per-project memory file, and auto-skips directories that look like existing non-startup projects (have `.git`, `package.json`, `Cargo.toml`, etc.). To bootstrap an existing repo, run `/telos:start` manually.
 
 ## Update / re-install
 
@@ -192,34 +192,39 @@ export TELOS_PITCH_ALWAYS=1    # show pitch even in dirs with package.json/.git/
 
 ```
 $ mkdir my-startup && cd my-startup && claude
-> hi
+> /telos:start
 
-Claude: Telos is loaded — it's like a senior co-founder who refuses
-        to let you build until you've talked to customers. Want to
-        use it here (run /telos:why) or normal session?
+Claude: I'm Telos. I'll spend 10 minutes asking three questions, and
+        you'll walk out with a real interview script and a hypothesis
+        you can kill. Sound good?
 
 > yes
 
-> /telos:why
+[brain/ scaffolded automatically. Then runs /telos:why → /telos:problem
+ → /telos:interview in sequence, with one-line context before each
+ step explaining why it matters.]
+
 [5 questions about your motivation, written to brain/why.md.
  Includes the kill question: "what would make you quit?"]
 
-> /telos:problem
 [8 questions about the pain, who, frequency, founder-market fit,
  falsification criteria, market type. Writes brain/problem.md.
  Stage advances 0 → 1.]
 
+[Generates an interview script tailored to your hypothesis. Past
+ behavior questions, not opinions.]
+
+✓ Anchor captured       brain/why.md
+✓ Hypothesis captured   brain/problem.md
+✓ Interview script      ready
+
+You're at Stage 0 → Stage 1. Send the script to ONE person this week.
+
 > let me build a Stripe integration
 
 🚫 BLOCKED — Stage 1 (Customer Discovery)
    product/ writes are blocked until 5+ believers identified.
-   You have 0. Run /telos:interview to find some.
-
-> /telos:interview
-[Generates a Mom-Test script tailored to your hypothesis.
- Recruit one by one. Paste notes after each call —
- atomic signals get extracted, the participant gets classified
- as Believer / Neutral / Infidel.]
+   You have 0. Run /telos:interview to find some, then /telos:believers.
 ```
 
 That's the loop. Talk → log → classify → eventually unlock `product/` → build with evidence citations.
@@ -229,6 +234,7 @@ That's the loop. Talk → log → classify → eventually unlock `product/` →
 All skills are namespaced under `telos:`:
 
 ```
+/telos:start          ← concierge — start here if you're new
 /telos:why
 /telos:problem
 /telos:interview

plugins/telos/hooks/session-start.sh

@@ -65,7 +65,7 @@ if [ -d "$BRAIN" ]; then
 
   # Recommend next action
   if [ "$WHY_SET" = "no" ]; then
-    NEXT="/telos:why — capture your anchor first"
+    NEXT="/telos:start — concierge walkthrough (10 min, produces a real artifact)"
   elif [ "$PROBLEM_SET" = "no" ]; then
     NEXT="/telos:problem — capture your hypothesis"
   elif [ "$STAGE" = "1" ] && [ "$INTERVIEW_COUNT" -lt 5 ]; then
@@ -111,7 +111,7 @@ cat <<EOF
 {
   "hookSpecificOutput": {
     "hookEventName": "SessionStart",
-    "additionalContext": "Telos is loaded for this fresh project (no brain/ yet, no existing decision).\n\nIn your VERY FIRST message to the founder, do EXACTLY this — no more, no less:\n\n  Say: 'Telos is loaded — it's like a senior co-founder who refuses to let you build until you've talked to customers. Want to use it here (run /telos:why) or normal session?'\n\nThen WAIT for their response. Three cases:\n\n  YES (or they invoke /telos:why themselves): immediately run /telos:why. Don't continue the pitch.\n\n  NO (or they decline / change subject / ask about something else): silently run this bash command to record the decision, then continue as a normal Claude Code session and NEVER bring up Telos again unless they explicitly invoke a /telos:* skill themselves:\n    echo \"$PROJECT_DIR\" >> ~/.claude/plugins/telos/decided.txt\n\n  AMBIGUOUS ('maybe later', 'not sure'): treat as no. Run the bash above, continue as normal session.\n\nThe goal is ONE graceful question, then get out of the way. Don't pitch twice. Don't keep nudging. Don't volunteer telos skills unless they explicitly ask."
+    "additionalContext": "Telos is loaded for this fresh project (no brain/ yet, no existing decision).\n\nIn your VERY FIRST message to the founder, do EXACTLY this — no more, no less:\n\n  Say: 'Telos is loaded — a discipline layer that refuses to let you build until you've validated. Run /telos:start for a 10-min walkthrough that produces a real interview script, or skip and treat this as a normal Claude session?'\n\nThen WAIT for their response. Three cases:\n\n  YES / start / walkthrough (or they invoke /telos:start themselves): immediately run /telos:start. Don't continue the pitch.\n\n  NO / skip / not now (or they decline / change subject / ask about something else): silently run this bash command to record the decision, then continue as a normal Claude Code session and NEVER bring up Telos again unless they explicitly invoke a /telos:* skill themselves:\n    echo \"$PROJECT_DIR\" >> ~/.claude/plugins/telos/decided.txt\n\n  AMBIGUOUS ('maybe later', 'not sure'): treat as no. Run the bash above, continue as normal session.\n\nThe goal is ONE graceful question, then get out of the way. Don't pitch twice. Don't keep nudging. Don't volunteer telos skills unless they explicitly ask."
   }
 }
 EOF

plugins/telos/skills/start/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: start
+description: First-run concierge. Walks a new founder from zero to a captured hypothesis and a real interview script in ~10 minutes. Auto-creates the brain/ skeleton, runs /why → /problem → /interview in sequence with one-line explanations of why each step matters. Use this as the front door instead of running individual skills.
+---
+
+# /start — the concierge
+
+This is the **front door** for someone new to Telos. Don't lecture. Don't dump theory. Walk them through three small captures that produce one real artifact: a hypothesis with kill criteria and a customer-interview script they can send today.
+
+If `brain/why.md` already exists with content, **switch to Mode B** (orientation, not onboarding).
+
+## Mode A — first run (no brain/ yet, or brain/why.md empty)
+
+### Step 0 — One-line welcome
+
+Open with exactly this, no more:
+
+> *"I'm Telos. I'll spend 10 minutes asking three questions, and you'll walk out with a real customer-interview script and a hypothesis you can kill. Sound good? (yes / I already know what I want / what is this?)"*
+
+Branches:
+- **yes** → continue to Step 1
+- **I already know what I want** → drop them out: *"Cool — run `/telos:why`, `/telos:problem`, or `/telos:interview` directly when you're ready. I'll get out of the way."* End.
+- **what is this?** → one-paragraph answer: *"Telos is a discipline layer for Claude Code. It refuses to let you write product code until you've validated the problem with real customers. The brain/ folder we'll build is your record of every interview, decision, and pivot. By the time you raise a round, it's your data room. Ready?"* Then back to the welcome question.
+
+### Step 1 — Bootstrap the brain
+
+If `brain/` does not exist, create it now (use Bash):
+
+```bash
+mkdir -p brain/interviews brain/believers brain/evidence brain/decisions brain/metrics
+touch brain/why.md brain/problem.md brain/stage.md brain/runway.md
+echo "current: 0" > brain/stage.md
+```
+
+Tell them in one line: *"Created `brain/`. Everything we capture lives here as markdown — git-tracked, you own it."*
+
+### Step 2 — The anchor (`/telos:why`)
+
+Set context in one line: *"First question is for you, not the product. Why YOU specifically must solve this. We capture it now so I can surface it later when you're tempted to quit or pivot under stress."*
+
+Then run `/telos:why`. Walk through the 5 questions one at a time. Don't summarize at the end — the file is the artifact.
+
+### Step 3 — The hypothesis (`/telos:problem`)
+
+Set context: *"Now the problem itself. Eight questions. The most important one is Q7 — what would prove this WRONG. If you can't answer that, you don't have a hypothesis, you have a wish. We'll capture it in writing so future-you can't pretend you didn't know."*
+
+Then run `/telos:problem`.
+
+### Step 4 — The first interview script (`/telos:interview`)
+
+Set context: *"Last step. I'll generate an interview script tailored to the hypothesis you just captured. The questions are about past behavior, not opinions — past behavior is signal, opinions are noise. After this, your only job is to send it to one person."*
+
+Then run `/telos:interview` (script-generation mode, not signal-extraction mode).
+
+### Step 5 — The handoff
+
+End with exactly this structure:
+
+```
+✓ Anchor captured       brain/why.md
+✓ Hypothesis captured   brain/problem.md
+✓ Interview script      ready
+
+You're at Stage 0 → Stage 1.
+
+Your only move now: send that script to ONE person this week.
+
+When you have an interview transcript, run /telos:interview again to extract
+signals into brain/. After 5 interviews + 5 believers, the gate to Stage 2
+unlocks and you can build.
+```
+
+Stop. Do not list other skills. Do not pitch the system. The artifact is the pitch.
+
+## Mode B — returning founder (brain/why.md already populated)
+
+This skill was invoked but the founder is not new. Don't re-onboard. Instead, run a **state-aware orientation**:
+
+1. Read `brain/why.md`, `brain/problem.md`, `brain/stage.md`, count interviews and believers.
+2. Output a 4-line snapshot:
+
+```
+Stage <N>.  Why captured.  Problem captured.  <X> interviews, <Y> believers.
+Last decision: <pull from brain/decisions.md>.
+Closest gate: <next stage gate, or PMF check, or runway>.
+Recommended next: /telos:<skill>.
+```
+
+3. Stop. Don't lecture. They know the system.
+
+## Refusal: when to NOT use /start
+
+- Founder is mid-task and runs `/telos:start` by mistake — ask: *"You're mid-flow on `<task>`. Restart onboarding (replaces context), or back out?"*
+- `brain/why.md` looks corrupted or partial — recommend running `/telos:why` directly to refresh, not full onboarding.
+
+## Why this exists
+
+Most new users land in Claude Code with an installed plugin and no idea which slash command to run first. The friction kills activation. `/start` is one obvious door — it produces a real artifact in 10 minutes, then gets out of the way.