Skip to content

MAX-524: improve ship README #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
maxtechera wants to merge 1 commit into
base: main
Choose a base branch
from
Open

MAX-524: improve ship README #13

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
306 changes: 121 additions & 185 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 "<idea>"` | 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 "<idea>"` | Create a new run, check credentials, and hand work to the engine |
| `/ship status [RUN-ID]` | Show stage, recent updates, and blockers |
| `/ship run <RUN-ID>` | 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).
Loading