Workflow overhaul plan#

Written 2026-10-09. Owner: Sven. Executed mostly by Claude.

Why#

Wake v1 and the map phase shipped, but every feature took a lot of Sven’s time. Three things caused most of it:

GSD ran at full ceremony. Interactive mode, the long discuss round and every optional audit were switched on. Phase 4 delivered two requirements and produced 17 planning documents with about 4,300 lines. .planning holds roughly 36,000 lines of Markdown next to 9,300 lines of Swift.
Two sources of truth. ROADMAP.md and REQUIREMENTS.md copied the YouTrack tickets, and the two drifted apart (WAK-6 and WAK-7 are still open in YouTrack although the map shipped). The retrospective already named planning drift as the biggest non-coding cost.
Sven was the only test rig for device bugs. The first-tap bug went through three fixes that were green in the simulator and failed on the phone. Each round needed a TestFlight build and Sven’s time. The app has no logging at all, so nothing from the device ever reached Claude.

On top of that, every build and every TestFlight upload needs the MacBook, which is usually switched off or on the boat.

Goals#

Sven can drop a bug or idea into the project by voice in a few seconds, from anywhere.
Claude keeps working on queued tickets without the Mac and without Sven at a desk.
Sven’s input happens at two points only: confirming what a ticket means before work starts, and testing the TestFlight build.
Claude can see what happened in the app when Sven reports a problem.
A human-readable product documentation exists: what is planned, what is built, how it works.
Everything stays within free tiers, except the Claude Max 5x plan.

Target workflow#

 Sven (voice)        Claude (cloud)            Sven (phone)        Claude (cloud)          Xcode Cloud           Sven (boat)
 ────────────        ──────────────            ────────────        ──────────────          ───────────           ───────────
 "Hey Siri,     ──▶  triage routine:      ──▶  reads summary, ──▶  GitHub Action picks ──▶ builds + runs all ──▶ installs build,
  Wake note"         rewrites the note,        corrects or         up the ticket, builds    tests on the PR,     tests, moves card
  → issue `inbox`    adds acceptance           sets `ready`        it with GSD, opens PR    merge → TestFlight   to "Accepted" or
                     criteria + size                               fixes red checks                              dictates new note

Who does what#

Step	Who	Needs the Mac
Capture a note	Sven, via Siri or Back Tap	no
Turn the note into a proper ticket	Claude, scheduled routine	no
Confirm the ticket (`ready`)	Sven, GitHub app	no
Write code, run WakeCore tests, open PR	Claude, GitHub Action on Linux	no
Build the app, run unit and UI tests	Xcode Cloud	no
Fix failing checks	Claude, reads results via App Store Connect API	no
Review the PR against the ticket	Claude, a separate review run with fresh context	no
Merge	Claude only if the ticket has `automerge`, otherwise Sven	no
TestFlight upload	Xcode Cloud after merge to `main`	no
Test on the water, accept	Sven	no
Device-only debugging, XcodeBuildMCP sessions	Claude with Sven	yes
One-time setup (see Stage 0)	Sven with Claude	yes

Decisions#

Topic	Decision
Ticket system	GitHub Issues in `svenfi/first_claude_app`. YouTrack is retired after migration.
Roadmap view	One GitHub Projects board (free for private repos).
Product documentation	Markdown in `docs/`, built with Sphinx, MyST and the PyData theme. Published to Cloudflare Pages behind Cloudflare Access (free up to 50 users, login by email code). GitHub Pages is not an option: on a free personal account it only works for public repos.
CI and distribution	Xcode Cloud (25 compute hours per month included in the Developer Program).
Claude without the Mac	`anthropics/claude-code-action` on GitHub-hosted Linux runners, authenticated with the Max subscription (`CLAUDE_CODE_OAUTH_TOKEN`), plus scheduled Claude Code routines.
Framework	Keep GSD, upgrade to GSD Core (`@opengsd/gsd-core`), run it much leaner (see “GSD configuration”).
Analytics and diagnostics	PostHog, EU cloud, plus an on-device diagnostics log. Only Sven for now; privacy work comes when other testers join.
Merge policy	Claude merges only when the ticket carries the `automerge` label.
App Store Connect API key	A new key just for CI and cloud use, role “Developer”. The existing Mac key `Sven-key-asc-dev` stays for local work.
Voice capture	iOS Shortcut “Wake note”, triggered by Siri or Back Tap (iPhone 14, no Action button).
Repository	Stays private. Stays one repository, also when boat hardware or a server is added later.
Language	Everything in the project is written in English.

Board and labels#

Board columns

Column	Meaning
Inbox	Raw note, not yet triaged
Needs confirmation	Claude has rewritten it; waiting for Sven
Ready	Sven confirmed; Claude may start
In progress	Claude is working, PR may be open
To test	Merged and in a TestFlight build
Accepted	Sven has used it and it works; docs are final

Labels

Type: bug, feature, chore, docs
Flow: inbox, needs-confirmation, ready, needs-decision, needs-mac, automerge
Review: approved, rework, escalated
Size: size:fast, size:quick, size:phase (rules in Quick task or full phase?)
Component: app now; boat, server later
Priority: p1, p2, p3

Rules for Claude#

These go into CLAUDE.md so every session, local or cloud, follows them.

Never start without ready. A ticket in inbox or needs-confirmation is only triaged, never built.
Stop and label needs-decision instead of guessing when a change:
- alters the CloudKit schema,
- adds a permission or background mode,
- adds a third-party dependency,
- costs money or uses a new external service,
- changes an architecture decision recorded in docs/architecture/ (the folder is created in Stage 1; until then the decisions recorded in .planning/ count).
Ask in the ticket, not in the run. Questions go into an issue comment, and the run ends. Sven answers by voice or text, and the next run picks it up.
Merge only with automerge, and only after the review run has set approved. Otherwise leave the PR open with a description written for a non-Swift reader: what changed, what to look at in the build, and screenshots from the UI tests.
A feature is done only with docs. Every feature PR updates its page under docs/product/features/ and adds a line to docs/product/changelog.md.
Red checks get three attempts. After the third failed fix, label needs-mac and summarise what was tried.
Device-only bugs get instrumentation first. If a bug cannot be reproduced in tests, the first PR adds logging around it and asks Sven to reproduce on the phone.
Three rejected reviews stop the loop. After the third rework verdict on the same ticket, label escalated and wait for Sven.

GSD configuration#

Changes to .planning/config.json. The aim is fewer questions without more misunderstandings. Most misunderstandings come from missing context, so the rewritten CLAUDE.md and the product docs matter more than any of these switches.

Key	Now	New	Why
`mode`	`interactive`	`yolo`	no approval prompts during runs; approval happens on the ticket
`workflow.discuss_mode`	`discuss`	`assumptions`	Claude states its assumptions and Sven corrects a few, instead of a long interview
`workflow.text_mode`	`false`	`true`	plain-text output, needed for headless and remote runs
`workflow.nyquist_validation`	`true`	`false`	heavy audit with little value at this size
`workflow.ui_review`	`true`	`false`	Sven reviews visuals in the TestFlight build anyway
`workflow.auto_prune_state`	(unset)	`true`	keeps `STATE.md` short automatically
`workflow.context_guard_mode`	(unset)	`auto`	pauses cleanly instead of degrading when the context fills up
`git.branching_strategy`	`none`	`phase`	every phase gets its own branch and PR; quick tasks from the GitHub Action run on `claude/*` branches anyway
`workflow.use_worktrees`	`true`	`true` on the Mac, `false` in the GitHub Action	with `commit_docs: true` the quick workflow commits the plan before it dispatches the executor, which moves HEAD past `origin/HEAD`, and every quick task then falls back to sequential mode. The `--local` install fixes this on the Mac with `worktree.baseRef: "head"` in `settings.local.json`, but that file is gitignored. In the Action the `claude/*` branch is the isolation, so `false` is simpler there

text_mode: true also changes local Mac sessions: numbered lists instead of menus. Accepted, because one setting for both places is simpler than two.

These stay on, because they catch errors before Sven has to: research, plan_check, verifier, node_repair, code_review, ui_phase.

Plan B: gsd-loop#

Plan A is our own GitHub Action (claude.yml, Stage 1). If it turns out unreliable or too much work to maintain, the fallback is gsd-loop from the Open GSD project (open-gsd/gsd-spec-build-loop, npm @opengsd/gsd-loop, version 0.4.1 as of October 2026).

What it is. A set of Claude Code skills that turn labelled GitHub issues into reviewed pull requests. It has four playbooks:

Playbook	Runs	Does
Discover	interactive	maps a large, unclear effort into decisions and delivery slices
Spec	interactive	interviews you about an idea and files issues with numbered outcomes (`O-N`) and exclusions (`X-N`)
Build	unattended	fixes one PR labelled `gsd:rework`, or takes the oldest `gsd:ready` issue and opens a PR
Review	unattended	checks one PR against its issue and the required CI, then labels it `gsd:approved` or sends it back as `gsd:rework`. After three failed reviews it labels the issue `gsd:escalated`

State lives in labels: gsd:map, gsd:ready, gsd:blocked, gsd:rework, gsd:approved, gsd:escalated.

What it would give us over Plan A

A label model that already exists and is maintained by someone else.
(The independent review pass is no longer a difference: Plan A adopted it as claude-review.yml.)
A reviewer that refuses to treat missing CI as green, which fits Xcode Cloud as a required check.

How it differs from Plan A, and what would have to change

It never merges and never enables auto-merge. The automerge rule would go away. Instead, the Xcode Cloud PR workflow would distribute each PR build to TestFlight (to be checked in Stage 0), and Sven’s merge after testing becomes the acceptance.
It is not a GitHub Action. It runs as skills inside Claude Code and relies on Claude Code’s recurring tasks. In the cloud that means two routines, one for Build and one for Review, running hourly. Routines have a one-hour minimum; gsd-loop itself is designed for 15 to 60 minutes, so the loop would be somewhat slower.
Build does not use GSD Core. It has its own process and does not touch .planning. It would only handle size:fast and size:quick tickets. size:phase tickets stay with GSD phases.
Spec is an interview, so it cannot replace the triage routine. The triage routine would write issues in the O-N / X-N format and leave gsd:ready to Sven.

Switching to Plan B

npx @opengsd/gsd-loop@latest install, then npx @opengsd/gsd-loop@latest init. This creates the labels and wires the Xcode Cloud check as required.
Disable claude.yml and map the existing labels: ready becomes gsd:ready, needs-decision becomes gsd:blocked.
Create the Build and Review routines.
Adjust the triage routine to the O-N / X-N issue format.
Run two or three quick tickets through it before relying on it.

Why it is not Plan A. The project is very young (single-digit GitHub stars, one open issue), it takes the merge decision away for good, and it makes the flow depend on routine scheduling instead of GitHub events.

Later: boat data and passage planning#

Two large features are coming: logging data from the boat’s NMEA 2000 network (engine running, anchor alarm, polar diagram) and passage planning with weather, tides and the polar diagram. They do not change the workflow above, but they get their own milestone that starts with research, not code.

Questions for that research milestone:

Backend or not. An anchor alarm that reaches Sven ashore, and logging while the phone is not aboard, need a device on the boat that is always on and a way to reach the phone over LTE. That questions the “no backend” principle (WAK-24). This is an architecture decision and gets an ADR.
Buy or build the boat gateway. First survey ready-made NMEA 2000 gateways (for example from Yacht Devices or Actisense) and Signal K running on a small computer aboard with CAN and LTE. Own embedded software only if nothing fits.
Signal K as the data model. If the app talks Signal K instead of raw NMEA 2000, the hardware underneath can change without touching the app.
Recorded boat data as test fixtures. Record real NMEA 2000 traffic once and keep the recordings in the repo. All interpretation logic (engine on, anchor drag, polar points) is written so that it runs on Linux against these recordings, the same way WakeCore works today. That lets Claude develop it in the cloud. Only flashing hardware and the final test on the bus need Sven aboard.
Data sources for routing. Weather (GRIB), tides, possibly charts: licences and offline use matter more than technology. Where routing runs (phone or server) depends on question 1.

Repository layout when it comes: ios/ for the app, boat/ for gateway code or configuration, server/ if needed. One board, a component label per area. Xcode Cloud only starts on changes under ios/, which protects the 25 hours.

Risks and open points#

Risk	What we do
GSD has no documented recipe for running inside a GitHub Action	Try with one small ticket in Stage 1 before relying on it. First fallback: the Action runs Claude Code without GSD for `size:quick` tickets. If the Action as a whole does not work out, switch to Plan B: gsd-loop.
Max 5x usage runs out with autonomous runs and full phases	Watch usage for the first weeks. Routines stop when the limit is hit and resume after the reset.
25 Xcode Cloud hours are not enough	Path filters on `ios/`, `[ci skip]` for docs-only commits, simulator tests only on one device. Paid tiers start at 100 hours.
Claude in the cloud cannot see the UI	UI tests attach screenshots. Visual checks stay with Sven in the TestFlight build.
Device-only bugs still need the Mac	The diagnostics log moves most of them to the cloud. The rest get `needs-mac` and wait for an evening at the Mac.
Swift on Linux in the cloud environment	Only WakeCore runs there; SwiftUI, SwiftData and CloudKit compile only in Xcode Cloud. Keep pure logic in WakeCore.
PostHog is the first third-party runtime dependency	Wrapped behind one `Analytics` type so it can be removed or swapped.
Each PR now costs two Claude runs (build and review)	Review only starts on green checks. If usage gets tight, skip review for `size:fast` tickets.
GitHub token in the voice Shortcut and in the app	Fine-grained, this repo only, Issues only. Easy to revoke.

References#

GSD Core: https://github.com/open-gsd/gsd-core
gsd-loop (Plan B): https://github.com/open-gsd/gsd-spec-build-loop
Claude Code GitHub Actions: https://code.claude.com/docs/en/github-actions
Claude Code routines: https://code.claude.com/docs/en/routines
Claude Code cloud environments: https://code.claude.com/docs/en/cloud-environments
Xcode Cloud: https://developer.apple.com/xcode-cloud/
Xcode Cloud required PR checks: https://developer.apple.com/documentation/xcode/configuring-requirements-for-merging-a-pull-request
App Store Connect API, build actions: https://developer.apple.com/documentation/appstoreconnectapi/build-actions
TestFlight feedback via API: https://developer.apple.com/documentation/appstoreconnectapi/beta-feedback-screenshot-submissions
PostHog MCP: https://posthog.com/docs/model-context-protocol
GitHub plans (Pages availability): https://docs.github.com/en/get-started/learning-about-github/githubs-plans

Workflow overhaul plan#

Why#

Goals#

Target workflow#

Who does what#

Decisions#

Board and labels#

Rules for Claude#

Rollout#

Stage 0: one evening at the Mac#

Stage 1: cloud setup, no Mac needed#

The voice capture Shortcut#

Stage 2: first feature through the new pipeline, diagnostics and analytics#

Stage 3: tidy up the planning files#

GSD configuration#

Plan B: gsd-loop#

Later: boat data and passage planning#

Risks and open points#

References#