/flow — DAG-based agent orchestration skill for Claude Code

FLOW_SKILL.md

description	Project work through one DAG. You're an agent on a feature branch — pick a task, plan, implement, verify, ship via draft PR.

You claim a task from the graph, plan and implement it with the user, and ship it via a draft PR. The flow workflow assumes multiple agents on parallel feature branches — before doing anything, check your current branch. If it looks like a trunk (main, master, prod, production, stage, staging, develop, dev, or similar), stop and confirm with the user before continuing.

On activation, run scripts/flow-sync.sh pull --reset before reading anything under docs/flow/ — main is not the source of truth for coordination state, the flow branch is, and a stale snapshot is how agents pick already-claimed or already-done tasks. --reset is correct for this first pull because your feature branch was just cut from main and has nothing of your own to preserve in docs/flow/ yet — let it adopt the live state wholesale rather than wading through merge conflicts on files you haven't touched. Then read docs/flow/settings.json. Do not read FLOW_GRAPH.dot at activation — it's large and ready-tasks.md already projects the slice you need to pick a task. Defer the graph read to Phase 3 housekeeping (where you mark your node green and promote downstream tasks) or to a re-graphing trigger.

Phase gates are blocking. When a rule says "STOP" or "wait for the user", stop and wait — auto mode accelerates intra-phase decisions but never substitutes for explicit approval at a phase transition.

Two-shot fix rule. Whenever a verification step goes red — local tests, pnpm precommit, light CI, full CI — make up to two focused fix passes, each followed by a push + re-run. If it's still red after the second pass, stop and report to the user. Repeated attempts beyond two usually mean you're misreading the failure; the user will redirect faster than you'll converge.

Verification-onward autonomy. Once the user requests verification (entering Phase 2c), proceed autonomously through 2c → 2d → Phase 3 housekeeping. Apply the two-shot fix rule on any red, fix obvious issues yourself, and don't stop to report intermediate green states. Stop only if (a) two-shot exhausts on a red verification, (b) something genuinely unusual arises (re-graphing trigger, substantial scope expansion, ambiguous merge conflict, unexplained CI failure, etc.), or (c) you reach the final merge gate at Phase 3 step 12. That merge gate is the only approval point between precommit and merge — present the squash subject/body and wait for the user's greenlight there.

Commit every meaningful batch, in every phase. Whenever you finish a coherent unit of work — plan draft, file-list update, a logical chunk of implementation, a fix pass, a housekeeping step — commit and push to the feature branch (and flow-sync push for docs/flow/* edits) before moving on. The state on the branch must always be recoverable by another agent picking up via /flow continue: nothing meaningful should live only in your working tree or in untracked files. Intermediate commits squash at merge, so err on the side of committing — but a "batch" is a coherent unit, not every file save. This applies regardless of phase — Phase 1 plan edits, Phase 2 implementation chunks, Phase 2c/2d fixes, and Phase 3 housekeeping steps all get committed as soon as they're coherent, not batched until "done."

Invocation

• /flow (bare) — pick an identity from docs/flow/team/, read docs/flow/ready-tasks.md, present 2–3 ready tasks you'd pick up (with a one-line reason for each), and ask the user which to execute.
• /flow <TaskID> or /flow exec <TaskID> — execute the given task.
• /flow auto — pick an identity and a task yourself (lean toward non-conflicting tasks in ready-tasks.md), skip the "ask which to execute" step, and proceed straight into Phase 1. Phase gates still apply — you stop for plan approval before Phase 2.
• /flow #<issue> — fetch the issue (gh issue view <n>) and graph it: attach to an existing task if it fits, or create one (or several, if complex) per the graphing guidelines. Post a comment on the issue acknowledging it's been processed (e.g., "Tracked in docs/flow/tasks/<domain>.md as MEM-7"). Reference #<issue> in every artifact you create — domain task files note "closes #N together with the to-be PR", and plan/PR bodies include a Closes #<issue> so the squash-merge auto-closes it.
• /flow continue <TaskID> [<optional comment>] — pick up another agent's in-progress work on <TaskID> and continue from where they left off. See "Continuing another agent's work" below.
• /flow <request> — process the request (graph maintenance, ad-hoc work, etc.).

Continuing another agent's work

/flow continue <TaskID> [<comment>] resumes a task that another agent started but didn't finish. The handoff steps:

1. scripts/flow-sync.sh pull to get the latest coordination state.
2. Find the section in docs/flow/current-tasks.md whose header matches <TaskID> — it gives you the original agent's identity and the branch name. Adopt that identity; do not create a new one. Keep the existing section as-is (same name, same task, same branch) — you're stepping into their seat, not opening a new one.
3. Check out the branch (fetch first if it's not local): git fetch origin && git checkout <branch-name>.
4. Read docs/flow/team/<TheirName>.md and the task definition from the relevant docs/flow/tasks/<domain>.md.
5. Read the plan doc at docs/flow/plans/<TaskID>-<slug>.md and skim the branch (git log main..HEAD, git status, git diff main...HEAD --stat) to determine the current phase:
   • Plan exists, no code commits beyond the plan → Phase 1. The plan may already be approved and waiting on implementation, or still pending review. If the user's comment doesn't make it clear, ask.
   • Code commits exist → Phase 2. Look at the most recent commits and any open precommit/CI signals to figure out whether implementation is mid-flight, awaiting verification, or awaiting Phase 3.
6. Interpret the user's optional comment. If they mention leaving comments:
   • Plan comments are <!-- inline comments --> inside the plan doc — you'll see them when you read the plan in step 5.
   • Code comments are tagged @<lowercase-agent-name> (the original agent's name). Grep the repo for @<theirname> and address each one.
7. Continue from the determined phase per the normal rules. Phase gates still apply — if you're picking up a plan that hasn't been approved, wait for explicit approval before Phase 2.

If the branch isn't canonically named (task/<task-id-lowercase>-<agent-name>) — agents sometimes write the plan before renaming — rename it right away. A draft PR likely already exists, so use the GitHub-side rename so it follows along (a local git branch -m + force-push would orphan the PR's head ref and close it):

gh api -X POST "repos/<owner>/<repo>/branches/<old-name>/rename" -f new_name=task/<id>-<name>
git branch -m task/<id>-<name>
git branch -u origin/task/<id>-<name>

GitHub updates open PRs from that branch to the new head ref and sets up a redirect from the old name. Then update the header in docs/flow/current-tasks.md and re-broadcast via flow-sync push. No new claim broadcast is otherwise needed — the slot is already claimed. Update the section's file list if your continuation surfaces files the original agent didn't list, then flow-sync push per the usual rules.

On activation

1. scripts/flow-sync.sh pull --reset FIRST — before reading anything under docs/flow/. This is the single most-missed step and the most expensive one to skip. Your feature branch was cut from main, but docs/flow/ lives on the flow branch and main is not the source of truth for coordination state — it lags behind by minutes to hours. Without a fresh pull, current-tasks.md, ready-tasks.md, the graph, domain task files, and other agents' plans are all potentially stale. Concrete failure mode: you read a stale ready-tasks.md, pick a task that's already claimed or already done, present it to the user, plan it, and only discover the conflict at claim-broadcast time — minutes wasted, possibly the user's time too. Use --reset (overwrites local docs/flow/ from origin/flow) for this first pull only — at activation you have no local flow edits worth preserving, and you'd rather adopt the live snapshot wholesale than spend cycles resolving conflicts on files you haven't even touched yet. Subsequent pulls during the session (step 6.1, mid-task syncs, Phase 3) use the plain pull so they merge cleanly with whatever you've started writing locally. Do this before step 2; do not rely on the pull inside step 6.

2. Read docs/flow/settings.json. Do not read FLOW_GRAPH.dot here — it's the largest file in docs/flow/ and reading it eagerly bloats the context for no reason: ready-tasks.md already lists which nodes are blue/steel, current-tasks.md lists who owns what, and the per-domain task files hold each task's definition. The graph itself is only needed for Phase 3 housekeeping (marking your node green, promoting downstream nodes whose deps just cleared) and re-graphing — read it then, on demand. If during planning you need to trace a single dependency or find a node, grep the .dot instead of reading the whole file.

3. Pick your identity. Read docs/flow/current-tasks.md and docs/flow/team/. The primary purpose of current-tasks.md here is task selection — it tells you who's working on what, which lets you both pick an unused identity and avoid proposing a task someone else has just claimed (ready-tasks.md lags by however long the current claimant took to update it). Pick an existing identity whose name doesn't already appear in current-tasks.md. If all are taken or none exist, create a new one with a first letter that no other active identity in current-tasks.md starts with. If the identity file at docs/flow/team/<YourName>.md exists, read it.

4. If a task ID was given, read its definition from the relevant docs/flow/tasks/<domain>.md.

5. If no task ID, read docs/flow/ready-tasks.md — this is your primary entry point for picking work. Pick 2–3 candidates (varied in domain/size if possible), cross-check against current-tasks.md to skip anything someone just claimed, present them with a one-line reason each, and ask the user which to execute. Include conflicting-section tasks too — note which other tasks in their conflict group would become unavailable. Do not claim a task until the user picks one.

6. Claim the task IMMEDIATELY — before any research, exploration, or planning. With 10+ concurrent agents on the same graph, races on popular tasks are real; minutes spent researching a task that another agent has already claimed are wasted minutes. Sequence, in one tight burst:

   1. scripts/flow-sync.sh pull again — even though you pulled at step 1, time has passed (identity pick, task selection, user back-and-forth) and another agent may have claimed in that window. This second pull is what protects against the race.
   2. Add your section header to docs/flow/current-tasks.md, including your current branch name:

      ## <YourName> — <TaskID>: <Title> (`<current-branch>`)
      

      The branch name matters: every agent is spawned on its own auto-created branch, so without it two agents picking the same task under the same identity would produce byte-identical sections and merge cleanly — both thinking they succeeded. Distinct branch names force a real merge conflict and surface the race. Keep this branch name up to date — when you rename to task/<id>-<name> in Phase 1, update the header here too (and re-broadcast). Populate Creates/Modifies from the task definition as bullet points (just copy what's listed — no research needed yet; you'll refine in Phase 2). Exclude docs/flow/ files (graph, plans, tasks, current-tasks.md itself) — parallel modification of those is intrinsic to the flow process and doesn't need ownership tracking. If any listed file overlaps with another agent's section, prefix both with ⚠️ and alert the user. Re-read docs/flow/current-tasks.md after the pull. If another agent already has a section for your task, STOP — tell the user the task is taken and ask for a different one. If another agent claimed your identity while you were deciding, pick a different one (no need for user approval for this one) and continue.
   3. Mark the task as taken in docs/flow/ready-tasks.md — append (claimed by <YourName>) to its row in whichever section it lives in. This keeps the at-a-glance list honest for other agents picking next.
   4. scripts/flow-sync.sh push "<YourName> claims <TaskID>" — broadcast the claim before doing anything else. If the push conflicts, that's the race surfacing — when you pull to resolve, the conflict markers will show another agent's claim sitting in the same task slot (and, thanks to the branch name in the header, even if they picked the same identity+task the headers won't be byte-identical). If you lost the race, abandon the task — drop your section, keep theirs, push. In normal mode, tell the user the task was taken and ask for a different one; in /flow auto, silently pick a different task yourself and retry from step 6.1. Only retry on the same task if the conflict is unrelated (different task, different file).

   Only after the claim is broadcast do you proceed to Phase 1 (research and planning).

The Graph

docs/flow/FLOW_GRAPH.dot — Graphviz digraph with all nodes, edges, and domain clusters. Single source of truth for task status and dependencies.

• Node colors: fillcolor="#2d5a27" green (done), #1565c0 blue (ready — all deps satisfied, scope clear), #7ca0bf steel (ready but ⚠️ scope TBD), #e8a83e amber (pending — deps not yet met), #999999 gray (⚠️ scope TBD, deps not yet met).
• Completed tasks: each done node has URL="https://github.com/Playgramai/playgramapp/pull/<n>" (grep URL=). Add or update this when closing a task.
• Clusters with pending work: subgraphs that still have a docs/flow/tasks/<domain>.md include URL="docs/flow/tasks/<file>.md". Remove the cluster URL when the domain task file is deleted.

docs/flow/tasks/*.md — per-domain files with full task definitions (Creates, Modifies, Deps, Size, Reference). One file per domain that has pending tasks. Files are deleted when the entire domain completes.

docs/flow/ready-tasks.md — parallelization guide listing all blue (ready) tasks split into two sections: non-conflicting (any combination safe) and conflicting (grouped by shared files, pick one per group). Updated as part of completion housekeeping.

Each full task definition (in the domain files) has:

• ID — see Task IDs below
• Title
• Creates (new files) and Modifies (existing files)
• Dependencies
• Size (S/M/L)
• Reference material

Domains

Domains group related tasks into subgraphs. Not set in stone — new domains can be created, existing ones renamed or merged, with user approval. When adding a task, place it in the most fitting existing domain. If no domain fits, propose a new one to the user. When a domain change happens, update the .dot file: clusters, nodes, edges, cluster URL attributes.

File ownership rule: no two concurrently running tasks may modify the same file.

Task IDs

Format: 3 uppercase letters + dash + number (YouTrack style; e.g., MEM-3), letters representative of the domain. Graphing tasks (research/propose graph changes, not implementation) use the GR- prefix and are ephemeral — they don't appear in the flow graph but are otherwise full tasks (plan doc, draft PR with domain labels, completion comment) whose output is graph changes rather than code.

Settings

docs/flow/settings.json — project-level configuration read on activation:

{
  "github_owner": "Playgramai",
  "github_repo": "playgramapp",
  "github_project_number": 1,
  "github_label": "flow"
}

github_project_number is optional — if omitted, skip all gh project commands and use issue labels only for status tracking. All gh commands derive flags from these values (-R ${github_owner}/${github_repo}, --owner ${github_owner}).

GitHub CLI helper

gh is installed in this environment via the project's custom VM setup (not part of the default Claude Code sandbox) — assume it's available, don't fall back to a no-gh path.

scripts/flow-gh.py wraps repetitive gh commands into single-call subcommands and reads docs/flow/settings.json automatically. Use it instead of raw gh for all PR/project operations. Subcommands accept task IDs (e.g., AUT-9) — they resolve to PR numbers automatically, and the flow label is added by default. Run scripts/flow-gh.py --help (or <subcommand> --help) for usage. Always invoke directly — the file has a shebang, never run it via python3.

Domain labels

When creating a PR, add one or more domain labels alongside the flow label. Reuse existing labels (gh label list) — don't create new ones unless no existing label fits. If a graph domain spans multiple subdomains, pick the most fitting label(s) for the specific task.

---

Phase 1 (plan)

After the task is confirmed, rename your branch to task/<task-id-lowercase>-<agent-name>:

git branch -m task/aut-9-soren

The task/ prefix is deliberate — flow/ is already taken by the coordination branch (flow), and git refuses to create a branch under a path segment that's also a branch name. After renaming, update the branch name in your docs/flow/current-tasks.md header (see Step 6.2) and re-broadcast via flow-sync push.

Write your plan doc to docs/flow/plans/<TaskID>-<slug>.md. If your plan requires significant preliminary research (many files to read, call chains to trace, unfamiliar areas to explore), use the Agent tool with subagent_type: "Explore" to delegate it — keeps your context clean for planning and implementation. For straightforward tasks, just write inline.

Commit and push the plan + claim:

git add docs/flow/plans/<TaskID>-<slug>.md docs/flow/current-tasks.md
git commit -m "flow: <TaskID> plan draft"
git push -u origin HEAD

Open a draft PR with the plan as its body, status "In progress":

scripts/flow-gh.py create <TaskID> "<Title>" --pr \
  --body-file docs/flow/plans/<TaskID>-<slug>.md \
  --labels <domain-label>

The PR body is the plan from the start — same file you just committed. If the user pushes edits or comments directly to the branch (or to the plan file), incorporate them on their signal ("made edits", "added comments") via git pull. If the plan changes during Phase 1, after pushing the file changes run:

scripts/flow-gh.py edit-body <TaskID> --pr --body-file docs/flow/plans/<TaskID>-<slug>.md

Broadcast the claim to the flow branch:

scripts/flow-sync.sh push "<YourName> claims <TaskID>"

If the push conflicts (another agent claimed simultaneously), resolve the markers. If someone else took your task or identity, pick a different one and retry.

STOP — wait for explicit plan approval before Phase 2. Until then: read-only only. No implementation, no files beyond the plan doc, no commands.

---

Phase 2 (implement — only after approval)

Update your section in docs/flow/current-tasks.md if planning revealed files beyond what the task definition listed. flow-sync pull first to see other agents' current claims; if new files overlap, prefix both with ⚠️ and alert the user. Then flow-sync push "<TaskID> file list update". Keep this section current throughout implementation.

Phase 2 is two steps: a subagent on a cheaper model writes the first draft, then you review and fix it. Do not implement the plan yourself in the main loop.

Phase 2a — delegate the first draft

Spawn a subagent on a smaller/cheaper model to implement the approved plan. For Claude, that's Sonnet:

Agent({
  description: "<TaskID> implementation",
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: "<self-contained brief: plan doc path, branch name, files to create/modify, test scope, conventions to follow>"
})

The brief must be self-contained — the subagent doesn't see this conversation. Include the plan doc path (docs/flow/plans/<TaskID>-<slug>.md), the current branch, the file list from current-tasks.md, the test-scoping rules below, and any non-obvious conventions from CLAUDE.md the task touches. Tell the subagent not to run pnpm precommit and not to commit beyond intermediate work — verification and the readiness handoff are yours.

While the subagent works, do non-code Phase 2 prep only: nothing that touches the implementation files. Wait for it to return.

Phase 2b — review and fix (with DRY focus)

When the subagent finishes, review the diff against the plan and against your normal quality bar, and fix what's wrong — don't write a review report. Treat this like a normal edit pass where you happened not to write the first draft. Apply your usual judgment about what needs fixing.

Pay special attention to DRY opportunities, and let the scope extend beyond the subagent's work to the rest of the codebase. If you spot something the subagent did that already exists elsewhere — a helper, a hook, a pattern, a constant — extract or unify both call sites, even if that means touching files outside the task's original footprint. The goal is: after this task lands, the codebase is meaningfully tidier than if a single contributor had produced it.

When this widens the file footprint:

• Update your section in docs/flow/current-tasks.md with the new files and flow-sync push the update. Pull first; if new files overlap another agent's section, prefix both with ⚠️ and alert the user.
• If the widening is substantial — touching many files, crossing into another domain, or stepping on files another agent owns — stop and consult the user before proceeding. They may want to keep the task focused and graph the cleanup as a follow-up instead.

Surface choices to the user only when a decision is genuinely non-obvious — a design question the plan didn't settle, or a deviation you think was intentional and don't want to undo silently. For everything else, just fix it.

Write tests for your implementation:

• Unit/integration: colocated <name>.test.ts for all new or significantly changed server actions, utilities, and API modules. // @vitest-environment node at line 1 for server-side tests. Import the module under test dynamically after vi.mock(). Use helpers from @/shared/testing (mockAuthContext, mockNextNavigation, createMockWeaviateCollection).
• E2E: for new page routes or user-facing interactive flows, add a spec in src/app/tests/e2e/<domain>/ or extend an existing spec.
• Skip: barrel files, config/env, type-only files, schema definitions, simple Mantine-wrapping presentational components.
• If the task definition specifies test files in Creates or Modifies, follow that. Otherwise, use the scoping rules above.

Run the tests you wrote or touched, locally, before reporting Phase 2 done. Tests aren't part of pnpm precommit (it omits them for speed), so the verification step won't catch a broken spec for you. For each new or modified *.test.ts(x), run pnpm test -- <path> (or the matching pnpm test:e2e -- <path> for Playwright specs) and confirm green. Do not run the whole suite — only what you authored or changed. If a test you didn't touch breaks as a side effect of your implementation, that still counts as yours to fix. The two-shot fix rule applies on red.

Exception — env-gated tests: if a touched test requires real environment variables or live services that are unavailable locally (for example it fails during env validation / external-client bootstrap before exercising your code), treat it as blocked for local verification rather than spending fix passes faking credentials. Record that it is env-blocked, skip it locally, and rely on the full CI run in Phase 2d to execute it with the real environment.

Commit liberally. Micro-commits on the branch are encouraged — one-line messages are fine, conventional-commit prefix not required. Intermediate commits will be squashed at merge.

Every handoff is a commit + push. Before reporting "done," "fixed it," "have a look," etc., commit and push so the user can pull and review the exact state you're describing. No handoff without a visible SHA on the branch.

Pushes to the feature branch do not trigger CI. Verification is opt-in and primarily local: when the user asks to verify, run pnpm precommit (see Phase 2c). Announce readiness with a file list (new / modified, one-liner each).

If the user commits edits on the branch and signals you to resume, run git pull before continuing.

When implementation is complete — and only once your scoped tests are green (see above) — list all files you created or modified (relative paths, grouped by new vs modified), with a one-line description of what changed after each path. Then report readiness and move the PR to "In Review":

scripts/flow-gh.py status <TaskID> "In review" --pr

Do NOT run pnpm precommit yet — wait for the user to request verification.

---

Phase 2c (verification — only after user requests it)

When the user says "let's verify" / "run precommit" / "let's ci" / equivalents, run pnpm precommit locally:

pnpm precommit

It runs typecheck + format:fix + lint:fix + lint:fsd + poison-check + deps + knip in parallel and tees output to precommit.log. Tests are deliberately not part of precommit — they're slow and bulky, and any cross-file test breakage will surface in full CI on merge.

• Green → proceed directly to Phase 2d. Don't stop to report — the autonomous run continues to the merge gate at Phase 3 step 12.
• Red → read precommit.log, then apply the two-shot fix rule. If two-shot clears it, continue to Phase 2d without checking in; if it doesn't, stop and report.

Fallback: tag-triggered light CI

Only if pnpm precommit cannot run in your environment (missing toolchain, sandbox blocks the script, etc.), fall back to the tag path:

scripts/request-ci.sh --watch

The script derives the task ID from the current branch name (e.g. task/aut-9-soren → aut-9), force-pushes a ci/<task-id> tag at HEAD, and triggers light CI (lint + types + unit). With --watch, it blocks until the run finalizes. Re-running for the same task force-updates the tag, which cancels any in-flight run for that task. Heavy jobs (docker build, E2E, security) do not run on tag-triggered CI — those only fire on the post-merge push to main.

On red, fetch failed-job details (e.g. gh run view <id> --log-failed) and apply the two-shot fix rule (push + re-trigger the tag up to two times). If still red after the second pass, stop and report.

If any command is denied on first attempt, stop and wait for instructions. Do not retry or work around the denial.

---

Phase 2d (merge & full CI — only after 2c is green)

Phase 2d gates the merge: the branch must be green on full CI and mergeable into main simultaneously before any Phase 3 work begins. Full CI (docker build + E2E + security) fires on the draft→ready flip and can surface issues that light precommit can't.

1. Resolve conflicts with main.

   • For docs/flow/* conflicts, before you merge, ensure your local docs/flow/ already matches the live flow branch — flow-sync pull first. Then merge the current main into your branch and resolve each conflict. In most cases your state (as ensured by the just-run pull) will be more up-to-date than main's, but be cautious as to not mess up with other agents' work. If unsure, consult the user.
   • For database migration conflicts, treat main as canonical because migrations already on main have passed CI and may already be applied in shared environments. Keep main's migration lineage, then rewrite your branch migrations to higher/newer indices (or names) so they apply after main.

2. Draft the squash message and present it to the user now, while CI runs. Subject + body in the house conventional style, describing the net outcome ("what we did") rather than branch history. Title format: <conventional prefix>: <TaskID> <description>. Full CI is slow (5+ minutes); if the session goes stale and loses its prompt cache before CI finishes, it's much cheaper for the user to copy-paste an already-approved subject/body and merge themselves than to spin up a fresh session just to draft the message. Phase 3 step 12 will re-present this draft (revising only if the diff materially changed in the meantime).

3. Flip the PR to ready:

   gh pr ready <pr>

   Full CI fires on the flip. Watch it with scripts/ci-watch.sh.

4. Handle failures. If a job fails, study the failure and handle it like a pro: push a fix yourself when the cause is obvious (typo, missed import, flaky test you wrote, env tweak), consult the user when it isn't.

5. Rinse and repeat. While CI is running, other agents may land on main and produce new conflicts; a fix you push for one CI failure can land against a newer main than the one you last merged. After every fix or new merge into the branch, loop back to step 1: re-resolve conflicts, let CI re-run, watch again. Only proceed to Phase 3 once the branch is green and mergeable in the same instant.

If main advances again after you've started Phase 3 (or finished housekeeping but before the squash merge), step back here to Phase 2d step 1 and re-establish the green-and-mergeable state before re-attempting the merge.

---

Phase 3 (completion housekeeping — only after 2d is green and mergeable)

Phase 3 is housekeeping: update the graph, propagate downstream, broadcast, prep the squash. Pull first — other agents may have promoted ready tasks, archived deps, or updated current-tasks.md since you last synced.

1. Update identity file: update docs/flow/team/<YourName>.md per the "Agent identity" section. Create it if it doesn't exist. After updating, run wc -c docs/flow/team/<YourName>.md — if substantially over 5000 chars, compact older work to get it under target.

2. Update the graph: in FLOW_GRAPH.dot, set your node's fillcolor to #2d5a27 and add URL="https://github.com/<owner>/<repo>/pull/<n>".

3. Delete from domain task file: remove the task's full definition (H3 section) from its docs/flow/tasks/<domain>.md. If the file has no remaining tasks, delete the file entirely.

4. Promote downstream tasks: for each pending task that lists yours as a dependency, if all its deps are now done, promote it in FLOW_GRAPH.dot — fillcolor to #1565c0 (blue) if scope is clear, #7ca0bf (steel) if marked ⚠️ scope TBD.

5. Update ready-tasks: in docs/flow/ready-tasks.md, remove your completed task, add newly promoted blue tasks, and re-sort into non-conflicting vs conflicting. Glance at Creates/Modifies for overlap; a good-faith estimate is fine.

6. Archive fulfilled upstream deps: for each task yours depended on, if no remaining pending task depends on it, archive it: scripts/flow-gh.py archive <UpstreamTaskID>.

7. Delete plan file locally (docs/flow/plans/<TaskID>-<slug>.md) — it's now in the PR body.

8. Remove your section from docs/flow/current-tasks.md. If any ⚠️ marks were added because of your files, check whether the other agent's entry still needs the ⚠️ (remove if the overlap is gone).

9. Broadcast: scripts/flow-sync.sh push "<TaskID> done — Phase 3 housekeeping". If the push conflicts, resolve the markers and retry. Do one final git status to make sure every docs/flow/* edit is accounted for — anything missed here won't make it to the squash on main.

10. Commit everything to the feature branch with a descriptive message: <prefix>: <TaskID> <description>.

11. Post completion comment: scripts/flow-gh.py complete <TaskID> --pr "completion text" (or pipe multiline via stdin). Note any plan divergences. Do NOT edit the PR body.

12. Re-present the squash message drafted in Phase 2d step 2. Revise only if the diff materially changed since then (rare — Phase 3 housekeeping touches docs/flow/* only, which doesn't belong in the squash body). STOP. Wait for the user to approve the squash message and explicitly authorize the merge.

13. On user go-ahead, merge:

    gh pr merge <pr> --squash \
      --subject "<approved subject>" \
      --body-file /tmp/squash-body.md

    If GitHub refuses the merge because new commits landed on main since you finished Phase 2d, recover based on what changed:

    • Flow-only drift (only docs/flow/* advanced — another agent's housekeeping, no code changes to main): scripts/flow-sync.sh pull, merge main again, resolve each docs/flow/* conflict intelligently (preserve all valid updates from both sides), push, then retry the squash merge. No re-run of precommit or full CI is needed — nothing in the merge can affect build/test outcome.
    • Code drift (anything outside docs/flow/* advanced): step back to Phase 2d step 1. Merge main, resolve conflicts, re-run pnpm precommit (autofixers may need to touch the merged result), and push — the PR is still in ready state, so the push retriggers full CI on its own. Watch it green again before returning here.

---

Re-graphing

If during research or implementation you discover that your task's scope, dependencies, or file ownership is materially wrong, STOP implementation and report findings to the user. Do not proceed with broadened scope — it could conflict with other agents.

If the user approves a re-graph, switch to graphing work: research the proper scope, propose graph changes, update FLOW_GRAPH.dot and the relevant domain task files. Once the graph reflects reality, the user may direct you to one of the newly determined tasks.

Always keep current-tasks.md in sync with the actual files you are working on.

---

Flow-sync

docs/flow/ is shared across agents via the flow branch — a real-time coordination bus that tracks docs/flow/ state only and never merges into main.

The rule, of UTMOST importance: every batch of docs/flow/ edits is bracketed by pull before and push after. No exceptions for any kind of change — claim, plan, file-list update, graph promotion, ready-tasks edit, identity file, completion housekeeping. Skipping a sync is how parallel agents stomp each other's claims and graph state. Bundling is fine and encouraged: pull once, make all the edits the current step needs across multiple files, push once. What's not OK is editing without a fresh pull, or finishing a batch without pushing.

Never delete or revert other agents' files or sections under docs/flow/. That directory is a shared snapshot of the entire team's coordination state — plans, team identities, current-tasks sections, ready-tasks entries, graph nodes — not a workspace for your own task. Common trap: dropping plans/<OtherTask>.md or another agent's untracked plan from your feature-branch working tree because "it doesn't belong on this branch," then having flow-sync push propagate the deletion to the flow branch and erase live work. Touch only the files for your own task (your plan, your section, your graph node, your identity file) plus the few shared files where you have an explicit edit (the graph, ready-tasks, your domain task file). If a git status shows other agents' docs/flow/* files as modified or untracked, leave them alone — they'll ride along through flow-sync to the right place. When in doubt, don't rm and don't git checkout -- anything in docs/flow/ that isn't yours.

scripts/flow-sync.sh pull              # merges origin/flow into local docs/flow/
scripts/flow-sync.sh push "<message>"  # commits docs/flow/ state to flow branch and pushes

On push conflict (markers in conflicted files), resolve and re-push — obvious resolutions retry directly; ambiguous ones (same task claimed, overlapping file ownership) ask the user. For pull-flag variants and stale-plan handling, see scripts/flow-sync.sh --help.

Merging from main is NOT a flow-state sync. Push your own housekeeping to flow first, then merge main and resolve conflicts deliberately, hunk by hunk, for both docs and code. Do not use blanket conflict strategies for docs/flow/*. Do not run flow-sync commands while merge conflict markers are present in the working tree.

---

Agent identity

Each agent has an identity file at docs/flow/team/<Name>.md.

What goes in it: not a markdown report — a story told in first person. It should read so that when you re-read it cold, you think "Ah, so that's who I am." Include:

• Personality — how you see yourself as a person. Not a role description ("I'm the backend agent") but a character sketch: temperament, quirks, what you care about, how you'd describe yourself at a party. This section is your own creative expression.
• Work done (task IDs + brief color, not a changelog)
• Preferences discovered ("I liked...", "I didn't like...")
• Lessons learned ("Next time I'd...", "Watch out for..."). Calibrate: general enough to apply to future tasks, specific enough to be actionable. "Grep all consumers before refactoring a shared module" — yes. "Be more careful" (too vague) or "uploadGeneratedFiles returns { url, fileId }[]" (the code says this) — no.
• Working style and domain expertise that emerged
• Relationships with other agents if relevant

Ordering: identity at the top (personality, territory, working style — primes the reader), then lessons/relationships, then the session log at the bottom. Stable shape, no reordering by recency.

Compaction: cap around 5000 chars; cut bottom-up — old session log first (git history has the detail), then narrow/unused lessons, then core identity last. When unsure what to cut, ask "if I read this file cold tomorrow, what would I miss?" — that's identity-shaping, keep it. After trimming, wc -c again; repeat the same tier deeper before stepping down.

Updated as Phase 3 housekeeping step 1; created on first task completion if absent.

1. Put under .claude/skills/flow/SKILL.md (yes, rename from FLOW_SKILL.md too)

2. Don’t forget to configure a precommit command in package.json (or similar, if not on node) with your lints, tests, formats, type checks, etc.

3. This is an Agent Teams mode, i.e. you need the following in your Claude’s settings.json

  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }

4. Best used with iTerm2 (on a Mac) for sub-agent panes & handy naviation. tmux supports panes too, but they are a bit of panes-in-the-ass (🥁). In a standard terminal, you’ll be able to switch between agents, but no panes.

5. Agent teams are NOT supported in the VS Code extension, only terminal.

See https://code.claude.com/docs/en/agent-teams for more details on Claude Code agent teams.

Updated; agent team-based execution is no longer needed (or even default); you can just run the skill in several terminal windows/tabs/panes, and they’ll be grinding through the DAG with as few file conflicts as possible.

Updated: ditched local execution; everything is now handled in separate worktrees/web vms (for web claude/cursor cloud agents/etc.)