manual_slop/.opencode/commands/conductor-new-track.md

description, agent, subtask

description	agent	subtask
Create a new conductor track with spec, plan, and metadata	tier1-orchestrator	true

/conductor-new-track

Create a new conductor track following the Surgical Methodology.

Arguments

$ARGUMENTS - Track name and brief description

Pre-Flight: Read the canonical docs FIRST (do NOT be conservative)

Added 2026-06-27. This project has extensive canonical documentation. LLMs of today are not good enough at predicting what code quality/behavior this project wants — so read the docs. Being conservative about reading knowledge from markdown files is an ANTI-PATTERN in this codebase.

Before writing the spec, read:

1. AGENTS.md — the project-root agent-facing rules; especially the HARD BANs (git restore/checkout/reset, opaque types in non-boundary code)
2. conductor/workflow.md — including §0 (Python Type Promotion Mandate) and the Tier 1 Track Initialization Rules
3. conductor/tech-stack.md — including the Core Value reference at the top
4. conductor/product.md — product vision + primary use cases
5. conductor/product-guidelines.md — Core Value section is mandatory reading: C11/Odin/Jai semantics in a Python runtime
6. conductor/code_styleguides/data_oriented_design.md §8.5 — the Python Type Promotion Mandate
7. conductor/code_styleguides/python.md §17 — the LLM Default Anti-Patterns (banned patterns)
8. conductor/code_styleguides/type_aliases.md — Metadata is the boundary type
9. conductor/code_styleguides/error_handling.md — Result[T] + NIL_T sentinels
10. The relevant docs/guide_*.md for the layers the track touches
11. conductor/tracks.md — check existing tracks for similar work (don't re-invent)

Protocol

1. Audit Before Specifying (MANDATORY): Before writing any spec, research the existing codebase:

   • Use py_get_code_outline on relevant files
   • Use py_get_definition on target classes
   • Use grep to find related patterns
   • Use get_git_diff to understand recent changes

   Document findings in a "Current State Audit" section.

2. Apply the Python Type Promotion Mandate (workflow.md §0):

   • NO dict[str, Any] outside the wire boundary
   • NO Any parameter, return, or field type
   • NO Optional[T] returns (use Result[T] + NIL_T sentinels)
   • NO hasattr() for entity type dispatch (use typed Union or per-entity function)
   • Direct field access on typed @dataclass(frozen=True, slots=True) instances

   If the track proposes lifting entities into dict[str, Any] or Any, REJECT the design and rewrite.

3. Generate Track ID: Format: {name}_{YYYYMMDD} Example: async_tool_execution_20260303

4. Create Track Directory: conductor/tracks/{track_id}/

5. Create spec.md:

   # Track Specification: {Title}
   
   ## Overview
   [One-paragraph description]
   
   ## Current State Audit (as of {commit_sha})
   ### Already Implemented (DO NOT re-implement)
   - [Existing feature with file:line reference]
   
   ### Gaps to Fill (This Track's Scope)
   - [What's missing that this track will address]
   
   ## Goals
   - [Specific, measurable goals]
   
   ## Functional Requirements
   - [Detailed requirements]
   
   ## Non-Functional Requirements
   - [Performance, security, etc.]
   
   ## Architecture Reference
   - docs/guide_architecture.md#section
   - docs/guide_tools.md#section
   - `conductor/code_styleguides/data_oriented_design.md` §8.5 (the Python Type Promotion Mandate)
   
   ## Out of Scope
   - [What this track will NOT do]
   

6. Create plan.md:

   # Implementation Plan: {Title}
   
   ## Phase 1: {Name}
   Focus: {One-sentence scope}
   
   - [ ] Task 1.1: {Surgical description with file:line refs}
   - [ ] Task 1.2: ...
   - [ ] Task 1.N: Write tests for Phase 1 changes
   - [ ] Task 1.X: Conductor - User Manual Verification
   
   ## Phase 2: {Name}
   ...
   

7. Create metadata.json:

   {
     "id": "{track_id}",
     "title": "{title}",
     "type": "feature|fix|refactor|docs",
     "status": "planned",
     "priority": "high|medium|low",
     "created": "{YYYY-MM-DD}",
     "depends_on": [],
     "blocks": []
   }
   

8. Update tracks.md: Add entry to conductor/tracks.md registry.

9. Report:

   ## Track Created
   
   **ID:** {track_id}
   **Location:** conductor/tracks/{track_id}/
   **Files Created:**
   - spec.md
   - plan.md
   - metadata.json
   
   **Next Steps:**
   1. Review spec.md for completeness
   2. Run `/conductor-implement` to begin execution
   

Surgical Methodology Checklist

• Audited existing code before writing spec
• Documented existing implementations with file:line refs
• Framed requirements as gaps, not features
• Tasks are worker-ready (WHERE/WHAT/HOW/SAFETY)
• Referenced architecture docs
• Mapped dependencies in metadata
• Applied the Python Type Promotion Mandate (workflow.md §0) — no dict[str, Any], no Any, no Optional[T], no hasattr() for entity dispatch