manual_slop/docs/superpowers/plans/2026-06-02-agent-config-refresh.md

# Agent Config Refresh Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Apply the explicit divergence model to `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md`. `AGENTS.md` becomes a thin pointer document (~1K). `CLAUDE.md` becomes a 1-line deprecation stub. `GEMINI.md` is lightly refreshed to remove any content that should have moved to `AGENTS.md`. Light verification pass (not rewrites) on the skill files in `.agents/`, `.gemini/`, and the legacy `.claude/commands/`.

**Architecture:** Single-agent sequential execution. Each top-level file is its own task. Skill file verification is a separate task that touches many files but only makes surgical edits where drift is found.

**Tech Stack:** Manual Slop's MCP research tools. Git for version control.

**Spec:** `docs/superpowers/specs/2026-06-02-comprehensive-documentation-refresh-design.md` §6 (Sub-Track 3).

**Depends on:** Sub-Track 1 (`docs_layer_refresh_20260602`) must complete first. The human-facing docs are the source of truth that the agent config files point to.

---

## Execution Constraints

These apply to every task in this plan:

- **No subagents.** Execute as a single agent.
- **Pre-edit checkpoint:** Before any file edit, run `git add .`.
- **Per-file atomic commits:** One file = one commit. The skill file verification task may have many commits (one per file) since there are many files, but each is still atomic.
- **Commit message format:** `docs(<scope>): <imperative description>`.
- **Git note format:** Attach a 3-8 line rationale to each commit.
- **The "no content duplication" rule:** After this plan completes, a section header that appears in 2+ of `AGENTS.md`/`CLAUDE.md`/`GEMINI.md` must be either (a) a short pointer (≤3 lines) to the canonical home, or (b) a violation to fix.

---

## Task 1: Rewrite `AGENTS.md` to a Thin Pointer

**Files:**
- Modify: `AGENTS.md` (current size ~5.4K)

**Target structure:** A thin orientation document of ~1K that:
- Describes what Manual Slop is (1-2 sentences)
- States the conductor convention (1 paragraph)
- Lists the canonical locations for agent guidance (with file links)
- Lists the 5-6 most critical project-wide anti-patterns
- Points to `docs/Readme.md` for human-facing docs

**Specific target content (use as a starting template, adapt to current state):**

```markdown
# AGENTS.md

## What This Is

Manual Slop is a local GUI orchestrator for LLM-driven coding sessions. It bridges high-latency AI reasoning with a low-latency ImGui render loop via a thread-safe async pipeline; every AI-generated payload passes through a human-auditable gate before execution.

## The Conductor Convention

All AI agents consuming this project must read `./conductor/workflow.md` and treat `./conductor/tracks.md` as the task registry. Track implementation follows the TDD protocol documented in `conductor/workflow.md` with per-file atomic commits and git notes.

## Guidance for AI Agents

Detailed agent guidance lives in the following locations — read these directly, do not duplicate content here:

- **Operational workflow:** `conductor/workflow.md`
- **Code style and process:** `conductor/product-guidelines.md`
- **Tech stack and constraints:** `conductor/tech-stack.md`
- **Product context:** `conductor/product.md`
- **MMA orchestrator role:** `mma-orchestrator/SKILL.md`
- **Tier 1 (Orchestrator):** `.agents/skills/mma-tier1-orchestrator/SKILL.md`
- **Tier 2 (Tech Lead):** `.agents/skills/mma-tier2-tech-lead/SKILL.md`
- **Tier 3 (Worker):** `.agents/skills/mma-tier3-worker/SKILL.md`
- **Tier 4 (QA):** `.agents/skills/mma-tier4-qa/SKILL.md`

## Human-Facing Documentation

For understanding, using, and maintaining the tool, see `docs/Readme.md` and the guides it indexes.

## Critical Anti-Patterns

- Do not read full files >50 lines without first using `py_get_skeleton` or `get_file_summary`
- Do not modify the tech stack without updating `conductor/tech-stack.md` first
- Do not implement code directly as Tier 2 — delegate to Tier 3 workers (or in the case of this docs track, do it yourself as a single agent)
- Do not skip TDD — write failing tests before implementation
- Do not batch commits — commit per-task for atomic rollback
- Do not add comments to source code; documentation lives in `/docs`
```

- [ ] **Step 1.1: Pre-edit checkpoint**

```powershell
git -C C:\projects\manual_slop add .
```

- [ ] **Step 1.2: Read the current `AGENTS.md`**

Use `manual-slop_read_file` (the file is small enough to read in full).

- [ ] **Step 1.3: Inventory what content currently lives in `AGENTS.md`**

For each major section in the current file, note:
- **Keep here:** Project-level orientation, anti-patterns, the conductor convention
- **Move to `conductor/workflow.md`:** Workflow details
- **Move to `conductor/product-guidelines.md`:** Style rules
- **Move to `conductor/tech-stack.md`:** Tech stack details
- **Move to `conductor/product.md`:** Feature descriptions
- **Move to `mma-orchestrator/SKILL.md`:** MMA role details
- **Move to the relevant `.agents/skills/*/SKILL.md`:** Tier-specific guidance
- **Move to `docs/Readme.md`:** Anything that documents the tool for humans (not agents)

- [ ] **Step 1.4: Verify the target skill files exist and have the content**

Before writing `AGENTS.md`, confirm:
- `mma-orchestrator/SKILL.md` exists
- `.agents/skills/mma-tier1-orchestrator/SKILL.md` exists
- `.agents/skills/mma-tier2-tech-lead/SKILL.md` exists
- `.agents/skills/mma-tier3-worker/SKILL.md` exists
- `.agents/skills/mma-tier4-qa/SKILL.md` exists
- `conductor/workflow.md` exists
- `conductor/product-guidelines.md` exists
- `conductor/tech-stack.md` exists
- `conductor/product.md` exists
- `docs/Readme.md` exists (and is updated per Sub-Track 1)

If any are missing, do NOT write `AGENTS.md` until they exist. (They should exist by the time Sub-Track 3 runs, since Sub-Track 1 has completed.)

- [ ] **Step 1.5: Write the new `AGENTS.md`**

Use the target structure above as a starting template. Adapt the language to match the project's style. Keep the file under 1.5K.

- [ ] **Step 1.6: Validate all cross-doc links in the new file**

For every `[text](./relative/path)` or file mention:
- Use `manual-slop_search_files` to confirm the target exists
- If broken, fix the link or remove the mention

- [ ] **Step 1.7: Confirm size is reasonable**

```powershell
(Get-Item C:\projects\manual_slop\AGENTS.md).Length
```

Should be ≤ 1500 bytes. If larger, trim.

- [ ] **Step 1.8: Commit**

```powershell
git -C C:\projects\manual_slop add AGENTS.md
git -C C:\projects\manual_slop commit -m "docs(agents): rewrite as thin pointer document; defer to skill files and conductor docs"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Reduced from [N]K to ~1K. Content relocated to: [list canonical homes]. Anti-patterns compressed to 6 most critical." $_ }
```

---

## Task 2: Replace `CLAUDE.md` with a 1-Line Stub

**Files:**
- Modify: `CLAUDE.md` (current size ~6.7K)

**Target content:** A 1-line deprecation stub that preserves the file's existence for any external tooling that may reference it.

- [ ] **Step 2.1: Pre-edit checkpoint**

```powershell
git -C C:\projects\manual_slop add .
```

- [ ] **Step 2.2: Read the current `CLAUDE.md`**

- [ ] **Step 2.3: Verify no external scripts reference the CLAUDE.md content**

Use `manual-slop_py_find_usages` to grep for any code that reads CLAUDE.md's specific sections. If anything does, the stub approach still works (the script will get a 1-line file instead of the rich content, but it's a graceful failure).

If critical tooling depends on the rich content, flag this to the user before continuing.

- [ ] **Step 2.4: Write the stub**

```markdown
# CLAUDE.md

This project is no longer actively used with Claude Code. For project context, see `AGENTS.md`. The conductor system in `./conductor/` is the cross-tool abstraction and works with any agent toolchain.
```

- [ ] **Step 2.5: Confirm size is small**

```powershell
(Get-Item C:\projects\manual_slop\CLAUDE.md).Length
```

Should be ≤ 500 bytes.

- [ ] **Step 2.6: Commit**

```powershell
git -C C:\projects\manual_slop add CLAUDE.md
git -C C:\projects\manual_slop commit -m "docs(claude): replace with deprecation stub; project no longer uses Claude Code"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Reduced from [N]K to stub. Preserves file existence for any legacy tooling. Project migrated to Gemini CLI + OpenCode." $_ }
```

---

## Task 3: Refresh `GEMINI.md`

**Files:**
- Modify: `GEMINI.md` (current size ~3.8K)
- Reference: `conductor/product.md` (now updated per Sub-Track 2), `conductor/tech-stack.md`, `src/gemini_cli_adapter.py`

**Scope:** This file should contain ONLY Gemini-CLI-specific content. Any content that was previously shared with `AGENTS.md` and has been relocated should now point to `AGENTS.md` instead.

- [ ] **Step 3.1: Pre-edit checkpoint**

```powershell
git -C C:\projects\manual_slop add .
```

- [ ] **Step 3.2: Read the current `GEMINI.md`**

- [ ] **Step 3.3: Identify any content in `GEMINI.md` that is not Gemini-specific**

For each section, ask: "Would this content be useful to an agent that is NOT using Gemini CLI?" If yes, it should be in `AGENTS.md` or a conductor doc, not here.

Likely candidates to move out (or point to canonical home):
- General MMA tier descriptions (should be in `AGENTS.md` or `mma-orchestrator/SKILL.md`)
- General session startup checklist (should be in `AGENTS.md`)
- General anti-patterns (should be in `AGENTS.md` or `conductor/product-guidelines.md`)

Content that should stay (Gemini-CLI-specific):
- Gemini model routing per MMA tier
- `activate_skill` usage for MMA roles
- Gemini CLI bridge architecture (`gemini_cli_adapter.py`, `GEMINI_CLI_HOOK_CONTEXT`, synchronous HITL approval)
- Gemini-specific caching/TTL behavior
- Provider-specific quirks (cache rebuilding at 90% TTL, server-side context cache)
- `gemini-3.1-pro-preview` / `gemini-3-flash-preview` / `gemini-2.5-flash-lite` model names

- [ ] **Step 3.4: Rewrite `GEMINI.md` to contain only Gemini-CLI-specific content**

For each non-Gemini-specific section, replace with a short pointer to the canonical home (e.g., "See `AGENTS.md` for the MMA tier overview. This document covers Gemini-CLI-specific implementation only.").

- [ ] **Step 3.5: Verify Gemini-specific content is accurate**

For each Gemini-specific claim:
- Verify model names match `conductor/tech-stack.md`
- Verify TTL/cache behavior matches `src/ai_client.py` and `src/gemini_cli_adapter.py`
- Verify the bridge architecture description matches the actual code

- [ ] **Step 3.6: Validate all cross-doc links**

- [ ] **Step 3.7: Commit**

```powershell
git -C C:\projects\manual_slop add GEMINI.md
git -C C:\projects\manual_slop commit -m "docs(gemini): refresh and reduce to Gemini-CLI-specific content"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Replaced [N] sections with pointers to AGENTS.md. Kept [list of Gemini-specific sections]." $_ }
```

---

## Task 4: Light Verification of `.agents/skills/*/SKILL.md` and `mma-orchestrator/SKILL.md`

**Files:**
- Read: `mma-orchestrator/SKILL.md` (~9.3K)
- Read: `.agents/skills/mma-tier1-orchestrator/SKILL.md` (~2.4K)
- Read: `.agents/skills/mma-tier2-tech-lead/SKILL.md` (~3.8K)
- Read: `.agents/skills/mma-tier3-worker/SKILL.md`
- Read: `.agents/skills/mma-tier4-qa/SKILL.md` (~813 bytes)
- Read: `.agents/skills/mma-orchestrator/SKILL.md` (~9.7K)

**Scope:** This is a LIGHT verification pass. For each file:
1. Read it
2. Confirm it covers the role accurately (cross-reference with the orchestrator skill's role description)
3. If drift is found, make a surgical fix
4. If the file is fundamentally outdated, FLAG for a separate track — do NOT rewrite wholesale here

- [ ] **Step 4.1: Pre-edit checkpoint**

```powershell
git -C C:\projects\manual_slop add .
```

- [ ] **Step 4.2: Read the canonical orchestrator skill**

Use `manual-slop_read_file` on `mma-orchestrator/SKILL.md`. This is the source of truth for the MMA architecture.

- [ ] **Step 4.3: For each tier skill (1-4), verify role accuracy**

For each `.agents/skills/mma-tierN-*/SKILL.md`:
- Read it (use `manual-slop_read_file`)
- Cross-reference with the orchestrator skill's description of the tier
- Note any drift: missing responsibilities, stale model names, wrong tool references

- [ ] **Step 4.4: For each drift found, make a surgical fix**

If the drift is small (a model name, a tool name, a single responsibility statement):
- Make the fix in place
- Commit per file

If the drift is large (the whole role description is outdated):
- DO NOT rewrite in this plan
- Note it in the commit message
- Add a task to a SEPARATE follow-up track (do not create new tasks in this plan)

- [ ] **Step 4.5: For each file with a surgical fix, commit**

```powershell
git -C C:\projects\manual_slop add .agents/skills/mma-tierN-*/SKILL.md
git -C C:\projects\manual_slop commit -m "docs(skills): fix drift in [tierN] skill - [specific fix]"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Found drift: [description]. Surgical fix applied: [what changed]. Larger rewrites deferred to [reason]." $_ }
```

- [ ] **Step 4.6: If no drift is found, commit an empty verification log**

```powershell
git -C C:\projects\manual_slop commit --allow-empty -m "docs(skills): verify all 5 skill files are coherent with orchestrator SKILL.md"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Read all 5 skill files. Cross-referenced with orchestrator SKILL.md. No drift found." $_ }
```

---

## Task 5: Light Verification of `.gemini/...` Mirrors

**Files:**
- Read: `.gemini/skills/mma-orchestrator/SKILL.md`
- Read: `.gemini/skills/mma-tier1-orchestrator/SKILL.md`
- Read: `.gemini/skills/mma-tier2-tech-lead/SKILL.md`
- Read: `.gemini/skills/mma-tier3-worker/SKILL.md`
- Read: `.gemini/skills/mma-tier4-qa/SKILL.md`
- Read: `.gemini/agents/tier1-orchestrator.md`
- Read: `.gemini/agents/tier2-tech-lead.md`
- Read: `.gemini/agents/tier3-worker.md`
- Read: `.gemini/agents/tier4-qa.md`

**Scope:** Compare the `.gemini/` mirror files against their canonical counterparts (`.agents/...`). If drift is found, fix it. This is the same LIGHT verification as Task 4 but for the Gemini-specific mirrors.

- [ ] **Step 5.1: Pre-edit checkpoint**

```powershell
git -C C:\projects\manual_slop add .
```

- [ ] **Step 5.2: For each `.gemini/...` file, compare to its canonical counterpart**

For each file:
- Read both the mirror and the canonical
- Diff them
- If different, determine which is the source of truth
- If the mirror is stale, fix it to match the canonical (or vice versa, depending on the file's role)

- [ ] **Step 5.3: For each drift found, commit per file**

```powershell
git -C C:\projects\manual_slop add .gemini/[path]
git -C C:\projects\manual_slop commit -m "docs(gemini-mirror): sync [file] with [canonical source]"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Mirror was out of sync. Updated to match canonical [path]." $_ }
```

---

## Task 6: Light Verification of `.claude/commands/*.md` (Legacy)

**Files:**
- Read: every file in `.claude/commands/` (9 files per the directory listing)

**Scope:** These are legacy files for backward compatibility. Lightly verify they still work and don't reference removed features. Do NOT rewrite — they are legacy.

- [ ] **Step 6.1: Pre-edit checkpoint**

```powershell
git -C C:\projects\manual_slop add .
```

- [ ] **Step 6.2: Read each file and check for broken references**

For each `.claude/commands/*.md`:
- Use `manual-slop_read_file` (they're small)
- Check for references to removed features (e.g., `gui_legacy.py`, `tkinter`, removed modules)
- Check for links that no longer resolve

- [ ] **Step 6.3: For each broken reference, decide**

Options:
- (a) Fix the broken reference (small edit)
- (b) Add a "(DEPRECATED)" notice to the file
- (c) Leave alone (legacy)

Default: (a) if it's a trivial fix (e.g., a link to a renamed file). (b) if the whole file is suspect. (c) if it's working and just old.

- [ ] **Step 6.4: For each file with a fix, commit per file**

```powershell
git -C C:\projects\manual_slop add .claude/commands/[file]
git -C C:\projects\manual_slop commit -m "docs(claude-commands): fix broken reference in [file]"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Found broken reference to [X]. Fixed by [what]." $_ }
```

---

## Task 7: Sub-Track 3 Verification (Drift Check)

- [ ] **Step 7.1: Section header drift audit**

For the section headers that should have been relocated, confirm each appears in at most one of `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`:

```powershell
$headers = @("Session Startup", "Conductor System", "MMA 4-Tier", "Anti-Patterns", "Development Workflow", "Code Style", "MCP Tool")
foreach ($h in $headers) {
    $inAgents = Select-String -Path C:\projects\manual_slop\AGENTS.md -Pattern $h -SimpleMatch -Quiet
    $inClaude = Select-String -Path C:\projects\manual_slop\CLAUDE.md -Pattern $h -SimpleMatch -Quiet
    $inGemini = Select-String -Path C:\projects\manual_slop\GEMINI.md -Pattern $h -SimpleMatch -Quiet
    $count = @($inAgents, $inClaude, $inGemini) | Where-Object { $_ } | Measure-Object | Select-Object -ExpandProperty Count
    if ($count -gt 1) { Write-Host "DRIFT: '$h' appears in $count files" }
}
```

If any header appears in 2+ files, the divergence model is violated. Either:
- (a) The duplicate is a short pointer (≤3 lines) → OK
- (b) The duplicate is full content → Fix by relocating

- [ ] **Step 7.2: Size sanity check**

```powershell
(Get-Item C:\projects\manual_slop\AGENTS.md).Length
(Get-Item C:\projects\manual_slop\CLAUDE.md).Length
(Get-Item C:\projects\manual_slop\GEMINI.md).Length
```

- AGENTS.md should be ≤ 1.5K
- CLAUDE.md should be ≤ 500 bytes
- GEMINI.md can be larger (Gemini-specific content is allowed) but should not contain duplicated agent-orientation content

- [ ] **Step 7.3: Link validation**

For every `[text](./relative/path)` in each of the 3 files, verify the target exists.

- [ ] **Step 7.4: Per-file commit verification**

```powershell
git -C C:\projects\manual_slop log --oneline -- AGENTS.md CLAUDE.md GEMINI.md .agents/ .gemini/ .claude/ | head -30
```

Confirm every file has its own commit history (not batched).

- [ ] **Step 7.5: Git note verification**

```powershell
git -C C:\projects\manual_slop log --format="%H" -- AGENTS.md CLAUDE.md GEMINI.md .agents/ .gemini/ .claude/ | Select-Object -First 20 | ForEach-Object { $note = git -C C:\projects\manual_slop notes show $_ 2>$null; if (-not $note) { Write-Host "MISSING NOTE: $_" } }
```

- [ ] **Step 7.6: Phase completion checkpoint**

Per the project's Phase Completion Verification protocol in `conductor/workflow.md`:
- Run the automated test suite
- Present the verification report to the user
- Get user sign-off
- Create the checkpoint commit: `conductor(checkpoint): Sub-Track 3 (agent config refresh) complete`
- Attach the verification report as a git note

---

## Self-Review (after writing this plan)

1. **Spec coverage:** Spec §6 has 6 phases (3.1-3.6). Tasks 1-3 cover 3.1-3.3. Tasks 4-6 cover 3.4-3.5 (skills, mirrors, legacy commands). Task 7 covers 3.6 (verification). ✓ All phases covered.
2. **Placeholder scan:** No "TBD" / "TODO" markers. The "If drift is found, fix it; if fundamentally outdated, flag for separate track" decision rule is explicit in Task 4.4. ✓
3. **Type/symbol consistency:** File paths, section header names, and the drift audit script are all consistent. ✓
4. **Risk check:** The stub approach for CLAUDE.md preserves compatibility. The "light verification, flag for separate track" pattern prevents scope creep. The drift audit script in Step 7.1 is concrete and runnable. ✓