Owner's guide
Working in Claude Code
A session is time you spend hands-on with Claude Code, building and maintaining the app. It opens by orienting and closes by cleaning up, and it runs on the issue board in between. Your Claude runs all of it. This page is for checking the work.
A sessionA session is you and Claude Code, working together
You sit with Claude Code and steer. It does the building. You decide what happens and check the result, without writing the code yourself.
StartupA session orients before it touches anything
A session opens by reading its own state, and the report arrives before it can act. It names the repository and the branch, any uncommitted or unpushed work the last session left behind, what shipped last, and whether a guide review round is overdue. If the last session ended without closing out, it finishes that first. It reads the state before acting, instead of guessing its job from whatever it saw last.
You no longer have to ask for it. Orienting used to be a command a session could decide to skip, and the skipped one was always the session that would have reported unfinished work. It runs automatically at startup now.
In betweenWork runs one claimed issue at a time
Your Claude picks the next issue and claims it with a comment, so a second session won't collide, then builds it: the code, the tests, and a plain note of what changed. Anything out of scope becomes its own issue instead of growing the task. The whole flow moves work across the board, so it follows the GitHub issue process the entire way.
CommandsA session uses just three commands
You rarely type these yourself. You'll see your Claude run them, and you can ask for any by name.
/preflight- Runs the phone app's lint, types and tests, and the personal-data scan, before anything is pushed. It covers the phone app only. The push itself runs the personal-data scan and a type check for the phone app or the web app when either one changed, and the independent server runs the rest.
/ship- Stages exactly the files your Claude names, runs the gates that belong to this path, records the change with a note of what and why, and pushes. It stops when the phone app, the web app or the tooling changed and the release notes did not, unless the session records why the change is invisible. Most of what it runs the server runs again on the push. Two of the gates run nowhere else, the guide voice check and the check on the two apps' shared palette. After the push, an independent server runs the wider set, and your Claude confirms the run came back green. A push is not a deploy in this repository, so the script also prints the deploy command for whichever part changed.
/closeout- Ends the session by working a nine-item list, and reports each item as passed, fixed or flagged. Your winding-down words trigger it, so you never call it by name.
ChecksThe gates run at the push, on the ship path, or as a rule
The gates run in three places. Your machine refuses a commit with no issue behind it, and refuses a push that comes from a session other than the integrating one, that would leak personal data, or that breaks types in the phone app or the web app. An independent server runs the wider set again on every push. The guide voice check and the palette check run only when the change goes through /ship, and two rules run on your Claude keeping them. Protections covers what the gates protect. This list covers where each one runs.
Personal data on the list stays out.
A scan reads every tracked file for a fixed list of banned strings: specific names, email addresses, home coordinates, and credential shapes. A hit stops the push, and the server repeats the scan, so a skipped hook changes nothing. The same scan reads every commit message as it is written, since a message reaches the remote without ever being a tracked file. The list is literal, so it protects only the identifiers it has been given. The owner's own name is deliberately allowed in the owner's and user's guides, where he writes in his own voice, and nowhere else.
Tests land with the code.
The independent server runs both apps' full check suites and the web build on every push. Your machine runs a type check for the phone app or the web app whenever either one changed, which is the cheapest catch there is. A backend-only change gets its type checking on the server with everything else. Everything slower moved to the server so that a push costs seconds instead of a minute. A bug fix ships with the test that catches that bug.
Every commit names its issue.
A commit without a reference to the issue it serves gets rejected on your machine, which also asks GitHub whether the issue it names is real. The server re-checks every pushed commit for the reference. The work and its record stay together.
UI gets a design lint, then a look at the live page.
When UI files go through /ship, a lint checks the design rules a machine can read, and the server runs the same lint over every screen on each push. The looking happens after the deploy now, on the page you would open. It used to refuse the commit until your Claude recorded that it had looked, which left you waiting on production while your Claude studied a local copy of the same thing. The deploy script prints the render command instead. The look happens on the web render, since the two apps are built to look the same and one look covers both. A session deliberately digging into a difference does the full side-by-side of phone and web instead. The same path checks the palette the two apps keep by hand, whenever a theme file is in the change, and that check runs nowhere else.
Guide wording gets a voice check, on the ship path.
A guide page going through /ship passes a voice check that holds the writing to the plain register these pages use. A plain push skips it, and the server runs no prose check of its own, so this gate depends on the ship path being used.
One session pushes.
Several Claude sessions can work this repository at once, and exactly one of them integrates: it runs the gates, commits and deploys. A push from a session that has not declared itself the integrator is refused. It stops the accident of two sessions pushing over each other, and a session that means to push can still say so.
Two rules run on discipline, not on machinery.
A green build is the first. Red on the server stops the work because your Claude stops, and the machinery lets the next push land even while the build is red, since /ship pushes without checking the server's state first. Your Claude watches each run and fixes or reverts before pushing again. The look at the deployed page is the second. The deploy script prints the render command once the page is live, and a deploy nobody looked at is refused by nothing, so this one rests on your Claude reaching for it when the change is one it could not predict from the code.
IteratingYou go back and forth, then ship at a stopping point
While you and your Claude work through something, it batches the changes and skips per-edit tests, staying in the conversation with you. It ships the batch when you reach a stopping point. Shipping and deploying are two steps here, on purpose, so the batch reaches your instance when your Claude runs the deploy, which waits for the build and reports success only once the live address answers. One deploy gets verified live before the next goes out.
CloseoutSaying you're done runs the closeout
You never ask for cleanup by name. Winding-down words, "that's it," "gotta run," run the closeout, and it works a fixed list of nine.
The board gets its own hygiene check and gets fixed where it fails. Every issue the session claimed is closed, or else has a status comment on it, and anything it discovered is filed rather than left in the chat. The release notes get matched to what shipped. Test coverage gets a glance when substantial code went out, for a drop worth naming rather than a number to hit. The tree is left clean and the last push is confirmed green by its own commit, not by whichever run finished most recently. Old test artifacts get pruned. A session that changed the interface reviews the design on the web render. A session that changed anything you can ask for, any protection, or any named service updates the pages of this guide that describe it, in the same session. And anything learned the hard way becomes a check or a written decision, never only a line in the chat.
If a session ends abruptly, a closed laptop or a dropped connection, the next one finishes the closeout before starting anything new.