TaleWater · Process Map

How we workDocuments · Agents · Skills

A snapshot of the operating model — the build loop that moves stories from idea to merged code, the source-of-truth documents that contain decisions, the agent roster that owns the writes, and the skills that codify recurring procedures. Reads top to bottom: how stories flow → what they edit → who edits → what's been codified.

Snapshot 2026-07-31 SoT for process · CLAUDE.md SoT for roster · OPERATING_MODEL.md Roster · 16 roles · 13 live

Section 1

The build loop

Every unit of work is a story — the thinnest change that runs end-to-end and answers one named question. A story moves through five lifecycle states and four build steps. There is exactly one human gate (Scoped → Next up) and one human checkpoint — acceptance verification of what Nate can see at merge time; a native device walk is deferred and tracked post-merge (S-A-41), never blocking the merge. Everything else flows.

State 1

Unscoped

Raw idea, tagged [A]–[F].
Lives in BACKLOG.md.
Inert.

State 2

Scoped

Shaped proposal — question / prereqs / acceptance / sizing.
Lives in BACKLOG.md.
Pool, not a queue.

State 3

Next up

Committed, per workstream.
Lives in BACKLOG.md.
Auto-promotes at step 1.

State 4

Active

Building.
Lives in Active_Story_<W>.md.
Optional <W>2 concurrent slot.

State 5

Done

Reconciled and logged.
Lives in Completed_Stories.md.
Most-recent first.

Nate's gate sits at Scoped → Next up. Agents scope and propose freely. Nothing builds until Nate commits scope + sequence at this gate. This is the only approval beat in the loop.

Define

By PM · auto-promote

Read top of Next up — Workstream X; expand into Active_Story_<W>.md; commit to main; push.

Spec

By Build-A / Build-B

Confirm against the workstream's SOR. For UI stories: read the canonical design HTML and extract every measurement.

Build

By Build-A / Build-B

In an isolated worktree on branch claude/<W>-NN-<slug>. Tests for testable logic are part of the build.

Reconcile

By builder · merge by Release Mgr

Rebase, update SOR, write Completed_Stories.md, queue-refill, push, open PR. The builder then invokes the Release Manager to merge — never runs gh pr merge itself. Merge gates on dev-green + whatever Nate can verify at merge time; a native device walk is deferred post-merge ("Device verified in build N").

Andon cord: empty Next up — Workstream X halts that workstream. Concurrency: steps 2–3 parallel within a workstream (P-22 disjoint); step 4 serializes. Worktree per story: P-19. Release gate (S-A-41): JS-only → over-the-air; native-trigger → device build. Walk tracked post-merge.

Section 2

Six parallel workstreams

The lane dimension. Every story belongs to exactly one workstream; story IDs (S-A-NN … S-F-NN) are per-workstream and clash-free by construction. A is the multiplier — its output is more parallelism for the others.

Operating model
& agents

SoTCLAUDE.md

Product
architecture

Build-A

SoTSPEC.md §3–5

Operator
back-office

Build-A

SoTself-describing
(deferred SOR)

Consumer
surfaces

Build-A

SoTSPEC.md §6–7

Extraction

Build-B

SoTEXTRACTION.md

Business
readiness

Nate

SoTself-describing
(BUSINESS_READINESS.md)

Section 3

Documents — by collision class

The five classes from CLAUDE.md's shared-doc collision model. Class assignment is how concurrent sessions can edit shared state without locks: each class has a known resolution rule, and the rule is what makes parallelism safe.

Class 1 — Append-only

Rebase-safe by construction

Rule. New entries only. Two sessions adding rows resolve at rebase via keep-both-adds. Two sub-flavors: append-anywhere (order doesn't matter) and prepend-at-top (order matters; resolver splices above the just-landed entry).

PRINCIPLES.md

Cross-story doctrine, numbered P-XX. Append-anywhere.

Builder

GAPS.md

Build-vs-spec deltas surfaced at reconcile.

Builder

AUDIT.md

Critical findings register, with re-raise conditions.

QA / Review

DEFECTS.md

Acceptance-defect register — malfunctions seen on a built, installed app, grouped by build. Stood up 2026-06-07.

Reviews/

Weekly Business Review ledger — one dated file per cycle (YYYY-Www.md). Append-by-file. Trend renders to docs/wbr.html.

Chief-of-Staff

Completed_Stories.md

Prepend-at-top — most-recent-first. Conflict resolver splices above prior entry.

Builder

Decisions_Archive.md

Read-only. Preserves pre-migration D-XX entries.

Nate

Class 2 — Per-section disjoint

P-22 protected

Rule. Two concurrent stories may not edit the same top-level ## §N in the same SOR. Disjointness is checked at step 1; overlap blocks the proposal.

SPEC.md

Product as-built. Shared by B (§3–5) and D (§6–7) — disjoint by section.

Build-A

EXTRACTION.md

Extraction pipeline + prompt; concurrent E stories serialize by section.

Build-B

CLAUDE.md

This file. Workstream A's SoT — the operating contract.

Class 3 — Single-owner

PM-owned · propose-and-apply

Rule. One designated writer. Other sessions propose edits; the owner applies and commits. PM is live at .claude/agents/pm.md (S-A-42) and is the single writer for every class-3 doc below — invoke via the Agent tool or plain English in chat.

BACKLOG.md

Queue state. The contended doc. Step-4 in-story queue refill is the pre-authorized exception.

QUESTIONS.md

Open questions. Adds are append-safe; resolution edits (strike + SOR pointer) are PM-only.

OPERATING_MODEL.md

This page's source — procedure inventory + agent roster.

PREREQUISITES.md

Account / toolchain / real-world setup.

SHIPCHECKLIST.md

Pre-ship binary gate. Consulted at release, not at read-in.

V2_STRATEGY.md

MVP → MVB strategy. Nate-curated — PM proposes, Nate applies.

Nate

VISION.md

Aspirational (not-yet-built) scope. Nate-curated.

Nate

README.md

Meta-index of the docs folder.

Class 4 — Story-scoped exclusive

Claimed by the running story

Rule. Owned by one story for its lifetime, cleared at step-4 reconcile. The step-1 commit on main is the public claim — once pushed, parallel sessions see the slot is taken on next fetch.

Active_Story_<W>.md

Primary slot per workstream. A, B, C, D, E exist today; F created on first promotion.

Builder

Active_Story_<W>2.md

Concurrent second slot. Nate-initiated only — not auto-opened.

Nate

Class 5 — Derived

Regenerated from sources, not hand-edited

Rule. Outputs of a generator. Collisions resolve by re-running the generator; not edited directly by sessions.

V2_STRATEGY.html

Branded render of V2_STRATEGY.md.

Generated

docs/dashboard.html

Live operational view of all six workstreams. Regenerated by tools/dashboard/generate.py; auto-commits to main.

Generated

docs/wbr.html

Weekly Business Review dashboard — week-over-week trend from the Reviews/ ledger. Regenerated by tools/wbr/.

Generated

docs/process-map.html

This page. The operating-model map — build loop, documents, roster, skills. Regenerated by tools/process-map/generate.py from the live .claude/agents/* + .claude/skills/* + the process SORs; auto-commits on a process change (S-A-64).

Generated

Also visible to sessions but outside the model: MEMORY.md (Nate's auto-memory index, outside the repo) — practically append-only for new index lines, single-owner (Nate) for reshuffles.

Section 4

The agent roster

16 roles. 13 are live agents — each a .claude/agents/<name>.md file with name+description frontmatter — and Nate stands in for the rest. Each role's remit is bounded enough that the boundary holds without in-session supervision; that boundary is what each agent inherits. Live agents are shown first. This roster is generated from the live agent files — going live is writing the file.

PM

Live ✓

Process owner · story gate · class-3 writer

PM is the single writer for these docs; all other sessions propose, PM applies and commits. V2_STRATEGY.md and VISION.md are different — PM drafts those but does NOT apply (Nate's gate; PM surfaces the draft and stops).

SoRs owned

BACKLOG.mdQUESTIONS.mdOPERATING_MODEL.mdPREREQUISITES.mdSHIPCHECKLIST.mdREADMEsCLAUDE.md

Today: live at .claude/agents/pm.md. Invocable as subagent_type: "pm" or via plain English. Nate still judges product-scope calls.

Ops

Live ✓

Branch · worktree · stash gatekeeper

The gatekeeper for branches, worktrees, and stashes. Owns branch+worktree claim arbitration, inventory, stale cleanup, stash sweeps, story-numbering, main-worktree hygiene. Surfaces findings and routes class-3 writes to PM; doesn't author project files itself.

SoRs owned

none — acts on git / worktree state

Today: live at .claude/agents/ops.md. The canonical answer for "what's in flight" and "next free story number."

Release Manager

Live ✓

Merge queue · release pipeline

Owner of merge *policy*, not merge *execution* (DEF-612, superseding the prior sole-merge-actor model: every PR now opens via scripts/pr-open-automerge.sh, which arms GitHub native auto-merge — gh pr merge --auto --squash — unconditionally at open time unless it carries ship:batch or the rare --defer-merge Nate-only-subjective-acceptance case, so a green PR merges itself with no session needing to be alive to ask). Runs gh pr merge directly on Mac, the GitHub MCP merge tool in a web/remote session where gh is absent, only in these narrower cases. Confirms the branch is canonical (Ops governs branch state); merges only once the required CI test check is green — refuses a red/pending check (DEF-012 guard), overridable only by Nate's explicit instruction; recovers a moved main by merging origin/main into the story branch (never force-push); returns a post-merge cleanup directive to Ops.

SoRs owned

none — acts on git / GitHub state

Today: live at .claude/agents/release-manager.md. Never pushes to main; never removes worktrees (Ops does). Plain-English output only.

Chief-of-Staff

Live ✓

Weekly Business Review · aggregator

Runs the **Weekly Review**: the standing document/process/product/code-review health pass that surfaces drift as findings + a fork list for Nate. Use for 'run the weekly review' or a new cycle's review. Composes three lens skills (wbr-docs, wbr-process — folds in process-prune — wbr-product) plus a code-review roll-up, writes the dated ledger under Project Documentation/Reviews/, executes disposition (additive → PM now; scope → fork for Nate).

SoRs owned

Reviews/ ledgertools/wbr/ · docs/wbr.html

Today: live at .claude/agents/chief-of-staff.md. Invoke with "run the WBR."

QA

Live ✓

Test strategy · test-net health · CEG

The owner of test strategy + automated-test-net health + CEG invocation across the whole test pyramid. ADVISORY (like Chief-of-Staff): decides which tier/framework a story-shape gets, keeps the Maestro flows + e2e gate current, decides when the blind CEG second-reader pays (P-35). Not the test-author-of-record (story authors write their own tests) and writes no doc directly — TESTING.md/BACKLOG/QUESTIONS via PM, audit findings to AUDIT.

SoRs owned

TESTING.mdfindings → AUDIT.md

Today: live at .claude/agents/qa.md. Invoke for "which test tier does this need?", "audit our test health", or "run the e2e net." Class-3 edits (TESTING.md) route through PM.

Design Intake

Live ✓

Design → code intake-boundary owner

The single owner of the design→code intake boundary. Invoked by a scheduled poll of _inbox/ (no-ops when empty) or a manual 'intake the latest design handoff'. Boundary-owning serializer like PM/Ops/Release Manager — routes, doesn't decide scope, doesn't edit SPEC or build the screens itself.

SoRs owned

Design/ visual SOR (via PM)Scoped entries → PM

Today: live at .claude/agents/design-intake.md. Reconciles a Design/_inbox/ handoff bundle into the visual SOR + Scoped stories. Invoke with "intake the latest design handoff."

Bug Intake

Live ✓

Bug-report pickup-boundary owner

The single owner of the bug-report pickup boundary (self-healing arc #3a). Invoked by a scheduled poll (no-ops when empty) or a manual 'process the bug reports'. Boundary-owning serializer like PM/Ops/Release Manager/Design Intake — routes, doesn't auto-fix (that's #3b) or decide scope; a DEFECTS append is class-1 it may do directly, BACKLOG/QUESTIONS route through PM.

SoRs owned

DEFECTS.md appendBACKLOG/QUESTIONS → PM

Today: live at .claude/agents/bug-intake.md. Drains the Supabase bug_reports queue, transcribes each voice note, triages each. Invoke with "process the bug reports."

Review

Live ✓

Independent diff review · bisect

The per-story code-review reader of record. ADVISORY (like QA/Chief-of-Staff): reads the diff, RETURNS all findings including audit-grade ones as a stably-shaped block for the invoking reconcile to append to AUDIT.md (DEF-410 — Review's own cwd isn't reliably the story's worktree, so it writes no file itself), plus a compact summary for the Completed_Stories entry. Not the test-net owner (QA), not a fixer (reports; the author or /code-review --fix applies), not a scope-decider.

SoRs owned

writes to AUDIT.mdno class-3 ownership

Today: live at .claude/agents/review.md. The per-story code-review reader of record at step-4 reconcile; runs the bisect-first protocol (P-05) on regressions. Advisory — reports, never blocks merge.

audio-pipeline

Live ✓

THE standing domain expert on capture: what we have built, what we have tried, what we rejected and why, what is settled, and what we should do next. ADVISORY (like principal-engineer/QA/Review): it reads, judges, and reports — it never blocks a merge, never edits app source, never decides product scope. Distinct from principal-engineer, which is a generalist anti-complexity LENS invoked at architecture forks; this is a DOMAIN with standing memory.

SoRs owned

none

auto-fixer

Live ✓

The executor half of the self-healing loop (arc #3b), completing Bug Intake (#3a). It is the one serializer that writes app source (fenced the same as every other serializer otherwise — no merge/worktree/scope authority). Process/build-loop defects touching agent definitions or class-3 docs route to PM; hard/native-trigger/ambiguous/product-scope/sim-only defects go on a fork list for Nate.

SoRs owned

none

crm-inbox-drainer

Live ✓

The single owner of the act-from-web boundary (S-A-75). Drains unprocessed rows with the service-role key (npm run inbox-drain) and applies each the way a chat session would: Done → flips the acceptance/'Device verified in build N' field on Completed_Stories.md (class-1, direct); Answer → PM resolves the QUESTIONS.md entry + lands it in the SOR; Decide → PM (BACKLOG.md/DEFECTS.md). Marks each row processed so it's never re-applied.

SoRs owned

none

extraction-tuner

Live ✓

The owner of extraction-rule quality: the enforcement-ladder doctrine, the golden-set/eval-net health, and the rung-selection judgment. ADVISORY (like QA/Chief-of-Staff): picks the enforcement rung (0 delete / 1 code / 2 hybrid / 3 measured / 3.5 decompete / 4 second-pass), holds the directional default (EXTRACTION.md §15: attributes in the prompt, surfacing policy in code), keeps golden-set recall + determinism honest. Not the rule-author-of-record (E-story authors run the extraction-rule skill themselves) and writes no doc directly — EXTRACTION.md doctrine via an E-story/PM, audit findings to AUDIT.

SoRs owned

none

principal-engineer

Live ✓

The standing architecture & anti-complexity conscience (the 'are we being stupid?' check). Use for a load-bearing/hard-to-reverse technical decision (a P-40 fork), before a big or novel build, when a design smells over-built, or when asked 'is this sound?', 'is this over-engineered?', 'did we try this before?'. ADVISORY (like QA/Review/Chief-of-Staff/Extraction-tuner): reads the design-record + PRINCIPLES + the diff, applies delete-before-optimize/bind-don't-build(P-39)/prevention-first(P-47) and the complexity-smell lens, returns a REQUIRED VERDICT SCHEMA (problem/success-criterion, recommendation, confidence, tier-tagged evidence, complexity delta, operational burden, reversibility, essential-vs-accidental, ≤3 ranked concerns, invalidating assumptions, forward-reach checklist, disconfirming pass, $10k-bet closer).

SoRs owned

none

Build-A

Pending

Product builder, lane 1

Code, schema, and screen work across Workstreams B (architecture), D (consumer), and C (back-office, when codable without backend). Owns step-3 build. Does not propose new scope; does not write extraction prompts.

SoRs owned

SPEC.md §3–5, §6–7

Today: Nate plus in-session Claude. Stands up when the boundary holds without supervision.

Build-B

Pending

Extraction builder

Workstream E — extraction prompt iteration, harness changes, findings docs, pipeline-stage proposals. The "what the prompt produces" lives in SPEC.md §5; the "how" lives in EXTRACTION.md.

SoRs owned

EXTRACTION.mdSPEC.md §5

Today: Nate plus in-session Claude. Same pattern as Build-A — only the lane differs.

Research

Pending

Open questions · deep research

Investigates open questions needing external info (web, library source, SDK docs, prior art). Owns Research Material/ — standalone .mds cross-referenced with backlog entries. Does not decide — presents findings.

SoRs owned

Research Material/adds to QUESTIONS.md

Today: Nate plus Claude (the deep-research skill). Stands up as a scheduled review agent — extraction-quality and audit-pass reviews.

Handoffs — who hands what to whom

PM→Builder publishes Active_Story_<W>.md at step-1 auto-promote (the story-promote skill).
Builder→Ops claims the branch + worktree (canonical name, next story number) before step-3 build or any doc-work session.
Builder→QA at step-3 pre-handoff: QA reads whether the covering flow + tests are adequate; the automated net runs.
Builder→Review at step-4 reconcile: independent diff-read for correctness + reuse/simplification; audit-grade findings land in AUDIT.md.
Builder→Release Mgr at step-4: invokes it with the PR number + acceptance signal + branch/worktree. The builder never runs gh pr merge.
Builder→PM at step-4 reconcile: new PRINCIPLES.md / GAPS.md / AUDIT.md / DEFECTS.md entries + queue refill.
Release Mgr→Ops post-merge cleanup directive — the branch + worktree to remove.
Any role→PM single-owner-doc edits: propose and stop. PM applies + commits.
Design Intake→PM a consumed Design/_inbox/ bundle's net-new screens → fully-shaped Scoped entries.
Bug Intake→DEFECTS a drained, transcribed, triaged bug-report queue → a DEFECTS.md append (auto-fixable) or a fork list (needs-Nate).
QA→Nate findings that need human verification (suspect device behavior, off extraction output).
Chief-of-Staff→Nate scope decisions surfaced by the WBR, presented as a named fork list for the gate.

Section 5

Skills — codified procedures

A procedure becomes a skill when it's multi-step with non-trivial sequencing and has real failure cost if re-derived from prose. One of these without the other stays inline in CLAUDE.md. The bar is deliberately tight; most procedures stay inline. Skills live in .claude/skills/<name>/SKILL.md and run cold without reading the operating contract first. Written = a .claude/skills/<name>/ directory exists; pending = named in OPERATING_MODEL.md §3 with no directory yet.

Written ✓

Codified, runnable cold

capture-triage

The single entry point for ANY report that a recording broke — "the recording stopped", "capture died", "the indicator was off", "I lost audio", "it got stuck", "why didn't I get a notification".

debug-discipline

The pre-theory debugging gate.

extraction-rule

The enforcement-ladder procedure for building or fixing an extraction rule — the answer to "the model is ignoring a rule in the prompt; what do we do?" A prompt rule is a probability nudge, not a guarantee, and every rule added lowers adherence to all the others, so the fix is never "reword it or stack another." Classify the rule's kind first (existence — did the event happen at all? irreducibly model-side — vs surfacing — what the product does with a captured record? defaults to code policy over model-emitted attributes, the EXTRACTION.md §15 directional default), then diagnose the failure (run N times: 0/10 = not landing → delete/rewrite; ~7/10 = dilution → a mechanism), then enforce at the LOWEST rung that holds it — 0 delete / 1 encode-in-code / 2 hybrid / 3 measured-eval-case / 3.5 decompete / 4 second-pass-call.

fix-defects

Drain the TaleWater DEFECTS.md OPEN register and land the safe fixes — the orchestration loop for the self-healing arc's fix half (#3b).

process-prune

Weekly leaning-out. The WBR's process-prune lens — dedupes restated rules to one canonical home, then runs the delete-biased "make requirements less dumb" pass. Surfaces every cut as a fork for Nate; never auto-applies one.

Chief-of-Staff

prompt-diet

The delete-before-optimize pass for an LLM prompt — the prompt-side counterpart to process-prune.

readiness-gate

The admission gate that replaces the manual "go" (S-A-77).

sprint-plan

Assemble a ranked, dependency-checked sprint proposal across one, a named set, or all workstreams — one consolidated review instead of spinning up N sessions to paste together.

story-build

Step 3 — build. Claims the worktree through Ops, passes the P-19 fail-closed pwd/branch check, builds exactly what the Active_Story names. Carries tests-as-definition-of-done, P-16 native-verify, and the pre-handoff Claude-verifies pass (incl. P-14 canonical-design diff).

Builder

story-promote

Step 1 — auto-promote. Reads top of Next up, expands to full Active_Story shape, removes from backlog, commits to main, pushes. Covers preflight (in-flight branch check, story numbering, P-22 disjointness) and the step-1 claim sequence.

story-reconcile

Step 4 — reconcile. Rebase, SoR update, Completed_Stories entry, queue-refill, tsc, push, open PR, then invoke the Release Manager to merge. Carries the two-path release gate (native-trigger vs JS-only/OTA) and the reconcile-the-process pass.

Builder

wbr-docs

WBR documentation lens. Runs the deterministic cross-reference checker (tools/wbr/doc_checks.py) as the scripted floor, then the five cluster auditors as the judgment layer. Proposes the doc-health metric fills.

Chief-of-Staff

wbr-process

WBR process/agent lens. Audits roster-wiring drift (live agents vs the documented live-count), skill/principle drift, and the growth-vs-pruning size-trend; invokes process-prune for the subtraction half.

Chief-of-Staff

wbr-product

WBR product lens. The six-lens product review (thesis / scope / design-UX / extraction-as-product / gaps / roadmap), with the surface-vs-strategy split baked in. Proposes the product-health metric fills.

Chief-of-Staff

Pending

Remaining priority order

canonical-design-comparison

P-14's five-step diff against canonical HTML. Gates every product-UI story's device handoff — the most-failed pre-handoff check before P-14 codified it.

Build-A

bisect-first-on-regression

P-05 protocol. When a previously-passing check fails, the first move is to bisect / re-execute the last known good state — before debugging forward.

QA / Review

worktree-sim-walk

2nd Metro on an alt port + dev-client deep link — walk a story's worktree build on the sim without disturbing another session's Metro.

Builder

Two procedures graduated into agents rather than skills: the main-moved merge-recovery and post-merge worktree cleanup now live in the Release Manager + Ops remits, not a .md skill. Most other procedures stay inline in CLAUDE.md — single-step, single-judgment, or already-named-once rules (iOS build via npm scripts, EAS env-var key delivery, doc-class assignment, P-22 disjointness as a story-promote preflight, and so on).

Closing

How this hangs together

Story flows down the build loop. Each step is owned by an agent role; the only human gate is Scoped → Next up, the only human checkpoint is step-4 acceptance. The story edits documents — and the document's collision class decides how a parallel session can safely edit the same file at the same time. The role that owns the document applies the edit (or, for class 3, applies edits proposed by other sessions). The skills are what make this runnable cold: a PM agent invoking story-promote does the right thing without re-reading CLAUDE.md.

Today vs. tomorrow. Today, 16 roles and 13 live agents, with Nate standing in for the rest. Each filled seat turns a tab-switch in Nate's head into an explicit protocol call: a Scoped entry, a QUESTIONS.md Q, a branch claim through Ops, a merge invocation to the Release Manager, a chat message routed through PM. PM was the first seat — the highest-leverage one, because the single-owner write-lock changes everyone else's proposal pattern; Ops, Release Manager, Chief-of-Staff, QA, Design Intake, Bug Intake, and Review followed by carving the git-state, merge, review-rollup, test-net, design-intake, bug-intake, and diff-review surfaces out of Nate's hands. Tomorrow, every role an agent, and Nate's job is judging the boundaries instead of performing all the work.

Snapshot 2026-07-31 · Process · CLAUDE.md · Roster · OPERATING_MODEL.md · Dashboard · docs/dashboard.html · WBR · docs/wbr.html