Private
Public Access
0
0

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.
This commit is contained in:
2026-06-06 21:22:40 -04:00
parent 8fea8fe9a0
commit c073e42a7a
2 changed files with 161 additions and 2 deletions
+16 -2
View File
@@ -30,6 +30,20 @@ For understanding, using, and maintaining the tool, see `docs/Readme.md` and the
- 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 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).