ship by benredmond/apex

Combines REVIEWER (adversarial code review) and DOCUMENTER (commit, complete, reflect).

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.

You can find active tasks in ./apex/tasks/ or run with: /apex:ship [identifier] Load task file and begin review.

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

light:
- full diff
- modified/created file list
- validation summary
- reviewer handoff summary
- recent commits, churn/regression signals, and ownership summary for modified files
standard:
- everything in light
- plan warnings and architecture decision summary
- churn/regression signals for modified files
deep:
- everything in standard
- adjacent snippets for changed functions/classes
- closely related tests, call sites, or neighboring abstractions needed to reason about downstream impact of the changed lines

Use the selected context pack consistently in Phase 1 and Phase 2 prompts.

Modes change context depth, not reviewer count or scoring rules:

light → concise context pack for low-risk, localized changes
standard → normal context pack
deep → richer context pack (plan warnings, validation gaps, git churn, adjacent snippets) and more explicit prompts for scrutinizing downstream impact of changed lines

Task ID: [taskId] Review Mode: [selected mode] Code Changes: [Full diff] Mode Context Pack: [Context assembled in Step 2.6 for the selected mode] Journey Context: Architecture warnings, implementation decisions, test results

Review for security vulnerabilities. In deep, read adjacent context and likely exploit paths to better assess changed lines, but only report findings rooted in the diff. Return the standard security-analyst YAML schema.

Task ID: [taskId] Review Mode: [selected mode] Code Changes: [Full diff] Mode Context Pack: [Context assembled in Step 2.6 for the selected mode] Journey Context: Original architecture from plan, pattern selections

Review for architecture violations and pattern consistency. In deep, use neighboring abstractions and dependency context to assess the changed lines more rigorously, but keep findings anchored to the diff. Return the standard architecture-analyst YAML schema.

Task ID: [taskId] Review Mode: [selected mode] Code Changes: [Full diff] Mode Context Pack: [Context assembled in Step 2.6 for the selected mode] Validation Results: [From implementation section]

Review for test coverage gaps. In deep, use integration seams and adjacent helpers to reason about risky changed paths, but only flag gaps tied to changed behavior. Return the standard test-coverage-analyst YAML schema.

Review for maintainability and code quality. In deep, examine long-term complexity and compounding design debt around the changed lines, but keep findings tied to the diff. Return the standard code-quality-analyst YAML schema.

Task ID: [taskId] Review Mode: [selected mode] Code Changes: [Full diff] Mode Context Pack: [Context assembled in Step 2.6 for the selected mode] Git Context: [recent commits, churn, regressions, ownership signals from the selected mode context pack]

Review for pattern violations, regressions, and inconsistencies using git history. In deep, prioritize high-churn and previously reverted areas to pressure-test the changed lines. Return the standard git-historian YAML schema.

WAIT for ALL 5 Phase 1 agents to complete before Phase 2.

Challenge EVERY finding using the standard challenger contract:

validate code accuracy and evidence quality
assess historical context and justification
analyze ROI and overrides using the challenger’s standard enums and schema
return the standard challenger YAML output, including per-finding validation, historical_context, roi_analysis, override, challenge_result, final_confidence, and final_category

Use the selected review mode only to decide how much context to read before applying the standard contract:

light → concise context pack
standard → normal context pack
deep → richer context pack and more context-reading before judgment

WAIT for the challenger to complete.

If finalCategory disagrees with the threshold-implied category:

STOP and re-run Phase 2 with the standard challenger schema

Filtered findings are internal only:

do not add them to <action-items>
do not include filtered findings as individual action items or detailed findings
do record aggregate filtered counts in the review summary

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

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com" 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>
```markdown
### 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]

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

<review-summary>
  <review-mode>[light|standard|deep]</review-mode>
  <review-mode-rationale>[Why this mode was selected]</review-mode-rationale>
  <phase1-findings count="X">
    <by-severity critical="N" high="N" medium="N" low="N"/>
    <by-agent>
      <agent name="code-quality-analyst" findings="N"/>
      <agent name="git-historian" findings="N"/>
      <agent name="test-coverage-analyst" findings="N"/>
      <agent name="architecture-analyst" findings="N"/>
      <agent name="security-analyst" findings="N"/>
    </by-agent>
  </phase1-findings>
  <phase2-challenges>
    <upheld>N</upheld>
    <downgraded>N</downgraded>
    <dismissed>N</dismissed>
  </phase2-challenges>
  <final-categories fix-now="N" should-fix="N" filtered="N"/>
  <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>
</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>

📊 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]
Filtered by thresholds: [N]
Dismissed by challenger: [N] ([X]%)
Action items: [N] (all resolved)

⏭️ Next: Task complete. No further action required.

Phase 1 review agents launched and returned?
Review mode selected and rationale recorded?
Phase 2 challenger 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.