Skip to content

Commit e5a3222

Browse files
AdaWorldAPIAdaWorldAPI
authored
Merge pull request #260 from AdaWorldAPI/claude/agent-log-split-gitignore
refactor: gitignore AGENT_LOG.md, split governance to AGENT_COORDINATION.md
2 parents b21c037 + a2295a9 commit e5a3222

4 files changed

Lines changed: 180 additions & 300 deletions

File tree

‎.claude/AGENT_COORDINATION.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Agent Coordination — Architectural Governance
2+
3+
> **Committed governance doc.** Read-through, not append-to. Describes HOW
4+
> agents coordinate in this workspace. The per-session activity log that
5+
> was briefly in `.claude/board/AGENT_LOG.md` is now **gitignored** (local
6+
> blackboard, ephemeral by design) because agent-by-agent appends kept
7+
> producing merge conflicts between parallel branches.
8+
>
9+
> The durable record of what agents did lives in:
10+
> - **Git log** — commit messages on each agent's branch
11+
> - **PR descriptions** — what the agent shipped, tests, verdict
12+
> - **EPIPHANIES.md** — findings that outlive a single PR
13+
> - **`.claude/board/CROSS_SESSION_BROADCAST.md`** — intentional cross-session messages (committed, rare)
14+
15+
---
16+
17+
## Three Coordination Layers
18+
19+
All three use the **same structured-entry format**. Only the transport differs.
20+
21+
### Layer A — Teleportation (in-context role switch)
22+
23+
**Transport:** None (same context window).
24+
**Latency:** Instant. **Context loss:** Zero.
25+
26+
The model loads an agent card (`.claude/agents/*.md`), adopts its role
27+
and knowledge, does the work, and switches back. No process boundary,
28+
no serialization. The 19 specialist + 5 meta-agent cards in this
29+
workspace are **teleportation roles**, not delegation targets. The
30+
agent IS the main thread wearing a different hat.
31+
32+
```
33+
[main thread] → load @family-codec-smith card → do codec work
34+
→ load @truth-architect card → review with full context
35+
→ back to main thread (nothing lost)
36+
```
37+
38+
### Layer B — Per-session file blackboard (in-session, between agents)
39+
40+
**Transport:** Local filesystem (`.claude/board/AGENT_LOG.md`, gitignored).
41+
**Latency:** Instant. **Context loss:** File-level.
42+
43+
Agents spawned via `Agent()` in the SAME session share a working tree.
44+
They can read each other's AGENT_LOG.md entries to see what's been done,
45+
same as Layer-1 experts reading prior `BlackboardEntry` rounds.
46+
47+
**Critical:** AGENT_LOG.md is **gitignored**. It does NOT travel between
48+
sessions or branches. It's pure local blackboard state. Each new session
49+
starts with an empty log.
50+
51+
Why gitignored: every branch that ended up with appended entries from
52+
parallel agents generated merge conflicts when its PR rebased against
53+
other merged PRs. The durable record was already preserved in git log
54+
+ PR description; the log was pure redundant metadata causing friction.
55+
56+
### Layer C — Cross-session broadcast (between sessions)
57+
58+
**Transport:** `.claude/board/CROSS_SESSION_BROADCAST.md` (committed,
59+
append-only but curated) + `git push` + `subscribe_pr_activity` webhook.
60+
61+
**Latency:** Minutes. **Context loss:** Entry-level.
62+
63+
When two sessions genuinely need to talk across the boundary, they:
64+
65+
1. Open a coordination PR (or use an existing long-running one).
66+
2. Subscribe via `mcp__github__subscribe_pr_activity`.
67+
3. Append to `CROSS_SESSION_BROADCAST.md` (curated — small, intentional).
68+
4. Push; the webhook notifies subscribers.
69+
70+
**Do NOT append here carelessly.** Unlike the gitignored AGENT_LOG.md,
71+
every entry here is a durable commit that travels with the repo. Think
72+
of it as a system-wide announcement channel. Most coordination should
73+
stay in Layer A (teleport) or Layer B (local log). Use Layer C only for:
74+
75+
- Findings another session MUST see before starting work
76+
- Architectural decisions that change what future sessions can assume
77+
- Urgent corrections that can't wait for the next PR to merge
78+
79+
Everything else is either Layer B (don't leave the session) or belongs
80+
in `EPIPHANIES.md` as a findings-of-record.
81+
82+
### Summary
83+
84+
| Layer | Scope | Transport | Committed? | Conflict risk |
85+
|---|---|---|---|---|
86+
| **A: Teleport** | In-context | None | N/A | None |
87+
| **B: File** | In-session | `AGENT_LOG.md` | **No (gitignored)** | None |
88+
| **C: Broadcast** | Cross-session | `CROSS_SESSION_BROADCAST.md` | Yes | Low (curated) |
89+
90+
All three share one invariant: **append-only, structured entries,
91+
newest-first.** A `BlackboardEntry` by any other transport.
92+
93+
---
94+
95+
## Canonical Append Pattern
96+
97+
For AGENT_LOG.md (local, gitignored) and CROSS_SESSION_BROADCAST.md
98+
(committed), use the `cat >>` heredoc — no Read required, no overwrite
99+
risk, pre-allowed in `.claude/settings.json`:
100+
101+
```bash
102+
cat >> .claude/board/AGENT_LOG.md <<'EOF'
103+
104+
## YYYY-MM-DDTHH:MM — description (model, branch)
105+
106+
**D-ids:** ...
107+
**Commit:** `abc1234`
108+
**Tests:** N pass (M new)
109+
**Outcome:** One-line summary.
110+
EOF
111+
```
112+
113+
This is the ONLY sanctioned write pattern for both logs. Do not use
114+
`Edit` or `Write` tools on them — they risk overwriting prior entries.
115+
`cat >>` is append-only by construction.
116+
117+
---
118+
119+
## Durable Record (not ephemeral blackboard)
120+
121+
For findings, architectural changes, and PR outcomes that need to survive
122+
beyond the session:
123+
124+
| What | Where | Format |
125+
|---|---|---|
126+
| Multi-source insight / "aha" / correction | `.claude/board/EPIPHANIES.md` | PREPEND dated entry |
127+
| Tech-debt observation | `.claude/board/TECH_DEBT.md` | PREPEND |
128+
| Unresolved blocker | `.claude/board/ISSUES.md` | PREPEND |
129+
| Contract type added | `.claude/board/LATEST_STATE.md` | Edit inventory |
130+
| Merged PR | PR description + git log | Automatic |
131+
| New D-id / deliverable | `.claude/board/STATUS_BOARD.md` | Row entry |
132+
| Plan version | `.claude/plans/<name>-v<N>.md` + `INTEGRATION_PLANS.md` PREPEND | New file |
133+
134+
Do NOT put findings in AGENT_LOG.md — it's local-only and will be lost
135+
when the session ends. Findings go in EPIPHANIES.md.
136+
137+
---
138+
139+
## The Rule of Thumb
140+
141+
> "Would a future session need to read this?"
142+
>
143+
> **Yes** → EPIPHANIES.md / LATEST_STATE.md / CROSS_SESSION_BROADCAST.md (committed)
144+
>
145+
> **No, just this session** → AGENT_LOG.md (gitignored)
146+
>
147+
> **Automatic from git** → nothing to write — commit messages and PR
148+
> descriptions already capture it
149+
150+
This is the split that was forced by three merge conflicts in one
151+
session (2026-04-24): the architectural governance survives, the
152+
ephemeral per-run log doesn't.

0 commit comments

Comments
 (0)