docs(spec): comprehensive documentation refresh design (3 sub-tracks)
This commit is contained in:
@@ -0,0 +1,385 @@
|
||||
# Comprehensive Documentation Refresh
|
||||
|
||||
**Date:** 2026-06-02
|
||||
**Status:** Draft (pending review)
|
||||
**Parent Track:** `documentation_refresh_comprehensive_20260602`
|
||||
**Sub-Tracks:** 3 (sequential with one parallel pair)
|
||||
|
||||
---
|
||||
|
||||
## 1. Context & Motivation
|
||||
|
||||
Manual Slop is a local GUI orchestrator for LLM-driven coding sessions. Since the last documentation refresh track (`documentation_refresh_20260224`, completed February 2026), the codebase has grown substantially:
|
||||
|
||||
- **New subsystems** without dedicated guides: Beads mode (Dolt-backed issue tracking), RAG (ChromaDB + multi-source retrieval), Hot Reload (state-preserving module reloading), Discussion Metrics & Compression, Command Palette, Structural File Editor (unified AST inspector + slice editor)
|
||||
- **New language support** via tree-sitter: C, C++ (already in docs), plus planned Lua, GDScript, C# (in backlog)
|
||||
- **Two new guide files** that exist but are not linked from the docs index: `docs/guide_context_curation.md`, `docs/guide_shaders_and_window.md`
|
||||
- **Drift in agent config files** (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`): the three files overlap on Session Startup, Conductor System, MMA tiers, and anti-patterns; no single source of truth
|
||||
- **CLAUDE.md is largely vestigial** — Claude Code is no longer the primary toolchain, but the file still receives content updates
|
||||
- **AGENTS.md contains rich guidance content** that should live in `mma-orchestrator/SKILL.md` or `conductor/workflow.md`, not as a surface-level orientation file
|
||||
|
||||
The user has explicitly stated two goals for this refresh:
|
||||
|
||||
1. **Human-facing docs (`./docs/`, READMEs)** must reach **textbook / Microsoft "purple-tomb" SDK documentation** fidelity. Every detail: state machines, public APIs, threading constraints, algorithms. No hand-waving, no "left to the reader." A human should be able to use the tool AND maintain/extend the codebase from the docs alone.
|
||||
2. **Agent-facing docs** (`AGENTS.md`, `GEMINI.md`, skill files in `.agents/`, `.gemini/`) must follow an **explicit divergence model** with no content duplication. `AGENTS.md` becomes a thin pointer; `CLAUDE.md` is deprecated; `GEMINI.md` stays Gemini-CLI-specific.
|
||||
|
||||
This refresh is **documentation-only** (no new code, no new tooling, no new scripts). Drift control after the refresh is manual via the track's verification step.
|
||||
|
||||
---
|
||||
|
||||
## 2. Scope Boundaries
|
||||
|
||||
### In Scope
|
||||
|
||||
- Top-level `Readme.md`
|
||||
- `docs/Readme.md` and all `docs/guide_*.md` files
|
||||
- `conductor/product.md`, `conductor/product-guidelines.md`, `conductor/tech-stack.md`, `conductor/workflow.md`, `conductor/index.md`
|
||||
- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`
|
||||
- Light verification pass (read each, confirm role accuracy, fix obvious drift; do NOT rewrite wholesale) on `.agents/skills/*/SKILL.md`, `mma-orchestrator/SKILL.md`, `.gemini/...` mirrors
|
||||
- Per-file atomic git commits with git notes attached as rationale trails
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- Source code changes (a separate agent is making code modifications)
|
||||
- New lint/check scripts (drift control is manual)
|
||||
- New `docs/` files beyond what's required to document new subsystems
|
||||
- Re-architecting the conductor system itself
|
||||
- Removing CLAUDE.md (kept as a stub for compatibility)
|
||||
- Visual diagrams (ASCII is fine; no image generation)
|
||||
- Translating the docs to other languages
|
||||
|
||||
---
|
||||
|
||||
## 3. Track Architecture
|
||||
|
||||
The parent track `documentation_refresh_comprehensive_20260602` is a coordinator: it registers the three sub-tracks in `conductor/tracks.md`, sequences them, and produces a final verification report. Each sub-track is an independent conductor track with its own `spec.md`, `plan.md`, and `metadata.json`.
|
||||
|
||||
### Dependency Graph
|
||||
|
||||
```
|
||||
Sub-Track 1: docs_layer_refresh
|
||||
│
|
||||
├──> Sub-Track 2: conductor_docs_refresh
|
||||
│
|
||||
└──> Sub-Track 3: agent_config_refresh
|
||||
│
|
||||
└──> Parent verification
|
||||
```
|
||||
|
||||
Sub-Tracks 2 and 3 can run in parallel after Sub-Track 1 establishes the human-facing doc layer. The parent track does the final verification and creates the checkpoint commit.
|
||||
|
||||
### Execution Constraints (apply to all 3 sub-tracks)
|
||||
|
||||
- **No subagents.** Each sub-track is executed by a single agent (the user or the Tier 2 Tech Lead session) sequentially. No Tier 3 worker delegation, no Tier 4 QA delegation, no parallel worker execution.
|
||||
- **Per-file atomic commits.** One file = one commit. The git note attached to each commit captures the rationale and the source files cross-referenced during the rewrite.
|
||||
- **Pre-edit `git add .` checkpoint** before each file edit (protects against `git restore` mishaps).
|
||||
- **Style baseline:** `conductor/product-guidelines.md` — VEFontCache-Odin pattern (Philosophy → Architectural Boundaries → Implementation Logic → Verification), high information density, structural parity between doc symbols and source code symbols.
|
||||
- **Symbol parity:** Every class, function, method, and event named in the docs must match the source exactly. If the source uses `AsyncEventQueue`, the doc must use `AsyncEventQueue`, not "the event queue."
|
||||
- **Link validation:** Every `[text](./relative/path)` link is manually verified via `manual-slop_search_files` to confirm the target exists. Cross-doc links must point to files that exist in this or a future sub-track.
|
||||
- **No comments added to source code.** Documentation lives in `./docs/`, not inline.
|
||||
|
||||
---
|
||||
|
||||
## 4. Sub-Track 1: `docs_layer_refresh_20260602`
|
||||
|
||||
**Priority:** HIGHEST. This is the dominant work.
|
||||
|
||||
### File List
|
||||
|
||||
| File | Current Size | Notes |
|
||||
|---|---|---|
|
||||
| `Readme.md` | 15.5K | Main project README |
|
||||
| `docs/Readme.md` | ~3K | Documentation index |
|
||||
| `docs/guide_architecture.md` | 34.5K | Threading, events, AI client, HITL |
|
||||
| `docs/guide_mma.md` | unknown | 4-tier hierarchy, DAG, worker lifecycle |
|
||||
| `docs/guide_tools.md` | 22.9K | MCP tools, Hook API, shell runner |
|
||||
| `docs/guide_simulations.md` | unknown | live_gui fixture, Puppeteer, mock provider |
|
||||
| `docs/guide_context_curation.md` | 8K | Skeleton/curated/targeted views, fuzzy anchors |
|
||||
| `docs/guide_shaders_and_window.md` | 3.4K | Shader pipeline, custom window frame |
|
||||
| `docs/guide_meta_boundary.md` | 4.6K | Application vs Meta-Tooling domain |
|
||||
| `docs/MMA_Support/*` | varies | Legacy MMA reference docs — review for archival or merge |
|
||||
|
||||
### Tasks (Phases)
|
||||
|
||||
**Phase 1.1: Inventory and Gap Analysis**
|
||||
- Read each existing guide, summarize what subsystems it covers
|
||||
- Identify subsystems in `conductor/product.md` that have NO corresponding guide
|
||||
- Identify subsystems that DO have a guide but the guide is stale (e.g., does not cover features added since Feb 2026)
|
||||
- Produce a gap table: subsystem → current guide → needed changes (rewrite / add / link from index / remove)
|
||||
|
||||
**Phase 1.2: Update the Documentation Index**
|
||||
- Update `docs/Readme.md` so every `docs/guide_*.md` appears in the Guides table
|
||||
- Currently unlinked: `docs/guide_context_curation.md`, `docs/guide_shaders_and_window.md`
|
||||
- Decide fate of `docs/MMA_Support/*` (legacy archive or merge into `docs/guide_mma.md`)
|
||||
- Commit: `docs(index): link guide_context_curation and guide_shaders_and_window`
|
||||
|
||||
**Phase 1.3: Rewrite Each Guide (one file at a time, per-file atomic commits)**
|
||||
- For each guide, follow the per-file workflow:
|
||||
1. Read current source code (use `manual-slop_get_file_summary` and `manual-slop_py_get_skeleton`; do NOT read full files >50 lines)
|
||||
2. Read current `docs/MMA_Support/*` and `conductor/tracks/*/plan.md` for context on subsystems that have evolved
|
||||
3. Cross-reference `conductor/product.md` and `conductor/tech-stack.md` for the canonical feature/tech statement
|
||||
4. Identify what changed since the guide was last meaningfully updated
|
||||
5. Rewrite affected sections, preserving the VEFontCache-Odin style (Philosophy → Architectural Boundaries → Implementation Logic → Verification)
|
||||
6. Validate every internal `[link](./relative/path)` resolves
|
||||
7. Commit per-file with `docs(<scope>): <description>` message
|
||||
8. Attach git note with: source files cross-referenced, subsystems updated, any decisions made
|
||||
|
||||
**Phase 1.4: Update `Readme.md`**
|
||||
- Add a "Module by Domain" reference table that links to each guide for deep dives
|
||||
- Add a "Subsystem Index" section cross-referencing each major feature to its dedicated guide
|
||||
- Update the screenshot/gallery references if needed
|
||||
- Update setup instructions to reflect any new prerequisites (e.g., Beads CLI, Dolt)
|
||||
- Commit per-section: `docs(readme): add module-by-domain reference table`, `docs(readme): add subsystem index`, `docs(readme): update setup prerequisites`, etc.
|
||||
|
||||
**Phase 1.5: Subsystems Without Guides (write new guides as needed)**
|
||||
For each subsystem identified in 1.1 that lacks a guide, write a new `docs/guide_<name>.md` using the same per-file workflow. Likely candidates based on the gap analysis:
|
||||
- RAG (`docs/guide_rag.md`) — vector store, chunking, multi-provider search
|
||||
- Beads (`docs/guide_beads.md`) — Dolt integration, toolset, context compaction
|
||||
- Hot Reload (`docs/guide_hot_reload.md`) — `HotReloader` lifecycle, state preservation, UI delegation pattern
|
||||
- Discussion Metrics & Compression (`docs/guide_discussion_metrics.md`) — per-response token tracking, history compression strategy
|
||||
- Command Palette (`docs/guide_command_palette.md`) — async context preview, fuzzy command resolution
|
||||
- Structural File Editor (`docs/guide_structural_editor.md`) — unified AST inspector + slice editor
|
||||
- NERV Theme (`docs/guide_nerv_theme.md`) — black void palette, CRT-style effects, status flickering
|
||||
|
||||
Each new guide must follow the same VEFontCache-Odin style and link from `docs/Readme.md` (which means the index update in 1.2 must accommodate them).
|
||||
|
||||
**Phase 1.6: Verification**
|
||||
- `grep` for every internal link in every rewritten guide to confirm targets exist
|
||||
- `grep` for stale feature references (e.g., "MMA 4-tier" without the recent persona, RAG, Beads integrations mentioned in `conductor/product.md`)
|
||||
- Spot-check 3 random sections per guide against the corresponding source code
|
||||
- Manual user review (per workflow.md Phase Completion Verification protocol)
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
- Every `docs/guide_*.md` is referenced from `docs/Readme.md`
|
||||
- Every internal cross-doc link resolves
|
||||
- Every subsystem in `conductor/product.md` has a corresponding guide (either existing or newly written)
|
||||
- Every public class, function, and event named in any guide matches the source code symbol exactly
|
||||
- Every guide follows the VEFontCache-Odin pattern (Philosophy → Architectural Boundaries → Implementation Logic → Verification) with all four sections present where applicable
|
||||
- "Textbook / purple-tomb fidelity" interpreted concretely: for every public class/function/event mentioned, the doc states its signature, threading constraints, side effects, and at least one usage example. Internal algorithms are explained step-by-step, not summarized. State machines include the full transition table
|
||||
- Per-file commits exist for every change, with git notes attached
|
||||
|
||||
---
|
||||
|
||||
## 5. Sub-Track 2: `conductor_docs_refresh_20260602`
|
||||
|
||||
**Priority:** Medium. Sync the source-of-truth conductor docs to current state.
|
||||
|
||||
### File List
|
||||
|
||||
| File | Current Size | Notes |
|
||||
|---|---|---|
|
||||
| `conductor/product.md` | 23.1K | Product vision, feature list, use cases |
|
||||
| `conductor/product-guidelines.md` | 6.6K | Style and process guidelines |
|
||||
| `conductor/tech-stack.md` | unknown | Technology stack constraints |
|
||||
| `conductor/workflow.md` | 25.2K | Task lifecycle, TDD protocol |
|
||||
| `conductor/index.md` | 334 bytes | Conductor directory index |
|
||||
|
||||
### Tasks (Phases)
|
||||
|
||||
**Phase 2.1: Sync `conductor/product.md`**
|
||||
- Cross-reference every feature claim in `product.md` against the actual codebase
|
||||
- Add features that exist in code but are missing from `product.md` (Beads, RAG, Hot Reload, Discussion Metrics/Compression, Command Palette, Structural File Editor, NERV theme, persona editor, workspace profiles, etc.)
|
||||
- Remove features that have been culled or replaced
|
||||
- Update the "Primary Use Cases" section to reflect current usage patterns
|
||||
- Commit per-section: `docs(product): sync MMA dashboard section`, `docs(product): add RAG feature`, etc.
|
||||
|
||||
**Phase 2.2: Sync `conductor/tech-stack.md`**
|
||||
- Verify every entry corresponds to an actual Python dep (check `pyproject.toml` / `requirements.txt`) or an actual src/ module
|
||||
- Add new dependencies: chromadb (RAG), dolt (Beads), any new ones
|
||||
- Add new src/ modules: rag_engine.py, beads_client.py, hot_reloader.py, history.py, workspace_manager.py, etc.
|
||||
- Commit per-section.
|
||||
|
||||
**Phase 2.3: Sync `conductor/workflow.md`**
|
||||
- Verify the TDD protocol is followed by recent tracks (spot-check 3 recent tracks)
|
||||
- Verify the Phase Completion Verification protocol is followed
|
||||
- Verify the checkpointing protocol is followed
|
||||
- Update any sections that have drifted from actual practice
|
||||
- Commit per-section.
|
||||
|
||||
**Phase 2.4: Sync `conductor/product-guidelines.md`**
|
||||
- Verify the AI-Optimized Python Style (1-space indent, no comments, type hints) is actually followed by recent code
|
||||
- Verify the "Modular Controller Pattern" and "UI Delegation Pattern" are followed in `src/app_controller.py` and `src/gui_2.py`
|
||||
- Verify the "Mandatory ImGui Verification" linter (`scripts/check_imgui_scopes.py`) is still the source of truth
|
||||
- Update any sections that have drifted
|
||||
- Commit per-section.
|
||||
|
||||
**Phase 2.5: Update `conductor/index.md`**
|
||||
- If any new top-level conductor docs were added (e.g., `conductor/code_styleguides/` is referenced but not verified), link them
|
||||
- Commit.
|
||||
|
||||
**Phase 2.6: Verification**
|
||||
- `grep` for references to features that no longer exist
|
||||
- `grep` for missing dependencies (every dep in `pyproject.toml` should appear in `tech-stack.md`)
|
||||
- Spot-check 3 random claims per file
|
||||
- Manual user review
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
- Every feature in `conductor/product.md` corresponds to a real subsystem in `src/` or `tests/`
|
||||
- Every entry in `conductor/tech-stack.md` is an actual dep or module
|
||||
- `conductor/workflow.md` matches the actual workflow used by recent completed tracks
|
||||
- `conductor/product-guidelines.md` matches the actual coding style used in `src/`
|
||||
- `conductor/index.md` links to all relevant conductor files
|
||||
- Per-file commits with git notes
|
||||
|
||||
---
|
||||
|
||||
## 6. Sub-Track 3: `agent_config_refresh_20260602`
|
||||
|
||||
**Priority:** Lower. Apply the explicit divergence model.
|
||||
|
||||
### File List
|
||||
|
||||
| File | Current Size | Notes |
|
||||
|---|---|---|
|
||||
| `AGENTS.md` | 5.4K | Universal agent orientation — target: thin pointer |
|
||||
| `CLAUDE.md` | 6.7K | DEPRECATE to stub |
|
||||
| `GEMINI.md` | 3.8K | Keep Gemini-CLI-specific content |
|
||||
| `.agents/skills/mma-tier1-orchestrator/SKILL.md` | 2.4K | Light verification only |
|
||||
| `.agents/skills/mma-tier2-tech-lead/SKILL.md` | 3.8K | Light verification only |
|
||||
| `.agents/skills/mma-tier3-worker/SKILL.md` | unknown | Light verification only |
|
||||
| `.agents/skills/mma-tier4-qa/SKILL.md` | 813 bytes | Light verification only |
|
||||
| `.agents/skills/mma-orchestrator/SKILL.md` | 9.7K | Light verification only |
|
||||
| `mma-orchestrator/SKILL.md` (root copy) | 9.3K | Light verification only |
|
||||
| `.gemini/skills/*/SKILL.md` | varies | Light verification only (mirrors) |
|
||||
| `.gemini/agents/*.md` | varies | Light verification only (mirrors) |
|
||||
| `.claude/commands/*.md` | 9 files | Light verification only (legacy) |
|
||||
|
||||
### Tasks (Phases)
|
||||
|
||||
**Phase 3.1: Rewrite `AGENTS.md` to a thin pointer**
|
||||
|
||||
Target structure (estimated ~1K):
|
||||
|
||||
```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.
|
||||
|
||||
## 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
|
||||
- Do not skip TDD — write failing tests before implementation
|
||||
- Do not batch commits — commit per-task for atomic rollback
|
||||
```
|
||||
|
||||
**Phase 3.2: Replace `CLAUDE.md` with a 1-line stub**
|
||||
|
||||
Target content:
|
||||
|
||||
```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.
|
||||
```
|
||||
|
||||
(Keep the file as a stub to avoid breaking any external tooling that may still reference it.)
|
||||
|
||||
**Phase 3.3: Lightly refresh `GEMINI.md`**
|
||||
|
||||
- Verify it covers only Gemini-CLI-specific content (no shared content that should live in `AGENTS.md`)
|
||||
- Update any stale references to features, models, or paths
|
||||
- If any content was previously shared with `AGENTS.md` and has been relocated, update `GEMINI.md` to point to `AGENTS.md` instead
|
||||
- Commit: `docs(gemini): refresh Gemini CLI orientation`
|
||||
|
||||
**Phase 3.4: Verify `.agents/skills/*/SKILL.md` and `.gemini/...` mirrors for coherence**
|
||||
|
||||
For each skill file:
|
||||
- Read it; confirm it covers the role accurately
|
||||
- Compare with the canonical role description in `mma-orchestrator/SKILL.md`
|
||||
- If drift is found, fix it (small surgical edits)
|
||||
- If the file is outdated, flag for a separate track — do not rewrite wholesale in this track
|
||||
- Commit per file: `docs(skills): fix drift in tier1 orchestrator skill`
|
||||
|
||||
**Phase 3.5: Verify `.claude/commands/*.md` (legacy)**
|
||||
|
||||
- These exist for backward compatibility
|
||||
- Lightly verify they still work and don't reference removed features
|
||||
- Do not rewrite — they are legacy
|
||||
- If a file is broken, flag for separate track
|
||||
|
||||
**Phase 3.6: Verification**
|
||||
- `grep` for the section headers that should have been relocated (Session Startup, Conductor System, MMA 4-Tier, Anti-Patterns) across `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`
|
||||
- Confirm each appears in at most one file (or in multiple files only as short pointers)
|
||||
- Spot-check 2 random skills files against their canonical description
|
||||
- Manual user review
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
- `AGENTS.md` is ≤ 1.5K and contains only project orientation + pointers
|
||||
- `CLAUDE.md` is ≤ 200 bytes and contains only the deprecation stub
|
||||
- `GEMINI.md` contains only Gemini-CLI-specific content
|
||||
- No section header appears in 2+ of these files unless it's a short pointer (≤3 lines)
|
||||
- `.agents/skills/*/SKILL.md` and `.gemini/...` mirrors are verified for coherence
|
||||
- `.claude/commands/*.md` legacy files are verified to not reference removed features
|
||||
- Per-file commits with git notes
|
||||
|
||||
---
|
||||
|
||||
## 7. Parent Track: Final Verification
|
||||
|
||||
After all 3 sub-tracks complete, the parent track produces a final verification report:
|
||||
|
||||
1. **Cross-track link audit:** For every markdown file modified in any sub-track, run `grep` for `[text](./relative/path)` patterns and verify each target exists
|
||||
2. **Symbol parity audit:** Spot-check 5 random symbols named in any doc against the source — confirm exact match
|
||||
3. **Drift audit:** `grep` for the relocated section headers (`Session Startup`, `Conductor System`, `MMA 4-Tier`, `Anti-Patterns`, etc.) across `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` — confirm explicit divergence holds
|
||||
4. **Subsystem coverage audit:** For every feature in `conductor/product.md`, confirm a corresponding guide exists in `docs/`
|
||||
5. **User review gate:** Present the final verification report and request user sign-off per workflow.md Phase Completion Verification protocol
|
||||
|
||||
The parent track then creates a single checkpoint commit: `conductor(checkpoint): Comprehensive documentation refresh complete` and attaches the verification report as a git note.
|
||||
|
||||
---
|
||||
|
||||
## 8. Risks & Mitigations
|
||||
|
||||
| Risk | Mitigation |
|
||||
|---|---|
|
||||
| A source code change by the other agent makes a doc claim stale mid-refresh | Per-file atomic commits + pre-edit `git add .` checkpoint; if drift is found during a later file's rewrite, fix the earlier file in a follow-up commit |
|
||||
| Scope creep — adding new guides balloons the track | The gap analysis in 1.1 is the gating step; new guides are written only for subsystems explicitly listed in `conductor/product.md` |
|
||||
| The 3 sub-tracks drift in style consistency | Style baseline is `conductor/product-guidelines.md` (single source); reviewed by user per sub-track |
|
||||
| Manual link validation misses broken links | Per-file commit immediately after each rewrite; a broken link is caught in the next file's cross-reference work |
|
||||
| User reviews take long enough that the codebase evolves underneath | Sub-tracks are independent; each can resume from its last commit if interrupted |
|
||||
| The legacy `CLAUDE.md` deprecation breaks external tooling | The file is kept as a 1-line stub, not removed; any external tooling that reads it will see a graceful pointer to `AGENTS.md` |
|
||||
|
||||
---
|
||||
|
||||
## 9. Out of Scope (Reminder)
|
||||
|
||||
- Source code changes
|
||||
- New lint scripts (drift control is manual)
|
||||
- Image/diagram generation
|
||||
- Translations
|
||||
- Removing CLAUDE.md
|
||||
- Visual layout of the docs site (Manual Slop is a GUI app, not a docs site)
|
||||
|
||||
---
|
||||
|
||||
## 10. Success Criteria
|
||||
|
||||
The track is complete when:
|
||||
|
||||
1. All 3 sub-tracks have completed all their phases with per-file atomic commits and git notes
|
||||
2. The parent track's verification report shows zero broken cross-doc links, zero symbol mismatches in spot-checks, and confirmed explicit divergence in agent config files
|
||||
3. Every subsystem in `conductor/product.md` has a corresponding guide
|
||||
4. `Readme.md`, `docs/Readme.md`, and every `docs/guide_*.md` is at textbook / purple-tomb fidelity (verified by user review)
|
||||
5. `AGENTS.md` is a thin pointer document; `CLAUDE.md` is a deprecation stub
|
||||
6. The user has signed off on the final verification report per workflow.md
|
||||
+23
-23
@@ -44,20 +44,20 @@ Collapsed=0
|
||||
DockId=0x00000010,0
|
||||
|
||||
[Window][Message]
|
||||
Pos=1370,26
|
||||
Size=1510,1774
|
||||
Pos=1192,28
|
||||
Size=1510,1619
|
||||
Collapsed=0
|
||||
DockId=0x00000006,0
|
||||
|
||||
[Window][Response]
|
||||
Pos=0,26
|
||||
Size=1368,1774
|
||||
Pos=0,28
|
||||
Size=1190,1619
|
||||
Collapsed=0
|
||||
DockId=0x00000010,5
|
||||
|
||||
[Window][Tool Calls]
|
||||
Pos=1370,26
|
||||
Size=1510,1774
|
||||
Pos=1192,28
|
||||
Size=1510,1619
|
||||
Collapsed=0
|
||||
DockId=0x00000006,3
|
||||
|
||||
@@ -76,8 +76,8 @@ Collapsed=0
|
||||
DockId=0xAFC85805,2
|
||||
|
||||
[Window][Theme]
|
||||
Pos=0,26
|
||||
Size=1368,1774
|
||||
Pos=0,28
|
||||
Size=1190,1619
|
||||
Collapsed=0
|
||||
DockId=0x00000010,0
|
||||
|
||||
@@ -105,26 +105,26 @@ Collapsed=0
|
||||
DockId=0x0000000D,0
|
||||
|
||||
[Window][Discussion Hub]
|
||||
Pos=1370,26
|
||||
Size=1510,1774
|
||||
Pos=1192,28
|
||||
Size=1510,1619
|
||||
Collapsed=0
|
||||
DockId=0x00000006,1
|
||||
|
||||
[Window][Operations Hub]
|
||||
Pos=0,26
|
||||
Size=1368,1774
|
||||
Pos=0,28
|
||||
Size=1190,1619
|
||||
Collapsed=0
|
||||
DockId=0x00000010,4
|
||||
|
||||
[Window][Files & Media]
|
||||
Pos=0,26
|
||||
Size=1368,1774
|
||||
Pos=0,28
|
||||
Size=1190,1619
|
||||
Collapsed=0
|
||||
DockId=0x00000010,3
|
||||
|
||||
[Window][AI Settings]
|
||||
Pos=0,26
|
||||
Size=1368,1774
|
||||
Pos=0,28
|
||||
Size=1190,1619
|
||||
Collapsed=0
|
||||
DockId=0x00000010,2
|
||||
|
||||
@@ -140,8 +140,8 @@ Collapsed=0
|
||||
DockId=0x00000006,2
|
||||
|
||||
[Window][Log Management]
|
||||
Pos=1370,26
|
||||
Size=1510,1774
|
||||
Pos=1192,28
|
||||
Size=1510,1619
|
||||
Collapsed=0
|
||||
DockId=0x00000006,2
|
||||
|
||||
@@ -409,8 +409,8 @@ Collapsed=0
|
||||
DockId=0x00000006,1
|
||||
|
||||
[Window][Project Settings]
|
||||
Pos=0,26
|
||||
Size=1368,1774
|
||||
Pos=0,28
|
||||
Size=1190,1619
|
||||
Collapsed=0
|
||||
DockId=0x00000010,1
|
||||
|
||||
@@ -686,18 +686,18 @@ Column 1 Width=30
|
||||
|
||||
[Table][0x9D36FCE8,2]
|
||||
RefScale=20
|
||||
Column 0 Width=495
|
||||
Column 0 Width=659
|
||||
Column 1 Weight=1.0000
|
||||
|
||||
[Docking][Data]
|
||||
DockNode ID=0x00000008 Pos=3125,170 Size=593,1157 Split=Y
|
||||
DockNode ID=0x00000009 Parent=0x00000008 SizeRef=1029,147 Selected=0x0469CA7A
|
||||
DockNode ID=0x0000000A Parent=0x00000008 SizeRef=1029,145 Selected=0xDF822E02
|
||||
DockSpace ID=0xAFC85805 Window=0x079D3A04 Pos=0,26 Size=2880,1774 Split=X
|
||||
DockSpace ID=0xAFC85805 Window=0x079D3A04 Pos=0,28 Size=2702,1619 Split=X
|
||||
DockNode ID=0x00000003 Parent=0xAFC85805 SizeRef=2357,1183 Split=X
|
||||
DockNode ID=0x0000000B Parent=0x00000003 SizeRef=404,1186 Split=X Selected=0xF4139CA2
|
||||
DockNode ID=0x00000005 Parent=0x0000000B SizeRef=1320,1681 Split=Y Selected=0x3F1379AF
|
||||
DockNode ID=0x00000010 Parent=0x00000005 SizeRef=983,1140 CentralNode=1 Selected=0x418C7449
|
||||
DockNode ID=0x00000010 Parent=0x00000005 SizeRef=983,1140 CentralNode=1 Selected=0x1DCB2623
|
||||
DockNode ID=0x00000011 Parent=0x00000005 SizeRef=983,184 Selected=0x432BAE4E
|
||||
DockNode ID=0x00000006 Parent=0x0000000B SizeRef=1510,1681 Selected=0x6F2B5B04
|
||||
DockNode ID=0x0000000D Parent=0x00000003 SizeRef=435,1186 Selected=0x363E93D6
|
||||
|
||||
Reference in New Issue
Block a user