Architecture: Models, Providers, and Execution Flow

This document explains how Kannaktopus orchestrates multiple AI providers and the execution flow of each workflow.

Overview

Kannaktopus coordinates eight AI providers — one per tentacle to give you multi-perspective analysis:

    +------------------+
    |   Claude Code    |  <-- Orchestrator (you talk to this)
    +--------+---------+
             |
    +--------v---------+
    | Kannaktopus   |  <-- Plugin coordinates providers
    +--------+---------+
             |
  +--+---+---+---+---+--+
  |  |   |   |   |   |  |
+-v--+ +-v-+ +v+ +v+ +v-+  +--v--+  +-v----+
|Cdx | |Gem| |Cl| |Pp| |OR|  |Ollma|  |Coplt |
|CLI | |CLI| |AI| |API |API|  |local|  |aspir.|
+----+ +---+ +--+ +--+ +--+  +-----+  +------+
  Core (5 providers)          Optional (2, fully wired)

Provider → Model Mapping

Note: Models are as of March 2026. The orchestrate.sh script uses the latest available models. Only Claude is required — all others are optional and auto-detected.

What Each Provider Excels At

Execution Flow by Workflow

Discover Phase (probe)

Trigger: octo research X or /octo:discover

User Request
     |
     v
+--------------------+
|   Kannaktopus   |
|    Orchestrator    |
+---------+----------+
          |
    +-----+-----+
    |           |
    v           v
+-------+   +-------+
| Codex |   |Gemini |   <- Run in PARALLEL
| CLI   |   | CLI   |
+---+---+   +---+---+
    |           |
    v           v
"Technical   "Ecosystem
 analysis"    research"
    |           |
    +-----+-----+
          |
          v
    +----------+
    |  Claude  |   <- SEQUENTIAL (after both complete)
    | Synthesis|
    +----------+
          |
          v
    Final Research
       Report

Execution:

1. Codex CLI and Gemini CLI run in parallel with the research prompt
2. Both responses are collected
3. Claude synthesizes both perspectives into a unified report

Typical duration: 30-60 seconds Typical cost: $0.01-0.05 (depending on prompt length)

Define Phase (grasp)

Trigger: octo define X or /octo:define

User Request
     |
     v
+--------------------+
|   Kannaktopus   |
+---------+----------+
          |
          v
    +-----------+
    |   Codex   |   <- Step 1: Problem statement
    +-----------+
          |
          v
    +-----------+
    |  Gemini   |   <- Step 2: Success criteria
    +-----------+
          |
          v
    +-----------+
    |  Gemini   |   <- Step 3: Constraints
    +-----------+
          |
          v
    +-----------+
    |  Gemini   |   <- Step 4: Build consensus
    | Consensus |
    +-----------+
          |
          v
   Problem Definition
    + Requirements

Execution: (Sequential for coherent problem definition)

1. Codex defines the core problem statement (2-3 sentences)
2. Gemini defines success criteria (3-5 measurable criteria)
3. Gemini defines constraints and boundaries
4. Gemini synthesizes all perspectives into unified requirements

Develop Phase (tangle)

Trigger: octo build X or /octo:develop

User Request
     |
     v
+--------------------+
|   Kannaktopus   |
+---------+----------+
          |
    +-----+-----+
    |           |
    v           v
+-------+   +-------+
| Codex |   |Gemini |   <- PARALLEL: Implementation proposals
+---+---+   +---+---+
    |           |
    v           v
"Approach A" "Approach B"
    |           |
    +-----+-----+
          |
          v
    +----------+
    |  Claude  |
    |  Merge   |
    +----------+
          |
          v
    +----------+
    | Quality  |   <- 75% CONSENSUS GATE
    |   Gate   |
    +----------+
       |     |
   PASS?    FAIL?
       |     |
       v     v
   Continue  Revise

Execution:

1. Codex and Gemini each propose implementation approaches
2. Claude merges the best elements from both
3. Quality Gate checks if merged approach meets 75% consensus threshold
4. If failed: Loop back for revision
5. If passed: Proceed to implementation

Quality Gate: The quality gate is based on subtask success rate:

• Measures: percentage of subtasks that completed successfully
• Threshold: 75% (configurable via CLAUDE_OCTOPUS_QUALITY_THRESHOLD)
• If failed: Can retry, escalate to human review, or abort

Deliver Phase (ink)

Trigger: octo review X or /octo:deliver

User Request
     |
     v
+--------------------+
|   Kannaktopus   |
+---------+----------+
          |
    +-----+-----+
    |           |
    v           v
+-------+   +-------+
| Codex |   |Gemini |   <- PARALLEL: Different review angles
+---+---+   +---+---+
    |           |
    v           v
"Code quality""Security &
 review"       edge cases"
    |           |
    +-----+-----+
          |
          v
    +----------+
    |  Claude  |
    | Validate |
    +----------+
          |
          v
    +----------+
    | Quality  |
    |  Score   |
    +----------+
          |
          v
   Validation Report
   + Go/No-Go Decision

Execution:

1. Codex reviews code quality, patterns, maintainability
2. Gemini reviews security, edge cases, compliance
3. Claude synthesizes into validation report
4. Quality score determines go/no-go recommendation

Validation Thresholds:

Debate (grapple)

Trigger: octo debate X vs Y or /octo:debate

User Question
     |
     v
+--------------------+
|   Kannaktopus   |
+---------+----------+
          |
     Round 1
    +-----+-----+
    |     |     |
    v     v     v
+-----+ +-----+ +-----+
|Codex| |Gemin| |Claud|  <- All 3 PARALLEL
+--+--+ +--+--+ +--+--+
   |       |       |
   v       v       v
"Pro X"  "Pro Y" "Moderator
                  analysis"
   |       |       |
   +---+---+---+---+
       |       |
     Round 2 (optional)
       |
       v
   +-------+
   |Claude |
   |Synth. |
   +-------+
       |
       v
  Final Verdict
  + Recommendation

Execution:

1. Round 1: All three providers argue their positions in parallel
2. Round 2+ (optional): Rebuttals and counter-arguments
3. Synthesis: Claude moderates and produces final verdict

Debate Styles:

Full Workflow (embrace)

Trigger: /octo:embrace

User Request
     |
     v
+---------+
| DISCOVER|  <- Phase 1
+---------+
     |
     v
+---------+
|  DEFINE |  <- Phase 2
+---------+
     |
     v
+---------+
| DEVELOP |  <- Phase 3 (with quality gate)
+---------+
     |
     v
+---------+
| DELIVER |  <- Phase 4
+---------+
     |
     v
  Complete
  Feature

Execution: All four phases run sequentially. Each phase uses the output of the previous phase as context.

Typical duration: 2-5 minutes Typical cost: $0.10-0.30

Cost Breakdown

Per-Query Estimates

Note: Claude costs are included in your Claude Code subscription (Pro, Max 5x, Max 20x).

Cost Optimization

Provider Detection

Kannaktopus auto-detects which providers are available:

# Check status
/octo:setup

# Output example:
# Providers:
#   Codex CLI: ready (OPENAI_API_KEY found)
#   Gemini CLI: ready (OAuth authenticated)

Graceful Degradation

Visual Indicators

When multi-AI mode is active, you'll see these indicators:

Example output:

🐙 KANNAKTOPUS ACTIVATED - Multi-provider research mode
🔍 Discover Phase: Researching authentication patterns

🔴 Codex CLI: Analyzing implementation patterns...
🟡 Gemini CLI: Researching ecosystem best practices...
🔵 Claude: Synthesizing perspectives...

[Final synthesis report]

Under the Hood: orchestrate.sh

All workflows are powered by scripts/orchestrate.sh:

# Direct CLI usage (advanced)
./scripts/orchestrate.sh probe "research OAuth patterns"
./scripts/orchestrate.sh tangle "implement authentication"
./scripts/orchestrate.sh ink "review auth code"
./scripts/orchestrate.sh embrace "complete auth feature"

The plugin wraps these commands and provides:

• Natural language triggers
• Session management
• Result storage
• Quality gates

See Also

• Command and Usage Reference - Commands, triggers, and provider indicators
• Documentation Guide - Docs landing page
• Command Reference - All available commands