Owner's guide

The work-loop

The work-loop is your name for the run from a sentence you say to a change you can see. Every piece of it is tracked as an issue in Linear. This page is what each step means, what your Claude does at it, and which parts of the loop are still undecided.

LinearThe queue moved to Linear on Sep 3 2026

Every piece of work is an issue in Linear, the issue tracker your Claude keeps the queue in. You open it in a browser. The workspace is named cognizant and the team inside it is COG, so each issue has an identifier like COG-42. That identifier is how your Claude names an issue back to you.

Your words for the change: “Clearly the github process is fucked. So we should start fresh.”

The GitHub board stopped being the queue on the same day. Two scheduled checks still file onto GitHub, and The development workflow says which.

Your Claude writes to Linear as its own user, so every issue, comment and status change there is stamped as its work rather than yours. If its connection to Linear ever needs signing in again, it stops and asks you. That sign-in is the one part of the loop only you can do.

FilingEvery change you name becomes an issue before anything else happens

A sentence of yours that names a change to the product becomes an issue before anything else happens in that exchange. Filing is the first thing your Claude does with your words.

The rule holds while you are watching a build. A change you name while looking at the screen gets filed like any other, and iterating on what is in front of you does not stand in for filing it. A correction that contradicts an issue's title becomes its own issue. One change per issue.

Everything filed is real work, and the only decision left is the order it gets done in.

The reply you get names the issue it filed, by identifier and title. A reply with no identifier means the filing did not happen, and saying so is enough to get it filed. Before the exchange ends, your Claude goes back over what you asked for and points at the issue for each change you named.

Why that check exists. A change you asked for mid-build on Sep 3 2026 never became an issue, and you said so the next day: “that means you are failing to file issues i tell you to file … This is constantly a gap and prevents all work from getting done”.

A title is the area, a colon, and the change, in your own nouns. “Events: parent events collapsible” is the shape. The body leads with your quote, then two plain lines of context, then the parts of the app the change touches. A screenshot you gave goes at the top.

StatusesEight statuses say where a piece of work stands

You read the queue by status. Each one means a single thing.

Backlog Parked. You are the only one who parks an issue here, and your Claude never takes work out of it.
Open The queue itself, ordered top to bottom. New issues arrive here, and your Claude reads and plans from the top. Linear called this column Todo until Sep 4 2026.
Planned The plan comment is on the issue. It is ready to build.
In Progress Being built.
Pre-release Built. What is owed at this step is still undecided.
Waiting on you Only you can unblock it, and the question is on the issue.
Shipping Deployed, and landing on each target.
Done Observed everywhere it was meant to go.

The assignee says who has the issue, and your Claude claims one by assigning itself.

PlanningAn issue gets planned before it gets built, on a stronger model

Planning and building run on different models. Fable plans and Opus builds, two Claude models with Fable the stronger of the pair. Planning is the judgment step, and a bad plan misdirects every builder working from it.

A planning pass starts when an issue reaches the top of Open, when you name one, or when you ask for every issue in Open to be planned.

The pass reads each issue's title and body once, with no code open, and sorts the issues by the part of the app they touch. One planner takes each part, and the parts are planned at the same time, so logic that several issues share gets named once. An issue you wrote by hand has its title rewritten as an area and a change here. Then the planner reads what the work touches: the code in the web app and in the phone app, and the guide pages describing that surface.

The plan is posted as a comment on the issue, under four headings every time.

Touches The files, listed for the web app and for the phone app.
Shared Logic both apps need, named as a function and a file, and which app gets it written first. The other app copies it exactly, and a check keeps the two copies identical.
Order The sequence to work in when other issues touch the same files, and which app each builder owns. Two issues on one surface are sequenced, never built side by side.
Needs you Anything only you can answer.

Anything under Needs you sends the issue to Waiting on you, with the question on it. An empty Needs you sends it to Planned, ready for a builder who never has to open the code to understand it.

BuildingDevelopment covers both apps, and the phone follows at a stopping point you name

Development is the web app and the phone app. Guides are pre-release work instead. Your words: “guides are not part of development”, and “ios is not pre-release, ios is development”.

The phone does not ship in step with the web. You argue a design out on the web while its shape settles, and rebuilding the phone for every rejected layout spends the work twice. You said it after three rejected layouts for one row: “this is a perfect example of why we dont implement ios lock step with web. We will implement ios when we get to a better stopping point.”

So an issue can finish its web work with the phone still owed. The phone half is picked up as its own pass, at a stopping point you name. Your Claude does not build it by default.

LabelsThree labels say which app is live, and shipped means live

Which app has a change is a label on the issue, and these three are the whole set.

Web shipped The web change is deployed, and someone has looked at it on the live site.
iOS built The phone code is finished and merged into the main line of code, and no phone has it yet. A change to the installed app itself waits here until you authorize a TestFlight build.
iOS shipped Your phone can have it. Most changes arrive over the air, with no new install; a change to the installed app itself arrives as a TestFlight build you tap Update on.
Absent That app is still owed the change.

The labels said “complete” for an hour on Sep 4 2026, and you read that as done and in your hands: “Wait this is confusing. Web Complete & IOS Complete, yet only Web has it live and deployed.” Shipped now means live everywhere the word appears, never code that has merely been merged.

The iOS built label came from your ask the same day: “You need a new label that distinguishes ios built and ios deployed”. Labels stay few on purpose, since your standing word on them is “I hate clutter”.

AgentsIssues are built in parallel, and one session lands them all

One builder takes one issue, in its own copy of the repository. The web half and the phone half can run at the same time. Builders never push their work up and never deploy it.

Two issues touching the same screen collide when their changes come together. One integrating session takes them one at a time in a set order, folds each onto the current code, re-runs the checks, then pushes once and deploys once. One unverified push is in flight at a time.

While you are watching, that order changes. The change is deployed first and reaches the live site in a little over a minute, so you see it. The deploy runs that app's own test suite on the way, and the rest follows after you have looked: the check on web-and-phone parity, the commit, and the push. Anything set aside to get there is written on the issue as a comment at the moment it is set aside.

A run with you away goes in phases, in your words: “Plan out first. Build web second. Build ios last, but do not push testflight. You can deploy ota. Finally update all docs and remaining to close out any issues you can.” Every issue in Open gets planned. Web gets built and deployed for every planned one. Then one phone pass covers everything that owes the phone, published over the air. Then the guides, then a close-out pass over whatever can be finished. A TestFlight upload waits for your explicit word, and a change to the installed app itself stops at iOS built until you give it.

ProjectsA run of related issues gets a project of its own

Issues that belong to one effort go in a Linear project, which is your word for that grouping: “I think all of these issues need to be in a higher level proejct”. The first is Events MVP. The project's description states the rules binding the whole run, so a rule like the phone not shipping in lockstep is settled once instead of argued on every issue underneath.

Sub-issues are for separate work. The steps of the process never become sub-issues.

UndecidedFour parts of the loop have no definition yet

The loop is written down as far as you and your Claude have decided it. These four are still blank, so an issue can stop at one of them with nothing agreed about what leaves it.

In Progress to Pre-release Both app labels being present is part of the exit. What else has to be true is undefined, and so is the place of the phone's own deploy in this step.
Pre-release to Shipping This step is undefined.
Shipping to Done This step is undefined.
The pre-release checklist Its contents are unagreed, so an issue gets no checklist on it at all until you settle them.

Three further decisions are open, and each one is yours.

Release pipelines Linear's own release feature is paid. Twenty dollars a month for two seats was the price, and you judged it excessive.
Deploy state How a deploy gets recorded on the issue is unsettled.
Client delivery A client instance takes the work as a merge on its own cadence, worked out from the code that changed. How that gets tracked is unsettled.