@xulthekl/team-flow 0.22.4

package/skills/ce-proof/SKILL.md

@@ -0,0 +1,346 @@
+---
+name: ce-proof
+description: Publish, read, comment on, or edit markdown in Proof. Use for Proof links, sharing specs/plans/drafts, or publish handoffs from planning workflows; avoid proofread, math, evidence, or proof-of-concept meanings.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - WebFetch
+---
+
+# Proof - Collaborative Markdown Editor
+
+Proof is a collaborative document editor for humans and agents. This skill uses the **hosted web API** at `https://www.proofeditor.ai` (HTTP/`Bash`). If typed `proof_*` MCP tools are already available in the harness, prefer them; otherwise use the HTTP recipes below.
+
+## Identity and Attribution
+
+Every write to a Proof doc must be attributed. Two fields carry the agent's identity:
+
+- **Machine ID (`by` on every op, `X-Agent-Id` header):** `ai:compound-engineering` — stable, lowercase-hyphenated, machine-parseable. Appears in marks, events, and the API response.
+- **Display name (`name` on `POST /presence`):** `Compound Engineering` — human-readable, shown in Proof's presence chips and comment-author badges.
+
+Set the display name once per doc session by posting to presence with the `X-Agent-Id` header; Proof binds the name to that agent ID for the session. These values are the defaults for any caller of this skill; a caller may pass a different `identity` pair if a distinct sub-agent should own the doc. Do not use `ai:compound` or other ad-hoc variants — identity stays uniform unless a caller explicitly overrides it.
+
+## Publish Mode
+
+The primary use is one-way publishing: take an existing local markdown file (a brainstorm, a unified plan, a learning, a draft), read its full contents and post them as the new doc's body (see "Workflow: Create and Share a New Document" for the source-file recipe — never publish placeholder content), and hand the user a shareable URL. The local file stays canonical — publishing does not sync anything back to disk. The user can open the link to read, comment, and share with others; the agent can also participate via the edit APIs below when given the URL. Two entry points, identical mechanics (see "Workflow: Create and Share a New Document"):
+
+- **Direct user request** — a bare user phrase naming a local markdown file and asking to share it via Proof: "share this to proof", "publish this to proof", "open this in proof editor so I can review", "get me a proof link for this doc". The file is whichever markdown the user just created, edited, or referenced; if ambiguous, ask which file. This is a first-class entry point — do not require an upstream caller.
+- **Upstream skill handoff** — `ce-brainstorm`, `ce-ideate`, or `ce-plan` finishes a draft and hands it off to publish for human review, passing the file path and title explicitly.
+
+Only publish markdown. If the source is an HTML unified plan, do not upload it
+to Proof; return the local browser/open path instead. When publishing a unified
+plan, label the title by readiness when available, e.g. `Plan: <title>
+(requirements-only)` or `Plan: <title> (implementation-ready)`.
+
+Do not silently replace repo-tracked project docs with Proof links. Do not put secrets, credentials, API keys, private tokens, or sensitive personal data in Proof unless the user explicitly approves.
+
+## Credentials
+
+Document creation returns two credentials with different jobs:
+
+- `accessToken` — everyday bearer for read, edit, presence, and events. Use this for all non-owner agent API calls.
+- `ownerSecret` — owner authority only (delete and other owner-level ops). Never use it as the everyday bearer.
+
+Store them separately for the session (shell vars or equivalent non-repo memory). Never write `ownerSecret` or `accessToken` into repo-tracked files, commits, or durable project logs. Never expose `ownerSecret` in user-facing UI copy.
+
+Always hand humans the tokenized link (`tokenUrl`), never a bare `/d/<slug>` alone — the editor token doubles as claim capability for ownerless docs.
+
+Public creates are ownerless until a signed-in Every user claims the doc in the browser (account menu → Claim ownership). Claiming permanently revokes `ownerSecret`; `accessToken` keeps working. After claim, delete and other owner ops belong to the owner's Every account — ask the owner, or use their Every session token. Do not retry delete with a revoked `ownerSecret`.
+
+Treat a `403` with `code: "DOCUMENT_DELETE_FORBIDDEN"` and `reason: "CREDENTIAL_NOT_OWNER"`, or a `401` when presenting the creation `ownerSecret`, as evidence the secret was revoked (commonly after claim). Stop using that `ownerSecret`; ask the owner to delete or supply an Every owner session.
+
+## Web API
+
+Auth on document surfaces (preferred first):
+
+- `Authorization: Bearer <accessToken>`
+- `x-share-token: <accessToken>`
+- `?token=<accessToken>` on the request URL
+
+Canonical agent read/write (v3 only — do not invent other agent mutation paths):
+
+- Read: `GET /api/agent/<slug>/v3/document`
+- Write: `POST /api/agent/<slug>/v3/edit`
+
+### Create a Shared Document
+
+No authentication required on the public create route. Returns a shareable URL with tokens.
+
+```bash
+curl -sS -X POST https://www.proofeditor.ai/share/markdown \
+  -H "Content-Type: application/json" \
+  -d '{"title":"My Doc","markdown":"# Hello\n\nContent here."}'
+```
+
+**Response fields to keep:**
+
+```json
+{
+  "slug": "abc123",
+  "tokenUrl": "https://www.proofeditor.ai/d/abc123?token=xxx",
+  "accessToken": "xxx",
+  "ownerSecret": "yyy",
+  "shareUrl": "https://www.proofeditor.ai/d/abc123",
+  "_links": {
+    "read": "https://www.proofeditor.ai/api/agent/abc123/v3/document",
+    "edit": { "method": "POST", "href": "/api/agent/abc123/v3/edit" },
+    "delete": { "method": "DELETE", "href": "/api/documents/abc123" }
+  }
+}
+```
+
+Use `tokenUrl` as the shareable link. Extract `slug`, `accessToken`, and `ownerSecret` immediately — `ownerSecret` is required for cleanup while the doc is still unclaimed.
+
+### Read a Shared Document
+
+If you already have a shared Proof URL, fetch with content negotiation or v3:
+
+```bash
+curl -sS -H "Accept: application/json" "https://www.proofeditor.ai/d/{slug}?token=<token>"
+curl -sS -H "Accept: text/markdown" "https://www.proofeditor.ai/d/{slug}?token=<token>"
+
+curl -sS "https://www.proofeditor.ai/api/agent/{slug}/v3/document" \
+  -H "Authorization: Bearer <token>" \
+  -H "X-Agent-Id: ai:compound-engineering"
+# -> { ok, revision, title, markdown, comments[], suggestions[], mutationReady? }
+```
+
+ACTIVE docs can be read tokenlessly via `v3/document`. Mutations, presence, and events need a tokenized credential. Tokenless `GET /d/<slug>` JSON reports `role: null` and no mutation links — that is truthful capability reporting, not a browser lock.
+
+`comments[]` and `suggestions[]` on the v3 read are the source of review state. Use a comment's `id` for `reply` / `resolve` / `unresolve`. Use a suggestion's `id` for `accept` / `reject`. v3 supports resolving and unresolving comments; it does **not** support deleting comments.
+
+When `mutationReady` is `false`, `revision` may be `null` — omit `baseRevision` and re-read shortly.
+
+### Edit a Shared Document
+
+Send `{ by, baseRevision?, operations: [...] }` to `POST /api/agent/{slug}/v3/edit`. Targets are **visible text** in `markdown` (not raw markdown syntax, not block refs). There is no base token. `baseRevision` (integer from the last read) is an optional conflict guard — omit it to apply at head. `Idempotency-Key` is optional; use one for important writes and retries.
+
+```bash
+curl -sS -X POST "https://www.proofeditor.ai/api/agent/{slug}/v3/edit" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <token>" \
+  -H "X-Agent-Id: ai:compound-engineering" \
+  -H "Idempotency-Key: $(uuidgen)" \
+  -d '{
+    "by":"ai:compound-engineering",
+    "operations":[
+      {"op":"replace","find":"old visible text","with":"new text"},
+      {"op":"comment","on":"text to anchor on","body":"Is this still accurate?"}
+    ]
+  }'
+```
+
+**Content operations:**
+
+| op | body |
+|---|---|
+| `replace` | `find`, `with` (optional `occurrence` / `before` / `after`) |
+| `insert` | `after` or `before` + `markdown` (anchor: quote, `heading:Title`, `section:Title`, `"start"`, or `"end"`) |
+| `delete` | `find` |
+| `set_document` | `markdown` (whole-doc replace as a minimal diff; safe with live collaborators) |
+
+**Review operations:**
+
+| op | body |
+|---|---|
+| `comment` | `on`, `body` (optional `occurrence`) |
+| `reply` | `comment` (id), `body`, optional `resolve: true` |
+| `resolve` / `unresolve` | `comment` (id) |
+| `suggest` | `kind: "insert"\|"delete"\|"replace"`, `find`, `with?` (`with` required for insert/replace) |
+| `accept` / `reject` | `suggestion` (id) |
+
+### Edit Strategy
+
+Prefer the narrowest op:
+
+1. Literal or scoped prose change → `replace` / `insert` / `delete`
+2. Visible track-changes desired → `suggest` (then `accept`/`reject` as needed)
+3. Whole-doc replacement → `set_document` only when the user asks for full replacement or the change cannot be expressed narrowly
+
+If a `find`/anchor matches more than once, the server rejects with `TARGET_AMBIGUOUS` and `error.candidates` — nothing is changed. Disambiguate with `occurrence` (`"first"`, `"last"`, or 0-based index) or `before`/`after`. Never assume silent first-match.
+
+Content ops in one request apply atomically; review ops then apply in order. If a review op fails after content committed, the response is `ok: false` with `partial: true` — re-read and retry only the failed op (same `Idempotency-Key` safely replays).
+
+**Errors** use `{ ok:false, error:{ code, message, retryable, opIndex?, target?, candidates?, current? } }`. Codes: `AUTH`, `NOT_FOUND`, `INVALID_REQUEST`, `TARGET_NOT_FOUND`, `TARGET_AMBIGUOUS`, `CONFLICT`, `TOO_LARGE`, `BUSY`, `PENDING`, `INTERNAL`.
+
+- `retryable: false` — fix the request; do not blind-retry
+- `retryable: true` with `error.current` — re-resolve targets against `current` and retry once
+- `TARGET_AMBIGUOUS` — add `occurrence` / `before` / `after` from `candidates`
+- `BUSY` — brief backoff and retry
+- Settled `200` with `ok:true` — inspect returned `revision` / document; chain without an extra read when the body is complete
+- `202` / `PENDING` — write may have committed; re-read `v3/document` before chaining or reporting success
+
+After every successful edit: confirm `ok:true`, confirm the intended text/comment/suggestion, then report the Proof link with a short summary.
+
+### Presence
+
+```bash
+curl -sS -X POST "https://www.proofeditor.ai/api/agent/{slug}/presence" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <token>" \
+  -H "X-Agent-Id: ai:compound-engineering" \
+  -d '{"name":"Compound Engineering","status":"reading","summary":"Joining the doc"}'
+```
+
+Common statuses: `reading`, `thinking`, `acting`, `waiting`, `completed`, `error`.
+
+### Title
+
+```bash
+curl -sS -X PUT "https://www.proofeditor.ai/api/documents/{slug}/title" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <token>" \
+  -d '{"title":"Updated document title"}'
+```
+
+### Delete
+
+Only owner credentials can delete:
+
+```bash
+curl -sS -X DELETE "https://www.proofeditor.ai/api/documents/{slug}" \
+  -H "Authorization: Bearer <ownerSecret>"
+```
+
+Viewer, commenter, and editor `accessToken` values cannot delete. Success returns `shareState: "DELETED"`; later reads return deleted-document responses (`410` on many routes).
+
+**Lifecycle:** Do **not** auto-delete after every publish handoff — review docs must linger. Persist `ownerSecret` for the session. Delete when the user asks to remove/clean up, or when finishing an explicitly ephemeral scratch doc the user is done with.
+
+### Marks and privacy
+
+Emptying the markdown (including `set_document` to blank/minimal content) does **not** scrub comment marks. Quote and commentary fields can remain readable via `v3/document` to anyone with the share credential. Without owner delete authority, content wipe is not a privacy cleanup — delete the document with `ownerSecret` (while unclaimed) or ask the owner after claim.
+
+### When the loop breaks
+
+If a mutation keeps failing after a fresh read and one safe retry, call `POST https://www.proofeditor.ai/api/bridge/report_bug` with the failing request ID, slug, and raw response. The server enriches and files an issue. Ask before including the user's name/email.
+
+## Workflow: Review a Shared Document
+
+When given a Proof URL like `https://www.proofeditor.ai/d/abc123?token=xxx`:
+
+1. Extract the slug and token
+2. Bind presence with the CE identity defaults
+3. Read via `v3/document`
+4. Edit with `v3/edit` (narrow content ops; review ops for comments/suggestions)
+
+```bash
+TOKEN="xxx"
+SLUG="abc123"
+AGENT="ai:compound-engineering"
+
+curl -sS -X POST "https://www.proofeditor.ai/api/agent/$SLUG/presence" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Agent-Id: $AGENT" \
+  -d '{"name":"Compound Engineering","status":"reading","summary":"Reviewing doc"}'
+
+DOC=$(curl -sS "https://www.proofeditor.ai/api/agent/$SLUG/v3/document" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Agent-Id: $AGENT")
+REVISION=$(printf '%s' "$DOC" | jq -r '.revision // empty')
+
+# Comment on visible text
+curl -sS -X POST "https://www.proofeditor.ai/api/agent/$SLUG/v3/edit" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Agent-Id: $AGENT" \
+  -H "Idempotency-Key: $(uuidgen)" \
+  -d "$(jq -n --argjson rev "${REVISION:-null}" '{
+    by:"ai:compound-engineering",
+    baseRevision: (if $rev == null then null else $rev end),
+    operations:[{op:"comment",on:"text to comment on",body:"Your comment here"}]
+  } | if .baseRevision == null then del(.baseRevision) else . end')"
+
+# Narrow content edit
+curl -sS -X POST "https://www.proofeditor.ai/api/agent/$SLUG/v3/edit" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Agent-Id: $AGENT" \
+  -H "Idempotency-Key: $(uuidgen)" \
+  -d '{"by":"ai:compound-engineering","operations":[{"op":"replace","find":"old","with":"new"}]}'
+
+# Tracked suggestion
+curl -sS -X POST "https://www.proofeditor.ai/api/agent/$SLUG/v3/edit" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Agent-Id: $AGENT" \
+  -H "Idempotency-Key: $(uuidgen)" \
+  -d '{"by":"ai:compound-engineering","operations":[{"op":"suggest","kind":"replace","find":"old","with":"new"}]}'
+```
+
+## Workflow: Create and Share a New Document
+
+**Publishing a local file (the primary case):** read the file and JSON-encode its full contents into the `markdown` field with `jq --rawfile` so newlines, quotes, and backticks are escaped correctly. Never hand-write the body or leave an inline placeholder — that publishes a placeholder doc instead of the source artifact.
+
+```bash
+SRC="docs/plans/2026-05-04-001-feat-foo-plan.md"
+TITLE="Plan: Foo"
+
+RESPONSE=$(jq -n --arg title "$TITLE" --rawfile md "$SRC" '{title:$title, markdown:$md}' \
+  | curl -sS -X POST https://www.proofeditor.ai/share/markdown \
+    -H "Content-Type: application/json" -d @-)
+
+URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
+SLUG=$(echo "$RESPONSE" | jq -r '.slug')
+TOKEN=$(echo "$RESPONSE" | jq -r '.accessToken')
+OWNER_SECRET=$(echo "$RESPONSE" | jq -r '.ownerSecret')   # required for owner delete while unclaimed
+
+# Keep OWNER_SECRET in session memory only — never write it into the repo tree.
+
+curl -sS -X POST "https://www.proofeditor.ai/api/agent/$SLUG/presence" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Agent-Id: ai:compound-engineering" \
+  -d '{"name":"Compound Engineering","status":"reading","summary":"Uploaded doc"}'
+
+echo "$URL"
+```
+
+After publish handoffs from planning workflows, surface the URL and return control — do not delete the doc automatically.
+
+When the user later asks to clean up an unclaimed doc you created:
+
+```bash
+curl -sS -X DELETE "https://www.proofeditor.ai/api/documents/$SLUG" \
+  -H "Authorization: Bearer $OWNER_SECRET"
+```
+
+## Workflow: Pull a Proof Doc to Local
+
+Sync the current Proof doc state to a local markdown file. Used for:
+
+- Ad-hoc snapshots of a Proof doc to disk
+- Pulling a shared Proof doc that the user (or others) edited back down to a local working copy
+- Refreshing a local working copy against the live Proof version
+
+Canonical read for this workflow: `GET /api/agent/$SLUG/v3/document`.
+
+```bash
+SLUG=<slug>
+TOKEN=<accessToken>
+LOCAL=<absolute-path>
+
+STATE_TMP=$(mktemp)
+curl -sS "https://www.proofeditor.ai/api/agent/$SLUG/v3/document" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Agent-Id: ai:compound-engineering" > "$STATE_TMP"
+REVISION=$(jq -r '.revision // empty' "$STATE_TMP")
+
+TMP="${LOCAL}.proof-sync.$$"
+jq -jr '.markdown' "$STATE_TMP" > "$TMP" && mv "$TMP" "$LOCAL"
+rm "$STATE_TMP"
+```
+
+`jq -jr` streams markdown bytes without going through a shell variable, so trailing newlines survive. `mv` within the same filesystem is atomic.
+
+**Confirm before writing when the pull isn't directly asked for.** If a workflow ends up pulling as a side-effect of a different action, surface the impending write with a short confirm like "Sync Proof doc to `<localPath>`?" A silent overwrite is surprising.
+
+## Safety
+
+- Use `v3/document` as source of truth before editing
+- Prefer narrow `replace` / `insert` / `delete` before `suggest` or `set_document`
+- Always include `by: "ai:compound-engineering"` on writes and `X-Agent-Id: ai:compound-engineering` in headers
+- Use `accessToken` for everyday calls; reserve `ownerSecret` for owner delete
+- Never commit share tokens or owner secrets to the project tree
+- On `TARGET_AMBIGUOUS` / retryable errors, re-resolve against `error.current` — do not double-apply comments blindly

package/skills/ce-strategy/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: ce-strategy
+description: "Create or update STRATEGY.md. Use when starting a product, changing direction or roadmap, or when ce-ideate, ce-brainstorm, or ce-plan need upstream product grounding."
+argument-hint: "[optional: section to revisit, e.g. 'metrics' or 'approach']"
+---
+
+# Product Strategy
+
+**Note: The current year is 2026.** Use this when dating the strategy document.
+
+`ce-strategy` produces and maintains `STRATEGY.md` - a short, durable anchor document that captures what the product is, who it serves, how it succeeds, and where the team is investing. It lives at the repo root as a canonical, well-known file (peer of `README.md`). Downstream skills (`ce-ideate`, `ce-brainstorm`, `ce-plan`) read it as grounding when it exists.
+
+The document is short and structured on purpose. Good answers to a handful of sharp questions produce a better strategy than any amount of prose. This skill asks those questions, pushes back on weak answers, and writes the doc.
+
+## Interaction Method
+
+Default to the platform's blocking question tool: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_question` in Antigravity CLI (`agy`), `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question.
+
+Ask one question at a time. Prefer free-form responses for the substantive sections (problem, approach, persona); reserve single-select for routing decisions (which section to revisit). Each option label must be self-contained.
+
+## Focus Hint
+
+The **focus hint** is any optional argument this skill was invoked with — present in the current prompt or conversation, whether the user gave it directly or a calling skill passed it (empty if none was given).
+
+Interpret any argument as an optional focus: a section name to revisit (`metrics`, `approach`, `tracks`) or a scope hint. With no argument, proceed open-ended and let the file state decide the path.
+
+## Core Principles
+
+1. **Anchor, not plan.** Strategy is what the product is and why. Features belong in `ce-brainstorm`; schedules belong in the issue tracker. Do not let either creep into the doc.
+2. **Rigor in the questions, not the headings.** The section headers are plain English. The interview questions enforce strategy discipline.
+3. **Short is a feature.** The template is constrained. Adding sections costs more than it looks like. Push back on expansion.
+4. **Durable across runs.** This skill is rerunnable. On a second run it updates in place, preserves what is working, and only challenges sections that look stale or weak.
+
+## Execution Flow
+
+### Phase 0: Route by File State
+
+Read `STRATEGY.md` using the native file-read tool.
+
+- **File does not exist** -> First run. Go to Phase 1.
+- **File exists and argument names a specific section** -> Targeted update. Go to Phase 2.
+- **File exists, no argument** -> Ask which section(s) to revisit, then Phase 2.
+
+Announce the path in one line: "Strategy doc not found - let's write it." or "Found existing strategy - let's review and update."
+
+### Phase 1: First-Run Interview
+
+Read `references/interview.md`. This load is non-optional - the pushback rules, anti-pattern examples, and quality bar for each section live there. Improvising from memory produces a passive transcription instead of a strategy doc.
+
+Run the interview in the section order of the final document:
+
+1. Target problem
+2. Our approach
+3. Who it's for
+4. Key metrics
+5. Tracks
+6. Milestones (optional)
+7. Not working on (optional)
+8. Marketing (optional)
+
+For each section, ask the opening question, apply the pushback rules, and capture the final answer in the user's own language. Do not skip the pushback step - it is the core of the skill. Two rounds of pushback per section maximum; capture what the user has given after that and note the section is worth revisiting on the next run.
+
+When all required sections (1-5) are captured, read `references/strategy-template.md`, fill it in, and present the full draft in chat before writing. Offer one round of edits. Then write to `STRATEGY.md`.
+
+### Phase 2: Update Run
+
+Read the existing `STRATEGY.md` thoroughly. Summarize current state in 3-5 lines so the user sees what is on file.
+
+If the argument named a specific section, jump to that section in `references/interview.md`. Preserve all other sections exactly. Apply pushback as if this were a first run - do not rubber-stamp existing weak content just because it is already written.
+
+If no specific target, ask the user which section to revisit using the blocking question tool. Options:
+
+- "Target problem"
+- "Our approach"
+- "Who it's for"
+- "Metrics, tracks, or other"
+
+For each revisited section, re-interview with full pushback. For sections the user confirms are still accurate, leave them untouched. Update the `last_updated` value in the YAML frontmatter to today's ISO date.
+
+Write the updated doc back to `STRATEGY.md`.
+
+### Phase 3: Downstream Handoff
+
+After writing, note in one line where the file lives and that `ce-ideate`, `ce-brainstorm`, and `ce-plan` will pick it up as grounding on their next run.
+
+If no downstream skill has run yet on this repo, suggest `ce-ideate` or `ce-brainstorm` skills as a next step.
+
+## What This Skill Does Not Do
+
+- Does not update the issue tracker or reconcile in-flight work. Strategy is the doc; execution lives elsewhere.
+- Does not prioritize the backlog. Prioritization is a separate workflow.
+- Does not write product requirements or implementation plans - those are `ce-brainstorm` and `ce-plan`.
+- Does not compute metric values. It records which metrics matter and where they live, not what they read today.
+
+## Learn More
+
+The "Target problem / Our approach / Tracks" structure is informed by Richard Rumelt's *Good Strategy Bad Strategy* - specifically his kernel of diagnosis, guiding policy, and coherent action. The interview questions in `references/interview.md` are designed to push past the patterns he calls "bad strategy": fluff, goals dressed up as strategy, and feature lists in place of a guiding choice. The book is the recommended follow-up reading if the distinction between a slogan and a strategy is not yet sharp.

package/skills/ce-strategy/references/interview.md

@@ -0,0 +1,143 @@
+# Strategy Interview
+
+Loaded by `SKILL.md` at the start of Phase 1 and revisited per-section in Phase 2. Every section below maps one-to-one to a section in `strategy-template.md`.
+
+For each section: ask the opening question, evaluate the answer against the quality bar, push back when it falls into a named anti-pattern, and capture the final answer in the user's own language.
+
+## Overall Rules
+
+1. **Ask, don't prescribe.** Do not offer menu options for open answers (problem, approach, persona). Use free-form responses. Reserve multi-select for routing decisions.
+2. **Push back once, maybe twice.** If the first answer is weak, name the specific issue and ask a sharper question. If the second answer is still weak, capture what the user has given and note in the draft that the section is worth revisiting. Do not let the interview spiral.
+3. **Quote the user back at them.** When challenging an answer, use the user's own words verbatim. Paraphrasing softens the challenge and is easier to dismiss.
+4. **Keep each answer to 1-3 sentences.** Longer answers are usually hiding something vague. If the user writes a paragraph, ask them to pick the sentence that matters most.
+5. **Don't leak the anti-pattern names.** The user does not need to hear "that's a vanity metric" - just ask the sharper question that follows.
+
+---
+
+## 1. Target Problem
+
+**Opening question:** "What's the core problem this product solves - and what makes that problem hard?"
+
+Strong answers name a specific situation the target user is in, identify what makes the situation hard *right now* (a crux, a constraint, something that isn't easy to route around), and are falsifiable - you could imagine the problem being absent and know the difference.
+
+**Anti-patterns and pushback:**
+
+- **Goal stated as problem** ("the problem is we need to grow revenue") -> "That's a goal, not a problem. What's in the world that's making that goal hard to achieve? Whose situation are you changing?"
+- **Vague wish** ("people need better tools for X") -> "Whose situation specifically? Doing what? What do they try today, and why doesn't it work?"
+- **Symptom, not cause** ("users churn after 30 days") -> "That's a symptom. What's happening in their world that makes them stop caring? What's the underlying condition?"
+- **Too broad** ("communication at work is broken") -> "That's a civilization-scale problem. Narrow it to a situation you can actually affect - which users, doing what, when does it hurt most?"
+- **Feature-shaped** ("there's no good way to do [specific workflow] with AI") -> "That's a missing feature, not the underlying problem. What outcome do users want that the feature would give them?"
+
+**Capture:** One or two sentences naming the user's situation and the crux. No solution language.
+
+---
+
+## 2. Our Approach
+
+**Opening question:** "Given that problem, what's your approach - the commitment or principle that makes it tractable?"
+
+This is the guiding choice: how the product competes or operates, so that many downstream decisions become easier. It is not the product and it is not a feature list.
+
+Strong answers are a choice (implying alternatives explicitly *not* pursued), are general enough to direct many decisions but specific enough to rule things out, and sound more like "we win by [doing X differently]" than "we do [a list of things]".
+
+**Anti-patterns and pushback:**
+
+- **Fluff / values** ("we're customer-obsessed and move fast") -> "Those are values, not an approach. What are you doing *differently* from the other products users could pick? If the answer applies to any company, it's not your approach."
+- **Feature list** ("we're building AI-powered X, Y, and Z") -> "That's a feature list. What's the underlying bet that makes you pick those features over others? What principle is guiding what you ship?"
+- **Product description as approach** ("we use AI to draft replies") -> "That's what the product does, but what's the *choice* inside it? Every competitor will say the same thing. Your approach should name what you're doing that the obvious alternative isn't - is it a grounding choice, a trust-building commitment, a workflow bet? What are you betting on that they're not?"
+- **Goal restated** ("our approach is to be the market leader") -> "That's still the goal. How does the product win? What choice are you making that competitors aren't?"
+- **Multiple approaches at once** ("we're going deep on enterprise, self-serve, and a consumer app") -> "Pick one as the guiding approach. The others may still get work, but one of them organizes the rest. Which is it?"
+- **Doesn't connect to the problem** (problem: "users can't trust AI output"; approach: "build a fast, beautiful UI") -> "How does that approach solve the problem you named? If there's no line between them, one of the two is wrong."
+
+**Capture:** One or two sentences. Ideally ends with or implies "...so that [outcome tied to the problem]".
+
+---
+
+## 3. Who It's For
+
+**Opening question:** "Who is the primary user, and what job are they hiring this product to do?"
+
+Jobs-to-be-done framing - the user isn't a demographic, they're someone in a situation trying to make progress.
+
+Strong answers name one primary persona (additional personas allowed but secondary), identify them by role or situation rather than demographic, and state a concrete job as a verb phrase.
+
+**Anti-patterns and pushback:**
+
+- **Too many primary personas** ("it's for founders, PMs, engineers, and designers") -> "If it's for everyone, it's for no one. Who matters most? The others can still benefit, but one of them drives the product decisions."
+- **Demographic framing** ("25-45 year old professionals") -> "That's a demographic, not a user. What are they trying to do that makes them pick up this product?"
+- **Role without situation** ("PMs") -> "PMs doing what? Running a roadmap review? Writing a spec at midnight? Convincing a skeptical eng lead? The situation is where the product matters."
+- **Generic job** ("they want to be more productive") -> "Productive at what specifically? They're hiring this product to do *what*? The more specific, the better the product decisions downstream."
+
+**Capture:** Persona name plus JTBD sentence. Example: "Solo founders running their own roadmap. They're hiring the product to keep strategy and execution aligned without a PM on staff."
+
+---
+
+## 4. Key Metrics
+
+**Opening question:** "What 3-5 metrics will tell you whether the approach is working?"
+
+Metrics are the feedback loop. Bad metrics create the illusion of progress while the product gets worse.
+
+Strong answers stay at 3-5 (not 10), mix leading and lagging (something that moves weekly and something that moves quarterly), and could plausibly regress if the product got worse.
+
+**Anti-patterns and pushback:**
+
+- **Vanity metrics** ("total signups, total pageviews, cumulative users") -> "Those can all go up while the product gets worse. What moves when users actually get value?"
+- **Too many** ("here are 12 metrics we watch") -> "A dashboard isn't a strategy. Pick the 3-5 you'd stake the quarter on. What are the others telling you that those don't?"
+- **Outputs, not outcomes** ("ship velocity, deploys per week") -> "Those measure the team, not the product. If the team doubled velocity but users didn't care, would you call it a win?"
+- **Can only go up** ("cumulative hours saved") -> "A metric that can only go up doesn't tell you much. What's the rate, the ratio, or the thing that can regress?"
+- **Unmeasurable** ("user delight") -> "How specifically? If you can't define how you'd check it on a Tuesday, it's aspirational, not a metric."
+
+**Capture:** A list of 3-5. Each with a one-line definition. Note where each is measured (analytics, DB, qualitative, etc.) if known. If measurement is undefined, ask: "Where does this metric live today? If nowhere, is this something you can start measuring?"
+
+---
+
+## 5. Tracks
+
+**Opening question:** "What are the 2-4 tracks of work you're investing in to execute the approach?"
+
+Tracks are the coherent-actions half of the strategy kernel - concrete areas of investment that flow from the approach. They are not feature lists and not personal todo items. Each track is a named *domain of work*.
+
+Strong answers stay at 2-4 (not 8, not 1), connect clearly back to the approach, and are broad enough that multiple features live inside each one.
+
+**Anti-patterns and pushback:**
+
+- **Feature list in disguise** ("track 1: Slack integration; track 2: mobile app; track 3: dark mode") -> "Those are features. What's the *investment area* each one lives inside? 'Integrations' might be one track, with Slack, Teams, and Discord as candidates inside it."
+- **Too many tracks** ("we have 7 tracks this quarter") -> "With 7 tracks, every track is starved for attention. Which 3 are load-bearing? The others either fold in or drop."
+- **Doesn't connect to approach** (approach: "win by being the easiest to onboard"; track: "enterprise SSO") -> "How does that track serve the approach? If it's a separate bet, name it as one. If it's load-bearing for onboarding, explain the link."
+- **Too vague** ("improve the product") -> "Every track is 'improve the product.' What's the specific investment area that's different from the others?"
+- **One track only** -> "With one track, there's no real choice being made. What are the 2-3 things the product needs to be good at, and how are they different?"
+
+**Capture:** 2-4 tracks. For each: a name, a one-line purpose, and a short note on why this serves the approach.
+
+---
+
+## 6. Milestones (optional)
+
+**Opening question:** "Are there any dated milestones worth anchoring - a launch, a fundraise, a conference, a renewal? Skip if none apply."
+
+Only capture externally visible, real milestones. Avoid turning this into an internal schedule.
+
+Default is to skip. Do not push the user to invent milestones. If they name some, capture them verbatim with dates.
+
+---
+
+## 7. Not Working On (optional)
+
+**Opening question:** "Is there anything you've explicitly decided *not* to do right now that's worth naming? This is for things the team keeps being tempted by."
+
+Clarity tool, not a blocker list. Skip by default. If the user names items, one sentence each. Do not encourage a long list.
+
+---
+
+## 8. Marketing (optional)
+
+**Opening question:** "Any positioning or narrative language you want the doc to carry - a one-liner, a tagline, a key message? Skip if not yet."
+
+Skip by default. Keep to 2-3 lines if present.
+
+---
+
+## After the Interview
+
+Once sections 1-5 are captured (and any optional sections the user engaged with), read `strategy-template.md` and fill it in. Present the full draft in chat before writing. Offer one edit round. Then write to `STRATEGY.md`.