impulso 0.19.1

package/README.md

@@ -0,0 +1,425 @@
+# Impulso
+
+Plugin bundle for opencode + Claude Code: **Plannotator** (vendored skills) +
+**Impulso-DirectSpeech** (terse communication mode) + **Impulso-RTK** (token
+savings via `rtk rewrite` for 60-90% LLM token savings on shell commands).
+
+Harness-neutral repo. Per-harness glue under `harnesses/`.
+
+## Contents
+
+| Piece                | What                                                                                                                                                                                                     |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Plannotator          | 3 vendored skills (annotate/last/review) + 3 commands. Skills invoke the `plannotator` CLI binary directly (user-installed); no npm plugin.                                                              |
+| Impulso-DirectSpeech | Terse communication mode — **always active, enforced by the harness**. Ruleset in `shared/AGENTS.md` + per-turn reinforcement hook on each harness. No toggle. 3 auxiliary skills (compress/stats/help). |
+| Impulso-RTK          | Rewrites bash tool calls via `rtk rewrite` for 60-90% token savings. `rtk` + `tokensave` hard-required and enforced at runtime — launchers, hooks, and plugin block with install hints when missing.     |
+
+## Install routes
+
+Four ways in — pick **one per profile** (combining the Claude plugin with the
+Claude installer duplicates hooks). The plugin route is the recommended default
+for both harnesses.
+
+| Route                                                     | Harness  | You get                                                              |
+| --------------------------------------------------------- | -------- | -------------------------------------------------------------------- |
+| **Claude Code plugin (marketplace, recommended)**         | claude   | hooks + skills + commands + tokensave MCP, versioned, auto-updatable |
+| `harnesses/claude/install.sh`                             | claude   | same + ruleset wired into CLAUDE.md; merge-safe into `~/.claude`     |
+| Self-boot (`run_here_claude.sh`)                          | claude   | everything, isolated to this repo — dev/testing                      |
+| **opencode plugin (recommended)** / installer / self-boot | opencode | plugin composes everything; see below                                |
+
+## Install — Claude Code plugin (marketplace, recommended)
+
+Inside any claude session:
+
+```
+/plugin marketplace add alexandrekm/Impulso
+/plugin install impulso@impulso
+```
+
+Loads the three hooks (preflight, rtk rewrite, DirectSpeech reinforcement — via
+`${CLAUDE_PLUGIN_ROOT}`), all skills/commands, and the tokensave MCP server.
+Update later with `/plugin marketplace update impulso`.
+
+Not covered by the plugin (Claude Code plugins can't ship memory files): the
+full ruleset in `shared/AGENTS.md`. DirectSpeech still enforces per turn via the
+hook; for the complete ruleset add an import line to your `~/.claude/CLAUDE.md`
+pointing at a checked-out copy, or use the installer route instead.
+
+Requires `rtk` + `tokensave` on PATH — the preflight hook blocks prompts
+otherwise (that's the point).
+
+## Install — opencode plugin (recommended)
+
+Add one entry to your opencode config:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["impulso@git+https://github.com/alexandrekm/Impulso.git"],
+}
+```
+
+Restart opencode (clear cache first):
+
+```bash
+rm -rf ~/.cache/opencode/node_modules/impulso
+pkill -f opencode
+opencode
+```
+
+The single plugin entry internally composes DirectSpeech + bundled skills and
+commands. Plannotator skills invoke the user-installed `plannotator` binary
+directly — no npm plugin dependency.
+
+### Update
+
+opencode caches git+https plugins locally and won't refetch on its own. Pull the
+latest revision with the same clear-cache-and-restart steps shown above:
+
+```bash
+rm -rf ~/.cache/opencode/node_modules/impulso
+pkill -f opencode
+opencode
+```
+
+If pinned to a tag or commit, bump it in your config first, then run the same
+cache-clear + restart.
+
+### Pin a version
+
+```jsonc
+"plugin": ["impulso@git+https://github.com/alexandrekm/Impulso.git#v0.1.0"]
+```
+
+### Install from a local clone
+
+```jsonc
+"plugin": ["impulso@git+file:///abs/path/to/hip-liger"]
+```
+
+The `file://` URL must be an **absolute path** with three slashes
+(`file:///abs/...`) and the directory must be a git repo (have `.git/`).
+
+---
+
+## Quick start — target repo directly (no install)
+
+Point `XDG_CONFIG_HOME` at the repo root:
+
+```bash
+cd /path/to/impulso
+XDG_CONFIG_HOME=$(pwd) opencode
+```
+
+Or use the convenience wrapper:
+
+```bash
+./run_here.sh
+```
+
+> **Prerequisite:** the `plannotator` binary must be on your `PATH` for the
+> Plannotator skills to launch the annotation UI. Install it separately (not
+> bundled with this repo).
+
+## Quick start — Claude Code
+
+Point `CLAUDE_CONFIG_DIR` at the repo's bundled `claude/` config dir — no
+install step, no separate profile dir. Skills and commands resolve via symlinks
+inside `claude/`; hooks resolve via `$CLAUDE_CONFIG_DIR` shell expansion in
+`settings.json`:
+
+```bash
+cd /path/to/impulso
+CLAUDE_CONFIG_DIR=$(pwd)/claude claude
+```
+
+Or use the convenience wrapper:
+
+```bash
+./run_here_claude.sh
+```
+
+For a permanent isolated install that leaves your main `~/.claude/` untouched:
+
+```bash
+./harnesses/claude/install.sh
+CLAUDE_CONFIG_DIR=~/.config/impulso-profile/claude claude
+```
+
+To install into `~/.claude/` directly (shared with your normal Claude Code
+config): `IMPULSO_CLAUDE_PROFILE="$HOME/.claude" ./harnesses/claude/install.sh`
+
+See [`harnesses/claude/README.md`](harnesses/claude/README.md) for Plannotator
+upstream plugin setup and RTK install.
+
+## Install — isolated profiles
+
+For permanent installs that leave your main config dirs untouched:
+
+```bash
+./harnesses/opencode/install.sh
+XDG_CONFIG_HOME=~/.config/impulso-profile opencode
+
+./harnesses/claude/install.sh
+CLAUDE_CONFIG_DIR=~/.config/impulso-profile/claude claude
+```
+
+## Token savings via RTK (hard-required)
+
+`rtk` and `tokensave` are enforced at every layer — no degraded mode:
+
+- `install.sh` scripts abort when either is missing.
+- `run_here.sh` / `run_here_claude.sh` launchers fail fast.
+- opencode: the Impulso plugin throws at init.
+- Claude Code: a UserPromptSubmit preflight hook blocks prompts, and the rtk
+  PreToolUse hook blocks Bash calls — both with install hints.
+
+```bash
+brew install rtk
+# or: cargo install --git https://github.com/rtk-ai/rtk
+# or: curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
+```
+
+The tokensave MCP server additionally needs a per-project index — run
+`tokensave init` once in each repo you work in (`.tokensave/` is gitignored
+globally by the installer).
+
+See [`harnesses/opencode/rtk/README.md`](harnesses/opencode/rtk/README.md).
+
+## Usage — everything in one place
+
+### Daily use
+
+DirectSpeech is always on — nothing to activate, no off-switch. RTK rewrites run
+automatically on every bash call; write plain commands. tokensave MCP tools are
+available once `tokensave init` has been run in the project.
+
+| Slash command                            | What it does                                        |
+| ---------------------------------------- | --------------------------------------------------- |
+| `/plannotator-annotate <file\|url\|dir>` | browser annotation UI, feedback returned to session |
+| `/plannotator-last`                      | annotate the latest assistant message               |
+| `/plannotator-review [PR URL]`           | browser code review of worktree or PR               |
+| `/impulso-directspeech-compress <file>`  | compress a .md file to terse prose (~46% tokens)    |
+| `/impulso-directspeech-stats`            | token-savings stats                                 |
+| `/impulso-directspeech-help`             | reference card                                      |
+
+Plannotator commands need the `plannotator` binary:
+`curl -fsSL https://plannotator.ai/install.sh | bash`
+
+### Per-project setup
+
+```bash
+tokensave init        # build the tokensave index (once per repo)
+```
+
+### Maintenance
+
+```bash
+./doctor.sh                          # health check: binaries, symlinks, configs, MCP
+./harnesses/claude/uninstall.sh      # reverse the claude install (targeted, safe)
+./harnesses/opencode/uninstall.sh    # remove the opencode profile
+```
+
+### Development (this repo)
+
+```bash
+npm test                                  # all unit suites
+npm run lint && npm run format:check
+npm run sync:commands                     # regen commands/ after editing skills/
+./harnesses/opencode/integration-tests.sh # live boot tests; model resolved via
+                                          # IMPULSO_TEST_MODEL > bedrock auth > CLI_PROXY_URL
+claude plugin validate .                  # check plugin/marketplace manifests
+```
+
+Editing rules: skills are the source — never edit `commands/` by hand (CI drift
+check will fail); the ruleset lives only in `shared/AGENTS.md` (`claude/` and
+`opencode/` symlink it); claude hooks live in `harnesses/claude/hooks/` and are
+referenced from both `claude/settings.json` (self-boot/installer) and
+`hooks/hooks.json` (plugin).
+
+## Agent orchestration
+
+Multi-agent pipeline (orchestrator → specialist agents) on both harnesses, from
+a single source of truth in `shared/orchestration-config.cjs`.
+
+### Roster
+
+| Agent                | Role                                             | CC default     | opencode default           |
+| -------------------- | ------------------------------------------------ | -------------- | -------------------------- |
+| ImpulsoOrchestrator  | Routes tasks to specialist agents; no file edits | session (null) | session (null)             |
+| scout                | Read-only recon; returns path:line refs          | haiku          | `llm/scout`                |
+| planner              | Drafts spec.md / plan.md                         | opus           | `llm/planner`              |
+| implementer          | Code, tests, refactors                           | sonnet         | `llm/implementer`          |
+| implementer-frontend | UI, CSS, component trees                         | sonnet         | `llm/implementer-frontend` |
+| implementer-infra    | Terraform, K8s, CI/CD                            | sonnet         | `llm/implementer-infra`    |
+| reviewer             | Code review (task-level and branch-level)        | opus           | `llm/reviewer`             |
+| debugger             | Root-cause analysis, regression test, fix        | sonnet         | `llm/debugger`             |
+| shipper              | Commits, push, PR                                | haiku          | `llm/shipper`              |
+| generalist           | Catch-all; prefer specialists when type is known | sonnet         | `llm/generalist`           |
+
+### Pipeline
+
+Key orchestration behaviors:
+
+- **Route self-check:** Estimate blast radius before committing to a route.
+  Prefer `small` for config-only / ≤~3-file / unambiguous changes; propose a
+  downgrade when the route feels heavier than the diff.
+- **Brainstorm:** Batch all independent questions in one round (sequential only
+  for dependent decisions). Any post-plan design change restarts the brainstorm
+  cycle — no mid-pipeline pivots.
+- **Spec:** Confirmed in chat with the user — no Plannotator gate at this phase.
+  Plannotator gates remain at Plan and the final branch/code review.
+- **Parallel dispatch:** Plan tasks carry a `parallel-safe: yes|no` field. The
+  orchestrator fans out `parallel-safe: yes` tasks concurrently (edit-only
+  implementers; orchestrator owns gate state + commits); `parallel-safe: no`
+  tasks run sequentially.
+
+### Override — `.impulso/models.json`
+
+Ladder (highest wins): `<repo>/.impulso/models.json` >
+`~/.impulso/models.json` > shipped defaults.
+
+The file is **harness-partitioned**: top-level keys must be `claude` and/or
+`opencode`. Flat keys (e.g. `"planner": "opus"`) are rejected with a
+migration-hint error. A file may carry only one block; the absent block
+contributes no overrides.
+
+Each block maps an agent key (roster name) to a model string or
+`{ "model", "effort" }` object; fields merge per-key down the ladder, so an
+effort-only override keeps the lower-rung model. Unknown keys or bad JSON = hard
+fail, no silent fallback.
+
+```json
+{
+  "claude": { "planner": "opus", "reviewer": "opus" },
+  "opencode": { "planner": "llm/deep", "implementer": { "effort": "xhigh" } }
+}
+```
+
+opencode values are **pass-through strings** — either a logical alias
+(`llm/deep`) or a concrete provider model. Impulso does not resolve or validate
+them; they replace the shipped `llm/<key>` default verbatim.
+
+`effort` inside a `claude` block is a **hard error** — Claude Code effort comes
+from `agents/<name>.md` frontmatter, not `models.json`. Place effort overrides
+in the `opencode` block only.
+
+### opencode aliases (BYO-config required)
+
+opencode ships logical aliases, not concrete model IDs. Every agent in the
+`opencode` block resolves through an `llm/<key>` alias that must be mapped in
+your opencode provider config — Impulso provides no fallback. An undefined alias
+fails at dispatch. `doctor.sh` warns when aliases are active (spec §7).
+
+| Agent                | Shipped alias              |
+| -------------------- | -------------------------- |
+| scout                | `llm/scout`                |
+| scout-writer         | `llm/scout-writer`         |
+| planner              | `llm/planner`              |
+| implementer          | `llm/implementer`          |
+| implementer-frontend | `llm/implementer-frontend` |
+| implementer-infra    | `llm/implementer-infra`    |
+| reviewer             | `llm/reviewer`             |
+| debugger             | `llm/debugger`             |
+| shipper              | `llm/shipper`              |
+| generalist           | `llm/generalist`           |
+
+To wire up aliases, define each `llm/<key>` entry in your opencode provider
+config (exact syntax depends on your provider plugin). Alternatively, override
+the `opencode` block in `.impulso/models.json` with concrete model IDs — that
+bypasses the alias layer entirely.
+
+### Inspection
+
+```bash
+impulso-hub models                              # full resolved map (claude, default)
+impulso-hub models --agent reviewer             # single agent
+impulso-hub models --harness opencode           # opencode alias map
+```
+
+### Caveats
+
+Model strings are **not** validated at config load — a typo surfaces at dispatch
+when the provider rejects the ID. Aliases (`sonnet`/`haiku`/`opus`) on the CC
+side track the harness's default for that tier; pin full model IDs to lock a
+specific version.
+
+**Migration (flat `models.json`):** Existing files with flat top-level keys
+(e.g. `{ "planner": "opus" }`) now fail at boot with a migration-hint error.
+Wrap the content under `"claude"` and/or `"opencode"` blocks. Move any `effort`
+values into the `opencode` block, or into `agents/<name>.md` frontmatter for
+Claude Code effort.
+
+**opencode default behavior change:** opencode no longer defaults to concrete
+models; it defaults to `llm/<key>` aliases (see table above). Users who did not
+previously override models must either define the `llm/*` aliases in their
+opencode provider config or pin concrete models in the `opencode` block of
+`models.json`. There is no fallback — undefined aliases fail at dispatch.
+
+### Harness differences
+
+**Effort** behaves differently per harness:
+
+- **opencode**: `effort` is registered at boot as `reasoningEffort` on the agent
+  config — a provider-passthrough value. The `models.json` ladder applies.
+  Interpretation is provider-specific.
+- **Claude Code**: the Agent tool has no dispatch-time effort parameter, so the
+  `models.json` effort ladder does not apply — specifying `effort` in the
+  `claude` block of `models.json` is a **hard error** (use `agents/<name>.md`
+  frontmatter instead). Effort is a static `effort:` frontmatter key in
+  `agents/*.md` (validated by `sync:agents`; unset = inherit session).
+
+**Model dispatch:**
+
+- **opencode**: models are pinned at boot in `config.agent[name].model`. Boot
+  values are the `llm/<key>` aliases by default (see alias table).
+- **Claude Code**: orchestrator pins the resolved model on every dispatch via
+  the Agent tool `model` parameter.
+
+Use `impulso-hub models --harness claude|opencode` (default `claude`) to inspect
+the full resolved map for either harness.
+
+**Model ID format and `[1m]` context-suffix:** no difference. Neither harness
+transforms or validates model IDs; no `[1m]` suffix support exists in either.
+
+### Deterministic orchestration ownership
+
+Deterministic state and precondition validation
+(`impulso-hub status --json schema v1`) are owned by `impulso-hub`. Specialized
+skills retain human interview, dispatch, and remediation policy.
+
+## Structure
+
+```
+impulso/
+├── AGENTS.md              # contributor guide for AI agents working on this repo
+├── CLAUDE.md              # @AGENTS.md import (Claude Code reads CLAUDE.md)
+├── .claude-plugin/        # plugin.json + marketplace.json (claude plugin route)
+├── hooks/hooks.json       # plugin hook declarations (${CLAUDE_PLUGIN_ROOT})
+├── .mcp.json              # tokensave MCP (plugin route + project-local)
+├── run_here.sh            # boots opencode against this repo
+├── run_here_claude.sh     # boots Claude Code against this repo
+├── doctor.sh              # health checks: binaries, symlinks, configs, MCP
+├── opencode/              # self-boot config: opencode.jsonc + AGENTS.md -> shared/ + symlinks
+├── claude/                # self-boot config: settings.json + CLAUDE.md + AGENTS.md -> shared/ + symlinks
+├── skills/                # harness-agnostic skill files (SKILL.md per dir)
+├── commands/              # auto-generated from skills/ (sync-commands.js)
+├── shared/                # harness-neutral: AGENTS.md (canonical ruleset), directspeech-config.cjs, tests.cjs
+└── harnesses/
+    ├── opencode/      # opencode-specific glue
+    │   ├── plugin.js          # orchestrator (composes DirectSpeech + bundled skills/commands)
+    │   ├── compose.js         # hook merging helper
+    │   ├── frontmatter.js     # shared YAML frontmatter parser
+    │   ├── commands-loader.js # runtime command registration
+    │   ├── sync-commands.js   # build-time cmd generation from skills
+    │   ├── install.sh         # isolated profile installer
+    │   ├── uninstall.sh       # removes the isolated profile
+    │   ├── directspeech/      # DirectSpeech plugin (always-on reinforcement)
+    │   └── rtk/               # vendored upstream RTK plugin (rtk.ts + README.md)
+    └── claude/        # Claude Code glue
+        ├── install.sh         # profile installer (merge-safe for shared profiles)
+        ├── uninstall.sh       # targeted reversal — never touches foreign content
+        ├── merge-settings.cjs # settings.json merge (foreign hooks/keys survive)
+        ├── tests.cjs
+        └── hooks/            # preflight.cjs, rtk.cjs, directspeech-context.cjs
+```

package/agents/ImpulsoOrchestrator.md

@@ -0,0 +1,112 @@
+---
+name: ImpulsoOrchestrator
+description: Routes tasks to specialist agents.
+tools: Read, Grep, Glob, Bash, Task, TaskCreate, TaskUpdate, AskUserQuestion
+permission-class: dispatch-only
+---
+
+# Orchestrator
+
+Pure scheduler. Never implement, edit source, or write files. Touch `.impulso/`
+state via `impulso-hub` only.
+
+## Route classification
+
+| Route    | When                                |
+| -------- | ----------------------------------- |
+| trivial  | ≤5 min, no file writes, answer only |
+| small    | single bug fix or narrow change     |
+| feature  | multi-task, needs spec + plan       |
+| debug    | repro-first investigation           |
+| question | answer only, no code                |
+
+User-stated route wins. When ambiguous, ask.
+
+Before choosing `feature`, estimate blast radius. Config-only or ≤~3-file
+changes with no real ambiguity → prefer `small`. If the chosen route feels
+heavier than the likely diff, propose downgrading to the user.
+
+## Session bootstrap
+
+If `impulso-hub status` exits 2 with "No active workspace...", immediately run
+`impulso-hub init <slug> --route <route>` using the route from classification
+above — do not probe further with ls/find/cat/models first.
+
+## Brainstorm protocol (feature route)
+
+Before dispatching the planner, gather ALL design decisions and
+environment/context facts up front. Batch independent questions into one message
+— reserve one-at-a-time strictly for decisions that depend on a prior answer.
+Say verbatim:
+
+<!-- prettier-ignore -->
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Batch independent questions into one message; ask dependent decisions one at a time, waiting for each answer before proceeding. For each question, provide your recommended answer.
+
+<!-- prettier-ignore -->
+Ask each question via the interactive question tool (`AskUserQuestion` on Claude Code, `question` on opencode) — recommended answer as the first option; plain text otherwise.
+
+Facts from the codebase come via scout. Decisions go to the human.
+
+<!-- prettier-ignore -->
+Do not enact the plan until I confirm we have reached a shared understanding.
+
+Any design change surfaced after the plan is approved is a new brainstorm — do
+not pivot mid-pipeline.
+
+## Dispatch rules
+
+- Model per agent: `impulso-hub models --agent <name>` — never hardcode.
+- Handoffs by path: brief files, report paths, review package paths — never
+  paste content.
+- Dispatch each agent with explicit model and exact file paths.
+- Expect ≤15-line status block from every dispatched agent.
+- On NEEDS_CONTEXT or BLOCKED: surface to user, do not guess.
+- Tasks marked `parallel-safe: yes` in the plan: dispatch concurrently. The
+  orchestrator alone calls `impulso-hub task start/done` and handles commits;
+  parallel-safe implementers are edit-only (no gate or git calls). Rationale:
+  `state.json` writes are atomic but concurrent gate calls from multiple agents
+  risk lost-updates — disallowed.
+
+## Phase transitions
+
+Only via `impulso-hub advance`. On exit 2, do exactly what stderr says — no
+other action.
+
+Spec phase: run `impulso-hub spec-review-mode`. Output tells you the mode
+(`confirm` or `plannotator`) and line count. If `confirm`: confirm spec with
+user in chat, then `impulso-hub record-spec-confirmation`, then
+`impulso-hub advance`. If `plannotator`: full Plannotator annotate → feedback →
+`impulso-hub record-plannotator spec.md` → advance.
+
+## Deterministic orchestration ownership
+
+Deterministic state and precondition validation (`impulso-hub status --json`
+schema v1) are owned by `impulso-hub`. Specialized skills retain human
+interview, dispatch, and remediation policy.
+
+## impulso-hub CLI reference
+
+| Command                  | Usage                                                                                  |
+| ------------------------ | -------------------------------------------------------------------------------------- |
+| version                  | `impulso-hub version`                                                                  |
+| init                     | `impulso-hub init <slug> --route <route>`                                              |
+| status                   | `impulso-hub status [--json]`                                                          |
+| advance                  | `impulso-hub advance`                                                                  |
+| record-test              | `impulso-hub record-test --cmd <c> --exit-code <n> [--full] [--coverage] [--task <n>]` |
+| run-test                 | `impulso-hub run-test [--full] [--coverage] [--task <n>]`                              |
+| record-plannotator       | `impulso-hub record-plannotator <artifact\|--review> [--output <path>]`                |
+| task                     | `impulso-hub task <start\|done> <n>`                                                   |
+| brief                    | `impulso-hub brief <n>`                                                                |
+| review-package           | `impulso-hub review-package <base> <head>`                                             |
+| models                   | `impulso-hub models [--agent <a>] [--harness <h>]`                                     |
+| record-review-verdict    | `impulso-hub record-review-verdict <clean\|findings>`                                  |
+| record-pr                | `impulso-hub record-pr <url>`                                                          |
+| config                   | `impulso-hub config set <key> <value>`                                                 |
+| spec-review-mode         | `impulso-hub spec-review-mode`                                                         |
+| record-spec-confirmation | `impulso-hub record-spec-confirmation`                                                 |
+
+**Note:** `run-test --full --coverage [--task <n>]` combines both flags in a
+single subprocess execution, satisfying both `suite-green` and `coverage-pass`
+preconditions at once. Do not call `--full` and `--coverage` separately if
+`coverage_cmd` and `test_cmd` overlap — it double-runs the suite for no extra
+signal.

package/agents/debugger.md

@@ -0,0 +1,38 @@
+---
+name: debugger
+description: Root-cause analysis and bug fixes.
+model: sonnet
+permission-class: full
+---
+
+# Debugger
+
+Reproduce first. No hypothesis before a red-capable repro command.
+
+## Protocol
+
+1. Produce a repro command: exact invocation + expected output + actual output.
+2. Confirm the command is red (fails reproducibly).
+3. Form 3–5 ranked falsifiable hypotheses. Most specific first.
+4. Test each hypothesis: one change, re-run repro, observe.
+5. Write regression test before applying the fix.
+6. Watch test fail → apply fix → watch test pass.
+
+## Rules
+
+- If `.impulso/work/<slug>/context.md` exists, read it first — shared, read-only
+  codebase facts. It supplements the brief, never overrides it.
+- No fix without a repro command.
+- No fix without a passing regression test.
+- Scope: the reported bug only. Do not refactor adjacent code.
+- Mark deliberate cuts: `impulso: <ceiling>, <upgrade path>`.
+- Write full report to the given report path before returning status.
+
+## Status block (≤15 lines, always last)
+
+```
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED
+commits: <sha7> <imperative summary>
+tests: <one-line summary: N passed, N failed>
+concerns: <none|description>
+```

package/agents/generalist.md

@@ -0,0 +1,26 @@
+---
+name: generalist
+description: Catch-all for tasks without a specialist fit.
+model: sonnet
+permission-class: full
+---
+
+# Generalist
+
+Catch-all route. Prefer a specialist when the task type is known.
+
+## Rules
+
+- DirectSpeech: terse, technical, no filler.
+- No scope creep — report back rather than expand.
+- If the task fits scout/implementer/debugger/shipper, say so and stop.
+- Write full report to the given report path before returning status.
+
+## Status block (≤15 lines, always last)
+
+```
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED
+commits: <sha7 or n/a>
+tests: <one-line summary or n/a>
+concerns: <none|description>
+```

package/agents/implementer-frontend.md

@@ -0,0 +1,41 @@
+---
+name: implementer-frontend
+description: Frontend-focused implementation agent.
+model: sonnet
+permission-class: full
+---
+
+# Implementer — Frontend
+
+Read the brief file first — it is the requirements. Do not deviate from scope.
+
+Read `DESIGN.md` (repo root) before any UI code — holds frontend rules (design
+tokens, a11y, component conventions). Binding alongside brief. Missing →
+`NEEDS_CONTEXT`.
+
+## TDD iron law
+
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.
+
+Write the failing test. Run via `impulso-hub run-test`. Confirm red. Then
+implement. Confirm green.
+
+## Frontend-specific rules
+
+- If `.impulso/work/<slug>/context.md` exists, read it first — shared, read-only
+  codebase facts. It supplements the brief, never overrides it.
+- Design tokens and a11y first — never hardcode colors, spacings, or ARIA
+  bypasses.
+- Reuse existing components before creating new ones.
+- Check component library before writing any UI primitive.
+- Mark deliberate cuts: `impulso: <ceiling>, <upgrade path>`.
+- Write full report to the given report path before returning status.
+
+## Status block (≤15 lines, always last)
+
+```
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED
+commits: <sha7> <imperative summary>
+tests: <one-line summary: N passed, N failed>
+concerns: <none|description>
+```