Skip to content
Skills Library
Programming · Automation

ship-loop

/ship-loop

Run a chained build→ship→verify→notify pipeline for multi-segment feature work. Use when implementing multiple features in sequence, each as a coding agent task that gets committed, deployed, and verified before moving to the next. Prevents dropped handoffs between segments.

Licence
MIT
Last repository change
20.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
70
Scripts
48
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 20.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 48 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: docs/astro.config.mjs, docs/src/content.config.ts, scripts/learnings.sh, scripts/meta-experiment.sh, scripts/preflight.sh, scripts/repair.sh, scripts/run-segment.sh, scripts/ship.sh

What it does and when to use it

Run a chained build→ship→verify→notify pipeline for multi-segment feature work. Use when implementing multiple features in sequence, each as a coding agent task that gets committed, deployed, and verified before moving to the next. Prevents dropped handoffs between segments.

Original author description

Run a chained build→ship→verify→notify pipeline for multi-segment feature work. Use when implementing multiple features in sequence, each as a coding agent task that gets committed, deployed, and verified before moving to the next. Prevents dropped handoffs between segments.

How it works

  1. Architecture: Three Loops + Event Queue + Verdict Router
  2. Security Notice
  3. When to Use
  4. Prerequisites
  5. Installation
  6. CLI Usage
  7. Pipeline Definition (SHIPLOOP.yml)
  8. SQLite State Backend (v5.0)
  9. Verdict Router (v5.0)
  10. Meta-Reflection Loop (v5.0)
Original SKILL.md headings · 390 lines, 1,917 words
SKILL.md preview
---
name: ship-loop
description: >
  Run a chained build→ship→verify→notify pipeline for multi-segment feature work.
  Use when implementing multiple features in sequence, each as a coding agent task
  that gets committed, deployed, and verified before moving to the next. Prevents
  dropped handoffs between segments.
metadata:
  openclaw:
    emoji: "🚢"
    version: "5.0.0"
    requires:
      bins: ["git", "python3"]
      python: ["pyyaml>=6.0", "pydantic>=2.0"]
    trigger_phrases:
      - "ship loop"
      - "keep building"
      - "run the next segment"
      - "build these features"
      - "multi-feature pipeline"
      - "ship these segments"
---

# Ship Loop v5.0 — TARS Convergence

Orchestrate multi-segment feature work as a self-healing pipeline. Three nested loops ensure maximum autonomy: **Loop 1** runs the standard code→preflight→ship→verify chain, **Loop 2** auto-repairs failures via the coding agent, **Loop 3** spawns experiment branches when repairs stall. A **SQLite state backend** provides crash recovery and cross-run analytics. A **verdict router** replaces hardcoded branching with a configurable decision table. A **reflection loop** audits historical effectiveness and auto-generates learnings.

## Architecture: Three Loops + Event Queue + Verdict Router

```
┌───────────────────────────────────────────────────────────┐
│                  SHIP LOOP v5.0                           │
│                                                           │
│  LOOP 1: Ship Loop                                        │
│  code → preflight → ship → verify → emit(segment_shipped)│
│          │                                                │
│       on fail (verdict → action via VerdictRouter)        │
│          ▼                                                │
│  LOOP 2: Repair Loop                                      │
│  capture context → agent fix → re-preflight (max N)      │
│  ↳ emit events: repair_done | repair_failed               │
│  ↳ convergence detected → CONVERGED verdict → META        │
│  ↳ unknown error → record_decision_gap()                  │
│          │                                                │
│       exhausted                                           │
│          ▼                                                │
│  LOOP 3: Meta Loop                                        │
│  meta-analysis → N experiment branches → winner → merge   │
│  ↳ emit: meta_done                                        │
│                                                           │
│  🗄  SQLite (tars.db): runs, segments, events, learnings  │
│  📋  Event Queue: crash recovery via unprocessed events   │
│  🔀  Verdict Router: configurable verdict→action table    │
│  📚  Learnings Engine: scored lessons (score tracks use)  │
│  🪞  Reflect Loop: post-run analysis + recommendations    │
│  💰  Budget Tracker: token/cost tracking per run          │
└───────────────────────────────────────────────────────────┘
```

## Security Notice

> **SHIPLOOP.yml is equivalent to running a script.** The `agent_command`, all preflight commands (`build`, `lint`, `test`), and custom deploy scripts execute with your full user privileges. Ship Loop does **not** sandbox these commands. **Never use on untrusted repos without reviewing the config.** Treat SHIPLOOP.yml with the same caution as a Makefile or CI pipeline.

## When to Use

- Building multiple features for a project in sequence
- Any work that follows: code → preflight → commit → deploy → verify → next
- When you need checkpointing so progress survives session restarts
- When you want self-healing: failures auto-repair before asking humans
- When you want cost visibility and learning from past runs

## Prerequisites

- Python 3.10+ with `pyyaml` and `pydantic` installed
- A git repository with a remote
- A deployment pipeline triggered by push (Vercel, Netlify, etc.)
- A coding agent CLI configured via `agent_command` in SHIPLOOP.yml

## Installation

```bash
pip install pyyaml pydantic
```

## CLI Usage

```bash
# Core pipeline
shiploop run              # Start or resume the pipeline
shiploop run --dry-run    # Preview what would happen
shiploop status           # Show segment states (reads from DB)
shiploop reset <segment>  # Reset a segment to pending

# Learnings
shiploop learnings list
shiploop learnings search "dark mode theme toggle"

# Budget
shiploop budget           # Show cost summary

# v5.0 NEW
shiploop reflect          # Run meta-reflection on recent run history
shiploop reflect --depth 20  # Analyze last 20 runs
shiploop events           # View event history for latest run
shiploop events <run_id>  # View event history for specific run
shiploop history          # View past run history from DB

# Options
shiploop -c /path/to/SHIPLOOP.yml run
shiploop -v run           # Verbose logging
shiploop --version        # Show version (5.0.0)
```

## Pipeline Definition (SHIPLOOP.yml)

```yaml
project: "Project Name"
repo: /absolute/path/to/project
site: https://production-url.com
branch: pr               # direct-to-main | per-segment | pr
mode: solo

agent_command: "claude --print --permission-mode bypassPermissions"

preflight:
  build: "npm run build"
  lint: "npm run lint"
  test: "npm run test"

deploy:
  provider: vercel        # vercel | netlify | custom
  routes: [/, /api/health]
  marker: "data-version"
  health_endpoint: /api/health
  deploy_header: x-vercel-deployment-url
  timeout: 300

repair:
  max_attempts: 3

meta:
  enabled: true
  experiments: 3

budget:
  max_usd_per_segment: 10.0
  max_usd_per_run: 50.0
  max_tokens_per_segment: 500000
  halt_on_breach: true

# v5.0 NEW: Reflection config
reflection:
  enabled: true       # run reflect loop after pipeline
  auto_run: true      # automatically run, not just on CLI command
  history_depth: 10   # how many past runs to analyze

# v5.0 NEW: Custom verdict routing
router:
  agent_fail: retry      # override default (fail) with retry
  deploy_fail: fail      # override default (retry) with fail

segments:
  - name: "feature-name"
    status: pending
    prompt: |
      Your coding agent prompt here.
    depends_on: []
```

## SQLite State Backend (v5.0)

State is now stored in `.shiploop/tars.db` (SQLite, WAL mode). SHIPLOOP.yml is config-only.

### Tables

| Table | Purpose |
|-------|---------|
| `runs` | Pipeline execution records (id, project, started_at, status, cost) |
| `segments` | Segment execution records per run (status, commit, touched_paths) |
| `run_events` | Event queue for crash recovery and audit trail |
| `learnings` | Failure/success lessons with effectiveness scores |
| `usage` | Token and cost records per agent invocation |
| `decision_gaps` | Situations the system didn't know how to handle |

### Event Types

| Event | When emitted |
|-------|-------------|
| `agent_started` | Agent invocation begins |
| `preflight_passed` | All preflight steps pass |
| `preflight_failed` | Any preflight step fails |
| `repair_done` | Repair loop succeeded |
| `repair_failed` | Repair loop failed or exhausted |
| `meta_done` | Meta loop winner merged |
| `segment_shipped` | Segment fully complete |
| `segment_failed` | Segment permanently failed |
| `deploy_failed` | Deploy or verification failed |
| `file_overlap_warning` | Segment may touch files changed by prior segment |

**Crash recovery**: On startup, unprocessed events are replayed to restore pipeline state.

## Verdict Router (v5.0)

The orchestrator no longer uses `if/else` chains. Every outcome maps to a `Verdict`, and a `VerdictRouter` maps verdicts to `Action` values.

### Default Routing Table

| Verdict | Default Action |
|---------|---------------|
| `success` | `ship` |
| `preflight_fail` | `repair` |
| `agent_fail` | `fail` |
| `deploy_fail` | `retry` |
| `repair_success` | `ship` |
| `repair_exhausted` | `meta` |
| `meta_success` | `ship` |
| `meta_exhausted` | `fail` |
| `budget_exceeded` | `fail` |
| `converged` | `meta` ← skip remaining repairs, jump to meta |
| `no_changes` | `fail` |
| `unknown` | `pause_and_alert` |

Override via `router:` section in SHIPLOOP.yml (see above).

## Meta-Reflection Loop (v5.0)

Runs automatically after pipeline completion (when `reflection.auto_run: true`) or manually via `shiploop reflect`.

### What It Analyzes

1. **Repeat failures** — same error_signature across multiple segments/runs
2. **Repair-heavy segments** — segments that needed >1 repair loop (same error type)
3. **Efficiency trends** — cost/time per segment trending up or down
4. **Stale learnings** — learnings with score < 0.3 that haven't helped
5. **Decision gaps** — situations that triggered `MISSING_DECISION_BRANCH`

### Auto-creates learnings from patterns

If an error signature appears 3+ times across runs, the reflect loop auto-generates a `AUTO-<sig>` learning flagging it for human review.

```bash
shiploop reflect --depth 20

═════════════════════════════════════════════════════
🪞  Ship Loop Reflection Report
   Generated: 2026-03-27T06:30:00Z
   Runs analyzed: 10
═════════════════════════════════════════════════════

📊 Efficiency
   Total cost:     $12.4200
   Segments run:   8
   Avg/segment:    $1.5525

🔁 Repeat Failures (2)
   abc123def456… × 3
   ...

💡 Recommendations
   ⚠️  Error signature abc123de… repeated 3× across segments: auth, api, db.
   📉 2 stale learning(s) (score < 0.3): L002, L004.
   ✅ No issues detected in recent history. Pipeline looks healthy!

═════════════════════════════════════════════════════
```

## Playbook Evolution (v5.0)

When a repair fails with an error that doesn't match any existing learning, the system records a `decision_gap`:

```python
learnings.record_decision_gap(
    segment="auth",
    context="Repair exhausted with unmatched error: ...",
    verdict="repair_exhausted_unknown_error",
    run_id="...",
)
```

Decision gaps surface in `shiploop reflect` output and the `decision_gaps` DB table. Operators use them to add new learnings or router overrides.

## Convergence Detection (v5.0 Enhanced)

**Same-segment**: if two consecutive repair attempts produce the same error hash → `CONVERGED` verdict → router jumps to META (skipping remaining repair attempts).

**Cross-segment**: before starting a segment, the orchestrator checks if any already-shipped segment touched the same files (via `touched_paths` in DB). If overlap detected, a `file_overlap_warning` event is emitted.

## Learnings Scoring (v5.0)

```
score (default 1.0)
  +0.1 when injected and segment succeeds first-try
  -0.2 when injected and segment fails the same way
```

Search results are sorted by combined keyword-relevance × score. Learnings with `score < 0.3` are flagged as stale in reflection.

```bash
shiploop learnings list  # shows all learnings with scores
```

## State Machine

```
States per segment:
  pending → coding → preflight → shipping → verifying → shipped
                  ↘ repairing (Loop 2) → preflight
                  ↘ experimenting (Loop 3) → preflight → shipping
                  ↘ failed
```

SHIPLOOP.yml checkpointed after every transition (for backward compat). SQLite is the primary state store.

## Deploy Providers

| Provider | How it works |
|----------|-------------|
| `vercel` | Polls routes for HTTP 200, checks `x-vercel-deployment-url` header |
| `netlify` | Polls routes for HTTP 200, checks `x-nf-request-id` header |
| `custom` | Runs `deploy.script` with `SHIPLOOP_COMMIT` and `SHIPLOOP_SITE` env vars |

## Budget Tracking

Token usage and estimated costs tracked per agent invocation in SQLite (falls back to `metrics.json`).

```bash
shiploop budget

💰 Budget Summary: Portfolio
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Total cost:       $3.84
  Budget remaining: $46.16
  Total records:    12

  By segment:
    dark-mode: $0.42
    contact-form: $3.42
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## Critical Rules

1. **Never break the chain** — after a segment ships, immediately start the next
2. **Preflight is mandatory** — no exceptions, no "ship now fix later"
3. **Explicit staging only** — never `git add -A`, only changed files from `git diff`
4. **Prompts via file** — never shell arguments (prevents injection)
5. **SQLite is source of truth** — SHIPLOOP.yml config-only; runtime state in `tars.db`
6. **Agent command from config** — always read from `agent_command`, never hardcode
7. **Budget-aware** — track costs, enforce limits, fail gracefully

## Project Structure

```
skills/ship-loop/
├── SKILL.md                  # This file
├── pyproject.toml
├── shiploop/
│   ├── __init__.py           # __version__ = "5.0.0"
│   ├── cli.py                # CLI (run, status, reset, reflect, events, history, ...)
│   ├── config.py             # SHIPLOOP.yml parsing + validation (Pydantic v2)
│   ├── orchestrator.py       # Main state machine + event queue + verdict routing
│   ├── db.py                 # NEW: SQLite state backend (tars.db)
│   ├── router.py             # NEW: Verdict→Action router
│   ├── learnings.py          # Learnings engine (SQLite + scoring + decision gaps)
│   ├── budget.py             # Cost/token tracking (SQLite backend)
│   ├── git_ops.py            # git operations + get_touched_paths()
│   ├── agent.py              # Agent runner
│   ├── deploy.py             # Deploy verification
│   ├── preflight.py          # Build + lint + test runner
│   ├── reporting.py          # Status messages + reports
│   ├── ship_utils.py         # Ship and verify helper
│   └── loops/
│       ├── ship.py           # Loop 1: code → preflight → ship
│       ├── repair.py         # Loop 2: repair + decision gap detection
│       ├── meta.py           # Loop 3: meta-analysis + experiments
│       ├── reflect.py        # NEW: post-run reflection + recommendations
│       └── optimize.py       # Optimization loop
├── providers/
│   ├── vercel.py
│   ├── netlify.py
│   └── custom.py
└── tests/
    ├── test_config.py
    ├── test_orchestrator.py
    ├── test_git_ops.py
    ├── test_budget.py
    ├── test_learnings.py
    └── ...
```

## Changelog

### v5.0.0 (2026-03-27) — TARS Convergence

- **SQLite state backend**: `tars.db` replaces `metrics.json` + `learnings.yml` for runtime state
- **Event queue**: all phase transitions emit events; unprocessed events enable crash recovery
- **Verdict router**: configurable `Verdict → Action` table replaces if/else chains in orchestrator
- **Meta-reflection loop**: `shiploop reflect` analyzes run history, finds patterns, auto-generates learnings
- **Playbook evolution**: `MISSING_DECISION_BRANCH` detection → `decision_gaps` table
- **Cross-segment convergence**: `touched_paths` tracked per segment for overlap warnings
- **Learnings scoring**: score field (+0.1 on success, -0.2 on failure), sorted by score
- **New CLI commands**: `reflect`, `events`, `history`
- **New config sections**: `reflection`, `router`

### v4.0.0

- Python CLI replaces bash scripts
- Pydantic v2 config validation
- Budget tracking with per-segment and per-run limits
- Error convergence detection (hash-based)
- Deploy provider plugins (Vercel, Netlify, Custom)
Files in this package (70)
  • CONTRIBUTING.md 3 KB
  • README.md 8 KB
  • SKILL.md 16 KB
  • _meta.json 1 KB
  • pyproject.toml 1 KB
  • docs/README.md 2 KB
  • docs/astro.config.mjs 2 KB
  • docs/package-lock.json 221 KB
  • docs/package.json 1 KB
  • docs/tsconfig.json 1 KB
  • docs/public/favicon.svg 1 KB
  • docs/src/content.config.ts 1 KB
  • docs/src/content/docs/index.mdx 2 KB
  • docs/src/content/docs/concepts/architecture.md 5 KB
  • docs/src/content/docs/concepts/budget.md 2 KB
  • docs/src/content/docs/concepts/learnings.md 3 KB
  • docs/src/content/docs/getting-started/installation.md 1 KB
  • docs/src/content/docs/getting-started/introduction.md 2 KB
  • docs/src/content/docs/getting-started/quickstart.md 3 KB
  • docs/src/content/docs/guides/adding-a-provider.md 3 KB
  • docs/src/content/docs/guides/agent-presets.md 2 KB
  • docs/src/content/docs/reference/cli.md 3 KB
  • docs/src/content/docs/reference/configuration.md 4 KB
  • docs/src/content/docs/reference/providers.md 2 KB
  • scripts/learnings.sh 6 KB
  • scripts/meta-experiment.sh 6 KB
  • scripts/preflight.sh 3 KB
  • scripts/repair.sh 4 KB
  • scripts/run-segment.sh 18 KB
  • scripts/ship.sh 7 KB
  • scripts/verify-deploy.sh 8 KB
  • shiploop/__init__.py 1 KB
  • shiploop/agent.py 3 KB
  • shiploop/budget.py 7 KB
  • shiploop/cli.py 15 KB
  • shiploop/config.py 6 KB
  • shiploop/db.py 19 KB
  • shiploop/deploy.py 1 KB
  • shiploop/git_ops.py 6 KB
  • shiploop/learnings.py 10 KB
  • shiploop/orchestrator.py 21 KB
  • shiploop/preflight.py 2 KB
  • shiploop/reporting.py 7 KB
  • shiploop/router.py 3 KB
  • shiploop/ship_utils.py 2 KB
  • shiploop/loops/__init__.py 1 KB
  • shiploop/loops/meta.py 9 KB
  • shiploop/loops/optimize.py 10 KB
  • shiploop/loops/reflect.py 7 KB
  • shiploop/loops/repair.py 6 KB
  • shiploop/loops/ship.py 4 KB
  • shiploop/providers/__init__.py 1 KB
  • shiploop/providers/base.py 1 KB
  • shiploop/providers/custom.py 2 KB
  • shiploop/providers/netlify.py 2 KB
  • shiploop/providers/vercel.py 3 KB
  • tests/__init__.py 1 KB
  • tests/test_agent.py 3 KB
  • tests/test_budget.py 5 KB
  • tests/test_cli.py 2 KB
  • tests/test_config.py 5 KB
  • tests/test_deploy.py 3 KB
  • tests/test_git_ops.py 2 KB
  • tests/test_integration.py 13 KB
  • tests/test_learnings.py 6 KB
  • tests/test_meta.py 4 KB
  • tests/test_optimize.py 15 KB
  • tests/test_orchestrator.py 4 KB
  • tests/test_preflight.py 3 KB
  • tests/test_repair.py 3 KB

Versions

RepositoryScoreLicence
This page · LeoYeAI/openclaw-master-skills100MIT
collective-wisdom-org/collective-wisdom100MIT

Database snapshot: 13.11.2026 · package version 8ececf487bbe (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100spec-driven-dev
    Use when starting any non-trivial feature, refactor, or new project that will touch more than one file. Drives an AI coding agent through a gated Spec → Plan → Build → Test → Review → Ship lifecycle so work is specified before it is built, verified before it is reviewed, and…
  • 90ownership
    Autonomous build-ship-verify loop that ends with code committed, deployed, and confirmed live. Triggers on: "$ownership", "execute X with ownership", "build this overnight", or any request for an autonomous product loop with no human checkpoints until production is verified. NOT…
  • 96verify
    Use when coding: run the checks and tests /ship picks until green. (gstack)
  • 100ship
    Ship one verified PR — the pipeline's single merge authority. Trigger on \"/ship\", \"ship #N\", \"merge #N\", \"enqueue #N\", \"close the loop on #N\", and whenever a reviewed PR needs its merge driven to a terminal state. Not review (`review`), not repair (`build`), not the human release flip.
  • 100go
    Use when you want to auto-run all remaining Ship steps for a feature without manual step-by-step invocation
  • 96ship-task
    Use to wrap up a finished task - set status to done, merge, clean up.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.