manual_slop/conductor/tracks/directive_hotswap_harness_20260627/plan.md

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):

# <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

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:

# 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

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:

## 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

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

# 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: ")

• 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

git add docs/reports/TRACK_COMPLETION_directive_hotswap_harness_20260627.md
git commit -m "docs(reports): TRACK_COMPLETION_directive_hotswap_harness_20260627"