Feature Release Skill

Merge the validated feature to main branch via PR, optionally tag a release, and clean up the feature worktree. Phase 5 of the feature lifecycle (design → plan → implement → validate → release).

Instructions

Phase 0: PRIME

1. Read and follow the repository CLAUDE.md before any other action. Repository-level conventions override defaults here.

2. Verify feature state is release and validate is completed. All state operations go through the state script -- never manipulate state files directly:

   python3 ~/.claude/scripts/feature-state.py gate FEATURE release.merge-strategy
   

3. Load all artifacts: design document, plan, implementation summary, and validation report. These provide the raw material for PR content in the next phase; skipping any artifact risks an incomplete PR description.

4. Confirm validation passed before proceeding. A feature with failing validation cannot be released -- there are no exceptions. If validation has not passed, stop and direct the user to run /feature-validate first.

Gate: All artifacts loaded. Validation passed. State confirmed as release. Proceed.

Phase 1: EXECUTE (Release)

Step 1: Generate PR Content

From the accumulated artifacts, generate a PR description following this structure:

## Summary
[From design document problem statement]

## Changes
[From implementation artifact -- what was built]

## Testing
[From validation report -- what was verified]

## Design Decision
[From design document -- why this approach]

Step 2: Create PR

Use existing pr-pipeline patterns:

1. Ensure feature branch is pushed to remote.
2. Create PR via gh pr create targeting main. Always merge via pull request -- never push directly to main, even for small features. This is non-negotiable because direct pushes bypass review and CI.
3. Use squash merge (default) so the feature branch collapses into a single clean commit on main.
4. Use conventional commit format for the squash commit message. Do not add "Co-Authored-By" or "Generated with Claude Code" attribution lines.
5. Link to design decisions in the PR body.

Step 3: Post-Merge Cleanup (after PR is merged)

Do not begin cleanup until the PR merge is confirmed. Deleting the branch or worktree before merge confirmation risks losing work.

1. Clean up worktree:

   python3 ~/.claude/scripts/feature-state.py worktree FEATURE cleanup
   

2. Archive feature state:

   python3 ~/.claude/scripts/feature-state.py complete FEATURE
   

3. Update L0 (remove feature from active list).

Optional post-merge actions (only when explicitly enabled by the user):

• Version Bump: Bump version number based on change type (patch/minor/major).
• Changelog Update: Add entry to CHANGELOG.md.
• Tag Release: Create git tag after merge.

Gate: PR created/merged. Cleanup complete.

Phase 2: VALIDATE

• PR was created successfully
• Feature branch exists on remote
• PR description includes design context

Phase 3: CHECKPOINT

1. Save release artifact:

   echo "RELEASE_NOTES" | python3 ~/.claude/scripts/feature-state.py checkpoint FEATURE release
   

2. Record learnings -- final pass, capture insights from the full lifecycle:

   python3 ~/.claude/scripts/learning-db.py record TOPIC KEY "VALUE" --category design
   

   Focus on: architectural decisions, workflow improvements, agent performance, patterns to reuse.

3. Report completion:

   Feature [NAME] released successfully.
   - Design → Plan → Implement → Validate → Release: complete
   - PR: [URL]
   - Retro findings: [N] recorded, [M] promoted to context
   

Error Handling

Scenario	Action
Validation not passed	Stop. Direct user to /feature-validate. Do not proceed.
PR creation fails	Check branch is pushed, gh is authenticated, and target branch exists. Retry once.
Worktree cleanup fails	Log the error but do not block completion. User can clean up manually.
State script errors	Report the exact error. Do not fall back to manual file manipulation.

References

• PR Pipeline
• Git Commit Flow
• State Conventions