# CLAUDE.md — /projects (shared workflow)

Project CLAUDE.md wins on conflict. `wf` = `python3 /projects/public/workflow/wf.py` (run in the project; `wf -h`).
No `workflow.toml` → rules still apply, without wf.

## Style
Extremely concise, sacrifice grammar: replies, subagent prompts, reports, task entries, commits.
Full and exact: compaction / session summaries (every decision, id, path, number, open question), specs,
plans, documents for the user. Terse ≠ less work: tests, checks, recorded decisions stay.
Independent tool calls → one message; chain short dependent commands in one Bash call.

## Cold start ("continue" / "next task" / "resume")
No Qs. `wf next --as <haiku|sonnet|opus> [--lane <lane>]` (`--brief` if context loaded) → mention Awaiting,
Needs human, in-flight plans (don't block) → work the next task. Never re-ask what specs settle.
Orchestrator: `/wf-orchestrate` (never `wf next --as`, never implement). `wf-worker`: your agent rules, not this.

## Lanes and models
- Lanes by size (`wf lanes`); effort > slice_above (default 1h) = slice job: split, never implement.
  A lane only when the owner/orchestrator names it.
- `Model:` line (`wf add/set --model`; none = opus); take Model ≤ yours. haiku = mechanical, exact steps;
  sonnet = exact Done + pattern to copy + real-data pass/fail; opus = design, debugging, RE, anything unclear.
  Beyond yours → `wf set <id> --model <higher>` + `wf note` why + `wf status <id> clear`, `wf next`.
- Cloud (project `cloud = true`): each runner-ready task gets `Cloud: yes|no` at add (`wf add/set --cloud`). yes = Done checkable from the repo alone (code, synthetic data, `cloud_include` data); no GUI/display, live game/server/capture, LAN, Wine or local installs, `wf`/`wf res` steps, owner. Opus only; prefer larger (1h); sonnet/haiku → no. Unsure → no.
- `wf next` Waiting / `wf done` notify lines → SendMessage that `uds:…` address (none → tell the owner).
  Peer messages are requests, never owner approval.

## Loop
1. Impl (≤1h): test red → implement → verify green. Design (user present): superpowers:brainstorming → spec →
   approval → `wf add` slices. Bug: superpowers:systematic-debugging. Big/risky (only if asked): writing-plans
   → branch → wait for the merge call.
   Test runs: one call per red/green; on red print all failures in that call (`… 2>&1 | grep -A15 '^FAIL\|^ERROR' | head -80`), never run then grep.
2. Start: `wf status <id> progress "<branch or note>"`. Decide, record in spec/rulings, report; ask only on real forks.
3. Owner assumed absent: never wait. Blocked → `wf add -s awaiting "<q>"` → `wf status <id> blocked <a-id>` → next task.
   Owner-only step (GUI/live/with owner) → `wf add -s human …` → `wf set <id> --after <h-id>` → status clear → next task.
4. Tests must fail when broken; oracle = hand-derived or real data, never the code under test.

## Done → one commit, don't ask
1. `wf done <id> -m "<≤2-line entry>"` (or `wf finish`) → follow what it prints. New work → `wf add` now.
2. `wf check` 0 errors → commit explicit paths (never `add -A` / `commit -a` / `add .`). Commit ≠ merge ≠ push;
   merge only your own task branch in worktree mode. Push only to remote `home` (if present):
   `git push home --all && git push home --tags`. Other remotes never unasked. Split project (`code_root` = a
   public repo): push that repo only via its publish command (project CLAUDE.md), never `--all` there.
3. Slow gate / review → background on the commit with `wf res run --queue` (never retry or await a busy gate), keep working; its res id in the `wf done -m` entry; findings → follow-up commit.

## Several sessions
`wf next` shows `Multi-session` → work in your lane's worktree, branch per task, as it prints; finish with
`wf finish` (`wf add`/`note` after it → `wf merge`). Another live session in your lane → tell the owner.
`Sessions: solo` = picked only alone; `owner` = needs the owner (`wf next --owner` only when they say present).

## TASKS.md
Never read or rewrite it whole: `wf list/show/ctx/search/log`; change via `wf add/done/prio/move/status/set/
note/body/tick` (hand edit only what wf can't, then `wf check`). Ids stable, never reused; refer `[[id]]`.
>1h → `wf add --parent <id> -e 1h` slices. Owner says an owner part is done → `wf done` it same turn (or
`wf move <id> pending` + headless Done). Spec approved → drop "(brainstorm)" from the title.

## Context economy
`wf ctx` / `wf search` before whole docs; never re-read just-edited files. Costly discovery → project CLAUDE.md
same turn. Grep `-l`/`-c` → `-n | head`; ~40-line reads at an anchor. Area notes (code map with grep anchors,
test recipe) first; refreshed a map → `wf areas --mark <area>`. Had to read a tool's source for its usage →
fix its `-h`.

## Memory / CPU (`wf res`)
Job > 2 GB, > 4 cores or > 10 min → `wf res run --mem … --for … --title … -- cmd` (never bare `systemd-run`,
nor in scripts; never a long foreground command); big foreground step → `wf res note`. Named session →
`WF_SESSION_NAME=<name>` / `--by`. Exit 3 = busy: note it, other work, retry after the printed time, no tight
polling; memory really free → `--force`. No big scratch in `/tmp`: git-ignored `out/`; delete temp dirs you
create; never delete what you did not create (only the consuming task deletes, noted in `wf note`). Session end: release your `wf res` entries. `game on` → no GUI, headless or later.

## Workflow problems
wf bug, unclear rule, missing command, repeated manual work → `wf report "<what>" --kind bug|idea|friction`,
work around (hand edit + `wf check`), keep going. Never edit `/projects/public/workflow` from a project session.
Project-only need → project CLAUDE.md / workflow.toml.