Northstar

A set of business-driven skills for Claude Code and OpenAI Codex — take a fuzzy request from a real stakeholder, turn it into decisions, a spec, and tracer-bullet tickets, then build them one focused session at a time.

New to all of this? Install, then jump to Start here — two commands and the pipeline explains itself.

Why

As AI grows more capable, it's easy to forget that we still operate within the boundaries of the engineering life-cycle. The temptation is to fight the complexity of frontier models with equally complex engineering workflows — and that temptation leads to disastrous results when you're shipping actual code, for actual customers, into a real production environment.

Now more than ever, grounding AI-assisted development in tried-and-true principles is the whole point: it's why a pipeline like this saves an enormous amount of time while keeping quality quantifiable and under control.

What working this way buys you

The pipeline starts before the code. Most engineering work doesn't begin with a ticket — it begins with a meeting, a document written by a non-technical stakeholder, a customer describing what they need. intake digests that raw material, the interview turns it into decisions, and every decision that clears the bar becomes an ADR recording who proposed it and who signed it off — a customer can be the approver. The paper trail is written for people who weren't in the room.

Every artifact is a file in the repo. Specs, ADRs, research, glossary, tickets — versioned next to the code they describe, readable by a human catching up and by an LLM loading project context in a future session. No issue tracker required; if the team has one, a one-line escape hatch maps spec → epic and tickets → stories.

The session is the unit of work. No skill runs the pipeline end to end. Each one is a session's worth of work with a hard boundary, and the value lives in those boundaries — a fresh context per ticket, a review that reads the spec instead of trusting the diff, an interview that isn't allowed to start building.

It teaches while it builds. The mentors — fullstack, Rust, C — consult mid-pipeline when an unknown concept blocks real work, run deliberate practice standalone, and grow their own reference shelf as genuinely new tech shows up. Sources are free official documentation; the knowledge layer stays copyright-clean.

Install

Guided (recommended): clone the repo, open Claude Code or Codex inside it, and ask the active harness to follow the installer skill:

git clone git@github.com:Memnoc/northstar.git
cd northstar
# start `claude` or `codex`, then:
# "read skills/install-northstar/SKILL.md and follow it"

It interviews you — Claude, Codex, or both; whole machine or one project; full set or a subset; and what to do with skills already installed — then runs the script with the right flags. Existing unrelated skills are never deleted, only moved to a dated backup.

Quick: skip the questions and take everything:

bash install.sh                                         # Claude → ~/.claude/skills/
bash install.sh --harness codex                         # Codex → ~/.agents/skills/
bash install.sh --harness both                          # both user-level locations
bash install.sh --only adr,to-spec,tdd                  # Claude subset
bash install.sh --harness codex --only adr,tdd          # Codex subset
bash install.sh --harness claude --dest .claude/skills  # project-local Claude
bash install.sh --harness codex --dest .agents/skills   # project-local Codex

For a project-local dual install, run the final two commands once each; --harness both deliberately cannot be combined with --dest. Re-run install.sh after every pull — installed copies are snapshots, not symlinks. Both harnesses detect skill changes; restart the active harness if newly installed skills do not appear.

Skill names below are harness-neutral. Invoke them with the harness syntax:

Claude Code:    /setup-northstar
OpenAI Codex:   $setup-northstar

The 27 skills/ directories follow the open Agent Skills format and remain the single workflow source. Harness extensions stay thin: Claude fields remain in SKILL.md, and Codex invocation policy lives in agents/openai.yaml, following the official Codex skill guidance and Claude skill guidance. Project guidance is canonical in AGENTS.md; the checked-in @AGENTS.md bridge follows Claude's project-memory guidance. Codex support targets the local CLI and IDE discovery paths directly; it does not require an OpenAI plugin or a one-time import command.

Start here

You've installed the set and you know nothing else about this style of development. That's fine — you need exactly two commands:

Start either harness in your project, invoke setup-northstar once to record the conventions canonically in AGENTS.md, then invoke guided-mode and describe what you want to build. A regular CLAUDE.md imports AGENTS.md, so Claude sees the same shared guidance while retaining any Claude-only content.

guided-mode is the whole onboarding. Describe your idea, your bug, or your pile of meeting notes in plain words; it figures out where you are, names the right entrance, and tells you what to invoke at every step from there. You never need to memorise the map — the map reads itself to you.

When you're curious what it's steering you through, a first feature looks like this:

adr-with-docs   # an interview sharpens your idea into decisions
compliance      # triage triggers; research and record applicable outcomes
to-spec         # same window — the thinking becomes a spec file
to-tickets      # same window — the spec becomes tracer-bullet tickets
                 # then, one FRESH session per ticket:
implement       # builds one ticket test-first, reviews it, commits it
                 # when every ticket is done:
harden          # rechecks compliance and walks every story end to end

Three habits while you learn: keep interview → compliance → spec → tickets in one unbroken window; give every ticket a fresh session (implement-all automates this — one sub-agent per ticket, pausing between them); when unsure, ask guided-mode. The fresh session isn't about saving tokens — each cold start proves the ticket's files can carry the work on their own, which is what keeps the repo, not the chat, the source of truth. Everything deeper — session boundaries, spikes, the big-effort on-ramp — lives in INSTRUCTIONS.md.

The mental model

No single skill runs the whole pipeline. Each one is a session's worth of work, and you drive the sequence. The value is in the boundaries between them, not in automating them away. When you're unsure where you are, guided-mode finds the entrance and shepherds the transitions.

The flow splits in two halves, and they deal in two different kinds of ticket — the distinction that matters most:

       DECIDE                 CLASSIFY                    BUILD
  ┌──────────────────┐   ┌─────────────────┐   ┌────────────────────────┐
  │ adr-with-docs    │   │ compliance      │   │ to-spec → to-tickets   │
  │ or pathfinder    │──▶│ triage/research │──▶│ implement → crosscheck │
  │ decision tickets│   │ evidence/verdict│   │ harden                 │
  └──────────────────┘   └─────────────────┘   └────────────────────────┘
    questions settle       obligations surface     software ships

• Decision tickets (pathfinder) are questions. They resolve into a decision, get closed, and leave one line on the map. Nobody builds them.
• Tracer-bullet tickets (to-tickets) are vertical slices of a build. Each is a thing that works end to end, living as files under .scratch/<spec-slug>/. These are what implement consumes.

A pathfinder map never becomes the build backlog. What crosses the gap is the map's Decisions so far index, which to-spec turns into a spec, which to-tickets slices into buildable work.

ADRs are receipts

Decisions worth keeping land in docs/adr/NNNN-slug.md — status / date / proposed-by / approved-by frontmatter, Context / Decision / Considered options, plus an index at docs/adr/README.md maintained on every write. An ADR is a receipt: who proposed a change, who signed it off (a customer can be the approver), and why — written for a stakeholder who was not in the room, read months later, by humans and by LLMs loading project context.

The write bar is a three-part gate — hard to reverse, surprising without context, a real trade-off — and all three must hold. adr, adr-with-docs, and pathfinder write them as decisions land; superseding an ADR edits the old one in the same change; every other skill reads them and flags contradictions instead of silently overriding.

The pipeline, step by step

setup-northstar runs once per repo — it writes the ## Northstar block into AGENTS.md and ensures Claude imports it through CLAUDE.md. After that, each feature walks this road:

  stakeholder material — meeting notes, transcripts, customer docs
       │
       ▼
  intake ············· optional front door → docs/intake/YYYY-MM-DD-<slug>.md
       │
       ▼
  adr-with-docs ······ the interview; glossary entries and ADRs land
   or pathfinder       as decisions are made (pathfinder when the effort
       │               is too big for one session: map + decision tickets)
       ▼
  compliance ········· shallow triage for every effort; triggers create
       │               current research + docs/compliance/<system>.md
       ▼
  to-spec ············ synthesize the thinking → docs/specs/YYYY-MM-DD-<slug>.md
       │               seams, user stories, compliance, links to the ADRs
       ▼
  to-tickets ········· slice the spec → .scratch/<spec-slug>/NN-<slug>.md
       │               tracer-bullet tickets with blocking edges
       ▼
  ┌── for each ticket, in a fresh session ─────────────────┐
  │                                                        │
  │   implement ──▶ tdd ·········· red-green at the seams  │
  │       │                        the spec called out     │
  │       ▼                                                │
  │   crosscheck ················· Standards + Spec review │
  │                                of the ticket's diff    │
  │                                                        │
  └── repeat until every ticket reads done ────────────────┘
       │
       ▼
  harden ············· re-run compliance, then walk every user story
       │               against the assembled system; failures become tickets;
       │               verdicts recorded in the spec
       ▼
  shipped ············ .scratch/<spec-slug>/ deleted; the spec, ADRs,
       │               and glossary stay as the permanent record
       ▼
  next ················ harvest Out of Scope + what shipping taught
       │                → docs/intake/YYYY-MM-DD-<spec-slug>-next.md
       │
       └─────────────▶ back to the interview: V2 walks the same road

Detours can hang off any step without breaking the flow: spike when a design question needs throwaway code, research when it needs cited facts, a mentor consult when an unknown concept blocks real work.

An existing repository does not need to enter or adopt the pipeline before it can be checked. Invoke compliance directly with its local path or hosted URL; the standalone branch audits current source and distributed releases and can write its evidence record without requiring other Northstar artifacts.

Underneath run two layers: domain-modeling (the glossary and ADR mechanics every step leans on) and the mentors — fullstack-mentor, rust-mentor, c-mentor — which consult mid-pipeline and run deliberate practice sessions standalone.

See INSTRUCTIONS.md for how to actually run this — exact session boundaries, context hygiene, when to spike, and a full walkthrough of pathfinder.

The mentors

Three skills — fullstack-mentor, rust-mentor, c-mentor — are not pipeline steps. They are the set's knowledge layer, and each works in two distinct ways:

As a trainer, standalone. Invoke one directly and it runs a deliberate practice session: socratic questioning, small programs against a strict quality bar, spaced-repetition quizzes on what you covered before. This mode has nothing to do with any project — it exists purely to make you better at the language.

As a Senior/Principal engineer on your project. Mid-pipeline, when an unknown concept blocks real work — a lifetime error you don't understand, a React effect misbehaving, an API design choice you can't weigh — the matching mentor consults: it explains the concept against your actual code, logs the topic for a later practice session, and hands control straight back to the work. You don't leave the pipeline to go learn; the expertise comes to where you're stuck. That specialisation is the point — a consult from the Rust mentor reasons like a principal Rust engineer, not like a general assistant.

Where their knowledge comes from. Every mentor is bound to free, official, current sources — and is required to verify against them before asserting anything, rather than trusting memory:

• rust-mentor — The Rust Book (official, continuously updated, and the source of truth for language rules), Rust by Example, and the Rust Cookbook.
• fullstack-mentor — the TypeScript Handbook, react.dev, MDN, the Node.js docs, Zalando's RESTful API Guidelines, and the System Design Primer.
• c-mentor — cppreference, Jens Gustedt's Modern C (free online), and the CERT C secure-coding standard.

Paid books are cited by title only, never distilled into the skills — the knowledge layer stays copyright-clean.

How they stay current. Each mentor grows its own reference shelf: the first time a genuinely new library, crate, or tool enters a session, the mentor finds its official documentation at the current version and appends it permanently to its references. One lookup per topic, recorded forever — the shelf compounds instead of the mentor re-searching or guessing.

You don't have to remember they exist. guided-mode routes to them: a Rust project blocked on a Rust concept gets steered into a rust-mentor consult — likewise for every mentor and any technology that benefits from its domain's patterns. The dividing line it uses: facts the project needs go to research; understanding you need goes to a mentor.

Spike and research

The other two detours answer questions the pipeline can't settle by talking — one by running something, one by reading something.

spike — throwaway code that answers a design question. The question decides the shape, and there are three:

• "Does this logic feel right?" — a tiny interactive terminal app that pushes the state model through the cases that are hard to reason about on paper.
• "What should this look like?" — several radically different UI variations on one route, switchable live, so you compare instead of imagine.
• "Does their API actually behave as documented?" — the probe: a small script that authenticates against the real or sandbox system, makes the calls in question, and prints the raw responses next to what the docs claim. Every divergence it finds is payload — it feeds the spec and the glossary's ## Mappings table. For connector work this branch is the workhorse: probe before you promise. (Never against destructive endpoints on a production system.)

Spikes are throwaway from day one: one command to run, no tests, no polish, no persistence. What survives is the verdict — captured into the spec's decisions or an ADR — while the code itself dies on a throwaway branch, out of main. If the spike produced a snippet that encodes the decision better than prose (a state machine, a schema, a type shape), the spec inlines that snippet and notes its origin.

research — delegated reading with receipts. A background agent investigates the question against primary sources only — official docs, source code, specs, first-party APIs, never a blog post summarising them — and follows every claim back to the source that owns it. You keep working while it reads. The findings land as a cited Markdown file in docs/research/<date>-<slug>.md, permanent like a spec: the interview can grill against it, and a future session can load it as context instead of re-reading the internet.

How to pick — the routing guided-mode applies for you: a question with a runnable answer goes to spike; a question with a readable answer goes to research; a gap in your own understanding goes to a mentor consult. Often it's two in sequence — research what the API claims, then spike to verify it.

Known limitations

• Northstar is designed and tested for Claude Code and the OpenAI Codex local CLI/IDE experience. Other clients that support the Agent Skills format may be able to read the skills, but their invocation and tool behaviour are not currently validated.
• The workflow structures an agent's work; it is not a deterministic workflow engine or a substitute for human review. Decisions, generated artifacts, code, and verification results can still be incomplete or wrong.
• Some skills depend on harness capabilities and external access. Delegated flows such as research, crosscheck, and implement-all need sub-agents; research and current-documentation lookups need network access; API probes and end-to-end hardening may need credentials and a runnable environment.
• The Compliance Round records current research, evidence, actions, and uncertainty. Its verdicts are engineering gates, not legal opinions or a substitute for qualified counsel. It can also audit an existing local or hosted repository without requiring Northstar project artifacts.
• Repository files are the only built-in system of record. Publishing tickets to Jira, GitHub Issues, Linear, or another tracker requires the active harness to have that integration and authentication; Northstar does not provide a tracker connector or keep local and remote tickets in sync.
• Installed skills are copied snapshots, so updates are not automatic. Re-run install.sh after pulling or editing Northstar, and restart the harness if the updated skills do not appear.
• Fresh-context boundaries are a practice rather than an enforced sandbox. Manual runs rely on the user starting a fresh session per ticket; implement-all relies on the harness's native sub-agent isolation.

Skills

Skill	Role
guided-mode	Active shepherd: finds your entrance, announces transitions, enforces the gates
intake	Digest meeting notes and stakeholder docs into interview-ready material
adr	Relentless one-question-at-a-time interview; offers gate-passing decisions as ADRs
adr-with-docs	The interview plus the paper trail: glossary and ADRs via domain-modeling
pathfinder	Chart big, multi-session work as a map of decision tickets in .scratch/
compliance	Triage specs, audit existing releases, and recheck evidence before shipping
to-spec	Synthesize the conversation into a spec in docs/specs/
to-tickets	Break a spec into tracer-bullet tickets with blocking edges
implement	Execute one ticket per fresh session, status kept current
implement-all	Autopilot: one fresh sub-agent per ticket, checkpointing between tickets
crosscheck	Two-axis review (Standards + Spec) in parallel subagents
harden	Post-ship verification: every user story walked against the assembled system
next	Harvest a shipped spec into intake material for the next version
tdd	Red-green discipline at the spec's seams, called by implement
domain-modeling	Glossary (CONTEXT.md), external-system Mappings, and ADR mechanics
spike	Throwaway code answering a design question: logic, UI, or API probe
research	Background agent → cited findings in docs/research/
fullstack-mentor	TypeScript / React / APIs / CRUD / system design — practice + consult
rust-mentor	Rust practice + consult
c-mentor	C practice + consult
deep-modules	Vocabulary for code shape: module, interface, depth, seam, adapter
deepen	Survey for deepening opportunities — visual HTML report, then interview
debug	Hard-bug discipline: no hypothesis without a red-capable loop
terse	Low-noise conversation mode — fluff dies, grammar survives
install-northstar	Guided machine-level install: scope, subset, clean slate, then install.sh
setup-northstar	Once per repo: records shared conventions in AGENTS.md
skillsmith	Reference for authoring portable Agent Skills and harness adapters

Origin and Credits

northstar began as an adaptation of Matt Pocock's skills — the interview, the spec, and tracer-bullet tickets are his ideas, written up at aihero.dev/skills. Every skill has since been rewritten and customised to fit different use cases; NOTICE carries the full attribution and the upstream-to-northstar name translations.

A special and heartfelt thank you to Matt and his team for the amazing work they have been doing for years in the community. I am an avid consumer of his courses and YouTube videos — you should check them out.