@launch11/srgical 0.0.1

package/docs/adr/0001-tech-stack.md

@@ -0,0 +1,27 @@
+# ADR 0001: Initial Stack
+
+## Status
+
+Accepted on 2026-03-23
+
+## Decision
+
+The first implementation uses TypeScript on Node with:
+
+- `commander` for the CLI surface
+- `blessed` for the full-screen terminal UI
+- native child-process spawning for Codex orchestration
+
+## Why
+
+- Node is already available in the current environment
+- the product needs fast iteration on terminal UX, subprocess orchestration, and text-heavy state
+- packaging through `npm` is immediate, while other install paths can wrap release artifacts later
+- the first version needs to target a real installed agent today, and `codex` is already present
+
+## Consequences
+
+- The first release is easiest to distribute through `npm`
+- Homebrew, Chocolatey, and PyPI support should be treated as release-packaging work, not as a reason to block the
+  initial product
+- if we later want a single native binary without Node, we can revisit Go or .NET once the workflow is proven

package/docs/distribution.md

@@ -0,0 +1,129 @@
+# Distribution Guide
+
+## Current Production Channel
+
+The current production release channels are GitHub Packages for npm, the public npm registry, and GitHub Releases.
+Versioning is source-controlled with Changesets, which means semver intent lives in pull requests instead of being
+inferred from CI build numbers.
+
+The npm package does not bundle `codex` or `claude`. Users still need at least one supported local agent CLI installed
+separately and available on `PATH`, and `srgical doctor` remains the truthful way to confirm which agents are usable on
+the current machine.
+
+## Release Flow
+
+1. A feature branch that changes the package also adds a changeset with `npm run changeset`.
+2. When that branch lands on `main`, the release workflow runs `npm ci`, `npm test`, and `npm run version-packages`.
+3. If the changesets produce a version bump, the workflow commits the updated `package.json`, `CHANGELOG.md`, and
+   consumed changeset files back to `main`.
+4. The same workflow run publishes `@launcheleven/srgical` to GitHub Packages.
+5. The workflow also stages and publishes `@launch11/srgical` to the public npm registry.
+6. After both publishes, the workflow creates a `v<version>` tag and a GitHub Release with the packaged artifacts
+   attached.
+
+This keeps the published semver repeatable across reruns and tracked in git history instead of being tied to a specific
+Actions run number, without requiring a separate release PR just to ship the version bump.
+
+## Local Release Check
+
+Run this from the repo root:
+
+```bash
+npm run release:pack
+```
+
+That command:
+
+- builds the TypeScript CLI,
+- runs `node dist/index.js doctor`,
+- creates an npm tarball under `.artifacts/release/`,
+- writes `release-manifest.json` and `release-manifest.md` with the artifact path and SHA256 hash.
+
+## Registry Configuration
+
+GitHub Packages only supports scoped npm package names. This repo publishes two package names from the same source:
+
+- `@launcheleven/srgical` on GitHub Packages
+- `@launch11/srgical` on the public npm registry
+
+The repo-local `.npmrc` pins that scope to GitHub Packages:
+
+```ini
+@launcheleven:registry=https://npm.pkg.github.com
+```
+
+The workflow publishes the GitHub package with `GITHUB_TOKEN`, which GitHub supports for packages associated with the
+workflow repository. The npm public package uses the repository secret `NPM_TOKEN`. Local installs and local publishes
+still require authentication in the user's own npm config:
+
+```ini
+//npm.pkg.github.com/:_authToken=TOKEN
+@launcheleven:registry=https://npm.pkg.github.com
+```
+
+```ini
+//registry.npmjs.org/:_authToken=TOKEN
+@launch11:registry=https://registry.npmjs.org
+```
+
+## Post-Install Setup
+
+After installing the package, run:
+
+```bash
+srgical doctor
+```
+
+That verifies the workspace state, shows the active agent, and reports whether `codex` and `claude` are locally
+available or missing.
+
+## Artifact Strategy
+
+### npm
+
+- Source of truth for the first production install path.
+- Install target once published:
+
+```bash
+npm install -g @launcheleven/srgical
+```
+
+```bash
+npm install -g @launch11/srgical
+```
+
+- Required local prerequisites after install:
+  - authenticated access to GitHub Packages
+  - `codex` and/or `claude` installed separately
+  - available on `PATH` for the current shell session
+
+- Local install smoke test from a generated tarball:
+
+```bash
+npm install -g ./.artifacts/release/<tarball-name>.tgz
+```
+
+### Standalone Binaries
+
+- Not implemented in this step.
+- Defined path: build Windows, macOS, and Linux binaries from tagged releases once the Node-based CLI workflow is
+  stable enough to freeze into a single-file artifact.
+- Those binaries should be uploaded to GitHub Releases next to the npm tarball so they remain version-aligned.
+
+### Wrapper Package Managers
+
+- Not implemented in this step.
+- Defined path: `brew`, `choco`, and similar wrappers should install versioned GitHub Release artifacts instead of
+  rebuilding from source in each ecosystem.
+- That keeps wrapper packages thin and aligned with the exact tested release outputs.
+
+## Release Inputs
+
+The published npm package should include:
+
+- `dist/`
+- `README.md`
+- `docs/`
+- `LICENSE`
+
+The production entrypoint remains the `srgical` bin mapped to `dist/index.js`.

package/docs/product-foundation.md

@@ -0,0 +1,50 @@
+# Product Foundation
+
+## Source Pattern
+
+The system in `Writr\migrations-part-5` has four durable primitives:
+
+1. `01`: a stable high-level plan
+2. `02`: a current-context kickoff and handoff log
+3. `03`: a detailed step tracker with strict progression rules
+4. `04`: a repeatable next-agent prompt that forces disciplined continuation
+
+That pattern is the product.
+
+## Product Thesis
+
+Teams should be able to run one command, enter a planning studio, talk with an AI until the approach is ready, write a
+tracker pack into the repo, and then keep executing the next valid chunk without manually reconstructing state each
+time.
+
+## Non-Negotiables
+
+- Local-first by default
+- Agent actions remain explicit
+- The workflow is markdown-first and repo-visible
+- Execution must be incremental, resumable, and validation-aware
+- The UI cannot feel like a boring debug console
+
+## V1 Scope
+
+- Two launch-scope agent adapters: `codex` and `claude`
+- One planning-pack format under `.srgical/`
+- One full-screen TUI for planning conversation
+- One execution command that runs the current next-step prompt through the active workspace agent
+- Truthful installed-tool detection plus session-scoped active-agent selection
+
+## V1 Success Criteria
+
+- A new repo can be bootstrapped without manual prompt copy-paste
+- The user can plan inside a dedicated interface instead of a raw shell
+- The generated pack is close enough to the existing Writr-style system that it feels familiar
+- The user can trigger the next execution loop with a single command
+- The product reports missing supported agents honestly and lets the user choose the active local tool when more than
+  one is installed
+
+## Distribution Strategy
+
+- Native packages: GitHub Packages as `@launcheleven/srgical` and npm public as `@launch11/srgical`
+- Versioning model: semver via Changesets on GitHub Actions, with version commits pushed directly to `main`
+- Release artifacts: standalone binaries for Windows, macOS, and Linux
+- Package-manager wrappers: `brew`, `choco`, and other ecosystems can install those release artifacts

package/docs/testing-strategy.md

@@ -0,0 +1,96 @@
+# Testing Strategy
+
+## Purpose
+
+This plan turns the current srgical CLI into a continuously verifiable tool instead of a repo that only relies on
+manual smoke checks. It is deliberately staged so we cover the highest-risk flows first and use the work to shake out
+real bugs.
+
+## Current Risk Map
+
+### Tier 1: Command safety
+
+- `doctor` must report truthful repo and agent state.
+- `init` must create a usable planning pack and fail safely on accidental overwrite.
+- `run-next` must never execute stale or unsafe work when the tracker has no queued step.
+- `studio` slash-command flows must keep explicit user control over writes and execution.
+
+### Tier 2: Pack integrity
+
+- workspace path helpers must resolve `.srgical/` files consistently.
+- template generation must always produce a complete four-file planning pack.
+- planning-pack state parsing must keep tracker truth aligned with command output.
+- execution state and durable logs must round-trip without corrupting summaries.
+
+### Tier 3: Adapter and Agent behavior
+
+- primary-agent status detection must degrade cleanly when Codex is unavailable.
+- planner, pack-writing, and execution adapters must preserve today's Codex-first behavior.
+- Windows command resolution and shell-shim launching must stay covered because that path has already broken once.
+
+### Tier 4: Release confidence
+
+- `release:pack` must build, validate, and emit the npm tarball plus manifests.
+- package contents must stay intentional.
+- release workflow configuration must remain aligned with the local release script.
+
+## Coverage Plan
+
+### Phase A: Fast local tests
+
+- built-in Node test runner through `tsx`
+- temp-workspace integration tests for command behavior
+- pure-module tests for parser and formatter logic
+
+This is the right default layer for the current codebase because most logic is filesystem- and text-driven, not UI DOM
+driven.
+
+### Phase B: Studio behavior tests
+
+- isolate slash-command handlers into smaller helpers
+- test `/write`, `/preview`, `/run`, and `/help` behavior without booting a full terminal
+- add keyboard behavior tests for transcript scrolling once more of the TUI logic is extracted from Blessed setup
+
+### Phase C: Agent and platform regression tests
+
+- stub the primary-agent adapter to verify planner, pack-write, and execution command paths
+- add Windows-focused regression cases for command resolution and `.cmd` launch behavior
+- add negative tests for missing agent, malformed tracker files, and partial planning-pack state
+
+### Phase D: Release verification
+
+- assert that `npm run release:pack` creates the tarball and release manifests
+- inspect packed file lists and fail if unintended files leak into the npm artifact
+- optionally run these as a slower integration suite in CI only
+
+## Executable Baseline Added Now
+
+- `test/core/planning-pack-state.test.ts`
+- `test/core/execution-state.test.ts`
+- `test/commands/doctor.test.ts`
+- `test/commands/run-next.test.ts`
+
+These cover the current highest-signal logic: tracker parsing, execution-state durability, truthful `doctor` output,
+and safe `run-next` behavior.
+
+## Bugs Surfaced During This Planning Pass
+
+- `run-next` was still willing to execute even when the tracker exposed no next recommended step. That left room for a
+  stale `.srgical/04-next-agent-prompt.md` to run after the tracker was effectively complete.
+- The same safety issue existed in the studio `/run` path.
+
+Both execution paths are now guarded by the same queued-step safety rule.
+
+## Commands
+
+```bash
+npm test
+npm run test:coverage
+```
+
+## Near-Term Next Test Steps
+
+- add `init` command tests, especially overwrite protection
+- extract and test studio slash-command helpers
+- add agent-adapter stubs for unavailable-agent and successful-execution cases
+- add release-pack integration assertions for tarball contents and manifest hashes

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@launch11/srgical",
+  "version": "0.0.1",
+  "description": "A polished local-first CLI for planning and executing long AI-driven delivery sequences.",
+  "files": [
+    "dist",
+    "README.md",
+    "docs",
+    "LICENSE"
+  ],
+  "bin": {
+    "srgical": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "changeset": "changeset",
+    "dev": "tsx src/index.ts",
+    "release": "npm run release:pack && npm run publish:github && npm run publish:npm",
+    "start": "node dist/index.js",
+    "doctor": "tsx src/index.ts doctor",
+    "test": "tsx --test test/**/*.test.ts",
+    "test:coverage": "tsx --test --experimental-test-coverage test/**/*.test.ts",
+    "version-packages": "changeset version",
+    "release:pack": "node scripts/release-pack.mjs",
+    "publish:github": "changeset publish",
+    "publish:npm": "node scripts/publish-npm.mjs",
+    "release:version": "node scripts/read-package-version.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LaunchEleven/Srgical.git"
+  },
+  "homepage": "https://github.com/LaunchEleven/Srgical#readme",
+  "bugs": {
+    "url": "https://github.com/LaunchEleven/Srgical/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "ai",
+    "cli",
+    "codex",
+    "agent",
+    "orchestration",
+    "planning"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "blessed": "^0.1.81",
+    "commander": "^14.0.3"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.30.0",
+    "@types/blessed": "^0.1.27",
+    "@types/node": "^25.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}