manual_slop/conductor/tracks/documentation_refresh_20260224/spec.md

Specification: Documentation Refresh and Context Cleanup

Overview

This track aims to modernize the project's documentation suite (Architecture, Tools, README) to reflect recent significant architectural additions, including the Conductor framework, the development of gui_2.py, and the API hook verification system. It also includes the decommissioning of MainContext.md, which has been identified as redundant in the current project structure.

Functional Requirements

1. Architecture Update (docs/guide_architecture.md):
   • Incorporate descriptions of the Conductor framework and its role in spec-driven development.
   • Document the dual-GUI structure (gui.py and gui_2.py) and their respective development stages.
   • Detail the EventEmitter and ApiHookClient as core architectural components.
2. Tools Update (docs/guide_tools.md):
   • Refresh documentation for the current MCP toolset.
   • Add documentation for the API hook client and automated GUI verification tools.
   • Update performance monitoring tool descriptions.
3. README Refresh (Readme.md):
   • Update setup instructions (e.g., uv, credentials.toml).
   • Highlight new features: Conductor integration, GUI 2.0, and automated testing capabilities.
   • Ensure the high-level project vision aligns with the current state.
4. Context Cleanup:
   • Permanently remove MainContext.md from the project root.
   • Update any internal references pointing to MainContext.md.

Non-Functional Requirements

• Link Validation: All internal documentation links must be verified as valid.
• Code-Doc Alignment: Architectural descriptions must accurately reflect the current code structure.
• Clarity & Brevity: Documentation should remain concise and targeted at expert-level developers.

Acceptance Criteria

• MainContext.md is deleted from the project.
• docs/guide_architecture.md is updated and reviewed for accuracy.
• docs/guide_tools.md is updated and reviewed for accuracy.
• Readme.md setup and feature sections are current.
• All internal links between Readme.md and the ./docs/ folder are functional.

Out of Scope

• Automated documentation generation (e.g., Sphinx, Doxygen).
• In-depth documentation for features still in early prototyping stages.
• Creating new video or visual walkthroughs.