From a4253c71984ff6e0f1c22b9eeac091ae816574d0 Mon Sep 17 00:00:00 2001 From: OpenClaw Agent Date: Wed, 22 Apr 2026 17:21:10 +0000 Subject: [PATCH] docs: improve README for ship --- README.md | 306 +++++++++++++++++++++--------------------------------- 1 file changed, 121 insertions(+), 185 deletions(-) diff --git a/README.md b/README.md index a166983..ae432cd 100644 --- a/README.md +++ b/README.md @@ -1,260 +1,196 @@ -# /ship +# ship -[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Version](https://img.shields.io/badge/version-0.3.0-green.svg)](CHANGELOG.md) +[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) +[![Platform: Claude Code](https://img.shields.io/badge/Claude_Code-supported-7C3AED)](#quick-start) +[![Platform: OpenClaw](https://img.shields.io/badge/OpenClaw-supported-111827)](#quick-start) +[![Platform: Gemini CLI](https://img.shields.io/badge/Gemini_CLI-supported-2563EB)](#quick-start) +[![Platform: Codex CLI](https://img.shields.io/badge/Codex_CLI-supported-059669)](#quick-start) -**Run `/ship` once. A coordinator team spawns, the dashboard renders, and work starts moving.** +Ship is an open source GTM operating system for teams running launches, content, and conversion work through one agentic pipeline. It is built for operators who want real stage ownership, credential-gated execution, and reviewer-visible proof instead of loose prompt chains. -Claude Code: -``` -/plugin marketplace add maxtechera/ship -``` +It boots a coordinator-led team that reads active work, routes specialists by stage, blocks risky deploys when credentials are missing, and keeps every run moving from idea to measurement. -OpenClaw: -```bash -clawhub install ship -``` +## What you get -Requires [orchestrator](https://github.com/maxtechera/orchestrator) — ship uses orchestrator's agent team coordination, loop mechanics, and verification harness. Ship adds the GTM pipeline, credential gate, and domain roster. +- A coordinator that keeps GTM work moving across the full pipeline +- Stage supervisors for intake, validation, strategy, awareness, lead capture, nurture, closing, launch, and measure +- A credential gate that checks 30+ integrations before deploy actions +- A critic and analyst review path so assets do not advance on vibes alone +- Content sub-skills for the actual production layer, not just orchestration ---- +## Quick start -A 9-agent GTM team boots on first run. The coordinator reads your Linear tickets, routes each active run to the right specialist by stage, and keeps every agent busy. The critic blocks every gate — fresh context, never sees the executor's work log, 100-pt rubric. The analyst runs pre-publish hook scoring before critic final approval, not just post-launch. - -**The pipeline:** idea → validate → strategy → awareness → lead-capture → nurture → closing → launch → measure +```bash +clawhub install ship +/credentials +/ship +``` -**Every deploy is credential-gated.** `check_local.py` covers 30+ integrations. Missing token = blocked run, not a mid-sprint surprise. +What those three commands do: ---- +1. Install the skill suite +2. Verify the credentials you need before work starts +3. Boot the ship dashboard and coordinator team -## Commands +## Core commands -| Command | Description | -|---------|-------------| -| `/ship` | Spawn coordinator team + render live dashboard of all active runs | -| `/ship create ""` | Create Linear run ticket, preflight credentials, hand off to engine | -| `/ship status [RUN-ID]` | Stage + last update + blocked items for an active run | +| Command | What it does | +|---|---| +| `/ship` | Launch the dashboard and coordinator team | +| `/ship create ""` | Create a new run, check credentials, and hand work to the engine | +| `/ship status [RUN-ID]` | Show stage, recent updates, and blockers | | `/ship run ` | Resume an existing run | -## Install +## Three concrete use cases -### Claude Code -``` -/plugin marketplace add maxtechera/ship -``` +### 1. Turn a rough launch idea into an active GTM run -### Update -``` -claude plugin update ship@ship -``` - -### OpenClaw -```bash -clawhub install ship -``` +**Before** -### Manual -```bash -git clone https://github.com/maxtechera/ship.git ~/.claude/skills/ship +```text +"We should probably launch the new AI automation workshop next week." ``` -### Gemini CLI -```bash -gemini extensions install maxtechera/ship -``` +**After** -### Codex CLI ```bash -git clone https://github.com/maxtechera/ship.git ~/.agents/skills/ship +/ship create "Launch the AI automation workshop for founders who want SOP-backed agents" ``` ---- - -## The Team - -Coordination (TeamCreate, zero-idle, loop) is provided by [orchestrator](https://github.com/maxtechera/orchestrator). Ship provides the GTM roster and domain prompts. - -Nine pre-defined roles. Coordinator assigns on every loop tick. - -| Agent | Coverage | Notes | -|-------|----------|-------| -| `coordinator` | All stages — routes + assigns | Reads Linear, zero-idle | -| `critic` | All gates + verified advances | v3 rubric (100-pt, ≥75 threshold), one-revise-max, fresh context only | -| `strategist` | Intake → Validate → Strategy | Blackboard keys: `intake.*`, `validate.*`, `strategy.*` | -| `content` | Awareness (all 17 sub-skills) | Carousel 1080×1350, reel hook 0-3s, newsletter ≤50 chars | -| `growth` | Lead Capture (UTM, GA4, A/B) | UTM required before campaign; A/B needs ≥400 control recipients | -| `nurture` | Nurture sequences + MailerLite | OSS Nurture Mode for `oss_tool` runs | -| `closer` | Closing (sales/course pages) | OSS Closing Mode for `oss_tool` runs | -| `launcher` | Launch readiness + directories | Runs credentials preflight before every deploy action | -| `analyst` | 3-stream: viral library + hook scoring + post-launch tracking | Pre-publish gate participant, not async-only | +Ship creates the run, checks credentials, routes strategy work first, and gives you a tracked pipeline instead of a loose brainstorm. -**Dynamic roles** — coordinator spawns as needed: `researcher`, `seo-specialist`, `outreach`, `designer`. +### 2. Keep content production connected to review and launch -### The analyst 3-stream model +**Before** -- **Stream 1** (pre-launch): seed viral pattern library per wave before content starts the bundle -- **Stream 2** (pre-publish gate): score every surface hook against library (0-10 pattern match + predicted engagement band). Default step: hook-vocab audit — grep bundle for category-native phrases, flag mismatches. Feed results to critic before final approval. -- **Stream 3** (async post-launch): T+24h / T+7d / T+30d actuals → update Linear ticket, flag underperformers +```text +Docs live in one place, assets in another, approvals happen in chat, and nobody knows what is actually ready. +``` -### The critic v3 rubric +**After** -100-pt, 10 categories × 10. Threshold ≥75 to approve. One revise pass max. +```text +idea → validate → strategy → awareness → lead-capture → nurture → closing → launch → measure +``` -| # | Category | -|---|----------| -| 1 | Brand voice | -| 2 | Audience fit | -| 3 | Hook strength (STEPPS ≥3/6, VE ≥100, pattern library match) | -| 4 | CTA + Hormozi two-part rule (Action + Reason-for-now) | -| 5 | Offer framing (value stack, risk reversal, urgency, dream outcome) | -| 6 | Structural completeness | -| 7 | Guide alignment (vs research guide) | -| 8 | Human-sounding (zero Tier-1 AI words, varied sentence length) | -| 9 | Format craft (platform-specific: carousel cadence, reel first-10s, HN no-emoji) | -| 10 | Verbatim/specificity (real numbers, receipts over claims) | +Each stage has an owner, proof requirements, and a gate before the run advances. -When analyst Stream-2 avg ≥7 and band mid/high, critic uses Stream-2 score ±1 for category 3 — no double-scoring. +### 3. Catch broken deploy readiness before it burns a sprint ---- +**Before** -## Credential Preflight +```bash +python3 credentials/scripts/check_local.py --quiet +# failures show up only after work is already blocked downstream +``` -Every deploy action gates on credential health. Run manually anytime: +**After** ```bash -# Check everything -python3 credentials/scripts/check_local.py +/ship +# launcher and credential preflight stop the run before a deploy action starts +``` -# Only failures -python3 credentials/scripts/check_local.py --quiet +That means missing tokens, expired auth, or absent CLIs are surfaced early, when they are still cheap to fix. -# With fix commands -python3 credentials/scripts/check_local.py --fix +## Skill map -# Scope to specific services -python3 credentials/scripts/check_local.py --only "github,railway,vercel,openai,anthropic" +| Layer | Path | What it owns | +|---|---|---| +| Credentials | `credentials/` | Preflight checks, CLI installs, auth helpers, token refresh | +| Engine | `engine/` | Dashboard loop, routing logic, active run orchestration | +| Supervisors | `supervisors/` | Stage-specific execution across intake to measure | +| Content | `content/` | Production skills for assets, copy, and channel outputs | +| Critic | `orchestrator` composition + ship review contract | Approval gates, proof expectations, stage advancement discipline | -# JSON output for automation -python3 credentials/scripts/check_local.py --json -``` +## Team structure -Exit 0 = all pass. Exit 1 = failures — prints `fix_cmd` per failure. +Coordination comes from [orchestrator](https://github.com/maxtechera/orchestrator). Ship adds the GTM roster, stage logic, credential system, and content production surface. -### What gets checked +| Role | Coverage | Notes | +|---|---|---| +| `coordinator` | All stages | Reads active runs, routes work, keeps zero-idle flow | +| `critic` | All gates | Fresh-context review, rubric-based approval | +| `strategist` | Intake, validate, strategy | Research, ICP, positioning, offer design | +| `content` | Awareness | Produces content assets across sub-skills | +| `growth` | Lead capture | UTM wiring, GA4, experiments | +| `nurture` | Nurture | Email flows, segmentation, automation | +| `closer` | Closing | Sales pages, objections, conversion assets | +| `launcher` | Launch | Readiness, deploy gating, final preflight | +| `analyst` | Measure | Hook scoring, performance tracking, learnings | -| Category | Services | -|----------|----------| -| Runtime CLIs (4) | `git`, `node`, `pnpm`, `python3` | -| CLI Auth (7) | `gh`, `railway`, `vercel`, `linear`, `supabase`, `render`, `docker` | -| API Tokens (10) | OpenAI, Anthropic, Gemini, xAI, Perplexity, Meta, ManyChat, Telegram, Brave, Zoom | -| CLI-first + fallback (4) | Twilio, ElevenLabs, MailerLite, PostHog | -| Google Suite (7) | `google_oauth`, `ga4`, `gsc`, `gcal`, `gdrive`, `gmail`, `skool` | +## Install options -### Credential scripts +### Claude Code ```bash -# Install all missing CLIs (idempotent) -python3 credentials/scripts/install.py --all +claude plugin marketplace add maxtechera/ship +claude plugin install ship@ship +``` -# Interactive auth wizard — shows status, offers to fix failures -bash credentials/scripts/auth.sh +### OpenClaw -# Check token expiry + auto-refresh (Meta 60d, MercadoLibre 6h, MercadoPago 180d) -python3 credentials/scripts/refresh.py --check -python3 credentials/scripts/refresh.py +```bash +clawhub install ship ``` -**First-time setup:** +### Gemini CLI ```bash -python3 credentials/scripts/install.py --all # 1. Install CLIs -bash credentials/scripts/auth.sh # 2. Authenticate -python3 credentials/scripts/check_local.py # 3. Verify (should exit 0) +gemini extensions install maxtechera/ship ``` ---- +### Codex CLI -## Configuration +```bash +git clone https://github.com/maxtechera/ship.git ~/.agents/skills/ship +``` -Credentials are read from the first matching location: +### Manual -| Priority | Path | -|----------|------| -| 1 | `$SHIP_CRED_DIR` | -| 2 | `$OPENCLAW_CRED_DIR` (legacy alias) | -| 3 | `/data/.clawdbot` (existing container) | -| 4 | `~/.clawdbot` (existing legacy) | -| 5 | `~/.config/ship/credentials` (default) | +```bash +git clone https://github.com/maxtechera/ship.git ~/.claude/skills/ship +``` -Set `$SHIP_CRED_DIR` to point anywhere. Token files live inside: `.github_token`, `.openai_token`, `.anthropic_token`, etc. +## Credential preflight ---- +Run this any time you want a direct health check: -## Extend credentials +```bash +python3 credentials/scripts/check_local.py +``` -Drop a `*.yml` file into `$SHIP_CRED_DIR/extensions/` to register additional checks: +Useful variants: -```yaml -version: 1 -checks: - - id: my_service - category: api-token - detect: - env: MY_SERVICE_TOKEN - token_file: .my_service_token - whoami: - url: https://api.my-service.com/me - auth: "header:Bearer" - fix: - summary: "Paste new My Service token" - template: "echo 'tok_...' > {cred_dir}/.my_service_token && chmod 600 {cred_dir}/.my_service_token" +```bash +python3 credentials/scripts/check_local.py --quiet +python3 credentials/scripts/check_local.py --fix +python3 credentials/scripts/check_local.py --json +python3 credentials/scripts/check_local.py --only "github,railway,vercel,openai,anthropic" ``` ---- +Ship checks runtime tools, CLI auth, API tokens, and Google-suite integrations before deploy actions. Missing credentials block the run early, not halfway through launch week. -## What This Repo Contains +## Repository map -``` +```text ship/ - SKILL.md # Core skill — the agent reads this + SKILL.md credentials/ - SKILL.md # Credentials sub-skill - scripts/ - check_local.py # Preflight runner — JSON output, exit codes, --only filter - install.py # Idempotent CLI installer - auth.sh # Interactive auth wizard - refresh.py # Auto-refresh expiring tokens - registry/core.yml # Declarative check index - extensions/ # Drop *.yml here to add custom checks + engine/ supervisors/ - engine/SKILL.md # Always-on control loop — reconciles Linear, delegates stages - intake/SKILL.md - validate/SKILL.md - strategy/SKILL.md - awareness/SKILL.md - lead-capture/SKILL.md - nurture/SKILL.md # Includes OSS Nurture Mode - closing/SKILL.md # Includes OSS Closing Mode - launch/SKILL.md # Credential gate before every deploy - measure/SKILL.md - content/ # 17 content sub-skills + content/ ``` ---- - ## Principles -- Credentials gate before agents start, not mid-sprint -- The coordinator never idles — zero-idle rule applies to every specialist -- The critic never reads the executor's work log — fresh context only -- The analyst gates critic approval, not just post-launch measurement -- One revise pass max — don't block on perfectionism -- `oss_tool` runs follow a different conversion chain: GitHub install → newsletter → course - ---- +- Practitioner-first, not prompt-theater +- Proof before advancement +- Fresh-context review for critic decisions +- Credential gating before deploy work +- One pipeline from idea to measurement ## License -MIT — see [LICENSE](LICENSE). - -Maintained by [maxtechera](https://github.com/maxtechera). +MIT. See [LICENSE](LICENSE).