diff --git a/conductor/tracks/agent_directives_consolidation_20260705/spec.md b/conductor/tracks/agent_directives_consolidation_20260705/spec.md new file mode 100644 index 00000000..9fa0cc0f --- /dev/null +++ b/conductor/tracks/agent_directives_consolidation_20260705/spec.md @@ -0,0 +1,207 @@ +# Track Specification: Agent Directives Consolidation + +**Status:** Spec approved 2026-07-05. +**Initialized:** 2026-07-05 +**Owner:** Tier 1 Orchestrator +**Priority:** Medium-High (user's "very good fallback" before new directive system adoption) +**Type:** Documentation refactor (no `src/`, no tests, no agent-directive file modifications outside the hard-coded `AGENTS.md` + `conductor/*.md` + `code_styleguides/*.md`) + +--- + +## 0. Overview + +The project has hard-coded directive markdown across 3 locations: +1. `AGENTS.md` (root, 200 lines) — project-level rules +2. `conductor/*.md` (`workflow.md`, `edit_workflow.md`, `product-guidelines.md`, etc.) — operational + style rules +3. `conductor/code_styleguides/*.md` (14 files) — per-domain styleguides + +Many directives are duplicated across these files. Goal: **reduce duplicates by establishing one canonical home per directive, with thin pointers from elsewhere.** The result is a well-organized fallback for the new `conductor/directives/` system (which is WIP per user). + +**NOT in scope** (per user direction): +- `.opencode/agents/*.md` role prompts (separate concern; user explicitly excluded MMA) +- `.opencode/agents/*.warm.md` (new directive system, WIP) +- `conductor/directives/` (WIP, excluded) +- `conductor/tier2/agents/tier2-autonomous.md` (active Tier 2 sandbox; kept as-is) + +--- + +## 1. Current State Audit (as of commit `f63769ac^`) + +### 1.1 Already Implemented (DO NOT re-implement) + +| What | Where | Notes | +|---|---|---| +| 14 code_styleguides with single-source-of-truth | `conductor/code_styleguides/*.md` | Each is the canonical for its domain; cross-references work | +| AGENTS.md as project-root index | `AGENTS.md` | Has 13 critical anti-patterns + 5 session-learned + 8 process anti-patterns | +| Operational workflow | `conductor/workflow.md` | Has Session Start Checklist, Task Workflow, Process Anti-Patterns (abridged) | +| Edit tool contract | `conductor/edit_workflow.md` | Has the 9 rules for `manual-slop_edit_file` etc. | +| Core Value (C11/Odin/Jai) | `conductor/product-guidelines.md` | The project root canonical | +| Python Type Promotion Mandate §8.5 | `conductor/code_styleguides/data_oriented_design.md` | The technical canonical | + +### 1.2 Gaps to Fill (This Track's Scope) + +The audit (per the prior review) identified these redundancies in the **hard-coded docs** (AGENTS.md + conductor/*.md + code_styleguides/*.md): + +| # | Directive | Duplicated in | Canonical home | +|---|---|---|---| +| 1 | `ast.parse()` "Syntax OK" is not enough | AGENTS.md §103-108 + conductor/edit_workflow.md §7 | conductor/edit_workflow.md §7 (longer, has examples) | +| 2 | Decorator-orphan pitfall | AGENTS.md §2 + conductor/edit_workflow.md §6 | conductor/edit_workflow.md §6 (longer, has fix code) | +| 3 | No Diagnostic Noise in Production Code | AGENTS.md §84 + conductor/edit_workflow.md §9 + conductor/code_styleguides/python.md §8 last bullet | conductor/code_styleguides/python.md §8 (last bullet) | +| 4 | Process Anti-Patterns (8 list) | AGENTS.md §120-189 + conductor/workflow.md §534-548 | AGENTS.md (canonical, with full rationale) | +| 5 | 1-Space Indentation | conductor/code_styleguides/python.md §1 + conductor/product-guidelines.md "AI-Optimized Compact Style" + conductor/edit_workflow.md §5 + conductor/workflow.md §"Code Style" | conductor/code_styleguides/python.md §1 (most detailed) | +| 6 | No comments in source code | AGENTS.md §56 + conductor/product-guidelines.md "AI-Optimized Compact Style" + conductor/code_styleguides/python.md §8 first bullet | conductor/code_styleguides/python.md §8 first bullet | +| 7 | HARD BAN list (git push/checkout/restore/reset/stash) | AGENTS.md §58-60 + conductor/workflow.md "Known Pitfalls" + conductor/edit_workflow.md §2 (partial) + conductor/tier2/agents/tier2-autonomous.md (out of scope) | AGENTS.md §"Critical Anti-Patterns" (full rationale) | +| 8 | TDD (write failing test first) | AGENTS.md §53 + conductor/workflow.md + conductor/product-guidelines.md + conductor/tier2/agents/tier2-autonomous.md (out of scope) | AGENTS.md §"Critical Anti-Patterns" §3 (1-line) + conductor/code_styleguides/python.md (full TDD methodology) | +| 9 | Skip-marker is documentation | AGENTS.md §54-55 + conductor/workflow.md "Skip-Marker Policy" | conductor/workflow.md "Skip-Marker Policy" (full policy) | +| 10 | Python Type Promotion Mandate | AGENTS.md §62 + conductor/product-guidelines.md "Core Value" + conductor/code_styleguides/data_oriented_design.md §8.5 + conductor/code_styleguides/python.md §17 + conductor/code_styleguides/type_aliases.md | conductor/code_styleguides/data_oriented_design.md §8.5 (technical canonical) | +| 11 | Per-Task Decision Protocol | conductor/workflow.md + conductor/tier2/agents/tier2-autonomous.md (out of scope) | conductor/workflow.md (abridged) | + +### 1.3 Pre-Existing Conditions + +- AGENTS.md + conductor/*.md + code_styleguides/*.md all live in git; user is the primary editor +- The hard-coded docs are referenced from `manual_slop.toml [agent].context_files` (per `docs/AGENTS.md`) for the Application's RAG; the canonical styleguide is `conductor/code_styleguides/data_oriented_design.md` "one source of truth for both harnesses" (per AGENTS.md §"Canonical Operating Rules") +- The 8 Process Anti-Patterns in AGENTS.md and conductor/workflow.md are NOT exactly identical — workflow.md has abridged 1-line summaries with a "see AGENTS.md for full rationale" pointer. This is designed layering, not pure redundancy. +- The 5 Session-Learned Anti-Patterns in AGENTS.md vs the 9 rules in conductor/edit_workflow.md have significant overlap but distinct content. The edit_workflow.md versions are practical examples; the AGENTS.md versions are lessons-learned. + +--- + +## 2. Goals (Priority Order) + +| Priority | Goal | Rationale | +|---|---|---| +| **A (primary)** | For each duplicated directive, identify the canonical home + replace the OTHER files' content with thin pointers to the canonical home. | User's "reduce the duplicates" goal. | +| **B (process)** | Keep AGENTS.md as the project-root index but reduce the §"Critical Anti-Patterns" + §"Process Anti-Patterns" sections to bare essentials. | AGENTS.md is read on session start by humans; full rationale is documented in code_styleguides/*.md. | +| **C (process)** | Keep conductor/code_styleguides/*.md as the technical canonical; ensure cross-references work cleanly. | Already well-organized; verify after changes. | +| **D (process)** | All changes are atomic per `conductor/workflow.md` §"Task Workflow" step 9; git notes attached. | Per project convention. | + +--- + +## 3. Functional Requirements + +### 3.1 AGENTS.md reductions + +Reduce the following sections to bare essentials (1-2 lines each) with a pointer to the canonical home: + +- §"Critical Anti-Patterns" → reduce from 15 items to: 1-line reference to `conductor/code_styleguides/python.md` §"Anti-Patterns (LLM Default Anti-Patterns)" + the 3 critical hard bans (git restore, git stash*, day estimates) inline as 1-liners + the file size/naming rule inline as 1-liner +- §"Session-Learned Anti-Patterns" → reduce from 5 items to: 1-line reference to `conductor/edit_workflow.md` for the edit-tool-specific rules (decorator-orphan, ast.parse, small-edits) +- §"Process Anti-Patterns" → reduce from 8 items to: 1-line summary list + pointer to the canonical home in `conductor/workflow.md` (which becomes the canonical for these) +- Keep §"File Size and Naming Convention" (it's the only place this is documented in detail; canonical) +- Keep §"Compaction Recovery" (canonical) + +### 3.2 conductor/workflow.md reductions + +- §"Process Anti-Patterns (Added 2026-06-09)" → becomes the CANONICAL home for process anti-patterns (was abridged summary; promote to full content). Currently 14 lines of abridged content; expand to full versions matching AGENTS.md's 70+ lines. AGENTS.md's version becomes the thin pointer. +- §"Known Pitfalls" → reduce git ban list to a 1-line pointer to AGENTS.md (the canonical) + +### 3.3 conductor/edit_workflow.md reductions + +- §6 "The Decorator-Orphan Pitfall" → keep the longer canonical version (the AGENTS.md version becomes a 1-line pointer) +- §7 "`ast.parse()` Is Not Enough" → keep the longer canonical version (the AGENTS.md version becomes a 1-line pointer) +- §9 "No Diagnostic Noise in Production Code" → reduce to a pointer to `conductor/code_styleguides/python.md` §8 (the canonical location) + +### 3.4 conductor/product-guidelines.md reductions + +- §"AI-Optimized Compact Style" → "Indentation" subsection: reduce to a 1-line pointer to `conductor/code_styleguides/python.md` §1 (the canonical) +- §"Data-Oriented Error Handling" → reduce to a 1-line pointer to `conductor/code_styleguides/error_handling.md` (the canonical) +- §"Data Structure Conventions" → reduce to a 1-line pointer to `conductor/code_styleguides/type_aliases.md` (the canonical) + +### 3.5 conductor/code_styleguides/*.md verification + +- No content changes; verify cross-references after the project file reductions work cleanly +- Ensure `python.md` §"AI-Agent Specific Conventions" + §"Anti-Patterns" (LLM Default Anti-Patterns) sections are still comprehensive enough to be the canonical home + +--- + +## 4. Non-Functional Requirements + +- All changes are atomic per `conductor/workflow.md` §"Task Workflow" step 9 +- All commits have git notes attached +- No `src/*.py` changes +- No `.opencode/` changes +- No `conductor/directives/` changes +- No `conductor/tier2/agents/tier2-autonomous.md` changes (active sandbox; out of scope per user) +- 1-space indentation (per `conductor/code_styleguides/python.md` §1) applies to any Python changes (none expected) +- "No comments in body" rule (per `conductor/code_styleguides/python.md` §8) applies + +--- + +## 5. Architecture Reference + +- **`AGENTS.md`** (root) — project-root agent-facing rules; "Critical Anti-Patterns" + "Process Anti-Patterns" + "File Size and Naming Convention" + "Compaction Recovery" sections +- **`conductor/workflow.md`** — operational workflow; "Task Workflow" + "Process Anti-Patterns" (becomes canonical) + "Per-Task Decision Protocol" + "Phase Completion Verification and Checkpointing Protocol" +- **`conductor/edit_workflow.md`** — edit tool contract; "Decorator-Orphan Pitfall" (canonical) + "`ast.parse()` Is Not Enough" (canonical) +- **`conductor/product-guidelines.md`** — "Core Value" + "UX & UI Principles" + "Code Standards & Architecture" + "Phase 5: Heavy Curation" + "AI-Optimized Compact Style" (with pointer to python.md) + "Data-Oriented Error Handling" (with pointer to error_handling.md) +- **`conductor/code_styleguides/python.md`** §1 (1-space indent canonical) + §8 (no comments, no diagnostic noise canonical) +- **`conductor/code_styleguides/data_oriented_design.md`** §8.5 (Python Type Promotion Mandate canonical) +- **`conductor/code_styleguides/error_handling.md`** (Result[T] + NIL_T canonical) +- **`conductor/code_styleguides/type_aliases.md`** (Metadata boundary type canonical) +- **`docs/AGENTS.md`** — the agent-facing mirror of `docs/Readme.md`; out of scope (no changes needed) + +--- + +## 6. Implementation Phases (4 phases, ~10 atomic commits) + +| # | Phase | Scope | Commits | +|---|---|---|---| +| 1 | **AGENTS.md reductions** | Reduce §"Critical Anti-Patterns" + §"Session-Learned Anti-Patterns" + §"Process Anti-Patterns" to thin pointers | 3 (1 per section) | +| 2 | **conductor/workflow.md reductions + promotion** | Reduce §"Known Pitfalls" to pointer; promote §"Process Anti-Patterns" to canonical (full content) | 2 (1 per section) | +| 3 | **conductor/edit_workflow.md + product-guidelines.md reductions** | Reduce edit_workflow.md §9 to pointer; reduce product-guidelines.md subsections to pointers | 4 (1 per file, possibly 2 for product-guidelines.md) | +| 4 | **Self-review + finalize** | Verify cross-references; ensure no broken links; update tracks.md + state.toml | 2 (state + tracks.md) | + +**Total commits:** ~11 atomic commits with git notes. + +--- + +## 7. Verification Criteria + +The track is "done" when all of the following are true: + +- [ ] `AGENTS.md` is reduced to ~80-100 lines (from 202); the §"Critical Anti-Patterns" + §"Session-Learned Anti-Patterns" + §"Process Anti-Patterns" sections are thin pointers to canonical homes +- [ ] `conductor/workflow.md` §"Process Anti-Patterns" is the canonical home (full content); the §"Known Pitfalls" hard-ban section is a thin pointer to AGENTS.md +- [ ] `conductor/edit_workflow.md` §9 is a thin pointer to `conductor/code_styleguides/python.md` §8 +- [ ] `conductor/product-guidelines.md` "Indentation", "Data-Oriented Error Handling", "Data Structure Conventions" subsections are thin pointers to their canonical styleguides +- [ ] `conductor/code_styleguides/*.md` files have no changes (verified as canonical) +- [ ] All cross-references resolve to actual files (no broken links) +- [ ] `state.toml` final state is `current_phase=4` and `status="active"` +- [ ] `tracks.md` row marked Completed +- [ ] No `src/`, `.opencode/`, `conductor/directives/`, or `conductor/tier2/` changes +- [ ] All commits are atomic with git notes attached + +--- + +## 8. Risks & Mitigations + +| Risk | Impact | Mitigation | +|---|---|---| +| Cross-reference text drift (e.g., "see python.md §8" but the section number changes) | Low | Verify each cross-reference after the change; use section titles not numbers where possible | +| Reducing AGENTS.md too aggressively loses information | Medium | Each reduction is a "thin pointer + 1-line summary + link to canonical"; the summary preserves the gist | +| conductor/workflow.md §"Process Anti-Patterns" promotion creates 2x duplication with AGENTS.md (now both have full content) | Low | The promotion replaces AGENTS.md's full content with a pointer, so net duplication is reduced | +| The "fallback" use case (new directive system not used) leaves agents under-informed | Low | The thin pointers in AGENTS.md are sufficient for the LLM to navigate to the canonical home; the canonical homes have full content | + +--- + +## 9. Out of Scope (Explicit) + +1. **`.opencode/agents/*.md` role prompts** — user explicitly excluded ("ignore the mma bullshit in ./opencode"); separate concern +2. **`.opencode/agents/*.warm.md`** — new directive system, WIP per user +3. **`conductor/directives/`** — new directive system, WIP per user +4. **`conductor/tier2/agents/tier2-autonomous.md`** — active Tier 2 sandbox; kept as-is +5. **`conductor/code_styleguides/*.md` content changes** — verified as canonical, not modified +6. **The role prompts' content** — separate from the hard-coded directive markdown concern + +--- + +## 10. See Also + +- `AGENTS.md` (root) — current state of the project-root rules +- `conductor/workflow.md` §"Process Anti-Patterns" — current state of the operational workflow rules +- `conductor/edit_workflow.md` — current state of the edit tool contract +- `conductor/product-guidelines.md` §"Core Value" — current state of the project Core Value +- `conductor/code_styleguides/*.md` (14 files) — current state of the per-domain styleguides +- `docs/AGENTS.md` §"Convention Enforcement" — out-of-scope mirror with the 4 enforcement mechanisms + +--- + +## 11. Track History + +- 2026-07-05 — Initialized (spec + plan + state + tracks.md) per user directive "Lets reduce the duplicates and put them in proper places... Then localize important directives from there" + "The goal for me is to have this 'hard-coded written' directive markdown be in good shape before I start attempting to use the new directive system in the near future while having a very good fallback." \ No newline at end of file diff --git a/conductor/tracks/agent_directives_consolidation_20260705/state.toml b/conductor/tracks/agent_directives_consolidation_20260705/state.toml new file mode 100644 index 00000000..baa46b87 --- /dev/null +++ b/conductor/tracks/agent_directives_consolidation_20260705/state.toml @@ -0,0 +1,63 @@ +# Track state for agent_directives_consolidation_20260705 +# Updated by Tier 1 Orchestrator as phases complete + +[meta] +track_id = "agent_directives_consolidation_20260705" +name = "Agent Directives Consolidation (Hard-coded markdown fallback for the new directive system)" +status = "active" +current_phase = 0 # 0 = pre-Phase 1; spec is written but no implementation yet +last_updated = "2026-07-05" + +[blocked_by] +# No external blockers; project documentation is always available to update. + +[blocks] +# No followup tracks blocked on this one. + +[phases] +phase_1 = { status = "pending", checkpointsha = "", name = "AGENTS.md reductions" } +phase_2 = { status = "pending", checkpointsha = "", name = "conductor/workflow.md reductions + Process Anti-Patterns promotion" } +phase_3 = { status = "pending", checkpointsha = "", name = "conductor/edit_workflow.md + product-guidelines.md reductions" } +phase_4 = { status = "pending", checkpointsha = "", name = "Self-review + finalize" } + +[tasks] +# Phase 1 +t1_1 = { status = "pending", commit_sha = "", description = "Reduce AGENTS.md §\"Critical Anti-Patterns\" to thin pointers" } +t1_2 = { status = "pending", commit_sha = "", description = "Reduce AGENTS.md §\"Session-Learned Anti-Patterns\" to thin pointer" } +t1_3 = { status = "pending", commit_sha = "", description = "Reduce AGENTS.md §\"Process Anti-Patterns\" to thin pointer" } + +# Phase 2 +t2_1 = { status = "pending", commit_sha = "", description = "Reduce conductor/workflow.md §\"Known Pitfalls\" hard-ban list to pointer" } +t2_2 = { status = "pending", commit_sha = "", description = "Promote conductor/workflow.md §\"Process Anti-Patterns\" to canonical (full content)" } + +# Phase 3 +t3_1 = { status = "pending", commit_sha = "", description = "Reduce conductor/edit_workflow.md §9 \"No Diagnostic Noise\" to pointer" } +t3_2 = { status = "pending", commit_sha = "", description = "Reduce conductor/product-guidelines.md \"Indentation\" to pointer" } +t3_3 = { status = "pending", commit_sha = "", description = "Reduce conductor/product-guidelines.md \"Data-Oriented Error Handling\" to pointer" } +t3_4 = { status = "pending", commit_sha = "", description = "Reduce conductor/product-guidelines.md \"Data Structure Conventions\" to pointer" } + +# Phase 4 +t4_1 = { status = "pending", commit_sha = "", description = "Verify cross-references resolve; ensure no broken links" } +t4_2 = { status = "pending", commit_sha = "", description = "Update state.toml to current_phase=4 + all tasks completed" } +t4_3 = { status = "pending", commit_sha = "", description = "Update tracks.md row to Completed" } + +[verification] +agents_md_reduced_to_80_to_100_lines = false +workflow_md_process_anti_patterns_canonical = false +edit_workflow_md_section_9_thinned = false +product_guidelines_md_subsections_thinned = false +code_styleguides_unchanged = true # already verified +cross_references_resolve = false +state_toml_current_phase_4 = false +tracks_md_row_marked_completed = false +no_src_changes = true # not in scope +no_opencode_changes = true # not in scope per user +no_directives_changes = true # not in scope per user +all_commits_atomic_with_git_notes = false + +[user_directives_logged] +goal = "Per user 2026-07-05 'The goal for me is to have this hard-coded written directive markdown be in good shape before I start attempting to use the new directive system in the near future while having a very good fallback.'" +out_of_scope_opencode = "Per user 'ignore the mma bullshit in ./opencode' — .opencode/agents/*.md role prompts excluded." +out_of_scope_directives = "Per user 'Ignore the new directive system as thats still wip' — conductor/directives/ excluded." +out_of_scope_tier2 = "Per user scope decision — conductor/tier2/agents/tier2-autonomous.md active sandbox kept as-is." +reduce_then_localize = "Per user 'Lets reduce the duplicates and put them in proper places. ... Then localize important directives from there.'" \ No newline at end of file