ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity
Files
01a12d6eafac04f86d179956cb676a031501bc2e
manual_slop/conductor/tracks/agent_directives_consolidation_20260705/spec.md
T

15 KiB
Raw Blame History

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."
View Git Blame Copy Permalink