soloship 0.1.0 → 0.1.2

package/README.md

@@ -2,33 +2,55 @@
 
 > Ship solo, safely.
 
-Soloship is guardrails for non-coders building software through AI agents. It's a Claude Code plugin that gives you three things a traditional engineering team would: **mechanical enforcement** that fires automatically (9 hooks, 4 rules, CI checks — no judgment calls required), **19 workflow skills** that guide you through the steps a professional would take (each with enforcement gates and anti-rationalization tables so the agent can't cut corners), and **a one-command setup** that detects your stack and wires everything into the project.
+Soloship is guardrails for non-coders building software through AI agents. It's a Claude Code plugin that gives you three things a traditional engineering team would: **mechanical enforcement** that fires automatically (9 hooks, 4 rules, CI checks — no judgment calls required), **15 Soloship-native workflow skills + 36 vendored skills from five best-in-class plugins** that guide you through the steps a professional would take (each with enforcement gates and anti-rationalization tables so the agent can't cut corners), and **a one-command setup** that detects your stack and wires everything into the project.
 
 **Quick reference:** [aifoundationlevels.com/soloship-cheatsheet](https://aifoundationlevels.com/soloship-cheatsheet)
 
 ## Install
 
-Soloship is a [Claude Code](https://claude.com/claude-code) plugin. If you don't have Claude Code installed yet, install it first — then come back here.
+### Prerequisites
 
-Inside any Claude Code session, run these two commands **one at a time** — run the first, wait for it to finish, then run the second:
+You need two things before you start:
 
-**1. Add the marketplace:**
+1. **[Claude Code](https://claude.com/claude-code)** — install it if you haven't yet. Soloship runs inside it.
+2. **Node.js 18 or newer** — `npx` ships with Node and is how Soloship's CLI runs. Check by running `node -v` in a terminal. If you don't have it, install from [nodejs.org](https://nodejs.org).
+
+You don't need to install anything from npm by hand. `npx` downloads `soloship` on demand and caches it. Soloship is [live on npm](https://www.npmjs.com/package/soloship) — you can verify with `npm view soloship`.
+
+### How Soloship is structured
+
+Soloship has two parts that work together:
+
+| Part | What it gives you | How it's installed | When it runs |
+|------|-------------------|--------------------|--------------|
+| **Plugin** (`thedigitalorganizer/soloship`) | The `/soloship:*` slash commands (audit, bootstrap, brainstorm, plan, etc.) | Claude Code plugin marketplace | Once per machine |
+| **npm CLI** (`soloship` on npm) | The `init` / `upgrade` / `doctor` / `rollback` commands that install hooks, rules, CI, and `CLAUDE.md` into a project | Auto-downloaded by `npx` (no manual install) | Once per project, then `upgrade` whenever a new version ships |
+
+You need both for the full experience. The plugin gives you the slash commands. The npm CLI installs the project-level guardrails. The plugin's `/soloship:bootstrap` calls `npx soloship init` for you, so in practice you only ever type slash commands.
+
+### Step 1 — Install the plugin (once per machine)
+
+Inside any Claude Code session, run these two slash commands **one at a time** — run the first, wait for it to finish, then run the second.
+
+**1a. Add the marketplace:**
 
 ```
 /plugin marketplace add thedigitalorganizer/soloship
 ```
 
-**2. Install the plugin:**
+This points Claude Code at the Soloship marketplace on GitHub. Nothing is installed yet — this just registers where to find the plugin.
+
+**1b. Install the plugin:**
 
 ```
 /plugin install soloship@soloship
 ```
 
-That's it. The plugin installs globally, so you only do this once on your machine. All 19 Soloship commands are now available as `/soloship:*` slash commands in every project you open.
+The syntax is `<plugin-name>@<marketplace-name>` — both happen to be `soloship`, which is why it reads twice. Once this finishes, every `/soloship:*` slash command is available in every project you open in Claude Code.
 
-### Using Soloship in a project
+### Step 2 — Set up a project (once per project)
 
-Open the project you want to use Soloship in — a brand-new empty folder or an existing codebase, either works — then run one of these in Claude Code:
+Open the project you want to use Soloship in — a brand-new empty folder or an existing codebase, either works — then run one of these in Claude Code. **You don't need to open a terminal.** The bootstrap skill calls `npx soloship init` for you.
 
 **Brand-new project (no code yet):**
 
@@ -49,6 +71,18 @@ Bootstrap asks four questions about your project, then sets up the guardrails (h
 
 After bootstrap, the daily loop is `/soloship:brainstorm` → `/soloship:plan` → `/soloship:implement` → `/soloship:shipthorough`.
 
+### Keeping Soloship up to date
+
+After install, every Claude Code session checks once a day whether a new Soloship version has been published. When one is, you'll see a single line at the top of the session:
+
+```
+Soloship update available: 0.1.0 → 0.1.2. Run: npx soloship upgrade
+```
+
+Run that command from your project root whenever you see it. It refreshes hooks, rules, and CI, then re-stamps the version. Your project docs (`CLAUDE.md`, `AGENTS.md`, `CHANGELOG.md`) are preserved.
+
+To update the plugin itself (the slash commands), Claude Code handles it via `/plugin update soloship@soloship`.
+
 ## How we got here
 
 Soloship didn't start as a project. It started as a frustration.
@@ -93,7 +127,8 @@ Others are routers — Soloship adds enforcement and routing logic, then dispatc
 | Skill | Routes to | What Soloship adds |
 |-------|-----------|-------------------|
 | `/brainstorm` | `office-hours` (product) / `superpowers:brainstorming` (technical) | Product-vs-technical routing, mandatory design-first nudge |
-| `/plan` | `superpowers:writing-plans` / `plan-eng-review` | Solution search before planning, 7-point enforcement gate, artifact contracts |
+| `/grill-me` | (self-contained, adapted from Matt Pocock's `grill-me`) | Pre-plan interview that refuses to write a plan until user + agent share a complete mental model. Walks the design tree exhaustively. |
+| `/plan` | `superpowers:writing-plans` / `plan-eng-review` | Solution search before planning, 7-point enforcement gate, artifact contracts, checks for `/grill-me` rationale on non-trivial work |
 | `/implement` | `superpowers:subagent-driven-development` / `superpowers:dispatching-parallel-agents` | Plan-first enforcement, execution strategy routing |
 | `/debug` | `superpowers:systematic-debugging` | Solution search for prior art, root-cause iron law |
 | `/learn` | `compound-engineering:workflows:compound` (Step 1) | Solution doc via CE, then own protocols: JSONL logging, registry audit, AGENTS.md propagation + creation |
@@ -122,38 +157,36 @@ Run bootstrap once per project. For existing code, run `/soloship:audit` first s
 
 ### The skills
 
-19 Claude Code skills invoked as `/soloship:*` slash commands:
+**15 Soloship-native workflow skills** invoked as `/soloship:*` slash commands. Each one handles orchestration, enforcement, and artifact contracts; the heavy lifting is often delegated to a vendored skill (see the next section).
 
 **Setup & orientation**
 
 - `/soloship:audit` — Deep 2-phase codebase investigation. Phase 1 launches 4 parallel agents to map architecture, conventions, decisions, and infrastructure. Phase 2 launches 6 more to assess quality, entanglement, security, dependencies, gaps, and leverage points. Human checkpoint between phases prevents building assessment on wrong assumptions. Produces `docs/audit/AUDIT-YYYY-MM-DD.md` + `audit-findings.json`.
 - `/soloship:bootstrap` — Configures governance from audit findings or interactive questions. Creates CLAUDE.md, AGENTS.md files (3+ source file threshold), installs 4 core rules, and wires up hooks. Never overwrites existing files. Anti-rationalization table blocks "I'll set up governance later."
 - `/soloship:onboard` — Reads CLAUDE.md, AGENTS.md, audit reports, and recent git history to produce a 7-section orientation briefing. Flags stale audit reports. No external routing — fully self-contained.
-- `/soloship:checkpoint` — Saves working state (git status, decisions, remaining work) so any future session can resume cleanly. Routes to gstack `checkpoint`. Pairs with `/soloship:onboard` for `/clear` recovery.
 
 **Daily work**
 
-- `/soloship:brainstorm` — Detects whether the question is product (demand, audience, wedge) or technical (approaches, trade-offs) and routes accordingly: `office-hours` for product questions, `superpowers:brainstorming` for technical ones. Ends with a mandatory design-first nudge — sketch before you plan.
+- `/soloship:brainstorm` — Detects whether the question is demand-validation (should this exist?) or feature-shaping (what should this do?) and routes accordingly: `gs-office-hours` for demand, `ce-brainstorm` for feature. Ends with a mandatory design-first nudge — sketch before you plan.
+- `/soloship:grill-me` — Relentless pre-plan interview that walks every branch of the design tree until user and agent share a complete mental model. Refuses to produce a plan or any code until alignment is explicit. Triggered explicitly ("grill me", "interview me") or by `/soloship:plan` on medium-to-large work. Adapted from Matt Pocock's `grill-me` (MIT).
 - `/soloship:spec` — Writes formal specifications with numbered acceptance criteria, data models, API contracts, user flows (including error states), and explicit out-of-scope boundaries. 8-point verification checklist. Fully self-contained.
-- `/soloship:plan` — Searches `docs/solutions/` for prior art, reads architecture context, then routes to `superpowers:writing-plans` for standard features or `plan-eng-review` for architectural work. 7-point enforcement gate validates: Why lines, Key Decisions, Execution Strategy, Handoff section, no unaddressed pitfalls.
-- `/soloship:implement` — Finds the most recent plan in `docs/plans/`, assesses the execution strategy, and routes to `superpowers:subagent-driven-development` (sequential tasks) or `superpowers:dispatching-parallel-agents` (independent modules). Freshness check warns on stale plans.
-- `/soloship:debug` — Iron law: no fixes without root cause investigation. Searches solutions for prior art first, then routes to `superpowers:systematic-debugging` for 4-phase discipline (Investigate → Analyze → Hypothesize → Implement). Nudges `/learn` for non-obvious fixes.
-- `/soloship:learn` — Captures knowledge from non-obvious work. Step 1 routes to `compound-engineering:workflows:compound` for solution doc creation. Steps 2-3 are Soloship's own protocols: JSONL logging for cross-session search and architecture registry drift checking. Steps 4-5 adapt the distributed AGENTS.md concept — propagating pitfalls into existing AGENTS.md files and creating new ones for directories above the 3-file governance threshold. Anti-rationalization table blocks "this fix was straightforward, not worth documenting."
-- `/soloship:cleanup` — Knowledge system maintenance. Launches 5 parallel audit agents (solution health, overlap detection, plan lifecycle, AGENTS.md staleness, index sync), presents findings interactively, then executes approved changes in a single atomic commit. Merge candidates require 2-of-3 signal threshold. Each merge dispatched as an independent subagent to prevent context bloat.
+- `/soloship:plan` — Searches `docs/solutions/` for prior art, reads architecture context, then invokes `ce-plan` to produce the plan. 7-point enforcement gate validates: Why lines, Key Decisions, Execution Strategy, Handoff section, no unaddressed pitfalls, and that non-trivial work was preceded by `/soloship:grill-me`. Review is separate — handled by `/soloship:review`.
+- `/soloship:implement` — Finds the most recent plan in `docs/plans/`, invokes `ce-work` for execution with branching and QC. Freshness check warns on stale plans.
+- `/soloship:debug` — Iron law: no fixes without root cause investigation. Searches solutions for prior art first, then invokes `sp-systematic-debugging` for 4-phase discipline (Investigate → Analyze → Hypothesize → Implement). Nudges `/learn` for non-obvious fixes.
+- `/soloship:learn` — Captures knowledge from non-obvious work. Invokes `ce-compound` for solution doc creation. Adds Soloship protocols: JSONL logging for cross-session search, architecture registry drift checking, and distributed AGENTS.md propagation (pitfalls into existing AGENTS.md files, new ones for directories above the 3-file governance threshold). Anti-rationalization table blocks "this fix was straightforward, not worth documenting."
+- `/soloship:cleanup` — Knowledge system maintenance. Launches 5 parallel audit agents (solution health, overlap detection, plan lifecycle, AGENTS.md staleness, index sync), presents findings interactively, then executes approved changes in a single atomic commit. Merge candidates require 2-of-3 signal threshold.
 
 **Shipping**
 
 - `/soloship:shipfast` — Emergency deploy pipeline. Lint (with auto-fix tolerance), test (pre-existing failures allowed), build (must pass), commit, push, deploy. Auto-detects platform. Minimum viable safety, maximum speed.
-- `/soloship:shipthorough` — Full due diligence: preflight checks, base branch merge, lint, test, coverage audit, 3-pass code review (via `/review`), registry update, CHANGELOG enforcement, plan lifecycle cleanup, bisectable commits, PR with structured body, verification gate, deploy. 12-point checklist.
+- `/soloship:shipthorough` — Full due diligence: preflight checks, base branch merge, lint, test, inline quality gate (TypeScript + linter + dead code + shellcheck), coverage audit, 3-pass code review (via `/review`), registry update, CHANGELOG enforcement, plan lifecycle cleanup, bisectable commits, PR with structured body, verification gate, deploy.
 
 **Quality**
 
-- `/soloship:review` — Detects whether the target is a plan or code. Plans route to `plan-eng-review`, `plan-ceo-review`, or `plan-design-review`. Code gets a 3-pass parallel review: structural (SQL safety, auth, types, tests), adversarial (load, bad input, state transitions), and design-lite (a11y, responsive, AI slop — only if frontend changed). Severity classification with file:line references.
-- `/soloship:qa` — Routes to gstack `qa` (test and fix) or `qa-only` (report only). Uses accessibility checklist as baseline.
-- `/soloship:security` — Routes to gstack `cso` for infrastructure-first security scanning: OWASP Top 10, STRIDE threat modeling, secrets archaeology, dependency supply chain, npm audit.
-- `/soloship:design-review` — Two-pass visual audit. Pass 1 routes to gstack `design-review` for spacing, hierarchy, and consistency. Pass 2 is Soloship's own AI slop detection — flags generic gradients, default shadows, "Welcome to" copy, 3-column feature grids, and other patterns that mark AI-generated design. Each fix committed atomically with before/after screenshots.
-- `/soloship:health` — Routes to gstack `health` for a composite 0-10 codebase quality score (type check, lint, tests, dead code) with trend tracking across runs. Intended as a pre-ship gate inside `/soloship:shipthorough`.
-- `/soloship:autoplan` — Routes to gstack `autoplan` to run the full plan-review gauntlet (CEO, design, engineering, DX) in a single pass with auto-decisions. Use when you want every review lens applied without stepping through them individually.
+- `/soloship:review` — Detects whether the target is a plan or code. **Plans** route to `gs-plan-eng-review`, `gs-plan-ceo-review`, `gs-plan-design-review` individually, or `gs-autoplan` for all four (adds DX review) in one auto-decided pass. **Code** routes to `ce-review` for PR-scale multi-agent analysis, or runs three inline passes (structural, adversarial, design slop lens) for quick local checks.
+- `/soloship:design-review` — Two-pass visual audit. Pass 1 invokes `gs-design-review` for spacing, hierarchy, and consistency. Pass 2 is Soloship's own AI slop detection (inspired by Impeccable) — flags generic gradients, default shadows, "Welcome to" copy, 3-column feature grids, and other patterns that mark AI-generated design. Each fix committed atomically with before/after screenshots.
+
+**Note:** Skills that were previously thin wrappers over vendored gstack skills (`/soloship:qa`, `/soloship:security`, `/soloship:checkpoint`, `/soloship:autoplan`, `/soloship:health`) have been removed. Use the vendored originals directly: `/gs-qa`, `/gs-cso`, `/gs-context-save` / `/gs-context-restore`, `/gs-autoplan`. Health has no replacement — its core checks were inlined into `/soloship:shipthorough`'s quality gate.
 
 ## Quick start
 
@@ -174,15 +207,18 @@ See the [Install](#install) section above for the two commands to install the pl
 /soloship:plan → /soloship:implement → /soloship:shipthorough
 ```
 
-### Prefer an npm installer?
+### Running the npm CLI directly
 
-If you'd rather set up the project scaffolding outside Claude Code (for example, in a scripted environment or CI), the npm CLI does the same thing bootstrap does:
+`/soloship:bootstrap` calls `npx soloship init` under the hood, so you don't usually need to think about the npm CLI. But it's there if you want to script setup, run it in CI, or skip the slash command entirely. Run any of these from your project root:
 
 ```bash
-npx soloship init
+npx soloship init        # initial setup — creates docs, hooks, rules, CI, CLAUDE.md
+npx soloship upgrade     # refresh hooks, rules, CI, and the .soloship/version stamp
+npx soloship doctor      # check Claude Code environment for missing companions
+npx soloship rollback    # restore the last safety snapshot
 ```
 
-Most people should use `/soloship:bootstrap` — it's the supported path and it can tailor setup to audit findings.
+`npx` auto-downloads the latest Soloship from npm the first time you run it, and caches it after that. There's no separate `npm install -g` step.
 
 ## Design decisions
 
@@ -202,23 +238,29 @@ Most people should use `/soloship:bootstrap` — it's the supported path and it
 | 7 | Not started | Safety floor hardening, surface simplification, CLAUDE.md governance |
 | 8 | Not started | Graduation system, methodology documentation |
 
-Phases 1-6 are shipped and usable today. Phases 7-8 were restructured after a 3-round adversarial review that identified rationalization traps in the original design. Phase 7 adds mechanical safety enforcement (Semgrep scanning, automated rollback, phone-a-friend triggers) and consolidates the 19 skills into 3-4 meta-workflows. Phase 8 adds a graduation system with calibrated thresholds that tell you when your project has outgrown solo mode.
+Phases 1-6 are shipped and usable today. Phases 7-8 were restructured after a 3-round adversarial review that identified rationalization traps in the original design. Phase 7 adds mechanical safety enforcement (Semgrep scanning, automated rollback, phone-a-friend triggers) and consolidates the native skills into 3-4 meta-workflows. Phase 8 adds a graduation system with calibrated thresholds that tell you when your project has outgrown solo mode.
+
+## Built on the shoulders of
+
+Soloship curates and vendors skills from five outstanding Claude Code plugins. One plugin install for the user; full credit and install links for the authors. Full attribution and version pins live in [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
 
-## Prior art & influences
+[**Compound Engineering**](https://github.com/EveryInc/compound-engineering-plugin) — Kieran Klaassen (Every). The brainstorm → plan → work → compound loop is the spine of how Soloship thinks about engineering. Also: `/review` inherits CE's multi-agent review pattern.
 
-Soloship builds on top of four Claude Code skill ecosystems rather than replacing them:
+[**Superpowers**](https://github.com/obra/superpowers) — Jesse Vincent. The discipline skills: `systematic-debugging`'s "no fixes without root cause," `verification-before-completion`'s "evidence before claims," `test-driven-development`, `writing-plans`, `executing-plans`, `subagent-driven-development`, `dispatching-parallel-agents` (via `using-git-worktrees`), `finishing-a-development-branch`, `brainstorming`. Nine skills total.
 
-[Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin) — `/learn` uses CE's `workflows:compound` to create solution documents with structured frontmatter. The multi-agent pattern in CE informs how `/audit` and `/review` dispatch parallel investigation agents.
+[**Impeccable**](https://impeccable.style) — Paul Bakaus (extending Anthropic's original `frontend-design`). Design vocabulary and steering commands that let non-coders ship work that doesn't look AI-generated. Soloship vendors `frontend-design` and five `/i-*` commands; 12 more are in the full plugin.
 
-[Superpowers](https://github.com/anthropics/superpowers) — `/brainstorm` routes to `superpowers:brainstorming` for technical exploration. `/plan` routes to `superpowers:writing-plans`. `/implement` routes to `superpowers:subagent-driven-development` or `superpowers:dispatching-parallel-agents`. `/debug` routes to `superpowers:systematic-debugging`.
+[**ui-ux-pro-max**](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) — nextlevelbuilder. The design reference library: styles, palettes, font pairings, UX guidelines, chart patterns, across every stack the agent might target.
 
-[gstack](https://github.com/garrytan/gstack) — `/qa` routes to gstack's QA skill. `/security` routes to `cso`. `/design-review` routes to gstack's design-review checklist. `/brainstorm` routes to `office-hours` for product questions. `/plan` routes to `plan-eng-review` for architectural work. `/review` routes to `plan-eng-review`, `plan-ceo-review`, and `plan-design-review` for plan reviews.
+[**gstack**](https://github.com/garrytan/gstack) — Garry Tan (YC). The solo builder toolkit. Soloship vendors 12 of the most non-coder-friendly skills — `autoplan` (chains CEO + design + eng + DX reviews), `context-save` / `context-restore` (the checkpoint pair), `browse` (headless browser daemon, re-vendored from gstack v1.31.1.0 with Soloship-native paths so it works standalone), `qa`, `design-review`, the four plan-review skills (eng, ceo, design, devex), `office-hours`, `cso`. Full gstack has ~25 more.
 
-[intent-layer](https://github.com/crafter-station/skills/tree/main/context-engineering/intent-layer) (crafter-station/skills, built on [The Intent Layer](https://www.intent-systems.com/learn/intent-layer) by Tyler Brandt) — `/learn` Steps 4-5 adapt the concept of distributed per-directory `AGENTS.md` files for codebase navigation. Soloship's version is continuous (updates on every `/learn` pass, not one-shot), threshold-gated (3+ source files before creating), append-only with dated attribution, and scoped to solution-doc evidence rather than speculative. `/bootstrap` and `/cleanup` also maintain the AGENTS.md network.
+If any of these are useful to you, please install the full upstream plugin — each `THIRD_PARTY_NOTICES.md` section has the one-line install command, and you'll get everything the author built, not just Soloship's selection.
 
-[Impeccable](https://github.com/pbakaus/impeccable) — `/design-review` adds an AI slop detection pass inspired by Impeccable's design quality philosophy, checking for generic AI-generated visual, content, and layout patterns.
+Also influential but not vendored:
 
-[Serena](https://github.com/oraios/serena) — symbol-level LSP code navigation. Optional. Worth adding once a codebase outgrows file-level tools; see Serena's README for install instructions.
+[**intent-layer**](https://github.com/crafter-station/skills/tree/main/context-engineering/intent-layer) (crafter-station/skills, built on [The Intent Layer](https://www.intent-systems.com/learn/intent-layer) by Tyler Brandt) — `/learn` Steps 4-5 adapt the concept of distributed per-directory `AGENTS.md` files for codebase navigation. Soloship's version is continuous (updates on every `/learn` pass, not one-shot), threshold-gated (3+ source files before creating), append-only with dated attribution, and scoped to solution-doc evidence rather than speculative. `/bootstrap` and `/cleanup` also maintain the AGENTS.md network.
+
+[**Serena**](https://github.com/oraios/serena) — symbol-level LSP code navigation. Optional. Worth adding once a codebase outgrows file-level tools; see Serena's README for install instructions.
 
 The broader design traces back to a research pass across: Ousterhout on strategic vs tactical programming (you are the architect, the agent implements), Hickey on simple vs easy, Metz on dependency awareness and sizing rules, Meadows on leverage points in systems, the BCG "AI Brain Fry" finding that productivity drops past three tools, Kathy Sierra on the collapse zone (only automated process survives when things break), and the Codified Context paper that validated the CLAUDE.md + AGENTS.md + docs/ three-tier pattern.
 
@@ -237,10 +279,22 @@ src/                   # TypeScript source for the installer
   ci.ts                # GitHub Actions + architecture fitness
   templates.ts         # CLAUDE.md / AGENTS.md / CHANGELOG / SOLUTION_GUIDE generators
 skills/                # Claude Code skills shipped by the plugin
-  audit/ autoplan/ bootstrap/ brainstorm/ checkpoint/ cleanup/
-  debug/ design-review/ health/ implement/ learn/ onboard/
-  plan/ qa/ review/ security/ shipfast/ shipthorough/ spec/
+  # 15 Soloship-native workflows:
+  audit/ bootstrap/ brainstorm/ cleanup/ debug/ design-review/
+  grill-me/ implement/ learn/ onboard/ plan/ review/
+  shipfast/ shipthorough/ spec/
+
+  # 36 vendored skills (full attribution in THIRD_PARTY_NOTICES.md):
+  ce-*        # 8 from Compound Engineering (Kieran Klaassen, MIT)
+  sp-*        # 9 from Superpowers (Jesse Vincent, MIT)
+  im-*        # 6 from Impeccable (Paul Bakaus, Apache 2.0)
+  uiux-*      # 1 from ui-ux-pro-max (nextlevelbuilder, MIT)
+  gs-*        # 12 from gstack (Garry Tan, MIT) — includes the gs-browse
+              # headless browser daemon, re-vendored at v1.31.1.0 with
+              # Soloship-native paths so it works without gstack installed
+
   references/          # Shared checklists (a11y, code review, perf, security, testing)
+  vendored/            # Per-source LICENSE / NOTICE / VERSION / README (attribution archive)
 ```
 
 ## License

package/dist/cli.js

@@ -3,11 +3,13 @@ import chalk from "chalk";
 import { runInit } from "./init.js";
 import { runRollback } from "./rollback.js";
 import { runDoctor } from "./doctor.js";
+import { runUpgrade } from "./upgrade.js";
+import { getVersion } from "./pkg.js";
 const program = new Command();
 program
     .name("soloship")
     .description("Ship solo, safely — guardrails for AI-assisted development")
-    .version("0.1.0");
+    .version(getVersion());
 program
     .command("init")
     .description("Initialize Soloship in the current project")
@@ -32,6 +34,22 @@ program
         process.exit(1);
     }
 });
+program
+    .command("upgrade")
+    .description("Refresh hooks, rules, and CI to the version of Soloship being run via npx")
+    .action(async () => {
+    console.log("");
+    console.log(chalk.bold("Soloship Upgrade"));
+    console.log(chalk.dim("Refreshing project hooks, rules, and CI. Project docs are preserved."));
+    console.log("");
+    try {
+        await runUpgrade();
+    }
+    catch (err) {
+        console.error(chalk.red("Upgrade failed:"), err);
+        process.exit(1);
+    }
+});
 program
     .command("rollback")
     .description("Roll back to the last Soloship safety snapshot")

package/dist/hooks.js

@@ -99,7 +99,7 @@ export async function installHooks(root, project) {
         },
     ];
     results.push("Stop: plan validation + workflow navigator + handoff reminder");
-    // SessionStart: Checkpoint commit + context injection
+    // SessionStart: Checkpoint commit + Soloship update check
     hooks.SessionStart = [
         {
             matcher: "",
@@ -116,14 +116,14 @@ export async function installHooks(root, project) {
             hooks: [
                 {
                     type: "command",
-                    command: buildSessionStartScript(),
-                    timeout: 10000,
+                    command: buildUpgradeCheckScript(),
+                    timeout: 5000,
                 },
             ],
         },
     ];
     results.push("SessionStart: checkpoint commit before agent session");
-    results.push("SessionStart: context injection");
+    results.push("SessionStart: daily check for Soloship updates on npm");
     // Merge hooks into settings (don't overwrite other settings)
     settings.hooks = hooks;
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
@@ -295,9 +295,44 @@ else
 fi
 '`;
 }
-function buildSessionStartScript() {
+function buildUpgradeCheckScript() {
+    // Once-per-day check for newer Soloship npm releases. Silent if up-to-date,
+    // network unavailable, or no version stamp exists. Cached to avoid hammering
+    // the npm registry on every session start.
     return `bash -c '
-# Dependency graph injection removed.
+SOLOSHIP_DIR=".soloship"
+VERSION_FILE="$SOLOSHIP_DIR/version"
+CACHE_FILE="$SOLOSHIP_DIR/.last-update-check"
+
+[ -f "$VERSION_FILE" ] || exit 0
+INSTALLED=$(cat "$VERSION_FILE" 2>/dev/null | head -n1 | tr -d "[:space:]")
+[ -z "$INSTALLED" ] && exit 0
+
+NOW=$(date +%s)
+LATEST=""
+if [ -f "$CACHE_FILE" ]; then
+  CACHED_TS=$(sed -n 1p "$CACHE_FILE" 2>/dev/null)
+  CACHED_VER=$(sed -n 2p "$CACHE_FILE" 2>/dev/null)
+  if [ -n "$CACHED_TS" ] && [ $((NOW - CACHED_TS)) -lt 86400 ]; then
+    LATEST="$CACHED_VER"
+  fi
+fi
+
+if [ -z "$LATEST" ]; then
+  LATEST=$(timeout 3 npm view soloship version 2>/dev/null | tr -d "[:space:]")
+  [ -z "$LATEST" ] && exit 0
+  mkdir -p "$SOLOSHIP_DIR"
+  printf "%s\\n%s\\n" "$NOW" "$LATEST" > "$CACHE_FILE" 2>/dev/null
+fi
+
+if [ "$INSTALLED" != "$LATEST" ]; then
+  NEWEST=$(printf "%s\\n%s\\n" "$INSTALLED" "$LATEST" | sort -V | tail -n1)
+  if [ "$NEWEST" = "$LATEST" ]; then
+    echo "{\\"systemMessage\\": \\"Soloship update available: $INSTALLED → $LATEST. Run: npx soloship upgrade\\"}"
+  fi
+fi
+
+exit 0
 '`;
 }
 function buildPhoneAFriendScript() {

package/dist/manifest.js

@@ -58,12 +58,6 @@ export const SOLOSHIP_MANIFEST = {
         },
     ],
     skills: [
-        {
-            name: "gstack",
-            severity: "recommended",
-            purpose: "Command bundle that provides office-hours, plan reviews (eng/CEO/design), QA, CSO, design-review, retro, and others. Soloship skills delegate to gstack for review and QA workflows.",
-            install: "gstack has its own install path — check its README. It typically deploys as a directory under ~/.claude/skills/gstack plus individual symlinked skills (office-hours, plan-eng-review, qa, cso, etc.).",
-        },
         {
             name: "log",
             severity: "recommended",

package/dist/rules.d.ts

@@ -1 +1,3 @@
-export declare function installRules(root: string): Promise<string[]>;
+export declare function installRules(root: string, options?: {
+    force?: boolean;
+}): Promise<string[]>;

package/dist/rules.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-export async function installRules(root) {
+export async function installRules(root, options = {}) {
     const results = [];
     const rulesDir = join(root, ".claude", "rules");
     if (!existsSync(rulesDir)) {
@@ -18,6 +18,10 @@ export async function installRules(root) {
             writeFileSync(path, content);
             results.push(filename);
         }
+        else if (options.force) {
+            writeFileSync(path, content);
+            results.push(`${filename} (refreshed)`);
+        }
         else {
             results.push(`${filename} (exists, skipped)`);
         }

package/dist/scaffold.d.ts

@@ -4,4 +4,5 @@ interface ScaffoldResult {
     action: "created" | "exists" | "updated";
 }
 export declare function scaffoldDocs(root: string, project: ProjectInfo): Promise<ScaffoldResult[]>;
+export declare function writeVersionStamp(root: string): ScaffoldResult[];
 export {};

package/dist/scaffold.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { getVersion } from "./pkg.js";
 import { generateClaudeMd, generateAgentsMd, generateSolutionGuide, generateChangelog, } from "./templates.js";
 export async function scaffoldDocs(root, project) {
     const results = [];
@@ -67,6 +68,31 @@ export async function scaffoldDocs(root, project) {
     else {
         results.push({ path: ".semgrep.yml", action: "exists" });
     }
+    // Soloship version stamp + per-clone cache directory
+    const stampResults = writeVersionStamp(root);
+    results.push(...stampResults);
+    return results;
+}
+export function writeVersionStamp(root) {
+    const results = [];
+    const soloshipDir = join(root, ".soloship");
+    if (!existsSync(soloshipDir)) {
+        mkdirSync(soloshipDir, { recursive: true });
+    }
+    const versionPath = join(soloshipDir, "version");
+    const exists = existsSync(versionPath);
+    writeFileSync(versionPath, getVersion() + "\n");
+    results.push({
+        path: ".soloship/version",
+        action: exists ? "updated" : "created",
+    });
+    // Local-only cache file is gitignored; the version stamp itself is committed
+    // so collaborators see the same pinned version.
+    const gitignorePath = join(soloshipDir, ".gitignore");
+    if (!existsSync(gitignorePath)) {
+        writeFileSync(gitignorePath, ".last-update-check\n");
+        results.push({ path: ".soloship/.gitignore", action: "created" });
+    }
     return results;
 }
 function generateSemgrepConfig() {

package/dist/templates.js

@@ -16,6 +16,10 @@ export function generateClaudeMd(project) {
 **${project.name}**${project.description ? ` — ${project.description}` : ""}
 
 ${stackLine ? `**Stack:** ${stackLine}\n` : ""}
+> **Audience note:** The maintainer of this project may not be a traditional coder — Soloship is built for people who ship software through AI agents. When explaining anything technical (architecture, protocols, tooling, tradeoffs), lead with a plain-English analogy before introducing jargon. Define a technical term once with its meaning, then use it freely. Default to recommendations with tradeoffs, not term-paper breakdowns.
+>
+> If the maintainer signals they want the technical version ("go deeper," "show me the code"), switch registers. Otherwise, keep it concrete.
+
 ## Related Documentation
 
 | Document | Location | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soloship",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Systematic programming methodology for AI-assisted development",
   "type": "module",
   "bin": {
@@ -10,7 +10,8 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "start": "node dist/cli.js",
-    "prepare": "tsc"
+    "prepare": "tsc",
+    "prepublishOnly": "node scripts/check-version.js"
   },
   "keywords": [
     "claude-code",