Repository navigation
feat(agents): a project-spec for each Linear project, one altitude above the epic - #1816
Conversation
…ove the epic The rules that bind several epics have had no home. W3's seven inherited shape rules survived only inside FIX-1354 §7 — a rule set living inside a document it governs, where a sibling epic couldn't find it and a correction to two of them ended up as a comment on a Linear issue. That is what a missing altitude looks like. Adds the project-spec: the same four documents at Linear-project altitude, on a never-merged PR that stays open for the life of the project and is mirrored to the project's own content field. Three properties keep it cheap: - No lifecycle and no gate. An epic has a shape that ends; a project runs for months and outlives every session. So it is maintained by whichever epic-lifecycle is running, and the epic objective gate stays the only gate. - Status is derived from Linear at read time, never accumulated. One query returns the epics and their states, and each dispatch re-derives the whole table. A refresh that is skipped, raced, or lost costs nothing. - Epic-level triggers only — an epic is created, approved, or wraps. Issue churn would spend a worktree per transition and say nothing the epic PR doesn't already say. That derivation is also what settles concurrency: two epics may run under one project (five sit under Workforce: Layer 2 Abstraction alone), they collide on project/<slug>, and the second skips rather than queues. Discovery is native — an epic's project is its epic issue's `project`, 21 of 21 today — so there is no registry, exactly as a work issue's epic is its parent. First build absorbs the project's existing hand-written content rather than overwriting it; most projects carry thousands of words of it and the overwrite is unrecoverable through the API. Verified: 299/299 workflow tests, validate-spec-folder clean, relative links resolve (the four flagged are nav-line references to the generated set — the epic template carries 30 of the same kind). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MpacHaJN9Rba13WrsPJosZ
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
The spec-folder guard is keyed on branch name and exempted only spec/* and epic/*. A project/<slug> branch carries spec/_projects/<slug>/ for exactly the same reason and would have gone red on its first push. Extends three surfaces that each stated the old pair: the CI condition, the script's header, and its failure message. Also extends SPEC_CITATION with a _projects arm, so a concrete spec/_projects/<slug>/SPEC.md citation in code or docs is caught as a dangling pointer like the epic arm already is — a project PR never merges either. The new arm immediately caught a real one in project-spec-template.md, where the worked example wrote a concrete slug instead of the placeholder every other process doc uses; fixed there. Two test cases pin the new arm in both directions: a concrete project path is flagged, the <slug> placeholder is not. 20/20. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MpacHaJN9Rba13WrsPJosZ
There was a problem hiding this comment.
Code Snob — outcome 3: already tight. No POC.
Read: docs/contributing/project-spec-template.md (four documents, refresh table, absorb), .agents/subagents/project-agent.md (create / refresh / update, hard rules, return line), .agents/skills/project-spec/SKILL.md (standalone entry + verify), docs/contributing/orchestration.md → "The project-spec", .agents/skills/epic-lifecycle/SKILL.md (three dispatch sites), CLAUDE.md skills row. Siblings: epic-spec-template.md (586) / epic-agent.md (197) — this set is already smaller (268 / 129).
The five properties (no lifecycle, derived status, skip not queue, epic-level triggers, absorb) look copied because each file is a different reader: template for the documents, agent for the worktree, skill for /project-spec, orchestration for the map, lifecycle for the call site. A rewrite that collapsed those into one home would shrink pages, not the contract — the next dispatch would re-derive the missing rule. Folding project-agent into epic-agent or dropping the skill re-opens the recorded split (different branch, no project loop, standalone entry).
Rejected: thin the skill to a stub (it is the runtime context for standalone use; its own "restates neither" line is leftover, not a second helper); drop orchestration's skip / derived subsections (those are the delta from the epic-spec section); shrink the CLAUDE.md cell (index, same density as agent-mailbox / settle-claim).
Not re-litigating: four documents vs three; no gate; absorb-never-clobber; derived status; skip rather than queue. Not implementing the Workforce pilot the body split off.
Leftover, not a rewrite: skill argument-hint says fold, the agent says Update; "The pieces at a glance" still lists two lifecycles and does not name project-agent.
Sent by Cursor Automation: Code Snob
There was a problem hiding this comment.
Simplify review — project-spec altitude
Verdict: The problem is real (cross-epic rules and outcomes with no durable home; the W3 anecdote in the template is convincing). The core design choices I’d keep are: no project-lifecycle, status derived from Linear (so skip-on-busy is safe), epic-level triggers only, and separate project/<slug> branch so epic worktrees don’t race. Those restrain cost better than copying epic-spec wholesale would have.
Where I think the approach went farther than necessary is the surface area: a full second stack parallel to epic-spec (four documents, never-merged PR, dedicated agent, figure pipeline, PR body contract, standalone skill) before most projects have a second epic or a cross-epic PD-n / PR-n. Epic-spec earns that machinery (objective gate, epic-wake refreshes, convergence budget). Project-spec explicitly drops the gate and workflow encoding but keeps most of the authoring cost—especially three project-agent dispatches per epic (setup, post-approval, wrap), each with worktree + fetch + possible figure render/mirror, stacked on an already heavy EPIC_WRAP chain.
Simpler approaches worth considering (not necessarily better)
| Approach | What you give up | What you gain |
|---|---|---|
Staged artifact — on first epic: absorb Linear content into SPEC.md + DECISIONS.md only; add BUSINESS-RULES.md / PLAN.md / arc figure when there are ≥2 epics or ≥3 PR-n rules |
Uniform “four docs everywhere” muscle memory | Less empty scaffolding; fewer figures on status-only refreshes |
| Defer the never-merged PR until the first cross-epic decision or second epic | GitHub review thread for project outcome from day one | One fewer long-lived PR/branch until coordination pain appears |
Wrap-weighted refresh — create at setup; status refresh primarily at wrap (manual /project-spec or approval-only if arc must move) |
Epics table / arc slightly stale mid-flight | ~1–2 fewer agent runs per epic; less wrap pile-up |
| Coordinator preflight — one Linear query before dispatch; skip agent when derived table/graph unchanged | Nothing on correctness if agent still authoritative | Avoids hollow worktrees when did: nothing |
I’m not arguing to fold project altitude into epic-spec—that would blur the gate and the unit of intent. I am asking whether full epic-shaped machinery on day one is the smallest change that solves “sibling epics can’t find shared rules.”
What’s working (keep)
- Layering:
orchestration.mdcanon → template SSOT → thin skill/agent procedure (same pattern as epic). project-agent/epic-agentparity where it matters (worktree-safe branch rules, one bounded action, compact return, absorb-don’t-clobber on first build).- Explicit “issue churn is not a trigger” — the main restraint preventing worktree explosions.
- Optional third figure only at ≥3 rules — good simplification vs epic’s three mandatory PR figures.
Blockers / wiring gaps (should land with or immediately after this PR)
- CI branch exemption —
.github/workflows/ci.ymlexemptsspec/*andepic/*only. A never-mergedproject/<slug>PR carryingspec/_projects/<slug>/will hitvalidate-spec-folder.mjson open/push (same failure mode epic fixed). Extend exemption + BP-037 wording toproject/*. scripts/validate-spec-folder.mjs—SPEC_CITATIONincludes_epics/but not_projects/.spec/README.md— still documents issue + epic paths only.docs/contributing/spec-figures.md— project figures (territory, arc, conditional matrix) and verify paths aren’t in the altitude table;project-specskill points verify here as “altitude-independent.”AGENTS.mdskills table — not updated (onlyCLAUDE.md); orchestration footnote still lists issue + epic templates only.
Medium feedback (simplify docs & ops, not necessarily block)
- Prose duplication — “derived from Linear / skip don’t queue / no issue churn / no gate” appears in ~5 places; consider one full treatment in
orchestration.md+ template and one-liners elsewhere (epic-lifecycle already defers epic doctrine heavily). project-specskill vsepic-spec— there is noepic-specskill; this skill mostly re-explains “why no lifecycle.” Could shrink to dispatch + verify + pointer, or fold intoproject-agentdescription only.- Coordinator handles — no persisted
project_pr/project_slugnext to epic handles; rediscovering “does project PR exist?” every setup is extra coordinator work. skipped: branch busy— no concrete detection rule (contrast epic branch “one worktree at a time”); worth one line (e.g. non-FF push → skip and exit).- Project PR feedback — fold/
updatepath has no stated relationship to epic’s two-round convergence; clarify whether project PR comments are out of scope for automatic re-dispatch (my lean: yes, unless dispatch carries feedback). - EPIC_SETUP — running full
project-agentcreate alongsideepic-agentcreate is two heavy agents on the critical path; if you keep both triggers, document expected token/wake budget in orchestration.
Skipped (product call / larger refactor)
- Merging project + epic altitude; async queue on
project/<slug>; subscribing coordinator to project PR activity; cross-epic review skill (orthogonal tocross-spec-review).
Summary: Directionally I’d ship project altitude; I’m requesting changes mainly for repo guardrails (project/* CI, citation scanner, README, spec-figures, AGENTS.md) before the first real project/<slug> PR. Separately, consider a staged or wrap-heavier v1 to avoid paying full epic-spec machinery on every epic when the artifact’s unique value is cross-epic DECISIONS / PR-n, not another live status table.
Sent by Cursor Automation: Review For Best Approach
| | Phase | What happens | Ends when | | ||
| |---|---|---| | ||
| | **EPIC_SETUP** | Resolve the set; discover or create the epic issue; `epic-agent` writes the epic-spec and opens the never-merged epic PR | Epic PR is open → AWAITING_OBJECTIVE | | ||
| | **EPIC_SETUP** | Resolve the set; discover or create the epic issue; `epic-agent` writes the epic-spec and opens the never-merged epic PR; `project-agent` stands up or refreshes its Linear project's project-spec | Epic PR is open → AWAITING_OBJECTIVE | |
There was a problem hiding this comment.
Three lifecycle touchpoints (here, post-approval, wrap) mean ~3 project-agent worktrees per epic, often with figure render + full Linear content re-mirror. Worth a short expected cost note in orchestration (intentional vs accidental). Alternative to consider: create-only at setup + wrap-heavy refresh if mid-epic staleness of the epics table is acceptable given Linear is source of truth.
There was a problem hiding this comment.
Fair pricing, and it moved me partway — but I'm keeping three triggers, because c9248d4d removed most of what made them expensive.
What each dispatch cost when you priced it, and what it costs now:
- A status refresh re-rendered every figure and re-verified the whole tree. It now re-renders only the figures that pass edited — the arc, never the territory — and scopes verification to what moved. That was your sibling comment on
project-agent.md:65, and it's the bulk of the saving. - The coordinator dispatched even with nothing to do, paying an agent to report
nothing. It now skips the dispatch when no epic-level transition happened, and carriesproject_slug/project_prin the epic record so a resume never re-discovers the PR.
On create-only + wrap-heavy: the cost case is real but it trades against the artifact's one claim. A project-spec exists to be true whenever you look, and "epics table is stale until the epic wraps" is a long window — W3 has been in flight nine days and is one of five epics. The reader it fails is exactly the one it's for: someone arriving mid-project who wants to know where things stand. "Linear is source of truth" is true and doesn't help — if they're reading Linear, the artifact earned nothing.
The one I'd cut first if this proves too chatty is post-approval, not setup or wrap: it moves a row from spec to in flight and starts an arc bar, which is the least load-bearing of the three. Noting that here so the cut is cheap to make later rather than re-derived.
I've flagged the cost/staging question to the repo owner as a product call, since it's their token budget and their staleness tolerance — I don't think it's mine to settle unilaterally.
Generated by Claude Code
Process guards failed here for the reason the machinery PR fixes: the exemption is keyed on branch name and main's copy lists only spec/* and epic/*, so a project/<slug> branch carrying spec/_projects/<slug>/ is checked and fails. The fix is already on #1816. Ported verbatim rather than waiting for that to merge; it no-ops the moment main carries it. This branch never merges, so the duplicate hunk dies with it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MpacHaJN9Rba13WrsPJosZ
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 60cca76e64
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Make sure not to double quote or put "``" in the img src |
Greptile found two places where my own files disagreed with themselves. **Existing Linear content could be lost.** The agent overwrote the project's content and then reported what it had dropped as stale — so the caller learns about a misjudged call after the original is gone, on an action the same file calls unrecoverable. The agent now commits the project's content verbatim to spec/_projects/<slug>/absorbed/linear-content.md, in its own commit, before it writes a line of the set. A report is not protection; a copy in git is, and it makes the judgment reversible by whoever disagrees with it later. **Wrap decisions were dropped.** epic-lifecycle dispatched a `refresh` at wrap and expected cross-epic conclusions in DECISIONS.md → decided once, but Refresh is forbidden from writing decisions. Wrap is the one moment that reliably produces cross-epic knowledge, so it is now always an `update`, stated on both sides, and the agent treats a wrap dispatch labelled `refresh` as an Update. Also from review, all real: - The skill's argument-hint offered `fold`, which is not an action the agent has. It is `update`. - "A skipped refresh costs nothing" conflated correctness with cost. A skip still spends a sub-agent and a worktree, and with the cap at two epics on one project the collision is routine. Replaced with the honest version plus the two things that actually keep it cheap (persist project_slug/project_pr in the epic record; don't dispatch when no epic-level transition happened) and the agent's own busy test, a non-fast-forward push. - A status-only refresh re-verified the whole tree. It now re-renders and checks only the figures that pass edited — the arc, never the territory. Guardrail follow-through the convention needed and did not have: - spec/README.md: project paths, the refresh rule, and the absorbed/ record. - spec-figures.md: four project rows in the altitude table, the arc's drawing rule (a not-started epic gets no bar — a dashed box reads as duration), and the verify path. The project-spec skill pointed here for verification while this file knew nothing about project altitude. - AGENTS.md: the orchestration note and the model tier. - orchestration.md "The pieces at a glance": three artifact altitudes, two lifecycles, and the project bullet saying why the third has none. Verified: validate-spec-folder clean, 299/299 workflows, 20/20 guard tests, links resolve. The one flagged link is a pre-existing ellipsis placeholder on main, untouched here. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MpacHaJN9Rba13WrsPJosZ
Review asked whether full epic-shaped machinery on day one is the smallest thing that solves "sibling epics can't find shared rules". Partly no, and this is the half I agree with. A project-spec is stood up when the FIRST epic runs, so the common first case is one epic and no cross-epic anything — where four full documents are mostly scaffolding, and scaffolding is what teaches people an artifact is busywork. Adds the bootstrap shape: SPEC.md full on day one (the outcome is the whole value and is the one thing never deferred), DECISIONS.md and BUSINESS-RULES.md as headings with nothing under them, the arc as a figure only at two epics. Each document names what makes it earn content — and the trigger for rules is a rule binding two epics, not a rule count. An empty section with its heading is correct, not unfinished: it says the question was asked and the answer is none, which is what stops the next epic inventing a private one. A missing document says nothing. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MpacHaJN9Rba13WrsPJosZ
… not fail Three findings from Codex, all real, and the first two hit the central claim. **Linear alone cannot derive "done".** An epic wraps by closing its epic PR unmerged and its Linear state is untouched — the repo states this twice (orchestration.md, epic-lifecycle "active means epic PR open"). So "derive status from Linear, never from the old file" would have regressed every wrapped epic back to in flight on the next refresh: the exact drift the rule exists to prevent, wearing its own clothes. The source set is now Linear state OR the epic PR being closed, and both halves are named as required. **Skip-don't-queue was right for status and wrong for a wrap.** Skipping is safe only for what is re-derivable. A wrap carries two things: status, which is, and the cross-epic decisions the epic settled, which are derivable from nothing — and wrap is the last thing an epic does, so there is no guaranteed later dispatch to repair it. A wrap Update now retries rather than skipping, and returns `blocked: wrap update undelivered` if it still cannot land. This also resolves a contradiction between the two files, where epic-lifecycle called the wrap "the one refresh not to skip" while the agent was told to skip it. **The status check could not fail.** It extracted identifiers and printed them; a table with every epic wrongly marked "in flight" passed it exactly as readily as a correct one — a check aimed at a neighbour of the claim it was supposed to prove. It now compares derived state against each row and reports mismatches, missing rows and stale ids. That replacement was itself wrong on the first attempt: the snippet did not parse (a multi-line GraphQL string in single quotes). Caught by parse-checking it rather than eyeballing it, then negative-tested both directions — three findings against a wrong table, silence against a correct one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MpacHaJN9Rba13WrsPJosZ
|
Three review rounds folded. Every finding was real; ten of eleven threads are answered and resolved. Two P1s that were contradictions inside my own files (Greptile):
The best finding on the PR (Codex): Linear alone cannot derive "done." An epic wraps by closing its epic PR unmerged and its Linear state is untouched — the repo says so in two places. A Linear-only derivation would have regressed every wrapped epic to in flight on the next refresh: the precise drift the derive-don't-accumulate rule exists to prevent, wearing that rule's own clothes. Two pilot epics read That cascaded usefully: because a closed epic PR is derivable, a dropped wrap status refresh self-heals — which let me scope Codex's sibling P2 to the half that genuinely can't. Skipping is safe only for what is re-derivable, so a wrap A check that could not fail (Codex): the status verification printed identifiers and commented that you should diff them. A table with every epic wrongly marked "in flight" passed it as readily as a correct one — tenet 7, guarding the feature's central freshness claim. Now compares and reports mismatches, missing rows and stale ids. My first replacement didn't parse; caught by Taken from the simplification review: the bootstrap shape ( Also fixed: the honest cost of a skipped dispatch (it's free in correctness, not in tokens) plus the two coordinator-side mitigations; verify scoped to touched figures on the hot path; One thread left open on purpose: the three-dispatches-per-epic cost question. I've kept three triggers, because this round removed most of what made them expensive — but whether that's the right trade is the repo owner's call on their token budget and staleness tolerance, so I've put it to them rather than settling it unilaterally. If it needs cutting, post-approval is the one to cut, and I've said so on the thread so it's cheap later. CI green on @cursor review — taking up the re-review, since the wiring gaps you gated on are closed. Generated by Claude Code |
The repo already documents that the GitHub tool cloud agents write PR bodies with wraps absolute image URLs in backticks on write, defanging the image into code (spec-figures.md -> "In the PR body"). The project-spec docs never said so, so an agent writing a project PR body would have walked into it. States the rule where it is applied — plain double quotes, raw HTML, no backticks in or around the line, never inside a fence — and points at the canonical section rather than restating the recovery procedure, which stays in one place. Also widens the never-rewrite rule from "a body a person has pasted an image into" to include one they hand-fixed: same reason, and hand-fixing is what actually happens when a defanged line ships. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MpacHaJN9Rba13WrsPJosZ
|
Got it — written into the doctrine in I checked before changing anything: both
I also widened the never-rewrite rule. It said "a body a person has pasted an image into"; it now covers one you've hand-fixed, which is what actually happens when a defanged line ships. I have not touched #1818's body for that reason — if you want the Generated by Claude Code |
…sumed The doc asserted that the tool wraps absolute image URLs in backticks. Three facts about it were unknown until it was hit on a real PR (#1818), and each changes what you do about it: - Deterministic, not sporadic: the same URL defangs every write, so a retry is not a fix. - Keys on the URL, not the link text: renaming a link changed nothing, and a .md filename can trigger it too — so a link can arrive defanged while the images beside it survive. That is how this shipped unnoticed. - create_pull_request does not defang; update_pull_request does. The images survived the original create and died on the first edit. The last one is the useful rule: get the body right on the first write, and treat every later edit as unable to carry an image. That is also the real reason the never-rewrite rule exists — not politeness toward a human's paste, but that the rewrite cannot carry what it is replacing. Learned by breaking it: I rewrote a body to fix two defanged links and took out both working images doing it, against a rule added to the project-spec template an hour earlier. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MpacHaJN9Rba13WrsPJosZ
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 32d4833. Configure here.
Adding "# or spec/_epics/… or spec/_projects/…" to the end of the S= line put the comment in the middle of `S=…; H=$(…)`, so H was never assigned. Every figure render then ran at --window-size=940,100 and reviewed a 100px strip instead of the figure — at every altitude, not just the new one. Reproduced and fixed, both measured on a real 300-high figure: broken -> H='' , render 940x100 (cropped strip) fixed -> H=300, render 940x400 (full figure) The block is now four lines: the path note as its own comment, then S, then H. Verified by extracting the block verbatim out of the markdown and executing it, rather than reading it — the same way the SVG snippet in the project-spec skill was checked earlier. Worth naming: this is the step that caught two real defects tonight — a label overrunning its box, and dashed bars that read as duration. Had it shipped broken, neither would have been visible, and the check would have gone on returning green over a strip of whitespace. A verification command that cannot fail is the defect this repo's tenet 7 is about, and I put one in the file that teaches the command. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MpacHaJN9Rba13WrsPJosZ
…ild skipped The doctrine requires the project's existing `content` be committed verbatim before a line of the set is written, so that every "folded in" / "dropped as stale" call stays reversible and the field can be restored if a mirror write goes wrong. This set was built on Sep 17 without it. The rule is not one this build ignored — it did not exist yet. It was added to project-spec-template.md and project-agent.md later that night, in response to a review finding on the machinery PR, by which point the pilot was already pushed. So the requirement and the only set built to date have been out of step since, and it went unnoticed until a refresh looked for the snapshot to recover from and found no absorbed/ directory. That matters now rather than eventually: the mirror write is the open question sitting with the owner, and it is the one action at this altitude the Linear API cannot undo. Answering it with no in-repo copy of what would be overwritten is the exact failure the rule was written to prevent. Taken from the live field rather than retyped: 6,060 characters, `updatedAt` 2026-09-05, which predates the Sep 17 build — so this is the same text the set was absorbed from, not a later revision of it. Verify: the body was re-read out of the committed file, split at the rule, and compared byte-for-byte against a fresh GraphQL read — 6,060/6,060 identical. Negative control run in the same pass: changing one word makes the comparison fail, so the check is not vacuous. The header's template link is absolute because this branch was cut before #1816 merged, so a relative path to docs/contributing/ dangles here; the URL was checked for 200. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MpacHaJN9Rba13WrsPJosZ
The PR went un-mergeable against main. One conflict, and it is one this branch created: c012d78 ported the `project/*` spec-folder exemption onto this branch by hand, because the branch was cut before #1816 merged and the exemption did not exist upstream yet. Main has since superseded that port - the step is now "Spec retention and legacy paths", issue and epic specs merge into specs/ and are checked, and `project/*` is the only exemption left. Resolved by taking main's file whole, so the branch stops carrying a private copy of a workflow it does not own. Nothing of the port is kept; main's version is strictly broader and this branch was the reason it exists. Verified rather than assumed: with main's ci.yml in place, the guard still rejects this tree - `scripts/validate-spec-folder.mjs` exits 1 naming `spec/_projects` - which is the negative control. The step passes on this PR only because `head_ref` is `project/workforce-layer-2-abstraction` and the exemption skips it, and it would fail the moment that stopped being true. All six spec files and both figures survive the merge untouched. No document, figure, count or decision is changed by this commit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MpacHaJN9Rba13WrsPJosZ



The rules that bind several epics have had nowhere to live. W3's seven inherited shape rules — which every file-convention epic obeys — survived only inside
FIX-1354 §7: a rule set living inside a document it governs, where a sibling epic couldn't find it and a verified correction to two of them ended up as a comment on a Linear issue.That is what a missing altitude looks like. An epic-spec coordinates a set of issues. Nothing coordinated a set of epics.
What this does
Adds the project-spec: the same four documents at Linear project altitude, on a never-merged PR that stays open for the life of the project and mirrors to the project's own
contentfield.Epiclabel)issue.parentepicIssue.project— 21 of 21 epics carry oneepic/<name>project/<slug>epic-lifecycleThree files:
project-spec-template.md(doctrine),project-agent(procedure),project-spec(the skill + wiring). Plus a canonical section inorchestration.mdand three dispatch points inepic-lifecycle.The three properties that keep it cheap
No lifecycle, deliberately. An epic has a shape that ends — a gate, a set, a wrap — which is what
epic-lifecycledrives. A project has none of it: it runs for months and outlives every session that touches it, so a loop for it would be a session that has to stay alive for a quarter. It's maintained by whichever epic-lifecycle is running.Status is derived, never accumulated. One query on the project returns its epics and their states, and every dispatch re-derives the whole table from source rather than editing last week's numbers. This is the load-bearing decision — everything else falls out of it.
Epic-level triggers only — an epic is created, approved, or wraps. Issue churn is explicitly not a trigger, in the template, the agent, and the skill.
Why the derivation settles concurrency
Two epics may run at once and both may serve one project — with five epics under
Workforce: Layer 2 Abstraction, that's routine, not exotic. They collide onproject/<slug>.Because status is re-derived, the second dispatch skips rather than queues. A refresh that is skipped, raced, or lost costs nothing; the next one is correct regardless of how many were dropped. No lock, no lease, no queue — and it's the same property that lets the artifact stay true in the long gaps when no session is running at all.
What's asked of you
One call, and it's about how much this artifact is allowed to say. I scoped it hard: a decision belongs here only if a second epic would otherwise have to make it again. One-epic calls stay on the epic.
Recommend keeping it that narrow. A project-spec that absorbs single-epic decisions becomes a design nobody signed off, sitting above five epics that each already have a gate. What would change my mind: if in practice the cross-epic section stays empty while people keep asking questions the project should have answered — then the filter is too tight. What being wrong costs: a few decisions get made twice before someone notices. Cheap and visible.
Parts worth reviewing closely
BUSINESS-RULES.mdat this altitude. I argued it earns its place from the W3 evidence above. If you read those seven rules as genuinely belonging to one epic, the document should go and the set drops to three.content;Inbound Transportshas 10,065. The agent folds it in and reports what it dropped as stale. This is the one action here that's unrecoverable through the API, and it's called out in all three files.Engineering calls
contentfield, not a separate Linear document —contentis the native project body and already holds the prose this replaces.spec/_projects/<slug>/mirrorsspec/_epics/<name>/, inheriting the same CI exemption and never-merged branch rules.Verification
node .agents/workflows/verify.mjs— 299/299.node scripts/validate-spec-folder.mjs— clean.project-spec-template.mdare nav-line references to the generated set (SPEC.md,DECISIONS.md, …) — the established convention;epic-spec-template.mdcarries 30 of the same kind, which is the baseline I checked against.content..agents/,docs/contributing/andCLAUDE.mdonly (BP-022).Not yet verified: no project-spec has been built by the agent yet. A pilot on
Workforce: Layer 2 Abstractionis next and will be its ownproject/<slug>PR, which is the real test of the absorb step.Links — no Linear issue; direct request. Merges normally.
🤖 Generated with Claude Code
https://claude.ai/code/session_01MpacHaJN9Rba13WrsPJosZ
Generated by Claude Code
The PR is not safe to merge until wrap dispatches can preserve cross-epic decisions and first-build mirroring cannot irreversibly discard existing Linear content before review.
Summary
This PR introduces a four-document project-spec above epic altitude, a dedicated agent to create and maintain it, and epic-lifecycle dispatches for creation, approval, and wrap transitions.
Diagram
Reviews (1) · Last reviewed commit: "feat(agents): a project-spec for each Li..."
Note
Medium Risk
Orchestration and first-build Linear mirroring are procedural only until piloted; wrap
updatemust not be dropped or cross-epic decisions are lost, and mis-absorbing Linearcontentis API-irreversible despite the git backup.Overview
Introduces a project-spec — a standing four-document set for a Linear project on never-merged branch
project/<slug>(spec/_projects/<slug>/), mirrored to the project’s Linearcontent, with no lifecycle and no gate. Cross-epic outcomes, decided-once decisions, shared PR-n rules with owner epics, and an arc figure live here so sibling epics don’t re-litigate or bury shared rules in one epic’s spec.project-agent(worktree) implements create / refresh / update: status is re-derived from Linear plus epic PR state (wrapped epics count as done when the epic PR is closed). Colliding refreshes skip withskipped: branch busy; wrap usesupdate, retries until push lands, and can returnblocked: wrap update undelivered. First create commits existing Linearcontentverbatim toabsorbed/linear-content.mdbefore folding.epic-lifecyclegains three dispatch points: stand up or refresh at epic setup, refresh after objective approval, andupdate(not refresh) at wrap for arc, epics table, and cross-epic decided once. Newproject-specskill,project-spec-template.md, and canonicalorchestration.md/ figure docs extend the three-altitude model.CI and guards:
project/*branches exempt from the empty-spec/check; citation scanner and tests coverspec/_projects/.AGENTS.md/CLAUDE.mdregister the skill and tierproject-agentas Opus judgment work.Reviewed by Cursor Bugbot for commit 32d4833. Configure here.