diff --git a/.opencode/commands/conductor-new-track.md b/.opencode/commands/conductor-new-track.md index 91617e90..3fd19d90 100644 --- a/.opencode/commands/conductor-new-track.md +++ b/.opencode/commands/conductor-new-track.md @@ -11,6 +11,24 @@ 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):** @@ -19,17 +37,26 @@ $ARGUMENTS - Track name and brief description - 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. **Generate Track ID:** +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` -3. **Create Track Directory:** +4. **Create Track Directory:** `conductor/tracks/{track_id}/` -4. **Create spec.md:** +5. **Create spec.md:** ```markdown # Track Specification: {Title} @@ -55,12 +82,13 @@ $ARGUMENTS - Track name and brief description ## 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] ``` -5. **Create plan.md:** +6. **Create plan.md:** ```markdown # Implementation Plan: {Title} @@ -76,7 +104,7 @@ $ARGUMENTS - Track name and brief description ... ``` -6. **Create metadata.json:** +7. **Create metadata.json:** ```json { "id": "{track_id}", @@ -90,10 +118,10 @@ $ARGUMENTS - Track name and brief description } ``` -7. **Update tracks.md:** +8. **Update tracks.md:** Add entry to `conductor/tracks.md` registry. -8. **Report:** +9. **Report:** ``` ## Track Created @@ -116,3 +144,4 @@ $ARGUMENTS - Track name and brief description - [ ] 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