codingthefuturewithai/teamcraft:merge-issue
plugins/teamcraft/skills/merge-issue/SKILL.md
Finalize and merge an approved (or solo-flow) PR. Verifies approval and CI status, marks the work item as done on the branch, commits, then merges. This is the skill that actually completes the work. Use when the user says "merge this issue", "ship this", "PR is approved, merge it", "finalize this issue", or "the review is done, let's merge".
testing
Updated May 28, 2026
$ install --global
skillsauthnpx skillsauth add codingthefuturewithai/claude-code-primitives teamcraft:merge-issueInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: May 28, 2026, 3:46 AM128.4s1 file scanned
SKILL.md
- name:
- teamcraft:merge-issue
- description:
- Finalize and merge an approved (or solo-flow) PR. Verifies approval and CI status, marks the work item as done on the branch, commits, then merges. This is the skill that actually completes the work. Use when the user says "merge this issue", "ship this", "PR is approved, merge it", "finalize this issue", or "the review is done, let's merge".
- argument-hint:
- [work item ID — e.g. feat-notification-prefs, bug-timezone-display]
- disable-model-invocation:
- false
- user-invocable:
- true
Why This Skill Exists
The work item's status: done must be written on the branch before merge, not on main after merge. Once a PR merges, the branch is dead — nothing else can be committed to it. So the final commit on the branch updates the work item to done, and then we merge. Main inherits the correct state via the merge itself.
This is why merge-issue is the one skill that actually completes the work. validate-issue submits. address-review-issue iterates. merge-issue ships. No other skill marks a work item done.
Verify the PR Is Ready to Merge
Identify the work item (from $ARGUMENTS, or from .teamcraft/work/INDEX.md looking for an in-review item on the current branch) and the PR associated with the branch.
Check all of these before proceeding:
- The PR exists and is ready for review — not a Draft.
- CI has passed. Use whatever tools are available to check CI status. If CI has not completed or has failed, stop. Do not merge on failing CI under any circumstances.
- Approval status:
- If this is a team-review flow, verify the PR has the required approvals per the team's process.
- If this is a solo flow (the developer chose "going solo" during
validate-issue, or confirms it now), approval is not required.
- The branch is up to date — if the target branch (e.g.,
main) has moved since this branch last updated, flag this so the developer can decide whether to rebase/merge before proceeding. Some teams require branches to be current; others don't.
If any check fails, stop. Tell the developer exactly what's blocking the merge and why.
Confirm with the Developer
Before taking destructive action, confirm: "All checks pass. Ready to merge this to main? This will: update the work item to done, commit that change on the branch, and merge the PR." Wait for explicit confirmation.
If the developer isn't sure (e.g., wants to check one more thing), stop and let them run the skill again when ready.
Finalize the Work Item on the Branch
On the current branch (NOT on main):
- Update the work item frontmatter:
status: donecompleted: YYYY-MM-DD(today's date)
- Update
.teamcraft/work/INDEX.md:- Change the item's status column to
done
- Change the item's status column to
- Commit both files with the work item ID in the commit message. Example:
chore(feat-notification-prefs): mark work item as done - Push the commit to the remote branch.
This is the final commit on the branch before the merge. Main will inherit this state when the merge completes.
Merge the PR
Before merging, consult the team's captured operating conventions for the prescribed merge strategy — squash, merge commit, or rebase. Locate the conventions via the repo's README or the standard documentation locations; don't assume a specific path. If no strategy is documented anywhere, ask the developer. If the conventions doc is found but lacks a Teamcraft certification stamp (see ../references/doc-provenance.md), treat the merge strategy it states as UNVERIFIED — confirm it with the developer before merging rather than silently following a possibly-inherited rule.
Execute the merge using the prescribed strategy. Confirm the merge succeeded by checking the PR status after the operation.
Cleanup
After the merge succeeds:
- Check out the default branch (typically
main) locally. - Pull to get the merged state.
- Optionally delete the local work branch — ask the developer first. Some teams keep branches briefly for reference.
When the Skill Is Complete
The skill is complete when ALL of the following are true:
- The PR was verified as approved (or solo-flow confirmed) with CI passing before merging
- The work item was updated to
status: doneandcompleted: YYYY-MM-DDon the branch .teamcraft/work/INDEX.mdwas updated to reflect the new status- The final commit was pushed to the branch
- The PR was merged successfully
- The developer has confirmed the merge completed as expected
Main now reflects the correct final state: the work item is done, the completed date is accurate, and the INDEX.md is current. No post-merge operations needed.
Report the outcome:
- Work item ID and title
- Completed date
- Merged PR number and URL
- Any follow-up items the developer might want (e.g., deferred work items from earlier reviews)
Do NOT start another work item here. The developer decides what's next — /pick-next-issue is their natural next move if they want to keep going.
Related Skills
codingthefuturewithai/teamcraft-auto:work-board
development
VerifiedTrustedCommunity
Launch (or re-launch) the user's live, multi-project work board. The dashboard is a single HTML file copied to a stable user-side location at ~/.claude/teamcraft-board.html and opened in the user's default browser. It has two views via a header toggle — a drag-and-drop Kanban Board and a live Status tab with analytics (work by status, throughput, cycle time, aging, blocked chains, recomputed on every poll). Each project is added via a header dropdown; the dashboard polls each project's .teamcraft/work directly from the browser and updates in real time. Use when the user says 'show me the kanban', 'work board', 'open the board', 'board view', 'kanban view', 'live dashboard', 'visual dashboard', 'live status dashboard', 'status dashboard', 'project metrics', 'throughput/cycle-time view', 'HTML view of work items', 'drag-and-drop board', or asks to see/move/track work visually.
SKILL.mdUpdated Jun 12, 2026
codingthefuturewithai/teamcraft-auto:run-retro
development
VerifiedTrustedCommunity
Run a retrospective — AI compiles evidence from recent work, facilitates human reflection, and captures process decisions back into living docs. Use when the user says 'run a retro', 'let's do a retrospective', 'run a retrospective on the last 2 weeks', 'let's reflect on how that feature went', or 'time for a retro'.
SKILL.mdUpdated Jun 12, 2026
codingthefuturewithai/teamcraft-auto:refresh-project-rules
development
VerifiedTrustedCommunity
Re-evaluate what Claude needs to be told about this project as the codebase evolves. Some gotchas become obvious from the code (remove them). New gotchas emerge. Decisions change. Use when the user says 'refresh the rules', 'update Claude's context', 'are the rules still accurate', 'clean up claude rules', or after significant codebase changes.
SKILL.mdUpdated Jun 12, 2026
codingthefuturewithai/teamcraft-auto:project-status
development
VerifiedTrustedCommunity
Report project status from work items and git history — either as a quick, interpreted read here in the session, or by pointing the developer to the live Status dashboard (the work board's Status tab). Covers work by status, what's in flight, cycle times, throughput, backlog priorities, aging alerts, blocked chains, and how commit activity lines up with the board. Use when the user says 'project status', 'show me the project status', 'what's the status of the work items', 'how are we doing', 'generate a status report', or asks for a status dashboard.
SKILL.mdUpdated Jun 12, 2026