ed/manual_slop

Private

Public Access

Fork 0

Files

T

ed 560c5dd131 docs(plans): implementation plans for comprehensive documentation refresh (3 sub-tracks)

2026-06-02 18:39:04 -04:00

20 KiB

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

Read it
Confirm it covers the role accurately (cross-reference with the orchestrator skill's role description)
If drift is found, make a surgical fix
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)

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.
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. ✓
Type/symbol consistency: File paths, section header names, and the drift audit script are all consistent. ✓
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. ✓

20 KiB Raw Permalink Blame History

Agent Config Refresh Implementation Plan

Execution Constraints

Task 1: Rewrite AGENTS.md to a Thin Pointer

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

Task 3: Refresh GEMINI.md

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

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

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

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

Self-Review (after writing this plan)

20 KiB

Raw Permalink Blame History

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

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

Task 3: Refresh `GEMINI.md`

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

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

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