docs(plan): directive hot-swap harness implementation plan
48 directives harvested from the entire doc tree into conductor/directives/ + baseline preset + 5 role-prompt 'warm with:' bootstrap updates. 3 phases: (1) directive harvest in 10 steps with exact source file:line refs, (2) preset + role-prompt updates, (3) verification + end-of-track report. Sources combed: AGENTS.md, workflow.md, product-guidelines.md, tech-stack.md, all 10 code_styleguides/*.md. Each v1.md is a verbatim lift with a source annotation header. No scripts, no TOML — markdown-only, LLM-native.
This commit is contained in:
@@ -0,0 +1,490 @@
|
||||
# Directive Hot-Swap Harness Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Build a directive hot-swap harness that lets the user maintain alternative encodings of the same directive as separate files, compose them into named presets (markdown bills of materials), and hot-swap which preset is active via a single `warm with: <path>` instruction in the role prompt or session message.
|
||||
|
||||
**Architecture:** A `conductor/directives/` directory tree where each directive is a subdirectory and each encoding variant is a file (`v1.md`, `v2_<style>.md`). Presets in `conductor/directives/presets/` are markdown files listing which variant files to read. The 5 tier role prompts are updated with a single `warm with: <preset_path>` line that replaces the hardcoded mandatory-reading list. No scripts, no TOML, no build steps — markdown-only, LLM-native.
|
||||
|
||||
**Tech Stack:** Markdown files. No code changes. No tests (this is a documentation/tooling track, not a code track). The "test" is: does an LLM follow the `warm with:` instruction and read the listed files?
|
||||
|
||||
**Spec:** `docs/superpowers/specs/2026-06-27-directive-hotswap-harness-design.md`
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
### New files (created by this plan)
|
||||
|
||||
```
|
||||
conductor/directives/
|
||||
ban_dict_any/v1.md
|
||||
ban_any_type/v1.md
|
||||
ban_optional_returns/v1.md
|
||||
ban_hasattr_dispatch/v1.md
|
||||
ban_getattr_dispatch/v1.md
|
||||
ban_dict_get_on_known_fields/v1.md
|
||||
ban_local_imports/v1.md
|
||||
ban_prefix_aliasing/v1.md
|
||||
ban_repeated_from_dict/v1.md
|
||||
boundary_layer_exception/v1.md
|
||||
result_error_pattern/v1.md
|
||||
nil_sentinel_pattern/v1.md
|
||||
typed_dataclass_fields/v1.md
|
||||
metadata_boundary_type/v1.md
|
||||
one_space_indent/v1.md
|
||||
no_comments_in_body/v1.md
|
||||
no_diagnostic_noise/v1.md
|
||||
type_hints_required/v1.md
|
||||
sdm_dependency_tags/v1.md
|
||||
file_naming_convention/v1.md
|
||||
no_new_src_files_without_permission/v1.md
|
||||
large_files_are_fine/v1.md
|
||||
atomic_per_task_commits/v1.md
|
||||
tdd_red_green_required/v1.md
|
||||
ban_arbitrary_core_mocking/v1.md
|
||||
live_gui_poll_not_sleep/v1.md
|
||||
batch_verification_not_isolation/v1.md
|
||||
git_hard_bans/v1.md
|
||||
ban_day_estimates/v1.md
|
||||
no_output_filtering/v1.md
|
||||
prefer_targeted_tier_runs/v1.md
|
||||
mandatory_research_first/v1.md
|
||||
no_skip_markers_as_avoidance/v1.md
|
||||
deduction_loop_limit/v1.md
|
||||
report_instead_of_fix_ban/v1.md
|
||||
scope_creep_track_doc_ban/v1.md
|
||||
inherited_cruft_ask_first/v1.md
|
||||
verbose_commit_message_ban/v1.md
|
||||
imgui_scope_verification/v1.md
|
||||
modular_controller_pattern/v1.md
|
||||
ui_delegation_for_hot_reload/v1.md
|
||||
strict_state_management/v1.md
|
||||
comprehensive_logging/v1.md
|
||||
feature_flag_delete_to_turn_off/v1.md
|
||||
rag_six_rules/v1.md
|
||||
cache_stable_to_volatile/v1.md
|
||||
knowledge_harvest_pattern/v1.md
|
||||
|
||||
presets/
|
||||
current_baseline.md
|
||||
```
|
||||
|
||||
### Modified files
|
||||
|
||||
```
|
||||
.opencode/agents/tier1-orchestrator.md (replace mandatory-reading list with warm with:)
|
||||
.opencode/agents/tier2-tech-lead.md (same)
|
||||
.opencode/agents/tier3-worker.md (same)
|
||||
.opencode/agents/tier4-qa.md (same)
|
||||
conductor/tier2/agents/tier2-autonomous.md (same)
|
||||
```
|
||||
|
||||
### NOT modified (the original docs stay untouched)
|
||||
|
||||
```
|
||||
AGENTS.md (stays as canonical source)
|
||||
conductor/workflow.md (stays as canonical source)
|
||||
conductor/product-guidelines.md (stays as canonical source)
|
||||
conductor/code_styleguides/*.md (all stay as canonical source)
|
||||
docs/*.md (all stay as canonical source)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Directive Harvest
|
||||
|
||||
Focus: Systematically comb the doc tree, extract every directive-like statement into a candidate list, resolve granularity (which to merge, split, keep standalone). This is the bulk of the work.
|
||||
|
||||
Each task creates one or more `conductor/directives/<name>/v1.md` files. The v1 content is a verbatim lift from the source doc (not a rewrite). The variant header annotates the source location and why this iteration exists.
|
||||
|
||||
- [ ] **Step 1.1: Harvest §17 banned patterns (7 directives)**
|
||||
|
||||
**Files to read:**
|
||||
- `conductor/code_styleguides/python.md:216-409` (§17 Banned Patterns — the 7 banned patterns + §17.7 boundary exception + §17.8 enforcement + §17.9 local imports + §17.10 enforcement inventory)
|
||||
|
||||
**Directives to create:**
|
||||
|
||||
1. `conductor/directives/ban_dict_any/v1.md` — source: `python.md:220-237` (§17.1). Content: the `dict[str, Any]` ban + before/after examples + the boundary exception cross-ref.
|
||||
2. `conductor/directives/ban_any_type/v1.md` — source: `python.md:239-250` (§17.2). Content: the `Any` ban + before/after.
|
||||
3. `conductor/directives/ban_optional_returns/v1.md` — source: `python.md:252-272` (§17.3). Content: the `Optional[T]` return ban + the `Result[T]` replacement pattern.
|
||||
4. `conductor/directives/ban_hasattr_dispatch/v1.md` — source: `python.md:274-299` (§17.4). Content: the `hasattr()` for entity type dispatch ban + the typed Union alternative.
|
||||
5. `conductor/directives/ban_getattr_dispatch/v1.md` — source: `python.md:301-311` (§17.5). Content: the `getattr(x, 'field', default)` for type dispatch ban.
|
||||
6. `conductor/directives/ban_dict_get_on_known_fields/v1.md` — source: `python.md:313-323` (§17.6). Content: the `.get('field', default)` on a `dict[str, Any]` ban + direct attribute access alternative.
|
||||
7. `conductor/directives/boundary_layer_exception/v1.md` — source: `python.md:325-327` (§17.7). Content: the ONE exception — the wire boundary (TOML/JSON parse) where `dict[str, Any]` is allowed.
|
||||
|
||||
**Variant header format** (use for ALL v1 files):
|
||||
```markdown
|
||||
# <directive_name> — v1
|
||||
|
||||
**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/python.md` §17.N (lines N-M).
|
||||
This is the baseline encoding — the style currently in production. Future variants
|
||||
will test alternative encodings (rationale-first, before/after, tabular) against this baseline.
|
||||
|
||||
**Source:** `conductor/code_styleguides/python.md:NNN-MMM`
|
||||
|
||||
---
|
||||
|
||||
<verbatim directive text from the source>
|
||||
```
|
||||
|
||||
- [ ] **Step 1.2: Harvest §17.9 import/aliasing bans (3 directives)**
|
||||
|
||||
**Files to read:**
|
||||
- `conductor/code_styleguides/python.md:336-409` (§17.9 local imports + aliasing + repeated from_dict)
|
||||
|
||||
**Directives to create:**
|
||||
|
||||
8. `conductor/directives/ban_local_imports/v1.md` — source: `python.md:336-360` (§17.9a). Content: local imports inside functions are banned + the `try/except ImportError` exception + the vendor-SDK-warmup whitelist.
|
||||
9. `conductor/directives/ban_prefix_aliasing/v1.md` — source: `python.md` (§17.9b, within the 336-409 range). Content: `import X as _X` aliasing-for-naming-convenience is banned.
|
||||
10. `conductor/directives/ban_repeated_from_dict/v1.md` — source: `python.md` (§17.9c, within the 336-409 range). Content: repeated `.from_dict()` calls in the same expression are banned.
|
||||
|
||||
- [ ] **Step 1.3: Harvest error handling conventions (2 directives)**
|
||||
|
||||
**Files to read:**
|
||||
- `conductor/code_styleguides/error_handling.md:22-56` (the 5 patterns) + `error_handling.md:212-242` (hard rules) + `error_handling.md:274-311` (boundary types)
|
||||
|
||||
**Directives to create:**
|
||||
|
||||
11. `conductor/directives/result_error_pattern/v1.md` — source: `error_handling.md:22-56, 212-242`. Content: the `Result[T]` dataclass pattern (data + errors list, not `Optional[T]` + exceptions). The 5 patterns (nil-sentinel, zero-init, fail-early, AND over OR, error-info as side-channel). The hard rules (`Optional[T]` returns forbidden in baseline files; `Result[T]` for any function that can fail).
|
||||
12. `conductor/directives/nil_sentinel_pattern/v1.md` — source: `error_handling.md:24-47` (Pattern 1 — Nil-Sentinel Dataclasses). Content: the `NIL_T` singleton pattern replacing `None`. The sentinel type contract.
|
||||
|
||||
- [ ] **Step 1.4: Harvest type/data-structure conventions (3 directives)**
|
||||
|
||||
**Files to read:**
|
||||
- `conductor/code_styleguides/data_oriented_design.md:176-215` (§8.5 Python Type Promotion Mandate + §8.6 Boundary Layer + §8.7 C11 framing)
|
||||
- `conductor/code_styleguides/type_aliases.md:40-81` (Metadata boundary type + when to promote + when NOT to promote)
|
||||
|
||||
**Directives to create:**
|
||||
|
||||
13. `conductor/directives/typed_dataclass_fields/v1.md` — source: `data_oriented_design.md:176-199` (§8.5). Content: the Python Type Promotion Mandate — use typed `@dataclass(frozen=True, slots=True)` with explicit fields. The 7 banned patterns table.
|
||||
14. `conductor/directives/metadata_boundary_type/v1.md` — source: `type_aliases.md:40-81` + `data_oriented_design.md:200-215` (§8.6). Content: `Metadata` is the typed fat struct at the wire boundary, NOT `TypeAlias = dict[str, Any]`. The boundary is 2-3 functions per file. When to promote to per-aggregate dataclass vs. when to keep as collapsed codepath.
|
||||
15. `conductor/directives/boundary_layer_exception/v1.md` — UPDATE the file created in Step 1.1 to also include the `data_oriented_design.md:200-215` (§8.6) and `type_aliases.md` boundary-layer content. This directive cross-references §17.7 (the exception) + §8.6 (the boundary definition) + type_aliases.md (the Metadata-as-boundary-type rule).
|
||||
|
||||
- [ ] **Step 1.5: Harvest code style directives (5 directives)**
|
||||
|
||||
**Files to read:**
|
||||
- `conductor/code_styleguides/python.md:7-21` (§1 Indentation + §2 Type Annotations)
|
||||
- `conductor/code_styleguides/python.md:64-71` (§8 AI-Agent Specific Conventions — no comments, no diagnostic noise)
|
||||
- `conductor/code_styleguides/python.md:185-199` (§13 Vertical Compaction)
|
||||
- `conductor/code_styleguides/python.md:175-184` (§12 SDM)
|
||||
- `conductor/workflow.md:5-20` (Code Style section)
|
||||
|
||||
**Directives to create:**
|
||||
|
||||
16. `conductor/directives/one_space_indent/v1.md` — source: `python.md:7-20` + `workflow.md:7`. Content: 1-space indentation for ALL Python code. CRLF line endings on Windows. No comments unless explicitly requested.
|
||||
17. `conductor/directives/no_comments_in_body/v1.md` — source: `python.md:66` + `AGENTS.md:56`. Content: no comments in source code; documentation lives in `/docs`. Only comment on *why* when non-obvious.
|
||||
18. `conductor/directives/no_diagnostic_noise/v1.md` — source: `python.md:70` + `AGENTS.md` "No Diagnostic Noise in Production" section. Content: no `sys.stderr.write("[XYZ_DIAG] ...")` in production code. Diag goes to log files or temp scripts.
|
||||
19. `conductor/directives/type_hints_required/v1.md` — source: `python.md:24-31` + `product-guidelines.md:58`. Content: mandatory strict type hints for all parameters, return types, and global variables.
|
||||
20. `conductor/directives/sdm_dependency_tags/v1.md` — source: `python.md:175-184` (§12) + `product-guidelines.md:59`. Content: Structural Dependency Mapping tags (`[C: ...]`, `[M: ...]`, `[U: ...]`) in docstrings for AI-assisted impact analysis.
|
||||
|
||||
- [ ] **Step 1.6: Harvest file/taxonomy conventions (3 directives)**
|
||||
|
||||
**Files to read:**
|
||||
- `AGENTS.md:62-76` (File Size and Naming Convention HARD RULE)
|
||||
- `conductor/workflow.md:45` (File Naming Convention HARD RULE)
|
||||
- `conductor/code_styleguides/python.md:205-215` (§15 Modular Controller Pattern)
|
||||
|
||||
**Directives to create:**
|
||||
|
||||
21. `conductor/directives/file_naming_convention/v1.md` — source: `AGENTS.md:62-76` + `workflow.md:45`. Content: new `src/<thing>.py` files may only be created on the user's explicit request. Helpers go in the parent module. Large files are FINE.
|
||||
22. `conductor/directives/no_new_src_files_without_permission/v1.md` — source: `AGENTS.md:68-76`. Content: the audit trigger — "is `<thing>` a new system, or is it part of an existing system?" If it's part of an existing system, the file goes in that system's file.
|
||||
23. `conductor/directives/large_files_are_fine/v1.md` — source: `AGENTS.md:62-67`. Content: large files are FINE. The "small files are good" stance is propaganda from LLM training data. Cognitive load is managed via naming, regions, and navigation tools — NOT via file splitting.
|
||||
|
||||
- [ ] **Step 1.7: Harvest process/workflow directives (10 directives)**
|
||||
|
||||
**Files to read:**
|
||||
- `conductor/workflow.md:80-120` (Standard Task Workflow — TDD, atomic commits, delegate)
|
||||
- `conductor/workflow.md:112-170` (Phase Completion Verification + API Hooks verification)
|
||||
- `conductor/workflow.md:262-280` (Structural Testing Contract)
|
||||
- `AGENTS.md:49-85` (Critical Anti-Patterns)
|
||||
- `AGENTS.md:86-118` (Session-Learned Anti-Patterns)
|
||||
- `AGENTS.md:119-185` (Process Anti-Patterns)
|
||||
- `conductor/workflow.md:385-391` (Tier 2 conventions — the 2 new rules)
|
||||
|
||||
**Directives to create:**
|
||||
|
||||
24. `conductor/directives/atomic_per_task_commits/v1.md` — source: `workflow.md:112` + `AGENTS.md:55`. Content: commit per-task for atomic rollback. Do NOT batch commits.
|
||||
25. `conductor/directives/tdd_red_green_required/v1.md` — source: `workflow.md:78-100` (Standard Task Workflow steps 4-6). Content: write failing tests before implementing. Run tests, confirm they fail (Red). Implement, run, confirm pass (Green). The Zero-Assertion Ban (tests must have meaningful assertions).
|
||||
26. `conductor/directives/ban_arbitrary_core_mocking/v1.md` — source: `workflow.md:262`. Content: ban on `unittest.mock.patch` to bypass core infrastructure unless explicitly authorized.
|
||||
27. `conductor/directives/live_gui_poll_not_sleep/v1.md` — source: `workflow.md:465-475` (Anti-Pattern: push_event + time.sleep + assert). Content: replace `time.sleep(N)` with a poll loop on `get_value` or `wait_for_event`.
|
||||
28. `conductor/directives/batch_verification_not_isolation/v1.md` — source: `workflow.md:510-514` (Isolated-Pass Verification Fallacy). Content: the only verification that matters for `live_gui` tests is the batch run. Do NOT commit a fix verified only in isolation.
|
||||
29. `conductor/directives/git_hard_bans/v1.md` — source: `AGENTS.md:59` + `workflow.md:417-430`. Content: `git restore`, `git checkout -- <file>`, `git reset` are FORBIDDEN without explicit user permission. Use `git show` for inspection, not `git checkout`.
|
||||
30. `conductor/directives/ban_day_estimates/v1.md` — source: `AGENTS.md:60`. Content: no day/hour/minute estimates in track artifacts. Measure effort by scope (N files, M sites, N tasks).
|
||||
31. `conductor/directives/no_output_filtering/v1.md` — source: `workflow.md:386`. Content: NEVER filter test output through `Select-Object`, `head`, `tail`. Always redirect to a log file.
|
||||
32. `conductor/directives/prefer_targeted_tier_runs/v1.md` — source: `workflow.md:387`. Content: do NOT run the full 11-tier batch for every verification. Run targeted tiers.
|
||||
33. `conductor/directives/mandatory_research_first/v1.md` — source: `workflow.md:46`. Content: before reading any file >50 lines, use `get_file_summary`/`py_get_skeleton`/`py_get_code_outline` to map the structure first.
|
||||
|
||||
- [ ] **Step 1.8: Harvest process anti-patterns (6 directives)**
|
||||
|
||||
**Files to read:**
|
||||
- `AGENTS.md:119-185` (Process Anti-Patterns — the 8 named patterns)
|
||||
- `conductor/workflow.md` "Skip-Marker Policy" section
|
||||
|
||||
**Directives to create:**
|
||||
|
||||
34. `conductor/directives/no_skip_markers_as_avoidance/v1.md` — source: `workflow.md` "Skip-Marker Policy" + `AGENTS.md:54`. Content: `@pytest.mark.skip` is documentation of a known failure, not an escape from fixing the bug. Fix in-session when feasible.
|
||||
35. `conductor/directives/deduction_loop_limit/v1.md` — source: `AGENTS.md:127` (Process Anti-Pattern #1). Content: at most 2 test runs in a single investigation. After the 2nd failure, STOP and read the code.
|
||||
36. `conductor/directives/report_instead_of_fix_ban/v1.md` — source: `AGENTS.md:134` (Process Anti-Pattern #2). Content: a 200-line status report is a confession, not a fix. A good status report is 5-10 sentences.
|
||||
37. `conductor/directives/scope_creep_track_doc_ban/v1.md` — source: `AGENTS.md:143` (Process Anti-Pattern #3). Content: if the user asks for a fix, your output is the fix. A track doc is only for multi-day work.
|
||||
38. `conductor/directives/inherited_cruft_ask_first/v1.md` — source: `AGENTS.md:149` (Process Anti-Pattern #4). Content: if a file is broken from a previous session, ASK the user before trying to fix it.
|
||||
39. `conductor/directives/verbose_commit_message_ban/v1.md` — source: `AGENTS.md:176` (Process Anti-Pattern #7). Content: a commit message is 1-3 sentences. If it's longer than 15 lines, it's a report.
|
||||
|
||||
- [ ] **Step 1.9: Harvest GUI/architecture directives (5 directives)**
|
||||
|
||||
**Files to read:**
|
||||
- `conductor/product-guidelines.md:29-43` (UX & UI Principles + Code Standards)
|
||||
- `conductor/workflow.md:39` (ImGui Verification)
|
||||
|
||||
**Directives to create:**
|
||||
|
||||
40. `conductor/directives/imgui_scope_verification/v1.md` — source: `product-guidelines.md:39` + `workflow.md:39`. Content: all changes to `gui_2.py` MUST be verified using `scripts/check_imgui_scopes.py`. Use `imscope` context managers over manual push/pop.
|
||||
41. `conductor/directives/modular_controller_pattern/v1.md` — source: `product-guidelines.md:40`. Content: state-independent logic must be moved to module-level functions. Massive `if/elif` dispatch blocks must be refactored into handler maps.
|
||||
42. `conductor/directives/ui_delegation_for_hot_reload/v1.md` — source: `product-guidelines.md:41`. Content: all complex ImGui rendering logic must be extracted from the `App` class into module-level `render_xxx(app)` functions. The `App` class should only contain thin delegation wrappers.
|
||||
43. `conductor/directives/strict_state_management/v1.md` — source: `product-guidelines.md:37`. Content: rigorous separation between the Main GUI rendering thread and daemon execution threads. The UI should NEVER hang during AI communication. Use lock-protected queues and events.
|
||||
44. `conductor/directives/comprehensive_logging/v1.md` — source: `product-guidelines.md:38`. Content: aggressively log all actions, API payloads, tool calls, and executed scripts. Maintain timestamped JSON-L and markdown logs.
|
||||
|
||||
- [ ] **Step 1.10: Harvest feature-flag + RAG + cache + knowledge directives (4 directives)**
|
||||
|
||||
**Files to read:**
|
||||
- `conductor/code_styleguides/feature_flags.md`
|
||||
- `conductor/code_styleguides/rag_integration_discipline.md:11-20` (the 6 rules)
|
||||
- `conductor/code_styleguides/cache_friendly_context.md:52-74` (the byte-comparison test)
|
||||
- `conductor/code_styleguides/knowledge_artifacts.md`
|
||||
|
||||
**Directives to create:**
|
||||
|
||||
45. `conductor/directives/feature_flag_delete_to_turn_off/v1.md` — source: `feature_flags.md`. Content: file presence ("delete to turn off") for side artifacts; config flags for persistent preferences; CLI flags for one-shot overrides.
|
||||
46. `conductor/directives/rag_six_rules/v1.md` — source: `rag_integration_discipline.md:11-20`. Content: the 6 rules (opt-in, complements, provenance, no mutation, feature-gated, graceful failure).
|
||||
47. `conductor/directives/cache_stable_to_volatile/v1.md` — source: `cache_friendly_context.md:52-74`. Content: stable-to-volatile context ordering. The byte-comparison test. Layers 1-7 cacheable, 8-12 not.
|
||||
48. `conductor/directives/knowledge_harvest_pattern/v1.md` — source: `knowledge_artifacts.md`. Content: the category files + provenance + sha256 ledger + digest regeneration pattern.
|
||||
|
||||
- [ ] **Step 1.11: Commit the directive harvest**
|
||||
|
||||
```bash
|
||||
git add conductor/directives/
|
||||
git commit -m "feat(directives): harvest 48 directives from doc tree into conductor/directives/
|
||||
|
||||
Systematic extraction of every directive-like statement (imperative,
|
||||
preference, hard ban, convention, anti-pattern) from the entire doc tree
|
||||
into conductor/directives/<name>/v1.md files. Each v1 is a verbatim lift
|
||||
from the source doc with a header annotating the source location.
|
||||
|
||||
Sources combed: AGENTS.md, conductor/workflow.md, conductor/product-guidelines.md,
|
||||
conductor/tech-stack.md, all 10 conductor/code_styleguides/*.md, docs/AGENTS.md.
|
||||
|
||||
Original docs remain untouched as canonical source. The conductor/directives/
|
||||
tree is a parallel structure, not a replacement."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Baseline Preset + Role-Prompt Bootstrap
|
||||
|
||||
Focus: Create the `current_baseline.md` preset that lists all 48 directives, then update the 5 role prompts with the `warm with:` bootstrap.
|
||||
|
||||
- [ ] **Step 2.1: Create the baseline preset**
|
||||
|
||||
**File:** `conductor/directives/presets/current_baseline.md`
|
||||
|
||||
**Content:**
|
||||
|
||||
```markdown
|
||||
# Preset: current_baseline
|
||||
|
||||
The baseline directive composition — all v1 variants lifted verbatim from the
|
||||
current production docs. This is the starting point; alternative presets swap
|
||||
variants to test different encodings.
|
||||
|
||||
## Directives to warm
|
||||
|
||||
Read each file below before any action.
|
||||
|
||||
- ban_dict_any: conductor/directives/ban_dict_any/v1.md
|
||||
- ban_any_type: conductor/directives/ban_any_type/v1.md
|
||||
- ban_optional_returns: conductor/directives/ban_optional_returns/v1.md
|
||||
- ban_hasattr_dispatch: conductor/directives/ban_hasattr_dispatch/v1.md
|
||||
- ban_getattr_dispatch: conductor/directives/ban_getattr_dispatch/v1.md
|
||||
- ban_dict_get_on_known_fields: conductor/directives/ban_dict_get_on_known_fields/v1.md
|
||||
- boundary_layer_exception: conductor/directives/boundary_layer_exception/v1.md
|
||||
- ban_local_imports: conductor/directives/ban_local_imports/v1.md
|
||||
- ban_prefix_aliasing: conductor/directives/ban_prefix_aliasing/v1.md
|
||||
- ban_repeated_from_dict: conductor/directives/ban_repeated_from_dict/v1.md
|
||||
- result_error_pattern: conductor/directives/result_error_pattern/v1.md
|
||||
- nil_sentinel_pattern: conductor/directives/nil_sentinel_pattern/v1.md
|
||||
- typed_dataclass_fields: conductor/directives/typed_dataclass_fields/v1.md
|
||||
- metadata_boundary_type: conductor/directives/metadata_boundary_type/v1.md
|
||||
- one_space_indent: conductor/directives/one_space_indent/v1.md
|
||||
- no_comments_in_body: conductor/directives/no_comments_in_body/v1.md
|
||||
- no_diagnostic_noise: conductor/directives/no_diagnostic_noise/v1.md
|
||||
- type_hints_required: conductor/directives/type_hints_required/v1.md
|
||||
- sdm_dependency_tags: conductor/directives/sdm_dependency_tags/v1.md
|
||||
- file_naming_convention: conductor/directives/file_naming_convention/v1.md
|
||||
- no_new_src_files_without_permission: conductor/directives/no_new_src_files_without_permission/v1.md
|
||||
- large_files_are_fine: conductor/directives/large_files_are_fine/v1.md
|
||||
- atomic_per_task_commits: conductor/directives/atomic_per_task_commits/v1.md
|
||||
- tdd_red_green_required: conductor/directives/tdd_red_green_required/v1.md
|
||||
- ban_arbitrary_core_mocking: conductor/directives/ban_arbitrary_core_mocking/v1.md
|
||||
- live_gui_poll_not_sleep: conductor/directives/live_gui_poll_not_sleep/v1.md
|
||||
- batch_verification_not_isolation: conductor/directives/batch_verification_not_isolation/v1.md
|
||||
- git_hard_bans: conductor/directives/git_hard_bans/v1.md
|
||||
- ban_day_estimates: conductor/directives/ban_day_estimates/v1.md
|
||||
- no_output_filtering: conductor/directives/no_output_filtering/v1.md
|
||||
- prefer_targeted_tier_runs: conductor/directives/prefer_targeted_tier_runs/v1.md
|
||||
- mandatory_research_first: conductor/directives/mandatory_research_first/v1.md
|
||||
- no_skip_markers_as_avoidance: conductor/directives/no_skip_markers_as_avoidance/v1.md
|
||||
- deduction_loop_limit: conductor/directives/deduction_loop_limit/v1.md
|
||||
- report_instead_of_fix_ban: conductor/directives/report_instead_of_fix_ban/v1.md
|
||||
- scope_creep_track_doc_ban: conductor/directives/scope_creep_track_doc_ban/v1.md
|
||||
- inherited_cruft_ask_first: conductor/directives/inherited_cruft_ask_first/v1.md
|
||||
- verbose_commit_message_ban: conductor/directives/verbose_commit_message_ban/v1.md
|
||||
- imgui_scope_verification: conductor/directives/imgui_scope_verification/v1.md
|
||||
- modular_controller_pattern: conductor/directives/modular_controller_pattern/v1.md
|
||||
- ui_delegation_for_hot_reload: conductor/directives/ui_delegation_for_hot_reload/v1.md
|
||||
- strict_state_management: conductor/directives/strict_state_management/v1.md
|
||||
- comprehensive_logging: conductor/directives/comprehensive_logging/v1.md
|
||||
- feature_flag_delete_to_turn_off: conductor/directives/feature_flag_delete_to_turn_off/v1.md
|
||||
- rag_six_rules: conductor/directives/rag_six_rules/v1.md
|
||||
- cache_stable_to_volatile: conductor/directives/cache_stable_to_volatile/v1.md
|
||||
- knowledge_harvest_pattern: conductor/directives/knowledge_harvest_pattern/v1.md
|
||||
|
||||
## Notes
|
||||
|
||||
All v1 (verbatim lifts from current production docs). No alternative encodings
|
||||
tested yet. This preset is the control group for future experiments.
|
||||
|
||||
To create an experimental preset: copy this file, change the variant path for
|
||||
the directives you want to test (e.g., swap `v1.md` for `v2_rationale_first.md`),
|
||||
and update the Notes section with your hypothesis.
|
||||
```
|
||||
|
||||
- [ ] **Step 2.2: Commit the preset**
|
||||
|
||||
```bash
|
||||
git add conductor/directives/presets/current_baseline.md
|
||||
git commit -m "feat(directives): add current_baseline preset (48 directives, all v1)"
|
||||
```
|
||||
|
||||
- [ ] **Step 2.3: Update tier1-orchestrator.md with warm with: bootstrap**
|
||||
|
||||
**File:** `.opencode/agents/tier1-orchestrator.md`
|
||||
|
||||
**What to change:** Find the "MANDATORY: Pre-Action Required Reading" section (or equivalent hardcoded file list). Replace the directive-reading portion with:
|
||||
|
||||
```markdown
|
||||
## MANDATORY: Directive Warm-up
|
||||
|
||||
warm with: conductor/directives/presets/current_baseline.md
|
||||
|
||||
Read the preset file above. It lists directive variant files to read before any action.
|
||||
Read each file the preset references. These are your active directives for this session.
|
||||
|
||||
If the user specifies a different preset (e.g., "warm with: conductor/directives/presets/exploratory_rationale.md"),
|
||||
use that instead. The user's instruction overrides the default.
|
||||
```
|
||||
|
||||
**What stays (non-directive reads that remain hardcoded):**
|
||||
- `AGENTS.md` — project operating rules
|
||||
- `conductor/workflow.md` — operational workflow
|
||||
- `conductor/edit_workflow.md` — edit tool contract
|
||||
- The relevant `docs/guide_*.md` — architecture reference
|
||||
|
||||
- [ ] **Step 2.4: Update tier2-tech-lead.md with warm with: bootstrap**
|
||||
|
||||
**File:** `.opencode/agents/tier2-tech-lead.md`
|
||||
|
||||
Same change as Step 2.3. The non-directive reads that stay hardcoded:
|
||||
- `AGENTS.md`
|
||||
- `conductor/workflow.md`
|
||||
- `conductor/edit_workflow.md`
|
||||
- `conductor/tier2/githooks/forbidden-files.txt`
|
||||
- The relevant `docs/guide_*.md`
|
||||
|
||||
- [ ] **Step 2.5: Update tier3-worker.md with warm with: bootstrap**
|
||||
|
||||
**File:** `.opencode/agents/tier3-worker.md`
|
||||
|
||||
Same change. Note: Tier 3 may benefit from a reduced preset (fewer directives — they don't need the planning/strategy directives). But for now, use `current_baseline.md` and let the user create a `worker_minimal.md` preset later.
|
||||
|
||||
- [ ] **Step 2.6: Update tier4-qa.md with warm with: bootstrap**
|
||||
|
||||
**File:** `.opencode/agents/tier4-qa.md`
|
||||
|
||||
Same change. Tier 4 reads narrowly; the preset can be customized later.
|
||||
|
||||
- [ ] **Step 2.7: Update tier2-autonomous.md with warm with: bootstrap**
|
||||
|
||||
**File:** `conductor/tier2/agents/tier2-autonomous.md`
|
||||
|
||||
This file has the most extensive hardcoded reading list (11 files, lines 32-52). Replace the directive-reading portion with the `warm with:` bootstrap. The non-directive reads that stay:
|
||||
- `AGENTS.md`
|
||||
- `conductor/workflow.md`
|
||||
- `conductor/edit_workflow.md`
|
||||
- `conductor/tier2/githooks/forbidden-files.txt`
|
||||
- `conductor/tracks/tier2_leak_prevention_20260620/spec.md` (this is a track spec, not a directive — stays hardcoded)
|
||||
|
||||
- [ ] **Step 2.8: Commit the role-prompt updates**
|
||||
|
||||
```bash
|
||||
git add .opencode/agents/tier1-orchestrator.md .opencode/agents/tier2-tech-lead.md .opencode/agents/tier3-worker.md .opencode/agents/tier4-qa.md conductor/tier2/agents/tier2-autonomous.md
|
||||
git commit -m "feat(role-prompts): replace hardcoded directive lists with warm with: bootstrap
|
||||
|
||||
All 5 tier role prompts now use 'warm with: conductor/directives/presets/current_baseline.md'
|
||||
instead of a hardcoded list of ~11 files. The LLM reads the preset, then reads
|
||||
the variant files it lists. Non-directive reads (AGENTS.md, workflow.md,
|
||||
edit_workflow.md, forbidden-files.txt, guide_*.md) remain hardcoded.
|
||||
|
||||
The user can override the preset per-session by saying 'warm with: <path>' in
|
||||
their session message. This is the hot-swap mechanism."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Verification + End-of-Track
|
||||
|
||||
- [ ] **Step 3.1: Verify the directory structure**
|
||||
|
||||
```bash
|
||||
# Count directive directories
|
||||
ls conductor/directives/ | wc -l
|
||||
|
||||
# Count v1.md files
|
||||
find conductor/directives/ -name "v1.md" | wc -l
|
||||
|
||||
# Verify preset exists
|
||||
test -f conductor/directives/presets/current_baseline.md
|
||||
|
||||
# Verify all 5 role prompts have the warm with: line
|
||||
grep -l "warm with:" .opencode/agents/tier1-orchestrator.md .opencode/agents/tier2-tech-lead.md .opencode/agents/tier3-worker.md .opencode/agents/tier4-qa.md conductor/tier2/agents/tier2-autonomous.md
|
||||
```
|
||||
|
||||
Expected: 48 directive directories, 48 v1.md files, preset exists, 5 role prompts have `warm with:`.
|
||||
|
||||
- [ ] **Step 3.2: Manual verification — does the LLM follow the warm with: instruction?**
|
||||
|
||||
Start a new OpenCode session with any tier role. Observe whether the LLM:
|
||||
1. Reads the preset file at `conductor/directives/presets/current_baseline.md`
|
||||
2. Reads each variant file listed in the preset
|
||||
3. Has the directives in context for the session
|
||||
|
||||
This is the "test" — there's no automated test for this. The signal is: does the LLM behave as if it has read the directives?
|
||||
|
||||
- [ ] **Step 3.3: Write end-of-track report**
|
||||
|
||||
**File:** `docs/reports/TRACK_COMPLETION_directive_hotswap_harness_20260627.md`
|
||||
|
||||
Document:
|
||||
- What shipped (48 directives + baseline preset + 5 role-prompt updates)
|
||||
- The directory structure
|
||||
- The preset format
|
||||
- The `warm with:` bootstrap
|
||||
- How to hot-swap (create a new preset or tell the LLM "warm with: <path>")
|
||||
- What's NOT included (no scripts, no TOML, no v2+ variants yet)
|
||||
- Handoff to future tracks (alternative encoding authoring, Manual Slop integration, token-cost analysis)
|
||||
|
||||
- [ ] **Step 3.4: Commit the end-of-track report**
|
||||
|
||||
```bash
|
||||
git add docs/reports/TRACK_COMPLETION_directive_hotswap_harness_20260627.md
|
||||
git commit -m "docs(reports): TRACK_COMPLETION_directive_hotswap_harness_20260627"
|
||||
```
|
||||
Reference in New Issue
Block a user