conductor(track): init agent_directives_consolidation_20260705 (spec + state)
This commit is contained in:
@@ -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."
|
||||
@@ -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.'"
|
||||
Reference in New Issue
Block a user