claude-code-workflow 7.2.26 → 7.2.28

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

@@ -0,0 +1,263 @@
+# Phase 4: Changelog & Commit
+
+> **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.
+
+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
+
+## Input
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| Phase 3 output | Yes | new_version, version_file, bump_type |
+| Git history | Yes | Commits since last tag |
+| CHANGELOG.md | No | Updated in-place if it exists; created if not |
+
+## Execution Steps
+
+### Step 1: Gather Commits Since Last Tag
+
+Retrieve commits to include in the changelog.
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| Last tag exists | `git log "$last_tag"..HEAD --pretty=format:"%h %s" --no-merges` |
+| No previous tag found | Use last 50 commits: `git log --pretty=format:"%h %s" --no-merges -50` |
+
+```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 changelog sections.
+
+**Conventional Commit Grouping Table**:
+
+| 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 using ISO 8601 date format.
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| Category has commits | Include section with all entries |
+| Category is empty | Omit section entirely |
+| test: commits present | Omit from changelog output |
+
+Changelog entry format:
+
+```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
+
+Write the new entry into CHANGELOG.md.
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| CHANGELOG.md exists | Insert new entry after the first heading line (`# Changelog`), before previous version entry |
+| CHANGELOG.md does not exist | Create new file with `# Changelog` heading followed by new entry |
+
+```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
+
+Stage changed files and create conventionally-formatted release commit.
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| Version file is package.json | Stage package.json and package-lock.json (if present) |
+| Version file is pyproject.toml | Stage pyproject.toml |
+| Version file is VERSION | Stage VERSION |
+| CHANGELOG.md was updated/created | Stage CHANGELOG.md |
+| git commit succeeds | Proceed to push step |
+| git commit fails | BLOCKED — report error |
+
+```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 <new_version>`
+- Follows conventional commit format
+- Includes Co-Authored-By trailer
+
+---
+
+### Step 6: Push to Remote
+
+Push the branch to the remote origin.
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| Remote tracking branch exists | `git push origin "<current_branch>"` |
+| No remote tracking branch | `git push -u origin "<current_branch>"` |
+| Push succeeds (exit 0) | PASS — gate satisfied |
+| 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` |
+
+```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
+```
+
+---
+
+## Output
+
+| Artifact | Format | Description |
+|----------|--------|-------------|
+| Commit and push record | JSON | changelog_entry, commit_sha, commit_message, pushed_to |
+| CHANGELOG.md | Markdown file | Updated with new version entry |
+
+```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"
+}
+```
+
+## Success Criteria
+
+| Criterion | Validation Method |
+|-----------|-------------------|
+| Commits gathered since last tag | Commit list non-empty or warn if empty |
+| Changelog entry formatted | Markdown entry with correct sections |
+| CHANGELOG.md updated or created | File exists with new entry at top |
+| Release commit created | `git log -1 --oneline` shows commit |
+| Branch pushed to remote | Push command exits 0 |
+| overall = "pass" | All steps completed without error |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| No commits since last tag | WARN — create minimal changelog entry, continue |
+| CHANGELOG.md write error | BLOCKED — report file system error |
+| git commit fails (nothing staged) | Verify version file and CHANGELOG.md were modified, re-stage |
+| Push rejected (non-fast-forward) | BLOCKED — suggest `git pull --rebase`, halt |
+| Push permission denied | BLOCKED — advise check SSH keys or access token |
+| No remote configured | BLOCKED — suggest `git remote add origin <url>` |
+
+## Next Phase
+
+-> [Phase 5: PR Creation](05-pr-creation.md)
+
+If commit and push succeed (overall: "pass"), proceed to Phase 5.
+If push fails, report BLOCKED status with error details. Do not proceed.

package/.codex/skills/ship/phases/05-pr-creation.md

@@ -0,0 +1,280 @@
+# Phase 5: PR Creation
+
+> **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.
+
+Create a pull request via GitHub CLI with a structured body, linked issues, and release metadata.
+
+## Objective
+
+- Create a PR using `gh pr create` with structured body
+- Auto-link related issues from commit messages
+- Include release summary (version, changes, test plan)
+- Output the PR URL
+
+## Input
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| Phase 4 output | Yes | commit_sha, pushed_to |
+| Phase 3 output | Yes | new_version, previous_version, bump_type, version_file |
+| Phase 2 output | Yes | merge_base (for change summary) |
+| Git history | Yes | Commit messages for issue extraction |
+
+## Execution Steps
+
+### Step 1: Extract Issue References from Commits
+
+Scan commit messages for issue reference patterns.
+
+**Issue Reference Pattern**: `fixes #N`, `closes #N`, `resolves #N`, `refs #N` (case-insensitive, singular and plural forms).
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| Last tag exists | Scan commits from last_tag..HEAD |
+| No last tag | Scan last 50 commit subjects |
+| Issue references found | Deduplicate, sort numerically |
+| No issue references found | issues_section = empty (omit section from PR body) |
+
+```bash
+last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+
+if [ -n "$last_tag" ]; then
+  commits=$(git log "$last_tag"..HEAD --pretty=format:"%s" --no-merges)
+else
+  commits=$(git log --pretty=format:"%s" --no-merges -50)
+fi
+
+# Extract issue references: fixes #N, closes #N, resolves #N, refs #N
+issues=$(echo "$commits" | grep -oiE '(fix(es)?|close[sd]?|resolve[sd]?|refs?)\s*#[0-9]+' | grep -oE '#[0-9]+' | sort -u || true)
+
+echo "Referenced issues: $issues"
+```
+
+---
+
+### Step 2: Determine Target Branch
+
+Find the appropriate base branch for the PR.
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| origin/main exists | target_branch = main |
+| origin/main not found | target_branch = master |
+
+```bash
+# Default target: main (fallback: master)
+target_branch="main"
+if ! git rev-parse --verify "origin/$target_branch" &>/dev/null; then
+  target_branch="master"
+fi
+
+current_branch=$(git branch --show-current)
+echo "PR: $current_branch -> $target_branch"
+```
+
+---
+
+### Step 3: Build PR Title
+
+Format the PR title as `release: vX.Y.Z`.
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| new_version available from Phase 3 | pr_title = "release: v<new_version>" |
+| new_version not available | Fall back to descriptive title derived from branch name |
+
+```bash
+pr_title="release: v${new_version}"
+```
+
+---
+
+### Step 4: Build PR Body
+
+Construct the full PR body with all sections.
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| issues list non-empty | Include "## Linked Issues" section with each issue as `- #N` |
+| issues list empty | Omit "## Linked Issues" section |
+| Phase 2 warnings exist | Include warning note in Summary section |
+
+```bash
+# Gather change summary
+change_summary=$(git log "$merge_base"..HEAD --pretty=format:"- %s (%h)" --no-merges)
+
+# Build linked issues section
+if [ -n "$issues" ]; then
+  issues_section="## Linked Issues
+$(echo "$issues" | while read -r issue; do echo "- $issue"; done)"
+else
+  issues_section=""
+fi
+```
+
+**PR Body Sections Table**:
+
+| Section | Content |
+|---------|---------|
+| **Summary** | Version being released, one-line description |
+| **Changes** | Grouped changelog entries (from Phase 4) |
+| **Linked Issues** | Auto-extracted `fixes #N`, `closes #N` references |
+| **Version** | Previous version, new version, bump type |
+| **Test Plan** | Checklist confirming all phases passed |
+
+---
+
+### Step 5: Create PR via gh CLI
+
+Invoke `gh pr create` with title and fully assembled body.
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| gh CLI available | Execute `gh pr create` |
+| gh CLI not installed | BLOCKED — report missing CLI, advise `gh auth login` |
+| PR created successfully | Capture URL from output |
+| PR creation fails (already exists) | Report existing PR URL, gate = pass |
+| PR creation fails (other error) | BLOCKED — report error details |
+
+```bash
+gh pr create --title "$pr_title" --base "$target_branch" --body "$(cat <<'EOF'
+## Summary
+Release vX.Y.Z
+
+### Changes
+- list of changes from changelog
+
+## Linked Issues
+- #N (fixes)
+- #M (closes)
+
+## Version
+- Previous: X.Y.Z-1
+- New: X.Y.Z
+- Bump type: patch|minor|major
+
+## Test Plan
+- [ ] Pre-flight checks passed (git clean, branch, tests, build)
+- [ ] AI code review completed with no critical issues
+- [ ] Version bump verified in version file
+- [ ] Changelog updated with all changes since last release
+- [ ] Release commit pushed successfully
+
+Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+---
+
+### Step 6: Capture and Report PR URL
+
+Extract the PR URL from gh output.
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| URL present in output | Record pr_url, set gate = pass |
+| No URL in output | Check `gh pr view --json url` as fallback |
+| Both fail | BLOCKED — report failure |
+
+```bash
+# gh pr create outputs the PR URL on success
+pr_url=$(gh pr create ... 2>&1 | tail -1)
+echo "PR created: $pr_url"
+```
+
+---
+
+## Output
+
+| Artifact | Format | Description |
+|----------|--------|-------------|
+| PR creation record | JSON | pr_url, pr_title, target_branch, source_branch, linked_issues |
+| Final completion status | Text block | DONE / DONE_WITH_CONCERNS with full summary |
+
+```json
+{
+  "phase": "pr-creation",
+  "pr_url": "https://github.com/owner/repo/pull/N",
+  "pr_title": "release: vX.Y.Z",
+  "target_branch": "main",
+  "source_branch": "feature-branch",
+  "linked_issues": ["#1", "#2"],
+  "overall": "pass|fail"
+}
+```
+
+## Success Criteria
+
+| Criterion | Validation Method |
+|-----------|-------------------|
+| Issue references extracted | issues list populated (or empty with no error) |
+| Target branch determined | target_branch set to main or master |
+| PR title formatted | pr_title = "release: v<new_version>" |
+| PR body assembled with all sections | All required sections present |
+| PR created via gh CLI | pr_url present in output |
+| Completion status output | DONE or DONE_WITH_CONCERNS block present |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| gh CLI not installed | BLOCKED — report error, advise install + `gh auth login` |
+| Not authenticated with gh | BLOCKED — report auth error, advise `gh auth login` |
+| PR already exists for branch | Report existing PR URL, treat as pass |
+| No changes to create PR for | BLOCKED — report, suggest verifying Phase 4 push succeeded |
+| Issue regex finds no matches | issues = [] — omit Linked Issues section, continue |
+
+## Completion Status
+
+After PR creation, output the final Completion Status:
+
+```
+## STATUS: DONE
+
+**Summary**: Released vX.Y.Z — PR created at <pr_url>
+
+### Details
+- Phases completed: 5/5
+- Version: <previous> -> <new> (<bump_type>)
+- PR: <pr_url>
+- Key outputs: CHANGELOG.md updated, release commit pushed, PR created
+
+### Outputs
+- CHANGELOG.md (updated)
+- <version_file> (version bumped)
+- Release commit: <sha>
+- PR: <pr_url>
+```
+
+If there were review warnings from Phase 2, use `DONE_WITH_CONCERNS` and list the warnings in the Details section:
+
+```
+## STATUS: DONE_WITH_CONCERNS
+
+**Summary**: Released vX.Y.Z — PR created at <pr_url> (review warnings noted)
+
+### Details
+- Phases completed: 5/5
+- Version: <previous> -> <new> (<bump_type>)
+- PR: <pr_url>
+- Concerns: <list review warnings from Phase 2>
+
+### Outputs
+- CHANGELOG.md (updated)
+- <version_file> (version bumped)
+- Release commit: <sha>
+- PR: <pr_url>
+```