cortex-command · landing.spec.mdR3 · 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 / 041
Part 1The Method
The commands you invoke, in order — turning a vague brief into a spec worth trusting, then a fork: hand it to the night, or ship it beside you.
§1.1 · the run
What gets run
You invoke these in order. /requirements sets the charter, /discovery fans it into tickets, /lifecycle carries one from spec to shipped — its front phases run alone as /refine. Underneath runs the charter — project.md — which every stage reads 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 returns a rapid sequence of questions that draw the real requirements out of your head and onto project.md. Watch the charter densify, a glossary term get minted, and an ADR spin off the moment a decision clears the gate.
Three durable layers, one interview: project.md holds the rules, glossary.md the words, cortex/adr/ the why.
HOW IT WORKS
Relentless questioning. Question-beams fire one at a time and a meter tallies them. Keep asking until the gaps are addressed.
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 fires it off
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.
§1.5
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.
sheet 02 / 042
Part 2The Rigor
Cortex scales its rigor to the work — and runs the phases that turn a feature into a real spec.
§2.1 · the patch atlas
Complexity earns ceremony. Simplicity skips it.
Two values in your spec — complexity and criticality — set how much rigor the work earns. The harness reads them and patches the lifecycle to match.
a simple change
adding a new lure
5gates
~200ktokens
~10 minwall clock
ships in one pass — no critical-review fork, no plan race, no escalated reviewer.
a critical change
the nightline game loop
10gates
~2Mtokens
~90 minwall clock
adversarial pre-plan review · two plans race for the winner · escalated Opus reviewer before merge.
§2.2 · /refine writes the spec · scrolls to lock4 gates · 0 of 4 cleared
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.
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.
§ 04
3/3risks named
R3
phase complete
Plan phase 04/critical-review available before approval
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 / 043
Part 3The Night Shift
What happens after you walk away — the overnight handoff in motion, and the safety contract that makes “work while you sleep” a claim you can check.
§3.1 · the overnight payoff · scroll to scrub
If a spec earns it, this is what handoff looks like.
spawns 4 research branches in parallel — one rail per reference signal
each ticket runs in its own claude window · clears spec → research → critical-review before a plan is approved
merges PRs · closes lifecycles · drops a morning-report.md you can skim with coffee
spec earned
lifecycle/{slug}/spec.md
all four phases locked. the orchestrator now has a tight enough spec to work without you.
/discovery — fan-out
lifecycle-research/{topic}/*.md
spawns research branches in parallel — one rail per reference signal.
discovery converges into named, refinable tickets.
/refine — per ticket
clarify · research · spec · plan · 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
/overnight — parallel rails
overnight-state.json · MCP server
orchestrator runs the tickets in parallel. read_spec → advance_phase per ticket. branches and PRs created as they pass critical-review.
/morning-review — converge
lifecycle/morning-report.md
merges PRs · closes lifecycles · drops a report you can skim with coffee.
draw
discoveryrefinenightdawn
—
—
§3.2 · /overnight · the safety contract
Inside /overnight · the safety contract.
Show the safety-contract figures7 figures · then pop the hood
Knows when to stop.
Three independent counters watch the run. zero_progress trips when nothing has advanced in 5 rounds. time trips at 10 hours. failures trips when the same ticket keeps blowing up. 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. The first retry runs on the same model; the next escalates to opus; the third hands off to a separate brain agent that decides SKIP, DEFER, or continue.
When even the brain can't decide cleanly, the harness writes ./deferred/<ticket>.md with what it tried and what it needs from you — then carries on with the rest of the queue. Three rungs, a judge, one calm exit.
retry → escalate → 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 at the seatbelt layer, not asked-for politely — the agent 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 phase transition writes overnight-state.json atomically before continuing. Close your laptop mid-run, lose power, kill the process — on restart, interrupt.py reads the last checkpoint, reconciles any half-finished branch, and resumes from exactly where it left off. No double-merges, no orphaned worktrees, no lost work.
atomic state · resumes cleanly
Tells you everything it did.
Five JSONL streams record everything during the run: phase transitions, agent spawns, retries, conflicts, and brain triage decisions. 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
fig 9 · gatefold · the overnight harness · claude code sdk inside
one harness.
dusk → night → dawn
22:00
dusk · refine + plan
dusk · 22:00
refine queue · overnight plan written · runner detaches
3 specs ready · plan.md immutable · cortex overnight start detaches as a Python process.
all three features merge. one runs rework; ci passes; review approves.
round 2 · 00:30 → 02:15
planner ④ · ralph loop exhausted · brain.py DEFER
feature ④ writes a blocking question to deferred/q001.md. integration held.
round 3 · skipped
dep gap — feature ⑤ depends on ④
planner ⑤ never runs. carried over to morning.
integration · 05:30
overnight/<sess-id> → main · test gate
3 features in · 2 carry over · session-end test gate (if armed).
dawn · 05:42
morning-report.md · session PR · /morning-review
3 merged, 1 paused, 1 deferred. walk the report; answer the blocking q; merge the PR.
sheet 04 / 044
Part 4The Toolkit
The deterministic CLI underneath the prose — why it exists, and the one command that installs all of it.
§4.1 · /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
01lifecycle state
cortex-lifecycle-statetier · criticality · phase, from events.log
cortex-common detect-phaselifecycle dir → current phase, plan progress
/lifecycle · /refine · /morning-review
02backlog i/o
cortex-resolve-backlog-itemid, slug, or title → filename
Five agents must read the same bytes. A prompt can't enforce that.
01 · setup
Five agents, one artifact.
/critical-review fans out four parallel reviewer angles plus an Opus synthesizer. All five must judge the same bytes.
02 · problem
The proof used to be prose.
Six in-context steps — validate path, compute SHA, dispatch, capture each sentinel, verify, log drift. Each one is a place a tired LLM can skip, paraphrase, or coerce "close enough."
03 · solution
We fused them into three calls.
prepare-dispatch, check-artifact-stable, check-synth-stable. Each call fuses validation + mutation in one subprocess — no longer addressable as independent steps.
04 · outcome
Consensus is enforced by the binary.
The orchestrator can't half-do the ceremony — there's no half. The proof that five agents read the same bytes lives outside the prompt.
the ceremony, collapsedsix prose steps · three atomic calls
A · without the CLI · six in-context steps
01validate path⚠ paraphrased
02compute SHA⚠ skipped
03dispatch ×5⚠ kept
04capture sentinel⚠ format drift
05verify SHA⚠ close enough
06log drift⚠ last-step amnesia
fuses→3 calls
B · with the CLI · three atomic subcommands
prepare-dispatch⊟ fuses 01 + 02
check-artifact-stable⊟ fuses 04 + 05 + 06
check-synth-stable⊟ fuses synth side
cost · same review · with and without the CLIper /critical-review pass
A · without the CLI · prose ceremony
0ktokens
six in-context steps × five agents · all bookkeeping, no review yet
collapses to→~30×leaner
B · with the CLI · three subprocess calls
0ktokens
structured output · and every byte verifiable across all five agents
drift caught · the payoff in motion
A reviewer's READ_OK sentinel carries a SHA. If the file moved while they were reading — concurrent edit, branch switch, partial save — that SHA won't match the pin from prepare-dispatch. check-artifact-stable notices, atomically appends sentinel_absence to events.log, and excludes the reviewer's findings from the synthesizer's payload. No prose ceremony to forget.
01cortex-critical-review prepare-dispatch plan.md
02{ sha256: "a7c4e1f9b2d83e0f…" } pinned into 5 prompts
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.3 · what installs · 3 plugins · one CLI underneath
Start with the core. It's complete on its own — add the rest as you want them.
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, /lifecycle runs each one down the same track, a gated stop at every phase, to a shipped PR.
02recommended · 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.
overnight requires the backlog
03optional · 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 start4 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
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.
4
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 (lifecycle, refine, backlog) and overnight all run cleanly, then tune per-repo preferences in cortex/lifecycle.config.md.