@ttfw/envoi 1.0.0

package/README.md

@@ -0,0 +1,238 @@
+# Envoi
+
+Deterministic repo-local orchestration for AI implementation loops: **planner -> builder -> checker**.
+
+Envoi is for teams that want:
+- fast delivery with AI agents,
+- strict safety boundaries,
+- auditable artifacts per cycle,
+- low-friction human control.
+
+## Product Narrative
+- Product name: **Envoi**.
+- `tick` is the core mechanic: one bounded execution cycle.
+- Human role stays plain: decide, approve, unblock.
+- “Taste” appears in microcopy, not in role names.
+
+Human-facing guidance uses:
+- `Needs you: choose direction.`
+- `Your call: accept, adjust, or undo.`
+- `Taste check: does this feel right?` (only when necessary)
+- `Waiting for you`
+
+## Core Invariant
+`envoi tick` executes exactly one finite cycle:
+1. lock + preflight,
+2. one planner decision,
+3. one builder execution,
+4. one checker pass,
+5. one persisted `REPORT.json` (+ optional `REPORT.md`).
+
+Use `envoi loop` only when you intentionally want multiple ticks.
+
+## Command Surface (7 Verbs)
+- `envoi start` — one-command scaffold + guided onboarding
+- `envoi brief` — onboarding alias (same flow, no tour prompt)
+- `envoi tick` — one bounded cycle (plan -> edit -> verify -> stop)
+- `envoi loop` — run multiple ticks until boundary
+- `envoi status` — current state + context
+- `envoi check` — environment + constraints health
+- `envoi undo` — rollback tracked files to last recorded base snapshot
+
+Optional bridge:
+- `envoi app` — open desktop app when available, otherwise show benefits + link
+
+### Compatibility During Transition
+Legacy command aliases are still accepted and automatically mapped to the new command set.
+
+Existing installs can move forward with:
+- `envoi update --dry-run`
+- `envoi update --yes`
+
+## Quickstart
+### One command for Claude/Codex
+```bash
+npx -y @ttfw/envoi@latest start
+```
+
+This runs Envoi without a global install and starts guided onboarding in the current repo.
+
+### 1) Install
+Development-linked install:
+```bash
+cd /path/to/envoi
+pnpm build
+pnpm link --global
+```
+
+Repo-local install:
+```bash
+cd /path/to/target-repo
+pnpm add /path/to/envoi
+```
+
+### 2) Run guided onboarding
+```bash
+cd /path/to/target-repo
+envoi start
+```
+
+`envoi start` handles onboarding end-to-end:
+1. asks `Tour` vs `Setup`,
+2. captures PRD/context (`--prd-file`, stdin, discovered file, editor, or inline paste),
+3. configures mode (`task|milestone|autonomous`) and builder (`cursor|claude_code`),
+4. optionally enables reviewer (`none|codex`),
+5. runs role connectivity checks,
+6. writes `ROADMAP.json` from the planner snapshot,
+7. asks whether to start execution now.
+
+### 3) Run manually later (optional)
+```bash
+envoi check
+envoi tick
+# or
+envoi loop --mode milestone
+```
+## Loop Modes + Follow-up Paths
+- `task`: stops at task completion boundary
+- `milestone`: stops at milestone boundary/completion
+- `autonomous`: continues across milestones until blocked/limit/signal
+
+Boundary outputs are explicit:
+- task/milestone => `STANDBY` with next command
+- autonomous => continues unless safety boundary triggers
+
+## PM-Style Idea Intake (No Technical Burden on User)
+Capture new ideas between boundaries:
+```bash
+envoi idea "Preview changes before publish"
+envoi idea "Need staging validation faster" --testability soon --target-by 2026-03-01
+```
+
+Ideas are persisted in state (`idea_inbox`) and fed into planner decisions.
+Planner should choose sequencing, scope, and timing; user should not be forced into low-level technical choices.
+Planner snapshots are written to ROADMAP.json and refreshed by onboarding when needed.
+
+## Optional Reviewer Gate
+When configured, reviewer can:
+- allow proceed,
+- force stop before build (`STOP_REVIEWER_FORCED_PATCH`),
+- ask product question (`STOP_REVIEWER_ASK_QUESTION`).
+
+This reduces rework on touchy tasks while keeping human control clear.
+
+## Verdict Labels (Display Layer)
+Canonical machine values remain unchanged (`success|stop|blocked`, `STOP_*`, `BLOCKED_*`).
+Display labels in CLI/report copy map to:
+- `CLEARED`
+- `STANDBY`
+- `BLOCKED`
+- `OUT_OF_BOUNDS`
+- `LIMIT_HIT`
+- `ROLLED_BACK`
+
+## Token Strategy + Telemetry
+Envoi minimizes context waste by:
+- compacting oversized prompt sections,
+- bounding idea/question payloads,
+- truncating oversized warning payloads,
+- using compact machine contracts for builder dispatch.
+
+Token feedback is surfaced at:
+- ORCHESTRATE,
+- BUILD,
+- per tick total,
+- cumulative loop totals.
+
+If provider usage metadata is missing, `n/a` is shown.
+
+## Update Strategy
+```bash
+envoi update --dry-run
+envoi update --yes
+```
+
+Options:
+- `--mode auto|linked|registry`
+- `--manager pnpm|npm|yarn|bun`
+- `--dry-run`
+- `--yes`
+
+Linked-install behavior:
+- `envoi tick` and `envoi loop` refresh stale linked builds before execution.
+- if linked source refreshes between loop ticks, loop stops at safe boundary (`self_update`) so next launch uses fresh code.
+
+## Config + Workspace Migration
+New defaults:
+- `envoi.config.json`
+- `envoi/` workspace directory
+
+Legacy layout support:
+- Envoi auto-detects prior config/workspace layouts.
+- on load, Envoi migrates prior defaults to new paths and writes `envoi.config.json`.
+- prior config names remain compatible and continue to load.
+
+## Safety vs Speed
+```bash
+envoi autonomy --set strict
+envoi autonomy --set balanced
+envoi autonomy --set fast
+```
+
+- `strict`: more friction, highest safety bias
+- `balanced`: recommended default
+- `fast`: fewer prompts, still constrained by guardrails
+
+Repeated proceed prompts usually come from host CLI safety boundaries (filesystem/network/command risk), not only Envoi itself.
+
+## CLI Reference
+Global option:
+- `envoi -c <path>` / `envoi --config <path>`
+
+Commands:
+- `envoi start`
+- `envoi brief`
+- `envoi tick`
+- `envoi loop --mode task|milestone|autonomous --max-ticks <n>`
+- `envoi status`
+- `envoi check`
+- `envoi undo`
+- `envoi app`
+- `envoi mode --set <mode>`
+- `envoi builder --set <builder>`
+- `envoi autonomy --set strict|balanced|fast`
+- `envoi idea "<text>" [--target-by <date>] [--testability soon|later|unknown]`
+- `envoi update`
+- `envoi pr-note`
+
+Help:
+- `envoi --help`
+- `envoi <command> --help`
+
+## Runtime Artifacts
+Default runtime files live under `envoi/`:
+- `STATE.json`
+- `TASK.json`
+- `REPORT.json`
+- `REPORT.md` (optional)
+- `BLOCKED.json`
+- `history/<run_id>/...`
+
+## PR Attribution
+```bash
+envoi pr-note
+envoi pr-note --format text
+```
+
+## Development
+```bash
+pnpm build
+pnpm test
+pnpm typecheck
+```
+
+## Additional Docs
+- `docs/DOGFOOD.md`
+- `docs/NEW-PLAN.md`
+- `ROADMAP.json`
+- `pilot/` (legacy workflow docs)

package/dist/commands/app.d.ts

@@ -0,0 +1,2 @@
+export declare function appCommand(): Promise<void>;
+//# sourceMappingURL=app.d.ts.map

package/dist/commands/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/commands/app.ts"],"names":[],"mappings":"AAoBA,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAYhD"}

package/dist/commands/app.js

@@ -0,0 +1,31 @@
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+const APP_URL = 'https://envoi.app';
+function openDesktopApp() {
+    if (process.platform === 'darwin') {
+        const hasBundle = existsSync('/Applications/Envoi.app') || existsSync(`${process.env.HOME ?? ''}/Applications/Envoi.app`);
+        if (!hasBundle)
+            return false;
+        const result = spawnSync('open', ['-a', 'Envoi'], { stdio: 'inherit' });
+        return result.status === 0;
+    }
+    if (process.platform === 'win32') {
+        const result = spawnSync('cmd', ['/c', 'start', '', 'envoi:'], { stdio: 'ignore' });
+        return result.status === 0;
+    }
+    const result = spawnSync('xdg-open', ['envoi://'], { stdio: 'ignore' });
+    return result.status === 0;
+}
+export async function appCommand() {
+    if (openDesktopApp()) {
+        console.log('Opened Envoi desktop app.');
+        return;
+    }
+    console.log('Envoi desktop app is not installed or not registered on this machine.');
+    console.log('Why use it:');
+    console.log('- Native timeline for ticks, checkpoints, and rollbacks.');
+    console.log('- Faster approvals with a dedicated human-in-the-loop surface.');
+    console.log('- Shared team visibility across planner, builder, and checker outcomes.');
+    console.log(`Learn more: ${APP_URL}`);
+}
+//# sourceMappingURL=app.js.map

package/dist/commands/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/commands/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,MAAM,OAAO,GAAG,mBAAmB,CAAC;AAEpC,SAAS,cAAc;IACrB,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAClC,MAAM,SAAS,GAAG,UAAU,CAAC,yBAAyB,CAAC,IAAI,UAAU,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,yBAAyB,CAAC,CAAC;QAC1H,IAAI,CAAC,SAAS;YAAE,OAAO,KAAK,CAAC;QAC7B,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QACxE,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC;IAC7B,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QACpF,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC;IAC7B,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,UAAU,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IACxE,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,IAAI,cAAc,EAAE,EAAE,CAAC;QACrB,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;QACzC,OAAO;IACT,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,uEAAuE,CAAC,CAAC;IACrF,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC3B,OAAO,CAAC,GAAG,CAAC,0DAA0D,CAAC,CAAC;IACxE,OAAO,CAAC,GAAG,CAAC,gEAAgE,CAAC,CAAC;IAC9E,OAAO,CAAC,GAAG,CAAC,yEAAyE,CAAC,CAAC;IACvF,OAAO,CAAC,GAAG,CAAC,eAAe,OAAO,EAAE,CAAC,CAAC;AACxC,CAAC"}

package/dist/commands/autonomy.d.ts

@@ -0,0 +1,6 @@
+export declare function autonomyCommand(options: {
+    configPath?: string;
+    set?: string;
+    json?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=autonomy.d.ts.map

package/dist/commands/autonomy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autonomy.d.ts","sourceRoot":"","sources":["../../src/commands/autonomy.ts"],"names":[],"mappings":"AAiDA,wBAAsB,eAAe,CAAC,OAAO,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAoDnH"}

package/dist/commands/autonomy.js

@@ -0,0 +1,89 @@
+import { resolve } from 'node:path';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { atomicReadJson, atomicWriteJson } from '../lib/fs.js';
+import { CONFIG_FILE_NAME, ConfigError, findConfigFile } from '../lib/config.js';
+import { describeAutonomyProfile } from '../lib/autonomy.js';
+function parseProfile(value) {
+    if (!value)
+        return null;
+    if (value === 'strict' || value === 'balanced' || value === 'fast')
+        return value;
+    throw new Error(`Invalid profile: ${value}. Must be 'strict', 'balanced', or 'fast'.`);
+}
+async function resolveConfigPath(configPath) {
+    if (configPath)
+        return resolve(configPath);
+    const found = await findConfigFile();
+    if (!found) {
+        throw new ConfigError(`Configuration file not found. Expected ${CONFIG_FILE_NAME} in current directory or parent directories.`);
+    }
+    return found;
+}
+async function promptProfile(current) {
+    const rl = readline.createInterface({ input, output });
+    try {
+        const options = ['strict', 'balanced', 'fast'];
+        console.log('\nChoose autonomy profile:');
+        options.forEach((profile, index) => {
+            const suffix = profile === current ? ' (current)' : '';
+            console.log(`  ${index + 1}. ${profile}${suffix}`);
+            console.log(`     ${describeAutonomyProfile(profile)}`);
+        });
+        const answer = (await rl.question(`Profile [1-3] (default ${current}): `)).trim();
+        if (!answer)
+            return current;
+        const index = Number.parseInt(answer, 10);
+        if (index >= 1 && index <= options.length)
+            return options[index - 1];
+        if (answer === 'strict' || answer === 'balanced' || answer === 'fast')
+            return answer;
+        throw new Error('Invalid selection');
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function autonomyCommand(options) {
+    const configPath = await resolveConfigPath(options.configPath);
+    const raw = await atomicReadJson(configPath);
+    const current = (raw.runner.autonomy?.profile ?? 'balanced');
+    const selected = parseProfile(options.set) ?? (input.isTTY ? await promptProfile(current) : current);
+    raw.runner = {
+        ...raw.runner,
+        autonomy: {
+            profile: selected,
+            command_trust: raw.runner.autonomy?.command_trust ?? [],
+            fs_policy: raw.runner.autonomy?.fs_policy ?? 'workspace_write',
+            network_policy: raw.runner.autonomy?.network_policy ?? 'deny',
+        },
+    };
+    if (selected === 'strict') {
+        raw.orchestrator = { ...raw.orchestrator, permission_mode: 'plan' };
+        raw.builder = {
+            ...raw.builder,
+            claude_code: { ...raw.builder.claude_code, permission_mode: 'plan' },
+        };
+    }
+    else if (selected === 'fast') {
+        raw.orchestrator = { ...raw.orchestrator, permission_mode: 'bypassPermissions' };
+        raw.builder = {
+            ...raw.builder,
+            claude_code: { ...raw.builder.claude_code, permission_mode: 'bypassPermissions' },
+        };
+    }
+    await atomicWriteJson(configPath, raw);
+    if (options.json) {
+        console.log(JSON.stringify({
+            profile: selected,
+            orchestrator_permission_mode: raw.orchestrator.permission_mode,
+            builder_permission_mode: raw.builder.claude_code.permission_mode,
+        }, null, 2));
+        return;
+    }
+    console.log(`\nAutonomy profile set to: ${selected}`);
+    console.log(describeAutonomyProfile(selected));
+    console.log(`Orchestrator permission mode: ${raw.orchestrator.permission_mode}`);
+    console.log(`Builder permission mode: ${raw.builder.claude_code.permission_mode}`);
+}
+//# sourceMappingURL=autonomy.js.map

package/dist/commands/autonomy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autonomy.js","sourceRoot":"","sources":["../../src/commands/autonomy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,QAAQ,MAAM,wBAAwB,CAAC;AAC9C,OAAO,EAAE,KAAK,IAAI,KAAK,EAAE,MAAM,IAAI,MAAM,EAAE,MAAM,cAAc,CAAC;AAEhE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAI7D,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,IAAI,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,UAAU,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IACjF,MAAM,IAAI,KAAK,CAAC,oBAAoB,KAAK,4CAA4C,CAAC,CAAC;AACzF,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,UAAmB;IAClD,IAAI,UAAU;QAAE,OAAO,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,MAAM,cAAc,EAAE,CAAC;IACrC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,WAAW,CACnB,0CAA0C,gBAAgB,8CAA8C,CACzG,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,OAAwB;IACnD,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;IACvD,IAAI,CAAC;QACH,MAAM,OAAO,GAAsB,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;QAClE,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;QAC1C,OAAO,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE;YACjC,MAAM,MAAM,GAAG,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,GAAG,CAAC,KAAK,OAAO,GAAG,MAAM,EAAE,CAAC,CAAC;YACnD,OAAO,CAAC,GAAG,CAAC,QAAQ,uBAAuB,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC1D,CAAC,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0BAA0B,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAClF,IAAI,CAAC,MAAM;YAAE,OAAO,OAAO,CAAC;QAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC1C,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,OAAO,CAAC,MAAM;YAAE,OAAO,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QACrE,IAAI,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,UAAU,IAAI,MAAM,KAAK,MAAM;YAAE,OAAO,MAAM,CAAC;QACrF,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACvC,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAA8D;IAClG,MAAM,UAAU,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,MAAM,GAAG,GAAG,MAAM,cAAc,CAAc,UAAU,CAAC,CAAC;IAE1D,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,IAAI,UAAU,CAAoB,CAAC;IAChF,MAAM,QAAQ,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAErG,GAAG,CAAC,MAAM,GAAG;QACX,GAAG,GAAG,CAAC,MAAM;QACb,QAAQ,EAAE;YACR,OAAO,EAAE,QAAQ;YACjB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,aAAa,IAAI,EAAE;YACvD,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,IAAI,iBAAiB;YAC9D,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,cAAc,IAAI,MAAM;SAC9D;KACF,CAAC;IAEF,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,GAAG,CAAC,YAAY,GAAG,EAAE,GAAG,GAAG,CAAC,YAAY,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC;QACpE,GAAG,CAAC,OAAO,GAAG;YACZ,GAAG,GAAG,CAAC,OAAO;YACd,WAAW,EAAE,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,eAAe,EAAE,MAAM,EAAE;SACrE,CAAC;IACJ,CAAC;SAAM,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QAC/B,GAAG,CAAC,YAAY,GAAG,EAAE,GAAG,GAAG,CAAC,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,CAAC;QACjF,GAAG,CAAC,OAAO,GAAG;YACZ,GAAG,GAAG,CAAC,OAAO;YACd,WAAW,EAAE,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,eAAe,EAAE,mBAAmB,EAAE;SAClF,CAAC;IACJ,CAAC;IAED,MAAM,eAAe,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IAEvC,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,CAAC,GAAG,CACT,IAAI,CAAC,SAAS,CACZ;YACE,OAAO,EAAE,QAAQ;YACjB,4BAA4B,EAAE,GAAG,CAAC,YAAY,CAAC,eAAe;YAC9D,uBAAuB,EAAE,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,eAAe;SACjE,EACD,IAAI,EACJ,CAAC,CACF,CACF,CAAC;QACF,OAAO;IACT,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,8BAA8B,QAAQ,EAAE,CAAC,CAAC;IACtD,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC/C,OAAO,CAAC,GAAG,CAAC,iCAAiC,GAAG,CAAC,YAAY,CAAC,eAAe,EAAE,CAAC,CAAC;IACjF,OAAO,CAAC,GAAG,CAAC,4BAA4B,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC;AACrF,CAAC"}

package/dist/commands/builder.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Interactive (or flag-based) builder selection.
+ *
+ * This is the "hands" engine choice:
+ * - claude_code: same engine family as orchestrator (works out of the box if Claude CLI is installed)
+ * - cursor: external driver (fast / auto-mode), requires builder.cursor config
+ */
+export declare function builderCommand(options: {
+    configPath?: string;
+    set?: string;
+    json?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=builder.d.ts.map

package/dist/commands/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/commands/builder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA4FH,wBAAsB,cAAc,CAAC,OAAO,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAiElH"}

package/dist/commands/builder.js

@@ -0,0 +1,142 @@
+/**
+ * Interactive (or flag-based) builder selection.
+ *
+ * This is the "hands" engine choice:
+ * - claude_code: same engine family as orchestrator (works out of the box if Claude CLI is installed)
+ * - cursor: external driver (fast / auto-mode), requires builder.cursor config
+ */
+import { resolve } from 'node:path';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { atomicReadJson, atomicWriteJson } from '../lib/fs.js';
+import { CONFIG_FILE_NAME, ConfigError, findConfigFile, loadConfig, validateConfig } from '../lib/config.js';
+import { CLI_NAME, WORKSPACE_DIR_NAME } from '../lib/branding.js';
+function describeBuilder(choice) {
+    switch (choice) {
+        case 'cursor':
+            return {
+                title: 'Cursor agent (auto-mode) — fast + (almost) unlimited (recommended)',
+                desc: `Requires a headless driver that reads ${WORKSPACE_DIR_NAME}/TASK.json and writes BUILDER_RESULT.json.`,
+            };
+        case 'claude_code':
+            return {
+                title: 'Claude Code builder — same as orchestrator',
+                desc: 'Uses your Claude CLI directly. Slower but fewer external moving parts.',
+            };
+    }
+}
+async function resolveConfigPath(configPath) {
+    if (configPath)
+        return resolve(configPath);
+    const found = await findConfigFile();
+    if (!found) {
+        throw new ConfigError(`Configuration file not found. Expected ${CONFIG_FILE_NAME} in current directory or parent directories.`);
+    }
+    return found;
+}
+async function promptForBuilder(current) {
+    const rl = readline.createInterface({ input, output });
+    try {
+        console.log('\nChoose builder:');
+        const options = ['cursor', 'claude_code'];
+        options.forEach((b, i) => {
+            const meta = describeBuilder(b);
+            const suffix = current === b ? ' (current)' : '';
+            console.log(`  ${i + 1}. ${b} — ${meta.title}${suffix}`);
+            console.log(`     ${meta.desc}`);
+        });
+        const answer = (await rl.question(`Builder [1-2]${current ? ` (default ${current})` : ''}: `)).trim();
+        if (answer === '' && current)
+            return current;
+        const idx = Number.parseInt(answer, 10);
+        if (idx >= 1 && idx <= 2)
+            return options[idx - 1];
+        if (answer === 'cursor' || answer === 'claude_code')
+            return answer;
+        throw new Error('Invalid selection');
+    }
+    finally {
+        rl.close();
+    }
+}
+async function promptCursorConfig(existing) {
+    const rl = readline.createInterface({ input, output });
+    try {
+        console.log('\nCursor driver config (Cursor Agent):');
+        console.log(`  This should point to the Cursor CLI executable (usually 'cursor'). ${CLI_NAME} will run: <command> <args...> <prompt>`);
+        const command = (await rl.question(`  command (Cursor CLI, must support 'agent') [${existing?.command ?? 'cursor'}]: `)).trim() ||
+            (existing?.command ?? 'cursor');
+        const defaultArgs = existing?.args?.length
+            ? existing.args
+            : ['agent', '--print', '--output-format', 'text', '--workspace', '.', '--force'];
+        const argsLine = (await rl.question(`  args (space-separated, no quoting) [${defaultArgs.join(' ')}]: `)).trim();
+        const args = argsLine ? argsLine.split(/\s+/).filter(Boolean) : defaultArgs;
+        const timeoutStr = (await rl.question(`  timeout_seconds [${existing?.timeout_seconds ?? 300}]: `)).trim();
+        const timeout_seconds = timeoutStr ? Number.parseInt(timeoutStr, 10) : (existing?.timeout_seconds ?? 300);
+        const driverKind = (await rl.question(`  driver_kind [${existing?.driver_kind ?? 'cursor_agent'}]: `)).trim() ||
+            (existing?.driver_kind ?? 'cursor_agent');
+        const output_file = (await rl.question(`  output_file (relative to workspace_dir) [${existing?.output_file ?? 'BUILDER_RESULT.json'}]: `)).trim() ||
+            (existing?.output_file ?? 'BUILDER_RESULT.json');
+        return { driver_kind: driverKind, command, args, timeout_seconds, output_file };
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function builderCommand(options) {
+    const config = await loadConfig(options.configPath);
+    const current = (config.builder.default_mode === 'cursor' ? 'cursor' : 'claude_code');
+    let next;
+    if (options.set) {
+        if (options.set !== 'cursor' && options.set !== 'claude_code') {
+            throw new Error(`Invalid builder: ${options.set}. Must be 'cursor' or 'claude_code'.`);
+        }
+        next = options.set;
+    }
+    else if (input.isTTY) {
+        next = await promptForBuilder(current);
+    }
+    else {
+        throw new Error('No --set provided and stdin is not a TTY (cannot prompt).');
+    }
+    const configPath = await resolveConfigPath(options.configPath);
+    const raw = await atomicReadJson(configPath);
+    if (next === 'claude_code') {
+        raw.builder = { ...raw.builder, default_mode: 'claude_code' };
+    }
+    else {
+        const cursor = input.isTTY ? await promptCursorConfig(raw.builder.cursor) : raw.builder.cursor;
+        if (!cursor) {
+            throw new Error('builder.cursor is required for cursor mode (cannot prompt in non-TTY).');
+        }
+        raw.builder = {
+            ...raw.builder,
+            default_mode: 'cursor',
+            cursor: {
+                driver_kind: cursor.driver_kind ?? 'cursor_agent',
+                command: cursor.command,
+                args: cursor.args,
+                timeout_seconds: cursor.timeout_seconds,
+                output_file: cursor.output_file,
+            },
+        };
+    }
+    // Validate before writing (keeps strict cursor requirements)
+    if (!validateConfig(raw)) {
+        throw new Error('Updated config is invalid (validateConfig failed).');
+    }
+    await atomicWriteJson(configPath, raw);
+    if (options.json) {
+        console.log(JSON.stringify({
+            default_mode: raw.builder.default_mode,
+            cursor_configured: raw.builder.cursor ? 'yes' : 'no',
+        }, null, 2));
+        return;
+    }
+    const meta = describeBuilder(next);
+    console.log(`\nBuilder set to: ${next} — ${meta.title}`);
+    if (next === 'cursor') {
+        console.log(`If your driver isn't installed/configured yet, the next tick will BLOCK until you fix builder.cursor.`);
+    }
+}
+//# sourceMappingURL=builder.js.map

package/dist/commands/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../src/commands/builder.ts"],"names":[],"mappings":"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"}

package/dist/commands/idea.d.ts

@@ -0,0 +1,12 @@
+export interface IdeaCommandOptions {
+    text?: string;
+    targetBy?: string;
+    testability?: string;
+    source?: string;
+    json?: boolean;
+}
+export declare function ideaCommand(options: IdeaCommandOptions, workspaceDir: string): Promise<{
+    saved: boolean;
+    count: number;
+}>;
+//# sourceMappingURL=idea.d.ts.map

package/dist/commands/idea.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idea.d.ts","sourceRoot":"","sources":["../../src/commands/idea.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAyCD,wBAAsB,WAAW,CAC/B,OAAO,EAAE,kBAAkB,EAC3B,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAoC5C"}

package/dist/commands/idea.js

@@ -0,0 +1,79 @@
+import { stdin as input, stdout as output } from 'node:process';
+import readline from 'node:readline/promises';
+import { appendIdeaEntry, readWorkspaceState, writeWorkspaceState } from '../lib/workspace_state.js';
+function normalizeTestability(value) {
+    if (!value || value.trim() === '')
+        return 'unknown';
+    if (value === 'soon' || value === 'later' || value === 'unknown')
+        return value;
+    throw new Error(`Invalid testability value: ${value}. Must be 'soon', 'later', or 'unknown'.`);
+}
+function normalizeSource(value) {
+    if (!value || value.trim() === '')
+        return 'cli';
+    if (value === 'interactive' || value === 'cli' || value === 'api')
+        return value;
+    throw new Error(`Invalid source value: ${value}. Must be 'interactive', 'cli', or 'api'.`);
+}
+async function promptIdeaText() {
+    if (!input.isTTY)
+        return '';
+    const rl = readline.createInterface({ input, output });
+    try {
+        return (await rl.question('Share a new idea for planning (Enter to skip): ')).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+async function promptTestability() {
+    if (!input.isTTY)
+        return 'unknown';
+    const rl = readline.createInterface({ input, output });
+    try {
+        const answer = (await rl.question('When should this be testable? [soon/later/unknown] (default unknown): '))
+            .trim()
+            .toLowerCase();
+        if (!answer)
+            return 'unknown';
+        if (answer === 'soon' || answer === 'later' || answer === 'unknown')
+            return answer;
+        throw new Error("Invalid choice. Use 'soon', 'later', or 'unknown'.");
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function ideaCommand(options, workspaceDir) {
+    const explicitText = options.text?.trim() ?? '';
+    const ideaText = explicitText || (await promptIdeaText());
+    if (!ideaText) {
+        if (options.json) {
+            console.log(JSON.stringify({ saved: false, reason: 'empty_input' }, null, 2));
+            return { saved: false, count: 0 };
+        }
+        console.log('No idea captured.');
+        return { saved: false, count: 0 };
+    }
+    const source = normalizeSource(options.source ?? (explicitText ? 'cli' : 'interactive'));
+    const promptedTestability = options.testability === undefined && source === 'interactive' ? await promptTestability() : undefined;
+    const testability = normalizeTestability(options.testability ?? promptedTestability);
+    const currentState = await readWorkspaceState(workspaceDir);
+    const nextState = appendIdeaEntry(currentState, {
+        text: ideaText,
+        source,
+        target_by: options.targetBy ?? null,
+        testability_need: testability,
+    });
+    await writeWorkspaceState(workspaceDir, nextState);
+    const count = nextState.idea_inbox?.filter((entry) => entry.status === 'new').length ?? 0;
+    if (options.json) {
+        console.log(JSON.stringify({ saved: true, pending_new_ideas: count }, null, 2));
+    }
+    else {
+        console.log(`Idea saved to ${workspaceDir}/STATE.json`);
+        console.log(`Pending new ideas: ${count}`);
+    }
+    return { saved: true, count };
+}
+//# sourceMappingURL=idea.js.map