impulso 0.19.1

package/shared/orchestration-config.cjs

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+// impulso-orchestration — shared roster, models, phases, and routes
+//
+// Single source of truth for agent orchestration config. Consumed by
+// impulso-hub, both harnesses, and any skill that routes work to
+// specialist agents.
+//
+// resolveModels/resolveEffort take a REQUIRED `harness` (claude|opencode) and
+// resolve that harness's block. Ladder (highest to lowest):
+//   projectDir/.impulso/models.json[harness] >
+//   homeDir/.impulso/models.json[harness] > DEFAULT_MODELS[harness].
+// Hard-fails on bad JSON, bad harness, or unknown keys — no silent fallback.
+// Values are either a model string ("sonnet") or an object
+// ({ "model": "sonnet", "effort": "high" }); fields merge per-key down the
+// ladder, so an effort-only override keeps the lower-rung model.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// -----------------------------------------------------------------------
+// ROSTER
+// Ordered: name -> { description, tools, permissionClass, variant?, routingBlurb }
+// -----------------------------------------------------------------------
+const ROSTER = {
+  ImpulsoOrchestrator: {
+    description: 'Routes tasks to specialist agents.',
+    permissionClass: 'dispatch-only',
+    routingBlurb: 'Dispatch hub; no direct file/tool access.',
+  },
+  scout: {
+    description: 'Read-only codebase explorer.',
+    permissionClass: 'read-only',
+    routingBlurb: 'Explore, locate, report — no writes.',
+  },
+  'scout-writer': {
+    description: 'Read-only explorer that writes the shared context pack.',
+    permissionClass: 'read-only',
+    routingBlurb: 'Explore + write context.md; workspace writes only.',
+  },
+  planner: {
+    description: 'Produces specs and implementation plans.',
+    permissionClass: 'read-only',
+    routingBlurb: 'Plan artifacts only; scout handles exploration.',
+  },
+  implementer: {
+    description: 'General-purpose implementation agent.',
+    permissionClass: 'full',
+    routingBlurb: 'Code, tests, refactors — no frontend/infra specialization.',
+  },
+  'implementer-frontend': {
+    description: 'Frontend-focused implementation agent.',
+    permissionClass: 'full',
+    variant: 'frontend',
+    routingBlurb: 'UI, CSS, component trees, browser APIs.',
+  },
+  'implementer-infra': {
+    description: 'Infrastructure and ops implementation agent.',
+    permissionClass: 'full',
+    variant: 'infra',
+    routingBlurb: 'Terraform, K8s, CI/CD, cloud config.',
+  },
+  reviewer: {
+    description: 'Reviews code changes (task-level and branch-level).',
+    permissionClass: 'read-only',
+    routingBlurb: 'Code review; read-only.',
+  },
+  debugger: {
+    description: 'Root-cause analysis and bug fixes.',
+    permissionClass: 'full',
+    routingBlurb: 'Reproduce, isolate, fix — systematic debugging.',
+  },
+  shipper: {
+    description: 'Commits, pushes, opens PRs.',
+    permissionClass: 'git-only',
+    routingBlurb: 'Git operations only; no arbitrary file writes.',
+  },
+  generalist: {
+    description: 'Catch-all for tasks without a specialist fit.',
+    permissionClass: 'full',
+    routingBlurb: 'Broad-capability; prefer specialists when type is known.',
+  },
+};
+
+// -----------------------------------------------------------------------
+// DISABLED_BUILTINS
+// opencode built-in subagents impulso disables at config-write time to prevent
+// the LLM orchestrator from dispatching a built-in (no impulso rules, no rtk,
+// no path-guard) instead of an impulso-owned roster agent. `scout` is NOT
+// listed: impulso's own `scout` registration overrides the built-in by name.
+// -----------------------------------------------------------------------
+const DISABLED_BUILTINS = ['explore', 'general'];
+
+// -----------------------------------------------------------------------
+// DEFAULT_MODELS, ROUTES, PHASES
+// Load from orchestration-data.json
+// -----------------------------------------------------------------------
+const {
+  routes: ROUTES,
+  phases: PHASES,
+  defaultModels: DEFAULT_MODELS,
+} = require('./orchestration-data.json');
+
+// -----------------------------------------------------------------------
+// EFFORT_LEVELS
+// Claude Code's per-subagent effort enum. opencode receives the value as a
+// reasoningEffort provider-passthrough; interpretation is provider-specific.
+// -----------------------------------------------------------------------
+const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
+
+// -----------------------------------------------------------------------
+// _resolveTuning
+// (projectDir, harness, homeDir) -> { models, effort } merged maps
+// `harness` is REQUIRED — the valid set is Object.keys(DEFAULT_MODELS).
+// Ladder: project > home > DEFAULT_MODELS[harness]. Values are a model string
+// or a { model?, effort? } object; fields merge per-key down the ladder.
+// Only the `harness` block of each models.json contributes overrides, but the
+// whole-file top-level key check runs regardless (catches the flat/legacy
+// shape). `effort` inside a claude block is a hard error (Claude Code effort
+// comes from agent frontmatter). Unknown keys/fields, invalid effort, bad
+// harness, or malformed JSON = throw.
+// -----------------------------------------------------------------------
+function _resolveTuning(projectDir, harness, homeDir) {
+  // Invalid harness arg → throw before reading any files.
+  if (!(harness in DEFAULT_MODELS)) {
+    throw new Error(
+      `orchestration-config: harness must be one of: ${Object.keys(DEFAULT_MODELS).join(', ')} (got ${JSON.stringify(harness)})`,
+    );
+  }
+
+  const block = DEFAULT_MODELS[harness];
+
+  // Apply lowest-priority first so higher-priority overwrites
+  const ladder = [path.join(homeDir, '.impulso', 'models.json')];
+
+  const models = Object.assign({}, block);
+  const effort = {};
+  for (const key of Object.keys(block)) effort[key] = null;
+
+  for (const filePath of ladder) {
+    if (!fs.existsSync(filePath)) continue;
+
+    let raw;
+    try {
+      raw = fs.readFileSync(filePath, 'utf8');
+    } catch (e) {
+      throw new Error(`orchestration-config: cannot read ${filePath}: ${e.message}`);
+    }
+
+    let overrides;
+    try {
+      overrides = JSON.parse(raw);
+    } catch (e) {
+      throw new Error(`orchestration-config: invalid JSON in ${filePath}: ${e.message}`);
+    }
+
+    // Whole-file top-level key check — every top-level key must be a known
+    // harness. Catches the flat/legacy shape (e.g. { "planner": "opus" })
+    // regardless of which harness is being resolved.
+    for (const key of Object.keys(overrides)) {
+      if (!(key in DEFAULT_MODELS)) {
+        throw new Error(
+          `orchestration-config: unknown top-level key "${key}" in ${filePath} — models.json is now harness-partitioned: wrap keys under a "claude" or "opencode" block`,
+        );
+      }
+    }
+
+    // Descend ONLY the resolved harness's block; absent block → no overrides.
+    const blockOverrides = overrides[harness];
+    if (blockOverrides === null || typeof blockOverrides !== 'object') continue;
+
+    for (const key of Object.keys(blockOverrides)) {
+      if (!(key in block)) {
+        throw new Error(
+          `orchestration-config: unknown model key "${key}" in the "${harness}" block of ${filePath}`,
+        );
+      }
+
+      const value = blockOverrides[key];
+      if (typeof value === 'string' || value === null) {
+        models[key] = value;
+        continue;
+      }
+      if (typeof value !== 'object') {
+        throw new Error(
+          `orchestration-config: value for "${key}" in the "${harness}" block of ${filePath} must be a string or { model?, effort? } object`,
+        );
+      }
+      for (const field of Object.keys(value)) {
+        if (field !== 'model' && field !== 'effort') {
+          throw new Error(
+            `orchestration-config: unknown field "${field}" for "${key}" in the "${harness}" block of ${filePath}`,
+          );
+        }
+      }
+      if ('model' in value) {
+        if (typeof value.model !== 'string' || value.model === '') {
+          throw new Error(
+            `orchestration-config: model for "${key}" in the "${harness}" block of ${filePath} must be a non-empty string`,
+          );
+        }
+        models[key] = value.model;
+      }
+      if ('effort' in value) {
+        if (harness === 'claude') {
+          throw new Error(
+            `orchestration-config: "effort" is not supported in the "claude" block (key "${key}" in ${filePath}) — Claude Code effort comes from agents/<name>.md frontmatter, not models.json`,
+          );
+        }
+        if (value.effort !== null && !EFFORT_LEVELS.includes(value.effort)) {
+          throw new Error(
+            `orchestration-config: invalid effort "${value.effort}" for "${key}" in the "${harness}" block of ${filePath} — must be one of: ${EFFORT_LEVELS.join(', ')}`,
+          );
+        }
+        effort[key] = value.effort;
+      }
+    }
+  }
+
+  return { models, effort };
+}
+
+// -----------------------------------------------------------------------
+// resolveModels
+// (projectDir, harness, homeDir?) -> merged models map (model strings only)
+// -----------------------------------------------------------------------
+function resolveModels(projectDir, harness, homeDir) {
+  if (homeDir === undefined) homeDir = process.env.IMPULSO_HOME ?? os.homedir();
+  return _resolveTuning(projectDir, harness, homeDir).models;
+}
+
+// -----------------------------------------------------------------------
+// resolveEffort
+// (projectDir, harness, homeDir?) -> merged effort map (EFFORT_LEVELS value or
+// null; null = inherit the session/dispatch default)
+// -----------------------------------------------------------------------
+function resolveEffort(projectDir, harness, homeDir) {
+  if (homeDir === undefined) homeDir = process.env.IMPULSO_HOME ?? os.homedir();
+  return _resolveTuning(projectDir, harness, homeDir).effort;
+}
+
+// -----------------------------------------------------------------------
+// PERMISSION_CLASSES
+// Class names are the single source of truth consumed by sync-agents (membership
+// validation) and orchestration/index.js (SDK permission mapping).
+// The allowed/denied tool lists were removed — they were only consumed by tests
+// and nothing runtime uses the values; opencode uses the SDK permission schema
+// (edit, bash) mapped in buildPermission().
+// -----------------------------------------------------------------------
+const PERMISSION_CLASSES = {
+  'read-only': {},
+  full: {},
+  'git-only': {},
+  'dispatch-only': {},
+};
+
+// -----------------------------------------------------------------------
+// phaseReminderLine
+// Pure function of inputs — byte-stable for prompt caching.
+// -----------------------------------------------------------------------
+function phaseReminderLine(phase, taskInfo) {
+  let line = `IMPULSO PIPELINE: phase ${phase}`;
+  if (taskInfo !== undefined && taskInfo !== null) {
+    line += `, task ${taskInfo}`;
+  }
+  line += '. Gates enforced by impulso-hub.';
+  return line;
+}
+
+module.exports = {
+  ROSTER,
+  DISABLED_BUILTINS,
+  DEFAULT_MODELS,
+  EFFORT_LEVELS,
+  resolveModels,
+  resolveEffort,
+  PERMISSION_CLASSES,
+  ROUTES,
+  PHASES,
+  phaseReminderLine,
+};

package/shared/orchestration-data.json

@@ -0,0 +1,48 @@
+{
+  "routes": {
+    "trivial": [],
+    "small": ["plan", "implement", "verify"],
+    "feature": ["brainstorm", "spec", "plan", "implement", "verify", "ship"],
+    "debug": ["debug"],
+    "question": []
+  },
+  "phases": {
+    "brainstorm": { "requires": ["artifact:brainstorm.md"] },
+    "spec": { "requires": ["artifact:spec.md", "spec-confirmed"] },
+    "plan": { "requires": ["artifact:plan.md", "plannotator:plan.md"] },
+    "implement": { "requires": ["tasks-complete"] },
+    "verify": {
+      "requires": ["suite-green", "coverage-pass", "review-clean", "plannotator-review"]
+    },
+    "ship": { "requires": ["pr-recorded"] },
+    "debug": { "requires": [] }
+  },
+  "defaultModels": {
+    "claude": {
+      "scout": "haiku",
+      "scout-writer": "haiku",
+      "planner": "opus",
+      "implementer": "sonnet",
+      "implementer-frontend": "sonnet",
+      "implementer-infra": "sonnet",
+      "reviewer": "opus",
+      "debugger": "sonnet",
+      "shipper": "haiku",
+      "generalist": "sonnet",
+      "ImpulsoOrchestrator": null
+    },
+    "opencode": {
+      "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",
+      "ImpulsoOrchestrator": null
+    }
+  }
+}

package/shared/state-guard.cjs

@@ -0,0 +1,56 @@
+'use strict';
+// impulso shared state-guard — detects bash commands that touch gate-owned
+// state paths (.impulso/work/*/state.json or .impulso/active).
+//
+// Shared between the Claude Code bash-state-guard hook and the opencode
+// orchestration before-hook so the pattern cannot drift between harnesses.
+
+// Primary regex: word-boundary-adjacent reference to gate-owned state paths.
+// Applied to the lowercase copy of the command string.
+// Trailing terminator class extended to cover shell separators that were
+// previously missing: ; ) & |
+const STATE_FILE_RE = /(^|[\s'"=/])\.impulso\/(work\/[^\s'"\/]+\/state\.json|active)([\s'";)&|]|$)/;
+
+// isStateGuardHit — returns true if the command string references a
+// gate-owned path.  Two checks:
+//   1. Primary regex — covers direct references, shell redirections, pipes.
+//   2. Co-occurrence — catches dot-segment bypasses like
+//      `.impulso/work/x/./state.json` where the primary regex can't follow /./
+//      and `.impulso/active` bypasses where the trailing char (;, ), &, |)
+//      was not in the original class.
+function isStateGuardHit(command) {
+  const lower = command.toLowerCase();
+  if (STATE_FILE_RE.test(lower)) return true;
+  // Dot-segment bypass: both tokens appear but the path separator sequence
+  // breaks the primary regex
+  if (lower.includes('.impulso') && lower.includes('state.json')) return true;
+  // Active-file co-occurrence: .impulso + /active with word boundary
+  // (avoids false positives on .impulso/activesomething where the next char
+  // is a word character, since \b won't fire there)
+  if (lower.includes('.impulso') && /\/active\b/.test(lower)) return true;
+  return false;
+}
+
+// isGateInvocation — returns true when every segment of the command that
+// references a gate-owned state path is itself an impulso-hub invocation.
+//
+// The command is split on shell separators (&&, ||, ;, |, newline).
+// Each segment that touches a gate-owned path must match the gate-executable
+// pattern; segments that do not reference state are ignored.
+// For commands with no state reference at all this is trivially true.
+function isGateInvocation(command) {
+  // Split on shell separators — simple split, no full shell parsing.
+  const segments = command.split(/&&|\|\||[;|\n]/);
+  // Gate-executable pattern: segment trimmed, starts with impulso-hub or
+  // node ...scripts/impulso-hub.cjs as the executable.
+  const GATE_RE = /(^|\s)(impulso-hub)\b/;
+  for (const seg of segments) {
+    // Only scrutinise segments that reference a gate-owned state path.
+    if (!isStateGuardHit(seg)) continue;
+    // This segment references state — it must itself be a gate invocation.
+    if (!GATE_RE.test(seg.trim())) return false;
+  }
+  return true;
+}
+
+module.exports = { isStateGuardHit, isGateInvocation, STATE_FILE_RE };

package/shared/tokensave-freshness.cjs

@@ -0,0 +1,62 @@
+// impulso tokensave-freshness — freshness reconciliation for the tokensave index
+//
+// SPIKE findings: SQLite .tokensave/tokensave.db mtime is unreliable as a
+// reindex signal — WAL-mode in-place page updates may not bump the db file
+// mtime. Decision: use max(mtime of all files in .tokensave/ excluding the
+// stale marker itself) as the reference time. Any file written by a reindex
+// (WAL, SHM, journal, or the db itself) advances this high-water mark.
+//
+// Interface:
+//   module.exports.reconcile(tokensaveDir) -> { stale: boolean, since?: string }
+//     Deletes the stale marker as a side effect when the index is newer.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function reconcile(tokensaveDir) {
+  const markerPath = path.join(tokensaveDir, 'stale');
+
+  // No marker → not stale (nothing to reconcile)
+  let markerStat;
+  try {
+    markerStat = fs.statSync(markerPath);
+  } catch (_) {
+    return { stale: false };
+  }
+
+  // Reference mtime: newest file in tokensaveDir, excluding the stale marker
+  let refMtime = 0;
+  try {
+    const files = fs.readdirSync(tokensaveDir);
+    for (const f of files) {
+      if (f === 'stale') continue;
+      try {
+        const m = fs.statSync(path.join(tokensaveDir, f)).mtimeMs;
+        if (m > refMtime) refMtime = m;
+      } catch (_) {}
+    }
+  } catch (_) {}
+
+  const markerMtime = markerStat.mtimeMs;
+
+  if (refMtime >= markerMtime) {
+    // Index is at least as fresh as the marker → reconciled; delete marker
+    try {
+      fs.unlinkSync(markerPath);
+    } catch (_) {}
+    return { stale: false };
+  }
+
+  // Marker is newer than any index file → stale
+  let since;
+  try {
+    since = fs.readFileSync(markerPath, 'utf8').split('\n')[0].trim();
+  } catch (_) {
+    since = new Date(markerMtime).toISOString();
+  }
+  return { stale: true, since };
+}
+
+module.exports = { reconcile };

package/skills/impulso-address-pr-comments/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: impulso-address-pr-comments
+description:
+  Fetch PR review comments from bots and humans, triage with per-comment
+  approval, apply fixes, commit, reply, and resolve threads
+---
+
+# Impulso Address PR Comments
+
+Detect PR → fetch all comment sources → present bot/human tables → per-comment
+approval → apply fixes → commit → reply + resolve threads → report. Zero-arg;
+`gh` CLI only, no MCP.
+
+## MUST
+
+1. **Detect PR** — resolve the PR for the current branch:
+
+   ```bash
+   gh pr view --json number,url,title,headRefName,baseRefName
+   ```
+
+   No PR on the branch → stop: "No open PR found for this branch." Derive the
+   repo:
+
+   ```bash
+   gh repo view --json nameWithOwner --jq '.nameWithOwner'
+   ```
+
+   Call the result `REPO` (`owner/name`) and the PR number `PR` in the steps
+   below.
+
+2. **Fetch all comment sources**, inline (no subagent dispatch):
+
+   ```bash
+   # Reviews
+   gh api repos/<REPO>/pulls/<PR>/reviews --paginate --jq \
+     '.[] | {id, state, body, reviewer: .user.login, is_bot: (.user.type=="Bot")}'
+
+   # Inline (file/line) comments
+   gh api repos/<REPO>/pulls/<PR>/comments --paginate --jq \
+     '.[] | {id, path, line, body, diff_hunk, reviewer: .user.login, is_bot: (.user.type=="Bot"), in_reply_to_id}'
+
+   # Issue-level (PR conversation) comments — catches bot walkthroughs posted
+   # outside a formal review
+   gh api repos/<REPO>/issues/<PR>/comments --paginate --jq \
+     '.[] | {id, body, reviewer: .user.login, is_bot: (.user.type=="Bot")}'
+
+   # Review threads, for resolving later (OWNER/REPO_NAME split from REPO)
+   OWNER="${REPO%%/*}"; REPO_NAME="${REPO#*/}"
+   gh api graphql -f query='
+     query($owner: String!, $repo: String!, $pr: Int!) {
+       repository(owner: $owner, name: $repo) {
+         pullRequest(number: $pr) {
+           reviewThreads(first: 100) {
+             nodes {
+               id
+               isResolved
+               comments(first: 1) { nodes { databaseId } }
+             }
+           }
+         }
+       }
+     }' -f owner=<OWNER> -f repo=<REPO_NAME> -F pr=<PR> --jq \
+     '.data.repository.pullRequest.reviewThreads.nodes[] | {thread_id: .id, is_resolved: .isResolved, root_comment_id: .comments.nodes[0].databaseId}'
+   ```
+
+   Classify every comment by `user.type=="Bot"` — bot or human, grouped/labeled
+   by literal login (no hardcoded bot allowlist). Group human inline replies by
+   `in_reply_to_id`; address the root thread, not each reply individually. No
+   comments found anywhere → report and stop.
+
+3. **Present** — group bot vs human. Every comment gets a uniform severity:
+   **blocker / high / medium / low**. Human comments add an **Intent** column
+   (orthogonal to severity): bug catch / style nit / design question /
+   clarification needed / blocking.
+
+   | #   | Source | Reviewer | File | Line | Severity | Intent | Suggested fix |
+   | --- | ------ | -------- | ---- | ---- | -------- | ------ | ------------- |
+
+   (Intent column applies to human rows only.)
+
+4. **Iterate + approve**, one comment at a time. Assess each technically before
+   proposing a fix — if a suggestion is wrong, say so. Show file, line, diff
+   hunk, and the full comment text. No file edits during this step — collect
+   every decision first. Nothing is applied without explicit per-comment
+   approval.
+
+   - Bot comment options: **Accept** / **Deny** / **Custom**.
+   - Human comment options: **Fix it** / **Reply only** / **Fix and reply** /
+     **Skip** / **Discuss**.
+
+5. **Apply** — once every comment has a decision: read each affected file, apply
+   the approved fixes with Edit, and show each change made.
+
+6. **Commit** — run `git log --oneline -5` first to confirm the branch's actual
+   commit convention. Branch name matches `[A-Z]+-\d+`:
+
+   ```
+   type(JIRA-KEY): address PR review feedback
+   ```
+
+   Otherwise:
+
+   ```
+   type: address PR review feedback
+   ```
+
+   One commit for all applied fixes, then push.
+
+7. **Reply + resolve** — reply to every comment, bot and human alike (replies ≤2
+   sentences):
+
+   | Action              | Reply                              | Resolve thread |
+   | ------------------- | ---------------------------------- | -------------- |
+   | Fixed               | `Fixed: <what changed>`            | Yes            |
+   | Fix and reply       | `Fixed: <what changed>. <context>` | Yes            |
+   | Reply only          | `<why no change needed>`           | No             |
+   | Skipped (invalid)   | `Not applicable: <reason>`         | Yes            |
+   | Skipped (by design) | `By design: <reason>`              | Yes            |
+
+   Inline reply:
+
+   ```bash
+   gh api repos/<REPO>/pulls/<PR>/comments -f in_reply_to=<ID> -f body='<reply>'
+   ```
+
+   Issue-level (PR conversation) reply:
+
+   ```bash
+   gh api repos/<REPO>/issues/<PR>/comments -f body='<reply>'
+   ```
+
+   Resolve a thread:
+
+   ```bash
+   gh api graphql -f query='mutation { resolveReviewThread(input: {threadId: "<thread_id>"}) { thread { id isResolved } } }'
+   ```
+
+8. **Report** — summary counts (bot / human, each: fixed / replied / skipped)
+   plus a per-comment action table:
+
+   | #   | Source | File | Line | Severity | Action | Summary |
+   | --- | ------ | ---- | ---- | -------- | ------ | ------- |
+
+   Offer to re-request review:
+
+   ```bash
+   gh pr edit <PR> --add-reviewer <reviewer>
+   ```
+
+## Error handling
+
+| Scenario               | Action                                    |
+| ---------------------- | ----------------------------------------- |
+| No PR on branch        | Stop: "No open PR found for this branch." |
+| No comments found      | Report and stop.                          |
+| `gh` not authenticated | Tell user to run `gh auth login`.         |
+| Bot login varies       | Filter on `user.type=="Bot"`.             |
+| API rate limiting      | Report, suggest waiting.                  |

package/skills/impulso-brainstorm/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: impulso-brainstorm
+description: >
+  Invoke at feature-route start: init the workspace, grill the user (batch
+  independent questions; ask dependent decisions one at a time), record
+  decisions to brainstorm.md, and advance to the spec phase.
+---
+
+# Impulso Brainstorm
+
+Deterministic state/precondition validation and status `--json` schema v1 are
+owned by `impulso-hub`; this skill retains human interview, dispatch, and
+decision logging policy.
+
+Feature-route entry. Init workspace → grill user → write decision log → advance.
+
+## MUST
+
+1. Derive `<slug>` (kebab-case, ≤40 chars) from the feature name. Run:
+
+   ```bash
+   impulso-hub init <slug> --route feature
+   ```
+
+   Exit 2 with "test_cmd required": run
+   `impulso-hub config set test_cmd "<project test command>"` then retry.
+
+2. Run the brainstorm protocol. Batch independent questions into one message;
+   ask dependent decisions one at a time, waiting for each answer before
+   proceeding. Say verbatim first:
+
+   > Interview me relentlessly about every aspect of this plan until we reach a
+   > shared understanding. For each question, provide your recommended answer.
+
+   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 via scout. Decisions go to the human. Do not enact
+   the plan until user confirms shared understanding reached.
+
+3. Write a terse decision log:
+
+   ```bash
+   BRAINSTORM_PATH=$(impulso-hub workspace-path --brainstorm)
+   # Write brainstorm.md at $BRAINSTORM_PATH
+   # Format: one bullet per decision: - <decision>: <rationale ≤10 words>
+   # No filler, no prose preamble.
+   ```
+
+4. Run `impulso-hub advance`. Exit 2 = read stderr, satisfy precondition, retry.