release: heavy-coder 0.3.0 - strategic coordinator skills

Author: codegraphtheory

.hermes.md

@@ -2,27 +2,27 @@
 
 Hermes loads this file for the installed profile. It states **default behavior for the coordinator agent**, not a hard runtime lock inside Hermes.
 
+## Every turn
+
+- Load **`heavy-scope-router`** first to classify read-only vs swarm vs single vs GitHub work.
+- Load phase skills from **`heavy-team-default`** companion table only when relevant (`heavy-context-budget` during explore/enrich).
+
 ## Default for coding work
 
-- Prefer the adaptive candidate pattern: width **3** (default) or **5** for larger or riskier tasks.
-- Use `delegate_task` with independent leaf workers (`delegation.max_spawn_depth` is 1: candidates do not nest further delegation).
-- After candidates finish: blind comparison, synthesis, then verification with real test commands.
-- If the user explicitly asks for **single mode**, **composer only**, or **no team**, follow that request.
+- Non-trivial implementation: **council width 8** by default (`heavy_coder.council_width`, `min_delegate_tasks: 8`) with `delegate_task` in **one** batch (`heavy-swarm-dispatch`).
+- Adaptive widths **3** and **5** apply when `heavy_council_always: false` or triage escalates risk; widths **8** and **16** are configured in `candidate_widths`.
+- After candidates finish: blind comparison, synthesis (`heavy-synthesize-winner`), then verification (`heavy-ship-gate`) with real test commands.
+- If the user explicitly asks for **single mode**, **composer only**, or **no team**, follow **`heavy-single-mode`**.
 
 ## Config alignment
 
-`config.yaml` sets `heavy_coder.team_enforced`, `candidate_widths: [3, 5]`, and `single_mode_requires_explicit`. The script `scripts/bootstrap_heavy_team.py` reads those flags for diagnostics; it does not auto-run on every Hermes turn unless you invoke it (for example via `doctor.py`).
+`config.yaml` sets `heavy_coder.team_enforced`, `candidate_widths: [3, 5, 8, 16]`, `council_width: 8`, `heavy_council_always: true`, and `single_mode_requires_explicit`. The script `scripts/bootstrap_heavy_team.py` reads those flags for diagnostics; it does not auto-run on every Hermes turn unless you invoke it (for example via `doctor.py`).
 
 ## Skills
 
-Load `heavy-team-default` for coding and repository tasks. It points to companion skills by phase:
-
-- `heavy-explore-first` - repo ground truth before planning
-- `heavy-leaf-brief` - pack `delegate_task` context for leaves
-- `heavy-synthesize-winner` - merge after swarm returns
-- `heavy-ship-gate` - run verification before claiming done
+Load **`heavy-team-default`** for coding and repository tasks. It maps companion skills by phase (router, enrich, dispatch, hook phases, candidate JSON, synthesis, repair wave, ship gate).
 
-Use `heavy-issue-to-merge` for GitHub issue and PR workflows (scaffolded scripts only today).
+Use **`heavy-issue-to-merge`** for GitHub issue and PR workflows (scaffolded scripts only today).
 
 ## Output
 

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.3.0
+
+- **Coordinator skills:** add eight strategic skills for routing, dispatch discipline, pre-dispatch enrich, candidate JSON, hook phases, repair waves, context budget, and single mode: `heavy-scope-router`, `heavy-swarm-dispatch`, `heavy-pre-dispatch-enrich`, `heavy-leaf-candidate-output`, `heavy-hook-phases`, `heavy-repair-wave`, `heavy-context-budget`, `heavy-single-mode`.
+- **`heavy-team-default` v0.6.0:** phase-based companion table wiring all swarm skills.
+- **Profile docs:** `.hermes.md` and `SOUL.md` - load `heavy-scope-router` each task; align council width **8** with `config.yaml`.
+- **Docs:** `enforcement-model.md` - delegate minimum and skills section for 0.3.0.
+
 ## 0.2.23
 
 - **IDE TUI bootstrap:** `display.auto_ide_skin` (default true) selects **`heavy-coder-ide`** in Cursor / VS Code / Windsurf and **`heavy-coder-light`** when `HERMES_TUI_THEME=light` (`profile_bootstrap.py`, shipped `config.yaml`).

RELEASE_NOTES.md

@@ -1,9 +1,10 @@
-## heavy-coder 0.2.23
+## heavy-coder 0.3.0
 
 ### Highlights
-- **IDE auto-skin:** `display.auto_ide_skin: true` (default) picks **`heavy-coder-ide`** in Cursor/VS Code/Windsurf on session bootstrap; **`heavy-coder-light`** when `HERMES_TUI_THEME=light`.
-- **heavy-coder-ide:** compact banner (logo only), brighter secondary/status text, clearer welcome for composer bleed mitigations.
-- **Docs:** `Iky`-style composer junk example in [ide-terminal-composer.md](docs/ide-terminal-composer.md).
+
+- **Strategic coordinator skills (8 new):** route tasks before spending swarm tokens (`heavy-scope-router`), dispatch full-width batches once (`heavy-swarm-dispatch`), enrich slim hook context (`heavy-pre-dispatch-enrich`), require candidate-result JSON (`heavy-leaf-candidate-output`), obey hook phases (`heavy-hook-phases`), narrow repair waves (`heavy-repair-wave`), token discipline (`heavy-context-budget`), explicit single mode (`heavy-single-mode`).
+- **`heavy-team-default` v0.6.0:** single phase table linking explore → enrich → dispatch → synthesize → ship gate.
+- **Profile alignment:** `.hermes.md` / `SOUL.md` updated for default council width **8** and per-turn routing.
 
 ### Install / update (local tree or GitHub)
 
@@ -12,22 +13,13 @@ hermes profile install github.com/codegraphtheory/heavy-coder --name heavy-coder
 heavy-coder chat
 ```
 
-Restart chat (`/new`) from the **IDE integrated terminal** so bootstrap can set the IDE skin.
-
-**Best composer fix in Cursor** (short prompt prefix):
-
-```bash
-hermes profile install github.com/codegraphtheory/heavy-coder --name hc --alias --force --yes
-hc chat
-```
-
 Pin a tagged checkout:
 
 ```bash
-git checkout v0.2.23
+git checkout v0.3.0
 hermes profile install . --name heavy-coder --alias --force --yes
 ```
 
 Hermes install URLs do not support `@tag` suffixes; use a local checkout to pin.
 
-Full changelog: [CHANGELOG.md](https://github.com/codegraphtheory/heavy-coder/blob/v0.2.23/CHANGELOG.md)
+Full changelog: [CHANGELOG.md](https://github.com/codegraphtheory/heavy-coder/blob/v0.3.0/CHANGELOG.md)

SOUL.md

@@ -16,6 +16,10 @@ Help maintainers move from a GitHub issue or terminal request to a tested, revie
 
 Read [docs/composer-hermes-swarms.md](docs/composer-hermes-swarms.md) when the user asks how swarms work.
 
+## Skills (coordinator)
+
+On each task: **`heavy-scope-router`** → phase skills from **`heavy-team-default`** (enrich, dispatch, synthesize, ship gate). Load only what the current phase needs.
+
 ## Operating principles
 
 1. Security and correctness come before speed.

distribution.yaml

@@ -1,5 +1,5 @@
 name: heavy-coder
-version: 0.2.23
+version: 0.3.0
 description: "Hermes profile with shell-hook enforced multi-candidate coding teams (Plan 1A)."
 hermes_requires: ">=0.12.0"
 author: "CodeGraphTheory"

docs/adr/0003-adaptive-agent-width.md

@@ -8,7 +8,9 @@ Parallel independent candidates can reveal different fixes and reduce early-assu
 
 ## Decision
 
-Use adaptive width 3 or 5 in the installed profile (`candidate_widths: [3, 5]`, `default_width: 3`). Escalate from 3 to 5 when tests fail, candidates disagree, or confidence is low. Single-agent mode is opt-in only (`single_mode_requires_explicit`).
+Use adaptive width 3 or 5 when `heavy_council_always` is false (`candidate_widths` includes 3 and 5). Escalate from 3 to 5 when tests fail, candidates disagree, or confidence is low. Single-agent mode is opt-in only (`single_mode_requires_explicit`).
+
+As of profile **0.3.0**, shipped `config.yaml` sets `heavy_council_always: true` and `council_width: 8` for default Composer swarms; widths 8 and 16 are first-class in `candidate_widths`. This ADR still governs adaptive 3/5 when council-always is disabled.
 
 ## Consequences
 

docs/enforcement-model.md

@@ -6,7 +6,7 @@ Heavy Coder combines **coordinator instructions**, **deterministic scripts**, an
 
 | Step | Mechanism |
 |------|-----------|
-| Triage width 3/5 | `src/heavy_coder/triage.py`, `scripts/team_coordinator.py` |
+| Triage / council width | `src/heavy_coder/triage.py`, `scripts/team_coordinator.py` (default **8** when `heavy_council_always`; adaptive 3/5 when off) |
 | Emit delegate specs | `team_coordinator.py` JSON field `delegate_tasks` |
 | One-shot flow | `scripts/heavy_coding_flow.py` (doctor + plan + worktree plan) |
 | Worktree isolation | `worktrees.py create --execute` (refuses dirty repos) |
@@ -17,7 +17,9 @@ Heavy Coder combines **coordinator instructions**, **deterministic scripts**, an
 
 The Hermes coordinator must still call `delegate_task`; scripts do not spawn agents themselves.
 
-**Plan 1A (0.2.0+):** Profile `config.yaml` registers **shell hooks** that inject the team plan, block solo `patch`/`write_file` before delegation, require `delegate_task` width 3+, and capture `subagent_stop` evidence. See `docs/plan-1a-shell-hooks.md`.
+**Plan 1A (0.2.0+):** Profile `config.yaml` registers **shell hooks** that inject the team plan, block solo `patch`/`write_file` before delegation, require `delegate_task` at least `delegate_minimum()` (default **8**), and capture `subagent_stop` evidence. See `docs/plan-1a-shell-hooks.md`.
+
+**Skills (0.3.0+):** Coordinator skills (`heavy-scope-router`, `heavy-swarm-dispatch`, `heavy-pre-dispatch-enrich`, etc.) document routing, dispatch discipline, and evidence gates-see `skills/heavy-team-default/SKILL.md`.
 
 ## Instruction layers
 

skills/heavy-context-budget/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: heavy-context-budget
+description: Keep coordinator and leaf context lean-batch reads, cap logs, use execute_code to filter-so swarms stay fast and within token limits.
+version: 0.1.0
+author: CodeGraphTheory
+license: MIT
+metadata:
+  hermes:
+    tags: [heavy-coder, performance, context, coordinator]
+    related_skills:
+      - heavy-explore-first
+      - heavy-pre-dispatch-enrich
+      - heavy-leaf-brief
+---
+
+# Heavy context budget
+
+## Overview
+
+Heavy Coder optimizes swarm **breadth** (parallel leaves). Coordinator and leaf **depth** (megabyte pastes) destroys latency and blows injection caps (`heavy_coder.max_injected_plan_chars`). This skill is the token discipline for coordinators and for text placed in `delegate_task` context.
+
+## When to Use
+
+- Every explore and pre-dispatch enrich turn
+- Before pasting CI logs, stack traces, or `read_file` output into chat or leaf context
+- Large monorepos or many candidate summaries at synthesis
+
+## Coordinator rules
+
+### Batch independent I/O
+
+- Multiple `read_file` / `search_files` / read-only `terminal` in **one turn** when inputs do not depend on each other.
+- Do not read file A, wait, read file B, wait-batch.
+
+### Cap pasted material
+
+| Material | Max in context/chat |
+|----------|---------------------|
+| Stack trace / test failure | ~80 lines or 4 KB |
+| Full file body | Use `offset`/`limit`; cite `path:line` |
+| Directory listings | `search_files` with `limit` |
+| Candidate summaries at synthesis | Bullets: files, commands, exit codes |
+
+### Filter before paste
+
+Use `execute_code` when you need to:
+
+- Ripgrep and return only matching lines + numbers
+- Parse JSON test output for failures only
+- Count/dedupe paths across candidates
+
+### Skills loading
+
+- Load **only** skills for the current phase (router → enrich → dispatch → synthesize → ship).
+- Do not load the full heavy skill catalog every turn.
+
+### Leaf context
+
+- Profile default `leaf_toolsets: [terminal, file]`-no `web` unless needed.
+- Point to plan file path instead of duplicating full user essay in eight contexts.
+
+## Slim injection alignment
+
+Hooks use `slim_delegate_context` and compact chat injection. Coordinator enrich (`heavy-pre-dispatch-enrich`) adds **high-signal** bytes only-touch map, repro excerpt, evidence bar-not narrative repetition.
+
+## Done when
+
+- No leaf `context` contains a full-file dump unless that file is the entire task scope (<200 lines)
+- Chat responses use references (`path:line`) instead of reproducing whole modules
+- Logs in context are truncated with note "truncated; run X for full"
+
+## Anti-patterns
+
+| Symptom | Fix |
+|---------|-----|
+| Injection truncated by hooks | Shorter enrich block; move detail to disk plan |
+| Eight copies of same 2 KB task | Shared enrich block once per leaf |
+| Coordinator summarizes without reading | Batch read touch map first |
+
+## Docs
+
+- [composer-hermes-swarms.md](../../docs/composer-hermes-swarms.md)

skills/heavy-explore-first/SKILL.md

@@ -7,7 +7,7 @@ license: MIT
 metadata:
   hermes:
     tags: [heavy-coder, discovery, context, software-development]
-    related_skills: [heavy-leaf-brief, heavy-team-default, plan]
+    related_skills: [heavy-leaf-brief, heavy-team-default, plan, heavy-scope-router]
 ---
 
 # Heavy explore first

skills/heavy-hook-phases/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: heavy-hook-phases
+description: Obey Plan 1A hook session phases so mutating tools, delegate_task sizing, and re-planning do not waste turns or trigger blocks.
+version: 0.1.0
+author: CodeGraphTheory
+license: MIT
+metadata:
+  hermes:
+    tags: [heavy-coder, hooks, coordinator, performance]
+    related_skills:
+      - heavy-swarm-dispatch
+      - heavy-synthesize-winner
+      - heavy-single-mode
+---
+
+# Heavy hook phases
+
+## Overview
+
+Shell hooks track a **session phase** per coordinator session. Ignoring phases causes blocked `patch` calls, duplicate council plans, and confused users. This skill is the operational cheatsheet aligned with `agent-hooks/*.py`.
+
+## When to Use
+
+- Before any `patch`, `write_file`, `delegate_task`, or write-like `terminal`
+- User asks why Heavy Coder blocked a tool
+- After `ASYNC DELEGATION BATCH COMPLETE` or mid-swarm
+
+## Phase model
+
+| Phase | Typical trigger | Coordinator may | Coordinator must not |
+|-------|-----------------|-----------------|----------------------|
+| `IDLE` | Session start, trivial chat | Read-only tools | Assume swarm already ran |
+| `AWAITING_DELEGATE` | `pre_llm_heavy_team` injected plan | Full-width `delegate_task`; read/todo | Repo writes; undersized delegate |
+| `AWAITING_SYNTHESIS` | `post_delegate_task` after dispatch | Synthesis reads; then writes after merge plan | New full council for **same** task |
+| (implicit complete) | After ship gate / user new task | Normal tools for **new** task | Re-use old width state blindly |
+
+Single mode (from task excerpt) relaxes delegate minimum and write blocks-see `heavy-single-mode`.
+
+## Tool-specific rules
+
+### `delegate_task`
+
+- Count must be ≥ `profile_cfg.delegate_minimum(width)` (default **8** when `council_width` and `min_delegate_tasks` are 8).
+- One batch with all plan entries (`heavy-swarm-dispatch`).
+
+### `patch` / `write_file`
+
+- Blocked in `AWAITING_DELEGATE` unless single mode.
+- After synthesis, apply **one coherent** patch set (`heavy-synthesize-winner`).
+
+### `terminal`
+
+- Write-like commands (redirect to file, `sed -i`, destructive git) blocked before delegation.
+- Verification commands run after synthesis (`heavy-ship-gate`).
+
+### `pre_llm_call` re-injection
+
+- Skipped when phase is `AWAITING_SYNTHESIS` or message contains batch complete marker.
+- Do not change the user task wording to force a new plan mid-synthesis.
+
+## Artifacts
+
+| Path | Purpose |
+|------|---------|
+| `.heavy-coder/plans/<session>.json` | Full plan + `delegate_tasks` |
+| `.heavy-coder/evidence/<child>.json` | Leaf evidence from `subagent_stop` |
+| `.heavy-coder/swarm-progress.json` | Live dashboard for `swarm_watch.py` |
+
+## User communication
+
+When blocked, explain in one sentence: phase, required next step (`delegate_task` with N tasks), or single-mode opt-out.
+
+**Done when:** next tool call matches the phase column above.
+
+## Docs
+
+- [plan-1a-shell-hooks.md](../../docs/plan-1a-shell-hooks.md)