claude-code-workflow 7.2.27 → 7.2.28

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

@@ -0,0 +1,121 @@
+# Phase 1: Pre-Flight Checks
+
+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
+
+## Gate Condition
+
+ALL four checks must pass. If any check fails, stop the pipeline and report BLOCKED status with the specific failure.
+
+## Execution Steps
+
+### Step 1: Git Clean Check
+
+```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
+
+```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 and run the project's test suite:
+
+```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 and run the project's build step:
+
+```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
+
+- **Format**: JSON object with pass/fail per check
+- **Structure**:
+
+```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": []
+}
+```
+
+## Next Phase
+
+If all checks pass, proceed to [Phase 2: Code Review](02-code-review.md).
+If any check fails, report BLOCKED status with the preflight report.

package/.claude/skills/ship/phases/02-code-review.md

@@ -0,0 +1,137 @@
+# Phase 2: Code Review
+
+Automated AI-powered code review of changes since the base branch, with risk assessment.
+
+## Objective
+
+- Detect the merge base between current branch and target branch
+- Generate diff for review
+- Run AI-powered code review via CCW CLI
+- Flag high-risk changes (large diffs, sensitive files, breaking changes)
+
+## Gate Condition
+
+No critical issues flagged by the review. Warnings are reported but do not block.
+
+## Execution Steps
+
+### Step 1: Detect Merge Base
+
+```bash
+# Determine target branch (default: main, fallback: master)
+target_branch="main"
+if ! git rev-parse --verify "origin/$target_branch" &>/dev/null; then
+  target_branch="master"
+fi
+
+# Find merge base
+merge_base=$(git merge-base "origin/$target_branch" HEAD)
+echo "Merge base: $merge_base"
+
+# If on main/master directly, compare against last tag
+current_branch=$(git branch --show-current)
+if [ "$current_branch" = "main" ] || [ "$current_branch" = "master" ]; then
+  last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+  if [ -n "$last_tag" ]; then
+    merge_base="$last_tag"
+    echo "On main — using last tag as base: $last_tag"
+  else
+    # Use first commit if no tags exist
+    merge_base=$(git rev-list --max-parents=0 HEAD | head -1)
+    echo "No tags found — using initial commit as base"
+  fi
+fi
+```
+
+### Step 2: Generate Diff Summary
+
+```bash
+# File-level summary
+git diff --stat "$merge_base"...HEAD
+
+# Full diff for review
+git diff "$merge_base"...HEAD > /tmp/ship-review-diff.txt
+
+# Count changes for risk assessment
+files_changed=$(git diff --name-only "$merge_base"...HEAD | wc -l)
+lines_added=$(git diff --numstat "$merge_base"...HEAD | awk '{s+=$1} END {print s}')
+lines_removed=$(git diff --numstat "$merge_base"...HEAD | awk '{s+=$2} END {print s}')
+```
+
+### Step 3: Risk Assessment
+
+Flag high-risk indicators before AI review:
+
+| Risk Factor | Threshold | Risk Level |
+|-------------|-----------|------------|
+| Files changed | > 50 | High |
+| Lines changed | > 1000 | High |
+| Sensitive files modified | Any of: `.env*`, `*secret*`, `*credential*`, `*auth*`, `*.key`, `*.pem` | High |
+| Config files modified | `package.json`, `pyproject.toml`, `tsconfig.json`, `Dockerfile` | Medium |
+| Migration files | `*migration*`, `*migrate*` | Medium |
+
+```bash
+# Check for sensitive file changes
+sensitive_files=$(git diff --name-only "$merge_base"...HEAD | grep -iE '\.(env|key|pem)|secret|credential' || true)
+if [ -n "$sensitive_files" ]; then
+  echo "HIGH RISK: Sensitive files modified:"
+  echo "$sensitive_files"
+fi
+```
+
+### Step 4: AI Code Review
+
+Use CCW CLI for automated analysis:
+
+```bash
+ccw cli -p "PURPOSE: Review code changes for release readiness; success = all critical issues identified with file:line references
+TASK: Review diff for bugs | Check for breaking changes | Identify security concerns | Assess test coverage gaps
+MODE: analysis
+CONTEXT: @**/* | Reviewing diff from $merge_base to HEAD ($files_changed files, +$lines_added/-$lines_removed lines)
+EXPECTED: Risk assessment (low/medium/high), list of issues with severity and file:line, release recommendation (ship/hold/fix-first)
+CONSTRAINTS: Focus on correctness and security | Flag breaking API changes | Ignore formatting-only changes
+" --tool gemini --mode analysis
+```
+
+**Note**: Wait for the CLI analysis to complete before proceeding. Do not proceed to Phase 3 while review is running.
+
+### Step 5: Evaluate Review Results
+
+Based on the AI review output:
+
+| Review Result | Action |
+|---------------|--------|
+| No critical issues | Proceed to Phase 3 |
+| Critical issues found | Report BLOCKED, list issues |
+| Warnings only | Proceed with DONE_WITH_CONCERNS note |
+| Review failed/timeout | Ask user whether to proceed or retry |
+
+## Output
+
+- **Format**: Review summary with risk assessment
+- **Structure**:
+
+```json
+{
+  "phase": "code-review",
+  "merge_base": "commit-sha",
+  "stats": {
+    "files_changed": 0,
+    "lines_added": 0,
+    "lines_removed": 0
+  },
+  "risk_level": "low|medium|high",
+  "risk_factors": [],
+  "ai_review": {
+    "recommendation": "ship|hold|fix-first",
+    "critical_issues": [],
+    "warnings": []
+  },
+  "overall": "pass|fail|warn"
+}
+```
+
+## Next Phase
+
+If review passes (no critical issues), proceed to [Phase 3: Version Bump](03-version-bump.md).
+If critical issues found, report BLOCKED status with review summary.

package/.claude/skills/ship/phases/03-version-bump.md

@@ -0,0 +1,171 @@
+# Phase 3: Version Bump
+
+Detect the current version, determine the bump type, and update the version file.
+
+## Objective
+
+- Detect which version file the project uses
+- Read the current version
+- Determine bump type (patch/minor/major) from commit messages or user input
+- Update the version file
+- Record the version change
+
+## Gate Condition
+
+Version file updated successfully with the new version.
+
+## Execution Steps
+
+### Step 1: Detect Version File
+
+Detection priority order:
+
+| Priority | File | Read Method |
+|----------|------|-------------|
+| 1 | `package.json` | `jq -r .version package.json` |
+| 2 | `pyproject.toml` | `grep -oP 'version\s*=\s*"\K[^"]+' pyproject.toml` |
+| 3 | `VERSION` | `cat VERSION` |
+
+```bash
+if [ -f "package.json" ]; then
+  version_file="package.json"
+  current_version=$(node -p "require('./package.json').version" 2>/dev/null || jq -r .version package.json)
+elif [ -f "pyproject.toml" ]; then
+  version_file="pyproject.toml"
+  current_version=$(grep -oP 'version\s*=\s*"\K[^"]+' pyproject.toml | head -1)
+elif [ -f "VERSION" ]; then
+  version_file="VERSION"
+  current_version=$(cat VERSION | tr -d '[:space:]')
+else
+  echo "NEEDS_CONTEXT: No version file found"
+  echo "Expected one of: package.json, pyproject.toml, VERSION"
+  # Ask user which file to use or create
+fi
+
+echo "Version file: $version_file"
+echo "Current version: $current_version"
+```
+
+### Step 2: Determine Bump Type
+
+**Auto-detection from commit messages** (conventional commits):
+
+```bash
+# Get commits since last tag
+last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+if [ -n "$last_tag" ]; then
+  commits=$(git log "$last_tag"..HEAD --oneline)
+else
+  commits=$(git log --oneline -20)
+fi
+
+# Scan for conventional commit prefixes
+has_breaking=$(echo "$commits" | grep -iE '(BREAKING CHANGE|!:)' || true)
+has_feat=$(echo "$commits" | grep -iE '^[a-f0-9]+ feat' || true)
+has_fix=$(echo "$commits" | grep -iE '^[a-f0-9]+ fix' || true)
+
+if [ -n "$has_breaking" ]; then
+  suggested_bump="major"
+elif [ -n "$has_feat" ]; then
+  suggested_bump="minor"
+else
+  suggested_bump="patch"
+fi
+
+echo "Suggested bump: $suggested_bump"
+```
+
+**User confirmation**:
+- For `patch` and `minor`: proceed with suggested bump, inform user
+- For `major`: always ask user to confirm before proceeding (major bumps have significant implications)
+- User can override the suggestion with an explicit bump type
+
+### Step 3: Calculate New Version
+
+```bash
+# Parse semver components
+IFS='.' read -r major minor patch <<< "$current_version"
+
+case "$bump_type" in
+  major)
+    new_version="$((major + 1)).0.0"
+    ;;
+  minor)
+    new_version="${major}.$((minor + 1)).0"
+    ;;
+  patch)
+    new_version="${major}.${minor}.$((patch + 1))"
+    ;;
+esac
+
+echo "Version bump: $current_version -> $new_version"
+```
+
+### Step 4: Update Version File
+
+```bash
+case "$version_file" in
+  package.json)
+    # Use node/jq for safe JSON update
+    jq --arg v "$new_version" '.version = $v' package.json > tmp.json && mv tmp.json package.json
+    # Also update package-lock.json if it exists
+    if [ -f "package-lock.json" ]; then
+      jq --arg v "$new_version" '.version = $v | .packages[""].version = $v' package-lock.json > tmp.json && mv tmp.json package-lock.json
+    fi
+    ;;
+  pyproject.toml)
+    # Use sed for TOML update (version line in [project] or [tool.poetry])
+    sed -i "s/^version\s*=\s*\".*\"/version = \"$new_version\"/" pyproject.toml
+    ;;
+  VERSION)
+    echo "$new_version" > VERSION
+    ;;
+esac
+
+echo "Updated $version_file: $current_version -> $new_version"
+```
+
+### Step 5: Verify Update
+
+```bash
+# Re-read to confirm
+case "$version_file" in
+  package.json)
+    verified=$(node -p "require('./package.json').version" 2>/dev/null || jq -r .version package.json)
+    ;;
+  pyproject.toml)
+    verified=$(grep -oP 'version\s*=\s*"\K[^"]+' pyproject.toml | head -1)
+    ;;
+  VERSION)
+    verified=$(cat VERSION | tr -d '[:space:]')
+    ;;
+esac
+
+if [ "$verified" = "$new_version" ]; then
+  echo "PASS: Version verified as $new_version"
+else
+  echo "FAIL: Version mismatch — expected $new_version, got $verified"
+fi
+```
+
+## Output
+
+- **Format**: Version change record
+- **Structure**:
+
+```json
+{
+  "phase": "version-bump",
+  "version_file": "package.json",
+  "previous_version": "1.2.3",
+  "new_version": "1.3.0",
+  "bump_type": "minor",
+  "bump_source": "auto-detected|user-specified",
+  "overall": "pass|fail"
+}
+```
+
+## Next Phase
+
+If version updated successfully, proceed to [Phase 4: Changelog & Commit](04-changelog-commit.md).
+If version update fails, report BLOCKED status.

package/.claude/skills/ship/phases/04-changelog-commit.md

@@ -0,0 +1,167 @@
+# Phase 4: Changelog & Commit
+
+Generate changelog entry from git history, update CHANGELOG.md, create release commit, and push to remote.
+
+## Objective
+
+- Parse git log since last tag into grouped changelog entry
+- Update or create CHANGELOG.md
+- Create a release commit with version in the message
+- Push the branch to remote
+
+## Gate Condition
+
+Release commit created and pushed to remote successfully.
+
+## Execution Steps
+
+### Step 1: Gather Commits Since Last Tag
+
+```bash
+last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+
+if [ -n "$last_tag" ]; then
+  echo "Generating changelog since tag: $last_tag"
+  git log "$last_tag"..HEAD --pretty=format:"%h %s" --no-merges
+else
+  echo "No previous tag found — using last 50 commits"
+  git log --pretty=format:"%h %s" --no-merges -50
+fi
+```
+
+### Step 2: Group Commits by Conventional Commit Type
+
+Parse commit messages and group into categories:
+
+| Prefix | Category | Changelog Section |
+|--------|----------|-------------------|
+| `feat:` / `feat(*):`| Features | **Features** |
+| `fix:` / `fix(*):`| Bug Fixes | **Bug Fixes** |
+| `perf:` | Performance | **Performance** |
+| `docs:` | Documentation | **Documentation** |
+| `refactor:` | Refactoring | **Refactoring** |
+| `chore:` | Maintenance | **Maintenance** |
+| `test:` | Testing | *(omitted from changelog)* |
+| Other | Miscellaneous | **Other Changes** |
+
+```bash
+# Example grouping logic (executed by the agent, not a literal script):
+# 1. Read all commits since last tag
+# 2. Parse prefix from each commit message
+# 3. Group into categories
+# 4. Format as markdown sections
+# 5. Omit empty categories
+```
+
+### Step 3: Format Changelog Entry
+
+Generate a markdown changelog entry:
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+### Features
+- feat: description (sha)
+- feat(scope): description (sha)
+
+### Bug Fixes
+- fix: description (sha)
+
+### Performance
+- perf: description (sha)
+
+### Other Changes
+- chore: description (sha)
+```
+
+Rules:
+- Date format: YYYY-MM-DD (ISO 8601)
+- Each entry includes the short SHA for traceability
+- Empty categories are omitted
+- Entries are listed in chronological order within each category
+
+### Step 4: Update CHANGELOG.md
+
+```bash
+if [ -f "CHANGELOG.md" ]; then
+  # Insert new entry after the first heading line (# Changelog)
+  # The new entry goes between the main heading and the previous version entry
+  # Use Write tool to insert the new section at the correct position
+  echo "Updating existing CHANGELOG.md"
+else
+  # Create new CHANGELOG.md with header
+  echo "Creating new CHANGELOG.md"
+fi
+```
+
+**CHANGELOG.md structure**:
+```markdown
+# Changelog
+
+## [X.Y.Z] - YYYY-MM-DD
+(new entry here)
+
+## [X.Y.Z-1] - YYYY-MM-DD
+(previous entry)
+```
+
+### Step 5: Create Release Commit
+
+```bash
+# Stage version file and changelog
+git add package.json package-lock.json pyproject.toml VERSION CHANGELOG.md 2>/dev/null
+
+# Only stage files that actually exist and are modified
+git add -u
+
+# Create release commit
+git commit -m "$(cat <<'EOF'
+chore: bump version to X.Y.Z
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+EOF
+)"
+```
+
+**Commit message format**: `chore: bump version to X.Y.Z`
+- Follows conventional commit format
+- Includes Co-Authored-By trailer
+
+### Step 6: Push to Remote
+
+```bash
+current_branch=$(git branch --show-current)
+
+# Check if remote tracking branch exists
+if git rev-parse --verify "origin/$current_branch" &>/dev/null; then
+  git push origin "$current_branch"
+else
+  git push -u origin "$current_branch"
+fi
+```
+
+**On push failure**:
+- If rejected (non-fast-forward): Report BLOCKED, suggest `git pull --rebase`
+- If permission denied: Report BLOCKED, check remote access
+- If no remote configured: Report BLOCKED, suggest `git remote add`
+
+## Output
+
+- **Format**: Commit and push record
+- **Structure**:
+
+```json
+{
+  "phase": "changelog-commit",
+  "changelog_entry": "## [X.Y.Z] - YYYY-MM-DD ...",
+  "commit_sha": "abc1234",
+  "commit_message": "chore: bump version to X.Y.Z",
+  "pushed_to": "origin/branch-name",
+  "overall": "pass|fail"
+}
+```
+
+## Next Phase
+
+If commit and push succeed, proceed to [Phase 5: PR Creation](05-pr-creation.md).
+If push fails, report BLOCKED status with error details.