brainclaw 1.5.4 → 1.6.0

package/README.md

@@ -108,28 +108,52 @@ If you want the least surprising setup today, use Linux first. If you are on Win
 
 ---
 
-## Get Started
-
-### 1. Install
-
-```bash
-npm install -g brainclaw
-```
-
-### 2. Initialize a project
-
-```bash
-cd your-project
-brainclaw init
-```
-
-This creates `.brainclaw/` in your repo, detects your coding agent, writes MCP config and instruction files, and sets up session hooks. It takes about 10 seconds.
-
-### 3. Restart your agent
-
-Restart your coding agent (or reload MCP servers) so it picks up the new configuration. After that, brainclaw tools are available.
-
-### 4. Start working
+## Get Started
+
+### 1. Let your coding agent lead
+
+The smoothest first-run path is agent-first:
+
+1. ask your coding agent to inspect the package and explain what brainclaw does
+2. ask it to install brainclaw and initialize or join the project you're working on
+3. use the CLI yourself when you need an explicit operator or fallback path
+
+If you want to drive setup manually, use the steps below.
+
+### 2. Install
+
+```bash
+npm install -g brainclaw
+```
+
+### 3. Bootstrap this machine
+
+```bash
+brainclaw setup-machine --yes
+```
+
+This detects the installed agents on the current machine, writes the machine-level MCP and user config Brainclaw manages, and does **not** scan or initialize repositories.
+
+### 4. Initialize or refresh the current project
+
+```bash
+cd your-project
+brainclaw init
+```
+
+`brainclaw init` is now safe to rerun. It creates `.brainclaw/` when the project is new, or refreshes the managed Brainclaw and agent integration files when the project already has memory.
+
+If you are explicitly adding another agent to an existing Brainclaw project, use:
+
+```bash
+brainclaw enable-agent <agent-name>
+```
+
+### 5. Restart your agent
+
+Restart your coding agent (or reload MCP servers) so it picks up the new configuration. After that, brainclaw tools are available.
+
+### 6. Start working
 
 Pick one of the canonical entry points depending on what you're doing:
 
@@ -161,7 +185,7 @@ For agents without MCP (e.g. Copilot reads `.github/copilot-instructions.md`), r
 brainclaw export --detect --write
 ```
 
-### 5. Verify it works
+### 7. Verify it works
 
 ```bash
 brainclaw status          # see active sessions, claims, plans
@@ -172,11 +196,11 @@ brainclaw agent-board     # see what each agent is doing
 
 To configure brainclaw for all your repos and agents at once:
 
-```bash
-brainclaw setup --yes
-```
-
-This scans your projects, detects installed agents (Claude Code, Codex, Cursor, Copilot, Cline, Mistral Vibe, etc.), and writes MCP configs for each.
+```bash
+brainclaw setup --yes
+```
+
+This is the broader multi-repo wizard. It bootstraps the machine, scans your project roots, and initializes selected repositories in one pass.
 
 ### Existing projects
 

package/dist/cli.js

@@ -2,7 +2,7 @@
 import path from 'node:path';
 import { Command } from 'commander';
 import { runInit } from './commands/init.js';
-import { runSetup } from './commands/setup.js';
+import { runSetup, runSetupMachine } from './commands/setup.js';
 import { runUpgrade } from './commands/upgrade.js';
 import { patchAllMcpConfigs } from './core/agent-files.js';
 import { runReconcile } from './commands/reconcile.js';
@@ -47,6 +47,7 @@ import { cleanupStaleCandidates } from './core/candidates.js';
 import { runListClaims } from './commands/list-claims.js';
 import { runReleaseClaim } from './commands/release-claim.js';
 import { runClaimResource } from './commands/claim-resource.js';
+import { runAssignmentResource } from './commands/assignment-resource.js';
 import { runMemoryCommand } from './commands/memory.js';
 import { runReleaseClaims } from './commands/release-claims.js';
 import { runAgentBoard } from './commands/agent-board.js';
@@ -104,6 +105,8 @@ import { runMigrate } from './commands/migrate.js';
 import { runRunProfile } from './commands/run-profile.js';
 import { runCompact } from './commands/compact.js';
 import { runHarvestCandidates } from './commands/harvest.js';
+import { runQuestionsCommand } from './commands/questions.js';
+import { runReplyCommand } from './commands/reply.js';
 import { requireRegisteredAgentIdentity } from './core/agent-registry.js';
 const program = new Command();
 function collect(value, previous) {
@@ -161,7 +164,7 @@ program
     initLogLevel({ verbose: root.verbose, debug: root.debug });
     // Skip effective cwd resolution for commands that create the store
     const cmdName = actionCommand.name();
-    const skipResolution = cmdName === 'init' || cmdName === 'setup';
+    const skipResolution = cmdName === 'init' || cmdName === 'setup' || cmdName === 'setup-machine';
     // pln#359 phase 1c — `--project <name>` resolves a linked project to an
     // absolute path via resolveProjectCwd, then feeds the same chdir flow
     // as --cwd. Mutually exclusive with --cwd to avoid ambiguity.
@@ -193,17 +196,19 @@ program
             logger.info(`Cleaned ${removed} orphan lock/tmp file(s) in ${memoryDir()}`);
         }
     }
-    else if (explicitCwd) {
-        // For init/setup, still respect explicit --cwd / --project but nothing else
+    else if (explicitCwd && cmdName !== 'init') {
+        // For setup commands, still respect explicit --cwd / --project but nothing else.
+        // init receives cwd through runInit options so scaffold writers do not
+        // depend on changing process.cwd().
         process.chdir(path.resolve(explicitCwd));
     }
 });
 // --- init ---
 program
     .command('init')
-    .description('Initialize project memory in .brainclaw/ storage directory')
+    .description('Initialize or refresh project memory in .brainclaw/ storage directory')
     .option('-y, --yes', 'Skip interactive wizard and use defaults')
-    .option('--force', 'Overwrite existing project memory directory')
+    .option('--force', 'Rebuild managed Brainclaw config and generated files from defaults')
     .option('--compact', 'Enable compact markdown mode')
     .option('--topology <mode>', 'Topology mode: embedded, sidecar, local-only')
     .option('--project-mode <mode>', 'Project mode: single-project, multi-project, auto')
@@ -211,13 +216,18 @@ program
     .option('--no-analyze-repo', 'Skip repository analysis when suggesting a project mode')
     .option('--no-ai-scan', 'Skip AI surface scan during init')
     .option('--scan', 'Scan subdirectories for service boundaries and suggest init targets')
+    .option('--cwd <path>', 'Override working directory for init scaffolding (parity with other CLI commands)')
     .action(async (options) => {
-    await runInit(options);
+    // pln#515 step 1: commander binds --cwd to the program-level option even
+    // when it appears after `init`, so resolve via program.opts() and feed
+    // runInit's existing options.cwd plumb.
+    const programCwd = program.opts().cwd;
+    await runInit({ ...options, cwd: options.cwd ?? programCwd });
 });
 // --- setup ---
 program
     .command('setup')
-    .description('Interactive onboarding wizard — global agent install + multi-repo init')
+    .description('Interactive onboarding wizard — machine bootstrap plus multi-repo init')
     .option('--roots <paths>', 'Comma-separated root directories to scan (skips interactive prompt)')
     .option('--agents <agents>', 'Agents to configure: all, detected, or comma-separated names')
     .option('--repos <mode>', 'Repo selection: all, current, or comma-separated numbers')
@@ -225,6 +235,15 @@ program
     .action(async (options) => {
     await runSetup(options);
 });
+// --- setup-machine ---
+program
+    .command('setup-machine')
+    .description('Machine-only onboarding — detect/configure agents and MCP without scanning or initializing repositories')
+    .option('--agents <agents>', 'Agents to configure: all, detected, or comma-separated names')
+    .option('-y, --yes', 'Accept all defaults non-interactively')
+    .action(async (options) => {
+    await runSetupMachine(options);
+});
 // --- memory-log ---
 program
     .command('memory-log')
@@ -1039,6 +1058,26 @@ program
     .action((subcommand, args, options) => {
     runClaimResource(subcommand, args, { ...options, planStatus: options.planStatus, localOnly: options.localOnly });
 });
+// --- assignment ---
+program
+    .command('assignment <subcommand> [args...]')
+    .description('Manage work assignments (list, show, update, cancel)')
+    .option('--json', 'Output as JSON for list/show')
+    .option('--all', 'Include terminal assignments in list')
+    .option('--status <status>', 'Status filter for list or target status for update')
+    .option('--agent <agent>', 'Filter by agent name')
+    .option('--claim <id>', 'Filter by linked claim ID')
+    .option('--plan <id>', 'Filter by linked plan ID')
+    .option('--sequence <id>', 'Filter by linked sequence ID')
+    .option('--reason <text>', 'Optional status reason for update/cancel')
+    .action((subcommand, args, options) => {
+    runAssignmentResource(subcommand, args, {
+        ...options,
+        claim: options.claim,
+        plan: options.plan,
+        sequence: options.sequence,
+    });
+});
 // --- list-claims ---
 program
     .command('list-claims')
@@ -1266,8 +1305,8 @@ program
     .option('--maintenance-mode <mode>', 'Maintenance mode: full (default) or fast')
     .option('--include-context', 'Output full project context after starting session (replaces separate context call)')
     .option('--json', 'Output as JSON')
-    .action((options) => {
-    runSessionStart(options);
+    .action(async (options) => {
+    await runSessionStart(options);
 });
 // --- session-end ---
 program
@@ -1283,8 +1322,8 @@ program
     .option('--reviewer <name>', 'Explicit reviewer to route the reflected handoff review to')
     .option('--reflect', 'Include structured reflection questions for the agent to answer')
     .option('--json', 'Output as JSON')
-    .action((options) => {
-    runSessionEnd({
+    .action(async (options) => {
+    await runSessionEnd({
         ...options,
         autoReflect: options.autoReflect,
         autoRelease: options.autoRelease,
@@ -1843,6 +1882,114 @@ if (isCodevEnabled()) {
         runCodevMetrics(thread, { ...options, cwd: globalOpts.cwd });
     });
 }
+// --- questions (operator-question artifacts across loops; pln#508 step 4) ---
+program
+    .command('questions')
+    .description('List pending operator_question artifacts across loops in the current project')
+    .option('--loop <loop_id>', 'Filter to a single loop')
+    .option('--status <status>', 'Filter by status: awaiting (default), answered, timed_out', 'awaiting')
+    .option('--mine', 'Filter to questions targeted at the current agent (v1 heuristic: humans see all awaiting)')
+    .option('--json', 'Output as JSON')
+    .action((options) => {
+    const globalOpts = program.opts();
+    const status = options.status;
+    if (!['awaiting', 'answered', 'timed_out'].includes(status)) {
+        console.error(`Error: --status must be one of awaiting|answered|timed_out (got "${options.status}")`);
+        process.exit(1);
+    }
+    runQuestionsCommand({
+        loop: options.loop,
+        status,
+        mine: options.mine,
+        json: options.json,
+    }, globalOpts.cwd);
+});
+// --- bootstrap-loop (open/join/status/cancel a bootstrap loop; pln#513 step 3) ---
+program
+    .command('bootstrap-loop')
+    .description('Open or join a bootstrap loop on the current project, or query its status')
+    .option('--status', 'Report current state')
+    .option('--cancel', 'Cancel the active bootstrap loop')
+    .option('--yes', 'Skip confirmation prompts')
+    .option('--json', 'Machine-readable output')
+    .action(async (options) => {
+    const globalOpts = program.opts();
+    const { runBootstrapLoopCommand } = await import('./commands/bootstrap-loop.js');
+    await runBootstrapLoopCommand(options, globalOpts.cwd);
+});
+// --- loop (drive loop turn verbs; pln#517 step 2) ---
+const loopCmd = program
+    .command('loop')
+    .description('Drive a loop turn (turn / complete-turn / advance / add-artifact)');
+loopCmd
+    .command('turn <loop_id>')
+    .description('Issue a turn assignment on a slot')
+    .requiredOption('--slot <slot_id>', 'Target slot id (lsl_...)')
+    .option('--input <text>', 'Free-form input passed to the slot')
+    .option('--role <role>', 'Slot role (resolves the first non-done slot with that role)')
+    .option('--assignment-id <id>', 'Dispatcher-provided assignment id to record on the slot')
+    .option('--json', 'Machine-readable output')
+    .action(async (loop_id, options) => {
+    const globalOpts = program.opts();
+    const { runLoopCommand } = await import('./commands/loop.js');
+    await runLoopCommand('turn', { loop_id }, options, globalOpts.cwd);
+});
+loopCmd
+    .command('complete-turn <loop_id>')
+    .description('Complete a slot turn')
+    .requiredOption('--slot <slot_id>', 'Target slot id (lsl_...)')
+    .requiredOption('--outcome <outcome>', 'Turn outcome: done, failed, or cancelled')
+    .option('--failure-reason <text>', 'Reason when outcome is failed')
+    .option('--artifact <json>', 'JSON object payload for an artifact to attach')
+    .option('--json', 'Machine-readable output')
+    .action(async (loop_id, options) => {
+    const globalOpts = program.opts();
+    const { runLoopCommand } = await import('./commands/loop.js');
+    await runLoopCommand('complete-turn', { loop_id }, options, globalOpts.cwd);
+});
+loopCmd
+    .command('advance <loop_id>')
+    .description('Advance a loop to its next phase')
+    .option('--to-phase <name>', 'Explicit target phase')
+    .option('--force', 'Bypass phase gate checks')
+    .option('--reason <text>', 'Reason to record on the phase advance event')
+    .option('--json', 'Machine-readable output')
+    .action(async (loop_id, options) => {
+    const globalOpts = program.opts();
+    const { runLoopCommand } = await import('./commands/loop.js');
+    await runLoopCommand('advance', { loop_id }, options, globalOpts.cwd);
+});
+loopCmd
+    .command('add-artifact <loop_id>')
+    .description('Attach an artifact to a loop')
+    .requiredOption('--phase <phase>', 'Artifact phase')
+    .requiredOption('--type <type>', 'Artifact type')
+    .requiredOption('--body <json-or-text>', 'Artifact body as JSON or text')
+    .option('--produced-by <agent>', 'Agent that produced the artifact')
+    .option('--ref <ref>', 'JSON ref object, e.g. {"kind":"plan","id":"pln_..."}')
+    .option('--json', 'Machine-readable output')
+    .action(async (loop_id, options) => {
+    const globalOpts = program.opts();
+    const { runLoopCommand } = await import('./commands/loop.js');
+    await runLoopCommand('add-artifact', { loop_id }, options, globalOpts.cwd);
+});
+// --- reply (provide_input to an operator_question; pln#508 step 4) ---
+program
+    .command('reply <qst_id>')
+    .description('Resolve an operator_question artifact (wraps bclaw_loop.provide_input)')
+    .option('--answer <text>', 'Free-form answer text')
+    .option('--choose <option_id>', 'Pick one of the question\'s structured options[].id')
+    .option('--skip', 'Materialize the question\'s suggested_default')
+    .option('--json', 'Output as JSON')
+    .action((qstId, options) => {
+    const globalOpts = program.opts();
+    runReplyCommand(qstId, {
+        answer: options.answer,
+        choose: options.choose,
+        skip: options.skip,
+        json: options.json,
+    }, globalOpts.cwd);
+});
 // --- run (agent profiles) ---
 program
     .command('run [profile-name]')

package/dist/commands/assignment-resource.js

@@ -0,0 +1,182 @@
+import { memoryExists } from '../core/io.js';
+import { listAssignments, loadAssignment, transitionAssignment } from '../core/assignments.js';
+import { resolveCurrentAgentName } from '../core/agent-registry.js';
+import { AssignmentStatusSchema } from '../core/schema.js';
+const TERMINAL_STATUSES = new Set(['completed', 'cancelled', 'expired', 'rerouted']);
+const KNOWN_SUBCOMMANDS = new Set(['list', 'ls', 'show', 'get', 'update', 'cancel']);
+export function runAssignmentResource(subcommand, args, options = {}) {
+    const normalized = subcommand.trim().toLowerCase();
+    if (normalized === 'list' || normalized === 'ls') {
+        runListAssignmentsCommand(options);
+        return;
+    }
+    if (normalized === 'show' || normalized === 'get') {
+        const id = args[0];
+        if (!id) {
+            console.error(`Error: assignment ${normalized} requires <id>.`);
+            process.exit(1);
+        }
+        runShowAssignmentCommand(id, options);
+        return;
+    }
+    if (normalized === 'update') {
+        const id = args[0];
+        if (!id) {
+            console.error('Error: assignment update requires <id>.');
+            process.exit(1);
+        }
+        const status = options.status;
+        if (!status) {
+            console.error('Error: assignment update requires --status <status>.');
+            process.exit(1);
+        }
+        runTransitionAssignmentCommand(id, status, options);
+        return;
+    }
+    if (normalized === 'cancel') {
+        const id = args[0];
+        if (!id) {
+            console.error('Error: assignment cancel requires <id>.');
+            process.exit(1);
+        }
+        runTransitionAssignmentCommand(id, 'cancelled', options);
+        return;
+    }
+    if (normalized.startsWith('asgn_') || KNOWN_SUBCOMMANDS.has(normalized)) {
+        console.error(`Error: unknown assignment subcommand "${subcommand}".`);
+        console.error('  Available: list, show, get, update, cancel');
+        process.exit(1);
+    }
+    console.error('Error: missing assignment subcommand.');
+    console.error('  Available: list, show, get, update, cancel');
+    process.exit(1);
+}
+function runListAssignmentsCommand(options) {
+    ensureInitialized(options.cwd);
+    const requestedStatus = parseAssignmentStatus(options.status);
+    let assignments = listAssignments(options.cwd, {
+        status: requestedStatus,
+        agent: options.agent,
+        claim_id: options.claim,
+        plan_id: options.plan,
+        sequence_id: options.sequence,
+    });
+    if (!options.all && !requestedStatus) {
+        assignments = assignments.filter((assignment) => !TERMINAL_STATUSES.has(assignment.status));
+    }
+    if (options.json) {
+        console.log(JSON.stringify(assignments, null, 2));
+        return;
+    }
+    if (assignments.length === 0) {
+        console.log(options.all ? 'No assignments.' : 'No active assignments.');
+        return;
+    }
+    console.log(`${assignments.length} ${options.all ? 'assignment(s)' : 'active assignment(s)'}:`);
+    console.log('');
+    for (const assignment of assignments) {
+        const extras = [];
+        if (assignment.plan_id)
+            extras.push(`plan ${assignment.plan_id}`);
+        if (assignment.claim_id)
+            extras.push(`claim ${assignment.claim_id}`);
+        if (assignment.sequence_id)
+            extras.push(`sequence ${assignment.sequence_id}`);
+        if (assignment.worktree_path)
+            extras.push(`worktree ${assignment.worktree_path}`);
+        const suffix = extras.length > 0 ? ` [${extras.join(', ')}]` : '';
+        console.log(`  [${assignment.id}] ${assignment.agent} (${assignment.status}) -> ${assignment.scope}: ${assignment.description}${suffix}`);
+    }
+}
+function runShowAssignmentCommand(id, options) {
+    ensureInitialized(options.cwd);
+    const assignment = requireAssignment(id, options.cwd);
+    if (options.json) {
+        console.log(JSON.stringify(assignment, null, 2));
+        return;
+    }
+    console.log(`Assignment: ${assignment.id}`);
+    console.log(`  Agent:        ${assignment.agent}`);
+    console.log(`  Status:       ${assignment.status}`);
+    console.log(`  Scope:        ${assignment.scope}`);
+    console.log(`  Description:  ${assignment.description}`);
+    console.log(`  Claim:        ${assignment.claim_id}`);
+    if (assignment.message_id)
+        console.log(`  Message:      ${assignment.message_id}`);
+    if (assignment.plan_id)
+        console.log(`  Plan:         ${assignment.plan_id}`);
+    if (assignment.sequence_id)
+        console.log(`  Sequence:     ${assignment.sequence_id}`);
+    if (assignment.session_id)
+        console.log(`  Session:      ${assignment.session_id}`);
+    if (assignment.status_reason)
+        console.log(`  Reason:       ${assignment.status_reason}`);
+    if (assignment.worktree_path)
+        console.log(`  Worktree:     ${assignment.worktree_path}`);
+    console.log(`  Created:      ${assignment.created_at}`);
+    if (assignment.updated_at)
+        console.log(`  Updated:      ${assignment.updated_at}`);
+    if (assignment.offered_at)
+        console.log(`  Offered:      ${assignment.offered_at}`);
+    if (assignment.accepted_at)
+        console.log(`  Accepted:     ${assignment.accepted_at}`);
+    if (assignment.started_at)
+        console.log(`  Started:      ${assignment.started_at}`);
+    if (assignment.completed_at)
+        console.log(`  Completed:    ${assignment.completed_at}`);
+    if (assignment.cancelled_at)
+        console.log(`  Cancelled:    ${assignment.cancelled_at}`);
+    if (assignment.failed_at)
+        console.log(`  Failed:       ${assignment.failed_at}`);
+    if (assignment.blocked_at)
+        console.log(`  Blocked:      ${assignment.blocked_at}`);
+    if (assignment.timed_out_at)
+        console.log(`  Timed out:    ${assignment.timed_out_at}`);
+    if (assignment.expired_at)
+        console.log(`  Expired:      ${assignment.expired_at}`);
+    if (assignment.rerouted_at)
+        console.log(`  Rerouted:     ${assignment.rerouted_at}`);
+}
+function runTransitionAssignmentCommand(id, statusInput, options) {
+    ensureInitialized(options.cwd);
+    const nextStatus = parseAssignmentStatus(statusInput, 'status');
+    const actor = resolveCurrentAgentName(options.cwd);
+    try {
+        const result = transitionAssignment(id, nextStatus, {
+            actor,
+            status_reason: options.reason,
+        }, options.cwd);
+        const verb = nextStatus === 'cancelled' ? 'cancelled' : 'updated';
+        console.log(`✔ Assignment ${verb}: [${result.assignment.id}] ${result.previous_status} -> ${result.assignment.status}`);
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+}
+function ensureInitialized(cwd) {
+    if (!memoryExists(cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+}
+function requireAssignment(id, cwd) {
+    const assignment = loadAssignment(id, cwd);
+    if (!assignment) {
+        console.error(`Error: assignment not found: ${id}`);
+        process.exit(1);
+    }
+    return assignment;
+}
+function parseAssignmentStatus(value, label = 'filter') {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = AssignmentStatusSchema.safeParse(value);
+    if (!parsed.success) {
+        console.error(`Error: invalid ${label} '${value}'. Expected one of: ${AssignmentStatusSchema.options.join(', ')}`);
+        process.exit(1);
+    }
+    return parsed.data;
+}
+//# sourceMappingURL=assignment-resource.js.map