@mrpatronz/nexusflow 1.7.0 → 1.9.0

package/dist/agent/nativeTools.js

@@ -0,0 +1,62 @@
+/**
+ * @module agent/nativeTools
+ * Shared prompt, tool metadata, and execution for the SDK-backed native agents
+ * (OpenAI / Anthropic / Gemini). Keeping the tool executor here means the
+ * read-only workspace access — and its path-containment guard — is defined
+ * once instead of copied into three agent loops.
+ */
+import fs from 'fs-extra';
+import path from 'node:path';
+export const NATIVE_STEP_LIMIT = 5;
+export const STEP_LIMIT_NOTICE = '\n\n*Stopped after reaching the tool-step limit without a final answer. Send a follow-up message to continue.*\n';
+export function buildSystemPrompt(cwd) {
+    return `You are an expert coding assistant running within the NexusFlow IDE.
+You have read-only access to the user's workspace at ${cwd} through your tools: you can read files and list directories, but you cannot edit files or run commands.
+When suggesting code changes, include the proposed diff directly in your text response so the user can apply it themselves.`;
+}
+/** Provider-agnostic description of the two read-only tools. Each agent maps
+ *  these into its own SDK's schema shape. */
+export const NATIVE_TOOLS = [
+    { name: 'read_file', description: 'Read the contents of a file', argName: 'filePath', argDescription: 'Path to file relative to workspace' },
+    { name: 'list_directory', description: 'List the contents of a directory', argName: 'dirPath', argDescription: 'Path to directory relative to workspace' },
+];
+function assertWithin(base, target, rel) {
+    // Trailing separator stops a sibling like `workspace-secret` from passing
+    // the prefix test for base `workspace`.
+    if (target !== base && !target.startsWith(base + path.sep)) {
+        throw new Error(`Path escapes the workspace: ${String(rel)}`);
+    }
+}
+/**
+ * Resolve a workspace-relative path and refuse anything that escapes `cwd`,
+ * including via symlinks. The lexical check catches `..`/absolute paths; the
+ * realpath check catches a symlink inside the workspace that points outside.
+ */
+async function resolveWithin(cwd, rel) {
+    const base = path.resolve(cwd);
+    const resolved = path.resolve(base, typeof rel === 'string' ? rel : '');
+    assertWithin(base, resolved, rel);
+    // Follow symlinks and re-check. realpath throws ENOENT for a missing target,
+    // which the fs read below would raise anyway — let it surface as-is.
+    const realBase = await fs.realpath(base);
+    const realTarget = await fs.realpath(resolved);
+    assertWithin(realBase, realTarget, rel);
+    return realTarget;
+}
+/**
+ * Execute a native tool call. Returns the tool's textual result; throws on an
+ * unknown tool, a path-containment violation, or a filesystem error (callers
+ * surface the message back to the model).
+ */
+export async function executeNativeTool(cwd, name, args) {
+    if (name === 'read_file') {
+        const abs = await resolveWithin(cwd, args?.filePath);
+        return await fs.readFile(abs, 'utf8');
+    }
+    if (name === 'list_directory') {
+        const abs = await resolveWithin(cwd, args?.dirPath);
+        return (await fs.readdir(abs)).join('\n');
+    }
+    throw new Error(`Unknown tool: ${name}`);
+}
+//# sourceMappingURL=nativeTools.js.map

package/dist/agent/nativeTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nativeTools.js","sourceRoot":"","sources":["../../src/agent/nativeTools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,UAAU,CAAC;AAC1B,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AACnC,MAAM,CAAC,MAAM,iBAAiB,GAC5B,kHAAkH,CAAC;AAErH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,OAAO;uDAC8C,GAAG;4HACkE,CAAC;AAC7H,CAAC;AASD;6CAC6C;AAC7C,MAAM,CAAC,MAAM,YAAY,GAAqB;IAC5C,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,6BAA6B,EAAE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,oCAAoC,EAAE;IAC5I,EAAE,IAAI,EAAE,gBAAgB,EAAE,WAAW,EAAE,kCAAkC,EAAE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,yCAAyC,EAAE;CAC3J,CAAC;AAEF,SAAS,YAAY,CAAC,IAAY,EAAE,MAAc,EAAE,GAAY;IAC9D,0EAA0E;IAC1E,wCAAwC;IACxC,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,+BAA+B,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChE,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,aAAa,CAAC,GAAW,EAAE,GAAY;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACxE,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IAElC,6EAA6E;IAC7E,qEAAqE;IACrE,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,UAAU,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC/C,YAAY,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;IACxC,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,GAAW,EAAE,IAAY,EAAE,IAAS;IAC1E,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QACrD,OAAO,MAAM,EAAE,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,IAAI,KAAK,gBAAgB,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QACpD,OAAO,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC;AAC3C,CAAC"}

package/dist/agent/nativeTools.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=nativeTools.test.d.ts.map

package/dist/agent/nativeTools.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nativeTools.test.d.ts","sourceRoot":"","sources":["../../src/agent/nativeTools.test.ts"],"names":[],"mappings":""}

package/dist/agent/nativeTools.test.js

@@ -0,0 +1,67 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import fs from 'fs-extra';
+import { executeNativeTool, buildSystemPrompt } from './nativeTools.js';
+let workspace;
+beforeAll(async () => {
+    workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'nf-native-tools-'));
+    await fs.writeFile(path.join(workspace, 'inside.txt'), 'hello', 'utf8');
+    await fs.ensureDir(path.join(workspace, 'sub'));
+});
+afterAll(async () => {
+    await fs.remove(workspace);
+});
+describe('executeNativeTool', () => {
+    it('reads a file inside the workspace', async () => {
+        const out = await executeNativeTool(workspace, 'read_file', { filePath: 'inside.txt' });
+        expect(out).toBe('hello');
+    });
+    it('lists a directory inside the workspace with real newlines', async () => {
+        const out = await executeNativeTool(workspace, 'list_directory', { dirPath: '.' });
+        expect(out.split('\n').sort()).toEqual(['inside.txt', 'sub']);
+    });
+    it('rejects a relative path that escapes the workspace', async () => {
+        await expect(executeNativeTool(workspace, 'read_file', { filePath: '../../../etc/hosts' }))
+            .rejects.toThrow(/escapes the workspace/);
+    });
+    it('rejects an absolute path outside the workspace', async () => {
+        const outside = process.platform === 'win32' ? 'C:\\Windows\\win.ini' : '/etc/hosts';
+        await expect(executeNativeTool(workspace, 'read_file', { filePath: outside }))
+            .rejects.toThrow(/escapes the workspace/);
+    });
+    it('rejects an unknown tool', async () => {
+        await expect(executeNativeTool(workspace, 'delete_everything', {}))
+            .rejects.toThrow(/Unknown tool/);
+    });
+    it('rejects a symlink inside the workspace that points outside it', async () => {
+        const outsideDir = await fs.mkdtemp(path.join(os.tmpdir(), 'nf-outside-'));
+        const secret = path.join(outsideDir, 'secret.txt');
+        await fs.writeFile(secret, 'top secret', 'utf8');
+        const link = path.join(workspace, 'escape.txt');
+        try {
+            await fs.symlink(secret, link);
+        }
+        catch {
+            // Symlink creation needs privileges on Windows; skip if unavailable.
+            await fs.remove(outsideDir);
+            return;
+        }
+        try {
+            await expect(executeNativeTool(workspace, 'read_file', { filePath: 'escape.txt' }))
+                .rejects.toThrow(/escapes the workspace/);
+        }
+        finally {
+            await fs.remove(link);
+            await fs.remove(outsideDir);
+        }
+    });
+});
+describe('buildSystemPrompt', () => {
+    it('states the workspace path and read-only scope', () => {
+        const p = buildSystemPrompt('/tmp/ws');
+        expect(p).toContain('/tmp/ws');
+        expect(p).toContain('read-only');
+    });
+});
+//# sourceMappingURL=nativeTools.test.js.map

package/dist/agent/nativeTools.test.js.map

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

package/dist/agent/session.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @module agent/session
+ * Session identity for chat agents that support resumable conversations.
+ */
+/** A chat session to create or resume. `resume` means the session already has turns on disk. */
+export interface AgentSession {
+    id: string;
+    resume: boolean;
+}
+/**
+ * Strict UUID check. Session ids come from the client and end up in the argv of a
+ * shell:true spawn, so only the inert UUID charset may pass.
+ */
+export declare function isValidSessionUuid(id: unknown): id is string;
+/**
+ * Builds the claude CLI args for one print-mode turn. The prompt itself is
+ * always piped via stdin, never argv.
+ *
+ * Without a session the legacy behavior applies: `-c` continues the most
+ * recent conversation in the cwd. With a session, a fresh id is created via
+ * --session-id on the first turn and every later turn resumes that id;
+ * resumed sessions use --resume from the start.
+ */
+export declare function buildClaudeTurnArgs(isFirstTurn: boolean, session?: AgentSession): string[];
+//# sourceMappingURL=session.d.ts.map

package/dist/agent/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/agent/session.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,gGAAgG;AAChG,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,OAAO,CAAC;CACjB;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,OAAO,GAAG,EAAE,IAAI,MAAM,CAE5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,CAQ1F"}

package/dist/agent/session.js

@@ -0,0 +1,31 @@
+/**
+ * @module agent/session
+ * Session identity for chat agents that support resumable conversations.
+ */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Strict UUID check. Session ids come from the client and end up in the argv of a
+ * shell:true spawn, so only the inert UUID charset may pass.
+ */
+export function isValidSessionUuid(id) {
+    return typeof id === 'string' && UUID_RE.test(id);
+}
+/**
+ * Builds the claude CLI args for one print-mode turn. The prompt itself is
+ * always piped via stdin, never argv.
+ *
+ * Without a session the legacy behavior applies: `-c` continues the most
+ * recent conversation in the cwd. With a session, a fresh id is created via
+ * --session-id on the first turn and every later turn resumes that id;
+ * resumed sessions use --resume from the start.
+ */
+export function buildClaudeTurnArgs(isFirstTurn, session) {
+    if (!session) {
+        return isFirstTurn ? ['-p'] : ['-c', '-p'];
+    }
+    if (!session.resume && isFirstTurn) {
+        return ['-p', '--session-id', session.id];
+    }
+    return ['-p', '--resume', session.id];
+}
+//# sourceMappingURL=session.js.map

package/dist/agent/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/agent/session.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,MAAM,OAAO,GAAG,iEAAiE,CAAC;AAElF;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAW;IAC5C,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAoB,EAAE,OAAsB;IAC9E,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,WAAW,EAAE,CAAC;QACnC,OAAO,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;AACxC,CAAC"}

package/dist/agent/session.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=session.test.d.ts.map

package/dist/agent/session.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.test.d.ts","sourceRoot":"","sources":["../../src/agent/session.test.ts"],"names":[],"mappings":""}

package/dist/agent/session.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { buildClaudeTurnArgs, isValidSessionUuid } from './session.js';
+const ID = '123e4567-e89b-42d3-a456-426614174000';
+describe('buildClaudeTurnArgs', () => {
+    it('uses plain -p on the first legacy turn', () => {
+        expect(buildClaudeTurnArgs(true)).toEqual(['-p']);
+    });
+    it('continues with -c on later legacy turns', () => {
+        expect(buildClaudeTurnArgs(false)).toEqual(['-c', '-p']);
+    });
+    it('creates a new session with --session-id on the first turn', () => {
+        expect(buildClaudeTurnArgs(true, { id: ID, resume: false })).toEqual(['-p', '--session-id', ID]);
+    });
+    it('resumes the created session on later turns', () => {
+        expect(buildClaudeTurnArgs(false, { id: ID, resume: false })).toEqual(['-p', '--resume', ID]);
+    });
+    it('resumes an existing session from the first turn', () => {
+        expect(buildClaudeTurnArgs(true, { id: ID, resume: true })).toEqual(['-p', '--resume', ID]);
+    });
+    it('keeps resuming an existing session on later turns', () => {
+        expect(buildClaudeTurnArgs(false, { id: ID, resume: true })).toEqual(['-p', '--resume', ID]);
+    });
+});
+describe('isValidSessionUuid', () => {
+    it('accepts a lowercase uuid', () => {
+        expect(isValidSessionUuid(ID)).toBe(true);
+    });
+    it('accepts an uppercase uuid', () => {
+        expect(isValidSessionUuid(ID.toUpperCase())).toBe(true);
+    });
+    it('rejects empty strings', () => {
+        expect(isValidSessionUuid('')).toBe(false);
+    });
+    it('rejects shell metacharacters', () => {
+        expect(isValidSessionUuid('x; rm -rf .')).toBe(false);
+        expect(isValidSessionUuid(`${ID} && echo pwned`)).toBe(false);
+    });
+    it('rejects non-strings', () => {
+        expect(isValidSessionUuid(undefined)).toBe(false);
+        expect(isValidSessionUuid(42)).toBe(false);
+        expect(isValidSessionUuid({ id: ID })).toBe(false);
+    });
+});
+//# sourceMappingURL=session.test.js.map

package/dist/agent/session.test.js.map

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

package/dist/commands/create.d.ts

@@ -5,13 +5,14 @@
  */
 /**
  * Executes the full "create workspace" flow:
- * 1. Prompt for branch name
- * 2. Prompt for feature description
- * 3. Scan for repos and let user pick
- * 4. Detect AI assistants and let user pick
- * 5. Create workspace with git worktrees
- * 6. Generate AI context files
- * 7. Optionally open in editor
+ * 1. Pick a registered project (or ad-hoc repos)
+ * 2. Choose the work mode: in-place (no git ceremony) or isolated worktrees
+ * 3. Prompt for branch name (worktree) or workspace name (in-place)
+ * 4. Prompt for feature description; select repos when ad hoc
+ * 5. Detect AI assistants and let user pick
+ * 6. Create the workspace (worktrees only in worktree mode)
+ * 7. Generate AI context files
+ * 8. Optionally open in editor
  */
 export declare function createCommand(): Promise<void>;
 //# sourceMappingURL=create.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/commands/create.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkCH;;;;;;;;;GASG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CA+OnD"}
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/commands/create.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoCH;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAwTnD"}

package/dist/commands/create.js

@@ -7,78 +7,143 @@ import chalk from 'chalk';
 import ora from 'ora';
 import path from 'node:path';
 import { execa } from 'execa';
-import { confirm } from '@inquirer/prompts';
+import { confirm, input, select } from '@inquirer/prompts';
 import { loadConfig } from '../core/config.js';
 import { scanForRepos } from '../core/scanner.js';
-import { createWorkspace } from '../core/workspace.js';
+import { createWorkspace, resolveRepoInfos } from '../core/workspace.js';
 import { generateContextFiles } from '../generators/index.js';
 import { analyzeAllRepos } from '../analyzers/index.js';
 import { detectAIAssistants } from '../utils/detect-ai.js';
 import { detectEditors } from '../utils/detect-editors.js';
 import { openInEditor } from '../utils/open-editor.js';
 import { debugLog } from '../utils/debug.js';
+import { getSessionCwd } from '../utils/feature.js';
 import { promptBranchName, promptDescription, promptSelectRepos, promptSelectAI, promptSelectEditor, promptSelectStrategy, promptNewStrategy, promptNewProjectName, promptRepoBranches, } from '../utils/prompts.js';
 import { createNewRepo } from '../core/new-repo.js';
+import { loadProjects, slugifyProjectName } from '../core/projects.js';
 import { suggestWorkflow } from '../utils/workflow-advisor.js';
 import { getWorkflowTemplates, saveWorkflowTemplate } from '../utils/workflows.js';
 /**
  * Executes the full "create workspace" flow:
- * 1. Prompt for branch name
- * 2. Prompt for feature description
- * 3. Scan for repos and let user pick
- * 4. Detect AI assistants and let user pick
- * 5. Create workspace with git worktrees
- * 6. Generate AI context files
- * 7. Optionally open in editor
+ * 1. Pick a registered project (or ad-hoc repos)
+ * 2. Choose the work mode: in-place (no git ceremony) or isolated worktrees
+ * 3. Prompt for branch name (worktree) or workspace name (in-place)
+ * 4. Prompt for feature description; select repos when ad hoc
+ * 5. Detect AI assistants and let user pick
+ * 6. Create the workspace (worktrees only in worktree mode)
+ * 7. Generate AI context files
+ * 8. Optionally open in editor
  */
 export async function createCommand() {
-    console.log(chalk.bold.cyan('\n🚀 NexusFlow — Create Feature Workspace\n'));
-    // ── 1. Branch name ──────────────────────────────────────────────────
-    const branchName = await promptBranchName();
-    // ── 2. Feature description ──────────────────────────────────────────
-    const description = await promptDescription();
-    // ── 3. Scan for repos ───────────────────────────────────────────────
+    console.log(chalk.bold.cyan('\n🚀 NexusFlow — Start Work\n'));
     const config = await loadConfig();
-    const spinner = ora('Scanning for projects...').start();
-    let repos;
-    try {
-        repos = await scanForRepos(config.devDir, config.scanDepth);
-        spinner.succeed(`Found ${chalk.bold(repos.length)} projects in ${config.devDir}`);
+    // ── 0. Project selection (when a registry exists) ───────────────────
+    const projects = await loadProjects({ quiet: true });
+    let project = null;
+    if (projects.length > 0) {
+        const choice = await select({
+            message: 'Start from a project?',
+            choices: [
+                ...projects.map((p) => ({
+                    name: `${p.name} ${chalk.dim(`(${p.repos.map((r) => path.basename(r.path)).join(', ')})`)}`,
+                    value: p.id,
+                })),
+                { name: 'Ad-hoc — pick repos manually', value: '' },
+            ],
+        });
+        project = choice ? projects.find((p) => p.id === choice) ?? null : null;
     }
-    catch (error) {
-        spinner.fail('Failed to scan for projects');
-        throw error;
+    // ── 1. Work mode ─────────────────────────────────────────────────────
+    const mode = await select({
+        message: 'How do you want to work?',
+        choices: [
+            {
+                name: 'In-place — directly in the source repos (no branches, fastest start)',
+                value: 'in-place',
+            },
+            {
+                name: 'Isolated worktrees — a feature branch and worktree per repo',
+                value: 'worktree',
+            },
+        ],
+    });
+    const inPlace = mode === 'in-place';
+    // ── 2. Identity: feature branch, or a plain name for in-place ───────
+    let branchName = '';
+    let workspaceId = '';
+    if (inPlace) {
+        const workspaceName = await input({
+            message: 'Workspace name:',
+            validate: (value) => slugifyProjectName(value).length > 0 || 'Name needs at least one letter or digit',
+        });
+        workspaceId = slugifyProjectName(workspaceName);
+        branchName = workspaceId; // populated for display/back-compat; no branch is created
     }
-    if (repos.length === 0) {
-        console.log(chalk.yellow('No git projects found. Check your devDir setting.'));
-        return;
+    else {
+        branchName = await promptBranchName();
+        workspaceId = branchName;
     }
-    // ── 4. Select repos ────────────────────────────────────────────────
-    const selectedRepos = await promptSelectRepos(repos);
-    // ── 4.1. Optionally scaffold brand-new projects ─────────────────────
-    while (await confirm({
-        message: '➕ Create a brand-new project to include in this workspace?',
-        default: false,
-    })) {
-        const projectName = await promptNewProjectName(config.devDir);
-        const newRepoSpinner = ora(`Creating new project ${projectName}...`).start();
+    // ── 2.1. Feature description ─────────────────────────────────────────
+    const description = await promptDescription();
+    // ── 3-4. Repos: from the project, or scanned and picked ad hoc ───────
+    let selectedRepos;
+    if (project) {
+        // Re-resolve at create time: the registry's defaultBranch is a snapshot
+        // from `project add` and may have gone stale (repo moved, default branch
+        // renamed) — basing a new feature branch on it would be silently wrong.
+        const projectSpinner = ora(`Validating repositories of ${project.name}...`).start();
         try {
-            const newRepo = await createNewRepo(config.devDir, projectName);
-            selectedRepos.push(newRepo);
-            newRepoSpinner.succeed(`Created ${chalk.bold(newRepo.name)} at ${newRepo.path}`);
+            selectedRepos = await resolveRepoInfos(project.repos.map((r) => r.path));
+            projectSpinner.succeed(`Repos from ${project.name}: ${selectedRepos.map((r) => r.name).join(', ')}`);
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            newRepoSpinner.fail(`Could not create project: ${message}`);
+            projectSpinner.fail(`A repository of project "${project.name}" is missing or not a git repo — fix it with "nexusflow project add/remove".`);
+            throw error;
         }
     }
-    if (selectedRepos.length === 0) {
-        console.log(chalk.yellow('No projects selected. Exiting.'));
-        return;
+    else {
+        const spinner = ora('Scanning for projects...').start();
+        let repos;
+        try {
+            repos = await scanForRepos(config.devDir, config.scanDepth);
+            spinner.succeed(`Found ${chalk.bold(repos.length)} projects in ${config.devDir}`);
+        }
+        catch (error) {
+            spinner.fail('Failed to scan for projects');
+            throw error;
+        }
+        if (repos.length === 0) {
+            console.log(chalk.yellow('No git projects found. Check your devDir setting.'));
+            return;
+        }
+        selectedRepos = await promptSelectRepos(repos);
+        // ── 4.1. Optionally scaffold brand-new projects ─────────────────────
+        while (await confirm({
+            message: '➕ Create a brand-new project to include in this workspace?',
+            default: false,
+        })) {
+            const projectName = await promptNewProjectName(config.devDir);
+            const newRepoSpinner = ora(`Creating new project ${projectName}...`).start();
+            try {
+                const newRepo = await createNewRepo(config.devDir, projectName);
+                selectedRepos.push(newRepo);
+                newRepoSpinner.succeed(`Created ${chalk.bold(newRepo.name)} at ${newRepo.path}`);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                newRepoSpinner.fail(`Could not create project: ${message}`);
+            }
+        }
+        if (selectedRepos.length === 0) {
+            console.log(chalk.yellow('No projects selected. Exiting.'));
+            return;
+        }
+        console.log(chalk.dim(`  Selected: ${selectedRepos.map((r) => r.name).join(', ')}`));
     }
-    console.log(chalk.dim(`  Selected: ${selectedRepos.map((r) => r.name).join(', ')}`));
-    // ── 4.2. Optionally use existing branches per repo ──────────────────
-    const branchOverrides = await promptRepoBranches(selectedRepos, branchName);
+    // ── 4.2. Optionally use existing branches per repo (worktree only) ───
+    const branchOverrides = inPlace
+        ? new Map()
+        : await promptRepoBranches(selectedRepos, branchName);
     for (const repo of selectedRepos) {
         const override = branchOverrides.get(repo.name);
         if (override) {
@@ -89,9 +154,6 @@ export async function createCommand() {
     // ── 5. Detect and select AI assistants ──────────────────────────────
     const detectedAI = await detectAIAssistants();
     const selectedAI = await promptSelectAI(detectedAI);
-    const localLlmEnabled = config.localLlm?.enabled
-        ? await confirm({ message: 'Enable Local AI Co-processor in this workspace context?', default: true })
-        : false;
     // ── 5.5. Suggest workflow strategy ───────────────────────────────
     const templates = await getWorkflowTemplates();
     const selectedStrategyId = await promptSelectStrategy(templates);
@@ -99,7 +161,7 @@ export async function createCommand() {
     if (selectedStrategyId === 'auto') {
         const workflowSpinner = ora('Suggesting teamwork collaboration strategy...').start();
         try {
-            const suggestion = await suggestWorkflow(description, selectedRepos, config.localLlm);
+            const suggestion = await suggestWorkflow(description, selectedRepos);
             teamworkInstructions = suggestion.customInstructions;
             workflowSpinner.succeed(`Auto-selected strategy for ${chalk.bold(suggestion.difficulty)} difficulty task`);
         }
@@ -129,21 +191,24 @@ export async function createCommand() {
         }
     }
     // ── 6. Create workspace ─────────────────────────────────────────────
-    const workspacePath = path.join(config.workspacesDir, branchName);
+    const workspacePath = path.join(config.workspacesDir, workspaceId);
     const feature = {
-        id: branchName,
+        id: workspaceId,
+        mode,
+        projectId: project?.id,
         branchName,
         description,
-        repos: selectedRepos.map((r) => path.join(workspacePath, r.name)),
+        repos: inPlace
+            ? selectedRepos.map((r) => r.path)
+            : selectedRepos.map((r) => path.join(workspacePath, r.name)),
         originalRepos: selectedRepos.map((r) => r.path),
         repoBranches: branchOverrides.size > 0 ? Object.fromEntries(branchOverrides) : undefined,
         assistants: selectedAI,
         workspacePath,
         createdAt: new Date().toISOString(),
-        localLlmEnabled,
         teamworkInstructions,
     };
-    const wsSpinner = ora('Creating workspace with git worktrees...').start();
+    const wsSpinner = ora(inPlace ? 'Registering workspace...' : 'Creating workspace with git worktrees...').start();
     try {
         await createWorkspace(feature, selectedRepos, (repoName, index, total) => {
             wsSpinner.text = `Creating worktrees… ${repoName} (${index + 1}/${total})`;
@@ -161,15 +226,17 @@ export async function createCommand() {
     // ── 7-8. Analyze projects & generate context ────────────────────────
     // The worktrees are the product; if analysis/generation fails the workspace
     // is still usable, so keep it and tell the user how to retry rather than
-    // exiting with an error.
-    const workspaceRepos = selectedRepos.map((repo) => ({
-        ...repo,
-        path: path.join(workspacePath, repo.name),
-    }));
+    // exiting with an error. In-place analysis runs on the source repos.
+    const workspaceRepos = inPlace
+        ? selectedRepos
+        : selectedRepos.map((repo) => ({
+            ...repo,
+            path: path.join(workspacePath, repo.name),
+        }));
     try {
         console.log(chalk.cyan('\nAnalyzing projects...'));
         const analysis = await analyzeAllRepos(workspaceRepos);
-        const ctx = { feature, repos: workspaceRepos, analysis, localLlm: config.localLlm };
+        const ctx = { feature, repos: workspaceRepos, analysis };
         console.log(chalk.cyan('\nGenerating AI context files...'));
         await generateContextFiles(ctx, selectedAI, workspacePath);
     }
@@ -194,10 +261,11 @@ export async function createCommand() {
     // ── Done ────────────────────────────────────────────────────────────
     console.log(chalk.bold.green('\n✅ Workspace ready!\n'));
     console.log(`  ${chalk.dim('Path:')}  ${workspacePath}`);
-    console.log(`  ${chalk.dim('Branch:')} ${branchName}`);
+    console.log(inPlace
+        ? `  ${chalk.dim('Mode:')}   in-place (working directly in the source repos)`
+        : `  ${chalk.dim('Branch:')} ${branchName}`);
     console.log(`  ${chalk.dim('Repos:')}  ${selectedRepos.map((r) => r.name).join(', ')}`);
     console.log(`  ${chalk.dim('AI:')}     ${selectedAI.join(', ')}`);
-    console.log(`  ${chalk.dim('Local AI:')} ${localLlmEnabled ? 'Enabled' : 'Disabled'}`);
     console.log(`\n  ${chalk.dim('To navigate:')} cd "${workspacePath}"`);
     console.log();
     // ── 9. Start AI Assistant Session ───────────────────────────────────
@@ -219,16 +287,17 @@ export async function createCommand() {
             });
             if (confirmStart) {
                 console.log(chalk.cyan(`\n🚀 Starting ${label} session inside workspace...\n`));
+                const sessionCwd = getSessionCwd(feature);
                 try {
                     await execa(launchCmd, [], {
-                        cwd: workspacePath,
+                        cwd: sessionCwd,
                         stdio: 'inherit',
                         shell: process.platform === 'win32',
                     });
                     console.log(chalk.green(`\n👋 Exited ${label} session.`));
                 }
                 catch {
-                    console.log(chalk.yellow(`\n⚠️  Could not start ${label}. Please start it manually:\n  ${chalk.dim(`cd "${workspacePath}" && ${launchCmd}`)}`));
+                    console.log(chalk.yellow(`\n⚠️  Could not start ${label}. Please start it manually:\n  ${chalk.dim(`cd "${sessionCwd}" && ${launchCmd}`)}`));
                 }
             }
         }