octopus-architecture · diff
git:20260813.14437ae to git:20260906.89d2d35
33 added, 165 removed. Audit A to A.
---
name: octopus-architecture
- description: "System architecture and API design with multi-AI consensus — use for design reviews and new subsystems"
+ description: "Review system architecture, simplify boundaries, or compare interface designs from repository evidence"
disable-model-invocation: true
---
> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex.
> Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands.
> Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it.
> For host tool equivalents, see `skills/blocks/codex-host-adapter.md`.
- ## ⚠️ EXECUTION CONTRACT (MANDATORY - CANNOT SKIP)
-
- This skill uses **ENFORCED execution mode**. You MUST follow this exact sequence.
-
- ### STEP 1: Display Visual Indicators (MANDATORY - BLOCKING)
-
- **Check provider availability:**
-
- ```bash
- providers_output="$("${HOME}/.claude-octopus/plugin/scripts/helpers/check-providers.sh" 2>/dev/null || true)"
- provider_status() {
- provider="$1"
- if printf '%s\n' "$providers_output" | grep -q "^${provider}:available"; then
- echo "Available ✓"
- else
- echo "Not installed ✗"
- fi
- }
- codex_status="$(provider_status codex)"
- agy_status="$(provider_status agy)"
- agy_status="$(provider_status agy)"
- ```
-
- **Display this banner BEFORE orchestrate.sh execution:**
-
- ```
- 🐙 **CLAUDE OCTOPUS ACTIVATED** - Architecture design mode
- 🏗️ Architecture: [Brief description of system to design]
-
- Provider Availability:
- 🔴 Codex CLI: ${codex_status} - Backend architecture patterns
- 🟡 Antigravity CLI: ${agy_status} - Alternative approaches
- 🧭 Antigravity CLI: ${agy_status} - Additional external-model challenge
- 🔵 Claude: Available ✓ - Synthesis and recommendations
-
- 💰 Estimated Cost: $0.02-0.08
- ⏱️ Estimated Time: 3-7 minutes
- ```
-
- **Validation:**
- - If no external providers are available → STOP, suggest: `/octo:setup`
- - If one or more external providers are available → Continue with available provider(s)
-
- **DO NOT PROCEED TO STEP 2 until banner displayed.**
-
-
- ### STEP 2: Execute orchestrate.sh spawn (MANDATORY - Use Bash Tool)
-
- **You MUST execute this command via the native shell command tool:**
-
- ```bash
- ${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh spawn backend-architect "<user's architecture request>"
- ```
-
- **CRITICAL: You are PROHIBITED from:**
- - ❌ Designing architecture directly without calling orchestrate.sh
- - ❌ Using direct analysis as a substitute
- - ❌ Claiming you're "simulating" the workflow
- - ❌ Proceeding to Step 3 without running this command
-
- **This is NOT optional. You MUST use the native shell command tool to invoke orchestrate.sh.**
-
-
- ### STEP 3: Verify Execution (MANDATORY - Validation Gate)
-
- **After orchestrate.sh completes, verify it succeeded:**
-
- ```bash
- # Check for persona output (varies by persona type)
- # For spawn commands, check exit code and output
- if [ $? -ne 0 ]; then
- echo "❌ VALIDATION FAILED: orchestrate.sh spawn failed"
- exit 1
- fi
-
- echo "✅ VALIDATION PASSED: Architecture design completed"
- ```
-
- **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 design
-
-
- ### STEP 4: Present Results (Only After Steps 1-3 Complete)
-
- Present the architecture design from the persona execution.
-
- **Include attribution:**
- ```
- *Multi-AI Architecture Design powered by Claude Octopus*
- *Providers: available external providers + 🔵 Claude*
- ```
-
-
- # Architecture Skill
-
- Invokes the backend-architect persona for system design during the `grasp` (define) and `tangle` (develop) phases.
-
- ## Usage
-
- ```bash
- # Via orchestrate.sh
- ${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh spawn backend-architect "Design a scalable notification system"
-
- # Via auto-routing (detects architecture intent)
- ${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "architect the event-driven messaging system"
- ```
-
- ## Capabilities
-
- - API design and RESTful patterns
- - Microservices architecture
- - Distributed systems design
- - Event-driven architecture
- - Database schema design
- - Scalability planning
-
- ## Persona Reference
-
- This skill wraps the `backend-architect` persona defined in:
- - `agents/personas/backend-architect.md`
- - CLI: `codex`
- - Model: `gpt-5.3-codex`
- - Phases: `grasp`, `tangle`
- - Expertise: `api-design`, `microservices`, `distributed-systems`
-
- ## Example Prompts
-
- ```
- "Design the API contract for the user service"
- "Plan the event sourcing architecture"
- "Design the caching strategy for the product catalog"
- "Create a microservices decomposition plan"
- ```
+ # Architecture review
- ## LSP Integration (Claude Code 2.1.14+)
+ Run this method on the current host. A routine architecture review makes zero additional provider dispatches.
+ `--peer-review`, an explicit independent-review
+ request, or an existing risk policy may add one bounded external reviewer through
+ Octopus routing. Report incomplete independent coverage if that reviewer cannot
+ read the source or does not return a grounded contribution.
- For enhanced structural awareness during architecture design, leverage Claude Code's LSP tools:
+ ## Method
- ### Recommended LSP Tool Usage
+ Read and apply `skills/blocks/architecture-simplification.md` from the installed
+ plugin root. Pin the source revision and inspect implementation, callers, tests,
+ recent churn, and failure behavior before recommending a boundary.
- 1. **Before defining architecture**, gather structural context:
- ```
- lsp_document_symbols - Understand existing module structure
- lsp_find_references - Identify current dependencies
- lsp_workspace_symbols - Find related patterns across codebase
- ```
+ For a single simplification, produce one evidence-backed interface. For a design
+ choice, produce two alternatives from the same immutable requirements:
- 2. **During design validation**:
- ```
- lsp_goto_definition - Verify interface contracts
- lsp_hover - Check type signatures
- lsp_diagnostics - Identify type/interface mismatches
- ```
+ - Draft A minimizes caller knowledge and configuration.
+ - Draft B makes the next demonstrated extension easier.
- ### Example Workflow
+ Label two host-generated drafts as correlated alternatives from one model. If an
+ independent reviewer is authorized, send it the same source and requirements but
+ not Draft A before its first response. Transport diversity does not prove model
+ family diversity. Unknown family means unknown independence.
- ```typescript
- // Step 1: Understand existing structure
- const symbols = await lsp_document_symbols("src/services/user.ts")
- const references = await lsp_find_references("UserService", line=5, char=10)
+ ## Completion
- // Step 2: Identify patterns in codebase
- const patterns = await lsp_workspace_symbols("Service")
+ Return `Evidence`, `Caller contract`, `Proposed interface`, `Migration`, `Test
+ impact`, and `Decision`. The decision is `keep`, `simplify`, or `investigate`.
+ `simplify` requires exact source evidence and a concrete caller example. A design
+ review never authorizes an automatic refactor.
- // Step 3: Design new architecture informed by existing patterns
- // ... architecture design ...
+ ## LSP Integration
- // Step 4: Validate design with diagnostics
- const issues = await lsp_diagnostics("src/services/*.ts")
- ```
+ When the host exposes language-server tools, use document symbols, workspace
+ symbols, definitions, and references to confirm module boundaries and caller
+ relationships before proposing an interface. Treat LSP results as an index:
+ verify consequential claims against source and tests, and fall back to
+ repository search when the language server is unavailable or incomplete.
- This ensures architecture recommendations align with existing codebase patterns and type contracts.
+ Adapted from `codebase-design` and `DESIGN-IT-TWICE` in `mattpocock/skills` at
+ commit `3cca18b368ae95cdbdebbff572ccafa662551015` under the MIT License. See
+ `THIRD_PARTY_NOTICES.md`.