EXPLICITLY USE when user requests validation, scoring, or review:
- "review X" or "validate Y" or "test Z"
- "score this", "quality check", "validate before shipping"
- "check if X works correctly"
- "verify the implementation of Y"
- "find issues in Z"
- "quality check for X"
- "ensure Y meets requirements"
DO NOT activate for:
- Implementation tasks (use tangle-workflow)
- Research tasks (use probe-workflow)
- Requirement definition (use grasp-workflow)
- Built-in commands (/plugin, /help, etc.)
{{PREAMBLE}}
Pre-Delivery: State Check
Before starting delivery:
Read .octo/STATE.md to verify Develop phase complete
Update STATE.md:
current_phase: 4
phase_position: "Delivery"
status: "in_progress"
# Verify Develop phase is completeif [[ -f ".octo/STATE.md" ]]; then
develop_status=$("${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" get_phase_status 3)
if [[ "$develop_status" != "complete" ]]; thenecho"⚠️ Warning: Develop phase not marked complete. Consider completing development first."fifi# Update state for Delivery phase"${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" update_state \
--phase 4 \
--position "Delivery" \
--status "in_progress"
⚠️ EXECUTION CONTRACT (MANDATORY - CANNOT SKIP)
This skill uses ENFORCED execution mode. You MUST follow this exact sequence.
STEP 1: Detect Work Context (MANDATORY)
Analyze the user's prompt and project to determine context:
Also check: What is being reviewed? Code files -> Dev, Documents -> Knowledge
Capture context_type = "Dev" or "Knowledge"
Step 1b: Detect Dev Subtype (if Dev context)
When context_type is Dev, determine the to inject domain-appropriate validation criteria into the review prompt. Append the matching validation supplement after the user's prompt when calling orchestrate.sh in Step 4.
Verify: all referenced files exist (scripts, stylesheets, images). Check ARIA labels and roles, keyboard navigability, touch target sizes (44px min). Flag innerHTML usage. Confirm progressive enhancement (fallbacks for navigator.share, localStorage, etc). Test self-containment: does this work if opened/run with zero setup?
Verify: input validation at every endpoint, consistent error response format, auth on protected routes, rate limiting considered, schema/contract documented.
DO NOT PROCEED TO STEP 2 until context determined. Context type (Dev vs Knowledge) and dev subtype determine which validation supplements to inject — wrong context produces a review that checks irrelevant criteria.
Use the ACTUAL results below. PROHIBITED: Showing only "🔵 Claude: Available ✓" without listing all providers.
If OCTO_ALLOWED_PROVIDERS is set, treat it as the source of truth for which providers may participate. Providers filtered out by that allowlist are intentionally reported as unavailable; do not invoke or recommend them in the workflow.
Display this banner BEFORE orchestrate.sh execution:
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider validation mode
✅ [Knowledge] Deliver Phase: [Brief description of document review]
Provider Availability:
🔴 Codex CLI: [Available ✓ / Not installed ✗] - Structure and logic analysis
🟡 Antigravity CLI: [Available ✓ / Not installed ✗] - Content quality and completeness
🧭 Antigravity CLI: [Available ✓ / Not installed ✗] - Additional external-model challenge
🔵 Claude: Available ✓ - Synthesis and recommendations
💰 Estimated Cost: $0.02-0.08
⏱️ Estimated Time: 3-7 minutes
DO NOT PROCEED TO STEP 3 until banner displayed. The banner shows users which providers will run and what costs they'll incur — starting API calls without this visibility violates cost transparency.
STEP 3: Read Prior State (MANDATORY - State Management)
Before executing the workflow, read full project context:
# Initialize state if needed"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" init_state
# Set current workflow"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" set_current_workflow "flow-deliver""deliver"# Get all prior decisions (critical for validation)
prior_decisions=$("${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" get_decisions "all")
# Get context from all prior phases
discover_context=$("${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" get_context "discover")
define_context=$("${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" get_context "define")
develop_context=$("${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" get_context "develop")
# Display what you found (validation needs full context)echo"📋 Validation Context Summary:"if [[ "$discover_context" != "null" ]]; thenecho" Discovery: $discover_context"fiif [[ "$define_context" != "null" ]]; thenecho" Definition: $define_context"fiif [[ "$develop_context" != "null" ]]; thenecho" Development: $develop_context"fiif [[ "$prior_decisions" != "[]" && "$prior_decisions" != "null" ]]; thenecho" Decisions to validate against:"echo"$prior_decisions" | jq -r '.[] | " - \(.decision) (\(.phase))"'fi
This provides full context for validation:
Requirements and scope (from define phase)
Implementation decisions (from develop phase)
Research findings (from discover phase)
All architectural decisions to validate against
If claude-mem is installed, its MCP tools (search, timeline, get_observations) are available — use them to check for past delivery issues or quality patterns
DO NOT PROCEED TO STEP 4 until state read.
STEP 4: Execute orchestrate.sh deliver (MANDATORY - Use Bash Tool)
❌ Reviewing directly without calling orchestrate.sh — adversarial multi-AI review catches blind spots that a single reviewer misses; Codex finds code quality issues while Antigravity catches security and edge cases
❌ Doing single-perspective analysis instead of multi-provider
❌ Claiming you're "simulating" the workflow
❌ Proceeding to Step 4 without running this command
You MUST use the Bash tool to invoke orchestrate.sh.
What Users See During Execution (v7.16.0+)
If running in Claude Code v2.1.16+, users will see real-time progress indicators in the task spinner:
Phase 1 - External Provider Execution (Parallel):
🔴 Analyzing code quality and patterns (Codex)...
🟡 Validating security and edge cases (Antigravity)...
Phase 2 - Synthesis (Sequential):
🔵 Synthesizing validation results...
These spinner verb updates happen automatically - orchestrate.sh calls update_task_progress() before each agent execution. Users see exactly which provider is working and what it's doing.
If NOT running in Claude Code v2.1.16+: Progress indicators are silently skipped, no errors shown.
Also check: What is being reviewed? Code files -> Dev, Documents -> Knowledge
Step 1b: Detect Dev Subtype — see EXECUTION CONTRACT Step 1b above for subtype table and validation supplements. Append the matching supplement to the prompt before calling orchestrate.sh.
Blocking Step 3: Execute orchestrate.sh deliver via Bash tool
Blocking Step 4: Verify validation file exists
Step 5: Present formatted validation report
Each step is mandatory and blocking - you cannot proceed to the next step until the current one completes successfully.
Task Management Integration
Create tasks to track execution progress:
// At start of skill executionTaskCreate({
subject: "Execute deliver workflow with multi-AI providers",
description: "Run orchestrate.sh deliver for validation",
activeForm: "Running multi-AI deliver workflow"
})
// Mark in_progress when calling orchestrate.shTaskUpdate({taskId: "...", status: "in_progress"})
// Mark completed ONLY after validation report presentedTaskUpdate({taskId: "...", status: "completed"})
Error Handling
If any step fails:
Step 1 (Context): Default to Dev Context if ambiguous
Step 2 (Providers): If all external providers are unavailable, suggest /octo:setup and STOP
Step 3 (orchestrate.sh): Show bash error, check logs, report to user
Step 4 (Validation): If validation file missing, show orchestrate.sh logs, DO NOT substitute with direct review
Never fall back to direct review if orchestrate.sh execution fails. Report the failure and let the user decide how to proceed.
Validation Report Format
After successful execution, present validation report with:
Probe: "Research authentication best practices" -> Discover options
Grasp: "Define auth requirements" -> Narrow to specific needs
Tangle: "Implement JWT auth" -> Build the solution
Ink: "Validate auth implementation" -> Ensure quality before ship
Or use ink standalone for validation of existing code.
Validation Checklist
Before marking validation complete, ensure:
All providers completed their analysis
Quality scores calculated for all dimensions
Critical issues identified and documented
Warnings and recommendations provided
Go/no-go decision clearly stated
Next steps documented for user
Full validation report shared
Cost Awareness
External API Usage:
🔴 Codex CLI uses your OPENAI_API_KEY (costs apply)
🟡 Antigravity CLI uses your AGY_AUTH_TOKEN (costs apply)
🔵 Claude analysis included with Claude Code
Ink workflows typically cost $0.02-0.08 per validation depending on codebase size and complexity.
Post-Validation: Documentation Sync
After validation passes (go decision), run documentation synchronization to keep project docs current with shipped code. This step is automatic when running as part of /octo:embrace and offered when running standalone.
Load the doc-sync source after delivery has been explicitly requested:
Read ${HOME}/.claude-octopus/plugin/.claude/skills/skill-doc-sync/SKILL.md and execute it for "sync docs for the changes on this branch"
The doc-sync skill will:
Read all .md files (max depth 2, cap 30 files)
Cross-reference each against git diff to find stale content
Auto-update factual corrections (paths, counts, version numbers)
Ask about risky/narrative changes before editing
Check cross-doc consistency and discoverability
Commit doc changes to the branch
Skip conditions: Skip doc-sync if:
No .md files exist in the project
The validation result was "no-go" (fix code first)
User explicitly requests to skip (--no-docs or declines when asked)
Post-Delivery: Route to Ship
After delivery validation and doc-sync complete, route according to the user's explicit
request:
Ship requested: update .octo/STATE.md, then read and follow
.claude/skills/skill-ship/SKILL.md from the stable plugin root.
Branch wrap-up requested: read and follow
.claude/skills/skill-finish-branch/SKILL.md from the stable plugin root.
Review only: deliver the synthesized findings and stop. Do not update the project
to a ready-to-ship state or display a shipping instruction.
# Run this block only when the user explicitly requested shipping."${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" update_state \
--status "complete" \
--history"All phases complete, ready to ship"# Display completion message with next stepsecho""echo"🎉 **EMBRACE WORKFLOW COMPLETE**"echo""echo"All four phases have been completed:"echo" ✅ Discover - Research and exploration"echo" ✅ Define - Requirements and scope"echo" ✅ Develop - Implementation"echo" ✅ Deliver - Validation and quality"echo""echo"📦 **Project ready! Run \`/octo:ship\` to finalize and archive.**"
After that block succeeds, perform the requested finalization immediately:
Read ${HOME}/.claude-octopus/plugin/.claude/skills/skill-ship/SKILL.md and execute it for "finalize and archive the validated project"
Do not stop after displaying the command. The ship-requested branch is incomplete until
the explicit ship workflow has actually been executed.
Terminal State
The Deliver phase is complete ONLY when validation findings are synthesized and
must-fix items are resolved or explicitly accepted by the user. If the user asked to
ship or wrap the branch, then read and execute skill-ship (or skill-finish-branch for tests,
PR, and merge). For review-only requests, deliver the findings and stop; do NOT expand
the request into shipping work without user authorization.
Ready to validate! This skill runs only after explicit invocation.