@launch11/srgical 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LaunchEleven
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# srgical
+
+`srgical` is a local-first orchestration CLI for the workflow you have already been using manually:
+
+1. talk to an AI until the plan is sharp,
+2. write a four-file planning pack into the repo,
+3. repeatedly execute the next eligible step,
+4. force validation and handoff updates every time.
+
+The current launch slice supports both local `codex` and local `claude` CLI installs through the same `.srgical/`
+workflow. `srgical` detects which supported tools are actually installed, keeps the planning pack agent-neutral, and
+lets you choose the active agent for the current workspace session.
+
+## Why This Exists
+
+The reference system in `G:\code\Launch11Projects\Writr\migrations-part-5` is strong because it does not just create a
+plan. It creates momentum:
+
+- a stable architecture file,
+- a current-context handoff log,
+- a step-by-step tracker,
+- and a repeatable next-agent prompt that keeps execution disciplined.
+
+`srgical` turns that from a repeated copy-paste ritual into a product.
+
+## Current Slice
+
+This repo currently ships the foundation for:
+
+- `srgical doctor`
+  Reports whether the current workspace has a planning pack, which supported agent is active, and which supported
+  agents are available locally.
+- `srgical init`
+  Creates a local `.srgical/` planning pack from built-in templates.
+- `srgical studio`
+  Opens a full-screen planning studio where you can plan against the repo, inspect supported tools with `/agents`,
+  switch the session agent with `/agent <id>`, and explicitly trigger pack writes or execution.
+- `srgical run-next`
+  Replays the generated next-agent prompt through the active agent, with `--dry-run` for safe preview and
+  `--agent <id>` for a one-run override that does not change the stored workspace choice.
+
+## Supported Agents
+
+- `codex`
+  Supported in the current launch slice for planning, pack writing, and `run-next` execution.
+- `claude`
+  Supported through the same adapter seam for planning, pack writing, and execution when the local Claude Code CLI is
+  installed and available on `PATH`.
+
+If only one supported agent is installed, `srgical` can auto-select it for the workspace session. If both are
+installed, you can keep the stored choice in the studio and still override a single execution with
+`srgical run-next --agent <id>`.
+
+## Design Direction
+
+The product should feel closer to a creative control room than a grey enterprise shell:
+
+- dark graphite base
+- hot coral and amber accents
+- crisp cyan status treatment
+- large, cinematic panel framing
+- transcript-first layout instead of command soup
+
+The first TUI pass already leans in that direction, and we can keep pushing it.
+
+## Distribution
+
+The first production channels are GitHub Packages, the public npm registry, and GitHub Releases for downloadable
+release assets. Version intent stays in git, and GitHub Actions bumps `package.json`, writes `CHANGELOG.md`, pushes
+that release commit back to `main`, publishes the GitHub-scoped package, publishes the npm org package, and creates a
+GitHub Release with the built tarballs attached.
+
+For a local production-style packaging check:
+
+```bash
+npm run release:pack
+```
+
+The release bundle lands under `.artifacts/release/`. The broader distribution path, including standalone binaries and
+wrapper package-manager installs, is documented in `docs/distribution.md`.
+
+For release work, add a changeset in your feature branch:
+
+```bash
+npm run changeset
+```
+
+When that branch reaches `main`, the release workflow versions the package, publishes `@launcheleven/srgical` to
+GitHub Packages, publishes `@launch11/srgical` to npm, and opens a matching GitHub Release entry with the packaged
+artifacts.
+
+## Install Prerequisites
+
+Install `srgical`, then install at least one supported local agent CLI separately.
+
+```bash
+npm install
+npm run build
+node dist/index.js doctor
+```
+
+`doctor` is the source of truth for local availability. If an agent CLI is missing, `srgical` reports it as missing
+instead of pretending it can run that path anyway.
+
+The package publishes in two install channels:
+
+- GitHub Packages: `@launcheleven/srgical`
+- npm public registry: `@launch11/srgical`
+
+For GitHub Packages installs, consumers need an `.npmrc` entry for `@launcheleven` plus a token before running:
+
+```bash
+npm install -g @launcheleven/srgical
+```
+
+For npm installs, consumers can use:
+
+```bash
+npm install -g @launch11/srgical
+```
+
+## Getting Started
+
+```bash
+npm install
+npm run build
+node dist/index.js doctor
+node dist/index.js studio
+```
+
+During development:
+
+```bash
+npm run dev -- studio
+```
+
+Typical flow once a workspace has a pack:
+
+```bash
+node dist/index.js doctor
+node dist/index.js run-next --dry-run
+node dist/index.js run-next
+```
+
+To override the active workspace agent for one execution only:
+
+```bash
+node dist/index.js run-next --agent codex
+node dist/index.js run-next --agent claude
+```
+
+## Current Claude Caveat
+
+Claude support is real, but it is not treated as interchangeable with Codex. The current non-interactive Claude path
+uses `plan` mode for planner replies and `acceptEdits` with allowlisted local tools for pack-writing and execution.
+
+If the Claude CLI is not installed locally, `doctor`, the studio, and `run-next --agent claude` all report that
+honestly instead of falling back to a fake Claude path.
+
+## Planned Next Steps
+
+- deepen the studio experience without weakening the terminal-first workflow
+- keep dual-agent docs and validation honest as Claude runtime behavior gets more live coverage
+- expand release outputs from npm tarballs into standalone binaries and wrapper package-manager installers

package/dist/commands/doctor.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDoctorCommand = runDoctorCommand;
+const node_process_1 = __importDefault(require("node:process"));
+const agent_1 = require("../core/agent");
+const planning_pack_state_1 = require("../core/planning-pack-state");
+const workspace_1 = require("../core/workspace");
+async function runDoctorCommand(workspaceArg) {
+    const workspace = (0, workspace_1.resolveWorkspace)(workspaceArg);
+    const [resolvedAgent, packState, gitRepo] = await Promise.all([
+        (0, agent_1.resolvePrimaryAgent)(workspace),
+        (0, planning_pack_state_1.readPlanningPackState)(workspace),
+        (0, workspace_1.isGitRepo)(workspace)
+    ]);
+    const { status: activeAgent, statuses } = resolvedAgent;
+    const lines = [
+        `Workspace: ${workspace}`,
+        `Git repo: ${gitRepo ? "yes" : "no"}`,
+        `Planning pack: ${packState.packPresent ? "present" : "missing"}`,
+        `Active agent: ${activeAgent.label} (${activeAgent.id}) - ${formatAgentAvailability(activeAgent)}`,
+        "",
+        ...renderSupportedAgentLines(statuses, activeAgent.id),
+    ];
+    if (packState.packPresent) {
+        lines.push("", ...renderNextStepLines(packState.nextStepSummary, packState.currentPosition.nextRecommended));
+    }
+    lines.push("", packState.packPresent
+        ? packState.nextStepSummary || packState.currentPosition.nextRecommended
+            ? "Next move: run `srgical studio` to refine the plan or `srgical run-next` to execute the next step."
+            : "Next move: run `srgical studio` to queue more work or update the tracker with a new recommended step."
+        : "Next move: run `srgical init` for a local scaffold or `srgical studio` to plan with the primary agent first.");
+    node_process_1.default.stdout.write(`${lines.join("\n")}\n`);
+}
+function renderSupportedAgentLines(statuses, activeAgentId) {
+    const lines = ["Supported agents:"];
+    for (const status of statuses) {
+        lines.push(`- ${status.label} (${status.id})${status.id === activeAgentId ? " [active]" : ""}: ${formatAgentAvailability(status)} via ${status.command}`);
+    }
+    return lines;
+}
+function formatAgentAvailability(status) {
+    return status.available
+        ? `available (${status.version ?? "version unknown"})`
+        : `missing (${status.error ?? "unknown error"})`;
+}
+function renderNextStepLines(nextStepSummary, nextRecommended) {
+    if (!nextStepSummary) {
+        return [
+            "Next Step: unavailable",
+            nextRecommended
+                ? `Tracker points to \`${nextRecommended}\`, but its table row could not be summarized.`
+                : "Tracker does not currently expose a next recommended step."
+        ];
+    }
+    const lines = [
+        `Next Step: ${nextStepSummary.id}${nextStepSummary.phase ? ` (${nextStepSummary.phase})` : ""}`,
+        `  Scope: ${nextStepSummary.scope || "unknown"}`,
+        `  Acceptance: ${nextStepSummary.acceptance || "unknown"}`,
+        `  Status: ${nextStepSummary.status || "unknown"}`
+    ];
+    if (nextStepSummary.notes) {
+        lines.push(`  Notes: ${nextStepSummary.notes}`);
+    }
+    return lines;
+}

package/dist/commands/init.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInitCommand = runInitCommand;
+const node_process_1 = __importDefault(require("node:process"));
+const templates_1 = require("../core/templates");
+const workspace_1 = require("../core/workspace");
+async function runInitCommand(workspaceArg, force = false) {
+    const workspace = (0, workspace_1.resolveWorkspace)(workspaceArg);
+    const exists = await (0, workspace_1.planningPackExists)(workspace);
+    if (exists && !force) {
+        throw new Error("A .srgical planning pack already exists. Re-run with --force to overwrite it.");
+    }
+    const paths = await (0, workspace_1.ensurePlanningDir)(workspace);
+    const templates = (0, templates_1.getInitialTemplates)(paths);
+    await Promise.all(Object.entries(templates).map(([filePath, content]) => (0, workspace_1.writeText)(filePath, content)));
+    node_process_1.default.stdout.write([
+        `Created planning pack in ${paths.dir}`,
+        `- ${paths.plan}`,
+        `- ${paths.context}`,
+        `- ${paths.tracker}`,
+        `- ${paths.nextPrompt}`
+    ].join("\n") + "\n");
+}

package/dist/commands/run-next.js

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRunNextCommand = runRunNextCommand;
+const node_process_1 = __importDefault(require("node:process"));
+const agent_1 = require("../core/agent");
+const execution_state_1 = require("../core/execution-state");
+const execution_controls_1 = require("../core/execution-controls");
+const planning_pack_state_1 = require("../core/planning-pack-state");
+const workspace_1 = require("../core/workspace");
+async function runRunNextCommand(workspaceArg, options = {}) {
+    const workspace = (0, workspace_1.resolveWorkspace)(workspaceArg);
+    const packState = await (0, planning_pack_state_1.readPlanningPackState)(workspace);
+    if (!packState.packPresent) {
+        throw new Error("No .srgical planning pack found. Run `srgical init` or `srgical studio` first.");
+    }
+    if (!options.dryRun && !(0, execution_controls_1.hasQueuedNextStep)(packState.currentPosition.nextRecommended)) {
+        throw new Error((0, execution_controls_1.formatNoQueuedNextStepMessage)("run-next"));
+    }
+    await (0, agent_1.resolveExecutionAgent)(workspace, options.agent);
+    const paths = (0, workspace_1.getPlanningPackPaths)(workspace);
+    const prompt = await (0, workspace_1.readText)(paths.nextPrompt);
+    const previewLines = options.dryRun
+        ? (0, execution_controls_1.renderDryRunPreview)(prompt, packState.nextStepSummary, packState.currentPosition.nextRecommended)
+        : (0, execution_controls_1.renderExecutionStepLines)(packState.nextStepSummary, packState.currentPosition.nextRecommended);
+    for (const line of previewLines) {
+        node_process_1.default.stdout.write(`${line}\n`);
+    }
+    if (options.dryRun) {
+        return;
+    }
+    node_process_1.default.stdout.write("\n");
+    node_process_1.default.stdout.write(`Running the current next-agent prompt through ${(0, agent_1.getPrimaryAgentAdapter)().label}...\n`);
+    try {
+        const result = await (0, agent_1.runNextPrompt)(workspace, prompt, {
+            agentId: options.agent
+        });
+        await (0, execution_state_1.saveExecutionState)(workspace, "success", "run-next", result);
+        await (0, execution_state_1.appendExecutionLog)(workspace, "success", "run-next", result, {
+            stepLabel: (0, execution_controls_1.formatStepLabel)(packState.nextStepSummary, packState.currentPosition.nextRecommended)
+        });
+        node_process_1.default.stdout.write(`${result}\n`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        await (0, execution_state_1.saveExecutionState)(workspace, "failure", "run-next", message);
+        await (0, execution_state_1.appendExecutionLog)(workspace, "failure", "run-next", message, {
+            stepLabel: (0, execution_controls_1.formatStepLabel)(packState.nextStepSummary, packState.currentPosition.nextRecommended)
+        });
+        throw new Error((0, execution_controls_1.formatExecutionFailureMessage)(message, packState.nextStepSummary, packState.currentPosition.nextRecommended, "run-next"));
+    }
+}

package/dist/commands/studio.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runStudioCommand = runStudioCommand;
+const studio_1 = require("../ui/studio");
+async function runStudioCommand(workspaceArg) {
+    await (0, studio_1.launchStudio)({ workspace: workspaceArg });
+}

package/dist/core/agent.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSupportedAgentAdapters = getSupportedAgentAdapters;
+exports.getPrimaryAgentAdapter = getPrimaryAgentAdapter;
+exports.detectSupportedAgents = detectSupportedAgents;
+exports.resolvePrimaryAgent = resolvePrimaryAgent;
+exports.detectPrimaryAgent = detectPrimaryAgent;
+exports.resolveExecutionAgent = resolveExecutionAgent;
+exports.requestPlannerReply = requestPlannerReply;
+exports.writePlanningPack = writePlanningPack;
+exports.runNextPrompt = runNextPrompt;
+exports.selectPrimaryAgent = selectPrimaryAgent;
+exports.resetAgentAdaptersForTesting = resetAgentAdaptersForTesting;
+exports.setAgentAdaptersForTesting = setAgentAdaptersForTesting;
+const claude_1 = require("./claude");
+const codex_1 = require("./codex");
+const studio_session_1 = require("./studio-session");
+const codexAdapter = {
+    id: "codex",
+    label: "Codex",
+    async detectStatus() {
+        const status = await (0, codex_1.detectCodex)();
+        return {
+            id: "codex",
+            label: "Codex",
+            available: status.available,
+            command: status.command,
+            version: status.version,
+            error: status.error
+        };
+    },
+    requestPlannerReply: codex_1.requestPlannerReply,
+    writePlanningPack: codex_1.writePlanningPack,
+    runNextPrompt: codex_1.runNextPrompt
+};
+const claudeAdapter = {
+    id: "claude",
+    label: "Claude Code",
+    async detectStatus() {
+        const status = await (0, claude_1.detectClaude)();
+        return {
+            id: "claude",
+            label: "Claude Code",
+            available: status.available,
+            command: status.command,
+            version: status.version,
+            error: status.error
+        };
+    },
+    requestPlannerReply: claude_1.requestPlannerReply,
+    writePlanningPack: claude_1.writePlanningPack,
+    runNextPrompt: claude_1.runNextPrompt
+};
+const defaultAgentAdapters = [codexAdapter, claudeAdapter];
+let registeredAgentAdapters = [...defaultAgentAdapters];
+let primaryAgentId = registeredAgentAdapters[0].id;
+function getSupportedAgentAdapters() {
+    return [...registeredAgentAdapters];
+}
+function getPrimaryAgentAdapter() {
+    return getAgentAdapterById(primaryAgentId) ?? getSupportedAgentAdapters()[0];
+}
+async function detectSupportedAgents(workspaceRoot) {
+    const statuses = await collectAgentStatuses();
+    syncPrimaryAgent((await resolvePrimaryAgentStatus(statuses, workspaceRoot)).id);
+    return statuses;
+}
+async function resolvePrimaryAgent(workspaceRoot) {
+    const statuses = await collectAgentStatuses();
+    const status = await resolvePrimaryAgentStatus(statuses, workspaceRoot);
+    const adapter = getAgentAdapterById(status.id) ?? getSupportedAgentAdapters()[0];
+    syncPrimaryAgent(adapter.id);
+    return {
+        adapter,
+        status,
+        statuses
+    };
+}
+async function detectPrimaryAgent(workspaceRoot) {
+    return (await resolvePrimaryAgent(workspaceRoot)).status;
+}
+async function resolveExecutionAgent(workspaceRoot, overrideId) {
+    const normalizedOverrideId = overrideId?.trim().toLowerCase();
+    if (!normalizedOverrideId) {
+        return resolvePrimaryAgent(workspaceRoot);
+    }
+    const statuses = await collectAgentStatuses();
+    const status = statuses.find((candidate) => candidate.id === normalizedOverrideId);
+    if (!status) {
+        throw new Error(`Unknown agent \`${overrideId}\`. Supported agents: ${getSupportedAgentAdapters().map((adapter) => adapter.id).join(", ")}.`);
+    }
+    if (!status.available) {
+        throw new Error(`Cannot use ${status.label} for this run: ${status.error ?? `${status.command} is not available`}.`);
+    }
+    const adapter = getAgentAdapterById(status.id) ?? getSupportedAgentAdapters()[0];
+    syncPrimaryAgent(adapter.id);
+    return {
+        adapter,
+        status,
+        statuses
+    };
+}
+async function requestPlannerReply(workspaceRoot, messages) {
+    const { adapter } = await resolvePrimaryAgent(workspaceRoot);
+    return adapter.requestPlannerReply(workspaceRoot, messages);
+}
+async function writePlanningPack(workspaceRoot, messages) {
+    const { adapter } = await resolvePrimaryAgent(workspaceRoot);
+    return adapter.writePlanningPack(workspaceRoot, messages);
+}
+async function runNextPrompt(workspaceRoot, prompt, options = {}) {
+    const { adapter } = await resolveExecutionAgent(workspaceRoot, options.agentId);
+    return adapter.runNextPrompt(workspaceRoot, prompt);
+}
+async function selectPrimaryAgent(workspaceRoot, id) {
+    const normalizedId = id.trim().toLowerCase();
+    const statuses = await collectAgentStatuses();
+    const status = statuses.find((candidate) => candidate.id === normalizedId);
+    if (!status) {
+        throw new Error(`Unknown agent \`${id}\`. Supported agents: ${getSupportedAgentAdapters().map((adapter) => adapter.id).join(", ")}.`);
+    }
+    if (!status.available) {
+        throw new Error(`Cannot activate ${status.label}: ${status.error ?? `${status.command} is not available`}.`);
+    }
+    await (0, studio_session_1.saveStoredActiveAgentId)(workspaceRoot, status.id);
+    const adapter = getAgentAdapterById(status.id) ?? getSupportedAgentAdapters()[0];
+    syncPrimaryAgent(adapter.id);
+    return {
+        adapter,
+        status,
+        statuses
+    };
+}
+function resetAgentAdaptersForTesting() {
+    registeredAgentAdapters = [...defaultAgentAdapters];
+    primaryAgentId = registeredAgentAdapters[0].id;
+}
+function setAgentAdaptersForTesting(adapters) {
+    registeredAgentAdapters = adapters.length > 0 ? [...adapters] : [...defaultAgentAdapters];
+    primaryAgentId = registeredAgentAdapters[0].id;
+}
+async function collectAgentStatuses() {
+    return Promise.all(getSupportedAgentAdapters().map((adapter) => adapter.detectStatus()));
+}
+async function resolvePrimaryAgentStatus(statuses, workspaceRoot) {
+    const storedId = workspaceRoot ? await (0, studio_session_1.loadStoredActiveAgentId)(workspaceRoot) : null;
+    if (storedId) {
+        const storedStatus = statuses.find((status) => status.id === storedId);
+        if (storedStatus) {
+            return storedStatus;
+        }
+        if (workspaceRoot) {
+            await (0, studio_session_1.saveStoredActiveAgentId)(workspaceRoot, null);
+        }
+    }
+    return statuses.find((status) => status.available) ?? statuses[0];
+}
+function getAgentAdapterById(id) {
+    return registeredAgentAdapters.find((adapter) => adapter.id === id);
+}
+function syncPrimaryAgent(id) {
+    const adapter = getAgentAdapterById(id) ?? getSupportedAgentAdapters()[0];
+    primaryAgentId = adapter.id;
+}