Shipwright

The Autonomous Delivery Platform
From labeled GitHub issue to merged PR — with 18 new autonomous agents orchestrating every step.

Table of Contents

• Shipwright Builds Itself
• Code Factory Pattern
• What's New in v3.2.4
• How It Works
• Install
• Quick Start
• Features
• Commands
• Pipeline Templates for Teams
• Configuration
• Prerequisites
• Architecture
• Contributing
• License

Shipwright Builds Itself

This repo uses Shipwright to process its own issues. Label a GitHub issue with shipwright and the autonomous pipeline takes over: semantic triage, plan, design, build, test, review, quality gates, PR. No human in the loop.

See it live | Create an issue and watch it build.

Code Factory Pattern

Shipwright implements the complete Code Factory control-plane pattern — where agents write 100% of the code and the repo enforces deterministic, risk-aware checks before every merge. Every decision is traceable to policy. Every merge is backed by machine-verifiable evidence.

Agent writes code → Risk policy gate → Tier-appropriate CI → Code review agent
→ Findings auto-remediated → SHA-validated evidence → Bot threads cleaned → Merge
→ Incidents feed back into harness coverage

What makes Shipwright best-in-class

Beyond the baseline

Shipwright extends the Code Factory pattern with capabilities most implementations don't have:

• 12-stage pipeline with self-healing builds, adversarial review, and compound quality gates
• Predictive risk scoring using GitHub signals (security alerts, contributor expertise, file churn)
• Persistent memory — failure patterns, fix effectiveness, and prediction accuracy compound over time
• Auto-learning — self-optimize runs automatically after every pipeline completion, including context efficiency tuning
• Decision engine — tiered autonomous decisions with outcome learning and deduplication
• Unified model routing — single source of truth for model selection across all components
• Evidence-gated merges — SHA discipline ensures all evidence validated against current PR head
• Semantic quality audits — Claude-powered audits with grep fallback when Claude unavailable
• 18 autonomous agents with specialized roles (PM, reviewer, security auditor, test generator, etc.)
• Cross-platform compatibility — portable date helpers, file_mtime, and compat layer for macOS/Linux
• Fleet operations — the Code Factory pattern applied across every repo in your org
• Cost intelligence — per-pipeline cost tracking, budget enforcement, adaptive model routing
• Self-optimization — DORA metrics analysis auto-tunes daemon config and template weights

# Evidence framework — capture and verify all types
npm run harness:evidence:capture          # All collectors (browser, API, DB, CLI)
npm run harness:evidence:capture:api      # API endpoints only
npm run harness:evidence:capture:cli      # CLI commands only
npm run harness:evidence:capture:database # Database checks only
npm run harness:evidence:verify           # Verify manifest + freshness
npm run harness:evidence:pre-pr           # Capture + verify in one step

# Risk and policy
npm run harness:risk-tier

# Incident-to-harness loop
shipwright incident gap list
shipwright incident gap sla

Full Code Factory documentation

What's New in v3.2.4

Code Factory pattern — deterministic, risk-aware agent delivery with machine-verifiable evidence:

• Risk policy gate — PR-level preflight classifies risk tier from changed files; blocks before expensive CI
• SHA discipline — All evidence validated against current PR head SHA; stale evidence never trusted
• Evidence framework — 6 collector types (browser, API, database, CLI, webhook, custom) with freshness enforcement
• Review remediation — Agent reads review findings, patches code, validates, pushes fix commit in-branch
• Auto-resolve bot threads — Bot-only PR threads cleaned up after clean rerun; human threads untouched
• Harness-gap loop — Every incident creates a test case requirement with SLA tracking (P0: 24h, P1: 72h)
• Policy contract v2 — Risk tiers, merge policy, docs drift rules, evidence specs, harness SLAs in one file

v2.3.1: Autonomous feedback loops, testing foundation, chaos resilience

v2.3.0: Fleet Command completeness overhaul + autonomous team oversight

v2.0.0: 18 autonomous agents, 100+ CLI commands, intelligence layer, multi-repo fleet, local mode

How It Works

graph LR
    A[GitHub Issue] -->|labeled 'shipwright'| B[Daemon]
    B --> C[Triage & Score]
    C --> D[Select Template]
    D --> E[Pipeline]

    subgraph Pipeline ["12-Stage Pipeline"]
        direction LR
        E1[intake] --> E2[plan] --> E3[design] --> E4[build]
        E4 --> E5[test] --> E6[review] --> E7[quality]
        E7 --> E8[PR] --> E9[merge] --> E10[deploy]
        E10 --> E11[validate] --> E12[monitor]
    end

    E --> E1
    E12 --> F[Merged PR]

    subgraph Intelligence ["Intelligence Layer"]
        I1[Predictive Risk]
        I2[Model Routing]
        I3[Adversarial Review]
        I4[Self-Optimization]
    end

    Intelligence -.->|enriches| Pipeline

    style A fill:#00d4ff,color:#000
    style F fill:#4ade80,color:#000

When tests fail, the pipeline re-enters the build loop with error context — self-healing like a developer reading failures and fixing them. Convergence detection stops infinite loops. Error classification routes retries intelligently.

Install

One-command install (recommended):

git clone https://github.com/sethdford/shipwright.git && cd shipwright && ./install.sh

curl

curl -fsSL https://raw.githubusercontent.com/sethdford/shipwright/main/scripts/install-remote.sh | bash

npm (global)

npm install -g shipwright-cli

Verify

shipwright doctor

Quick Start

# One-command setup
shipwright init

# See what's running
shipwright status

# Process a GitHub issue end-to-end
shipwright pipeline start --issue 42

# Run daemon 24/7 with agent orchestration
shipwright daemon start --detach

# See live agent activity
shipwright activity

# Spin up agent team for manual work
shipwright session my-feature -t feature-dev

# View DORA metrics and pipeline vitals
shipwright dora

# Continuous build loop with test validation
shipwright loop "Build auth module" --test-cmd "npm test"

# Multi-repo operations
shipwright fleet start
shipwright fix "upgrade deps" --repos ~/a,~/b,~/c

# Release automation
shipwright version bump 2.4.0
shipwright changelog generate

Features

18 Autonomous Agents

Wave 1 (Organizational):

• Swarm Manager — Orchestrates dynamic agent teams with specialization roles
• Autonomous PM — Team leadership, task scheduling, roadmap execution
• Knowledge Guild — Cross-team learning, pattern capture, mentorship
• Recruitment System — Talent acquisition and team composition
• Standup Automaton — Daily standups, progress tracking, blocker detection

Wave 2 (Operational Backbone):

• Quality Oversight — Intelligent audits, zero-defect gates, completeness verification
• Strategic Agent — Long-term planning, goal decomposition, roadmap intelligence
• Code Reviewer — Architecture analysis, clean code standards, best practices
• Security Auditor — Vulnerability detection, threat modeling, compliance
• Test Generator — Coverage analysis, scenario discovery, regression prevention
• Incident Commander — Autonomous triage, root cause analysis, resolution
• Dependency Manager — Semantic versioning, update orchestration, compatibility checking
• Release Manager — Release planning, changelog generation, deployment orchestration
• Adaptive Tuner — DORA metrics analysis, self-optimization, performance tuning
• Strategic Intelligence — Predictive analysis, trend detection, proactive recommendations

Plus 10+ specialized agents for observability, UX, documentation, and more.

12-Stage Delivery Pipeline

intake → plan → design → build → test → review → compound_quality → pr → merge → deploy → validate → monitor

Each stage is configurable with quality gates that auto-proceed or pause for approval. 8 pipeline templates:

Intelligence Layer

7 modules that make the pipeline smarter over time. Enabled by default: intelligence is on when Claude CLI is available, with optimization and prediction active out of the box. Set intelligence.enabled=false to disable. All modules degrade gracefully.

Adaptive everything: thresholds learn from history, model routing uses SPRT evidence-based switching, poll intervals adjust to queue depth, memory timescales tune based on fix effectiveness.

GitHub Deep Integration

Native GitHub API integration enriches every intelligence module:

Decision Engine

The autonomous decision engine (config/policy.json → decision section) handles routine operational decisions with outcome learning. Decisions are tiered by risk, with low-risk actions auto-approved and higher tiers escalated. The engine learns from outcomes to improve future decisions.

Context Engineering

Intelligent context window management for pipeline agents:

• Budget-aware trimming — Configurable character budgets for prompt composition (context_budget_chars)
• Section-level trimming — Independent limits for memory, git history, hotspot files, and test output
• Context efficiency metrics — Tracks budget utilization and trim ratios per iteration
• Self-tuning — The self-optimization loop analyzes context efficiency events and recommends budget adjustments

Autonomous Daemon

shipwright daemon start --detach

Watches GitHub for labeled issues and processes them 24/7:

• Auto-scaling: Adjusts worker count based on CPU, memory, budget, and queue depth
• Priority lanes: Reserve a worker slot for urgent/hotfix issues
• Retry with escalation: Failed builds retry with template escalation (fast → standard → full)
• Patrol mode: Proactively scans for security issues, stale deps, dead code, coverage gaps
• Self-optimization: Tunes its own config based on DORA metrics over time

Fleet Operations

shipwright fleet start

Orchestrate daemons across multiple repositories with a shared worker pool. Workers rebalance based on queue depth, issue complexity, and repo priority.

Persistent Memory

The pipeline learns from every run:

• Failure patterns: Captured and injected into future builds so agents don't repeat mistakes
• Fix effectiveness: Tracks which fixes actually resolved issues
• Prediction validation: Compares predicted risk against actual outcomes, auto-adjusts thresholds
• False-alarm tracking: Reduces noise by learning which anomalies are real

Cost Intelligence

shipwright cost show

Per-pipeline cost tracking with model pricing, budget enforcement, and ROI analysis. Adaptive model routing picks the cheapest model that meets quality targets.

Real-Time Dashboard

shipwright dashboard start

Web dashboard with live pipeline progress, GitHub context (security alerts, contributors, deployments), DORA metrics, cost tracking, and context efficiency metrics. WebSocket-powered, updates in real-time.

Webhook Receiver

shipwright webhook listen

Instant issue processing via GitHub webhooks instead of polling. Register webhook with shipwright webhook register, receive events in real-time, process issues with zero-lag.

PR Lifecycle Automation

shipwright pr review <pr#>
shipwright pr merge <pr#>
shipwright pr cleanup

Fully automated PR management: review based on predictive risk and coverage, intelligent auto-merge when gates pass, cleanup stale branches. Reduces manual PR overhead by 90%.

Fleet Auto-Discovery

shipwright fleet discover --org myorg

Scan a GitHub organization and auto-populate fleet config with all repos matching criteria (language, archived status, team ownership). One command instead of manual registry building.

SQLite Persistence

ACID-safe state management replacing JSON files. Replaces volatile .claude/pipeline-artifacts/ with reliable database schema. Atomic transactions ensure no partial states, crash recovery automatic.

Issue Decomposition

shipwright decompose analyze 42
shipwright decompose decompose 42

AI-powered issue analysis: analyze scores complexity; decompose creates child issues with inherited labels/assignees and a dependency graph.

Linux systemd Support

Cross-platform process supervision. Use systemd on Linux instead of tmux, same daemon commands:

shipwright launchd install  # macOS launchd
# systemd service auto-generated on Linux

Context Engine

shipwright context gather

Rich context injection for pipeline stages. Pulls together: contributor history, file hotspots, architecture rules, related issues, failure patterns. Injected automatically at each stage for smarter decisions.

Commands

Over 100 commands. Key workflows:

# Autonomous delivery
shipwright pipeline start --issue 42
shipwright daemon start --detach

# Agent teams
shipwright swarm status
shipwright recruit --roles builder,tester
shipwright standup
shipwright guild list

# Quality gates
shipwright code-review
shipwright security-audit
shipwright testgen
shipwright quality validate

# Observability
shipwright vitals
shipwright dora
shipwright stream
shipwright activity

# Multi-repo operations
shipwright fleet start
shipwright fix "feat: add auth" --repos ~/a,~/b,~/c
shipwright fleet-viz

# Release automation
shipwright version bump 2.4.0
shipwright changelog generate
shipwright deploys list

# Setup & maintenance
shipwright init
shipwright prep
shipwright doctor
shipwright upgrade --apply

# See all commands
shipwright --help

See .claude/CLAUDE.md for the complete 100+ command reference organized by workflow. Full documentation: https://sethdford.github.io/shipwright.

Pipeline Templates for Teams

24 team templates covering the full SDLC:

shipwright templates list

Configuration

Prerequisites

Architecture

100+ bash scripts (~100K lines), 125 shell test suites + 16 dashboard test files (141 total), plus E2E system test proving full daemon→pipeline→loop→PR flow. Dashboard at 98% coverage. Bash 3.2 compatible — runs on macOS and Linux out of the box.

Core Layers:

Pipeline Layer
  sw-pipeline.sh              # 12-stage delivery orchestration
  sw-daemon.sh                # Autonomous GitHub issue watcher
  sw-loop.sh                  # Continuous multi-iteration build loop

Agent Layer (18 agents)
  sw-swarm.sh                 # Dynamic agent team orchestration
  sw-pm.sh                    # Autonomous PM coordination
  sw-recruit.sh               # Agent recruitment system
  sw-standup.sh               # Daily team standups
  sw-guild.sh                 # Knowledge guilds
  sw-oversight.sh             # Quality oversight board
  sw-strategic.sh             # Strategic intelligence
  sw-scale.sh                 # Dynamic team scaling
  ... 10 more agent scripts

Intelligence Layer
  sw-intelligence.sh          # AI analysis engine
  sw-predictive.sh            # Risk scoring + anomaly detection
  sw-adaptive.sh              # Data-driven pipeline tuning
  sw-security-audit.sh        # Security analysis
  sw-code-review.sh           # Code quality analysis
  sw-testgen.sh               # Test generation
  sw-architecture.sh          # Architecture enforcement

Operational Layer
  sw-fleet.sh                 # Multi-repo orchestration
  sw-ci.sh                    # CI/CD orchestration
  sw-webhook.sh               # GitHub webhooks
  sw-incident.sh              # Incident response
  sw-release-manager.sh       # Release automation
  ... 20+ operational scripts

Observability Layer
  sw-vitals.sh                # Pipeline health scoring
  sw-dora.sh                  # DORA metrics dashboard
  sw-activity.sh              # Live activity streams
  sw-replay.sh                # Pipeline playback
  sw-trace.sh                 # E2E traceability
  sw-otel.sh                  # OpenTelemetry integration
  ... observability services

Infrastructure
  sw-github-graphql.sh        # GitHub GraphQL API client
  sw-github-checks.sh         # Native GitHub check runs
  sw-github-deploy.sh         # Deployment tracking
  sw-memory.sh                # Persistent learning system
  sw-cost.sh                  # Cost intelligence
  sw-db.sh                    # SQLite persistence
  sw-eventbus.sh              # Async event bus

Tools & UX
  dashboard/server.ts         # Real-time dashboard
  sw-session.sh               # tmux agent sessions
  sw-status.sh                # Team dashboard
  sw-docs.sh                  # Documentation sync
  sw-tmux.sh                  # tmux health management

Contributing

Let Shipwright build it: Create an issue using the Shipwright template and label it shipwright. The autonomous pipeline will triage, plan, build, test, review, and create a PR.

Manual development: Fork, branch, then:

npm test    # 125 shell suites + 16 dashboard test files (141 total), E2E system test

License

MIT — Seth Ford, 2026.