workflow

git clone https://git.godosa.eu/workflow

master

history zip tar.gz

raw · 5799 bytes

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.