ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

conductor(track): init directive_hotswap_harness_20260627 + move spec/plan from docs/superpowers/ to conductor/tracks/

Browse Source 
Spec + plan + metadata + state for the directive hot-swap harness.
Harvests 48 directives from the entire doc tree into conductor/directives/
+ baseline preset + 5 role-prompt 'warm with:' bootstrap updates. No scripts,
no TOML — markdown-only, LLM-native.

Track 1 of Campaign A (Directive Encoding). Sibling campaign B (4-video
analysis) is a separate future track.
This commit is contained in:
ed
2026-06-27 13:54:02 -04:00
parent acb0d62a1d
commit 03c7cfd510
4 changed files with 176 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/plans/2026-06-27-directive-hotswap-harness.md
-490
View File
@@ -1,490 +0,0 @@
# 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"
```
docs/superpowers/specs/2026-06-27-directive-hotswap-harness-design.md
-230
View File
@@ -1,230 +0,0 @@
# Design: Directive Hot-Swap Harness (OpenCode Directive Presets)
**Date:** 2026-06-27
**Status:** Draft — pending user review
**Track ID (proposed):** `directive_hotswap_harness_20260627`
## Problem
The codebase's directives — the instructions that tell LLMs how to behave (banned patterns, conventions, hard bans, anti-patterns) — are scattered across the entire doc tree: `AGENTS.md`, `conductor/workflow.md`, `conductor/product-guidelines.md`, `conductor/tech-stack.md`, every `conductor/code_styleguides/*.md`, `docs/Readme.md`, `docs/AGENTS.md`, all 14 `docs/guide_*.md`, etc. They're embedded in prose, tables, anti-pattern sections, "Critical Anti-Patterns" lists, "Hard Rules," styleguide sections.
The 4 tier role prompts (`.opencode/agents/tier1-orchestrator.md`, `tier2-tech-lead.md`, `tier3-worker.md`, `tier4-qa.md`) plus the autonomous variant (`conductor/tier2/agents/tier2-autonomous.md`) currently hardcode a list of ~11 files to read before any action. This list is static — every session gets the same directives regardless of the task. There's no mechanism to:
- Test whether an alternative encoding of the same directive (imperative-ban vs. rationale-first vs. before/after) produces better LLM compliance
- Hot-swap which encoding is active without manually editing files or navigating the filesystem
- Exercise per-session control over which directives the LLM warms up with
## Goal
Build a **directive hot-swap harness** that lets the user:
1. Maintain multiple alternative encodings ("variants") of the same directive as separate files
2. Compose active directive sets into named "presets" (markdown bills of materials)
3. Hot-swap which preset is active via a single `warm with: <path>` instruction in the role prompt or session message
4. Use the existing file-reading behavior LLMs already have — no scripts, no TOML, no build steps
## Design
### The directive directory structure
```
conductor/directives/
<directive_name>/
v1.md ← the baseline encoding (verbatim lift from current docs)
v2_<style>.md ← alternative encodings (added over time)
presets/
current_baseline.md ← the default preset (all v1)
<experimental>.md ← alternative presets (added over time)
```
**Naming convention:** lowercase, underscore-separated, action-oriented (`ban_dict_any`, not `dict_str_any_ban`). The name describes the directive's intent.
**Variant file format:** each `vN.md` has a short header annotating why this iteration exists, then the directive text:
```markdown
# <directive_name> — v1
**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/python.md` §17.1.
This is the baseline encoding — the imperative-ban style currently in production.
Future variants will test alternative encodings against this baseline.
---
<directive text>
```
### The preset format
A preset is a markdown bill of materials. It tells the LLM which directive variant files to read for this run. Nothing more.
```markdown
# Preset: current_baseline
The baseline directive composition — all v1 variants lifted from the current
production docs.
## Directives to warm
Read each file below before any action.
- ban_dict_any: conductor/directives/ban_dict_any/v1.md
- ban_optional_returns: conductor/directives/ban_optional_returns/v1.md
- no_local_imports: conductor/directives/no_local_imports/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.
```
**Key properties:**
- **Flat list.** No nesting, no conditionals, no includes. The LLM reads the list, reads the files.
- **Human-readable name.** `current_baseline`, `exploratory_rationale`, `minimal_tokens` — pick by name.
- **Notes section.** Documents the hypothesis being tested. This is the experiment log, inline with the preset.
- **Partial swaps.** Swap 2-3 directives to v2, leave the rest at v1. The preset makes the diff explicit.
- **No script needed.** Author a new preset by copying an existing one and changing variant paths. Hot-swap by telling the LLM which preset to use.
### The role-prompt bootstrap
The 5 role prompts (`.opencode/agents/tier1-orchestrator.md`, `tier2-tech-lead.md`, `tier3-worker.md`, `tier4-qa.md`, and `conductor/tier2/agents/tier2-autonomous.md`) have a hardcoded "MANDATORY: Pre-Action Required Reading" section listing ~11 specific files. This is replaced with a single `warm with:` directive.
```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.
```
**Key properties:**
- **One line is the bootstrap.** `warm with: <path>` is the entire mechanism.
- **User override.** The user can tell the LLM "warm with: <path>" in their session message and it uses that preset instead of the default. This is the hot-swap — no file editing, just a text instruction.
- **Per-role defaults.** Each tier role prompt can default to a different preset.
- **Non-directive reads remain hardcoded.** Files that aren't tunable directives (e.g., `conductor/tracks/tier2_leak_prevention_20260620/spec.md`, `conductor/tier2/githooks/forbidden-files.txt`) stay as direct references in the role prompt.
### What stays in the role prompt (not directive-based)
- `AGENTS.md` — project operating rules (contains directives AND non-directive rules)
- `conductor/workflow.md` — operational workflow
- `conductor/edit_workflow.md` — edit tool contract
- `conductor/tier2/githooks/forbidden-files.txt` — file denylist
- The relevant `docs/guide_*.md` — architecture reference
These are context, not tunable directives. They stay hardcoded in the role prompt.
### The directive harvest
The directives are NOT limited to the 11 files the role prompts mandate. They're scattered across the entire doc tree. The track's first phase is a systematic harvest:
**A directive is any statement that tells the LLM:**
- "Do X" / "Don't do X" (imperative)
- "Use Y instead of Z" (preference)
- "This is BANNED" (hard ban)
- "Follow pattern P" (convention)
- "Never do Q" (anti-pattern)
**NOT a directive:**
- Descriptive prose ("The App class holds GUI state")
- Architecture documentation ("Thread domains are separated by...")
- Reference material ("The 45-tool inventory includes...")
**Sources to comb (non-exhaustive):**
- `AGENTS.md` — "Critical Anti-Patterns", "File Size and Naming Convention", "Session-Learned Anti-Patterns", "Process Anti-Patterns"
- `conductor/workflow.md` — "Code Style", "Guiding Principles", "Testing Requirements", "Known Pitfalls", "Process Anti-Patterns", "Tier 2 Autonomous Sandbox conventions"
- `conductor/product-guidelines.md` — "Core Value", "Code Standards & Architecture", "Data-Oriented Error Handling", "Phase 5: Heavy Curation"
- `conductor/tech-stack.md` — "Core Value" header
- `conductor/code_styleguides/data_oriented_design.md` — §8.5 "Python Type Promotion Mandate", the 7-question simplification pass, the 10-question self-check
- `conductor/code_styleguides/python.md` — §10 "Anti-OOP Conventions", §17 "LLM Default Anti-Patterns" (the 7 banned patterns)
- `conductor/code_styleguides/error_handling.md` — the Result[T] convention, the AI Agent Checklist
- `conductor/code_styleguides/type_aliases.md` — "When NOT to promote"
- `conductor/code_styleguides/feature_flags.md` — "delete to turn off" convention
- `conductor/code_styleguides/agent_memory_dimensions.md` — the 4-dimension decision tree
- `conductor/code_styleguides/rag_integration_discipline.md` — "conservative-RAG rule"
- `conductor/code_styleguides/cache_friendly_context.md` — stable-to-volatile ordering
- `conductor/code_styleguides/knowledge_artifacts.md` — the harvest pattern
- `docs/AGENTS.md` — "Convention Enforcement"
- `docs/Readme.md` — any directive-like content in feature descriptions
**Granularity resolution:** the harvest produces a candidate list. Then the question of which directives to merge (e.g., `ban_prefix_aliasing` + `no_local_imports` might become `import_hygiene`), split, or keep standalone is resolved in the harvest phase — not locked in upfront.
### The original docs stay untouched
The `conductor/directives/` tree is a *parallel* structure, not a replacement. The original docs (`python.md`, `error_handling.md`, `AGENTS.md`, etc.) remain the canonical source until a future track deprecates them. The harness is useful immediately (the v1 variants are exact copies); the old docs are not broken.
### Why no scripts / TOML
The user explicitly rejected TOML manifests and scripts for this initial version: "no need to systematize that hard when I don't know what's going to work yet." The preset is markdown. The hot-swap is a text instruction. The variant selection is a path in a markdown file. No build steps, no generated files, no tooling dependencies. If the system proves useful, a future track can add automation (auto-generating presets from the directory tree, token-cost analysis per variant, automated compliance testing).
## Scope: Two Parallel Campaigns
The user's request bundles two distinct campaigns that share a theme ("how do you encode information densely for an LLM?") but are tracked and executed independently.
### Campaign A: Directive Hot-Swap Harness (this spec)
**Track A-1 (this):** directive harvest + scaffold + baseline preset + role-prompt bootstrap update. Gets the system working with v1 (current) encodings.
Future tracks in Campaign A:
- Alternative encoding authoring (v2, v3 per directive — the actual experimentation)
- Manual Slop integration (a "Directive Lab" panel for virtualized directive selection)
- Token-cost analysis tooling
- Automated compliance testing
### Campaign B: Video Analysis (4 new videos)
A separate research campaign following the established 3-pass pattern from the previous 12-video campaign (Pass 1: extract → Pass 2: deobfuscate → Pass 3: project to C11/Python). The 4 videos:
1. **Reinventing Entropy | Compression is Intelligence Part 1** (https://youtu.be/l6DKRf-fAAM)
2. **Yann LeCun: World Models: Enabling the next AI revolution** (https://www.youtube.com/watch?v=72Xj8k5WQX4)
3. **Yann LeCun's $1B Bet Against LLMs [Part 1]** (https://youtu.be/kYkIdXwW2AE)
4. **Recursive Self-Improvement** (https://youtu.be/t7_ZXgfJVG8)
### Cross-Campaign Relationship
The two campaigns inform each other but have no hard dependency:
- **The video analysis informs directive encoding.** The entropy/compression video (video 1) provides theoretical grounding for how information density affects comprehension. LeCun's world-model work (videos 2-3) informs how LLMs model directive intent. Recursive self-improvement (video 4) is directly relevant to the meta-question of whether better directive encodings can be discovered iteratively. Insights from the video analysis may surface alternative encoding strategies to test in Campaign A's harness.
- **The harness informs the video analysis.** The previous video campaign produced a lexicon + C11 reference + deobfuscation DSL. The directive harness is itself a compression-aid tool — it encodes the same directive in fewer/different tokens and observes the effect. The harness's design (preset as bill-of-materials, variant as alternative encoding) is the same pattern as the video campaign's deobfuscation pass (same content, different encoding). The harness may inform how the video analysis encodes its own outputs.
- **Execution order:** the campaigns can run in parallel. Campaign A (Track A-1) is an engineering track; Campaign B is a research track. They don't share files. The cross-pollination is intellectual, not structural.
### The video analysis track structure (Campaign B)
Follows the established 3-pass pattern from `docs/reports/2026-06-15/CAMPAIGN_CLOSE_OUT_video_analysis_20260621.md`:
- **Pass 1:** Information extraction (4 deep-dive reports, one per video). Uses the existing `scripts/video_analysis/` pipeline (download_video, extract_transcript, extract_keyframes, ocr_frames, synthesize_report). The lexicon v2 from the previous campaign is the starting point for deobfuscation.
- **Pass 2:** Deobfuscation (apply the lexicon v2 to the 4 new videos' content). May produce lexicon v3 corrections if the new videos surface notation the lexicon doesn't cover.
- **Pass 3:** C11/Python projection (project each video's deobfuscated content to code in the user's idiomatic style).
The video analysis track is initialized as a separate conductor track (`video_analysis_campaign_2_20260627` or similar). Its spec/plan is authored separately from this design doc.
## Out of Scope (for Track A-1)
- **Authoring alternative encodings (v2+).** This track only creates v1 (verbatim lifts). The experimentation is a future activity.
- **Deprecating the original docs.** The old docs stay as canonical source.
- **Scripts for preset generation or variant selection.** No automation in this version.
- **Manual Slop GUI integration.** The harness is OpenCode-only for now.
- **Token-cost analysis.** No tooling to measure token cost per variant in this version.
- **Automated compliance testing.** No test harness to measure LLM compliance per encoding.
- **The 4-video analysis (Campaign B).** Separate track, separate campaign. This design doc covers Campaign A (the harness) only. The video analysis gets its own track spec.
## Risks
1. **Harvest completeness.** The directive harvest might miss directives embedded in prose. Mitigation: systematic combing of the doc tree + the user reviews the candidate list before variants are created.
2. **Granularity ambiguity.** Some directives overlap (e.g., "ban dict[str, Any]" and "use typed dataclass fields" are two sides of the same coin). Mitigation: the harvest phase produces a candidate list; the granularity is resolved there, not upfront.
3. **Role-prompt drift.** The 5 role prompts need to be updated consistently. Mitigation: the `warm with:` line is the only change; the rest of each role prompt is untouched.
4. **Adoption friction.** LLMs might not follow the `warm with:` instruction reliably. Mitigation: the instruction is simple (read a file, read the files it lists) and uses the existing file-reading behavior the LLMs already have.
## See Also
- `conductor/tier2/agents/tier2-autonomous.md` — the role prompt that will be updated with `warm with:`
- `conductor/tier2/commands/tier-2-auto-execute.md` — the slash command template
- `conductor/code_styleguides/python.md` §17 — the primary source of directives to harvest
- `conductor/code_styleguides/error_handling.md` — the Result[T] convention to harvest
- `AGENTS.md` "Critical Anti-Patterns" — the hard bans to harvest
- `docs/guide_meta_boundary.md` — the meta-tooling / application distinction (relevant to why this harness lives in the meta-tooling domain)
- `docs/reports/2026-06-15/CAMPAIGN_CLOSE_OUT_video_analysis_20260621.md` — the previous video campaign's closeout (the pattern Campaign B follows)
- `scripts/video_analysis/` — the existing video analysis pipeline (Campaign B reuses this)