| name | north-star |
| description | Use to derive, persist, and propagate a "North Star" project compass (mission, non-goals, constraints, principles) for autonomous agents. Trigger via `/north-star`, "set project compass", or during `/orchestrator-mode` boot if missing. Inputs: repo signals (README, manifests, CHANGELOG) + user signoff. Produces `docs/NORTH_STAR.md` and a MemPalace mirror. Do not use for roadmaps, sprint plans, or feature scoping; use planning/strategy skills instead. Escalate on conflicting docs or missing write access. Auto-injected into delegate briefs via orchestrator-mode. |
North Star
Derive, persist, and propagate the project compass that an autonomous agent uses to make tradeoffs without re-asking the user.
Evidence tier: P (practitioner-backed)
Basis: Amplitude's North-Star Framework (one mission + leading indicators + non-goals); constitutional anchoring for agentic autonomy (Anthropic's constitutional-AI, OpenAI's spec-driven agents); Solo MCP + MemPalace durable-memory conventions used by orchestrator-mode in this registry.
Source IDs: amplitude.com/north-star, anthropic/constitutional-ai, naoray/skills orchestrator-mode, orchestrator-handoff, references/state-surfaces.md.
Reviewed: 2026-05-13
Why this skill exists
/orchestrator-mode keeps asking the user "what matters here, what's the goal, can I act autonomously?" because no durable answer is loaded at boot. The fix is not a smarter orchestrator — it's a persisted artefact the orchestrator (and every delegate brief) reads automatically. North star is that artefact.
It is NOT a roadmap, sprint plan, or feature list. It is the decision rule: "when two valid paths fork, pick the one that serves for without violating or ."
The artefact — docs/NORTH_STAR.md
Six sections, all required. Full template + worked example: references/template.md.
- Mission — one sentence. Verb-led. What this project is for.
- Target users / adopters — who. Specific enough to disqualify someone.
- Non-goals — what this project explicitly will NOT do. Decision shortcuts.
- Hard constraints — tech / legal / budget / perf / compatibility. Non-negotiable.
- Decision principles — 3-7 priority-ordered rules. Used when constraints don't decide.
- Success + anti-signals — what going right looks like; what going wrong looks like.
Stays under ~80 lines. If it grows past that, it's a roadmap — split it.
Storage — two surfaces, one canonical
| Surface | Role | Loaded by |
|---|
docs/NORTH_STAR.md | Canonical. Versioned in repo. Survives without MCP. | Delegates in anvil worktrees; orchestrator after cd <repo>. |
MemPalace drawer north-star in wing=<project> | Mirror. Cross-session anchor. | Orchestrator at boot before repo open; cross-project search. |
The repo file is source of truth. The MemPalace drawer mirrors it and references the file path. Never edit the drawer without updating the file; the consult workflow rejects drift.
Why both: delegates work inside isolated worktrees that may not have MemPalace MCP. Orchestrator may boot before any repo is open. Each surface covers a real gap.
Route
Read this file. Then read exactly one of:
- workflows/derive.md — author a north star by inspecting the project (no existing file). Inspection → draft → user signoff → persist both surfaces.
- workflows/refresh.md — update an existing north star. Delta-only — propose changed sections, user signoff per section, write back.
- workflows/consult.md — read the north star and inject it into orchestrator-mode boot + every delegate brief. Read this when wiring downstream consumers.
Cross-cutting rules
- User-approval gate is non-negotiable. A north star drafted without user signoff is a hallucination. Why: it becomes load-bearing for every downstream decision; an unreviewed draft poisons the well. Workflows must print the draft, wait for "approved" or per-section edits, then persist.
- No silent file creation. First write of
docs/NORTH_STAR.md requires user confirmation of path. Why: some projects use .github/, docs/specs/, or STRATEGY.md instead; auto-creating the file conflicts with existing conventions.
- Drift check on consult. When
consult.md loads the file, it diffs mtime of docs/NORTH_STAR.md vs the MemPalace drawer's last update. On drift, prompt the user to reconcile — never silently prefer one surface.
- Delegate brief injection is automatic. Every coding/slash-cmd brief template in
orchestrator-mode/workflows/dispatch.md gets a ## Project north star section auto-populated by consult. Delegates do not derive — they obey.
- Refresh, don't append. New decisions update relevant sections in-place. Append-only changelogs belong in
CHANGELOG.md, not here.
Anti-patterns
- North star as feature roadmap. Becomes stale every sprint; agent then ignores it. Mission + principles only — features go elsewhere.
- No non-goals. Without exclusions, every direction is "aligned" and the artefact decides nothing.
- MUSTs without WHY. Decision principles must include their rationale; an unjustified rule is rationalised away at the first hard tradeoff.
- Persisting before approval. A draft is not a north star. The user's "yes, that's right" is the persist trigger.
- Embedding contents in every brief inline. Delegates read the file path. Inline copies drift; the path stays canonical.
- Auto-deriving on every
/orchestrator-mode boot. Boot CHECKS for existence; only PROMPTS if missing. Silent derivation creates files the user did not request.
See also
- references/template.md — the artefact template + a worked example for a real project
- workflows/derive.md — full inspection → draft → persist procedure
- workflows/refresh.md — delta-update procedure
- workflows/consult.md — read + propagate procedure (orchestrator-mode boot, delegate brief injection)
orchestrator-mode/SKILL.md — the primary consumer; boot step 1 invokes consult.mdorchestrator-mode/workflows/dispatch.md — brief templates that auto-inject north starorchestrator-mode/references/state-surfaces.md — the broader state-storage conventionevals/trigger.csv, evals/checks.md
