ship

<skill name="apex:ship" phase="ship">

<overview> Final phase: Review implementation with adversarial agents, commit changes, complete task, and record reflection.

Combines REVIEWER (adversarial code review) and DOCUMENTER (commit, complete, reflect). </overview>

<phase-model> phasemodel: frontmatter: [research, plan, implement, rework, complete] rework: enabled dbrole: [RESEARCH, ARCHITECT, BUILDER, BUILDERVALIDATOR, REVIEWER, DOCUMENTER] legacydbrole: [VALIDATOR] sourceoftruth: gating: frontmatter.phase telemetry: dbrole </phase-model>

<phase-gate requires="implement" sets="complete"> <reads-file>./.apex/tasks/[ID].md</reads-file> <requires-section>implementation</requires-section> <appends-section>ship</appends-section> </phase-gate>

<mandatory-actions> This phase requires THREE mandatory actions in order:

1. Adversarial Review - Launch review agents
2. Git Commit - Commit all changes
3. Final Reflection - Record pattern outcomes and key learnings

YOU CANNOT SKIP ANY OF THESE for APPROVE or CONDITIONAL outcomes. If REJECT, stop after review, set frontmatter to phase: rework, and return to /apex:implement. </mandatory-actions>

<initial-response> <if-no-arguments> I'll review and finalize the implementation. Please provide the task identifier.

You can find active tasks in ./.apex/tasks/ or run with: /apex:ship [identifier] </if-no-arguments> <if-arguments>Load task file and begin review.</if-arguments> </initial-response>

<workflow>

<step id="1" title="Load task and verify phase"> <instructions>

1. Read ./.apex/tasks/[identifier].md
2. Verify frontmatter phase: implement
3. Parse <task-contract> first and note its latest version and any amendments
4. Parse all sections for full context
5. If phase != implement, refuse with: "Task is in [phase] phase. Expected: implement"

Contract rules:

• Final report MUST map changes to AC-* and confirm no out-of-scope work
• If scope/ACs changed during implement, ensure amendments are recorded with rationale and version bump

</instructions> </step>

<step id="2" title="Gather review context"> <extract>

• <task-contract> - Authoritative scope/ACs and amendment history
• <implementation><files-modified> - What changed
• <implementation><files-created> - What's new
• <implementation><patterns-used> - Patterns to validate
• <implementation><validation-results> - Test status
• <implementation><reviewer-handoff> - Key points for review
• <plan><architecture-decision> - Original intentions
• <plan><warnings> - Risks to verify mitigated

</extract>

<get-diffs>

git diff HEAD~N  # or appropriate range for this task's changes
git log --oneline -10

</get-diffs> </step>

<step id="3" title="Phase 1: Launch review agents"> <critical> Launch ALL 5 Phase 1 agents in a SINGLE message for true parallelism. </critical>

<agents parallel="true">

<agent type="apex:review:phase1:review-security-analyst"> Task ID: [taskId] Code Changes: [Full diff] Journey Context: Architecture warnings, implementation decisions, test results

Review for security vulnerabilities. Return YAML with id, severity, confidence, location, issue, evidence, mitigations_found. </agent>

<agent type="apex:review:phase1:review-performance-analyst"> Task ID: [taskId] Code Changes: [Full diff] Journey Context: Architecture warnings, implementation decisions

Review for performance issues. Return YAML findings. </agent>

<agent type="apex:review:phase1:review-architecture-analyst"> Task ID: [taskId] Code Changes: [Full diff] Journey Context: Original architecture from plan, pattern selections

Review for architecture violations and pattern consistency. Return YAML findings. </agent>

<agent type="apex:review:phase1:review-test-coverage-analyst"> Task ID: [taskId] Code Changes: [Full diff] Validation Results: [From implementation section]

Review for test coverage gaps. Return YAML findings. </agent>

<agent type="apex:review:phase1:review-code-quality-analyst"> Task ID: [taskId] Code Changes: [Full diff] Journey Context: Patterns applied, conventions followed

Review for maintainability and code quality. Return YAML findings. </agent>

</agents>

<wait-for-all>WAIT for ALL 5 agents to complete before Phase 2.</wait-for-all> </step>

<step id="4" title="Phase 2: Adversarial challenge"> <agents parallel="true">

<agent type="apex:review:phase2:review-challenger"> Phase 1 Findings: [YAML from all 5 Phase 1 agents] Original Code: [Relevant snippets] Journey Context: Plan rationale, implementation justifications

Challenge EVERY finding for:

• Code accuracy (did Phase 1 read correctly?)
• Pattern applicability (does framework prevent this?)
• Evidence quality (Strong/Medium/Weak)
• ROI Analysis:

- fixeffort: trivial | minor | moderate | significant | major - benefittype: security | reliability | performance | maintainability | correctness - roiscore: 0.0-1.0 (benefit / effort ratio) - overridedecision: pullforward | keep | pushback - override_reason: [Why changing priority]

Return: challengeresult (UPHELD|DOWNGRADED|DISMISSED), evidencequality, recommendedconfidence, roianalysis </agent>

<agent type="apex:review:phase2:review-context-defender"> Phase 1 Findings: [Findings affecting existing code] Repository: [Path and git info]

Use git history to find justifications for seemingly problematic patterns. Return: Context justifications for historical code choices. </agent>

</agents>

<wait-for-all>WAIT for both agents to complete.</wait-for-all> </step>

<step id="5" title="Synthesize review results"> <confidence-adjustment> For each finding: finalConfidence = phase1Confidence finalConfidence = challengeImpact # UPHELD=1.0, DOWNGRADED=0.6, DISMISSED=0.2 finalConfidence = (0.5 + evidencescore 0.5) if contextjustified: finalConfidence = 0.3 </confidence-adjustment>

<action-decision>

• confidence < 0.3 → DISMISS
• critical AND confidence > 0.5 → FIX_NOW
• high AND confidence > 0.6 → FIX_NOW
• confidence > 0.7 → SHOULD_FIX
• else → NOTE

</action-decision>

<review-decision>

• 0 FIX_NOW → APPROVE (proceed to commit)
• 1-2 FIX_NOW minor → CONDITIONAL (fix or accept with docs)
• 3+ FIX_NOW or critical security → REJECT (return to /apex:implement)

</review-decision>

<reject-flow> On REJECT:

1. Write <ship><decision>REJECT</decision> with a brief rationale
2. Update frontmatter: phase: rework, updated: [ISO timestamp]
3. STOP. Do NOT commit or finalize reflection. Return to /apex:implement.

</reject-flow> </step>

<step id="5.5" title="Documentation Updates"> <purpose> Ensure documentation stays in sync with code changes. </purpose>

<documentation-checklist> If task modified workflow or architecture:

• CLAUDE.md - Check for stale references to changed behavior
• README.md - Update any affected workflow descriptions
• Related design docs - Search in docs/ directory

If task modified API or CLI:

• API documentation files
• CLI command documentation
• Usage examples in docs

If task modified data structures:

• Type definition docs
• Schema documentation
• Migration notes if breaking change

Search strategy:

# Find docs that might reference changed files
for file in [modified_files]; do
  grep -r "$(basename $file .ts)" docs/ README.md CLAUDE.md
done

</documentation-checklist>

<update-procedure>

1. Search for references to modified code
2. Read each found doc FULLY
3. Update outdated references
4. Verify accuracy after update
5. Add to git staging for commit

</update-procedure>

<docs-to-update-output> Record in <implementation><docs-updated>:

<docs-updated>
  <doc path="[path]" reason="[Why updated]"/>
</docs-updated>

</docs-to-update-output> </step>

<step id="6" title="Git commit"> <critical> Commit BEFORE final reflection - reflection should reference an immutable commit. </critical>

<commands>

git status --short
git add [relevant files]
git commit -m "[Task ID]: [Description]

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>"
git log -1 --oneline  # Capture commit SHA

</commands>

<checkpoint>Commit SHA captured for evidence.</checkpoint>

<compound-prompt> After successful commit, display:

Committed: [SHA]

Run `/apex:compound [identifier]` to capture learnings for future agents.

</compound-prompt> </step>

<step id="7" title="Reflection and completion"> <critical> You MUST record a final reflection. This is NOT optional.

Without reflection:

• Learnings aren't captured
• Pattern outcomes aren't recorded
• Future tasks don't benefit

</critical>

<reflection-format>

### Reflection
- **Outcome**: success | partial | failure
- **Key Learning**: [Main lesson from this task]
- **Patterns Used**: [PAT:ID from plan] with outcome notes
- **New Patterns / Anti-patterns**: [If discovered]
- **Evidence**: [Commit SHA, files, tests]

</reflection-format>

<instructions>

1. Summarize outcome and key learning
2. List patterns used from the plan with outcome notes
3. Capture any new patterns or anti-patterns discovered
4. Reference evidence (commit SHA, file paths, tests)
5. Update the task file's <ship><reflection> section

</instructions> </step>

<step id="9" title="Write ship section to task file"> <output-format> Append to <ship> section:

<ship>
<metadata>
  <timestamp>[ISO]</timestamp>
  <outcome>success|partial|failure</outcome>
  <commit-sha>[SHA]</commit-sha>
</metadata>

<review-summary>
  <phase1-findings count="X">
    <by-severity critical="N" high="N" medium="N" low="N"/>
    <by-agent security="N" performance="N" architecture="N" testing="N" quality="N"/>
  </phase1-findings>
  <phase2-challenges>
    <upheld>N</upheld>
    <downgraded>N</downgraded>
    <dismissed>N</dismissed>
  </phase2-challenges>
  <false-positive-rate>[X%]</false-positive-rate>
</review-summary>

<contract-verification>
  <contract-version>[N]</contract-version>
  <amendments-audited>[List amendments or "none"]</amendments-audited>
  <acceptance-criteria-verification>
    <criterion id="AC-1" status="met|not-met">[Evidence or exception]</criterion>
  </acceptance-criteria-verification>
  <out-of-scope-check>[Confirm no out-of-scope work slipped in]</out-of-scope-check>
</contract-verification>

<action-items>
  <fix-now>
    <item id="[ID]" severity="[S]" confidence="[C]" location="[file:line]">
      [Issue and fix]
    </item>
  </fix-now>
  <should-fix>[Deferred items]</should-fix>
  <accepted>[Accepted risks with justification]</accepted>
  <dismissed>[False positives with reasons]</dismissed>
</action-items>

<commit>
  <sha>[Full SHA]</sha>
  <message>[Commit message]</message>
  <files>[List of files]</files>
</commit>

<reflection>
  <patterns-reported>
    <pattern id="PAT:X:Y" outcome="[outcome]"/>
  </patterns-reported>
  <key-learning>[Main lesson]</key-learning>
  <reflection-status>recorded|missing</reflection-status>
</reflection>

<final-summary>
  <what-was-built>[Concise description]</what-was-built>
  <patterns-applied count="N">[List]</patterns-applied>
  <test-status passed="X" failed="Y"/>
  <documentation-updated>[What docs changed]</documentation-updated>
</final-summary>
</ship>

</output-format>

<update-frontmatter> For APPROVE or CONDITIONAL only: Set phase: complete, status: complete, and updated: [ISO timestamp] </update-frontmatter> </step>

<step id="10" title="Final report to user"> <template> ✅ Task Complete: [Title]

📊 Metrics:

• Complexity: [X]/10
• Files modified: [N]
• Files created: [N]
• Tests: [passed]/[total]

💬 Summary: [Concise description of what was built]

📚 Patterns:

• Applied: [N] patterns
• Reflection: ✅ Recorded

✅ Acceptance Criteria:

• AC-* coverage: [met|not met with exceptions]

🔍 Review:

• Phase 1 findings: [N]
• Dismissed as false positives: [N] ([X]%)
• Action items: [N] (all resolved)

⏭️ Next: Task complete. No further action required. </template> </step>

</workflow>

<completion-verification> BEFORE reporting to user, verify ALL actions completed:

• Phase 1 review agents launched and returned?
• Phase 2 challenge agents launched and returned (with ROI analysis)?
• Documentation checklist completed?
• Contract verification completed (AC mapping + out-of-scope check)?
• Git commit created? (verify with git log -1)
• Reflection recorded in <ship><reflection>?

If ANY unchecked → GO BACK AND COMPLETE IT. </completion-verification>

<success-criteria>

• Adversarial review completed (7 agents: 5 Phase 1 + 2 Phase 2)
• ROI analysis included in challenger findings
• Documentation checklist completed (grep → read → update → verify)
• Contract verification completed with AC mapping and scope confirmation
• All FIX_NOW items resolved (or explicitly accepted)
• Git commit created with proper message
• Reflection recorded with patterns and learnings
• Task file updated with complete ship section
• Frontmatter shows phase: complete, status: complete

</success-criteria>

</skill>