docs(reports): archive markdown audit & cleanup plan and unanimous peer review reports
This commit is contained in:
Godopu committed
1 parent
cfa15eadee
commit
4d11308497
4 files changed
+362
No files matched your search
@@ -0,0 +1,208 @@
|
||||
# 📋 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:
|
||||
```bash
|
||||
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.:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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](.agents/MULTI_AGENT_RULES.md) ... first before working"*) and `BOOTSTRAP.md:193` (*"onboarding agents should immediately read the **[MULTI_AGENT_RULES.md](.agents/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.` (drop `cline`, 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:
|
||||
```bash
|
||||
.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
Block a user