Private
Public Access
15 KiB
15 KiB
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:
AGENTS.md(root, 200 lines) — project-level rulesconductor/*.md(workflow.md,edit_workflow.md,product-guidelines.md, etc.) — operational + style rulesconductor/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/*.mdrole 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(perdocs/AGENTS.md) for the Application's RAG; the canonical styleguide isconductor/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.mdfor 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/*.pychanges - No
.opencode/changes - No
conductor/directives/changes - No
conductor/tier2/agents/tier2-autonomous.mdchanges (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" sectionsconductor/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 ofdocs/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.mdis reduced to ~80-100 lines (from 202); the §"Critical Anti-Patterns" + §"Session-Learned Anti-Patterns" + §"Process Anti-Patterns" sections are thin pointers to canonical homesconductor/workflow.md§"Process Anti-Patterns" is the canonical home (full content); the §"Known Pitfalls" hard-ban section is a thin pointer to AGENTS.mdconductor/edit_workflow.md§9 is a thin pointer toconductor/code_styleguides/python.md§8conductor/product-guidelines.md"Indentation", "Data-Oriented Error Handling", "Data Structure Conventions" subsections are thin pointers to their canonical styleguidesconductor/code_styleguides/*.mdfiles have no changes (verified as canonical)- All cross-references resolve to actual files (no broken links)
state.tomlfinal state iscurrent_phase=4andstatus="active"tracks.mdrow marked Completed- No
src/,.opencode/,conductor/directives/, orconductor/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)
.opencode/agents/*.mdrole prompts — user explicitly excluded ("ignore the mma bullshit in ./opencode"); separate concern.opencode/agents/*.warm.md— new directive system, WIP per userconductor/directives/— new directive system, WIP per userconductor/tier2/agents/tier2-autonomous.md— active Tier 2 sandbox; kept as-isconductor/code_styleguides/*.mdcontent changes — verified as canonical, not modified- The role prompts' content — separate from the hard-coded directive markdown concern
10. See Also
AGENTS.md(root) — current state of the project-root rulesconductor/workflow.md§"Process Anti-Patterns" — current state of the operational workflow rulesconductor/edit_workflow.md— current state of the edit tool contractconductor/product-guidelines.md§"Core Value" — current state of the project Core Valueconductor/code_styleguides/*.md(14 files) — current state of the per-domain styleguidesdocs/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."