ed
c073e42a7a
All additive; no breaking changes to existing content. Derived from gaps observed during the 2026-06-06 planning session (5 tracks spec'd + planned end-to-end). **AGENTS.md (1 new section, 16 lines):** - Compaction Recovery - explicit recovery path for a new agent picking up mid-track (read the digest, check state.toml, run audits, resume from next unchecked task). Cross-references the workflow-level 'Compaction Recovery' section. **conductor/workflow.md (6 new sections, 145 lines):** - Planning Session Workflow - documents the brainstorming -> spec -> plan flow used 5x this session; mandates spec approval before plan; notes the plan is the only artifact the implementer reads. - Track Dependencies and Execution Order - verify the blocked_by chain in metadata.json before starting; topological sort gives the recommended execution order (recorded in PLANNING_DIGEST). - State.toml Template - canonical structure (meta / blocked_by / blocks / phases / tasks / verification / track-specific) so future tracks have a consistent shape. - Per-Task Decision Protocol - small decisions (cosmetic) decide yourself; large decisions (architectural) STOP and report; regressions STOP and report. The boundary is 'does this require a new spec or plan update?'. - Documentation Refresh Protocol - after a track ships, identify affected guides (grep for renamed/moved symbols), update them, add new guides for new modules, add styleguides for new conventions. The 'post-tracks documentation' pattern is repeatable; tracks that only update code are incomplete. - Audit Script Policy - whenever a track introduces a new convention that can be statically checked, add an audit script in scripts/ with --help / --json / strict modes. The audit + CI gate pair is the convention-enforcement mechanism; 3 existing audits (audit_main_thread_imports, audit_weak_types, check_test_toml_paths) are the precedent. All sections reference existing project files (brainstorming skill, writing-plans skill, audit scripts, tracks.md, the existing 5 new tracks' spec.md files, PLANNING_DIGEST_20260606.md). No code changes. Documentation only. ~160 lines total added.
50 lines
3.0 KiB
Markdown
50 lines
3.0 KiB
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 14 deep-dive 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 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`
|
|
|
|
## Compaction Recovery
|
|
|
|
If you're a new agent picking up a session that was compacted (or a previous agent ran out of context), follow this recovery path:
|
|
|
|
1. **Read the most recent `docs/reports/PLANNING_DIGEST_<date>.md`** if one exists. It indexes the planning artifacts and explains the design decisions behind the active tracks.
|
|
2. **For each in-flight track**, read `conductor/tracks/<track_id>/state.toml` to see `current_phase`; read `conductor/tracks/<track_id>/plan.md` for the task breakdown.
|
|
3. **Check `git log --oneline -20`** to see what has been committed; the most recent commits in `conductor/tracks/<track_id>/` are the latest work.
|
|
4. **Run the audit scripts** (`scripts/audit_main_thread_imports.py`, `scripts/audit_weak_types.py`) to see the current state of the codebase.
|
|
5. **Resume from the next unchecked task** in `state.toml`. The per-task commit discipline means each commit is a safe rollback point.
|
|
|
|
The track's `metadata.json` has a `verification_criteria` field — this is the definition of "done" for the track. If all the criteria are checked, the track is complete.
|
|
|
|
For deeper recovery, see `conductor/workflow.md` "Compaction Recovery" (the same pattern, but workflow-level).
|