Skip to content

feat(agents): a project-spec for each Linear project, one altitude above the epic - #1816

Merged
jhoffner merged 8 commits into
mainfrom
claude/epic-artifact-sub-agent-wvyqp7
Sep 17, 2026
Merged

jhoffner merged 8 commits into
mainfrom
claude/epic-artifact-sub-agent-wvyqp7

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 17, 2026 •

Copy link
Copy Markdown
Collaborator

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 content field.

Epic-spec Project-spec
Container Linear epic issue (Epic label) Linear project
Discovery issue.parent epicIssue.project — 21 of 21 epics carry one
Branch epic/<name> project/<slug>
Driven by epic-lifecycle Nothing — no lifecycle
Gate The objective gate None

Three files: project-spec-template.md (doctrine), project-agent (procedure), project-spec (the skill + wiring). Plus a canonical section in orchestration.md and three dispatch points in epic-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-lifecycle drives. 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 on project/<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

  1. BUSINESS-RULES.md at 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.
  2. First build absorbs, never clobbers. Most projects carry 1k–10k characters of hand-written content; Inbound Transports has 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.
  3. No gate. Check you agree the epic objective gate should stay the only one. Adding a project gate later is easy; removing one people have started waiting on is not.
Engineering calls
  • Four documents, not three. Matches epic and issue altitude rather than inventing a shape.
  • Mirror to the project's content field, not a separate Linear document — content is the native project body and already holds the prose this replaces.
  • spec/_projects/<slug>/ mirrors spec/_epics/<name>/, inheriting the same CI exemption and never-merged branch rules.
  • Budgets deliberately below epic's (~700/900/600/700 vs ~900/1300/800/900). A project-spec heavier than the epics beneath it has stopped coordinating.
  • Two figures, not three. The rule × epic matrix only appears once there are three or more rules to own.
Verification
  • node .agents/workflows/verify.mjs — 299/299.
  • node scripts/validate-spec-folder.mjs — clean.
  • Relative links resolve across all five touched files. Four flagged in project-spec-template.md are nav-line references to the generated set (SPEC.md, DECISIONS.md, …) — the established convention; epic-spec-template.md carries 30 of the same kind, which is the baseline I checked against.
  • Linear structure verified live, not assumed: 21 Epic-labelled issues, 0 without a project; 25+ projects, most carrying existing content.
  • No changeset — .agents/, docs/contributing/ and CLAUDE.md only (BP-022).

Not yet verified: no project-spec has been built by the agent yet. A pilot on Workforce: Layer 2 Abstraction is next and will be its own project/<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

RetriggerConfidence Score: 3/5

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.

Fix All in CursorFindings

  1. P1 Wrap decisions are dropped ▶
  2. P1 Existing content can be lost ▶

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.

  • Adds project-level outcome, cross-epic decision, shared-rule, and timeline conventions.
  • Mirrors the project-spec into Linear project content and maintains a never-merged project branch.
  • Adds concurrency behavior based on skipping colliding refreshes and re-deriving status from Linear.
  • The wrap action cannot currently perform its promised decision fold, and first-build mirroring lacks a safe checkpoint for destructive content replacement.
Diagram
sequenceDiagram
  participant E as Epic lifecycle
  participant A as Project agent
  participant B as project/<slug>
  participant L as Linear project
  E->>A: Create project-spec
  A->>L: Read existing content
  A->>B: Commit four-document set
  A->>L: Replace content with mirror
  A-->>E: Return absorbed/dropped report
  E->>A: Refresh on epic approval or wrap
  A->>L: Query current epic states
  A->>B: Refresh table, graph, and arc
  A->>L: Refresh mirror
  Note over E,A: Wrap also expects cross-epic decisions
  Note over A,B: Refresh currently forbids decision edits
Loading

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 update must not be dropped or cross-epic decisions are lost, and mis-absorbing Linear content is 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 Linear content, 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 with skipped: branch busy; wrap uses update, retries until push lands, and can return blocked: wrap update undelivered. First create commits existing Linear content verbatim to absorbed/linear-content.md before folding.

epic-lifecycle gains three dispatch points: stand up or refresh at epic setup, refresh after objective approval, and update (not refresh) at wrap for arc, epics table, and cross-epic decided once. New project-spec skill, project-spec-template.md, and canonical orchestration.md / figure docs extend the three-altitude model.

CI and guards: project/* branches exempt from the empty-spec/ check; citation scanner and tests cover spec/_projects/. AGENTS.md / CLAUDE.md register the skill and tier project-agent as Opus judgment work.

Reviewed by Cursor Bugbot for commit 32d4833. Configure here.

…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
@vercel

vercel Bot commented Sep 17, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Sep 17, 2026 1:55am UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 17, 2026 1:55am UTC
flow-state-dev-ui Ignored Ignored Preview Sep 17, 2026 1:55am UTC

Request Review

@jhoffner
jhoffner marked this pull request as ready for review September 17, 2026 00:50
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

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.md canon → template SSOT → thin skill/agent procedure (same pattern as epic).
  • project-agent / epic-agent parity 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)

  1. CI branch exemption — .github/workflows/ci.yml exempts spec/* and epic/* only. A never-merged project/<slug> PR carrying spec/_projects/<slug>/ will hit validate-spec-folder.mjs on open/push (same failure mode epic fixed). Extend exemption + BP-037 wording to project/*.
  2. scripts/validate-spec-folder.mjs — SPEC_CITATION includes _epics/ but not _projects/.
  3. spec/README.md — still documents issue + epic paths only.
  4. docs/contributing/spec-figures.md — project figures (territory, arc, conditional matrix) and verify paths aren’t in the altitude table; project-spec skill points verify here as “altitude-independent.”
  5. AGENTS.md skills table — not updated (only CLAUDE.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-spec skill vs epic-spec — there is no epic-spec skill; this skill mostly re-explains “why no lifecycle.” Could shrink to dispatch + verify + pointer, or fold into project-agent description only.
  • Coordinator handles — no persisted project_pr / project_slug next 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/update path 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-agent create alongside epic-agent create 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 to cross-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.

Open in Web View Automation 

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 |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 carries project_slug / project_pr in 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

Comment thread .agents/skills/epic-lifecycle/SKILL.md Resolved
Comment thread docs/contributing/orchestration.md Resolved
Comment thread .agents/subagents/project-agent.md Resolved
Comment thread .agents/subagents/project-agent.md Resolved
Comment thread .agents/subagents/project-agent.md Resolved
jhoffner pushed a commit that referenced this pull request Sep 17, 2026
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

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread .agents/subagents/project-agent.md Resolved
Comment thread .agents/subagents/project-agent.md Resolved
Comment thread .agents/subagents/project-agent.md Resolved
Comment thread .agents/skills/project-spec/SKILL.md Resolved
@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-17T00:54:42.252052Z 60cca76 Draft marked ready
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

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

Copy link
Copy Markdown
Collaborator Author

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):

  • Existing Linear content could be lost. The agent overwrote the project's content and then reported what it dropped — protection arriving strictly after the thing it protects, on an action the same file calls unrecoverable. It now commits the content verbatim, in its own commit, to absorbed/linear-content.md, before writing a line of the set. Chose that over preview-and-confirm because this agent has no AskUserQuestion by design, so a gate would be nobody's; a copy in git needs no one present.
  • Wrap decisions were dropped. epic-lifecycle dispatched a refresh at wrap and expected cross-epic decisions recorded, while refresh is forbidden from writing decisions. Wrap is now always an update.

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 Done only because a human moved them, which is what would have let this survive. The source set is now Linear state OR the epic PR closed.

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 update now retries and returns blocked: wrap update undelivered, while refresh still skips on the hot path.

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 ast.parse-ing it out of the markdown, then negative-tested both directions.

Taken from the simplification review: the bootstrap shape (a1bd1669) — SPEC.md full on day one, DECISIONS.md and BUSINESS-RULES.md as headings with nothing under them, the arc as a figure only at two epics. Two deliberate differences from the sketch: the rules trigger is a rule binding two epics, not a count (a count gets gamed by splitting rules), and the outcome is never deferred.

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; argument-hint offering a fold action that doesn't exist; and the guardrail follow-through — spec/README.md, spec-figures.md (four project rows + the arc's drawing rule), AGENTS.md, and orchestration's "pieces at a glance" now saying three artifact altitudes, two lifecycles.

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 6c4dcda9: validate-spec-folder clean, 299/299 workflows, 20/20 guard tests.

@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

Copy link
Copy Markdown
Collaborator Author

Got it — written into the doctrine in 8fa870c0, since this would have bitten every project PR the agent writes.

I checked before changing anything: both <img> lines on #1818 landed as clean raw HTML with no backticks, and both pinned URLs return 200 image/svg+xml. So the src itself was fine this time — but you'd already hand-fixed the territory one (its width/alt are gone), which is exactly the case the rule needs to cover.

spec-figures.md already documents the underlying cause — the GitHub tool cloud agents write bodies with wraps absolute image URLs in backticks on write, defanging the image into code. The project-spec docs never mentioned it, so an agent writing a project PR body would have walked straight into it. Now stated where it's applied: plain double quotes, raw HTML, no backticks in or around the line, never inside a code fence — pointing at the canonical section rather than giving the recovery procedure a second home that can drift.

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 width="940" and alt restored on the territory image, tell me and I'll hand you the exact line to paste rather than rewriting over your edit.


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

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Fix All in Cursor

❌ 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.

Comment thread docs/contributing/spec-figures.md Resolved
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
@jhoffner
jhoffner merged commit f49cd63 into main Sep 17, 2026
12 checks passed
jhoffner pushed a commit that referenced this pull request Sep 18, 2026
…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
jhoffner pushed a commit that referenced this pull request Sep 23, 2026
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants