claude-code-workflow 7.2.27 → 7.2.29

package/.codex/skills/ship/orchestrator.md

@@ -0,0 +1,426 @@
+---
+name: ship
+description: Structured release pipeline with pre-flight checks, AI code review, version bump, changelog, and PR creation. Triggers on "ship", "release", "publish".
+agents: ship-operator
+phases: 5
+---
+
+# Ship
+
+Structured release pipeline that guides code from working branch to pull request through 5 gated phases: pre-flight checks, automated code review, version bump, changelog generation, and PR creation.
+
+## Architecture
+
+```
++--------------------------------------------------------------+
+|  ship Orchestrator                                           |
+|  -> Single ship-operator agent driven through 5 gated phases |
++------------------------------+-------------------------------+
+                               |
+           +-------------------+-------------------+
+           v                   v                   v
+    +------------+      +------------+      +------------+
+    |  Phase 1   |  --> |  Phase 2   |  --> |  Phase 3   |
+    | Pre-Flight |      | Code Review|      | Version    |
+    |  Checks    |      |            |      |   Bump     |
+    +------------+      +------------+      +------------+
+          v                   v                   v
+      Gate: ALL           Gate: No            Gate: Version
+      4 checks            critical            updated OK
+      pass                issues
+                               |
+           +-------------------+-------------------+
+           v                                       v
+    +------------+                          +------------+
+    |  Phase 4   |  ----------------------> |  Phase 5   |
+    | Changelog  |                          | PR Creation|
+    |  & Commit  |                          |            |
+    +------------+                          +------------+
+          v                                       v
+      Gate: Push                             Gate: PR
+      succeeded                              created
+```
+
+---
+
+## Agent Registry
+
+| Agent | task_name | Role File | Responsibility | Pattern | fork_context |
+|-------|-----------|-----------|----------------|---------|--------------|
+| ship-operator | ship-operator | ~/.codex/agents/ship-operator.md | Execute all 5 release phases sequentially, enforce gates | Deep Interaction (2.3) | false |
+
+> **COMPACT PROTECTION**: Agent files are execution documents. When context compression occurs and agent instructions are reduced to summaries, **you MUST immediately `Read` the corresponding agent.md to reload before continuing execution**.
+
+---
+
+## Fork Context Strategy
+
+| Agent | task_name | fork_context | fork_from | Rationale |
+|-------|-----------|--------------|-----------|-----------|
+| ship-operator | ship-operator | false | — | Starts fresh; all context provided in initial task message |
+
+**Fork Decision Rules**:
+
+| Condition | fork_context | Reason |
+|-----------|--------------|--------|
+| Pipeline stage with explicit input | false | Context in message, not history |
+| Agent is isolated utility | false | Clean context, focused task |
+| ship-operator | false | Self-contained release operator; no parent context needed |
+
+---
+
+## Subagent Registry
+
+Utility subagents callable by ship-operator (not separate pipeline stages):
+
+| Subagent | Agent File | Callable By | Purpose | Model |
+|----------|-----------|-------------|---------|-------|
+| inline-code-review | ~/.codex/agents/cli-explore-agent.md | ship-operator | AI code review of diff during Phase 2 | haiku |
+
+> Subagents are spawned by agents within their own execution context (Pattern 2.8), not by the orchestrator.
+
+---
+
+## Phase Execution
+
+### Phase 1: Pre-Flight Checks
+
+**Objective**: Validate that the repository is in a shippable state — confirm clean working tree, appropriate branch, passing tests, and successful build.
+
+**Input**:
+
+| Source | Description |
+|--------|-------------|
+| User trigger | "ship" / "release" / "publish" command |
+| Repository | Current git working directory |
+| Phase detail | ~/.codex/skills/ship/phases/01-preflight-checks.md |
+
+**Execution**:
+
+Spawn ship-operator with Phase 1 task. The operator reads the phase detail file then executes all four checks.
+
+```
+spawn_agent({
+  task_name: "ship-operator",
+  fork_context: false,
+  message: `## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS
+1. Read role definition: ~/.codex/agents/ship-operator.md (MUST read first)
+2. Read phase detail: ~/.codex/skills/ship/phases/01-preflight-checks.md
+
+---
+
+Goal: Execute Phase 1 Pre-Flight Checks for the release pipeline.
+
+Execute all four checks (git clean, branch validation, test suite, build verification).
+Output structured preflight-report JSON plus gate status.`
+})
+const phase1Result = wait_agent({ targets: ["ship-operator"], timeout_ms: 300000 })
+```
+
+**Gate Decision**:
+
+| Condition | Action |
+|-----------|--------|
+| All four checks pass (overall: "pass") | Fast-advance: assign Phase 2 task to ship-operator |
+| Any check fails (overall: "fail") | BLOCKED — report failure details, halt pipeline |
+| Branch is main/master (warn) | Ask user to confirm direct-to-main release before proceeding |
+| Timeout | assign_task "Finalize current work and output results", re-wait 120s |
+
+**Output**:
+
+| Artifact | Description |
+|----------|-------------|
+| preflight-report JSON | Pass/fail per check, blockers list |
+| Gate status | pass / fail / blocked |
+
+---
+
+### Phase 2: Code Review
+
+**Objective**: Detect merge base, generate diff, run AI-powered code review via inline subagent, assess risk, evaluate results.
+
+**Input**:
+
+| Source | Description |
+|--------|-------------|
+| Phase 1 result | Gate passed (overall: "pass") |
+| Repository | Git history, diff data |
+| Phase detail | ~/.codex/skills/ship/phases/02-code-review.md |
+
+**Execution**:
+
+Phase 2 is assigned to the already-running ship-operator via assign_task.
+
+```
+assign_task({
+  target: "ship-operator",
+  items: [{ type: "text", text: `## PHASE 2 TASK
+
+Read phase detail: ~/.codex/skills/ship/phases/02-code-review.md
+
+Execute Phase 2 Code Review:
+1. Detect merge base
+2. Generate diff summary
+3. Perform risk assessment
+4. Spawn inline-code-review subagent for AI analysis
+5. Evaluate review results and report gate status` }]
+})
+const phase2Result = wait_agent({ targets: ["ship-operator"], timeout_ms: 600000 })
+```
+
+**Gate Decision**:
+
+| Condition | Action |
+|-----------|--------|
+| No critical issues (overall: "pass") | Fast-advance: assign Phase 3 task to ship-operator |
+| Critical issues found (overall: "fail") | BLOCKED — report critical issues list, halt pipeline |
+| Warnings only (overall: "warn") | Fast-advance to Phase 3, flag DONE_WITH_CONCERNS |
+| Review subagent timeout/error | Ask user whether to proceed or retry; if proceed, flag warn |
+| Timeout on phase2Result | assign_task "Finalize current work", re-wait 120s |
+
+**Output**:
+
+| Artifact | Description |
+|----------|-------------|
+| Review summary JSON | Risk level, risk factors, AI review recommendation, issues |
+| Gate status | pass / fail / warn / blocked |
+
+---
+
+### Phase 3: Version Bump
+
+**Objective**: Detect version file, determine bump type from commits or user input, calculate new version, update version file, verify update.
+
+**Input**:
+
+| Source | Description |
+|--------|-------------|
+| Phase 2 result | Gate passed (no critical issues) |
+| Repository | package.json / pyproject.toml / VERSION |
+| Phase detail | ~/.codex/skills/ship/phases/03-version-bump.md |
+
+**Execution**:
+
+```
+assign_task({
+  target: "ship-operator",
+  items: [{ type: "text", text: `## PHASE 3 TASK
+
+Read phase detail: ~/.codex/skills/ship/phases/03-version-bump.md
+
+Execute Phase 3 Version Bump:
+1. Detect version file (package.json > pyproject.toml > VERSION)
+2. Determine bump type from commit messages (patch/minor/major)
+3. For major bumps: ask user to confirm before proceeding
+4. Calculate new version
+5. Update version file
+6. Verify update
+Output version change record JSON plus gate status.` }]
+})
+const phase3Result = wait_agent({ targets: ["ship-operator"], timeout_ms: 300000 })
+```
+
+**Gate Decision**:
+
+| Condition | Action |
+|-----------|--------|
+| Version file updated and verified (overall: "pass") | Fast-advance: assign Phase 4 task to ship-operator |
+| Version file not found | NEEDS_CONTEXT — ask user which file to use; halt until answered |
+| Version mismatch after update (overall: "fail") | BLOCKED — report mismatch, halt pipeline |
+| User declines major bump | BLOCKED — halt, user must re-trigger with explicit bump type |
+| Timeout | assign_task "Finalize current work", re-wait 120s |
+
+**Output**:
+
+| Artifact | Description |
+|----------|-------------|
+| Version change record JSON | version_file, previous_version, new_version, bump_type, bump_source |
+| Gate status | pass / fail / needs_context / blocked |
+
+---
+
+### Phase 4: Changelog & Commit
+
+**Objective**: Parse git log into grouped changelog entry, update CHANGELOG.md, create release commit, push branch to remote.
+
+**Input**:
+
+| Source | Description |
+|--------|-------------|
+| Phase 3 result | new_version, version_file, bump_type |
+| Repository | Git history since last tag |
+| Phase detail | ~/.codex/skills/ship/phases/04-changelog-commit.md |
+
+**Execution**:
+
+```
+assign_task({
+  target: "ship-operator",
+  items: [{ type: "text", text: `## PHASE 4 TASK
+
+Read phase detail: ~/.codex/skills/ship/phases/04-changelog-commit.md
+
+New version: <new_version>
+Version file: <version_file>
+
+Execute Phase 4 Changelog & Commit:
+1. Gather commits since last tag
+2. Group by conventional commit type
+3. Format changelog entry
+4. Update or create CHANGELOG.md
+5. Create release commit (chore: bump version to <new_version>)
+6. Push branch to remote
+Output commit record JSON plus gate status.` }]
+})
+const phase4Result = wait_agent({ targets: ["ship-operator"], timeout_ms: 300000 })
+```
+
+**Gate Decision**:
+
+| Condition | Action |
+|-----------|--------|
+| Push succeeded (overall: "pass") | Fast-advance: assign Phase 5 task to ship-operator |
+| Push rejected (non-fast-forward) | BLOCKED — report error, suggest `git pull --rebase` |
+| Permission denied | BLOCKED — report error, advise check remote access |
+| No remote configured | BLOCKED — report error, suggest `git remote add` |
+| Timeout | assign_task "Finalize current work", re-wait 120s |
+
+**Output**:
+
+| Artifact | Description |
+|----------|-------------|
+| Commit record JSON | changelog_entry, commit_sha, commit_message, pushed_to |
+| Gate status | pass / fail / blocked |
+
+---
+
+### Phase 5: PR Creation
+
+**Objective**: Extract issue references from commits, build PR title and body, create PR via `gh pr create`, capture PR URL.
+
+**Input**:
+
+| Source | Description |
+|--------|-------------|
+| Phase 4 result | commit_sha, new_version, previous_version, bump_type |
+| Phase 2 result | merge_base (for change_summary) |
+| Repository | Git history, remote |
+| Phase detail | ~/.codex/skills/ship/phases/05-pr-creation.md |
+
+**Execution**:
+
+```
+assign_task({
+  target: "ship-operator",
+  items: [{ type: "text", text: `## PHASE 5 TASK
+
+Read phase detail: ~/.codex/skills/ship/phases/05-pr-creation.md
+
+New version: <new_version>
+Previous version: <previous_version>
+Bump type: <bump_type>
+Merge base: <merge_base>
+Commit SHA: <commit_sha>
+
+Execute Phase 5 PR Creation:
+1. Extract issue references from commits
+2. Determine target branch
+3. Build PR title: "release: v<new_version>"
+4. Build PR body with all sections
+5. Create PR via gh pr create
+6. Capture and report PR URL
+Output PR creation record JSON plus final completion status.` }]
+})
+const phase5Result = wait_agent({ targets: ["ship-operator"], timeout_ms: 300000 })
+```
+
+**Gate Decision**:
+
+| Condition | Action |
+|-----------|--------|
+| PR created, URL returned (overall: "pass") | Pipeline complete — output DONE status |
+| PR created with review warnings | Pipeline complete — output DONE_WITH_CONCERNS |
+| gh CLI not available | BLOCKED — report error, advise `gh auth login` |
+| PR creation fails | BLOCKED — report error details, halt |
+| Timeout | assign_task "Finalize current work", re-wait 120s |
+
+**Output**:
+
+| Artifact | Description |
+|----------|-------------|
+| PR record JSON | pr_url, pr_title, target_branch, source_branch, linked_issues |
+| Final completion status | DONE / DONE_WITH_CONCERNS / BLOCKED |
+
+---
+
+## Lifecycle Management
+
+### Timeout Protocol
+
+| Phase | Default Timeout | On Timeout |
+|-------|-----------------|------------|
+| Phase 1: Pre-Flight | 300000 ms (5 min) | assign_task "Finalize current work", re-wait 120s |
+| Phase 2: Code Review | 600000 ms (10 min) | assign_task "Finalize current work", re-wait 120s |
+| Phase 3: Version Bump | 300000 ms (5 min) | assign_task "Finalize current work", re-wait 120s |
+| Phase 4: Changelog & Commit | 300000 ms (5 min) | assign_task "Finalize current work", re-wait 120s |
+| Phase 5: PR Creation | 300000 ms (5 min) | assign_task "Finalize current work", re-wait 120s |
+
+### Cleanup Protocol
+
+After Phase 5 completes (or on any terminal BLOCKED halt), close ship-operator.
+
+```
+close_agent({ target: "ship-operator" })
+```
+
+### Agent Health Check
+
+```
+const remaining = list_agents({})
+if (remaining.length > 0) {
+  remaining.forEach(agent => close_agent({ target: agent.id }))
+}
+```
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Agent timeout (first) | assign_task with "Finalize current work and output results" + re-wait 120s |
+| Agent timeout (second) | Log error, close_agent({ target: "ship-operator" }), report partial results |
+| Gate fail — any phase | Log BLOCKED status with phase name and failure detail, close_agent, halt |
+| NEEDS_CONTEXT | Pause pipeline, surface question to user, resume with assign_task on answer |
+| send_message ignored | Escalate to assign_task |
+| Inline subagent timeout | ship-operator handles internally; continue with warn if review failed |
+| User cancellation | close_agent({ target: "ship-operator" }), report current pipeline state |
+| Fork from closed agent | Not applicable (single agent, no forking) |
+
+---
+
+## Output Format
+
+```
+## Summary
+- One-sentence completion status (DONE / DONE_WITH_CONCERNS / BLOCKED)
+
+## Results
+- Phase 1 Pre-Flight: pass/fail
+- Phase 2 Code Review: pass/warn/fail
+- Phase 3 Version Bump: <previous> -> <new> (<bump_type>)
+- Phase 4 Changelog & Commit: commit <sha> pushed to <remote/branch>
+- Phase 5 PR Creation: <pr_url>
+
+## Artifacts
+- CHANGELOG.md (updated)
+- <version_file> (version bumped to <new_version>)
+- Release commit: <sha>
+- PR: <pr_url>
+
+## Next Steps (Optional)
+1. Review and merge the PR
+2. Tag the release after merge
+```

package/.codex/skills/ship/phases/01-preflight-checks.md

@@ -0,0 +1,198 @@
+# Phase 1: Pre-Flight Checks
+
+> **COMPACT PROTECTION**: This is a core execution phase. If context compression has occurred and this file is only a summary, **MUST `Read` this file again before executing any Step**. Do not execute from memory.
+
+Validate that the repository is in a shippable state before proceeding with the release pipeline.
+
+## Objective
+
+- Confirm working tree is clean (no uncommitted changes)
+- Validate current branch is appropriate for release
+- Run test suite and confirm all tests pass
+- Verify build succeeds
+
+## Input
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| Repository working directory | Yes | Git repo with working tree |
+| package.json / pyproject.toml / Makefile | No | Used for test and build detection |
+
+## Execution Steps
+
+### Step 1: Git Clean Check
+
+Run `git status --porcelain` and evaluate output.
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| Output is empty | PASS — working tree is clean |
+| Output is non-empty | FAIL — working tree is dirty; report dirty files, suggest `git stash` or `git commit` |
+
+```bash
+git_status=$(git status --porcelain)
+if [ -n "$git_status" ]; then
+  echo "FAIL: Working tree is dirty"
+  echo "$git_status"
+  # Gate: BLOCKED — commit or stash changes first
+else
+  echo "PASS: Working tree is clean"
+fi
+```
+
+**Pass condition**: `git status --porcelain` produces empty output.
+**On failure**: Report dirty files and suggest `git stash` or `git commit`.
+
+---
+
+### Step 2: Branch Validation
+
+Run `git branch --show-current` and evaluate.
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| Branch is not main or master | PASS — proceed |
+| Branch is main or master | WARN — ask user to confirm direct-to-main/master release before proceeding |
+| User confirms direct release | PASS with warning noted |
+| User declines | BLOCKED — halt pipeline |
+
+```bash
+current_branch=$(git branch --show-current)
+if [ "$current_branch" = "main" ] || [ "$current_branch" = "master" ]; then
+  echo "WARN: Currently on $current_branch — direct push to main/master is risky"
+  # Ask user for confirmation before proceeding
+else
+  echo "PASS: On branch $current_branch"
+fi
+```
+
+**Pass condition**: Not on main/master, OR user explicitly confirms direct-to-main release.
+**On warning**: Ask user to confirm they intend to release from main/master directly.
+
+---
+
+### Step 3: Test Suite Execution
+
+Detect project type and run appropriate test command.
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| package.json with "test" script exists | Run `npm test` |
+| pytest available and tests/ or test/ directory exists | Run `pytest` |
+| pyproject.toml with pytest listed exists | Run `pytest` |
+| No test suite detected | WARN and continue (skip check) |
+| Test command exits code 0 | PASS |
+| Test command exits non-zero | FAIL — report test failures, halt pipeline |
+
+```bash
+# Detection priority:
+# 1. package.json with "test" script → npm test
+# 2. pytest available and tests exist → pytest
+# 3. No tests found → WARN and continue
+
+if [ -f "package.json" ] && grep -q '"test"' package.json; then
+  npm test
+elif command -v pytest &>/dev/null && [ -d "tests" -o -d "test" ]; then
+  pytest
+elif [ -f "pyproject.toml" ] && grep -q 'pytest' pyproject.toml; then
+  pytest
+else
+  echo "WARN: No test suite detected — skipping test check"
+fi
+```
+
+**Pass condition**: Test command exits with code 0, or no tests detected (warn).
+**On failure**: Report test failures and stop the pipeline.
+
+---
+
+### Step 4: Build Verification
+
+Detect project build step and run it.
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| package.json with "build" script exists | Run `npm run build` |
+| pyproject.toml exists and python build module available | Run `python -m build` |
+| Makefile with build target exists | Run `make build` |
+| No build step detected | INFO — skip (not all projects need a build), PASS |
+| Build command exits code 0 | PASS |
+| Build command exits non-zero | FAIL — report build errors, halt pipeline |
+
+```bash
+# Detection priority:
+# 1. package.json with "build" script → npm run build
+# 2. pyproject.toml → python -m build (if build module available)
+# 3. Makefile with build target → make build
+# 4. No build step → PASS (not all projects need a build)
+
+if [ -f "package.json" ] && grep -q '"build"' package.json; then
+  npm run build
+elif [ -f "pyproject.toml" ] && python -m build --help &>/dev/null; then
+  python -m build
+elif [ -f "Makefile" ] && grep -q '^build:' Makefile; then
+  make build
+else
+  echo "INFO: No build step detected — skipping build check"
+fi
+```
+
+**Pass condition**: Build command exits with code 0, or no build step detected.
+**On failure**: Report build errors and stop the pipeline.
+
+---
+
+## Output
+
+| Artifact | Format | Description |
+|----------|--------|-------------|
+| preflight-report | JSON | Pass/fail per check, current branch, blockers list |
+
+```json
+{
+  "phase": "preflight",
+  "timestamp": "ISO-8601",
+  "checks": {
+    "git_clean": { "status": "pass|fail", "details": "" },
+    "branch": { "status": "pass|warn", "current": "branch-name", "details": "" },
+    "tests": { "status": "pass|fail|skip", "details": "" },
+    "build": { "status": "pass|fail|skip", "details": "" }
+  },
+  "overall": "pass|fail",
+  "blockers": []
+}
+```
+
+## Success Criteria
+
+| Criterion | Validation Method |
+|-----------|-------------------|
+| Git working tree is clean | `git status --porcelain` returns empty |
+| Branch is non-main or user confirmed | Branch check + optional user confirmation |
+| Tests pass or skipped with warning | Test command exit code 0, or skip with WARN |
+| Build passes or skipped with info | Build command exit code 0, or skip with INFO |
+| Overall gate is "pass" | All checks produce pass/warn/skip (no fail) |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Dirty working tree | BLOCKED — list dirty files, suggest `git stash` or `git commit`, halt |
+| Tests fail | BLOCKED — report test output, halt pipeline |
+| Build fails | BLOCKED — report build output, halt pipeline |
+| git command not found | BLOCKED — report environment error |
+| No version file or project type detected | WARN — continue, version detection deferred to Phase 3 |
+
+## Next Phase
+
+-> [Phase 2: Code Review](02-code-review.md)
+
+If any check fails (overall: "fail"), report BLOCKED status with the preflight report. Do not proceed.