supipowers 1.2.0 → 1.2.2

package/README.md

@@ -2,166 +2,101 @@
 
 <div align="center">
 
-# Supipowers
+[![npm version](https://img.shields.io/npm/v/supipowers.svg)](https://www.npmjs.com/package/supipowers)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-[![npm version](https://img.shields.io/npm/v/supipowers?style=flat-square)](https://www.npmjs.com/package/supipowers)
-[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+**Workflow extension for OMP coding agents.**
 
-Agentic workflows for [Pi](https://github.com/mariozechner/pi-coding-agent) and [OMP](https://github.com/can1357/oh-my-pi) coding agents.
-Plan features, orchestrate sub-agents, run quality gates, fix PRs, manage MCP servers, and ship releases. All from slash commands.
-
-[Install](#install) · [Commands](#commands) · [How it works](#how-it-works) · [Configuration](#configuration) · [Development](#development)
+Plan, execute, review, test, and ship — without leaving your agent session.
 
 </div>
 
-## Install
+---
 
-```bash
-bunx supipowers@latest
-```
+Supipowers adds agentic workflow commands on top of [Oh My Pi](https://github.com/can1357/oh-my-pi). It steers the active AI session using OMP's native extension API — no subprocess, no context switching.
 
-The installer detects which agent you're running (Pi or OMP), copies supipowers into the right directory, and optionally sets up LSP servers for better code intelligence. Re-running the installer upgrades to the latest version if one is available.
+## Installation
 
-### Update from inside your agent
+Run the interactive installer:
 
-```
-/supi:update
+```bash
+bunx supipowers
 ```
 
-Checks npm for the latest version, downloads and installs it. No prompts, no restart needed.
+The installer detects your agent, registers the extension, and optionally sets up LSP servers, MCP tools, and the context-mode integration.
 
-## Requirements
+> [!TIP]
+> Run `/supi:update` at any time to upgrade to the latest version, or `/supi:doctor` to check your setup.
 
-### Required
+### Requirements
 
 | Dependency | What it's for |
 | --- | --- |
-| [Pi](https://github.com/mariozechner/pi-coding-agent) or [OMP](https://github.com/can1357/oh-my-pi) | The coding agent that supipowers extends |
-| [Bun](https://bun.sh) | Runtime (provides bun:sqlite with FTS5 for full-text search) |
-| [Git](https://git-scm.com) | Version control (used by the installer and context-mode setup) |
+| [Oh My Pi (OMP)](https://github.com/can1357/oh-my-pi) | The coding agent that supipowers extends |
+| [Bun](https://bun.sh) | Runtime — required for installation and the built-in SQLite FTS index |
+| [Git](https://git-scm.com) | Used by the installer and context-mode setup |
 
-### Optional
+### Optional dependencies
 
 The installer scans for these and offers to install any that are missing. Everything works without them, but each one unlocks additional capabilities.
 
-| Dependency | Category | What it enables | Install command |
-| --- | --- | --- | --- |
-| [mcpc](https://github.com/apify/mcpc) | MCP | MCP server management via `/supi:mcp` | `npm install -g @apify/mcpc` |
-| [context-mode](https://github.com/mksglu/context-mode) | MCP | Context window protection (auto-routes large outputs through sandboxed execution) | Installed as extension via `git clone` + `npm install` |
-| [typescript-language-server](https://github.com/typescript-language-server/typescript-language-server) | LSP | TypeScript/JavaScript diagnostics, references, completions | `bun add -g typescript-language-server typescript` |
-| [Pyright](https://github.com/microsoft/pyright) | LSP | Python type checking and language features | `pip install pyright` |
-| [rust-analyzer](https://rust-analyzer.github.io) | LSP | Rust language server | `rustup component add rust-analyzer` |
-| [gopls](https://pkg.go.dev/golang.org/x/tools/gopls) | LSP | Go language server | `go install golang.org/x/tools/gopls@latest` |
-| [playwright-cli](https://github.com/microsoft/playwright-cli) | Testing | Interactive browser exploration for E2E flow discovery via `/supi:qa --e2e` | `npm install -g @playwright/cli@latest` |
-| [Playwright Test](https://playwright.dev) | Testing | Test runner for E2E test execution via `run-e2e-tests.sh` | `npm install -g @playwright/cli@latest` |
-
-LSP servers are language-specific. You only need the ones matching the languages in your project. Sub-agents use them to check diagnostics and find references before making changes.
+| Dependency | What it enables |
+| --- | --- |
+| [mcpc](https://github.com/apify/mcpc) | MCP server management via `/supi:mcp` |
+| [context-mode](https://github.com/ogrodev/context-mode) | Context window protection — large outputs are sandboxed automatically |
+| `typescript-language-server` | TypeScript/JS diagnostics and references in review gates |
+| `pyright` | Python type checking |
+| `rust-analyzer` | Rust language server |
+| `gopls` | Go language server |
+| `@playwright/cli` | Browser exploration and E2E test execution via `/supi:qa` |
 
-> [!TIP]
-> Run `/supi:doctor` at any time to check which dependencies are installed and which are missing.
+> [!NOTE]
+> LSP servers are language-specific — install only the ones that match your project's stack.
 
 ## Commands
 
-| Command         | What it does                                          |
-| --------------- | ----------------------------------------------------- |
-| `/supi`         | Interactive menu with commands and project status     |
-| `/supi:plan`    | Collaborative planning with structured task breakdown |
-| `/supi:run`     | Execute a plan with parallel sub-agents               |
-| `/supi:review`  | Quality gates at chosen depth                         |
-| `/supi:qa`      | E2E testing pipeline with playwright-cli               |
-| `/supi:release` | Version bump, release notes, publish                  |
-| `/supi:fix-pr`  | Assess and fix PR review comments                     |
-| `/supi:mcp`     | Manage MCP servers (connect, disconnect, list)        |
-| `/supi:config`  | Interactive settings (TUI)                            |
-| `/supi:status`  | Check running sub-agents and progress                 |
-| `/supi:doctor`  | Diagnose extension health and configuration           |
-| `/supi:update`  | Update supipowers to latest version                   |
-
-Commands like `/supi`, `/supi:config`, `/supi:status`, and `/supi:update` open native TUI dialogs. They don't send chat messages or trigger the AI.
-
-### Planning
-
-```
-/supi:plan add authentication to the API
-```
-
-Starts an interactive session: clarifying questions, approach proposals, then a structured task breakdown saved to `.omp/supipowers/plans/` (or the Pi equivalent).
-
-For simple tasks, skip the brainstorming:
-
-```
-/supi:plan --quick add rate limiting middleware
-```
-
-### Running plans
-
-```
-/supi:run
-```
-
-Loads the latest plan and executes it with sub-agent orchestration. Tasks marked `[parallel-safe]` run concurrently (up to the configured limit). Sequential tasks respect their dependency chains.
-
-The orchestration loop: dispatch batch, collect results, detect conflicts, retry failures, next batch. If interrupted, re-running picks up where it left off.
-
-### Quality review
-
-```
-/supi:review           # opens profile picker
-/supi:review --quick   # fast: LSP diagnostics + AI scan
-/supi:review --thorough  # deep: full AI review + code quality
-/supi:review --full    # everything: tests + E2E + all gates
-```
-
-When no flag is provided, a TUI picker lets you choose the review profile interactively.
-
-### QA
-
-```
-/supi:qa              # opens scope picker
-/supi:qa --changed    # tests for changed files only
-/supi:qa --e2e        # Playwright / E2E only
-```
-
-Detects your test framework on first run (vitest, jest, pytest, cargo test, go test) and caches it. E2E mode (`--e2e`) uses `playwright-cli` to run browser tests autonomously. When no flag is provided, a TUI picker lets you choose the scope.
-
-### Fix PR
-
-```
-/supi:fix-pr          # auto-detects current branch PR
-/supi:fix-pr 42       # targets PR #42
-```
-
-Pulls review comments from GitHub, assesses each one (some comments deserve pushback, not code changes), then fixes what needs fixing. Tracks sessions so you can pick up where you left off.
-
-### Release
-
-```
-/supi:release
-```
-
-Analyzes commits since last tag, suggests a version bump, generates release notes, and publishes. On first run, a TUI picker lets you choose your pipeline (npm, GitHub release, or manual).
+| Command | What it does |
+| --- | --- |
+| `/supi` | Interactive menu with commands and project status |
+| `/supi:plan` | Collaborative planning with structured task breakdown |
+| `/supi:review` | Run quality gates at chosen depth |
+| `/supi:qa` | E2E testing pipeline with Playwright |
+| `/supi:fix-pr` | Assess and fix PR review comments |
+| `/supi:release` | Version bump, release notes, publish |
+| `/supi:commit` | AI-powered commit with conventional message generation |
+| `/supi:model` | Configure model assignments per action (plan, review, qa…) |
+| `/supi:context` | Show current context window usage and system prompt breakdown |
+| `/supi:mcp` | Manage MCP servers (connect, disconnect, migrate) |
+| `/supi:config` | Interactive settings TUI |
+| `/supi:status` | Check running sub-agents and progress |
+| `/supi:doctor` | Diagnose extension health and missing dependencies |
+| `/supi:update` | Update supipowers to the latest version |
+
+Commands like `/supi`, `/supi:config`, `/supi:commit`, and `/supi:status` are TUI-only — they open native dialogs without triggering the AI session.
 
-### MCP servers
+## How it works
 
-```
-/supi:mcp
-```
+**Planning.** `/supi:plan` steers the AI through planning phases (scope → decompose → estimate → verify), saves the result to `.omp/supipowers/plans/`, and presents an approval UI. On approval, tasks execute in the same session.
 
-Register, connect, and manage MCP (Model Context Protocol) servers through supipowers. Each server gets auto-generated trigger rules so the agent knows when to use its tools without being told explicitly.
+**Quality gates.** `/supi:review` runs composable checks selected by profile. LSP diagnostics surface real type errors. AI review catches logic issues. Test gates run your actual test suite. Each gate reports issues with severity levels.
 
-## How it works
+**PR fixing.** `/supi:fix-pr` fetches PR review comments, critically assesses each one, checks for ripple effects, then fixes or rejects with evidence. Bot reviewers are auto-detected and filtered out.
 
-Supipowers runs as an extension inside Pi or OMP. A platform abstraction layer handles the API differences between the two agents, so every command works the same regardless of which agent you're using.
+**Context protection.** When [context-mode](https://github.com/ogrodev/context-mode) is detected, supipowers injects routing hooks that protect the agent's context window. Large outputs, file reads, and HTTP calls are automatically routed through sandboxed execution so only summaries enter the conversation.
 
-**Sub-agent orchestration.** Plans are broken into batches of parallel-safe tasks. Each batch dispatches sub-agents with full tool access (file editing, bash, LSP). After a batch completes, the orchestrator checks for file conflicts, retries failures, and moves to the next batch.
+**Model assignment.** Each action (planning, review, QA) can be assigned a different model and thinking level. `/supi:model` opens a TUI picker backed by OMP's model registry.
 
-**Quality gates.** Composable checks selected by profile. LSP diagnostics surface real type errors. AI review catches logic issues. Test gates run your actual test suite. Gates report issues with severity levels (error, warning, info).
+## Quality profiles
 
-**LSP integration.** Sub-agents query LSP before making changes (find references, check diagnostics). If no LSP is active, everything still works, just with less precision. The installer offers to set up LSP servers during installation.
+Three built-in profiles control how much `/supi:review` checks:
 
-**Context-mode integration.** When the [context-mode](https://github.com/ogrodev/context-mode) MCP server is detected, supipowers injects routing hooks that protect the agent's context window. Large command outputs, file reads, and HTTP calls are automatically routed through sandboxed execution so only summaries enter the conversation.
+| Profile | LSP | AI Review | Code Quality | Tests | E2E |
+| --- | --- | --- | --- | --- | --- |
+| `quick` | ✓ | quick scan | — | — | — |
+| `thorough` _(default)_ | ✓ | deep | ✓ | — | — |
+| `full-regression` | ✓ | deep | ✓ | ✓ | ✓ |
 
-**Update checking.** On session start, supipowers checks npm for a newer version in the background. If one is available, a notification tells you to run `/supi:update`.
+Create custom profiles in `.omp/supipowers/profiles/`.
 
 ## Configuration
 
@@ -169,126 +104,37 @@ Supipowers runs as an extension inside Pi or OMP. A platform abstraction layer h
 /supi:config
 ```
 
-Opens an interactive settings screen. Select a setting to change its value: toggles flip instantly, selects open a picker, text fields open an input dialog.
-
-### Profiles
+Opens an interactive settings screen. Toggles flip instantly, selects open a picker, text fields open an input dialog.
 
-Three built-in profiles control quality gate depth:
+Configuration is a three-layer deep-merge (lowest to highest priority):
 
-| Profile           | LSP | AI Review   | Code Quality | Tests | E2E |
-| ----------------- | --- | ----------- | ------------ | ----- | --- |
-| `quick`           | yes | quick scan  | no           | no    | no  |
-| `thorough`        | yes | deep review | yes          | no    | no  |
-| `full-regression` | yes | deep review | yes          | yes   | yes |
-
-Create custom profiles in `.omp/supipowers/profiles/`.
-
-### Key settings
-
-```jsonc
-{
-  "defaultProfile": "thorough",
-  "orchestration": {
-    "maxParallelAgents": 3, // concurrent sub-agents per batch
-    "maxFixRetries": 2, // retry failed tasks
-    "maxNestingDepth": 2, // sub-agent nesting limit
-    "modelPreference": "auto",
-  },
-  "lsp": {
-    "setupGuide": true,
-  },
-  "qa": {
-    "framework": null, // auto-detected and cached
-    "command": null,
-  },
-}
-```
-
-Config lives in `~/.omp/agent/extensions/supipowers/` (OMP) or `~/.pi/agent/extensions/supipowers/` (Pi) and is managed entirely through `/supi:config`.
+1. Built-in defaults
+2. `~/.omp/supipowers/config.json` — global overrides
+3. `.omp/supipowers/config.json` — per-project overrides
 
 ## Skills
 
-Supipowers ships with prompt skills that commands load at runtime to steer AI sessions:
-
-| Skill                   | Used by                                |
-| ----------------------- | -------------------------------------- |
-| `planning`              | `/supi:plan`                           |
-| `code-review`           | `/supi:review`                         |
-| `debugging`             | Failure retry loop                     |
-| `qa-strategy`           | `/supi:qa`                             |
-| `fix-pr`                | `/supi:fix-pr`                         |
-| `tdd`                   | Plan tasks with test-first annotations |
-| `verification`          | Pre-completion checks                  |
-| `receiving-code-review` | Review comment assessment              |
-| `context-mode`          | Context-mode routing hooks             |
-
-Skills are markdown files in `skills/`. They're loaded on demand, not bundled at build time.
-
-## Project structure
+Supipowers ships runtime-loaded prompt skills that are also available to the agent during regular sessions:
 
-```
-src/
-  index.ts                     # extension entry + platform detection
-  bootstrap.ts                 # command registration orchestrator
-  platform/                    # dual-platform abstraction (Pi + OMP)
-    detect.ts, types.ts, pi.ts, omp.ts
-  commands/                    # one file per slash command
-    supi.ts, plan.ts, run.ts, review.ts, qa.ts, release.ts,
-    fix-pr.ts, mcp.ts, config.ts, status.ts, doctor.ts, update.ts
-  orchestrator/                # sub-agent dispatch & coordination
-    batch-scheduler.ts, dispatcher.ts, result-collector.ts,
-    conflict-resolver.ts, prompts.ts
-  planning/                    # plan writing & review prompts
-    plan-writer-prompt.ts, plan-reviewer.ts,
-    spec-reviewer.ts, prompt-builder.ts
-  quality/                     # composable quality gates
-    gate-runner.ts, lsp-gate.ts, ai-review-gate.ts, test-gate.ts
-  qa/                          # QA pipeline
-    session.ts, matrix.ts, prompt-builder.ts, config.ts
-  fix-pr/                      # PR comment assessment & fixing
-    prompt-builder.ts, config.ts, types.ts
-  mcp/                         # MCP server gateway
-    gateway.ts, registry.ts, activation.ts, triggers.ts,
-    lifecycle.ts, manager-tool.ts, mcpc.ts, config.ts
-  context-mode/                # context-mode integration
-    hooks.ts, routing.ts, detector.ts, installer.ts,
-    compressor.ts, event-store.ts, event-extractor.ts,
-    snapshot-builder.ts
-  lsp/                         # LSP integration
-    detector.ts, bridge.ts, setup-guide.ts
-  release/                     # release automation
-    analyzer.ts, notes.ts, publisher.ts
-  config/                      # configuration & profiles
-    loader.ts, profiles.ts, defaults.ts, schema.ts
-  storage/                     # persistence layer
-    plans.ts, runs.ts, reports.ts, specs.ts,
-    qa-sessions.ts, fix-pr-sessions.ts
-  notifications/               # rich inline notifications
-    renderer.ts, types.ts
-  types.ts                     # shared type definitions
-skills/                        # runtime-loaded prompt skills
-bin/
-  install.mjs                  # bunx installer
-```
+| Skill | Used by |
+| --- | --- |
+| `planning` | `/supi:plan` |
+| `code-review` | `/supi:review` |
+| `qa-strategy` | `/supi:qa` |
+| `fix-pr` | `/supi:fix-pr` |
+| `debugging` | Agent sessions |
+| `tdd` | Agent sessions |
+| `verification` | Agent sessions |
+| `receiving-code-review` | Agent sessions |
+| `context-mode` | Context window guidance |
 
 ## Development
 
 ```bash
-git clone https://github.com/ogrodev/supipowers.git
-cd supipowers
-bun install
-bun test              # run all tests
-bun run typecheck     # type checking
-bun run test:watch    # watch mode
-bun run build         # emit to dist/
+bun install          # install dependencies
+bun test             # run tests
+bun run typecheck    # type-check without emitting
+bun run build        # emit to dist/
 ```
 
-The test suite mirrors the `src/` structure under `tests/`. Tests use Bun's built-in test runner (`bun:test`) with inline mocks via `mock()`. Filesystem tests use temp directories created in `beforeEach`.
-
-> [!NOTE]
-> Supipowers works with both Pi and OMP. The platform abstraction in `src/platform/` normalizes API differences (event names, tool registration, message delivery) so you can develop against either agent.
-
-
-## License
-
-MIT
+Tests live in `tests/`, mirroring `src/` one-to-one. The test runner is Bun's built-in `bun:test`.

package/bin/install.ts

@@ -493,7 +493,12 @@ async function main(): Promise<void> {
   // ── Done ───────────────────────────────────────────────────
 
   const targetNames = targets.map((t) => t.name.toLowerCase()).join(" or ");
-  outro(`supipowers is ready! Run \`${targetNames}\` to start using it.`);
+  note(
+    "Restart OMP for the extension to take effect.\n" +
+      `Run \`${targetNames}\` in a new session to confirm /supi commands appear.`,
+    "Action required"
+  );
+  outro(`supipowers is ready!`);
 }
 
 main().catch((e) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supipowers",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Workflow extension for OMP coding agents.",
   "type": "module",
   "scripts": {
@@ -23,7 +23,10 @@
   "files": [
     "src",
     "skills",
-    "bin",
+    "bin/install.mjs",
+    "bin/install.ts",
+    "bin/local-install.sh",
+    "bin/ctx-mode-wrapper.mjs",
     "README.md",
     "LICENSE"
   ],

package/src/commands/plan.ts

@@ -151,7 +151,7 @@ export function registerPlanCommand(platform: Platform): void {
       );
 
       // Track planning state for the approval flow (agent_end hook)
-      startPlanTracking(ctx.cwd, platform.paths);
+      startPlanTracking(ctx.cwd, platform.paths, ctx.newSession?.bind(ctx));
 
       notifyInfo(ctx, "Planning started", args ? `Topic: ${args}` : "Describe what you want to build");
     },

package/src/commands/release.ts

@@ -20,6 +20,24 @@ const BUMP_OPTIONS = [
   "major — breaking changes",
 ];
 
+/**
+ * Returns true when re-running supi:release should skip the confirmation
+ * dialog and proceed directly to execution.
+ *
+ * This is the resume path: the version in package.json hasn't been tagged yet
+ * AND all channels are already configured — the user staged the release
+ * deliberately when they bumped the version, so no new decisions are needed.
+ * Dry-run is excluded because it is exploratory by intent; the user explicitly
+ * wants to preview and confirm before anything happens.
+ */
+export function isInProgressRelease(opts: {
+  skipBump: boolean;
+  channelsWerePreConfigured: boolean;
+  isDryRun: boolean;
+}): boolean {
+  return opts.skipBump && opts.channelsWerePreConfigured && !opts.isDryRun;
+}
+
 // ── Release progress tracker ────────────────────────────────────
 
 interface ReleaseStep {
@@ -241,6 +259,11 @@ export function handleRelease(platform: Platform, ctx: any, args?: string): void
       // 1. Ensure channels are configured (or detect + ask)
       progress.activate(1, "Detecting channels");
       let channels = config.release.channels;
+      // Track whether channels were already set in config before any interactive
+      // setup. This distinguishes "user already decided" from "just configured now",
+      // which determines whether we can auto-continue without a confirmation prompt.
+      const channelsWerePreConfigured = config.release.channels.length > 0;
+
       if (channels.length === 0) {
         progress.complete(1, "Awaiting selection");
         channels = await setupChannels(platform, ctx);
@@ -343,24 +366,43 @@ export function handleRelease(platform: Platform, ctx: any, args?: string): void
         return;
       }
 
-      // 7. Confirm via UI
-      const confirmLabel = isDryRun ? `[DRY RUN] Ship v${nextVersion}?` : `Ship v${nextVersion}?`;
-      const confirmDetail = [
-        `${currentVersion} → ${nextVersion}`,
-        `Channels: ${channels.join(", ")}`,
-        `Changes: ${summary}`,
-        "",
-        changelog,
-      ].join("\n");
-
-      const confirmed = ctx.ui.confirm
-        ? await ctx.ui.confirm(confirmLabel, confirmDetail)
-        : (await ctx.ui.select(confirmLabel, ["Yes \u2014 publish", "No \u2014 abort"])) === "Yes \u2014 publish";
-
-      if (!confirmed) {
-        progress.dispose();
-        notifyInfo(ctx, "Release cancelled", "No changes were made");
-        return;
+      // 7. Confirm via UI — skipped when resuming a staged unreleased release.
+      //    When skipBump is true the user already decided on the version; when
+      //    channels were pre-configured there's nothing left to decide. Asking
+      //    again is friction without benefit. Dry-run always asks because the
+      //    user explicitly opted into preview mode.
+      const isResume = isInProgressRelease({ skipBump, channelsWerePreConfigured, isDryRun });
+
+      if (isResume) {
+        notifyInfo(
+          ctx,
+          `Resuming release v${nextVersion}`,
+          "Version staged and channels configured — proceeding without confirmation",
+        );
+      } else {
+        const confirmLabel = isDryRun ? `[DRY RUN] Ship v${nextVersion}?` : `Ship v${nextVersion}?`;
+        // When skipBump=true, currentVersion === nextVersion — avoid the
+        // misleading "0.5.0 → 0.5.0" display.
+        const versionLine = skipBump
+          ? `v${nextVersion} (staged, not yet released)`
+          : `${currentVersion} → ${nextVersion}`;
+        const confirmDetail = [
+          versionLine,
+          `Channels: ${channels.join(", ")}`,
+          `Changes: ${summary}`,
+          "",
+          changelog,
+        ].join("\n");
+
+        const confirmed = ctx.ui.confirm
+          ? await ctx.ui.confirm(confirmLabel, confirmDetail)
+          : (await ctx.ui.select(confirmLabel, ["Yes \u2014 publish", "No \u2014 abort"])) === "Yes \u2014 publish";
+
+        if (!confirmed) {
+          progress.dispose();
+          notifyInfo(ctx, "Release cancelled", "No changes were made");
+          return;
+        }
       }
 
       // 8. Execute release
@@ -499,7 +541,7 @@ function buildReleaseCommands(
 ): string[] {
   const commands: string[] = [
     `git add -A`,
-    `git commit -m "release: v${version}"`,
+    `git commit -m "chore(release): v${version}"`,
     `git tag -a v${version} -m "Release v${version}"`,
     `git push origin HEAD --follow-tags`,
   ];

package/src/git/commit.ts

@@ -35,6 +35,50 @@ export interface CommitOptions {
   userContext?: string;
 }
 
+// ── Shared commit primitive ─────────────────────────────────
+
+/** Minimal exec function signature for commitStaged. */
+type ExecFn = (
+  cmd: string,
+  args: string[],
+  opts?: { cwd?: string },
+) => Promise<{ stdout: string; stderr: string; code: number }>;
+
+export interface CommitStagedResult {
+  success: boolean;
+  /** Human-readable error. Present only when success is false. */
+  error?: string;
+}
+
+/**
+ * Validate a commit message and run `git commit` on whatever is currently staged.
+ *
+ * This is the single commit primitive shared between `supi:commit` (AI-powered
+ * plans) and `supi:release` (executor). It ensures every commit in the project
+ * passes the same validation and respects any git hooks.
+ *
+ * Callers are responsible for staging files before calling this function.
+ */
+export async function commitStaged(
+  exec: ExecFn,
+  cwd: string,
+  message: string,
+): Promise<CommitStagedResult> {
+  const validation = validateCommitMessage(message);
+  if (!validation.valid) {
+    return { success: false, error: `Invalid commit message: ${validation.error}` };
+  }
+
+  const result = await exec("git", ["commit", "-m", message], { cwd });
+  if (result.code !== 0) {
+    const detail = result.stderr?.trim() || result.stdout?.trim() || `exit code ${result.code}`;
+    return { success: false, error: `git commit: ${detail}` };
+  }
+
+  return { success: true };
+}
+
+
 // ── Constants ──────────────────────────────────────────────
 
 /** Diff byte budget before we truncate */
@@ -372,20 +416,9 @@ async function manualFallback(
     return null;
   }
 
-  const validation = validateCommitMessage(message);
-  if (!validation.valid) {
-    notifyError(ctx, "Invalid commit message", validation.error);
-    return null;
-  }
-
-  const commitResult = await exec(
-    "git",
-    ["commit", "-m", message],
-    { cwd },
-  );
-
-  if (commitResult.code !== 0) {
-    notifyError(ctx, "git commit failed", commitResult.stderr || "Non-zero exit");
+  const commitResult = await commitStaged(exec, cwd, message);
+  if (!commitResult.success) {
+    notifyError(ctx, "Commit failed", commitResult.error);
     return null;
   }
 
@@ -428,27 +461,12 @@ async function executeCommitPlan(
     // Build commit message
     const message = formatCommitMessage(group);
 
-    const validation = validateCommitMessage(message);
-    if (!validation.valid) {
-      progress.dispose();
-      return reportPartialFailure(ctx, exec, cwd, committedMessages, {
-        step: `Commit ${i + 1}/${plan.commits.length}`,
-        error: `Invalid commit message: ${validation.error}\nMessage: ${message}`,
-      });
-    }
-
-    const commitResult = await exec(
-      "git",
-      ["commit", "-m", message],
-      { cwd },
-    );
-
-    if (commitResult.code !== 0) {
+    const commitResult = await commitStaged(exec, cwd, message);
+    if (!commitResult.success) {
       progress.dispose();
-      const reason = commitResult.stderr?.trim() || "git commit returned non-zero";
       return reportPartialFailure(ctx, exec, cwd, committedMessages, {
         step: `Commit ${i + 1}/${plan.commits.length}`,
-        error: `git commit failed: ${reason}`,
+        error: commitResult.error!,
       });
     }