candid-ship

Candid Ship

Orchestrate the full shipping workflow: review code via candid-loop, run install/build/tests, create a GitHub PR, optionally update an issue tracker and auto-merge. Aborts on any failure before PR creation.

candid-ship runs all configured steps by default — the user opts out with --skip-* flags. (Compare candid-fast-ship, which is opt-in.)

Workflow

Execute these steps in order. The mechanics for each step are defined in skills/candid-ship/WORKFLOW.md. This file specifies the skip semantics unique to candid-ship.

Step 1: Pre-Flight Checks

Run the pre-flight checks from WORKFLOW.md → "Pre-Flight Checks".

Step 2: Load Configuration

Read config per WORKFLOW.md → "Load Configuration", extracting these ship.* fields plus mergeTargetBranches:

buildCommand, testCommand, installCommand, targetBranch, autoMerge, additionalPrompt, postMergeCommand, issueTracker (full sub-tree).

When loading from project config, output: Using ship settings from project config. From user config: Using ship settings from user config.

Parse CLI Flags

Flag	Description	Default
--auto-merge	Enable auto-merge	from config
--no-auto-merge	Disable auto-merge	from config
--skip-review	Skip candid-loop step	false
--skip-install	Skip install step	false
--skip-build	Skip build command	false
--skip-tests	Skip test command	false
--dry-run	Show plan without executing	false

If both --auto-merge and --no-auto-merge are provided, --no-auto-merge wins.

After loading, run the targetBranch resolution and branch-state validation from WORKFLOW.md → "Resolve targetBranch" / "Validate Branch State".

Step 3: Display Plan

Calculate totalSteps = 1 (PR creation always runs) + number of optional steps that will run. An optional step counts when:

• review: --skip-review is not set
• install: --skip-install is not set AND installCommand is set
• build: --skip-build is not set AND buildCommand is set
• tests: --skip-tests is not set AND testCommand is set
• issueTracker: issueTracker.enabled is true
• autoMerge: autoMerge is true
• postMergeCommand: autoMerge is true AND postMergeCommand is set

Renumber the displayed step list to skip rows for any disabled optional steps.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Candid Ship Plan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Branch: [currentBranch] → [targetBranch]

Steps (numbers assigned dynamically — only running steps get a number):
  [N]. 🔍 Review code (candid-loop)           [or SKIP]
  [N]. 🛠️  Install: [installCommand]          [only if installCommand is set]
  [N]. 🔨 Build: [buildCommand]               [or SKIP — not configured]
  [N]. 🧪 Tests: [testCommand]                [or SKIP — not configured]
  [N]. 📋 Create pull request
  [N]. 🎯 Update issue tracker ([provider]): state="[state]"  [only if issueTracker.enabled]
  [N]. 🔀 Auto-merge: enabled                 [or disabled]
  [N]. 🚀 Post-merge: [postMergeCommand]      [only if postMergeCommand is set]

If additionalPrompt is set, append: Review context: "[additionalPrompt]".

If --dry-run: Output Dry run complete. No changes made. and exit.

Otherwise: Use AskUserQuestion: "Proceed with this shipping plan?" with options "Yes, ship it" / "No, cancel". On "No, cancel": exit with Ship cancelled.

Step 4: Run Review

Skip if --skip-review is set → Skipping review (--skip-review). Otherwise execute WORKFLOW.md → "Run Review (candid-loop)".

Step 5: Install Dependencies

Skip if --skip-install is set → Skipping install (--skip-install). Skip if installCommand is not configured → Skipping install (not configured). Otherwise execute WORKFLOW.md → "Install Dependencies".

Step 6: Run Build

Skip if --skip-build is set → Skipping build (--skip-build). Skip if buildCommand is not configured → Skipping build (not configured). Otherwise execute WORKFLOW.md → "Run Build".

Step 7: Run Tests

Skip if --skip-tests is set → Skipping tests (--skip-tests). Skip if testCommand is not configured → Skipping tests (not configured). Otherwise execute WORKFLOW.md → "Run Tests".

Step 8: Create Pull Request

Always runs. Execute WORKFLOW.md → "Create Pull Request".

Step 9: Update Issue Tracker

Execute WORKFLOW.md → "Update Issue Tracker". The skip conditions there map directly to ship's behavior. Notes:

• The default teamPrefixes (DIS, ENG, DISC) reflect one Linear workspace. Edit ship.issueTracker.teamPrefixes in .candid/config.json to match your workspace's team keys.
• The default prompt encodes four invariants (single-issue, single-field, idempotent, no fallback search). Custom prompts must preserve "single issue" and "no fallback search" or the pre-call check will refuse the call.

Step 10: Auto-Merge

Skip if autoMerge is false → Auto-merge: disabled (manual merge required). Otherwise execute WORKFLOW.md → "Auto-Merge".

Step 11: Post-Merge Command

Skip if postMergeCommand is not configured → Skipping post-merge command (not configured). Skip if autoMerge is false → Skipping post-merge command (auto-merge disabled). Skip if auto-merge failed in Step 10 → Skipping post-merge command (auto-merge failed). Otherwise execute WORKFLOW.md → "Post-Merge Command".

Step 12: Summary

Execute WORKFLOW.md → "Display Summary" with header Candid Ship Complete.

Configuration

Config File Schema

Add to .candid/config.json:

{
  "version": 1,
  "ship": {
    "buildCommand": "npm run build",
    "testCommand": "npm test",
    "installCommand": "pnpm install",
    "targetBranch": "stable",
    "autoMerge": false,
    "additionalPrompt": "Focus on security and ensure all API endpoints have auth middleware",
    "postMergeCommand": "curl -X POST https://deploy.example.com/trigger",
    "issueTracker": {
      "provider": "linear",
      "enabled": true,
      "teamPrefixes": ["DIS", "ENG", "DISC"],
      "state": "In Review"
    }
  }
}

Field Reference

For full type, default, and validation rules see skills/candid-review/CONFIG.md (the ship section). Highlights:

• buildCommand / testCommand / installCommand / additionalPrompt / postMergeCommand default to null — the corresponding step is skipped if not set.
• targetBranch defaults to first mergeTargetBranches entry, else "main".
• autoMerge defaults to false.
• issueTracker is opt-in (enabled: false by default). When enabled, provider: "linear" is the only supported value today; other values warn and skip. The default prompt is documented in CONFIG.md and codifies the four safety invariants.

Note: issueTracker is an optional integration. When omitted, the issue-tracker step is skipped silently — the rest of the ship runs unchanged. To request support for another tracker (Asana, Jira, GitHub Issues, etc.), open an issue at https://github.com/ron-myers/candid/issues.

Examples

Minimal — just PR creation:

{ "ship": { "targetBranch": "main" } }

Full pipeline with install, auto-merge, and Linear:

{
  "ship": {
    "installCommand": "pnpm install",
    "buildCommand": "pnpm build",
    "testCommand": "pnpm test",
    "targetBranch": "stable",
    "autoMerge": true,
    "additionalPrompt": "Ensure error handling covers all async operations",
    "postMergeCommand": "curl -X POST https://deploy.example.com/trigger",
    "issueTracker": {
      "provider": "linear",
      "enabled": true,
      "teamPrefixes": ["DIS", "ENG"],
      "state": "In Review"
    }
  }
}

CLI Examples

# Ship with all defaults from config
/candid-ship

# Force auto-merge
/candid-ship --auto-merge

# Quick ship — skip review, just install/build/test/PR
/candid-ship --skip-review

# Skip install (deps already up to date)
/candid-ship --skip-install

# See what would happen without doing it
/candid-ship --dry-run

# PR only
/candid-ship --skip-review --skip-install --skip-build --skip-tests

Remember

The goal of candid-ship is to automate the entire shipping workflow so you can go from code to merged PR with one command.

Fail-fast principle: Any failure (review incomplete, install/build/test fail) aborts immediately with a clear message. Post-PR steps (issue tracker, auto-merge, post-merge) warn but never abort — the PR is already created and shouldn't be wasted.

Pre-flight checks: Always validate the environment before starting. It's frustrating to complete a full review + install + build + test cycle only to discover gh isn't installed.

Install before build: Setting installCommand (e.g. pnpm install, npm ci, poetry install) keeps build/test failures focused on real code issues rather than missing dependencies.