shipsmith

v1.2.1

Published

a month ago

AI-orchestrated SDLC engine — run DAG workflows that take software from idea to ship

0High
0Medium
0Low

ngocsangairvds

shipsmith sdlc ai-agent workflow dag orchestration claude

Shipsmith

DAG-based workflow engine for AI coding agents. Define multi-step workflows in YAML, execute them with AI providers, and monitor runs in realtime through a web dashboard.

New package, not an upgrade. Shipsmith 1.0.0 is a new package — formerly published under a different name. This is the first release under the shipsmith name, so there is no automatic upgrade path from a prior install. If your project has an old .vsaf/ directory, it is no longer read; delete it and run shipsmith install <pack> fresh (e.g. shipsmith install sdlc). Previous run history and conversations are not carried over. See CHANGELOG.md.

What It Does

Shipsmith orchestrates complex AI workflows as directed acyclic graphs (DAGs). Each node in a DAG can be a prompt (sent to an AI provider), a bash command, or a reusable command template. Nodes declare dependencies, conditional execution rules, and context isolation — Shipsmith handles the rest.

shipsmith run fix-issue --args "fix #42"

extract-issue-number ✓  1.2s
fetch-issue          ✓  0.8s
classify             ✓  2.1s
investigate          ●  running...
plan                 ⊘  skipped
bridge-artifacts     ○  pending
implement            ○  pending
validate             ○  pending

Features

YAML workflow definitions — declarative DAGs with prompt, bash, and command node types
Dependency-based execution — wave-based parallel scheduling, conditional branching, trigger rules
Variable resolution — reference outputs from upstream nodes ($classify.output.issue_type)
Workspace isolation — each run executes in an ephemeral temp directory, changes applied on success
Run persistence — run state saved to JSON after each node, supports resume on failure
Provider-agnostic — pluggable AI provider adapters (Claude Code adapter included)
Web dashboard — Angular SPA with workflow management and realtime SSE monitoring
REST API — Fastify server for programmatic access to workflows and runs
MCP server — Model Context Protocol integration for Claude Code
Skill pack system — no packs ship built in; shipsmith install <pack> fetches one from GitHub by tag (e.g. sdlc, vds-skill), or shipsmith pack link <path> uses a local checkout for pack development
AJV validation — JSON Schema validation for workflow definitions
Cycle detection — DAG cycle detection prevents infinite loops
Error recovery — configurable retry backoff strategies for failed nodes

Installation

Supported Platforms

Every release is verified by the Install Matrix CI — build, test suite, and a global-install smoke test (shipsmith init/doctor/list) on each platform:

| Platform | Versions | CI coverage | |---|---|---| | Ubuntu | 22.04, 24.04 | ubuntu-22.04, ubuntu-24.04 runners | | Windows | 10, 11 | windows-2022, windows-2025 runners (Server builds share the Windows 10/11 kernel) | | macOS | 13+ | macos-latest runner | | Node.js | 20, 22, 24 | all three, on every OS above |

[x] Ubuntu 22.04 / 24.04
[x] Windows 10 / 11 (Git Bash recommended for bash workflow nodes; cmd.exe works for simple commands)
[x] macOS 13+
[x] Node.js 20 / 22 / 24

Prerequisites

| Requirement | Version | Check | |---|---|---| | Node.js | >= 20.0.0 | node -v | | Bun | >= 1.3.0 | bun --version | | npm | >= 9.0.0 | npm -v | | Python | >= 3.10 | python --version | | git | any | git --version | | Claude Code CLI | latest | claude --version | | GitHub CLI (optional) | any | gh --version |

Claude Code CLI is required for prompt and command nodes. GitHub CLI is required only for workflows that interact with GitHub (e.g., fix-issue uses gh issue view); on Windows install it with winget install GitHub.cli or the MSI from github.com/cli/cli/releases. Python ≥ 3.10 is required by the sdlc pack (its own install.sh uses pipx for graphify + markitdown); on Windows that pack’s install.ps1 fetches the Visual C++ Redistributable from Microsoft when missing. The engine itself installs nothing — it runs the pack’s script after you confirm it. Run shipsmith doctor any time to see which prerequisites are present.

Bun is required to run shipsmith (the CLI executes under Bun). npm install -g shipsmith auto-installs Bun via the official bun.sh installer when it is missing — the install is announced, best-effort (never fails your npm install), and skipped in CI. Opt out with SHIPSMITH_SKIP_BUN_INSTALL=1 and install Bun yourself. After an auto-install, open a new terminal so ~/.bun/bin is on your PATH.

Option 1: Global Install (Recommended)

npm install -g shipsmith
shipsmith --version

Option 2: Project-Local Install

npm install -D shipsmith
npx shipsmith --version

Option 3: Install from Source

git clone https://github.com/ngocsangairvds-tech/shipsmith.git
cd shipsmith
npm install && npm run build
npm link
shipsmith --version

Quick Start

# Initialize in your project
cd /path/to/your/project
shipsmith init

# Check environment
shipsmith doctor

# List available workflows
shipsmith list

# Run a workflow
shipsmith run fix-issue --args "fix #42"

# Start the web dashboard
shipsmith serve --port 3000 --open

shipsmith init creates the .shipsmith/ directory:

.shipsmith/
├── config.yaml          ← Project configuration
├── workflows/           ← Workflow definitions (3 built-in)
│   ├── fix-issue.yaml
│   ├── idea-to-pr.yaml
│   └── code-review.yaml
├── commands/            ← Reusable prompt templates (10 built-in)
│   ├── investigate-issue.md
│   └── ... (9 more)
└── storage/             ← Run state persistence (add to .gitignore)

CLI Commands

| Command | Description | |---|---| | shipsmith init | Initialize .shipsmith/ directory with config and default workflows | | shipsmith run <workflow> | Execute a workflow by name | | shipsmith run <workflow> --resume <runId> | Resume an interrupted run | | shipsmith list | List available workflows | | shipsmith status | Show recent run statuses | | shipsmith runs | List workflow runs (alias of status) | | shipsmith chat "<message>" | Send a message to a conversation; a paused run in it resumes with the message as gate feedback (approve/reject keywords, anything else is revision feedback for looped gates) | | shipsmith abandon <runId> | Mark a run cancelled without deleting its data | | shipsmith isolation list | List .shipsmith/worktrees/ entries with their run status | | shipsmith isolation cleanup [--merged] [--dry-run] | Remove worktrees of terminal/orphaned runs; --merged also reclaims paused runs whose branch is merged (never removes executing runs) | | shipsmith validate workflows [name] | Validate workflow YAML: schema, node references, command file existence | | shipsmith doctor | Check environment and dependencies | | shipsmith serve | Start API server and web dashboard | | shipsmith mcp | Start MCP server for Claude Code integration | | shipsmith install <pack> | Install a skill pack (e.g. shipsmith install sdlc) — downloads from GitHub by tag unless linked or cached | | shipsmith pack | Manage pack dev-links and the local pack cache: list, link <path>, unlink <pack>, update [pack], clean | | shipsmith skill | Manage skills: add, list, info, remove, init | | shipsmith ai | Manage model tiers and aliases: tier set\|list\|unset, alias set\|list\|unset | | shipsmith workflow | Community marketplace: search [query], install <slug> | | shipsmith telemetry | Anonymous usage telemetry: status, reset |

`shipsmith serve`

shipsmith serve [--port 3000] [--open]

Starts a Fastify server exposing a REST API and the Angular dashboard.

`shipsmith mcp`

Starts a Model Context Protocol (MCP) server that exposes Shipsmith workflows and skills to Claude Code. Configure in .mcp.json for automatic integration.

`shipsmith install`

The engine ships with no packs built in. shipsmith install <pack> resolves the pack in this order — a dev link (shipsmith pack link) wins, then a matching cached version, then a fresh download from GitHub, by tag (<owner>/shipsmith-<pack>, e.g. sdlc → ngocsangairvds-tech/shipsmith-sdlc) — and deploys its skills/workflows to .shipsmith/:

shipsmith install sdlc           # Downloads the latest tag from GitHub (or reuses a link/cache); pick IDEs (claude/cursor/codex/antigravity) to add command proxies
shipsmith install [email protected]    # Pin an exact tag

The resolved tag is recorded in .shipsmith/config.json (packs: { sdlc: "v1.2.0" }) so a bare re-run reuses the same pin instead of silently drifting.

Prerequisites belong to the pack, not the engine. A pack may ship its own install.sh / install.ps1 (the sdlc pack installs gitnexus, graphify, markitdown, and — on Windows — the Visual C++ Redistributable). Before running one, Shipsmith prints the script path and its sha256 and asks for confirmation; accepting remembers that hash, and if the script later changes you are asked again. A pack resolved through shipsmith pack link skips the prompt (you own that checkout) but still announces what it runs.

shipsmith install sdlc --yes     # Skip the trust prompt (same as SHIPSMITH_CI=1) — CI should also pin an explicit @tag
shipsmith install sdlc --setup   # Re-run only the prerequisite script for an already-installed pack

If the script fails, the pack's content is still deployed — fix the tool and re-run with --setup. On Windows, a pack with no install.ps1 deploys its content and warns instead of failing.

`shipsmith pack` — dev links and the local pack cache

shipsmith pack link ../shipsmith-sdlc   # Use a local checkout instead of GitHub (pack development)
shipsmith pack list                     # Show every linked and cached pack
shipsmith pack unlink sdlc              # Remove the dev link (cached/downloaded versions are untouched)
shipsmith pack update [pack]            # Refresh one pack (or every cached pack) from GitHub
shipsmith pack clean                    # Remove all cached pack versions (dev links are preserved)

Packs and cache live under ~/.shipsmith/packs/ (override with SHIPSMITH_HOME): a dev link is a symlink packs/<name> -> /absolute/path/to/checkout; a cached download sits at packs/<name>@<version>/.

`shipsmith skill`

shipsmith skill list              # List installed skills
shipsmith skill info <name>       # Show skill details
shipsmith skill add <path>        # Add a skill from file
shipsmith skill remove <name>     # Remove a skill
shipsmith skill init              # Scaffold a new skill template

`shipsmith ai` — model tiers and aliases

shipsmith ai tier set small claude haiku       # Bind a tier to provider/model
shipsmith ai tier list                         # Show tiers (configured + built-in)
shipsmith ai tier unset small                  # Remove a tier binding
shipsmith ai alias set @cheap openai-api gpt-4o-mini
shipsmith ai alias list
shipsmith ai alias unset @cheap

Bindings persist in ~/.shipsmith/config.yaml under tiers: and aliases:. Workflow nodes (and shipsmith run --model) may then use model: small|medium|large or model: "@alias" — resolved to a concrete provider+model at run time, with a tier fallback chain (large → medium → small) and built-in claude defaults (haiku/sonnet/opus).

`shipsmith workflow` — community marketplace

shipsmith workflow search review              # Search the registry index
shipsmith workflow install review-pr          # Install into .shipsmith/workflows/community/
shipsmith run community/review-pr             # Run an installed workflow

The registry is a git repo of YAML workflows described by a JSON index. Override the index URL with --registry <url>, SHIPSMITH_WORKFLOW_REGISTRY, or marketplace.index_url in ~/.shipsmith/config.yaml. Downloads are validated against the workflow schema before being installed.

`shipsmith telemetry`

shipsmith telemetry status   # enabled/disabled + reason + install id
shipsmith telemetry reset    # rotate the anonymous install id

Anonymous, opt-out usage telemetry: workflow name (bundled workflows only — user workflows report as custom), node type counts, provider/model, and run outcome. Never prompts, code, arguments, or file paths. Disabled when DO_NOT_TRACK=1, SHIPSMITH_TELEMETRY_DISABLED=1, in CI, or when no endpoint is configured (telemetry.endpoint in ~/.shipsmith/config.yaml or SHIPSMITH_TELEMETRY_ENDPOINT). The install id lives in ~/.shipsmith/telemetry-id.

Writing Workflows

Basic Workflow

Create .shipsmith/workflows/my-workflow.yaml:

name: my-workflow
description: A custom workflow

provider: claude
model: sonnet

nodes:
  - id: step1
    prompt: |
      Analyze this request: $ARGUMENTS
      Output a summary.

  - id: step2
    bash: |
      echo "Step 1 output was: $step1.output"
    depends_on: [step1]

  - id: step3
    prompt: |
      Based on: $step2.output
      Generate a final report.
    depends_on: [step2]

Run it:

shipsmith run my-workflow --args "analyze the auth module"

Node Types

| Type | Field | Description | |---|---|---| | prompt | prompt: | Send text to the AI provider | | bash | bash: | Run a shell command | | command | command: | Execute a reusable command template from .shipsmith/commands/ |

Node Fields

| Field | Required | Description | |---|---|---| | id | yes | Unique node identifier | | prompt / bash / command | yes | Node content (exactly one) | | depends_on | no | List of node IDs that must complete first | | when | no | Condition expression — node skipped if false | | trigger_rule | no | all_success (default) or one_success | | context | no | fresh (new AI session) or inherit (default) | | model | no | Override the workflow-level model — literal, tier (small/medium/large), or @alias | | provider | no | Override which provider runs this node (claude, mock, …) | | execution | no | engine (default, run headless) or agent — see Agent handoff | | allowed_tools | no | Restrict AI tool access (empty array = no tools) | | output_format | no | JSON Schema for structured output | | hooks | no | Quality gates on prompt/command nodes: pre:/post: lists of {run, name?, timeout?} bash commands — pre failure blocks dispatch, post failure fails the node |

Agent handoff (`execution: engine | agent`)

Document-style phases (analysis, writing a spec) run fine headless in the engine. Code-heavy phases that need interactive subagent dispatch belong in the agent orchestrator (Claude Code / Cursor). Mark such a node execution: agent and the engine pauses with a handoff gate instead of running it headless:

  - id: implement
    prompt: Implement the feature per the SRS.
    execution: agent      # engine pauses here

[shipsmith] Run paused (agent_handoff): implement — run this phase in your agent…
[shipsmith] When the agent has finished, continue with: shipsmith resume run-abc123

Run the phase in your agent, then shipsmith resume <runId> — the node is marked done and the DAG continues into the nodes that read the agent's on-disk output. This is the engine⇄agent swap: use the engine for the document phases and the agent for implement, or go fully headless with build-headless (a bounded, provider-agnostic TDD loop).

Variables

| Pattern | Description | Example | |---|---|---| | $ARGUMENTS | Args passed to shipsmith run --args | "fix #42" | | $node-id.output | Text output of a completed node | "bug" | | $node-id.output.field | Field from structured output | "enhancement" | | $ARTIFACTS_DIR | Shared directory for file passing | /tmp/shipsmith-run-abc/artifacts |

Conditional Branching

nodes:
  - id: classify
    prompt: |
      Classify this as 'bug' or 'feature': $ARGUMENTS
    output_format:
      type: object
      properties:
        type:
          type: string
          enum: [bug, feature]
      required: [type]

  - id: fix-bug
    prompt: Fix this bug: $ARGUMENTS
    depends_on: [classify]
    when: "$classify.output.type == 'bug'"

  - id: build-feature
    prompt: Implement this feature: $ARGUMENTS
    depends_on: [classify]
    when: "$classify.output.type == 'feature'"

  - id: finalize
    prompt: Wrap up the work.
    depends_on: [fix-bug, build-feature]
    trigger_rule: one_success  # Only need one branch to succeed

Using Commands (Reusable Prompts)

Create .shipsmith/commands/my-command.md:

---
description: A reusable prompt template
argument-hint: The task description
---

You are an expert engineer. Your task:

$ARGUMENTS

Previous analysis: $classify.output

Write your implementation to the codebase. Save notes to $ARTIFACTS_DIR/notes.md.

Reference it in a workflow:

  - id: implement
    command: my-command
    depends_on: [classify]
    context: fresh    # Start a new AI session
    model: opus       # Use a stronger model

Structured Output

Force JSON output from AI nodes:

  - id: analyze
    prompt: Analyze this code and rate its quality.
    output_format:
      type: object
      properties:
        score:
          type: string
          enum: ["A", "B", "C", "D", "F"]
        issues:
          type: string
      required: [score, issues]

  - id: report
    prompt: |
      The code scored: $analyze.output.score
      Issues: $analyze.output.issues
    depends_on: [analyze]

Passing Files Between Nodes

Nodes can share files via $ARTIFACTS_DIR:

nodes:
  - id: investigate
    prompt: |
      Investigate the issue. Write findings to $ARTIFACTS_DIR/investigation.md

  - id: plan
    bash: cat $ARTIFACTS_DIR/investigation.md
    depends_on: [investigate]

  - id: implement
    prompt: |
      Here is the investigation: $plan.output
      Now implement the fix.
    depends_on: [plan]

Resume Failed Runs

If a workflow fails mid-execution, resume from where it left off:

shipsmith status                                     # Find the run ID
shipsmith run fix-issue --resume run-a1b2c3d4e5f6    # Skip completed nodes

SDLC Skill Pack

shipsmith install sdlc installs the SDLC skill pack from GitHub by tag (shipsmith-sdlc) — skills organized into workflows for building features and fixing bugs with TDD discipline. It is not bundled with the engine; see "shipsmith install" above. For pack development, check out the shipsmith-sdlc pack repo alongside this one and run shipsmith pack link ../shipsmith-sdlc.

Headless / CI mode

The phases that normally wait for a human gate (PRD, SRS, Review) can run unattended. Set SHIPSMITH_CI=1 (or SHIPSMITH_AUTO_APPROVE=1) in the environment and those skills auto-write ## Gate: APPROVED (auto · SHIPSMITH_CI · rationale: …) with an audit rationale instead of blocking. Safety rule: Review never auto-approves while MUST-FIX issues remain — it returns to Implement regardless of the flag. Without the flag, gates require a human (default).

Skill dependencies

Most skills need only Claude Code. External tools are used opportunistically and the flow degrades gracefully when they're absent:

| Dependency | Required by | Optional / fallback | |---|---|---| | Claude Code CLI | all prompt/command skills | — (required) | | GitNexus (auto-installed) | onboard-code, prd, architecture, srs, review (impact/query/context) | needs VC++ runtime on Windows (auto-installed) | | graphify (auto-installed) | onboard-docs, feature-complete | skill still completes without the docs graph | | gh | ship (PR creation) | required only for GitHub workflows | | sonar-scanner | implement, review (quality gate) | optional — auto-detected; falls back to the quality-gate.md self-checklist | | docker | onboard-code (env probe) | optional | | Python ≥3.10 + pipx | shipsmith install sdlc (graphify, markitdown) | required for the install step |

Setup

# 1. Install the skill pack (downloads shipsmith-sdlc from GitHub, then runs its prerequisite script after you confirm)
shipsmith install sdlc

# 2. Initialize Shipsmith in your project
cd /path/to/your/project
shipsmith init

# 3. Inside Claude Code — bootstrap SDLC documentation layer
/sdlc-init

# 4. Onboard project knowledge
/sdlc-onboard-docs    # Build docs knowledge graph (graphify)
/sdlc-onboard-code    # Index code (GitNexus) + environment check

After setup, the project should have:

your-project/
├── .shipsmith/              ← Engine config, skills, workflows, storage
│   └── docs/              ← STATUS.md, KNOWLEDGE.md, features/
├── .mcp.json              ← Shipsmith + GitNexus MCP servers
├── CONTEXT.md             ← Shared domain language
├── .gitnexus/             ← Code index
└── graphify-out/          ← Docs knowledge graph

Workflows

Full Pipelines

| Workflow | Command | Description | |---|---|---| | master | /sdlc-master --args "feature description" | Full 9-phase feature pipeline (implement phase is agent-driven) | | master-headless | shipsmith run sdlc/master-headless --args "…" | Same pipeline, implement phase runs headless in the engine | | hotfix | /sdlc-hotfix --args "path/to/bug-report.md" | TDD-driven hotfix from bug report | | onboarding | /sdlc-onboarding | Docs + code knowledge indexing |

Sub-workflows (crash-safe, run independently)

| Workflow | Command | Phases | |---|---|---| | thinking | /sdlc-thinking | Discovery → PRD | | design | /sdlc-design | Architecture → SRS | | testcase | /sdlc-testcase | Test Design | | build | /sdlc-build | Implement → Test Gate (loop 3x) — agent-driven (subagent dispatch) | | build-headless | shipsmith run sdlc/build-headless | Implement headless: one test case per loop iteration → Test Gate | | qa | /sdlc-qa | Review → Feature Complete → Ship | | hotfix-tdd | /sdlc-hotfix-tdd | TDD RED → GREEN → Test Gate (loop 3x) |

Master Flow (New Feature)

9 phases, each produces artifacts on disk for session continuity:

/sdlc-master --args "Add OAuth2 authentication to REST API"

| Phase | Skill | Output | Description | |---|---|---|---| | 1 | discovery | 01-discovery.md | Scan system → grill user with questions → brainstorm | | 2 | prd | 02-prd.md | PRD via BMAD elicitation + adversarial review | | 3 | architecture | 03-adr.md | Grill constraints → architecture design + epics | | 4 | srs | 05-srs.md | Detailed SRS + edge cases + interface verification | | 5 | test-design | 06-testcases.md | Test cases from SRS (tests before code — TDD) | | 6 | implement | code changes | Subagent-driven TDD implementation | | 6b | test-gate | npm test | Automated test verification (loop 3x on fail) | | 7 | review | 08-review.md | Code review + quality gate + impact analysis | | 8 | feature-complete | KNOWLEDGE.md | Update shared knowledge before shipping | | 9 | ship | git commit + PR | Commit source code + create pull request |

Artifacts saved to .shipsmith/docs/features/{feature-name}/. Each phase checks prerequisites — if the session crashes, resume from the last completed phase.

Hotfix Flow (Bug Fix)

TDD-driven: receives a bug report, analyzes, writes failing test, fixes, reviews, ships.

/sdlc-hotfix --args "path/to/bug-report.md"

| Phase | Skill | Description | |---|---|---| | 1 | hotfix-analyze | Read bug report → GitNexus impact → root cause | | 2 | hotfix-prd | Lightweight PRD — fix requirements, acceptance criteria, scope | | 3 | hotfix-implement | TDD — RED → GREEN → REFACTOR, minimal fix | | 3b | test-gate | Full test suite — loop back to implement on fail (max 3x) | | 4 | hotfix-ship | Git commit + PR on hotfix branch |

hotfix-review is also available as a standalone skill for a quick minimality + test-quality check.

Artifacts saved to .shipsmith/docs/hotfixes/{bug-id}/.

Crash Recovery

Long sessions can crash (context overflow, network). Sub-workflows let you resume without restarting the full pipeline:

# Session 1: thinking phase
/sdlc-thinking --args "Add OAuth2"
# → crash during PRD → 01-discovery.md already saved

# Session 2: resume just the PRD skill
/sdlc-prd
# → PRD completed, 02-prd.md saved

# Session 3: continue with design
/sdlc-design

# Session 4: build
/sdlc-build

# Session 5: ship
/sdlc-qa

Each phase reads input from files on disk — no data is lost between sessions.

Individual Skills

Every SDLC phase can be invoked directly as a Claude skill:

/sdlc-init              # Setup
/sdlc-onboard-docs      # Index docs
/sdlc-onboard-code      # Index code
/sdlc-discovery         # Phase 1
/sdlc-prd               # Phase 2
/sdlc-architecture      # Phase 3
/sdlc-srs               # Phase 4
/sdlc-test-design       # Phase 5
/sdlc-implement         # Phase 6
/sdlc-review            # Phase 7
/sdlc-feature-complete  # Phase 8
/sdlc-ship              # Phase 9
/sdlc-health       # Health check
/sdlc-hotfix-analyze    # Hotfix Phase 1
/sdlc-hotfix-prd        # Hotfix Phase 2
/sdlc-hotfix-implement  # Hotfix Phase 3
/sdlc-hotfix-review     # Hotfix Phase 4
/sdlc-hotfix-ship       # Hotfix Phase 5

SDLC Skills (21)

| Skill | Purpose | |---|---| | setup | Install dependencies and configure environment | | init | Bootstrap .shipsmith/docs/, .mcp.json, CONTEXT.md | | onboard-docs | Docs scan → graphify → CONTEXT.md | | onboard-code | GitNexus index + Claude review + env check | | discovery | Grill questions → brainstorm + GitNexus | | prd | PRD with BMAD elicitation + adversarial review | | architecture | Grill constraints → architecture + epics | | srs | SRS + edge cases + GitNexus shape_check | | write-srs | Write feature-level SRS from the 12-section template | | validate-srs | Validate SRS — 8 dimensions, weighted scoring, GO/NO-GO | | test-design | Test design from SRS (TDD: tests before code) | | implement | Subagent-driven TDD + SonarQube rules | | review | Code review + quality gate + impact analysis | | feature-complete | Update CONTEXT.md, KNOWLEDGE.md, re-index | | ship | Git commit + PR via gh CLI | | sdlc-health | Health check — verify all prerequisites | | hotfix-analyze | Bug report → GitNexus + deep thinking → root cause | | hotfix-prd | Lightweight PRD — fix requirements + acceptance criteria | | hotfix-implement | TDD — RED → GREEN → REFACTOR, minimal fix | | hotfix-review | Quick review — minimality + test quality | | hotfix-ship | Commit + PR on hotfix branch |

Bundled BMAD Skills (17)

Used by discovery, prd, architecture, srs, test-design, and review phases:

| Skill | Purpose | |---|---| | bmad-advanced-elicitation | Push LLM to reconsider and deepen analysis | | bmad-brainstorming | Facilitate interactive brainstorming | | bmad-domain-research | Conduct domain and industry research | | bmad-prfaq | Working Backwards PRFAQ challenge | | bmad-create-prd | Create a PRD from scratch | | bmad-validate-prd | Validate a PRD against standards | | bmad-review-adversarial-general | Cynical review and challenge assumptions | | bmad-create-architecture | Create architecture solution design | | bmad-create-epics-and-stories | Break requirements into epics and stories | | bmad-check-implementation-readiness | Validate PRD, UX, Architecture completeness | | bmad-agent-analyst | Strategic business analyst | | bmad-review-edge-case-hunter | Walk every branching path for edge cases | | bmad-code-review | Review code changes adversarially | | bmad-party-mode | Orchestrate group discussion simulations | | bmad-qa-generate-e2e-tests | Generate end-to-end automated tests | | bmad-checkpoint-preview | LLM-assisted human-in-the-loop checkpoint | | bmad-correct-course | Manage significant changes during epic |

Bundled Mattpocock Lean Skills (5)

Lean alternative for bugfix and known-domain flows:

| Skill | Purpose | |---|---| | grill-me | Interview relentlessly to extract requirements | | diagnose | Disciplined diagnosis loop for bugs | | zoom-out | Step back and evaluate broader context | | tdd | Test-driven development with strict RED/GREEN | | improve-codebase-architecture | Find deepening opportunities in architecture |

Configuration

.shipsmith/config.yaml:

provider: claude          # AI provider (only 'claude' currently)
model: sonnet             # Default model: haiku, sonnet, opus

isolation:
  type: ephemeral         # Workspace strategy
  cleanup: after_success  # after_success | after_always | never
  exclude:                # Directories excluded from workspace copy
    - node_modules
    - .git
    - dist
    - build
    - .shipsmith/storage
  max_workspaces: 5

Cleanup policies:

after_success — keep workspace on failure for debugging
after_always — always delete
never — never delete (fills disk)

Add to .gitignore:

.shipsmith/storage/

REST API

All endpoints prefixed with /api. Start with shipsmith serve.

| Method | Endpoint | Description | |---|---|---| | GET | /api/health | Health check | | GET | /api/workflows | List workflows | | GET | /api/workflows/:name | Workflow detail (full DAG as JSON) | | POST | /api/runs | Start a run → 202 { runId } | | GET | /api/runs | List runs | | GET | /api/runs/:runId | Run detail (status + node results) | | GET | /api/runs/:runId/events | SSE stream (realtime events) |

POST /api/runs returns 202 Accepted immediately — the workflow runs async. Subscribe to SSE events for realtime progress.

SSE Events

event: node:start
data: {"nodeId":"classify","timestamp":"..."}

event: node:complete
data: {"nodeId":"classify","durationMs":2100,"output":"bug"}

event: node:skip
data: {"nodeId":"plan","reason":"condition not met"}

event: run:complete
data: {"success":true,"totalMs":45200}

Architecture

┌──────────────────────────────────────────────────────────┐
│                    Browser (Angular SPA)                  │
│   Dashboard ──── Workflow Detail ──── Run Execution      │
│    (HTTP)           (HTTP)           (EventSource)       │
└──────────┬───────────┬────────────────┬──────────────────┘
           ▼           ▼                ▼
┌──────────────────────────────────────────────────────────┐
│                  Fastify Server (packages/cli)            │
│   /api/health   /api/workflows/*   /api/runs/* + SSE     │
│                              ExecutionManager             │
│   @fastify/static ──→ Angular dist/ (SPA fallback)       │
└──────────────────────────┬───────────────────────────────┘
                           ▼
┌──────────────────────────────────────────────────────────┐
│                  Core Engine (packages/core)              │
│   DAG Parser → DAG Executor → Node Runner                │
│   Variable Resolver · Condition Evaluator                │
│   Workspace Manager · Run Store · Provider Registry      │
│   AJV Validation · Contract Checks · Cycle Detection     │
└──────────────────────────────────────────────────────────┘

Strict dependency direction: web → (HTTP) → cli → core. Published as a single npm package shipsmith.

| Package | Responsibility | |---|---| | packages/core | Engine library: parsing, execution, providers, isolation, persistence | | packages/cli | CLI commands + Fastify API server + MCP server | | packages/web | Angular SPA dashboard (private, not published separately) |

Design Decisions

| Decision | Choice | Why | |---|---|---| | DAG scheduling | Wave-based parallel scan | Simple, no topological sort, natural parallelism | | Workspace isolation | Copy project to temp dir | Prevents partial changes on failure, safe rollback | | Run persistence | JSON files, one per run | No database, human-readable, easy to debug | | API framework | Fastify 5 | TypeScript-first, fast, built-in inject() for testing | | Realtime | SSE (not WebSocket) | One-way sufficient, simpler protocol | | Frontend | Angular 19 standalone | Strong TypeScript integration, lazy-loaded routes | | AI adapter | Shell out to claude CLI | No SDK dependency, simple to test | | Schema validation | AJV | Industry standard JSON Schema | | MCP integration | Stdio-based MCP server | Native Claude Code protocol, zero network config | | Skill distribution | shipsmith install → .shipsmith/skills (canonical) + per-IDE command proxies | Skills stay in .shipsmith/; selected IDEs get thin command/skill proxies (.claude/commands, .agents/skills, …) that drive runs via the shipsmith MCP |

Tech Stack

| Layer | Technology | |---|---| | Language | TypeScript 6 (core/cli) · 5.7 (web) | | Runtime | Node.js >= 20 | | Build | tsc (project references) | | API Server | Fastify 5 | | Frontend | Angular 19 + Tailwind CSS 4 | | Realtime | Server-Sent Events (SSE) | | Testing | Vitest | | AI Provider | Claude Code (extensible) | | AI Integration | Model Context Protocol (MCP) | | Schema Validation | AJV |

Programmatic Usage

Use shipsmith as a library:

import { parseWorkflow, DAGExecutor, ProviderRegistry, ClaudeCodeAdapter } from 'shipsmith';
import { readFileSync } from 'fs';

// Parse workflow
const yaml = readFileSync('.shipsmith/workflows/fix-issue.yaml', 'utf-8');
const graph = parseWorkflow(yaml);

console.log(graph.name);           // "fix-issue"
console.log(graph.nodes.size);     // 10

// Execute with provider
const registry = new ProviderRegistry();
registry.register(new ClaudeCodeAdapter());
const provider = registry.get('claude');

const executor = new DAGExecutor(provider, workspacePath, projectPath, graph, {
  onNodeStart: (id) => console.log(`▶ ${id}`),
  onNodeComplete: (id, r) => console.log(`✓ ${id} (${r.durationMs}ms)`),
  onNodeSkip: (id, reason) => console.log(`⊘ ${id}: ${reason}`),
  onNodeFail: (id, err) => console.error(`✗ ${id}: ${err}`),
});

const result = await executor.execute('fix #42', artifactsPath);

Development

npm install          # Install dependencies
npm test             # Run tests
npm run test:watch   # Watch mode
npm run lint         # Type check
npm run build        # Build all packages

shipsmith/
├── packages/core/     ← Engine library
├── packages/cli/      ← CLI + API server + MCP
├── packages/web/      ← Angular dashboard
└── tests/             ← Vitest test suites (tests/fixtures/packs/demo/ — synthetic pack for engine tests)

Pack content (skills, workflows) lives in separate repos — shipsmith-sdlc, shipsmith-vds — not in this one. See "SDLC Skill Pack" above and shipsmith pack --help.

Troubleshooting

| Problem | Solution | |---|---| | shipsmith: command not found | npm install -g shipsmith or use npx shipsmith | | claude: command not found | Install Claude Code CLI | | gh: command not found | Install GitHub CLI: brew install gh or https://cli.github.com | | .shipsmith/ already exists | rm -rf .shipsmith/ then shipsmith init | | Workflow not found | Check shipsmith list. Ensure .shipsmith/workflows/xxx.yaml exists | | Command not found | Ensure .shipsmith/commands/xxx.md exists with correct frontmatter | | Run stuck / no progress | Check claude --print "hello" works. Check network | | shipsmith serve shows "Web UI not built" | Build Angular: cd packages/web && npx ng build | | Workspace disk full | Set cleanup: after_always in config.yaml or rm -rf /tmp/shipsmith-* |

License

MIT