Private

Public Access

Files

T

ed c073e42a7a docs(workflow,agents): add 7 process improvements from planning session

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.

2026-06-06 21:22:40 -04:00

3.0 KiB

Raw Blame History

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:

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.
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.
Check git log --oneline -20 to see what has been committed; the most recent commits in conductor/tracks/<track_id>/ are the latest work.
Run the audit scripts (scripts/audit_main_thread_imports.py, scripts/audit_weak_types.py) to see the current state of the codebase.
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).

3.0 KiB Raw Blame History