Linear Agentic Duality

linear-agentic-duality.md

Linear Agentic Duality — Plan an Epic in Linear, Implement in Fresh Sessions

You are tasked with turning a feature description into a fully fleshed-out Linear epic with per-chunk sub-issues, built so that implementation can be farmed out to separate, fresh Claude sessions — one per sub-issue, each on a right-sized model/effort.

The "duality": this session is the planner, and it stays open for the whole epic. The Linear issues are the contract between the planner and the implementers. Fresh implementer sessions read the issue + parent and execute; when reality diverges from plan, the prompt engineer comes back to this window and you revise the tickets. You never implement the sub-issues in this session.

Reference example of the finished product (epic + sub-issues, read it before writing anything): https://linear.app/flex-wash/issue/FLE-3496/automate-pay-tablet-provisioning

Step 0: Model & effort gate

This command is meant to run on Fable @ xhigh effort. Check the model name in your system prompt. If you are not Fable, or you cannot confirm the effort level is xhigh, warn the prompt engineer:

⚠️ This command produces the plan-of-record for a whole epic — it's meant for Fable @ xhigh (/model, /effort). You appear to be running .

Then ask (AskUserQuestion) whether to continue anyway or stop so they can switch. Do not silently proceed.

Inputs from the prompt engineer

1. Background/description of the work to be completed (required).
2. A shell Linear issue to populate. If none was provided, create one yourself (FlexWash team unless told otherwise) and say so.
3. Relevant code files/pointers. If none were provided, ask for them before doing heavy research — along with any other clarifying questions (scope boundaries, what stays manual, who the users are, external systems involved). One focused round of questions up front beats guessing.

Research phase — before writing a single issue

The plan is only as good as its grounding. Do all of this, fanning out in parallel:

• Read every named code file yourself. Note schema types, existing UI affordances, and model-layer entry points the feature will touch.
• Spawn an Explore agent to map the in-repo patterns to build on. Name concretely what to find: existing analogs of each mechanism the feature needs (background jobs, progress UI, caching, external API clients, comment/audit systems, authz patterns), with file paths and symbols. What already exists changes the plan's shape.
• If the work touches external/vendor APIs, spawn a web-search-researcher agent for current, cited API facts: auth mechanism, exact endpoints and request/response shapes, rate limits, eventual-consistency caveats, and explicit flags on anything uncertain. Never plan vendor integrations from memory.
• Fetch the reference epic above (and one of its sub-issues, e.g. FLE-3497) via the Linear tools to mirror the structure exactly.

Everything in the final plan must be grounded: real file paths, real symbol names, real endpoints, real in-repo patterns to mirror. "Add an API client" without naming the auth mechanism and the closest existing client in the repo is not a plan.

The parent issue (epic)

Populate the shell issue with:

• ## Problem — what's manual/broken today, grounded in the runbook/code, and why it's automatable/fixable now.
• ## Target design — kickoff/UX, the pipeline or data flow, key mechanisms. Bold the load-bearing decisions (idempotency model, source-of-truth choices, what survives refresh, error surfacing).
• ## Sub-issues & sequencing — numbered list with links, blockers noted inline, ⚠️ on one-time manual prerequisites that need special access (admin consoles, credential creation). State that each sub-issue carries a QA section and a suggested model/effort footer.
• ## Assumptions / decisions (flag if wrong) — every judgment call you made, one bullet each, so the prompt engineer can veto any of them cheaply. This section is what makes async review work.

Sub-issues — one per deliverable chunk

Chunk by deliverable (a thing that can be built, tested, and QA'd on its own), not by file. Typical shape: external clients first (parallelizable), then the core mechanism, then wiring, then UI, then cleanup. Create each as a sub-issue (parentId = the epic) and wire real blockedBy relations.

Every sub-issue:

• Title: <Epic Name> N/M: <chunk name>. If M changes while all sub-issues are still unstarted, renumber all titles and in-body cross-references. Once implementation is underway (any sub-issue In Progress or Done), do NOT renumber or otherwise touch existing sub-issues to absorb new scope — append the new chunk as a fresh issue numbered past the old M (e.g. an 8/8 alongside N/7 siblings) and add it to the epic's sequencing list.
• ## Goal — what exists when this is done, and which sibling consumes it.
• ### 0. One-time manual prerequisite (only if applicable) — human-with-special-access steps, marked do-this-first, with exact console navigation and env var names.
• Numbered plan sections — concrete file paths, function signatures, request/response shapes, and the specific in-repo pattern to mirror ("mirror trpc/coordinator.ts's trigger → createPublicToken → TriggerRun pattern"), plus known gotchas the research surfaced.
• ### Tests — what to unit-test and how (what to mock, which factories).
• ### QA — verifying this works is part of the work — numbered, executable steps:
  • End-to-end verification driven from Chrome (typescript:verify / claude-in-chrome) whenever a UI can exercise it; API/DB-layer steps otherwise.
  • pnpm build from the typescript/ dir as a required monorepo type check.
  • Leave the dev env running afterwards (never pnpm dev:stop) so the prompt engineer can verify himself.
  • The line: "Update thoughts/implementation-notes.html with: deviations from the plan, test/QA results, and anything else the prompt engineer should know — update it as you go, not at the end."
• Footer (last line): **Suggested model & effort: <model> @ <effort>** — <one-sentence justification>.
  • Calibrate: novel/no-in-repo-precedent or mistakes-are-expensive → Fable 5 or Opus 5 @ high; assembly of proven in-repo patterns → Opus 5 @ medium; mechanical chores/config → Sonnet 5 @ low. (Recommend the newest Opus generation available at planning time.)

After publishing

Mark the parent (epic) issue In Progress (save_issue with state: "In Progress") — planning has started the epic; sub-issues stay Backlog until an implementer picks them up.

Report back with the epic + sub-issue links and the handful of decisions most worth sanity-checking. Then tell the prompt engineer this, explicitly:

Keep this Fable window open — it's the planning session for this epic. Any plan revision (scope change, a question an implementer hits, a redirect) happens here, and I'll update the tickets.

Open a second terminal for implementation. For each sub-issue, in dependency order:

1. /clear the session
2. /model → set the model recommended in the sub-issue's footer
3. /effort → set the recommended effort
4. Implement <linear-issue-link>, make sure to read the issue and the parent first. <plus any extra context>

After each sub-issue lands, the dev env is left running so you can verify it yourself, and thoughts/implementation-notes.html has that chunk's deviations and QA results — worth a skim before kicking off the next one.

Keeping the plan alive (the rest of this session's job)

• When the prompt engineer redirects scope, update both the affected sub-issue(s) and the epic (target design + assumptions), renumber if the chunk count changed, and leave a dated scope note in the rewritten ticket so a fresh implementer doesn't resurrect the old design from stale context.
• Fold implementer discoveries (from thoughts/implementation-notes.html or the prompt engineer's reports) into the not-yet-started sub-issues they affect — downstream tickets should always reflect what upstream actually shipped, not what was originally planned.
• If a sub-issue is already In Progress when you edit it, say so — the prompt engineer may need to tell that implementer to re-read the ticket.
• Answer "what happens if…" questions against the plan as written; if the honest answer reveals a gap, fix the tickets, not just the chat.