flow-develop

> This file is generated from a template. Edit the `.tmpl` file, not this file directly. > Run `scripts/gen-skill-docs.sh` to regenerate after changes. ## Pre-Development: State Check Before starting development: 1. Read `.octo/STATE.md` to verify Define phase complete 2. Update STATE.md: - current_phase: 3 - phase_position: "Development" - status: "in_progress" ```bash # Verify Define phase is complete if [[ -f ".octo/STATE.md" ]]; then define_status=$("${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" get_phase_status 2) if [[ "$define_status" != "complete" ]]; then echo "⚠️ Warning: Define phase not marked complete. Consider running definition first." fi fi # Update state for Development phase "${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" update_state \ --phase 3 \ --position "Development" \ --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: **Knowledge Context Indicators**: - Deliverable terms: "PRD", "proposal", "presentation", "report", "strategy document", "business case" - Business terms: "market entry", "competitive analysis", "stakeholder", "executive summary" **Dev Context Indicators**: - Technical terms: "API", "endpoint", "function", "module", "service", "component" - Action terms: "implement", "code", "build", "create", "develop" + technical noun **Also check**: Does project have `package.json`, `Cargo.toml`, etc.? (suggests Dev Context) **Capture context_type = "Dev" or "Knowledge"** #### Step 1b: Detect Dev Subtype (if Dev context) When context_type is Dev, determine the **subtype** to inject domain-appropriate quality guidance into the prompt sent to providers. Append the matching supplement text after the user's prompt. | Subtype | Trigger keywords | Quality supplement | |---------|-----------------|-------------------| | `frontend-ui` | "page", "widget", "component", "UI", "HTML", "CSS", "form", "dashboard", "layout" | See **frontend-ui enrichment** below. | | `cli-tool` | "CLI", "command-line", "terminal", "script", "flag", "argument" | Help text via --help flag. Meaningful exit codes (0 success, 1 user error, 2 system error). Stdin/stdout/stderr used correctly. Argument validation with clear error messages. | | `api-service` | "API", "endpoint", "REST", "GraphQL", "gRPC", "server", "route" | Input validation at boundaries. Consistent error response format. Auth/authz on every endpoint. Rate limiting consideration. OpenAPI/schema documentation. | | `infra` | "deploy", "terraform", "docker", "CI", "pipeline", "Kubernetes", "helm" | Idempotent operations. Secrets never hardcoded. Rollback path documented. Health checks included. | | `data` | "ETL", "pipeline", "migration", "schema", "database", "SQL" | Idempotent migrations. Backup/rollback strategy. Data validation at ingestion. | | `general` | Default if no subtype matches | No supplement — use base implementer persona only. | #### frontend-ui enrichment When `frontend-ui` subtype is detected, do TWO things: **A. Inject quality supplement into the prompt:** Self-contained files preferred. Accessibility: ARIA labels, keyboard nav, 44px touch targets (WCAG 2.5.5). Safe DOM: createElement over innerHTML. Progressive enhancement: feature-detect APIs (navigator.share, localStorage) with fallbacks. Persist user prefs via localStorage. **B. Pull design intelligence from BM25 (if available):** Before calling orchestrate.sh, check if the design intelligence engine exists and query it for relevant design context: ```bash SEARCH_PY="${HOME}/.claude-octopus/plugin/vendors/ui-ux-pro-max-skill/src/ui-ux-pro-max/scripts/search.py" if [[ -f "$SEARCH_PY" ]]; then # Detect relevant domains from the prompt design_context="" # Style query — what visual style fits this task? style_hit=$(python3 "$SEARCH_PY" "<user's task description>" --domain style --top 1 2>/dev/null || true) [[ -n "$style_hit" ]] && design_context+="Design style suggestion: $style_hit\n" # UX query — relevant UX patterns ux_hit=$(python3 "$SEARCH_PY" "<user's task description>" --domain ux --top 1 2>/dev/null || true) [[ -n "$ux_hit" ]] && design_context+="UX pattern: $ux_hit\n" # Append to prompt if hits found if [[ -n "$design_context" ]]; then # Append design intelligence to the orchestrate.sh prompt prompt="${prompt}\n\nDesign intelligence (from BM25 search):\n${design_context}" fi fi ``` This gives providers concrete design guidance (style direction, UX patterns) without requiring the user to run `/octo:design-ui-ux` separately. If the search engine isn't installed, implementation proceeds with the quality supplement only. **How to apply:** When calling orchestrate.sh in Step 4, append the quality supplement (and design intelligence if available) to the prompt: ``` orchestrate.sh develop "<user prompt>\n\nQuality requirements for this deliverable:\n<supplement text>\n<design intelligence if found>" ``` **DO NOT PROCEED TO STEP 2 until context determined.** Context type (Dev vs Knowledge) and dev subtype determine which quality supplements and design intelligence to inject — wrong context wastes provider credits on irrelevant analysis. --- ### STEP 2: Display Visual Indicators (MANDATORY - BLOCKING) **MANDATORY: Run the centralized provider check BEFORE displaying the banner:** ```bash bash "${HOME}/.claude-octopus/plugin/scripts/helpers/check-providers.sh" ``` **Use the ACTUAL results. PROHIBITED: Showing only "🔵 Claude: Available ✓" without listing all providers.** **Validation:** - If ALL external CLI providers unavailable -> STOP, suggest: `/octo:setup` - If some unavailable -> Continue with available provider(s) - If multiple available -> Proceed normally **Display this banner BEFORE orchestrate.sh execution (list ALL providers from check output):** **For Dev Context:** ``` 🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider implementation mode 🛠️ [Dev] Develop Phase: [Brief description of what you're building] Provider Availability: 🔴 Codex CLI: [status from check] - Code generation and patterns 🟡 Gemini CLI: [status from check] - Alternative approaches 🟢 Copilot CLI: [status from check] - GitHub integration 🟣 Qwen CLI: [status from check] - Additional perspective 🟤 OpenCode CLI: [status from check] - Multi-provider routing 🔵 Claude: Available ✓ - Integration and quality gates 💰 Estimated Cost: $0.02-0.10 ⏱️ Estimated Time: 3-7 minutes ``` **For Knowledge Context:** ``` 🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider implementation mode 🛠️ [Knowledge] Develop Phase: [Brief description of deliverable] Provider Availability: 🔴 Codex CLI: ${codex_status} - Structure and framework application 🟡 Gemini CLI: ${gemini_status} - Content and narrative development 🔵 Claude: Available ✓ - Integration and quality review 💰 Estimated Cost: $0.02-0.10 ⏱️ 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 any prior context:** ```bash # 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-develop" "develop" # Get prior decisions (critical for implementation) prior_decisions=$("${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" get_decisions "all") # Get context from discover and define 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") # Display what you found (if any) if [[ "$discover_context" != "null" ]]; then echo "📋 Discovery phase findings:" echo " $discover_context" fi if [[ "$define_context" != "null" ]]; then echo "📋 Definition phase scope:" echo " $define_context" fi if [[ "$prior_decisions" != "[]" && "$prior_decisions" != "null" ]]; then echo "📋 Implementing with decisions:" echo "$prior_decisions" | jq -r '.[] | " - \(.decision) (\(.phase)): \(.rationale)"' fi ``` **This provides critical context for implementation:** - Technology stack and patterns decided - Scope and requirements defined - Research findings to inform implementation - If **claude-mem** is installed, its MCP tools (`search`, `timeline`, `get_observations`) are available — use them to check for related past implementation patterns **DO NOT PROCEED TO STEP 4 until state read.** --- ### STEP 4: Execute orchestrate.sh develop (MANDATORY - Use Bash Tool) **You MUST execute this command via the Bash tool:** ```bash ${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh develop "<user's implementation request>" ``` **CRITICAL: You are PROHIBITED from:** - ❌ Implementing directly without calling orchestrate.sh — single-model implementation misses alternative approaches and edge cases that Codex and Gemini surface through independent analysis - ❌ Writing code without multi-provider perspectives - ❌ 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):** - 🔴 Generating code and patterns (Codex)... - 🟡 Exploring alternative approaches (Gemini)... **Phase 2 - Synthesis (Sequential):** - 🔵 Integrating and applying quality gates... 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. --- ### STEP 5: Verify Execution (MANDATORY - Validation Gate) **After orchestrate.sh completes, verify it succeeded:** ```bash # Find the latest synthesis file (created within last 10 minutes) SYNTHESIS_FILE=$(find ~/.claude-octopus/results -name "tangle-synthesis-*.md" -mmin -10 2>/dev/null | head -n1) if [[ -z "$SYNTHESIS_FILE" ]]; then echo "❌ VALIDATION FAILED: No synthesis file found" echo "orchestrate.sh did not execute properly" exit 1 fi echo "✅ VALIDATION PASSED: $SYNTHESIS_FILE" cat "$SYNTHESIS_FILE" ``` **If validation fails:** 1. Report error to user 2. Show logs from `~/.claude-octopus/logs/` 3. DO NOT proceed with presenting results 4. DO NOT substitute with direct implementation — fallback to single-model implementation skips the multi-provider synthesis that catches design flaws early --- ### STEP 6: Update State (MANDATORY - Post-Execution) **After synthesis is verified, record implementation details in state:** ```bash # Extract key implementation decisions from synthesis implementation_approach=$(head -50 "$SYNTHESIS_FILE" | grep -A 3 "## Implementation\|## Approach" | tail -3 | tr '\n' ' ') # Record implementation decisions decision_made=$(echo "$implementation_approach" | grep -o "implemented\|using [A-Za-z0-9 ]*\|chose to\|pattern:" | head -1) if [[ -n "$decision_made" ]]; then "${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" write_decision \ "develop" \ "$decision_made" \ "Multi-AI implementation consensus" fi # Update develop phase context "${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" update_context \ "develop" \ "$implementation_approach" # Update metrics "${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" update_metrics "phases_completed" "1" # Track actual providers used (dynamic — not hardcoded) for _provider in $(bash "${HOME}/.claude-octopus/plugin/scripts/helpers/check-providers.sh" | grep ":available" | cut -d: -f1) claude; do "${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" update_metrics "provider" "$_provider" done ``` **DO NOT PROCEED TO STEP 7 until state updated.** --- ### STEP 7: Present Implementation Plan (Only After Steps 1-6 Complete) Read the synthesis file and present: - Recommended approach - Implementation steps - Code overview from all perspectives (Codex, Gemini, Claude) - Quality gates results - Request user confirmation before implementing **After user confirms, STEP 6: Implement the solution using Write/Edit tools** **Include attribution:** ``` --- *Multi-AI Implementation powered by Claude Octopus* *Providers: 🔴 Codex | 🟡 Gemini | 🔵 Claude*