From 7035ce640e20cc6098210cc487b4311a6201c4e2 Mon Sep 17 00:00:00 2001 From: "Vadim S." <66877650+vadimsv1@users.noreply.github.com> Date: Fri, 24 Jul 2026 18:38:43 -0400 Subject: [PATCH] fix: use ship as the Desktop entry point --- .claude-plugin/marketplace.json | 4 +-- .claude-plugin/plugin.json | 2 +- CHANGELOG.md | 14 ++++++++ README.md | 63 +++++++++++++++++---------------- commands/go.md | 7 ++-- scripts/scaffold_project.py | 3 +- scripts/ship-doctor.sh | 14 +++++--- skills/ship/SKILL.md | 11 +++++- 8 files changed, 76 insertions(+), 42 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 12464df..ecf359c 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -2,7 +2,7 @@ "name": "ship-marketplace", "metadata": { "description": "Ship — a gated idea-to-production pipeline plugin for Claude Code (phases, expert-QA panel, templates, gitleaks secret scan).", - "version": "0.10.4" + "version": "0.10.5" }, "owner": { "name": "Vadim S." @@ -12,7 +12,7 @@ "name": "ship", "source": "./", "description": "Idea-to-production pipeline: gated phases, parallel expert-QA panel, reusable doc templates, and a gitleaks pre-commit + CI secret scan.", - "version": "0.10.4", + "version": "0.10.5", "license": "MIT", "keywords": ["workflow", "pipeline", "qa", "deployment"] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 793e888..6af9001 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "ship", "displayName": "Ship", - "version": "0.10.4", + "version": "0.10.5", "description": "A gated idea-to-production pipeline for Claude Code: research -> spec -> build -> layered QA (functional + eval + a parallel expert-agent panel) -> prod-prep -> provision -> deploy -> monitor, with reusable doc templates (including a gitleaks pre-commit + CI secret scan). Owner sign-off gates and per-phase state keep routine delivery steps from being skipped. Beta.", "author": { "name": "Vadim S.", diff --git a/CHANGELOG.md b/CHANGELOG.md index ca55335..92558e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,20 @@ All notable public changes to the **Ship** plugin are recorded here. +## [0.10.5] — 2026-07-24 + +Desktop/Cowork entry-point compatibility patch. + +### Fixed + +- The visible `/ship` skill is now the single public entry point in Desktop/Cowork and handles + deterministic new-project setup itself. +- README examples no longer tell Desktop/Cowork users to invoke `/ship:go`, which is not available + on that surface. +- Claude Code users can still use its namespaced skill surface; the old `go` command remains as a + compatibility alias. +- `ship-doctor` now guards the primary skill's scaffolder wiring and the public README entry point. + ## [0.10.4] — 2026-07-24 Initial public beta. diff --git a/README.md b/README.md index 9aadb26..ac18bda 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ for your approval before important decisions or external actions. Instead of rel chat, it keeps plans, acceptance criteria, QA findings, and release evidence in versioned files inside your repository. -**Free and open source** · MIT · `v0.10.4` · Beta · Not affiliated with Anthropic +**Free and open source** · MIT · `v0.10.5` · Beta · Not affiliated with Anthropic > Ship itself is free and has no subscription. Claude Code and model/API usage are still billed > according to your own Anthropic setup. @@ -31,7 +31,7 @@ This is a condensed trace from that run. It is shortened for readability, not pr verbatim transcript or benchmark: ```text -> /ship:go +> /ship What are you building? > A free English-language catalog of Claude Code skills, @@ -62,16 +62,25 @@ in the project. ## Quick start -In Claude Code: +Install Ship: ```text /plugin marketplace add vadimsv1/ship-plugin /plugin install ship@ship-marketplace -/ship:go ``` -Ship asks what you are building and whether it is a quick experiment or a real project. That is the -only workflow you need to learn. +Then open Claude Desktop or Cowork and start with: + +```text +/ship +``` + +Add your idea on the same line if you want: `/ship Build a small portfolio site.` Ship asks only +for missing information and whether this is a quick experiment or a real project. That is the only +workflow you need to learn. + +Claude Code namespaces plugin skills in its slash-command menu; there the same orchestrator can +appear as `/ship:ship`. You can also simply ask Claude to “use Ship” for the project. For a low-commitment first try, use a small repository and choose **Quick experiment**. Ship will use the shorter Lite flow instead of the full production pipeline. @@ -95,27 +104,26 @@ phones home. ## Examples -Three ways to start Ship — type these in Claude Code once the plugin is installed: +Three ways to start Ship in Claude Desktop or Cowork: 1. **A new content site (full pipeline):** - > `/ship:go` — *"Build a searchable catalog of open-source CLI tools: ~20 real tools, browse by + > `/ship` — *"Build a searchable catalog of open-source CLI tools: ~20 real tools, browse by > category, each page shows a working install command and a link to the real repo."* Ship runs research → spec (with an owner-approved design direction) → build → expert QA → fix. 2. **A quick experiment (Lite flow):** - > `/ship:go` — *"Quick experiment: a single-page cron-expression explainer. Keep it minimal."* + > `/ship` — *"Quick experiment: a single-page cron-expression explainer. Keep it minimal."* Ship uses the short Idea → Build → Deploy path and skips the heavy panel. 3. **An adversarial QA pass on an existing repo:** - > `/ship:expert-review` — *"Review this project before launch: code correctness, security on + > `/ship` — *"Review this project before launch: code correctness, security on > untrusted input, UI/UX on desktop + mobile, and SEO."* Ship runs the risk-sized panel + an independent verifier and triages verified findings. -You can also drive phases one at a time with `/ship:phase ` and check progress with -`/ship:ship-status`. +Ship selects and runs the relevant phases and reviewers underneath that one entry point. ## Why not just ask Claude Code to build it? @@ -304,7 +312,7 @@ It also scaffolds `.env.example`, `.gitignore`, pre-commit secret scanning, and ## Project types -`/ship:go` chooses a suitable type from your answer, or you can set it explicitly: +Ship chooses a suitable type from your answer, or you can set it explicitly: | Type | Intended use | Flow emphasis | |---|---|---| @@ -313,23 +321,17 @@ It also scaffolds `.env.example`, `.gitignore`, pre-commit secret scanning, and | `saas` | Full applications | Auth, billing, security, staging, and full release checks | | `engine` | Headless services and tools | Correctness, security, evaluation, and operations | -## Commands +## Everyday use -You only need `/ship:go`, but the lower-level commands remain available: +You only need one entry point: -| Command | Purpose | +| Entry | Purpose | |---|---| -| `/ship:go` | Set up a project and drive the appropriate workflow | -| `/ship:new-project` | Scaffold the deterministic phase-0 working set | -| `/ship:phase ` | Run one selected phase | -| `/ship:gate ` | Validate and advance a phase gate | -| `/ship:pack build\|check` | Build or validate a bounded context pack | -| `/ship:expert-review` | Run the relevant expert panel and verifier | -| `/ship:ship-status` | Show the current phase, gates, and production pointer | -| `/ship:handoff` | Package draft work for another session or person | -| `/ship:ship-update` | Reconcile project templates with a newer Ship version | - -Skills and agents run underneath these commands; users do not need to invoke them directly. +| `/ship` | Start a project, resume its current phase, or request a focused review | + +The scaffolder, phase skills, gates, context packs, reviewers, and handoffs run underneath it. +Their namespaced commands are an internal/advanced Claude Code surface and may not appear as +user-entered commands in Claude Desktop or Cowork. ## Real-world proof @@ -403,8 +405,8 @@ for. |---|---| | A gate or context command errors with `pyyaml missing` | `pip install pyyaml` — Ship's scripts need Python 3 + PyYAML. | | `python3: command not found` (often python.org Windows) | This is about the **manual scripts** (gate/context/migrate) — run them with `python` instead. | -| `/ship:ship-status` says **`Phase-Isolated pipeline: OFF`** | A phase ran without a context pack. Run `/ship:pack build ` (`/ship:phase` should build it automatically). This means the token economy isn't engaged — worth fixing before trusting a run's token numbers. | -| `/ship:gate` prints **BLOCKED** | It's doing its job — missing checks, an unverified QA, a leftover `{{placeholder}}`, or a null commit SHA. Fix what it lists; don't hand-set `gate_passed`. | +| Ship reports **`Phase-Isolated pipeline: OFF`** | A phase ran without a context pack. Ask Ship to rebuild and validate the current phase pack. This means the token economy isn't engaged — worth fixing before trusting a run's token numbers. | +| A Ship gate reports **BLOCKED** | It's doing its job — missing checks, an unverified QA, a leftover `{{placeholder}}`, or a null commit SHA. Fix what it lists; don't hand-set `gate_passed`. | | A gate blocks on a missing prior handoff (project upgraded from older Ship) | Run `python /scripts/context_builder.py migrate .` (use `python3` if that's your Python) to write a synthetic predecessor handoff (review it), or set `last_completed_phase` in `.ship/state.yml`. | | Installed version looks stale after an update | Refresh the marketplace clone, not just the plugin: `/plugin marketplace update ship-marketplace` → `/plugin install ship@ship-marketplace` → restart. | | `pre-commit` not found | Optional. Install `pre-commit` and run `pre-commit install`, or rely on the CI gitleaks job. | @@ -414,7 +416,8 @@ privately via [`SECURITY.md`](SECURITY.md). ## Installation details -- **Marketplace:** use the three commands in [Quick start](#quick-start). +- **Marketplace:** use the two install commands in [Quick start](#quick-start), then enter `/ship` + in Claude Desktop or Cowork. - **Local development:** `claude --plugin-dir /path/to/ship-plugin`. - **Loose installation:** copy `skills/`, `agents/`, and `commands/` into `~/.claude/` and keep the plugin directory available so they can resolve templates and scripts. diff --git a/commands/go.md b/commands/go.md index 2f77822..0317a5a 100644 --- a/commands/go.md +++ b/commands/go.md @@ -1,10 +1,11 @@ --- -description: Start here. Kick off a new project and let ship drive it end-to-end — just answer a couple of plain questions. +description: Compatibility alias for Claude Code's namespaced command surface. The primary Desktop/Cowork entry is the ship skill. argument-hint: "(optional) one line about what you're building" --- -You are the friendly front door of the ship pipeline. The user does NOT need to learn phases, -skills, or state files — just guide them. Keep it human. +This is a backward-compatible alias for the `ship` skill's friendly front door. Follow the same +workflow below. The user does NOT need to learn phases, skills, or state files — just guide them. +Keep it human. 1. **Ask up to two plain questions** (skip any already answered in $ARGUMENTS): - "What are you building?" (a sentence or two). diff --git a/scripts/scaffold_project.py b/scripts/scaffold_project.py index 13336bc..2ef81ba 100644 --- a/scripts/scaffold_project.py +++ b/scripts/scaffold_project.py @@ -1,6 +1,7 @@ #!/usr/bin/env python3 """ship scaffold_project — the DETERMINISTIC phase-0 scaffolder and single source of truth for the -exact phase-0 working set. `/ship:go` and `/ship:new-project` invoke THIS instead of copying files by +exact phase-0 working set. The primary `ship` skill and the compatibility/new-project commands invoke +THIS instead of copying files by hand: model-driven scaffolding drifted (a weak agent dropped CONSTITUTION.md and the secret-scan/CI, re-opening the empty-critical_rules P0). This script copies a fixed set, fills only the known scaffold placeholders, snapshots a COMPLETE baseline, and `git init -b main`s the project. Deferred docs diff --git a/scripts/ship-doctor.sh b/scripts/ship-doctor.sh index 8829ad0..1518295 100644 --- a/scripts/ship-doctor.sh +++ b/scripts/ship-doctor.sh @@ -106,7 +106,7 @@ grep -q '"hooks"[[:space:]]*:' .claude-plugin/plugin.json && er "plugin.json mus { [ -e hooks/hooks.json ] || [ -d hooks/scripts ]; } && er "leftover Claude-side secret hook under hooks/ — it was removed; gitleaks is the secret scan" || ok "no bundled Claude-side secret hook (gitleaks pre-commit + CI is the scan)" badpat "no hardcoded C:\\\\dev default in commands (cross-platform)" 'C:\\\\dev' commands -h "gate authority = EXECUTED, never hand-written (regression: /ship:go hand-edited gate_passed/current_phase)" +h "gate authority = EXECUTED, never hand-written (regression: front door hand-edited gate_passed/current_phase)" # The v0.10.2 fix: an owner approval is permission to RUN the gate, not to hand-edit its result. Both # entry commands must route the approval through the authoritative executable gate, and nothing may # offer a "write the fields by hand" shortcut (which skips the checks AND the checked_at stamp). @@ -138,8 +138,8 @@ grep -q 'ph\["checked_at"\]' scripts/gate_check.py \ h "deterministic scaffolder (model-driven phase-0 copying replaced; gate 0 enforces the inventory)" # A weak agent hand-scaffolding a subset dropped CONSTITUTION.md etc. Now scripts/scaffold_project.py is -# the single source of the exact phase-0 set; /ship:go and /ship:new-project INVOKE it; gate 0 blocks any -# incomplete scaffold (spec.phase0_required_files). Guard the pieces stay wired. +# the single source of the exact phase-0 set; the ship skill and compatibility/new-project commands +# INVOKE it; gate 0 blocks any incomplete scaffold (spec.phase0_required_files). Guard the pieces stay wired. [ -f scripts/scaffold_project.py ] && ok "scripts/scaffold_project.py present" || er "missing scripts/scaffold_project.py (the deterministic scaffolder)" [ -f scripts/test_scaffold.py ] && ok "scripts/test_scaffold.py present" || er "missing scripts/test_scaffold.py (full+lite integration)" grep -qE '^phase0_required_files:' spec/pipeline.yml \ @@ -153,8 +153,14 @@ for c in go new-project; do && ok "commands/$c.md invokes the scaffolder (no hand-copying)" \ || er "commands/$c.md must run scaffold_project.py, not hand-copy the phase-0 set" done +grep -q 'scaffold_project.py' skills/ship/SKILL.md \ + && ok "primary ship skill invokes the deterministic scaffolder on a new project" \ + || er "skills/ship/SKILL.md must run scaffold_project.py when /ship starts a new project" # the two reserved-name-colliding commands were renamed so they appear in the Claude Code menu -{ [ -f commands/go.md ] && [ -f commands/pack.md ]; } && ok "entry command is /ship:go and context cmd is /ship:pack (renamed off reserved /start,/context)" || er "commands/go.md + commands/pack.md must exist (renamed from start/context)" +{ [ -f commands/go.md ] && [ -f commands/pack.md ]; } && ok "primary entry is the ship skill; go.md remains a compatibility alias and pack.md avoids the reserved /context name" || er "commands/go.md + commands/pack.md must exist as compatibility/internal commands" +grep -q '/ship:go' README.md \ + && er "README.md must advertise the Desktop/Cowork /ship entry, not /ship:go (unavailable there)" \ + || ok "README.md does not advertise /ship:go" { [ -e commands/start.md ] || [ -e commands/context.md ]; } && er "leftover commands/start.md or commands/context.md (renamed to go.md/pack.md)" || ok "no leftover start.md/context.md (reserved-name collisions removed)" badpat "no active references to removed /ship:start or /ship:context commands" '/ship:(start|context)([^A-Za-z0-9_-]|$)' scripts commands skills README.md examples diff --git a/skills/ship/SKILL.md b/skills/ship/SKILL.md index 9dcc6a2..cc8e833 100644 --- a/skills/ship/SKILL.md +++ b/skills/ship/SKILL.md @@ -1,6 +1,7 @@ --- name: ship description: Drive a project from idea to production through a gated pipeline — research → spec → build → layered QA (functional + eval + a parallel expert-agent panel) → prod-prep → provision → deploy → monitor. Use when starting a new project, resuming one, or when the user says "take this to production", "ship it", "what's the next step", or asks to plan a project end-to-end. Enforces phase gates and owner sign-off to reduce skipped steps and keep delivery evidence visible. +argument-hint: "(optional) what you are building" --- # ship — the orchestrator @@ -106,7 +107,15 @@ detailed checklist. This orchestrator only sequences and gates. 1. Read `.ship/state.yml` — the source of truth for `current_phase`, gate status, and owner sign-offs. If it's missing, infer the phase from the furthest-along artifact in the map above, then create `.ship/state.yml` from the template to make it explicit. -2. If nothing exists → phase 0. Offer `/new-project` to scaffold the phase-0 working set. +2. If nothing exists → act as the friendly new-project front door. Treat `$ARGUMENTS` and the + current user message as the brief; ask at most two missing questions: what they are building, + and whether it is a quick experiment (`lite`) or a real project. Pick a safe project name and + destination, then **RUN the deterministic scaffolder** (never hand-copy the working set): + `python3 "${CLAUDE_PLUGIN_ROOT}/scripts/scaffold_project.py" "" ""` + (use `python` if `python3` is unavailable). It creates the exact placeholder-free phase-0 + working set, baseline, state, and git repository. Say only `Set up ✓`, draft the positioning + from the brief, and stop for the phase-0 owner approval. Desktop/Cowork users should not need + to know or invoke a second setup command. 3. State: *"Project **X** is in phase **N (name)**. Gate to pass: …"* (or run `/ship-status`). Then do the work.