name: complete
description: "Complete task: validate, document, review, commit, and merge to develop. Use when all implementation is done and ready to finalize."
model: claude-sonnet-4-20250514
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task

/complete

Complete a task with full validation, documentation updates, reviews, and automatic merge to develop.

Usage

/complete careerbrain 002         # Complete specific issue
/complete careerbrain             # Complete current/active issue

What It Does

1. Validate PLAN completion and spec compliance
2. Update all project documentation
3. Create final commit with doc changes
4. Run mandatory code review + security audit
5. Merge to develop branch
6. Clean up feature branch

GitFlow Pattern: feature/* → develop (automatic) | develop → main (requires PR)

Prerequisites

• All implementation complete (code written)
• Active issue with completed work
• PLAN.md exists with phases mostly complete

Execution Flow

1. Check PLAN.md Completion

✓ All phases complete (5/5)
  or
✗ Incomplete phases:
  - [ ] 1.3 - Implement session refresh

2. Spec Compliance Validation

Acceptance Scenario Coverage:
- Search tests matching each Given/When/Then scenario
- Create missing tests if needed

Success Metrics Verification:
- Check performance, coverage, accessibility

Out-of-Scope Enforcement:
- Scan for code that violates out-of-scope items

Agent Constraints Check:
- Verify no dependencies added (if constrained)
- Check no files outside scope modified

3. Update Spec Status Markers

If the TASK has an implements: field, update inline status markers in the spec:

# Before (in spaces/[project]/docs/specs/*.md)
- 🚧 User registration with email/password

# After
- ✅ User registration with email/password

This provides public visibility into what's implemented.

4. Update All Documentation

Scan and validate ALL docs in spaces/[project]/docs/:
- architecture-overview.md
- data-model.md
- api-overview.md
- README.md

5. Update CHANGELOG

MANDATORY: Add entries under [Unreleased] section.

Categories:
- ### Added - New features (TASKs)
- ### Fixed - Bug fixes (BUGs)
- ### Changed - Modifications
- ### Security - Security updates

6. Final WORKLOG Entry

## YYYY-MM-DD HH:MM - COMPLETED

Issue ### complete and ready for merge.

Summary:
- [What was implemented]
- [What was deferred]

7. Update Status

Set issue frontmatter: status: complete

8. Create Final Commit

Stage and commit documentation changes.

9. Run Final Reviews

If not already done:
1. Launch code-reviewer agent
2. Launch security-auditor agent
3. Block if CRITICAL issues

10. Merge to Develop

git checkout develop
git pull origin develop
git merge --no-ff feature/###-slug
git push origin develop
git branch -d feature/###-slug

11. Suggest Next Steps

Next actions:
1. Start next task: /implement project ### --full
2. View status: /project-status project
3. Merge to main (requires PR): gh pr create --base main --head develop

Documentation Checklist

Before merge, verify:
1. PLAN.md - All phases checked off
2. Linked SPEC - Updated to reflect what was built
3. architecture-overview.md - Reflects changes
4. ADRs - New decisions documented
5. CHANGELOG.md - User-facing changes
6. WORKLOG.md - Final summary
7. README.md - Updated if API changed

Workflow

/issue → /plan → /implement → /commit → /complete
                                            ↓
                                    Update docs + CHANGELOG
                                            ↓
                                    Run reviews
                                            ↓
                                    Merge to develop