Ship Changes

Run local CI checks, then create branch, commit, push, and PR in one workflow.

Follow every step in order. Stop and report if any step fails.

Step 1: Determine Issue Context

Check if $ARGUMENTS is provided:

• With issue (/ship 613 or /ship https://github.com/.../issues/613):

  gh issue view <number> --json title,body,labels

Use the issue title and labels to inform branch name, commit message, and PR description.

• Without issue (/ship):

Skip issue fetch. Derive context entirely from the changed files and git diff. The user will be asked to confirm the commit message and PR title before proceeding.

Step 2: Check Working Tree

git status
git diff --stat

If there are no changes to ship, stop and inform the user.

Step 3: Detect Project Structure

Detect whether the project is a monorepo or single-repo by checking for configuration:

Option A: Configured via codingbuddy.config.json

If codingbuddy.config.json exists and contains custom.ship, use it:

// codingbuddy.config.json
{
  "custom": {
    "ship": {
      "packageManager": "yarn",        // "yarn" | "npm" | "pnpm" | "bun"
      "structure": "monorepo",          // "monorepo" | "single"
      "workspaces": [
        {
          "name": "my-app",
          "paths": ["apps/my-app/**"],
          "checks": ["lint", "format:check", "typecheck", "test:coverage", "build"]
        },
        {
          "name": "my-lib",
          "paths": ["packages/my-lib/**"],
          "checks": ["lint", "typecheck", "test"]
        }
      ],
      "globalChecks": [
        {
          "name": "schema-validation",
          "command": "npx ajv-cli validate -s schema.json -d 'data/*.json'"
        },
        {
          "name": "markdown-lint",
          "command": "npx markdownlint-cli2 '**/*.md'"
        }
      ],
      "skipPaths": ["docs/**", "*.md", ".github/**"]
    }
  }
}

Option B: Auto-detection (no config)

If no custom.ship config exists, auto-detect:

1. Package manager: Check for lock files in order: bun.lock → pnpm-lock.yaml → yarn.lock → package-lock.json. Default to npm.
2. Structure: Check package.json for workspaces field. If present → monorepo; otherwise → single-repo.
3. Workspaces (monorepo): Parse workspaces from package.json, resolve glob patterns against git diff --name-only to find affected workspaces.
4. Checks (auto): Run standard checks for each affected workspace:

   <pm> [workspace <name>] lint
   <pm> [workspace <name>] typecheck
   <pm> [workspace <name>] test
   <pm> [workspace <name>] build

Where <pm> is the detected package manager and workspace <name> is included only for monorepos.

Step 4: Classify Changed Files

Run git diff --name-only (include both staged and unstaged) and classify into workspaces.

Monorepo: Match changed file paths against workspace paths patterns to find affected workspaces.

Single-repo: All changes belong to the single workspace.

If changed files match only skipPaths (or don't match any workspace in auto-detect), skip CI checks entirely and proceed to Step 6.

Step 5: Run Local CI Checks

Workspace checks

Run checks only for affected workspaces. Execute checks sequentially within each workspace. Stop at first failure.

Configured (from custom.ship.workspaces):

# For each affected workspace, run each check:
<pm> workspace <workspace-name> <check>

Auto-detected:

# Monorepo — run for each affected workspace:
<pm> workspace <workspace-name> lint
<pm> workspace <workspace-name> typecheck
<pm> workspace <workspace-name> test
<pm> workspace <workspace-name> build

# Single-repo — run at project root:
<pm> run lint
<pm> run typecheck
<pm> run test
<pm> run build

Skip any script that does not exist in the workspace's package.json — check with <pm> run --json or by reading package.json scripts.

Global checks

If custom.ship.globalChecks is configured, run each global check command after workspace checks pass:

<command>   # executed from project root

Security check (ALL workspaces)

Security audit must run across ALL workspaces, not just affected ones:

# Monorepo — run for ALL workspaces (not just affected):
<pm> audit
# Or for npm:
npm audit --workspaces

Why: A vulnerability in an unaffected workspace still ships with the project. Security scanning must be comprehensive.

CI workflow self-inclusion check

When modifying CI workflow files (e.g., .github/workflows/*.yml), verify the workflow's on.push.paths or on.pull_request.paths filter includes the workflow file itself:

# ✅ Correct — workflow file is included in its own paths filter
on:
  push:
    paths:
      - 'src/**'
      - '.github/workflows/ci.yml'  # Self-included

# ❌ Wrong — workflow changes won't trigger the workflow
on:
  push:
    paths:
      - 'src/**'
      # Missing: .github/workflows/ci.yml

Why: If a workflow file is not in its own paths filter, changes to the workflow itself won't trigger CI, making it impossible to validate workflow changes before merging.

If ANY check fails, stop and report the failure. Do NOT proceed to shipping.

Step 6: Check Commit Convention

git log --oneline -10

Identify the commit message convention from recent history. Common conventions:

• type(scope): description (Conventional Commits)
• type: description
• Free-form

Step 7: Create Branch and Commit

Branch naming

• With issue: <type>/<short-description>-<issue-number> (e.g., feat/add-auth-613)
• Without issue: <type>/<short-description> (e.g., fix/login-redirect)

Commit

git checkout -b <branch-name>

# Stage relevant files (never use git add -A)
git add <specific-files>

# Exclude task artifacts from staging
git reset HEAD RESULT.json TASK.md 2>/dev/null || true

# Commit with convention — use HEREDOC for message
git commit -m "$(cat <<'EOF'
type(scope): concise description

- Detail 1
- Detail 2

Closes #<issue-number>   ← only if issue provided
EOF
)"

Rules:

• Write commit message in English
• Do NOT include author information
• Follow the detected convention from Step 6
• Use specific file paths in git add (never git add -A or git add .)
• Only include Closes #<number> if an issue was provided

Step 8: Push and Create PR

git push -u origin <branch-name>

Create PR using gh pr create:

With issue

gh pr create --title "<type>(scope): description" --label "<labels>" --body "$(cat <<'EOF'
## Summary
<bullet points summarizing changes>

## Test plan
<verification steps>

Closes #<issue-number>
EOF
)"

• Labels: detect from issue labels, add relevant ones

Without issue

gh pr create --title "<type>(scope): description" --label "<labels>" --body "$(cat <<'EOF'
## Summary
<bullet points summarizing changes>

## Test plan
<verification steps>
EOF
)"

• Labels: infer from change type (e.g., enhancement for feat, bug for fix)

PR Rules:

• Title: under 70 characters, English, follows commit convention
• Body: English, include Summary + Test plan sections
• Do NOT include author information

Step 9: Report Result

Print the PR URL and a summary of:

• Which CI checks were run and passed (or "skipped — no matching workspace")
• Branch name
• Commit hash
• PR URL
• Linked issue (or "none")