Commit 620513c3 authored by Vacaliuc, Bogdan's avatar Vacaliuc, Bogdan
Browse files

plan: add communication-paths.md + cross-reference from §6 and role prompts 



Per reviewer request: a single source of truth for how the four
roles (Analyst, Developer, Integrator, Administrator) communicate,
covering both channels (git refs cross-machine; local filesystem
per-machine), per-ref/per-file writers and readers with lifecycles,
the concurrency model (no concurrent same-file writes by
construction; atomic state-file writes via tmp+rename; git's
regular-merge recovery for the one multi-writer ref), and
multi-machine semantics.

Eight sections in the new doc:

§1 The two channels (table contrasting git vs local filesystem).
§2 Roles, sessions, and clones (per-machine and per-effort counts).
§3 Channel A — Git repository: ref-by-ref table (analysis, triage,
   feature, qa, review, escalate, init-check), discussion of the
   one multi-writer ref (analysis), discovery vs fetch, the four
   poll-wrapper event grammars.
§4 Channel B — Local filesystem: file-by-file table, atomicity of
   state-file writes (tmp+rename), single-writer-per-file
   invariant proven file-by-file, statusline render path,
   Stop-hook restore path.
§5 Worker → Administrator visibility (state-file read + ls-remote;
   what a missing state file means; what Administrator does NOT do).
§6 Multi-machine semantics (single-writer-per-role across machines;
   multiple Administrators OK because Phase 2 is read-only;
   multi-clone single-machine layout).
§7 End-state contract (cross-reference to orchestration.md §3 / §8).
§8 Cross-references to every other plan doc and the parent CLAUDE.md.

Cross-references added:
- orchestration.md §6 preamble points readers at communication-paths.md.
- All four role prompts (Analyst/Developer/Integrator/Administrator)
  add communication-paths.md to their "Read these in order" preamble.

Co-Authored-By: default avatarClaude Opus 4.7 (1M context) <noreply@anthropic.com>
parent 6061a710

plan/Administrator-prompt.md

+8 −3
Original line number Diff line number Diff line
@@ -52,9 +52,14 @@ Read these in order before acting: 
  4. {tasking-prefix}/plan/orchestration-v2-redesign.md

     — design rationale (especially §4.1 state-file schema, §4.2

       statusline command, §5 Administrator spec, §10.4 Stop hook,

       §15.2 verification block)

  5. {tasking-prefix}/../CLAUDE.md

  6. ~/.claude/CLAUDE.md (especially [ALWAYS] sections)

       §15.2 verification block, §17 v2.1/v2.2 walk-back)

  5. {tasking-prefix}/plan/communication-paths.md

     — single source of truth for inter-agent communication;

       in particular §5 (Worker → Administrator visibility),

       §6 (multi-machine semantics — when you may run alongside a

       peer Administrator on another machine)

  6. {tasking-prefix}/../CLAUDE.md

  7. ~/.claude/CLAUDE.md (especially [ALWAYS] sections)



Session setup (run before starting phase 1) — see orchestration.md §9.7:

  1. Verify {admin-state-dir} exists with mode 700:

plan/Analyst-prompt.md

+6 −2
Original line number Diff line number Diff line
@@ -47,8 +47,12 @@ efforts: 
     — per-issue seeds: symptom, root cause, files, TDD seed, acceptance

  3. {tasking-prefix}/plan/initialization.md

     — what the Administrator (or v1 Initialization) agent verified

  4. {tasking-prefix}/../CLAUDE.md

  5. ~/.claude/CLAUDE.md (especially [ALWAYS] sections)

  4. {tasking-prefix}/plan/communication-paths.md

     — single source of truth for inter-agent communication

       (which refs you write/read, which local files you write/read,

       atomicity guarantees, multi-machine semantics)

  5. {tasking-prefix}/../CLAUDE.md

  6. ~/.claude/CLAUDE.md (especially [ALWAYS] sections)



Session setup (run before starting your poll loop) — see §9.7:

  1. Install agent statusline:

plan/Developer-prompt.md

+6 −2
Original line number Diff line number Diff line
@@ -45,8 +45,12 @@ intentional: your input is the git log, not this orchestration doc. 
       (especially §6 dedup/discovery contracts, §9.7 statusline)

  2. {tasking-prefix}/plan/initialization.md

     — what the Administrator (or v1 Initialization) agent verified

  3. {tasking-prefix}/../CLAUDE.md

  4. ~/.claude/CLAUDE.md (especially [ALWAYS] sections)

  3. {tasking-prefix}/plan/communication-paths.md

     — single source of truth for inter-agent communication

       (which refs you write/read, which local files you write/read,

       atomicity guarantees, multi-machine semantics)

  4. {tasking-prefix}/../CLAUDE.md

  5. ~/.claude/CLAUDE.md (especially [ALWAYS] sections)



Session setup (run before starting your poll loop) — see §9.7:

  1. Install agent statusline:

plan/Integrator-prompt.md

+6 −2
Original line number Diff line number Diff line
@@ -49,8 +49,12 @@ orchestration doc. 
       (especially §6 dedup/discovery contracts, §9.7 statusline)

  2. {tasking-prefix}/plan/initialization.md

     — platform detection and PR/MR creation commands (§7)

  3. {tasking-prefix}/../CLAUDE.md

  4. ~/.claude/CLAUDE.md (especially [ALWAYS] sections)

  3. {tasking-prefix}/plan/communication-paths.md

     — single source of truth for inter-agent communication

       (which refs you write/read, which local files you write/read,

       atomicity guarantees, multi-machine semantics)

  4. {tasking-prefix}/../CLAUDE.md

  5. ~/.claude/CLAUDE.md (especially [ALWAYS] sections)



Session setup (run before starting your poll loop) — see §9.7:

  1. Install agent statusline:

plan/communication-paths.md

0 → 100644
+399 −0

File added.

Preview size limit exceeded, changes collapsed.