tmpl/multi-agent-mux
1
0 Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
26e2c43753169671b600d03274901dbe203988dd
multi-agent-mux/.agents/reports/planner-reviewer-claude-01/plan-e359e7af.md
T

25 KiB
Raw Blame History

📋 Implementation Plan — Project-Wide Markdown Audit & Cleanup (Job e359e7af)

  • Planner: planner-reviewer-claude-01
  • Status: Plan only — no files changed in the repo by this job. Ready for review/handoff to a Creator (or a follow-up Planner job) for execution.
  • Scope: Full inventory of every .md file in the repository, classified into (a) stray/duplicate files to remove, (b) files that need v4.1.3-era content updates, (c) files that are already current and must not be touched. All findings below were derived by reading the actual files, git log, and cross-referencing every candidate deletion against the rest of the codebase — not assumed from the brief's examples.
  • Rev. 2 note: this plan was refined in response to an architectural challenge (creator-agy-01, job 9dcd14f6) that identified a genuine survey blind spot in Rev.1's §1. See the changelog at the very bottom of this document for what changed and why.

1. Survey method

  • find . -name "*.md" across repo root, docs/, deploy/, .agents/skills/, and .agents/ itself (top-level, non-recursive — Rev.1 only listed .agents/skills/ explicitly and this omitted the two repository-charter files sitting directly in .agents/; see Rev.2 changelog) (excluding .agents/reports/ archives, which are immutable per-job history and out of scope — see §5).
  • For every root-level file flagged as possibly stale in the brief, read its content, git log -1 -- <file>, and grep -rl for cross-references from other live docs/skills before proposing deletion.
  • For README/BOOTSTRAP/deploy docs, grepped for opencode|grok|hermes|cline|v4\. to find version/agent-roster gaps.
  • Re-ran pytest tests/test_version_consistency.py at current HEAD to confirm the 3-way lockstep baseline this plan must not disturb: 2 passed.

2. Findings — file deletions (duplicate/stray cleanup)

2.1 mam-agent-creation-fix-report.md (repo root) — DELETE

  • diff mam-agent-creation-fix-report.md bug-report/mam-agent-creation-fix-report.md → byte-identical.
  • The properly-namespaced copy already lives at bug-report/mam-agent-creation-fix-report.md (added in commit ccdde63, "docs(bug-report): add upstream bug fix report artifact"), alongside its sibling bug-report/mam_upstream_bug_fix_report.md.
  • Historical archived reports (.agents/reports/reviewer-opencode-01/report-89fd2305.md, .agents/reports/creator-agy-01/report-final-v4.1.1.md, .agents/reports/planner-reviewer-claude-01/plan-c38ddfcf.md) cite this filename as a "field report... at root of repo" — those citations describe the historical state at the time they were written and remain valid as history regardless of where the file physically sits today (git history retains the original root copy for anyone tracing those citations).
  • Action: git rm mam-agent-creation-fix-report.md (root copy only). Keep bug-report/mam-agent-creation-fix-report.md untouched.

2.2 implementation_plan.md (repo root) — KEEP, do not delete or merge

Initially flagged by the brief as a possible duplicate/temp file alongside the root fix-report. Verified this is not stale:

  • It is the live execution roadmap for the O-5 / A-2 messaging-backplane migration (HiveMQ → private nats-server), which IMPROVEMENTS.md still lists as an open, actively-tracked backlog item (O-5, Track 1, "차순위 P2 — 브로커 스파이크 검증").
  • nats-docker/ (the submodule this plan tracks) exists on disk and is referenced from nats-docker/PRIVATE_SERVER.md, which itself links back to implementation_plan.md.
  • .agents/skills/multi-agent-mux-loop/SKILL.md:72,148 documents implementation_plan.md as the standard, conventional artifact name every Planner is instructed to create/maintain per project — it is not a one-off stray file, it's the load-bearing convention filename.
  • Note: .agents/reports/implementation_plan.md (an unrelated, already-completed OpenCode-adapter plan, archived under a Planner's report namespace) shares the same basename but is a completely different document in a completely different directory. This is a harmless naming coincidence — no action needed, do not conflate the two or attempt to "de-duplicate" them.
  • Action: none. Leave implementation_plan.md exactly as-is.

2.3 IMPROVEMENTS.md, MESSAGING.md, AGENTS.md (repo root) — KEEP

  • IMPROVEMENTS.md: live backlog tracker (5 open items: A-2, B-16–B-18, O-5), last touched 2026-08-24, directly cross-referenced by implementation_plan.md and .mam.env-adjacent docs. Its historical cline mentions (lines 34, 110-111) are changelog/history entries describing a past state ("이전에 cline이 존재했을 때..."), not current-state claims — correctly left as-is per standard changelog append-only practice (same treatment VERSIONS.md's v3.x/MAJOR-release history section already receives, and which was explicitly endorsed as correct in this session's prior review of VERSIONS.md).
  • MESSAGING.md: companion technical-analysis doc for the same O-5/A-2 track, linked from implementation_plan.md's header. Live.
  • AGENTS.md: generic LLM behavioral-guidelines doc, version-agnostic, no agent-roster or MAM-version content to go stale. Live.
  • Action: none.

2.4 bug-report/ directory — KEEP as-is

Both files (mam_upstream_bug_fix_report.md, mam-agent-creation-fix-report.md) are dated 2026-08-30, properly namespaced, and not duplicated elsewhere except the root stray copy handled in §2.1. No action beyond that deletion.

3. Findings — content updates needed (v4.1.3 / current-architecture sync)

3.1 README.md / README.ko.md — out of date, needs update

  • Grepped for opencode|grok in both files: zero matches in either file. The docs describe the framework as if only claude/agy/hermes exist (README.md:43 mentions only claude -r <uuid> / hermes --resume <uuid> as examples) and never mention:
    • The 5-agent roster (claude, agy, hermes, grok, opencode).
    • The Herdr daemon process-group isolation feature shipped in v4.1.3 (start_new_session=True detachment — see VERSIONS.md's current-release summary).
    • Any version string at all (no v4.1.x mention anywhere in either file).
  • Concrete edits:
    1. Wherever the docs enumerate supported agents (README.md's architecture/feature-list sections), extend claude/agy/hermes → claude, agy, hermes, grok, opencode (5 agents), matching docs/NEW_AGENT_INTEGRATION_GUIDE.md's registry.
    2. Add one sentence to the feature/architecture section noting Herdr daemon isolation (background server processes spawn in their own OS session/process-group via start_new_session=True, so they survive process-group signal delivery to the parent shell — this is the actual v4.1.3 content, phrase it in README's existing voice/register rather than copy-pasting VERSIONS.md's changelog prose verbatim).
    3. Add a version badge/line (e.g. near the top, alongside the existing tagline) citing v4.1.3, sourced from VERSIONS.md's current-release header — do not hardcode a version number that would need to be manually bumped every release; either reference VERSIONS.md directly or use a badge mechanism, so this doesn't become a 9th lockstep touchpoint that regresses at the next PATCH/MINOR bump.
    4. Apply the identical set of edits to README.ko.md (Korean mirror) — keep both language versions in sync, same content, same structure.

3.2 BOOTSTRAP.md / BOOTSTRAP.ko.md — out of date, needs update

  • Same gap: zero opencode/grok mentions, no version reference, in either file.
  • Concrete edits: same shape as §3.1 — extend the agent roster wherever BOOTSTRAP.md walks through onboarding/setup steps that name specific agents, and add the same lightweight version reference. Keep BOOTSTRAP.ko.md in lockstep with BOOTSTRAP.md.
  • Rev. 2 addition — §1 "Scaffolding Overview" skill list is incomplete: verified directly (sed -n '15,30p' BOOTSTRAP.md / BOOTSTRAP.ko.md) that the skills/ bullet list under the scaffolding-overview section names only 6 of the 8 lockstep-tracked skills — multi-agent-mux-create, -stop, -resume, -status, -monitor, -delegate-job. multi-agent-mux-loop and multi-agent-mux-orc-onboard are both missing from this list in both language files, even though both are shipped, version-locked skills (grep -n "^version:" .agents/skills/*/SKILL.md confirms both carry version: 4.1.3 same as the other 6). Add two bullets for them, matching the existing bullet style/format (one-line description each, e.g. multi-agent-mux-loop/: recurring/self-paced prompt execution on an interval; multi-agent-mux-orc-onboard/: orchestrator onboarding/handshake helper — confirm exact wording against each skill's own SKILL.md description: frontmatter rather than paraphrasing from memory). Apply to both BOOTSTRAP.md and BOOTSTRAP.ko.md, same position (end of the skills/ sub-list), keeping the two files in parity.
  • Note: BOOTSTRAP.md:57's "Legacy Config Migration" note (.env → .mam.env) is accurate and unrelated to the agent-roster/version gap — leave it untouched.

3.3 deploy/INSTALL.md — minor update

  • Line 3 already says "복수의 에이전트(Claude, Agy, Hermes, Grok 등)들이..." — the trailing 등 ("etc.") technically covers opencode, but since opencode is a fully first-class 5th agent (not a minor/edge one), it should be named explicitly for clarity, matching how grok already earned an explicit mention.
  • Concrete edit: line 3 → "...(Claude, Agy, Hermes, Grok, OpenCode 등)...". One-word addition, no structural change.
  • No cline references found in this file (grep -n "cline" deploy/INSTALL.md → empty) — the brief's "삭제된 cline 언급 정리" concern does not apply here; already clean.

3.4 deploy/README.md — no change needed

  • Contains no agent-specific roster claims (it describes the deployment tooling — install.sh, update.sh, etc. — not the agent backends). No cline references. No action.

3.5 docs/NEW_AGENT_INTEGRATION_GUIDE.md, docs/OPENCODE_OLLAMA_GUIDE.md — no change needed

  • Both already reflect the current 5-agent architecture (NEW_AGENT_INTEGRATION_GUIDE.md's worked example is literally "how grok was added," and its assertion set/registry checks already list {claude, agy, hermes, grok} plus the guide text explicitly frames opencode as one of the example agents a reader might add next). No cline references in either. No action.

3.6 docs/MAM_WEB_PTY_BRIDGE_PLAN.md — no change needed

  • Independent, still-forward-looking architecture plan for a browser PTY bridge; not agent-roster or version-coupled. No action.

3.7 .agents/skills/multi-agent-mux-resume/SKILL.md:71-75 — known, already-specified fix

This was already identified as a non-blocking finding in the prior post-commit review (job 4d3c2c1c, report-final.md §2) and is now in-scope for this cleanup pass:

  • Current (inaccurate) text, inside the illustrative "Workflow" bash snippet: 
    if [ -z "$UUID" ]; then
  # For Class A, resume_session.sh handles fresh-spawn fallback automatically.
  echo "No saved session for $WORKSPACE ($AGENT). Class B agents must use multi-agent-mux-create first."
  exit 1
fi
    The echo text does not match the real, unchanged resume_session.sh:67 error string ("ERROR: No saved session for $WORKSPACE ($AGENT). Use multi-agent-mux-create first." — no "Class B agents must" phrase; the real script also never reaches this echo for Class A agents at all, since resume_session.sh branches internally on agent class before this point).
  • Fix: replace the flat illustrative echo with a version that actually mirrors the real script's branch, e.g.: 
    if [ -z "$UUID" ]; then
  case "$AGENT" in
    agy|hermes|opencode)
      : # resume_session.sh handles fresh-spawn fallback automatically (FRESH_SPAWN=1)
      ;;
    *)
      echo "ERROR: No saved session for $WORKSPACE ($AGENT). Use multi-agent-mux-create first." >&2
      exit 1
      ;;
  esac
fi
    This mirrors the real resume_session.sh branch structure (case-per-agent-class) instead of a single flat message, and uses the byte-exact real error string. It also closes the pre-existing gap noted in the prior review — the Workflow snippet's two further case "$AGENT" in ... blocks have never had an opencode arm even though opencode is fully supported; while not strictly this line-range's job, if this file is being touched anyway the executing agent should add the missing opencode) case arms in the same pass.
  • Rev. 2 — verified exact fix for the two downstream case blocks (raised by creator-agy-01's challenge, job 9dcd14f6; independently re-verified against the live adapter source before accepting, not taken on the challenge's word alone):
    • Line 88-93 (the CMD_FULL determination block) is currently: 
      case "$AGENT" in
  claude) CMD_FULL="claude --dangerously-skip-permissions $CLAUDE_ID_FLAG $UUID" ;;
  agy)    CMD_FULL="agy --dangerously-skip-permissions --conversation $UUID" ;;
  hermes) CMD_FULL="hermes --resume $UUID --no-restore-cwd --yolo --accept-hooks" ;;
  grok)   CMD_FULL="grok --resume $UUID --permission-mode bypassPermissions" ;;
esac
      Add one more arm: opencode) CMD_FULL="opencode --session $UUID --auto --agent build" ;;. This exact string is not a guess — it was checked directly against .agents/skills/lib_py/agents/adapters/opencode.py:188-191's resume_spec(): f"{binary} --session {session_uuid} --auto --agent build" when materialized and session_uuid (the case this illustrative snippet is modeling — an already-saved UUID). The proposed text is byte-for-byte what that method returns.
    • Line 96-106 (the spawn-dispatch block) currently ends its non-claude branch with agy|hermes|grok) (line 103). Since opencode, like agy/hermes/grok, needs no claude-specific TUI dialog handling, it belongs in the same branch — change line 103 to agy|hermes|grok|opencode). No new branch needed, just widening the existing pattern-match arm.
  • Line 55 (prose) is already correct and must not be touched.

3.8 .agents/MULTI_AGENT_RULES.md / .agents/MULTI_AGENT_RULES.ko.md — out of date, needs update (Rev. 2 addition)

Raised by creator-agy-01's architectural challenge (job 9dcd14f6) as a genuine survey scope blind spot: Rev.1's §1 survey method named .agents/skills/ explicitly but never listed the .agents/ top-level directory itself, so these two repository-charter files — which sit directly in .agents/, not under .agents/skills/ — were never enumerated by the original audit. Independently re-verified before accepting into this plan (not taken on the challenge's word alone):

  • .agents/MULTI_AGENT_RULES.md:21 (confirmed via direct read): "Newly spawned agents (e.g., antigravity, claude, cline, hermes) act as Team Leaders of their respective groups." — still lists the fully-removed cline agent (deprecated/removed at the v4.0.0 MAJOR release per VERSIONS.md's history section) and omits both grok and opencode, the two agents added since.
  • .agents/MULTI_AGENT_RULES.ko.md:21 (confirmed via direct read): the Korean mirror has the identical gap — "새롭게 생성되는 에이전트(antigravity, claude, cline, hermes 등)는 각 팀의 팀장 역할을 수행합니다."
  • Why this is high-impact, not cosmetic: this file is the mandatory onboarding read for every newly spawned agent. Confirmed two independent live cross-references instructing agents to read it first: AGENTS.md:70 ("Read MULTI_AGENT_RULES.md ... first before working") and BOOTSTRAP.md:193 ("onboarding agents should immediately read the MULTI_AGENT_RULES.md guidelines"). A grok or opencode agent onboarding today reads a charter that doesn't list its own agent name among the Team Leader roster and still lists a deleted one — a real, user-facing inconsistency that fits squarely inside "Project-Wide Markdown Audit."
  • Concrete edits:
    • MULTI_AGENT_RULES.md:21: Newly spawned agents (e.g., \antigravity`, `claude`, `hermes`, `grok`, `opencode`) act as Team Leaders of their respective groups.(dropcline, add grok/opencode` — 5-agent roster, same ordering convention as the rest of this audit).
    • MULTI_AGENT_RULES.ko.md:21: 새롭게 생성되는 에이전트(\antigravity`, `claude`, `hermes`, `grok`, `opencode` 등)는 각 팀의 팀장 역할을 수행합니다.`
    • Scope is deliberately narrow to line 21 (the one sentence enumerating the agent roster) — do not sweep the rest of either file for other possible staleness in this pass; if a broader read turns up more, flag it as a new finding rather than silently expanding this edit's blast radius.

4. Version lockstep — must remain untouched and green

This is a documentation-content-only pass. None of the three lockstep touchpoints are in scope for edits:

  • .agents/skills/lib.sh:32 (MAM_VERSION="4.1.3") — no change.
  • VERSIONS.md current-release header / skill matrix — no change (already correctly at v4.1.3; this job is about other docs catching up to what VERSIONS.md already states, not about VERSIONS.md itself).
  • All 8 SKILL.md version: frontmatter fields — no change (all already 4.1.3, confirmed via grep -n "^version:" .agents/skills/*/SKILL.md).

Regression guard for the executing Creator/Planner: after making the §3 edits, re-run:

.venv/bin/python -m pytest tests/test_version_consistency.py -v
.venv/bin/python -m pytest tests/ -q   # full suite — doc-only changes should not affect any test, but confirm

Both must stay green. If any editor tool accidentally touches a version: line or MAM_VERSION= while doing a find-and-replace across .agents/skills/, the lockstep test will catch it immediately — treat any failure here as a hard blocker, not a doc nit.

5. Explicitly out of scope (do not touch)

  • .agents/reports/**/*.md — immutable per-job archival history (plans, reports, peer-review verdicts). Contains many historical cline references and two implementation_plan.md-named files; these are frozen historical records, not living docs, and must never be edited/pruned by a "cleanup" pass.
  • VERSIONS.md's historical changelog sections (pre-v4.1.3 entries, including the MAJOR cline-removal entry) — changelog history is append-only by convention; do not edit past entries.
  • nats-docker/ submodule contents — separate submodule, not this repo's direct concern.
  • IMPROVEMENTS.md's backlog freshness (open items, "최종 갱신일" date) — a full backlog refresh is a distinct piece of work from a markdown audit/cleanup, and is not called for by the brief's checklist. Flagging only as a possible future follow-up, not part of this job's deliverable.

6. Recommended execution order (for the Creator who implements this plan)

  1. git rm mam-agent-creation-fix-report.md (§2.1) — single-file deletion, zero content risk, do first.
  2. .agents/MULTI_AGENT_RULES.md:21 + .agents/MULTI_AGENT_RULES.ko.md:21 fix (§3.8, Rev. 2) — single-line-per-file, well-specified, isolated. Do early since it's the highest-impact item (mandatory onboarding read) and carries the least edit risk.
  3. .agents/skills/multi-agent-mux-resume/SKILL.md:71-75, 88-93, 103 fix (§3.7, including the Rev. 2 opencode case arms) — small, well-specified, isolated.
  4. deploy/INSTALL.md:3 one-word edit (§3.3).
  5. README.md + README.ko.md sync (§3.1) — do both languages in the same commit so they never drift out of parity.
  6. BOOTSTRAP.md + BOOTSTRAP.ko.md sync (§3.2, including the Rev. 2 8-skill scaffolding-list fix) — same pairing discipline.
  7. Run the regression guard in §4.
  8. Hand to Reviewers (Claude/Grok/OpenCode) for cross-review against this plan's checklist — reviewers should verify each §2/§3 item was actually applied (or correctly left alone) and that §5's out-of-scope files were not touched (git diff --stat should show no changes under .agents/reports/, VERSIONS.md, nats-docker/, or any SKILL.md version: line).

7. Acceptance checklist (for reviewers)

  • mam-agent-creation-fix-report.md removed from repo root; bug-report/ copy intact and unchanged.
  • implementation_plan.md, IMPROVEMENTS.md, MESSAGING.md, AGENTS.md unchanged (byte-identical to pre-job state).
  • README.md/README.ko.md now mention all 5 agents (claude, agy, hermes, grok, opencode) and reference v4.1.3 / Herdr daemon isolation, with both language files in parity.
  • BOOTSTRAP.md/BOOTSTRAP.ko.md same treatment, in parity, and the §1 scaffolding-overview skill list names all 8 skills (create, stop, resume, status, monitor, delegate-job, loop, orc-onboard) — not just 6.
  • deploy/INSTALL.md:3 names opencode explicitly.
  • multi-agent-mux-resume/SKILL.md:71-75 echo text matches the real resume_session.sh error string byte-for-byte, and the flat if-block is replaced with a class-aware case; and lines 88-93/103 have the opencode case arms added (opencode) CMD_FULL="opencode --session $UUID --auto --agent build" ;; and agy|hermes|grok|opencode) respectively) — text verified against adapters/opencode.py, not guessed.
  • .agents/MULTI_AGENT_RULES.md:21 and .agents/MULTI_AGENT_RULES.ko.md:21 updated to the 5-agent roster (cline removed, grok/opencode added) — scope confined to that one line/sentence in each file.
  • lib.sh:32, VERSIONS.md header/matrix, and all 8 SKILL.md version: fields are byte-identical to pre-job state (no accidental touch).
  • pytest tests/test_version_consistency.py and the full suite both 100% pass post-change.
  • No file under .agents/reports/ was modified.

Rev. 2 — Refinement in response to creator-agy-01's architectural challenge (job 9dcd14f6)

What changed and why: creator-agy-01 filed a formal challenge against Rev.1 of this plan, identifying that the §1 survey method named .agents/skills/ but never the .agents/ top-level directory, causing two repository-charter files (.agents/MULTI_AGENT_RULES.md, .agents/MULTI_AGENT_RULES.ko.md) to be skipped entirely by the original audit — both still list the removed cline agent and omit grok/opencode. The challenge also flagged two secondary gaps: BOOTSTRAP.md/.ko.md's scaffolding-overview skill list only names 6 of the 8 lockstep-tracked skills, and the resume SKILL.md fix in §3.7 stopped at lines 71-75 without extending to the two further case "$AGENT" in ... blocks (lines 88-93, 103) that also lack an opencode arm.

Every claim in the challenge was independently re-verified against the live files before being accepted into this plan (not taken on the challenge author's word):

  • Read .agents/MULTI_AGENT_RULES.md:21 and .agents/MULTI_AGENT_RULES.ko.md:21 directly — confirmed the cline-listed / grok+opencode-missing roster exactly as the challenge described.
  • Confirmed the two onboarding cross-references (AGENTS.md:70, BOOTSTRAP.md:193) that make this file mandatory-read, establishing the "high impact" claim is not overstated.
  • Read BOOTSTRAP.md/.ko.md lines 15-30 directly — confirmed only 6 of 8 skills are listed, and confirmed both multi-agent-mux-loop and multi-agent-mux-orc-onboard carry version: 4.1.3 frontmatter same as the other 6 (i.e. they are not somehow lesser/unshipped skills that would legitimately be excluded).
  • Read .agents/skills/multi-agent-mux-resume/SKILL.md lines 86-107 directly and cross-checked the challenge's proposed opencode) CMD_FULL="opencode --session $UUID --auto --agent build" ;; text against .agents/skills/lib_py/agents/adapters/opencode.py:188-191's actual resume_spec() implementation — confirmed byte-for-byte match. This is a case where the challenge's proposed fix text was verified correct and adopted verbatim rather than merely triggering a "go look into it" pointer, since it had already done the adapter-source verification plan-e359e7af.md Rev.1 explicitly required ("verify the actual CLI flag name... before writing it — do not guess the flag") — no reason to redo work that was already done correctly and can be independently confirmed.

Net result: added new §3.8 (MULTI_AGENT_RULES.md/.ko.md), extended §3.2 (BOOTSTRAP 8-skill list) and §3.7 (resume SKILL.md opencode case arms with verified exact text), corrected §1's survey-method description to name .agents/ explicitly, and updated §6/§7 to reflect the added scope. No part of Rev.1's original findings (§2 deletions, §3.1/3.3-3.6 content updates, §4/§5 lockstep and out-of-scope guards) were found to be wrong by this challenge — all three challenge items were additive scope-completeness findings, not corrections of an error in what was already there.

Reference in new issue View Git Blame Copy Permalink