verbalcoding 0.2.10 → 0.2.12

package/docs/superpowers/plans/2026-05-13-phase7-voice-plan-mode.md

@@ -0,0 +1,108 @@
+# Phase 7 — Voice Plan Mode Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:subagent-driven-development or superpowers:executing-plans.
+
+**Goal:** Let the user say "plan it first" and the agent returns a numbered plan, narrated step-by-step; the user can say "skip step 3", "add a test for X after step 2", or "approve" to run the modified plan.
+
+**Architecture:** Stateful plan session in `app-node/plan_mode.mjs`. The first user request is wrapped with a planning preamble in `voiceBridgePrompt`. Agent returns a numbered plan in a `PLAN_BEGIN ... PLAN_END` envelope; we parse, narrate, and listen for follow-up voice commands. Commands mutate the plan; the approval command sends the modified plan back to the agent with an "act on this plan now" preamble.
+
+**Tech Stack:** Node 20 ESM, existing adapter + sentencer, regex grammar (no external NLP).
+
+---
+
+## Spec
+
+### Plan envelope
+
+Agent returns:
+```
+PLAN_BEGIN
+1. <step>
+2. <step>
+PLAN_END
+```
+
+Parser strips envelope and yields `{ id, text, status }`.
+
+### Voice command grammar
+
+- enter: `plan it first` / `plan first` / `먼저 계획`
+- skip: `skip step N` / `step N 건너뛰어`
+- insert: `add <text> after step N` / `step N 다음에 <text> 추가`
+- approve: `approve` / `go ahead` / `실행`
+- cancel: `cancel` / `취소`
+
+### Session state
+
+`{ active: boolean, steps: Step[], language: 'en'|'ko' }` stored in `bridge_state.mjs` per channel.
+
+---
+
+## File Structure
+
+- Create: `app-node/plan_mode.mjs`, `app-node/plan_mode.test.mjs`.
+- Modify: `app-node/agent_adapters.mjs::voiceBridgePrompt` — add `planMode` branch.
+- Modify: `app-node/discord_text.mjs` and `app-node/main.mjs` — route plan-mode utterances.
+
+---
+
+## Tasks
+
+### Task 1: TDD — parsers
+
+- [ ] Write tests in `app-node/plan_mode.test.mjs`:
+  1. `parsePlanOutput` extracts numbered steps between markers.
+  2. `parseVoiceCommand` recognises skip (en + ko).
+  3. `parseVoiceCommand` recognises insert (en + ko).
+  4. `parseVoiceCommand` recognises approve in both languages.
+  5. `applyCommand` skip flips a step's status.
+  6. `applyCommand` insert places a new step after the named one.
+
+- [ ] Run, expect FAIL.
+
+### Task 2: Implement `plan_mode.mjs`
+
+- [ ] Functions to export:
+  - `parsePlanOutput(text)` — regex on `/PLAN_BEGIN\s*\n([\s\S]*?)\nPLAN_END/`, then split lines matching `^\s*(\d+)\.\s*(.+)$`.
+  - `parseVoiceCommand(text, language)` — small regex set, returns discriminated union `{ type: 'skip'|'insert'|'approve'|'cancel'|'unknown', ...}`.
+  - `applyCommand(steps, cmd)` — pure reducer.
+  - `renderFinalPlan(steps)` — re-numbers active steps for the approval prompt.
+
+- [ ] Run tests: PASS.
+- [ ] Commit: `feat(plan-mode): parsers and reducer`.
+
+### Task 3: Wire `voiceBridgePrompt`
+
+- [ ] In `agent_adapters.mjs::voiceBridgePrompt`, accept `options.planMode`. When set, append:
+  ```
+  You are in PLAN MODE. Do NOT modify any files. Reply ONLY with a plan:
+  PLAN_BEGIN
+  1. ...
+  2. ...
+  PLAN_END
+  Each step under 12 words.
+  ```
+  Korean variant included.
+- [ ] Test: `voiceBridgePrompt('do X', { planMode: true })` contains `PLAN_BEGIN`.
+- [ ] Commit.
+
+### Task 4: Bridge wiring
+
+- [ ] In `main.mjs`:
+  - Detect enter phrase → call agent with `planMode: true` → parse output → store in channel state → speak each step.
+  - Each follow-up utterance while `state.active` → `parseVoiceCommand` → mutate state OR on approve call agent again with `renderFinalPlan(...)` as the user prompt and clear state.
+- [ ] Add integration test using a fake adapter.
+- [ ] Commit.
+
+### Task 5: Document
+
+- [ ] Add a "Voice plan mode" section to `docs/USAGE.md` with example transcript.
+- [ ] Commit.
+
+---
+
+## Self-Review
+
+- Spec covered.
+- No placeholders.
+- Names consistent: `parsePlanOutput`, `parseVoiceCommand`, `applyCommand`, `renderFinalPlan`, `planMode`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verbalcoding",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "Discord voice bridge for CLI coding agents.",
   "license": "MIT",
   "repository": {
@@ -38,6 +38,7 @@
     "run.sh",
     ".env.example",
     "README.md",
+    "README.*.md",
     "LICENSE"
   ],
   "scripts": {

package/scripts/cli.mjs

@@ -32,6 +32,7 @@ function usage() {
 Usage:
   vc setup [--yes] [--no-wizard] [--skip-system] [--skip-model] [--skip-edge-tts]
   vc setup token [bot-token] [--client-id <client-id>]
+  vc setup channels [voice-channel[,voice-channel...]]
   vc start
   vc status
   vc language <ko|en|auto>
@@ -47,9 +48,11 @@ Usage:
   vc doctor
 
 Examples:
-  npx verbalcoding setup --yes
-  vc setup --yes
-  vc setup token
+  npx verbalcoding setup
+  vc setup
+  vc setup --yes        # automation/non-interactive starter config
+  vc setup token        # later token update
+  vc setup channels "General,Team Voice"
   vc start
   vc language en
   vc language ko
@@ -277,7 +280,7 @@ async function main(argv = process.argv.slice(2)) {
   }
   if (command === 'setup' || command === 'install') {
     const { spawnSync } = await import('node:child_process');
-    if (argv[1] === 'token' || argv[1] === 'discord' || argv[1] === 'bot-token') {
+    if (['token', 'discord', 'bot-token', 'channels', 'channel', 'voice'].includes(argv[1])) {
       const result = spawnSync(process.execPath, [path.join(ROOT, 'scripts', 'install.mjs'), ...argv.slice(1)], { stdio: 'inherit', cwd: ROOT });
       process.exitCode = result.status ?? 1;
       return;

package/scripts/doctor.mjs

@@ -5,6 +5,7 @@ import { spawnSync } from 'node:child_process';
 import { parseKeyValueEnv } from '../app-node/install_config.mjs';
 import { checkInstanceConfigs, formatInstanceDoctor } from '../app-node/instance_doctor.mjs';
 import { autoRestartVoiceBotEnabled } from '../app-node/restart_policy.mjs';
+import { detectInstalledAgents, formatAgentDetectionReport } from '../app-node/agent_detect.mjs';
 
 const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
 const args = process.argv.slice(2);
@@ -210,6 +211,16 @@ if (!autoFixEnabled) note('Automatic prerequisite bootstrap', 'off');
 if (autoFixAttempted) note('Automatic prerequisite bootstrap', 'attempted');
 console.log('');
 
+try {
+  const detection = await detectInstalledAgents(env);
+  console.log(formatAgentDetectionReport(detection));
+  const selected = detection.find(r => r.backend === backend || r.backend === backend.replace(/-/g, ''));
+  if (selected && !selected.present) note(`Selected backend "${backend}"`, `binary ${selected.bin} not on PATH`);
+  console.log('');
+} catch (e) {
+  note('Agent backend detection', `skipped: ${e?.message || e}`);
+}
+
 const nodeCommand = commandExists('node');
 const npmCommand = commandExists('npm');
 const ffmpegCommand = commandExists('ffmpeg');

package/scripts/install.mjs

@@ -4,6 +4,7 @@ import path from 'node:path';
 import readline from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import { buildEnvFile, normalizeInstallAnswers, renderInstallSummary, SUPPORTED_HARNESSES } from '../app-node/install_config.mjs';
+import { detectInstalledAgents, pickDefaultBackend, formatAgentDetectionReport } from '../app-node/agent_detect.mjs';
 
 const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
 
@@ -76,12 +77,41 @@ async function configureDiscordToken(args) {
   if (clientId) console.log(`Invite URL: vc bot invite ${clientId}`);
 }
 
+async function configureAutoJoinChannels(args) {
+  const envPath = path.join(ROOT, '.env');
+  let channels = args.find((arg, idx) => idx > 0 && !arg.startsWith('--')) || argValue(args, '--channels') || argValue(args, '--voice');
+  if (!channels) {
+    globalThis.__rl = readline.createInterface({ input, output });
+    try {
+      console.log('Discord auto-join voice channel setup');
+      console.log('Enter one or more voice channel names, comma-separated. Example: General,Team Voice,일반');
+      channels = await ask('Auto-join voice channel names', process.env.AUTO_JOIN_VOICE_CHANNELS || 'General,general');
+    } finally {
+      globalThis.__rl.close();
+      globalThis.__rl = null;
+    }
+  }
+  if (!channels) {
+    console.error('No voice channel names provided. Nothing changed.');
+    process.exitCode = 2;
+    return;
+  }
+  upsertEnvFile(envPath, { AUTO_JOIN_VOICE_CHANNELS: channels });
+  console.log(`Updated ${envPath}`);
+  console.log(`Auto-join voice channels: ${channels}`);
+  console.log('Restart the bridge for this to take effect. You can update it anytime with `vc setup channels`.');
+}
+
 async function main() {
   const args = process.argv.slice(2);
   if (args[0] === 'token' || args[0] === 'discord' || args[0] === 'bot-token') {
     await configureDiscordToken(args);
     return;
   }
+  if (args[0] === 'channels' || args[0] === 'channel' || args[0] === 'voice') {
+    await configureAutoJoinChannels(args);
+    return;
+  }
   const yes = args.includes('--yes') || args.includes('-y');
   if (args[0] === 'instance' || args.includes('--instance')) {
     const { spawnSync } = await import('node:child_process');
@@ -109,7 +139,20 @@ async function main() {
   try {
     console.log('VerbalCoding installer');
     console.log(`Supported harnesses: ${SUPPORTED_HARNESSES.join(', ')}`);
-    const harness = await ask('Harness/backend', 'hermes');
+    console.log('Discord setup: keep https://discord.com/developers/applications open.');
+    console.log('Create an application/bot, enable Message Content intent, then paste the bot token and application/client ID below.');
+    console.log('If you are not ready, press Enter to skip and run `vc setup token` / `vc setup channels` later.');
+    let detectionDefault = 'hermes';
+    try {
+      const detection = await detectInstalledAgents(process.env);
+      console.log('');
+      console.log(formatAgentDetectionReport(detection));
+      detectionDefault = pickDefaultBackend(detection, process.env.AGENT_BACKEND);
+      console.log('');
+    } catch (e) {
+      console.log(`(agent detection skipped: ${e?.message || e})`);
+    }
+    const harness = await ask('Harness/backend', detectionDefault);
     let agentCommand = '';
     let agentLabel = '';
     if (harness.toLowerCase() === 'custom') {