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.
The commands you invoke, in order — turning a vague brief into a spec worth trusting.
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.
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.
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.
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.
/discovery turns it into tickets
One prompt. Discovery clarifies ambiguities, reviews adversarially, and spawns one ticket per scoped piece of work.
/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.
Cortex scales its rigor to the work — and runs the phases that turn a feature into a real spec.
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.
Research phase 02
- 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.
Specify phase 03/critical-review before approval
status: refined written back to the ticket. /refine is done — /build picks it up here.
Plan /build · phase 04skipped on the short road
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.
Earn the spec, pick the harness.
If a spec earns it, this is what handoff looks like.
-
spec earnedlifecycle/{slug}/spec.mdall three refine phases locked. the orchestrator now has a tight enough spec to work without you.
-
/discovery — fan-outcortex/research/{topic}/research.mdruns 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
-
backlog · 5 ticketsbacklog/NNN-*.mddiscovery converges into named, refinable tickets.
-
/refine — per ticketclarify · 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
-
/overnight — parallel railsovernight-state.json · MCP serverorchestrator runs the tickets in parallel, one git worktree and branch each.
cortex-lifecycle-advancemoves each ticket's phase; work merges onto the session integration branch as each round's gate passes. -
/morning-review — convergelifecycle/morning-report.mdwalks the report with you · answers deferred questions · closes lifecycles · one session PR left to merge.
Inside /overnight · the safety contract.
Show the safety-contract figures
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.
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.
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.
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.
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.
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.
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.
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.
- 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
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
Interviews you and writes the project’s charter —
cortex/requirements/project.mdor 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.
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.
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.
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.mdandspec.md. If either is missing, it hands back to /refine.
Night line · many tickets, run while you are away
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.
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
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.
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.
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.
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
“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.
“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
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).
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.
- cortex-lifecycle-statetier · criticality · phase, from events.log
- cortex-common detect-phaselifecycle dir → current phase, plan progress
- 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
- cortex-refine emit-lifecycle-startseed lifecycle_start event
- cortex-lifecycle-counterstally for morning report
- cortex-complexity-escalatoropen-question signal · advisory
- advance spec-approveconsent + transition + write-back
- advance plan-decisionapproval + branch mode + transition
- advance review-verdictverdict → routed next phase
- cortex-lifecycle-nextserved state + advance contract
- cortex-git-sync-rebasesync + clean rebase
- cortex-jccjit commit-and-checkout
A phase boundary is six writes that must land in order, once. A prompt can't enforce that.
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.cortex-lifecycle-advance spec-approve. The arm takes the lock, re-reads the log, validates the gate, and appends every row under one invocation_id — no longer addressable as independent steps.state and routes on it; the sequence that produced it lives outside the prompt.from_state. No prose ceremony to forget, and no bad row to unwind.
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.
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
drag sideways to see the whole map
- 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
- 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.
Start with the core. It's complete on its own — add the rest as you want them.
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.
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.
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.
-
Install the cortex CLI
One command in your terminal — the bootstrap installs
uvfirst if it's missing.curl -fsSL https://raw.githubusercontent.com/charleshall888/cortex-command/main/install.sh | sh -
Add the marketplace
One command, run inside Claude Code.
plugin marketplace add charleshall888/cortex-command -
Install the plugins you want
Run
/plugin(or/plugins) and pick — or just paste:plugin install cortex-core@cortex-commandplugin install cortex-backlog@cortex-commandplugin install cortex-overnight@cortex-command
That's it. The skills are live in your session.
-
Set up each reporecommended
In each repo you work in, run
cortex init— it scaffolds thecortex/workspace and registers the sandbox path so the core skills (refine, build, backlog) and overnight all run cleanly, then tune per-repo preferences incortex/lifecycle.config.md.cortex init