/north-star

name: north-star
version: 0.2.1
description: Step 0 for going from 0 to 1 in any new project, business, or pivot. Conducts a structured 3-question self-interview, produces a 3-5 sentence paragraph artifact at docs/00-north-star.md plus a build log capturing the full session and consolidated positioning context for downstream skills. Drift-mode supported. Cross-model review required at lock. Designed to prevent identity drift during early-stage builds.

/north-star — turn the founder's feelings and intentions on day 1 into a locked day-1 artifact

When to use

At the very beginning of a new project, business, or pivot, before brand, scope, or implementation work. Or later, in **drift mode**, when the existing north-star isn't working anymore and the founder explicitly wants to revise.

Skip for: features (those use the project's `feature` skill if one exists), pure technical decisions (use ADRs directly), marketing campaigns (downstream).

What it produces

Three artifacts:

1. **`<project>/docs/00-north-star.md`** — a short paragraph (3 to 5 sentences) capturing what / why / for-whom, the approach, and the philosophical posture. YAML frontmatter at the top makes the paragraph machine-readable for downstream apps. Real-world mission statements (Patagonia, Amazon) are 1 to 3 sentences; aim there. The 3-to-5-sentence count is the authoritative bar; line count is incidental.

2. **`<project>/docs/build-logs/north-star-v{N}.md`** — full session record: founder's verbatim answers to each interview question, scratch synthesis attempts, cross-model review findings, draft evolution v1 to vN with rejection reasons, and a consolidated **Positioning context for downstream skills** section.

3. (Optional) **1 to 3 foundational ADRs** in `<project>/docs/adrs/` for durable bright-line decisions surfaced during the interview that warrant separable, citable records.

Downstream skills (e.g. `feature`) read (1) and (2) at requirements-gathering time to check alignment before scoping new work.

Hard rules

1. **Self-interview, not interrogation.** Capture the founder's literal language. Don't paraphrase, don't generate from templates, don't put words in their mouth. 2. **Pointed questions, not vague ones.** Each question elicits a *felt* answer, not an analytical one. 3. **No drift into brand, voice, pricing, scope, or marketing.** All downstream. If the founder veers, redirect with a script: *"That's worth holding onto, but for now I'm parking it. Right now I'm only after what / why / who and the deepest beliefs. We'll come back to that."* Park stray thoughts in build-log notes. 4. **Short artifact.** 3 to 5 sentences in the paragraph. Resist the urge to produce a polished document; polish comes through months of iteration. 5. **Read aloud or it doesn't ship.** The founder reads the paragraph aloud. If it sounds like them, lock. If not, edit. 6. **Founder edits the file directly once a draft exists.** Iterate the first draft conversationally in chat. The moment a working draft exists, open `docs/00-north-star.md` in their editor (`code <path>`, `$EDITOR <path>`, or whatever they use) and let them edit there. Quality jumps once the founder is in their own editor; chat-based list confirmations are explicitly forbidden. 7. **Positive commitments only in the artifact.** No "we don't" or "we are not for" framing in the paragraph; that reads judgy. Specific anti-patterns to avoid in synthesis:

• Defensive hedging in the headline (e.g. *"...not get skinny"* — even if the founder said it, putting it in the headline turns the orientation into an argument with the customer's possible motivations)
• "We don't do X" framing in beliefs (replace with positive commitments that imply the bright line)
• "Who we are NOT for" as a section heading (use *"What to expect"* or fold into positioning context as expectation-setting)

Bright lines and counter-personas live in the build log's positioning-context section. 8. **Locked-but-revisable.** Drift-mode re-run requires the founder to explicitly name what's drifted; old version is archived, not deleted. 9. **Ideal pace is one sitting, no hard cap.** Most runs land in one focused session. Some genuinely take two. There is no enforced limit; if a session is going long, take a break and resume rather than rushing. 10. **Stop-or-go is allowed.** If Q3 (founder-market fit) makes the founder realize they shouldn't be building this, surface that, don't push through to a locked artifact. *(This rule is designed but not yet exercised in real-world use.)* 11. **Cross-model review is required at lock; optional at any point during the run.** Mid-flight reviews (single different-model agent at any point the interviewer or founder wants a sanity check) caught real drift in the inaugural run. The pre-lock review is a fan-out across multiple models (Sonnet + Opus + Haiku) for confidence on the final paragraph. See Phase 4. 12. **Build log uses verbatim quotes for founder language.** When the interviewer's notes summarize what the founder said, mark it explicitly as a summary; the verbatim founder answers are the source of truth for downstream skills. Don't paraphrase silently. 13. **Founder overwhelm is a course-correction trigger.** If the founder says *"this is a lot,"* *"this is overwhelming,"* or similar, stop the current approach and find a smaller surface. Don't push through. The most common moment this fires is when the interviewer is presenting list-mode confirmations; the right correction is to skip lists and let the founder react to a draft instead.

14. **Trace logging is env-var opt-in.** If `BRAINTRUST_API_KEY` is set, the skill accumulates interview transcripts, draft versions, cross-model reviews, and the lock event in `/tmp/claude/north-star-traces-<project-slug>.jsonl`, then flushes to the configured braintrust project via `npm run flush-traces` in Phase 6. Without the env var, all logging no-ops. Traces are private (braintrust SaaS); the `<consu