Awesome-omni-skill ship

<skill name="apex:ship" phase="ship"> <overview> Final phase: Review implementation with adversarial agents, commit changes, complete task, and submit reflection.

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

<phase-model> phase_model: frontmatter: [research, plan, implement, rework, complete] rework: enabled db_role: [RESEARCH, ARCHITECT, BUILDER, BUILDER_VALIDATOR, REVIEWER, DOCUMENTER] legacy_db_role: [VALIDATOR] source_of_truth: gating: frontmatter.phase telemetry: db_role </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. **apex_reflect** - Submit pattern outcomes

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> ```bash 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:
  • fix_effort: trivial | minor | moderate | significant | major
  • benefit_type: security | reliability | performance | maintainability | correctness
  • roi_score: 0.0-1.0 (benefit / effort ratio)
  • override_decision: pull_forward | keep | push_back
  • override_reason: [Why changing priority]

Return: challenge_result (UPHELD|DOWNGRADED|DISMISSED), evidence_quality, recommended_confidence, roi_analysis </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 + evidence_score * 0.5) if context_justified: 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 call apex_reflect. 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>`: ```xml <docs-updated> <doc path="[path]" reason="[Why updated]"/> </docs-updated> ``` </docs-to-update-output> </step> <step id="6" title="Git commit"> <critical> Commit BEFORE apex_reflect - reflection validates git evidence. </critical> <commands> ```bash git status --short git add [relevant files] git commit -m "[Task ID]: [Description]

🤖 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>
</step>

<step id="7" title="apex_task_complete">
<call>
```javascript
apex_task_complete({
  id: taskId,
  outcome: "success" | "partial" | "failure",
  key_learning: "Main lesson from this task",
  patterns_used: ["PAT:ID:FROM:PLAN"]  // Only patterns from plan
})

</call>

<returns>ReflectionDraft - use as basis for apex_reflect</returns> </step>

<step id="8" title="apex_reflect"> <critical> YOU MUST CALL apex_reflect. THIS IS NOT OPTIONAL.

Without apex_reflect:

• Pattern trust scores don't update
• Learnings aren't captured
• Future tasks don't benefit </critical>

<format-choice> **batch_patterns** (simple, for most cases): ```javascript apex_reflect({ task: { id: taskId, title: taskTitle }, outcome: "success", batch_patterns: [ { pattern: "PAT:ID", // Must exist in plan's pattern list outcome: "worked-perfectly", notes: "Optional notes about usage" } ] }) ```

claims (advanced, for new patterns/anti-patterns/learnings):

apex_reflect({
  task: { id: taskId, title: taskTitle },
  outcome: "success",
  claims: {
    // Patterns used from plan (updates trust scores)
    patterns_used: [{
      pattern_id: "PAT:ID",
      evidence: [{
        kind: "git_lines",
        file: "src/auth.ts",
        sha: "HEAD",  // or commit SHA
        start: 45,
        end: 78
      }]
    }],

    // Trust score updates (required for patterns_used)
    trust_updates: [{
      pattern_id: "PAT:ID",
      outcome: "worked-perfectly"
    }],

    // NEW patterns discovered during implementation
    new_patterns: [{
      title: "Error Boundary Pattern",
      summary: "Wrap async operations with consistent error handling",
      snippets: [{
        snippet_id: "error-boundary-1",
        source_ref: {
          kind: "git_lines",
          file: "src/utils/errors.ts",
          sha: "HEAD",
          start: 10,
          end: 35
        }
      }],
      evidence: []
    }],

    // Anti-patterns to AVOID
    anti_patterns: [{
      title: "Direct Database Access in Handler",
      reason: "Bypasses transaction management and audit logging",
      evidence: [{
        kind: "git_lines",
        file: "src/handlers/user.ts",
        sha: "HEAD",
        start: 100,
        end: 110
      }]
    }],

    // General learnings
    learnings: [{
      assertion: "JWT refresh tokens require httpOnly cookies for security",
      evidence: [{
        kind: "git_lines",
        file: "src/auth/tokens.ts",
        sha: "HEAD",
        start: 50,
        end: 65
      }]
    }]
  }
})

</format-choice> <evidence-kinds> | Kind | Required Fields | When to Use | |------|-----------------|-------------| | `git_lines` | file, sha, start, end | Code at specific lines | | `commit` | sha | Entire commit as evidence | | `pr` | number, repo | Pull request reference | | `ci_run` | id, provider | CI/CD run evidence | </evidence-kinds> <valid-outcomes> - "worked-perfectly" → 100% success (alpha: 1.0, beta: 0.0) - "worked-with-tweaks" → 70% success (alpha: 0.7, beta: 0.3) - "partial-success" → 50% success (alpha: 0.5, beta: 0.5) - "failed-minor-issues" → 30% success (alpha: 0.3, beta: 0.7) - "failed-completely" → 0% success (alpha: 0.0, beta: 1.0) </valid-outcomes> <common-errors> 1. **Mixing formats**: Use batch_patterns OR claims, not both 2. **Missing SHA**: Always include sha (use "HEAD" if current) 3. **Fabricated patterns**: Only claim patterns from plan 4. **Not committing first**: Evidence validation fails without commit </common-errors> </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>
  <apex-reflect-status>submitted|failed</apex-reflect-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: ✅ Submitted

✅ 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)
• apex_task_complete called? (received ReflectionDraft?)
• apex_reflect called? (received ok: true?)

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 - apex_task_complete called - apex_reflect called with proper format (batch_patterns or claims) - Task file updated with complete ship section - Frontmatter shows phase: complete, status: complete </success-criteria> </skill>