EpicSpine · EpicTeam · EpicSocial
Part 1 · Three intuitions

EpicSpine

Talk. It becomes a plan.
The memory is the repo.

A skill that turns loose chat into a tracked goal tree, kept as plain files in git next to the code, so every agent and every human picks up exactly where the last one stopped.

Scroll down like a page, or step with ← → or Space; press G for the part-grouped index. Three plain intuitions come first; Part 5 is the technical part. Deep-link with #5. Diagrams do the explaining; the text is only a caption.

One loop: talk, plan, delivery, outcome A loop around the repo: you chat loosely, the chat becomes a goal tree, steps are delivered by agents, an outcome is written that you approve, and you talk again; every turn is written down in the repo. Talk loose chat Plan a goal tree Delivered owner + status Outcome you approve all in the repo plain files + git
Part 1 · Three intuitions · binding

Every agent knows what it is for.

Manager

Plans, never builds

Turns what you ask into a goal and steps, hands each step out, and checks what comes back.

Writer

Drafts, then waits

Writes in your voice from the research it was given, and stops for your yes before anything goes out.

Reviewer

Checks against the goal

Judges the work by the done means you agreed, not by taste, and says why in one line.

Before it acts, each agent binds: it reads its goal, where things stand and the rules you taught it. That is where its clarity comes from.

Part 1 · Three intuitions · relentless

It goes as far as the code can.

Keeps going

Step after step

When one step is verified, the next one starts. Nobody has to remember to ask.

Unsticks itself

Wakes find what stalled

A worker stops, a lease runs out, a test turns red. A scheduled wake notices and starts it again.

Stops for you

Only where you matter

A decision, a look at something live, a yes to publish. Everything else is already done when you arrive.

You are needed only where a step truly needs a person. The rest of the way, the team does not wait.

Part 1 · Three intuitions · together

Ask once. Everyone pushes for it.

You ask

Say it loosely

“Google sign-in before Friday, and don’t break email login.” That is enough to start.

They conspire

Everyone takes a side

The manager plans, workers build, the reviewer checks. Each one pushes the same goal from where it stands.

The line moves

You see where it is

The goal file says what is done, what is running and what waits on you, at any hour.

It feels like summoning people who want what you want and keep moving the line forward with you.

Part 2 · What and why · why

Agents lose the plot between chats.

Chat fades

Intent disappears

Long projects drift when the only memory is a transcript no future agent will read completely.

Issues are narrow

Tickets lack the whole story

A ticket is excellent for one bounded step, but too narrow to carry scope, direction and acceptance.

Roles blur

Agents overreach

Workers start planning, reviewers rewrite, and state gets buried in comments. The system needs boundaries.

The fix is two ideas: talk becomes a plan, and the memory is the repo.

Part 2 · What and why · idea 1

Talk. It becomes a plan.

Say it loosely. It is structured for you into goals that are tracked and delivered.

What you say

You · 09:02users keep asking for Google sign-in
09:03don't break the email login though
09:05can it be live before Friday's launch?
09:06and always run the e2e tests before merging
structured
for you

What the repo keeps: a goal tree

acme-approot goal
EPIC-3 Billingdone
EPIC-4 Google sign-in in progress
GoalSign in with Google, live before Friday; email login keeps working.
Done means Google button on the login page Email login still passes its tests You check it live
Steps S1 OAuth app · worker done S2 Login button · worker running S3 Live check · you waiting
NowS1 merged. Next: S2, then your check.
Learning L-2always run e2e before merging
Chat on any node later: it lands back here
Goalfrom your words
→
Steps deliveredeach has an owner + status
→
Outcome writtenwhat was achieved
→ YOU APPROVE ✓

Unstructured in, structured out. Nothing said is lost; everything said becomes trackable.

Part 2 · What and why · idea 2

The memory is the repo.

Goals, status, decisions and lessons are plain files, committed in git next to the code.

① Agents write

M
Managergoal, steps, current state
W
Workerdone + evidence, outcome
R
Reviewera decision + its why
You
You, correcting oncebecomes a permanent rule
commit
② The repo: files + git history
acme-app/
├─ src/ ← the code
└─ docs/ ← the memory
   ├─ EPIC-0-root.md
   └─ EPIC-4-google-sign-in.md
## Decisions
03-12 Google only, Apple later
      why: 9 of 10 asks name Google
## Operating Learnings
L-2 Always run e2e before merging
git log
a41c9e2 EPIC-4 S1 OAuth app verified
7be03d1 L-2 learned: e2e before merge
19f0c55 EPIC-4 created from chat
bind

③ A new agent starts

--bind EPIC-4
The goalGoogle sign-in by Friday
Where it standsS1 done, S2 running
What was decided, and whyGoogle only: 9 of 10 asks
Rules learnedL-2 e2e before merging

In seconds. No handover call.

Repo = the truth: goals, state, decisions, learnings, outcomes a separate database Versioned, reviewable, on any machine.

Status and lineage travel with the code. Any new agent binds and has the whole build trace.

Part 2 · What and why · the file under both ideas

One living spine carries intent; everything else carries detail.

Three surfaces: spine, tickets, code and tests Layer stack: the spine owns intent, tickets own step detail, code and tests are truth; intent falls down the stack and the durable consequence rises back up. INTENT CONSEQUENCE INTENT Spine mission · scope · acceptance · decisions · state DETAIL Tickets one bounded step each; deep technical detail lives here TRUTH Code and tests what exists and what passed; evidence outranks old docs Keep a detail in the ticket if it helps only that step; summarize the durable consequence back into the spine. LEGEND Authoritative intent Detail and truth Intent falls Consequence rises

Readskill/epic-spine/SKILL.md

Part 2 · What and why · the cycle

Intent to issues to proof to Book, then round again.

The core loop Loop: intent becomes issues, issues become code and tests, verified work is integrated and landed in the Book, and the Book informs the next intent; each pass writes durable state back to the spine. DECISIONS EVIDENCE STATE Intent why + acceptance Issues one bounded step Code + tests worker, worktree Integrate verify, ff-merge Book what we now know Root spine Current State Every pass writes its durable consequence into the spine, so the next agent binds from the record and not from the chat. The Book is the loop's memory of understanding: what we now know, not what we did. LEGEND Where the loop starts Stage Work advances Writes state back

Readskill/epic-spine/SKILL.md skill/epic-spine/references/book-companion.md

Part 3 · Basic principles

Eight principles everything else follows from.

◆
One authoritative intentThe spine owns why, scope, acceptance and decisions.
▸
Issues are executable ticketsOne bounded step each; the deep detail lives there.
✓
Code and tests are truthObserved evidence outranks any older document.
◎
The manager never implementsCoordinate, dispatch, verify, integrate, report.
✦
Fresh-context workersEach runs one task in its own wt/<task> worktree.
⟶
Stay in main and verify firstff-only merge, tests in main, revert on red.
⌘
Learnings are explicit and scopedRead Always at bind; propose, never write silently.
✂
Lean, tidy, documentedDelete before adding; clean as you integrate; land knowledge in the Book.

Source of truth: the Default Behaviors card in skill/epic-spine/SKILL.md and the root spine's Always list.

Part 4 · Feature map

Everything the skill does, and where to dig in.

Talk becomes a planChat structured into a goal tree.Idea 1 → The memory is the repoPlain files in git; bind and know.Idea 2 → Core loopIntent, issues, proof, Book.Loop → Spine modelOne intent; authority by artifact.Surfaces → Profiles: compact / fullDocument size control.Anatomy → Dialect v1 / v2Acceptance workflow; SHIP / HARDEN.Anatomy → Hierarchy + rollupsRoot to child; one level up.Hierarchy → Bind pathAGENTS.md, root spine, branch spine.Bind → Roles + dispatchManager and worker; who writes where.Roles → Dispatch profileAsk once, record it, reuse it.Profile → Ask-first + ready frontierSettle forks, then launch.Dispatch → Git doctrineWorktree, ff-only, revert on red.Git → Two-axis verificationStandards and spec.Verify → LearningsExplicit, scoped memory.Learnings → Validation toolingStructural and graph checks.Tooling → Hygiene + sweepsClean as you go.Hygiene → Skill installOne hub, linked per harness.Install → Always-on bindA bind line on every harness.Always on → Skill updatesFreshness by content, at bind.Updates → Book companionChapters, leaves, contract.Book → Shortlists + HTML servingJSON to table-first page on 127.0.0.1.Shortlists → Ticket backendsGitHub default; local files.Backends → Ticket lifecycleDraft to done, plus two off-path states.Lifecycle → Draft until stamped readyOnly the user readies; the repo delivers itself.Stamp → One task end to endGoal to merged and recorded.Sequence → MigrationFull to compact, hash-gated.Tooling → Dogfood invariantSkill, spine and Book move together.One repo →
Part 5 · How it works, technically · 1 of 20

A spine is small on purpose.

Anatomy of a spine Layer stack of a spine document from header to learnings and spine map, with the Current State section expanded into the ten fields it carries. EXPANDS Current State carries Owner Status Last attempted Result Evidence Waiting on Approved work Next action Source revision Verified at DECLARED Header ID · repo · doc · branch REQUIRED Current State the one cursor, read first REQUIRED Mission · Non-Goals why, and what it is not REQUIRED Definition Of Done epic-wide acceptance REQUIRED Issue Ledger · Decisions tickets, resolved forks WHEN NEEDED Learnings · Spine Map if it owns rules/children Profile (compact or full) sets the size; dialect (v1 or v2) sets the acceptance surface: SHIP and HARDEN. LEGEND The one cursor Section Record of fields Expands into

Readskill/epic-spine/references/spine-model.md skill/epic-spine/references/compact-state.md skill/epic-spine/references/sprint-dialect-v2.md skill/epic-spine/assets/compact-spine-template.md

Part 5 · How it works, technically · 2 of 20

One root. Children own local truth.

Root, children, rollups Tree: one root spine registers two child spines, each owning two issues; each child rolls one compact row up to the root. ROLLUP ROW ROLLUP ROW Root spine one canonical root Child spine A own state and ledger Child spine B own state and ledger Issue A-1 ticket Issue A-2 ticket Issue B-1 ticket Issue B-2 ticket Never copy a descendant's ledger or deep history into an ancestor. LEGEND Spine document Ticket Registers / owns Rolls up one level

Readskill/epic-spine/references/execution-rollups.md skill/epic-spine/references/spine-model.md skill/epic-spine/references/persona-tasks.md

Part 5 · How it works, technically · 3 of 20

Bind first. Then read three hops.

Bind first, then read three hops Flow of what a fresh agent reads at bind: AGENTS.md, then the root spine, then only the branch spine for its task, ending in the visible bind line; everything else is not read until a task matches. NOT READ AT BIND; LOADED ONLY WHEN THE TASK MATCHES ROOT PATH SCOPE MATCH BIND LINE AGENTS.md router + always-on block; no live state Root spine Current State + Learnings: Always Branch spine Current State, Decisions, Ledger First reply role + Learnings in force Other branch spines sibling missions Scoped learnings only matching triggers Book leaves on demand Skill references Load On Demand table If role, spine or issue is unclear: orient read-only, then ask before editing. LEGEND Read at bind Visible result Not read at bind Read order

Readskill/epic-spine/SKILL.md skill/epic-spine/references/role-protocols.md

Part 5 · How it works, technically · 4 of 20

Independence comes from fresh context.

Delivery manager and worker Architecture: the user gives a goal to the delivery manager, who dispatches one worker into its own worktree, verifies the handoff, merges to main and records state in the root spine. SHARED CHECKOUT · MANAGER ONLY WORKER WRITES HERE ONLY GOAL REPORT DISPATCH HANDOFF RECORD FF-ONLY MERGE EDITS User states the goal Delivery manager coordinate · dispatch verify · integrate · record Worker one task never merges Root spine Current State main one tested line wt/<task> its own worktree The manager's checkout stays on clean main; every edit happens in a worker worktree. LEGEND You Delivery manager Worker Artifact Dispatch Write Return

Readskill/epic-spine/references/roles-and-dispatch.md skill/epic-spine/references/dispatch-prompts.md skill/epic-spine/scripts/claim.py skill/epic-spine/assets/dispatch-prompt-preamble.md

Part 5 · How it works, technically · 5 of 20

Task instruction beats repo profile beats default.

Which worker runs the task Layer stack of dispatch profile precedence: a per-task user instruction beats the repository's recorded Dispatch profile, which beats the built-in lower-cost native subagent default; an unavailable profile stops the work. PRECEDENCE UNAVAILABLE If the profile's tool or model is unavailable stop and say so · propose a concrete substitute · never substitute or implement silently 1 · HIGHEST This task's instruction a different model, provider, mechanism, reasoning 2 · REPO Dispatch profile: in the root spine asked once if unset, then recorded and reused 3 · FALLBACK Built-in default lower-cost native subagent · worktree-first · disjoint waves LEGEND Recorded per repo Layer Failure rule If unavailable

Readskill/epic-spine/references/roles-and-dispatch.md

Part 5 · How it works, technically · 6 of 20

Settle the forks. Launch only the ready frontier.

Before dispatch: settle forks, launch the ready frontier Flowchart: the manager settles facts by reading and running, asks the user one real fork at a time and records it, then dispatches only tickets whose dependencies are done and whose write surfaces are disjoint. NO YES YES NO New task Settle facts read the repo, run it; facts are never asked Real fork? not a fact Ready frontier? deps done Dispatch profile + binding Ask one fork with a recommendation, then record in Decisions Sequence it wait for blockers or a disjoint write surface Facts are settled by reading and running; decisions belong to the user. LEGEND Start Outcome Step Decision Flow

Readskill/epic-spine/references/roles-and-dispatch.md skill/epic-spine/references/role-protocols.md

Part 5 · How it works, technically · 7 of 20

Stay in main. Isolate execution. Merge verified.

Worktree lifecycle and integration Flowchart: a worker creates wt/task from clean main and commits there, hands off; the manager verifies, fast-forward merges, tests in main, then removes the worktree on green or reverts on red and re-dispatches. WORKER DELIVERY MANAGER HANDOFF YES NO RE-DISPATCH Create worktree git worktree add wt/<task> from main Implement commit only in the worktree; run checks Verify diff and checks; rebase if main moved ff-only merge clean main checkout; one merge at a time Tests green? run in main Clean up remove worktree and local branch git revert then re-dispatch a fix Clean-repo end state: one branch, one worktree, clean status, no stray remotes. One merge at a time; serialise branches that touch MANIFEST.sha256. LEGEND Step Gate Flow Re-dispatch

Readskill/epic-spine/references/git-doctrine.md

Part 5 · How it works, technically · 8 of 20

Verify on two axes before anything merges.

Two-axis verification Quadrant of repository standards against the ticket spec: only when both axes pass does the manager integrate; any other cell is rework with a stated reason. Rework standards not met Integrate ff-only merge, test in main Rework neither axis met Rework spec not met SPEC PASS · STANDARDS FAIL BOTH PASS BOTH FAIL SPEC FAIL · STANDARDS PASS STANDARDS tests · validators · lean SPEC the ticket's acceptance Verify against the repository, the diff and the checks: never the worker's summary. One failing axis sends the work back, with the reason stated. LEGEND Integrate Rework More of the axis met

Readskill/epic-spine/references/roles-and-dispatch.md

Part 5 · How it works, technically · 9 of 20

Memory, at the depth where it applies.

Operating Learnings Tree: the root spine's Operating Learnings section splits into the Always list, read in full at bind and capped at twelve lines, and the Scoped index, which points to child spines and Book leaves that own deeper rules. Operating Learnings section of the root spine Always every task; read in full at bind; hard cap 12 lines one learning per line Scoped index one row per scoped learning: an applies-when trigger and a pointer Child spine its own learnings Book leaf deeper rules Precedence: the user's instruction beats a deeper learning, which beats a shallower one. Any agent proposes; only the steward writes. LEGEND Root section Part of the section Deeper scope Contains / points to

Readskill/epic-spine/references/learnings.md

Part 5 · How it works, technically · 10 of 20

Documents have a contract. Checks prove it.

Validation and tooling Architecture: two groups of tools, spine-document tools and repo-and-install tools, with no sequence implied between them. SPINE DOCUMENTS REPO AND INSTALL validate_spine.py document contract, required data, state conflicts; --graph adds the hierarchy checks rollup_spine.py projects direct-child facts into the parent, with source-hash receipts migrate_spine.py conservative full-to-compact migration behind a reviewed source hash tests + MANIFEST + CI unit, smoke and drift tests; the manifest gate that keeps the install in sync skill_update.py status, pin, verify, atomic upgrade of the installed copy; freshness by tree hash agents_block.py always-on block: repo files and, via global_install.py, every harness on the machine No sequence is implied between these tools. Validation proves the document contract and the checks, never that a product shipped. LEGEND Script Gate

Readskill/epic-spine/references/structural-validation.md skill/epic-spine/references/execution-rollups.md skill/epic-spine/references/operating-model.md skill/epic-spine/scripts/validate_spine.py skill/epic-spine/scripts/spine_fix.py skill/epic-spine/scripts/close_rows.py skill/epic-spine/scripts/tree_audit.py skill/epic-spine/references/tree-cleanse.md

Part 5 · How it works, technically · 11 of 20

Leave the repo clean and the next agent a map.

Hygiene and resumability Flowchart: after integrating, the manager removes the worktree and branch and records state; if a sweep is due it dispatches one, otherwise the repo is already clean. YES NO LAST SWEEP Integrated Remove worktree and local branch, right now Record Current State + Ledger so any agent can resume Sweep due? stale or clutter Dispatch sweep cheap worker brief; skips active worktrees Clean repo one branch, clean status Sweep when Last sweep is absent or over 7 days, clutter exists, or the user asks. Never sweep while integrating; pass the sweep the active worktrees to skip. LEGEND Start End state Step Decision Flow

Readskill/epic-spine/references/hygiene.md skill/epic-spine/assets/sweep-brief.md

Part 5 · How it works, technically · 12 of 20

One source, installed once, linked everywhere.

One source, installed once and linked per harness Architecture: the canonical skill source upgrades one installed hub, every harness entry is a symlink to that hub, and a vendored copy in another repo is a snapshot that is re-synced rather than upgraded. UPGRADE RE-SYNC Canonical source skill/epic-spine/ deployed from main Installed hub ~/.agents/skills/epic-spine one real copy Claude Code symlink to the hub OpenCode symlink to the hub Codex symlink to the hub Vendored copy snapshot in another repo; re-sync per SYNC.md A plain per-harness copy also works; upgrade the hub and every link follows. LEGEND Source The one real copy Harness entry Vendored snapshot Upgrade Link

Readskill/epic-spine/references/skill-update.md SYNC.md

Part 5 · How it works, technically · 13 of 20

Bound on the first reply, on every harness.

Always-on bind on every harness Architecture: install-global writes a pointer to the live global block into every harness's user-level file plus a session-start hook that injects it, install writes the thin repo block and pointer files, and both make the first reply open with the bind line. ONCE PER MACHINE ONCE PER REPO WRITES WRITES install-global agents_block.py global_install.py Instruction files + hooks each harness's user-level file, plus a session-start hook where one exists install agents_block.py per repo Thin AGENTS.md block + pointers CLAUDE.md, GEMINI.md point at it; Cursor and Copilot get a copy First reply Delivery manager · EpicSpine · Learnings in force: <ids> Installed once, it binds every agent on every harness, even in a repo with no spine. A harness with no user file or hook is reported as unsupported, never skipped silently. LEGEND Installer Written file Visible result Writes / feeds

Readskill/epic-spine/assets/agents-block.md skill/epic-spine/assets/global-block.md skill/epic-spine/scripts/agents_block.py skill/epic-spine/scripts/commit_msg.py skill/epic-spine/scripts/global_install.py skill/epic-spine/scripts/install_guard.py skill/epic-spine/scripts/pre_commit.py

Part 5 · How it works, technically · 14 of 20

Freshness is checked by content, once a day.

Freshness check at bind Flowchart: at bind the manager runs the skill update status check; fresh carries on, linked or unknown reports one line, and stale follows the Skill updates policy: auto upgrades between tasks, manual asks first. STALE FRESH OTHER AUTO MANUAL At bind Check freshness skill_update.py status; cached for 1 day, else a blobless tree check Status? fresh, stale, else Skill updates: auto or manual Carry on No action linked or unknown: one line, no nagging Upgrade shallow clone, verify vs MANIFEST, atomic swap, rewrite the pin Ask first report staleness, then upgrade if told Freshness is the skill tree's content hash, not the VERSION label or the head commit. Auto upgrades between tasks, never mid-task; off never checks. LEGEND Start / stop Step Decision Action Flow

Readskill/epic-spine/references/skill-update.md skill/epic-spine/references/session-sync.md skill/epic-spine/scripts/skill_update.py skill/epic-spine/scripts/session_sync.py skill/epic-spine/scripts/repo_sync.py skill/epic-spine/scripts/fetch_guard.py skill/epic-spine/scripts/vendored_skill.py skill/epic-spine/scripts/stop_push.py skill/epic-spine/scripts/codex_hooks.py skill/epic-spine/scripts/rehook.py skill/epic-spine/scripts/background_sync.py skill/epic-spine/scripts/local_mess.py skill/epic-spine/scripts/local_servers.py skill/epic-spine/scripts/auto_return.py skill/epic-spine/scripts/deploy_gate.py skill/epic-spine/scripts/merge_trust.py skill/epic-spine/scripts/repo_state.py skill/epic-spine/scripts/sync_schedule.py skill/epic-spine/assets/epicspine-profile.md

Part 5 · How it works, technically · 15 of 20

The spine owns development. The Book owns understanding.

Book shape and navigation Tree: a shallow Book root links to chapters and each chapter to its leaves, with every link navigable in both directions; an optional canonical registry feeds a view in the root. BOTH WAYS VIEW Book root shallow: goal, chapter map Chapter one durable domain Chapter one durable domain Leaf one question Leaf one question Leaf one question Leaf one question Canonical registry optional; row per item Every leaf links back to its chapter and the Book root; this deck is this repo's Book root. LEGEND Shallow root Chapter or leaf Optional registry Links both ways Feeds a view

Readskill/epic-spine/references/book-companion.md

Part 5 · How it works, technically · 16 of 20

Declare it once. Every bound agent then authors.

The Book companion contract Flowchart: a repository declares the Book active, every bound agent becomes a Book author, results pass a landing test, land as an updated or new leaf, then reciprocal links are validated and the reply carries the leaf link. YES NO Declaration AGENTS.md or root spine: Status: active Every agent authors inspects the Book at bind, no extra request Landing test worth keeping? Land the leaf reuse before creation: update in place, else create under a chapter Stay in chat or the issue Link + validate chapter and root links; declared check passes Reply with the link Landing test: durable after the chat, evidence-backed, navigable, worth returning to. An author without root or registry authority proposes the promotion to the Book steward. LEGEND Declared Step Test Stops Flow

Readskill/epic-spine/assets/book-companion-contract.md skill/epic-spine/references/book-companion.md

Part 5 · How it works, technically · 17 of 20

A shortlist is a first-class deliverable.

Shortlist pipeline Data flow: shortlist JSON is the source of truth, build_shortlist.py renders table-first HTML, a local server on 127.0.0.1 serves it, and the user's choice is written back to the JSON and recorded in Decisions. DECIDES REBUILD shortlist JSON shortlists/*.json source of truth build_shortlist.py stdlib, offline; embeds the data Table-first HTML sortable, filterable never hand-edited Local server 127.0.0.1 only; HTTP 200 verified You clickable URL Choose or reject status chosen / rejected; rejectedReason required Decisions table one dated row in the bound spine Choices are never silent: status in the JSON, then a dated row in Decisions, then the URL. Any HTML artifact is served from 127.0.0.1, never a file path. LEGEND Source of truth Script Artifact Local server You Flows Rebuilds

Readskill/epic-spine/references/shortlists.md skill/epic-spine/assets/shortlist.template.html skill/epic-spine/assets/shortlist-sample.json skill/epic-spine/references/artifacts.md

Part 5 · How it works, technically · 18 of 20

GitHub by default. Local files when declared.

Ticket backends Architecture: in the default github backend the Issue Ledger points at GitHub issues that own live status; in the declared local backend the ledger holds references and dependencies and each ticket file owns status, owner and evidence. GITHUB · THE DEFAULT BACKEND LOCAL · A DECLARED FILE BACKEND POINTS AT POINTS AT Issue Ledger concrete issue URLs; status cells are snapshots GitHub issue owns the live status, assignment, evidence Issue Ledger references and deps only; Ticket root declared Ticket file owns Status, Owner, and Evidence Offline, a valid URL never proves the issue is current. Unknown status terms such as closed are rejected, not mapped. LEGEND Ledger in the spine Owner of the live ticket Points at

Readskill/epic-spine/references/ticket-backends.md skill/epic-spine/assets/github-issue-template.md

Part 5 · How it works, technically · 19 of 20

A ticket moves from draft to done on evidence.

Ticket lifecycle State machine: a ticket moves from draft to ready, active, review, testing and done, with blocked as a side state of active; superseded and deferred are off-path states that the documentation gives no fixed origin. OFF THE MAIN PATH SCOPED DISPATCH WAITING UNBLOCKED CHECKS PASS AVAILABLE ACCEPTED draft proposed, not ready ready scoped for its role active being worked now blocked needs named input review branch handed off, checks pass testing exact commit on a named test surface done accepted, evidence linked in the spine superseded replaced; history kept deferred postponed on purpose Superseded and deferred are off-path states: the reference fixes no single origin for them, so no arrow points at them. LEGEND State Terminal state Off the main path Transition Return

Readskill/epic-spine/references/operating-model.md skill/epic-spine/references/compact-state.md

Part 5 · How it works, technically · 20 of 20

Draft until stamped ready: the repo delivers itself.

✎
Draft = planningEvery new epic and row enters as draft; spine_new.py scaffolds it so. Never touched by a wake.
✓
Only the user stamps ready“Ready for delivery” is the start order. No agent self-readies, whatever it scaffolds.
▸
The next wake starts itA standing manager at the root picks up each ready child, starts its rows and sets it active.
⊘
Parked and finished are left alonedeferred, review, done, superseded: runnable is false in spines.py --json.

The user writes into the spine and stamps what is ready; the manager stays on and does the rest. See skill/epic-spine/references/spine-model.md (Running).

Readskill/epic-spine/references/spine-model.md skill/epic-spine/scripts/run_state.py

Part 6 · Putting it together · 1 of 4

One full task, goal to merged and recorded.

One task, end to end Sequence: the user states a goal, the manager dispatches a worker, the worker implements in its worktree and hands off, the manager verifies, fast-forward merges to main, tests in main, cleans up and reports. GOAL DISPATCH IMPLEMENT HANDOFF VERIFY FF-ONLY MERGE TESTS IN MAIN CLEAN UP REPORT User states the goal Delivery manager never implements Worker wt/<task> worktree main one tested line

Readskill/epic-spine/references/role-protocols.md skill/epic-spine/references/git-doctrine.md

Part 6 · Putting it together · 2 of 4

This repo is the skill, its own spine, and its own Book.

Skill, spine and Book in one repo Venn diagram: this repository is at once the skill source, its own root spine and its own Book; what all three share is a single commit, and divergence between them is a defect. Skill source skill/epic-spine/ Root spine docs/EPIC-0-OPERATING-SYSTEM.md Book index.html, this deck same commit If any one changes, the other two change in the same commit. Divergence is a defect. The manager checks all three at integration. LEGEND A repo surface What all three share

Readskill/epic-spine/SKILL.md docs/EPIC-0-OPERATING-SYSTEM.md tests/test_book_drift.py

Part 6 · Putting it together · 3 of 4

Three surfaces, three checks, one final gate.

How divergence is caught Architecture: the manifest gate checks the skill, the drift test checks the skill against the Book, strict validation checks the root spine, and the manager checks all three at integration. Skill source skill/epic-spine/ Book index.html Root spine docs/EPIC-0-OPERATING-SYSTEM.md MANIFEST gate CI and skill_update.py verify the skill tree byte for byte Drift test tests/test_book_drift.py: every skill file named in the Book; nothing external Strict validate validate_spine.py --strict on the root spine Manager at integration checks all three surfaces in one commit Divergence is a defect: fix it in the same commit. LEGEND Repo surface Check Final gate Is checked by

Readtests/test_book_drift.py tools/epicspine-manifest.sh skill/epic-spine/scripts/validate_spine.py

Part 6 · Putting it together · 4 of 4

Read the source, not the summary.

References skill/epic-spine/references/operating-model.md skill/epic-spine/references/spine-creation.md skill/epic-spine/references/spine-model.md skill/epic-spine/references/compact-state.md skill/epic-spine/references/sprint-dialect-v2.md skill/epic-spine/references/execution-rollups.md skill/epic-spine/references/structural-validation.md skill/epic-spine/references/learnings.md skill/epic-spine/references/personas.md skill/epic-spine/references/steward-persona.md skill/epic-spine/references/standing-spines.md skill/epic-spine/references/packs.md skill/epic-spine/references/totems.md skill/epic-spine/references/hygiene.md skill/epic-spine/references/machine-dispatcher.md skill/epic-spine/references/role-protocols.md skill/epic-spine/references/dispatch-prompts.md skill/epic-spine/references/book-companion.md skill/epic-spine/references/shortlists.md skill/epic-spine/references/ticket-backends.md skill/epic-spine/references/artifacts.md skill/epic-spine/references/skill-update.md
Scripts skill/epic-spine/scripts/validate_spine.py skill/epic-spine/scripts/rollup_spine.py skill/epic-spine/scripts/migrate_spine.py skill/epic-spine/scripts/spine_new.py skill/epic-spine/scripts/pack.py skill/epic-spine/scripts/pack_init.py skill/epic-spine/scripts/pack_validate.py skill/epic-spine/scripts/pack_checks.py skill/epic-spine/scripts/pack_md.py skill/epic-spine/scripts/pack_export.py skill/epic-spine/scripts/pack_intake.py skill/epic-spine/scripts/pack_role.py skill/epic-spine/scripts/spines.py skill/epic-spine/scripts/spine_tree.py skill/epic-spine/scripts/git_stamps.py skill/epic-spine/references/tree-library.md skill/epic-spine/assets/tree-library-parity.json skill/epic-spine/scripts/bind.py skill/epic-spine/scripts/agents_block.py skill/epic-spine/scripts/global_install.py skill/epic-spine/scripts/artifact_host.py skill/epic-spine/scripts/url_gate.py skill/epic-spine/scripts/skill_update.py skill/epic-spine/scripts/build_shortlist.py Tooling tools/epicspine-manifest.sh tests/test_book_drift.py
Assets skill/epic-spine/assets/agents-block.md skill/epic-spine/assets/global-block.md skill/epic-spine/assets/book-companion-contract.md skill/epic-spine/assets/compact-spine-template.md skill/epic-spine/assets/dispatch-prompt-preamble.md skill/epic-spine/assets/epic-spine-template.md skill/epic-spine/assets/github-issue-template.md skill/epic-spine/assets/shortlist-sample.json skill/epic-spine/assets/shortlist.template.html skill/epic-spine/assets/sweep-brief.md
1 / 35