ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity
Files
4ee22dedb98b6cedbf556da0160ae1e2808a6de0
manual_slop/docs/superpowers/plans/2026-06-02-agent-config-refresh.md
T

20 KiB
Raw Blame History

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):

# 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
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

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

Should be ≤ 1500 bytes. If larger, trim.

  • Step 1.8: Commit
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
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
# 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
(Get-Item C:\projects\manual_slop\CLAUDE.md).Length

Should be ≤ 500 bytes.

  • Step 2.6: Commit
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
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

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
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

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
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
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

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
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
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:

$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

(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
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
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. ✓
View Git Blame Copy Permalink