cortex-command · landing.spec.md R3 · live document · MIT

A Claude Code harness that earns its autonomy.

Deep research, then interrogation — until the spec is extracted from your head onto the page. An orchestrator agent with a tight spec and a solid harness can be trusted to work while you sleep.

sheet 01 / 04
Part 1 The Method

The commands you invoke, in order — turning a vague brief into a spec worth trusting.

§1.1 · the run

What gets run

You invoke these in order. /requirements sets the charter, /discovery fans it into tickets, then each ticket runs in two halves — /refine earns the spec, /build ships it, and /dev picks which half a ticket needs.

/requirements interview → charter /discovery research → tickets /refine /build clarify research specify plan implement review complete spec.md ticket → approved spec spec → shipped PR project.md (the charter) — every stage reads it to stay on course

Get step zero right and everything after it stays on course. Skip it and discovery fans out on guesses, every spec earns the wrong edges, and the overnight build ships the wrong thing — fast.

§1.2 · step zero · the interrogation bench

The interrogation bench  ·  /requirements

Give it a brief — vague or detailed — and it asks the questions that get the real requirements out of your head and onto project.md. As you answer, the charter fills in, new terms are added to the glossary, and any decision that is hard to reverse is written up as an ADR.

/requirements i want an overnight fishing game vague brief ? ? ? questions project.md scope ✓ philosophy · calm, not grindy constraints · browser-only → 0007 boundaries · in / out / deferred quality · 60 fps, no jank glossary.md +1 phase-transition the words adr/0007 proposed accepted 3-criteria gate the why

Three durable layers, one interview: project.md holds the rules, glossary.md the words, cortex/adr/ the why.

HOW IT WORKS

  • It keeps asking until nothing else needs your judgement. Questions that don't depend on each other come in one batch, grouped by section, and each one leads with a recommended answer — so you confirm or redirect instead of writing from scratch. Anything the codebase already answers is confirmed, not asked.
  • An ADR spins off at the gate. When a decision is hard to reverse · surprising · a real trade-off, the interview proposes an ADR (lands proposed, promotes to accepted at merge). The project.md row keeps only a → 0007 back-pointer; the ADR owns the rationale.
  • Progressive disclosure keeps context lean. project.md stays terse and always-loaded; the why lives in ADRs and the words in the glossary, pulled in on demand only when a stage needs them. Downstream agents read the rule, not the whole backstory.
§1.3

/discovery turns it into tickets

One prompt. Discovery clarifies ambiguities, reviews adversarially, and spawns one ticket per scoped piece of work.

§1.4

/refine each ticket separately

Refinement turns a scoped ticket into a buildable spec. Each ticket lands with shared scope, cited prior art, and pinned acceptance criteria — the things that prevent rework once code starts.

sheet 02 / 04
Part 2 The Rigor

Cortex scales its rigor to the work — and runs the phases that turn a feature into a real spec.

§2.1 · how much rigor a ticket earns

Complexity earns ceremony. Simplicity skips it.

Two values on the ticket — complexity (simple · moderate · complex) and criticality — set how much rigor the work earns. /refine sets them in Clarify, then re-checks them once the research is in; every stage after that reads them and patches the track to match. Below moderate there is no track at all: simple work is implemented on the spot.

moderate · low
adding a new lure
5phases
1research agent
0review gates
ships in one pass — one codebase-only research agent, no plan phase (spec goes straight to implement), no adversarial fork, no review phase.
complex · critical
the nightline game loop
7phases
6research agents
2review gates
six-angle research ending in an adversarial pass · /critical-review before the spec is approved · two or three plans race for the winner · a builder implements it · a review phase before merge.
§2.2 · the track, gate by gate · scrolls to lock 4 gates · 0 of 4 cleared
§ 01
3/3 scope agreed
R3
phase complete

Clarify phase 01the lifecycle's first phase

status: drafting → locked · acceptance: scope agreed
[ pending — scroll to capture from interview ]
What does it feel like to set a nightline well? Player loop: choose tackle → cast at dusk → set depth → leave the line → return at dawn. Fish simulated overnight. Catch determined by depth, bait, weather, patience. Scope-in: a satisfying choice + a morning the night actually paid for.
§ 02
3/3 refs cited
R3
phase complete

Research phase 02

status: collecting → locked · 4 sources cited
[ pending — research bullets resolve here ]
  • Stardew Valley: tight skill window, instant feedback.
  • Animal CrossingSea of Thieves: fishing as social ritual.
  • Dredge: dread, reward, depth as risk axis.
  • Real-world nightline: hooks set at dusk, retrieved at dawn — a sleep-while-you-fish craft.
§ 03
3/3 OUTCOME NAMED
R3
phase complete

Specify phase 03/critical-review before approval

status: resolving → locked · acceptance criteria pinned
[ pending — system + edge cases resolve here ]
Tackle: 3 rod tiers, 6 lure types, 4 bait types. Depth: 1–5 fathoms. Weather modifies catch table per fathom. Overnight simulation: discrete tick at midnight resolves bites against a Markov model parameterized by depth/bait/weather. Morning UI: animated reveal of the line being pulled. Edge cases: empty, snagged, legendary.
cortex/lifecycle/{slug}/spec.md spec approved · status: refined written back to the ticket. /refine is done — /build picks it up here.
§ 04
3/3 risks named
R3
phase complete

Plan /build · phase 04skipped on the short road

status: drafting → locked · 5 tasks · 1 named risk
[ pending — implementation order resolves here ]
Implementation: (a) tackle data model + UI, (b) cast/set screen, (c) overnight resolver, (d) dawn reveal animation, (e) catch encyclopedia. Acceptance: a player who sets a line and sleeps wakes to a result that feels earned. Risk: the resolver carries the loop. Mock it badly and the loop collapses.
sheet 03 / 04
Part 3 The Night Shift

The spec is earned — now pick the harness. What happens after you walk away, and the safety contract that makes “work while you sleep” a claim you can check.

§3.1

Earn the spec, pick the harness.

specs/ · 4 ready
nightline-loopLR3
dawn-revealMR2
tackle-progressionXLR5
weather-tablesSR1
option a · overnight harness
ships by morning, while you sleep
/overnight batches it. A scheduled overnight process runs on the CLI and orchestrates the full pipeline — with safeguards and error handling — then /morning-review hands you a full summary of what was done.
option b · guided lifecycle
ships with you, in-session
One ticket at a time, planned and shipped with you in the terminal. Optionally runs in an isolated worktree so your working tree stays clean.
§3.2 · the overnight payoff · scroll to scrub

If a spec earns it, this is what handoff looks like.

runs 4 research agents at the same time — one per angle
each ticket runs in its own claude window · clears clarify → research → spec, with /critical-review before the spec is approved
walks the report · answers deferrals · closes lifecycles · hands you one session PR to merge
  1. spec earned
    lifecycle/{slug}/spec.md
    all three refine phases locked. the orchestrator now has a tight enough spec to work without you.
  2. /discovery — fan-out
    cortex/research/{topic}/research.md
    runs several research agents at the same time — one per angle.
    • → Stardew Valley · feedback-loop ref
    • → Sea of Thieves · social-ritual ref
    • → Dredge · depth-as-risk ref
    • → real-world nightline · sleep-while-you-fish craft
  3. backlog · 5 tickets
    backlog/NNN-*.md
    discovery converges into named, refinable tickets.
  4. /refine — per ticket
    clarify · research · spec (+ /critical-review)
    each ticket clears its own gates. five tickets → five tight specs.
    • → tackle data model
    • → cast/set screen
    • → overnight resolver
    • → dawn reveal anim
    • → catch encyclopedia
  5. /overnight — parallel rails
    overnight-state.json · MCP server
    orchestrator runs the tickets in parallel, one git worktree and branch each. cortex-lifecycle-advance moves each ticket's phase; work merges onto the session integration branch as each round's gate passes.
  6. /morning-review — converge
    lifecycle/morning-report.md
    walks the report with you · answers deferred questions · closes lifecycles · one session PR left to merge.
draw
discovery refine night dawn
§3.3 · /overnight · the safety contract

Inside /overnight · the safety contract.

Show the safety-contract figures 7 figures · then pop the hood

Knows when to stop.

Three independent stop conditions watch the run. zero-progress trips when two consecutive rounds merge nothing. time trips at --time-limit — six hours by default. The stall watchdog trips when a child stops making progress at all: 30 minutes of inactivity, or a four-hour absolute ceiling that never resets. Any one of them ends the run cleanly — saves state, writes the report, exits — instead of churning until your wallet or your repo notices.

three circuit breakers · zero-progress · time · watchdog

Climbs when stuck — stops calmly when it can't.

Failed gates don't loop blindly. A failure that's worth another go runs again with the previous attempt's learnings appended — each retry is a fresh process, so nothing carries over but the notes. A refusal or an infrastructure failure skips the retries entirely and pauses on the spot. When the attempts are spent, a separate brain agent triages: SKIP, DEFER, or PAUSE. There is deliberately no RETRY verdict — it would re-enter the caller that just gave up.

A DEFER writes deferred/<slug>-q001.md with what it tried and what it needs from you — then carries on with the rest of the queue. Four attempts, a judge, one calm exit.

try → retry → triage → calm pause

Stays in its lane.

Each ticket runs in its own git worktree on its own branch. The agent can’t reach main, can’t touch packed-refs, can’t read other repos, and has its tool list pinned ahead of time. The fence is enforced by the OS sandbox, not by asking the agent nicely — it literally cannot do the things outside it.

sandboxed by design · seatbelt-enforced

Schedules around conflicts. Heals what slips through.

Conflicts are mostly prevented before they happen. /overnight reads each ticket's file list and groups tickets into rounds so no two tickets in the same round touch the same file — and dependencies wait for their predecessors to finish. When a conflict still slips through, the harness uses a graded heal: trivial conflicts (whitespace, imports, non-overlapping hunks) take a fast-path stamp; real conflicts get exactly one bounded repair attempt, then defer. No infinite repair loops, no surprise force-pushes.

round scheduler · graded heal

Survives interruption.

Every state write lands atomically — tempfile plus os.replace(), so a reader sees the old bytes or the new bytes, never a torn mix. Close your laptop mid-run, lose power, kill the process — on restart, interrupt.py inspects each still-running ticket's worktree, logs an interrupted event with the evidence it found, and hands the ticket back to the queue as pending. No double-merges, no orphaned worktrees, no half-applied state.

atomic state · resumes cleanly

Tells you everything it did.

Five append-only JSONL streams record the run at five different scopes: session events, per-task dispatch and merge outcomes, per-feature phase transitions, per-turn agent tool calls, and the worker↔orchestrator escalation channel. Each has exactly one writing module, so ownership can't drift. At dawn they're collated into a single morning-report.md — what merged, what was skipped and why, what's waiting for you. Every decision is auditable; nothing happens off the record.

five logs · one morning-report
sheet 04 / 04
Part 4 The Toolkit

Every skill and how they connect, the deterministic CLI underneath them, the dashboard that draws your backlog and docs, and how to install it all.

§4.1 · /skills · the skill map

Every skill, and how they connect.

You can run any skill by itself. Some skills also start other skills. To go from an idea to reviewed code, run /requirements, /discovery, /refine and /build in order. Hover over a skill to see what it does, or click it to read its file.Each skill below says what it does and what it works with.

sheet 4.1 · skill maphover to see what a skill does · click to read its SKILL.md
use inside any skill /dev picks one of these reads hand-back · not refined main line night line /dev front door /requirements the charter /discovery → tickets /refine → spec /build → code /overnight unattended /morning-review after a run /interview grilling loop /research 1–6 agents /critical-review 1–2 reviewers /backlog-author one ticket body /backlog the ticket list /pick you choose /hmm that didn't land
  • main line
  • night line
  • calls a helper
  • /dev can send you here
  • lines cross, not a link
  • reads the same backlog
  • use inside any skill

nothing selectedNot sure where to start? Run /dev. It reads your request and picks the right skill for you.

Front door · picks the right skill

  • /devfront door · cortex-core · you or the modelSKILL.md

    Routes a request. With no arguments it triages the backlog (“what’s next”). A vague topic goes to /discovery; a simple change it does right there; otherwise /refine if there’s no spec yet, or /build if the ticket is refined. A batch of three or more larger features goes to /overnight.

    on its own
    When you know what you want done but not which skill does it.
    with other skills
    Sends you to /discovery, /refine, /build, or /overnight. Its triage reads the same backlog that /backlog manages.

Main line · from an idea to reviewed code

  • /requirementsmain line · cortex-core · slash command onlySKILL.md

    Interviews you and writes the project’s charter — cortex/requirements/project.md or an area doc — plus glossary terms.

    on its own
    Set down what the project is for, or what one area of it must do.
    with other skills
    Comes first, before any tickets exist. Runs /interview’s loop to ask its questions.
  • /discoverymain line · cortex-core · you or the modelSKILL.md

    Investigates a topic, then breaks it into backlog tickets grouped by epic. It ends at tickets, not a spec.

    on its own
    Turn a fuzzy area of work into a set of concrete tickets.
    with other skills
    Calls /research to investigate and /backlog-author to write each ticket body. Its tickets are what /refine takes next.
  • /refinemain line · the night line starts here · cortex-core · you or the modelSKILL.md

    Takes one ticket through Clarify → Research → Spec, then marks it status: refined. It stops at the spec.

    on its own
    Get an approved spec for a ticket without building anything yet.
    with other skills
    Delegates its research phase to /research; runs /critical-review on the spec when the ticket is complex and criticality is medium or higher. Then hands off to /build — or leaves the ticket ready for /overnight.
  • /buildend of the main line · cortex-core · you or the modelSKILL.md

    Takes a refined ticket through plan → implement → review → complete.

    on its own
    Build one ticket you’ve already refined.
    with other skills
    Needs the ticket’s research.md and spec.md. If either is missing, it hands back to /refine.

Night line · many tickets, run while you are away

  • /overnightnight line · cortex-overnight · you onlySKILL.md

    Picks eligible refined tickets, shows you a session plan to approve, then hands off to an unattended runner.

    on its own
    Queue up a batch of refined tickets and let them run while you’re away.
    with other skills
    Runs after /refine, instead of you running /build on each ticket. /morning-review goes through the results.
  • /morning-reviewend of the night line · cortex-overnight · you onlySKILL.md

    After a run: walks you through the morning report, collects your answers to deferred questions, advances finished lifecycles to Complete, and closes their tickets.

    on its own
    Settle what happened during a run, one item at a time.
    with other skills
    Comes after /overnight. Files follow-up tickets through /backlog-author.

Helpers · other skills start them · each also works alone

  • /interviewhelper · cortex-core · you or the modelSKILL.md

    A structured grilling loop to think a topic through. It recommends an answer before asking, lets the codebase answer what it can, and ends in a brief.

    on its own
    Think a decision through before any ticket exists.
    with other skills
    /requirements runs this loop.
  • /researchhelper · cortex-core · you or the modelSKILL.md

    Sends 1–6 agents down independent angles of a question and synthesizes what they find into research.md.

    on its own
    Investigate any question and keep the findings as a document.
    with other skills
    Called by /discovery and by /refine’s research phase.
  • /critical-reviewhelper · cortex-core · you or the modelSKILL.md

    Adversarial review: 1–2 reviewer agents on distinct angles, then a synthesis. It pressure-tests a plan, a spec, or a research doc.

    on its own
    Point it at any plan, spec, or research doc you want attacked.
    with other skills
    Called by /refine’s spec gate.
  • /backlog-authorhelper · cortex-core · you or the modelSKILL.md

    Writes one ticket body: Why, Role, Integration, Edges, Touch-points.

    on its own
    Turn a note into one well-formed ticket.
    with other skills
    Called by /discovery for each ticket, and by /morning-review for follow-ups.

Any time · use inside any other skill

  • /pickany time · cortex-core · you, or the model on “either is fine”SKILL.md

    “You choose.” Hands a fork back to Claude. A small call, it just decides. Missing information, it researches, then decides. An open question, it sends out agents, synthesizes, and commits. A call that is genuinely yours — taste, priorities, risk — it asks you again, plainly.

    on its own
    Any time you’d otherwise say “either is fine.”
    with other skills
    Works inside any other skill. It changes how the conversation goes, not what gets built.
  • /hmmany time · cortex-core · you onlySKILL.md

    “That didn’t land.” Claude backs up and re-explains the last stretch in plain words, leading with the context you’re missing and using the project’s glossary terms.

    on its own
    The moment an explanation loses you.
    with other skills
    Works inside any other skill. Only you can start it; Claude never does.

The backlog · the ticket list

  • /backlogcortex-backlog · you or the modelSKILL.md

    Add, list, pick, or archive backlog items.

    on its own
    Manage the ticket list by hand.
    with other skills
    No skill runs it. /dev reads the same backlog when it triages, and the other skills create and update its tickets.

Installed names carry their plugin, e.g. /cortex-core:refine; this map writes them short. Not shown: android-dev-extras, a separate optional plugin (android-cli, edge-to-edge, r8-analyzer).

The skill file as it is on main right now, read straight from the repo — the exact text Claude loads.


    
§4.2 · /cli · the bench

Prose skills wander. The CLI is the toolkit that doesn't.

A Cortex skill is prose — and prose, under fatigue or context drift, paraphrases, skips, coerces "close enough." Every skill shells out to deterministic cortex-* subcommands for the parts that can't. Three guarantees a prose skill alone can never give you.

consistentatomic ops · same output every time fasterone subprocess vs many tool calls ¢token-efficientpinned values · structured output
01 lifecycle state
  • cortex-lifecycle-statetier · criticality · phase, from events.log
  • cortex-common detect-phaselifecycle dir → current phase, plan progress
/build · /refine · /morning-review
02 backlog i/o
  • cortex-resolve-backlog-itemid, slug, or title → filename
  • cortex-update-itematomic frontmatter write-back
  • cortex-backlog-readyreadiness-gate filter
  • cortex-load-parent-epicwalk discovery_source frontmatter
/refine · /build · /overnight · /dev
03 events · gates
  • cortex-refine emit-lifecycle-startseed lifecycle_start event
  • cortex-lifecycle-counterstally for morning report
  • cortex-complexity-escalatoropen-question signal · advisory
/refine · /build · /morning-review
04 phase transitions ★ DEEP DIVE ↓
  • advance spec-approveconsent + transition + write-back
  • advance plan-decisionapproval + branch mode + transition
  • advance review-verdictverdict → routed next phase
  • cortex-lifecycle-nextserved state + advance contract
/refine · /build
05 commit · git ops
  • cortex-git-sync-rebasesync + clean rebase
  • cortex-jccjit commit-and-checkout
/build
§4.3 · why we built this

A phase boundary is six writes that must land in order, once. A prompt can't enforce that.

01 · setup
Approving a spec is not one write.
It re-reads the log, checks the gate, records consent, routes the spec exit for this ticket's tier, and writes status: refined plus the spec path back to the ticket — which regenerates the backlog index. Order matters, and a resumed session must not replay any of it twice.
02 · problem
The ordering used to be prose.
Six in-context steps — read the phase, validate it against the expected one, append consent, append the transition, write the ticket back, regenerate the index. Each is a place a tired LLM can skip, reorder, or run twice.
03 · solution
We fused them into one arm.
cortex-lifecycle-advance spec-approve. The arm takes the lock, re-reads the log, validates the gate, and appends every row under one invocation_idno longer addressable as independent steps.
04 · outcome
Ordering is enforced by the binary.
The orchestrator can't half-do the ceremony — there's no half. It reads back one state and routes on it; the sequence that produced it lives outside the prompt.
the ceremony, collapsedsix ordered writes · one atomic arm
A · without the CLI · six in-context steps
01read current phase⚠ stale read
02check expected gate⚠ close enough
03append consent row⚠ replayed twice
04append transition⚠ wrong order
05write ticket back⚠ paraphrased
06regenerate index⚠ last-step amnesia
fuses 1 arm
B · with the CLI · one atomic arm per boundary
advance spec-approve⊟ fuses 01 → 06
advance plan-decision⊟ the plan boundary
advance review-verdict⊟ the review boundary
drift caught · the payoff in motion The prose believes the feature is at specify. The event log says research — a sibling session moved it, or a resume replayed out of order. Rather than write a transition from a phase that isn't current, the arm refuses: it returns the mismatch and the remedy, and appends nothing. The orchestrator re-syncs against the served state and re-invokes with the real from_state. No prose ceremony to forget, and no bad row to unwind.
01cortex-lifecycle-advance spec-approve --decision approved
·holds the lock · re-reads events.log · validates the gate
02refused · expected specify, log says research — 0 rows written
·preferred_remedy: re-sync against the served state
03cortex-lifecycle-next my-feature → state: research
04advance spec-approve --from-state research
05committed · consent + transition + write-back, one invocation_id

This pattern repeats across the whole bench. Lifecycle state, backlog reads, atomic event appends, gate transitions — every operation that needs to be the same every time lives behind a subprocess. The CLI is how the framework makes "consistent" a property you can prove.

§4.4 · /dashboard · backlog and docs

Your backlog and your docs, drawn as maps.

The Backlog page shows which tickets are ready, which are blocked, and what blocks them. The Docs page shows your requirements and the decisions they cite, so you can see how your project works. It also follows overnight runs. Everything comes from the files in your repo, with no account and no database.

Cortex Dashboard

Mac app

Run cortex dashboard once and this app appears. After that, open it from Spotlight, Launchpad or the Dock.

Backlog · epics and blockers

epic #40 Overnight line-setting 1 ready · 3 blocked

drag sideways to see the whole map

BLOCKERS FROM OUTSIDE #38 IN PROGRESS Save-file format v2 #41 READY Tide table data model #42 BLOCKED Cast-and-anchor controls #43 BLOCKED Bait drawdown while lines are out #44 BLOCKED Resolve the night's catch on wake
  • ready or in progress
  • blocked
  • blocks a ticket in this epic
  • blocks from outside this epic

Hover over or tap a ticket to see its details. Each arrow comes from a blocked-by: line in a ticket’s file.

Docs · requirements and decisions

drag sideways to see the whole map

cited by project.md cited by fishing.md not cited by any doc INSTRUCTIONS PROJECT AREAS DECISIONS CLAUDE.md INSTRUCTIONS Nightline instructions cites 1 project.md PROJECT Requirements: Nightline cites 1 · cited by 1 fishing.md AREA Requirements: fishing cites 2 save-data.md AREA Requirements: save data cites 1 audio.md AREA Requirements: audio cites nothing ADR-0002 ACCEPTED Simulate the night on wake cited by 1 ADR-0003 ACCEPTED Seed catches once a night cited by 2 ADR-0004 SUPERSEDED Lines snap after 6 hours cited by no doc ADR-0006 ACCEPTED Line tension decays cited by 1
  • parent doc
  • cites
  • replaces
  • requirements
  • decision (ADR)

Hover over or tap a doc to see what it says and light up its links. Each arrow comes from the doc’s own text: a Parent doc line, a link, or a mention like ADR-0003.

§4.5 · what installs · 3 core plugins · one CLI underneath

Start with the core. It's complete on its own — add the rest as you want them.

01 How to install required · complete on its own

cortex-core

One simple plugin gives you the rails to build a project end to end. You set the direction in /requirements, then /discovery breaks ideas down into small bodies of work. From there, /refine earns each one an approved spec and /build runs it down the same track, a gated stop at every phase, to a shipped PR.

02 recommended · swappable backend

cortex-backlog

Plain-markdown tickets the cortex-* CLI reads and writes directly — token-cheap and fast, which is why it's the recommended default. The harness is built around it, but a repo can point its config at a different backend like GitHub Issues — just not as fast.

03 optional · autonomy

cortex-overnight

Runs through the Claude Code SDK to plan and implement refined tickets in batches while you sleep. Skip it if you only want to work in-session.

quick start 4 steps · CLI first, then inside Claude Code
  1. Install the cortex CLI

    One command in your terminal — the bootstrap installs uv first if it's missing.

    curl -fsSL https://raw.githubusercontent.com/charleshall888/cortex-command/main/install.sh | sh
  2. Add the marketplace

    One command, run inside Claude Code.

    plugin marketplace add charleshall888/cortex-command
  3. Install the plugins you want

    Run /plugin (or /plugins) and pick — or just paste:

    plugin install cortex-core@cortex-command
    plugin install cortex-backlog@cortex-command
    plugin install cortex-overnight@cortex-command

That's it. The skills are live in your session.

  1. Set up each reporecommended

    In each repo you work in, run cortex init — it scaffolds the cortex/ workspace and registers the sandbox path so the core skills (refine, build, backlog) and overnight all run cleanly, then tune per-repo preferences in cortex/lifecycle.config.md.

    cortex init
Achievement
Spec Earned
all three refine phases locked · ready for handoff
Achievement
First Light
overnight run completed before you woke up