Explore

Codebase Exploration

Multi-angle codebase exploration using 3-5 parallel agents.

🎯 Quick Start

/ork:explore authentication

Opus 4.8: Exploration agents use native adaptive thinking for deeper pattern recognition across large codebases.

---

STEP -0.5: Effort-Aware Agent Scaling (CC 2.1.120+)

Read ${CLAUDE_EFFORT} to scale exploration depth before any other decision.

# CC 2.1.120+ env var; explicit --effort= overrides
EFFORT = os.environ.get("CLAUDE_EFFORT")
for token in "$ARGUMENTS".split():
    if token.startswith("--effort="):
        EFFORT = token.split("=", 1)[1]
EFFORT = EFFORT or "high"  # default

Override gate: if the user passes --effort=high explicitly while ${CLAUDE_EFFORT} is low, the flag wins. /ork:doctor warns when xhigh is requested without Opus 4.8.

---

STEP 0: Verify User Intent with AskUserQuestion

BEFORE creating tasks, clarify what the user wants to explore:

AskUserQuestion(
  questions=[{
    "question": "What aspect do you want to explore?",
    "header": "Focus",
    "options": [
      {"label": "Full exploration (Recommended)", "description": "Code structure + data flow + architecture + health assessment"},
      {"label": "Quick scan", "description": "Find relevant files + structure, skip deep analysis"},
      {"label": "Data flow", "description": "Trace how data moves through the system"},
      {"label": "Architecture patterns", "description": "Identify design patterns and integrations"}
    ],
    "multiSelect": false
  }]
)

Based on answer, adjust workflow:

• Full exploration: All phases, all parallel agents
• Quick scan: Files + structure only (phases 1-2), skip health/deps/product — no deep agents
• Data flow: Focus phase 3 agents on data tracing
• Architecture patterns: Focus on backend-system-architect agent

---

STEP 0b: Select Orchestration Mode

MCP Probe

# memory is alwaysLoad in .mcp.json (CC 2.1.121+, #1541) — probe below kept as fallback for older CC:
ToolSearch(query="select:mcp__memory__search_nodes")
Write(".claude/chain/capabilities.json", { memory, timestamp })

if capabilities.memory:
  mcp__memory__search_nodes({ query: "architecture decisions for {path}" })
  # Enrich exploration with past decisions

Exploration Handoff

After exploration completes, write results for downstream skills:

Write(".claude/chain/exploration.json", JSON.stringify({
  "phase": "explore", "skill": "explore",
  "timestamp": now(), "status": "completed",
  "outputs": {
    "architecture_map": { ... },
    "patterns_found": ["repository", "service-layer"],
    "complexity_hotspots": ["src/auth/", "src/payments/"]
  }
}))

---

Choose Agent Teams (mesh) or Task tool (star):

1. Agent Teams mode (GA since CC 2.1.33) → recommended for 4+ agents 2. Task tool mode → for quick/single-focus exploration 3. ORCHESTKIT_FORCE_TASK_TOOL=1 → Task tool (override)

Fallback: If Agent Teams encounters issues, fall back to Task tool for remaining exploration.

---

🚨 Task Management (MANDATORY)

BEFORE doing ANYTHING else, create tasks to show progress:

# 1. Create main task IMMEDIATELY
TaskCreate(subject="Explore: {topic}", description="Deep codebase exploration for {topic}", activeForm="Exploring {topic}")

# 2. Create subtasks for each phase
TaskCreate(subject="Initial file search", activeForm="Searching files")                # id=2
TaskCreate(subject="Check knowledge graph", activeForm="Checking memory")              # id=3
TaskCreate(subject="Launch exploration agents", activeForm="Dispatching explorers")     # id=4
TaskCreate(subject="Assess code health (0-10)", activeForm="Assessing code health")    # id=5
TaskCreate(subject="Map dependency hotspots", activeForm="Mapping dependencies")       # id=6
TaskCreate(subject="Add product perspective", activeForm="Adding product context")     # id=7
TaskCreate(subject="Generate exploration report", activeForm="Generating report")      # id=8

# 3. Set dependencies for sequential phases
TaskUpdate(taskId="3", addBlockedBy=["2"])  # Memory check needs file search first
TaskUpdate(taskId="4", addBlockedBy=["3"])  # Agents need memory context
TaskUpdate(taskId="5", addBlockedBy=["4"])  # Health needs exploration done
TaskUpdate(taskId="6", addBlockedBy=["4"])  # Hotspots need exploration done
TaskUpdate(taskId="7", addBlockedBy=["4"])  # Product needs exploration done
TaskUpdate(taskId="8", addBlockedBy=["5", "6", "7"])  # Report needs all analysis done

# 4. Before starting each task, verify it's unblocked
task = TaskGet(taskId="2")  # Verify blockedBy is empty

# 5. Update status as you progress
TaskUpdate(taskId="2", status="in_progress")  # When starting
TaskUpdate(taskId="2", status="completed")    # When done — repeat for each subtask

---

🔄 Workflow Overview

Progressive Output (CC 2.1.76)

Output findings incrementally as each phase completes — don't batch until the report:

For Phase 3 parallel agents, output each agent's findings as soon as it returns — don't wait for all 4 explorers. Early findings from one agent may answer the user's question before remaining agents complete, allowing early termination.

---

Phase 1: Initial Search

# PARALLEL - Quick searches
Grep(pattern="$ARGUMENTS[0]", output_mode="files_with_matches")
Glob(pattern="**/*$ARGUMENTS[0]*")

Phase 2: Memory Check

mcp__memory__search_nodes(query="$ARGUMENTS[0]")
mcp__memory__search_nodes(query="architecture")

Phase 3: Parallel Deep Exploration (4 Agents)

Load Read("${CLAUDE_SKILL_DIR}/rules/exploration-agents.md") for Task tool mode prompts.

Load Read("${CLAUDE_SKILL_DIR}/rules/agent-teams-mode.md") for Agent Teams alternative.

Phase 4: AI System Exploration (If Applicable)

For AI/ML topics, add exploration of: LangGraph workflows, prompt templates, RAG pipeline, caching strategies.

Phase 5: Code Health Assessment

Load Read("${CLAUDE_SKILL_DIR}/rules/code-health-assessment.md") for agent prompt. Load Read("${CLAUDE_SKILL_DIR}/references/code-health-rubric.md") for scoring criteria.

Phase 6: Dependency Hotspot Map

Load Read("${CLAUDE_SKILL_DIR}/rules/dependency-hotspot-analysis.md") for agent prompt. Load Read("${CLAUDE_SKILL_DIR}/references/dependency-analysis.md") for metrics.

Phase 7: Product Perspective

Load Read("${CLAUDE_SKILL_DIR}/rules/product-perspective.md") for agent prompt. Load Read("${CLAUDE_SKILL_DIR}/references/findability-patterns.md") for best practices.

Phase 8: Generate Report

Load Read("${CLAUDE_SKILL_DIR}/references/exploration-report-template.md").

Phase 8b: Emit Dashboard Spec (json-render)

Parse --render= from $ARGUMENTS. Default is both.

When emitting a spec:

1. Load the format and catalog: Read("${CLAUDE_SKILL_DIR}/references/dashboard-spec.md"). Reference example: references/dashboard-example.json. 2. Build the spec object using only catalog component types: Card, StatGrid, DataTable, StatusBadge, BarMeter, Heatmap, Markdown. 3. Write to .claude/chain/explore-dashboard.json with compact JSON (no indentation) — minimizes token cost for downstream consumers. 4. Validate before declaring success:

node "${CLAUDE_SKILL_DIR}/scripts/render-spec.mjs" .claude/chain/explore-dashboard.json --check

If validation fails (exit ≠ 0), do not emit — fall back to markdown-only and surface the error to the user. Never write a partial or invalid spec.

5. For --render=both, render the markdown view from the spec for consistency:

node "${CLAUDE_SKILL_DIR}/scripts/render-spec.mjs" .claude/chain/explore-dashboard.json

Pipe the output into the user-facing markdown report (or use it as-is). This guarantees the JSON spec and markdown report stay in sync — a single source of truth.

Why this matters: Downstream skills (/ork:fix-issue, /ork:implement, /ork:create-pr) parse .claude/chain/explore-dashboard.json directly instead of re-reading 3000-token markdown. Measured: spec ≈ 580 tokens for the same content. Backwards-compatible: old chained workflows that read markdown keep working in both mode.

Phase 6.5 — Notebook summary (signal-fired, optional)

After the session synthesis lands, optionally invoke scripts/post_explore_summary.py <session-dir> to auto-emit a notebook-backed summary of the exploration. Self-skips on every non-happy-path so it never breaks the run:

python3 ${CLAUDE_SKILL_DIR}/scripts/post_explore_summary.py "$CLAUDE_JOB_DIR"

Auto-skip conditions (all exit 0, all WARN-logged):

Session dir must contain explore-output.json (with dirs_scanned: list[str], optional synthesis: str, required notebook_id: str). Handoff JSON at <session-dir>/explore-summary.json records status (fired / skipped) and summary_path on success.

Mirrors the /ork:brainstorm post-synth podcast pattern from PR #1889. Closes orchestkit#1893.

Notes for long explorations

Oversized reads (CC 2.1.144+): Read returns a [PARTIAL view] truncated first page (not a hard error) when a whole-file read exceeds the token limit. When traversing large files, detect that notice and re-read with explicit offset/limit to page through the rest — never treat the partial as the full file.

When context fills (CC 2.1.141+): Use the rewind menu's "Summarize up to here" to compress earlier turns while keeping recent context, instead of restarting. Reactive compaction (CC 2.1.142+) now sizes the first summarize to the actual overflow, so a second mid-turn pass is rare.

Common Exploration Queries

• "How does authentication work?"
• "Where are API endpoints defined?"
• "Find all usages of EventBroadcaster"
• "What's the workflow for content analysis?"

Running unattended with /goal

Set a completion condition with /goal (CC 2.1.139+) and this skill will keep working across turns until the condition is met. Works in interactive, -p, and Remote Control. The overlay panel shows live elapsed / turns / tokens.

Example completion condition for this skill:

/goal until report.has_architecture_diagram AND patterns.detected_count >= 5

Stops when: codebase architecture diagram is generated and at least 5 design patterns have been classified. Compatible with claude.ai Remote Control runs.

📜 Related Skills

• ork:implement: Implement after exploration

---

Version: 2.6.0 (April 2026) — ${CLAUDE_EFFORT} env var scales agent count (CC 2.1.120, #1540)

Exploration Report: {{TOPIC}}

Generated: {{DATE}} Explorer: {{AGENT}}

---

Overview

{{BRIEF_SUMMARY}}

---

Architecture

{{ASCII_ARCHITECTURE_DIAGRAM}}

Key Components:

• {{COMPONENT_1}}: {{PURPOSE_1}}
• {{COMPONENT_2}}: {{PURPOSE_2}}

---

Entry Points

Search Keywords: {{KEYWORD_1}}, {{KEYWORD_2}}, {{KEYWORD_3}}

---

Health Assessment

Hotspots:

• {{FILE}}:{{LINE}} - {{ISSUE}}

---

Dependency Map

{{HOTSPOT_DIAGRAM}}

• Coupling Score: {{SCORE}}/10
• Fan-In: {{N}} files depend on this
• Fan-Out: {{M}} dependencies
• Circular Dependencies: {{LIST_OR_NONE}}

---

Recommendations

1. Immediate: {{ACTION_1}} 2. Short-term: {{ACTION_2}} 3. Long-term: {{ACTION_3}}

---

How to Modify

1. {{STEP_1}} 2. {{STEP_2}} 3. {{STEP_3}}

---

Related Resources

• {{LINK_1}}
• {{LINK_2}}

Dependency Hotspot Diagram Templates

Basic Dependency Graph

                    ┌──────────────┐
                    │   Target     │
                    │   Module     │
                    └──────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
    ┌──────────┐    ┌──────────┐    ┌──────────┐
    │  Dep A   │    │  Dep B   │    │  Dep C   │
    └──────────┘    └──────────┘    └──────────┘

Fan-In / Fan-Out Chart

Fan-In (Dependents)        Fan-Out (Dependencies)
━━━━━━━━━━━━━━━━━━━        ━━━━━━━━━━━━━━━━━━━━━
module_a.py  ████████ 8    lib_x       ██████ 6
module_b.py  ██████ 6      lib_y       ████ 4
module_c.py  ████ 4        lib_z       ██ 2
module_d.py  ██ 2          internal    █ 1

Coupling Matrix

             │ auth │ user │ api │ db │
─────────────┼──────┼──────┼─────┼────┤
auth         │  -   │  X   │  X  │  X │
user         │  X   │  -   │  X  │  X │
api          │      │      │  -  │    │
db           │      │      │     │  - │

X = bidirectional dependency (potential circular)

Circular Dependency Visualization

    ┌─────────────────────────────┐
    │                             │
    ▼                             │
┌───────┐     ┌───────┐     ┌───────┐
│   A   │────▶│   B   │────▶│   C   │
└───────┘     └───────┘     └───────┘
    ▲                             │
    │                             │
    └─────────────────────────────┘
    CIRCULAR: A → B → C → A

Change Impact Blast Radius

                    [CHANGED FILE]
                          │
         ┌────────────────┼────────────────┐
         │                │                │
    [Direct: 3]     [Direct: 5]     [Direct: 2]
         │                │
    ┌────┴────┐      ┌────┴────┐
    │         │      │         │
[Trans: 2] [Trans: 4] [Trans: 1] [Trans: 3]

Total Impact: 3 + 5 + 2 = 10 direct
              2 + 4 + 1 + 3 = 10 transitive

Code Health Rubric

Standardized 0-10 scoring criteria for assessing code quality across five dimensions.

Scoring Scale

---

1. Readability (0-10)

2. Maintainability (0-10)

3. Testability (0-10)

4. Complexity (0-10, inverted: 10=simple)

5. Documentation (0-10)

---

Overall Score Calculation

overall = (readability + maintainability + testability + complexity + documentation) / 5

Score Interpretation:

• 8.0+: Ship it
• 6.0-7.9: Acceptable, plan improvements
• 4.0-5.9: Technical debt, prioritize refactoring
• <4.0: Stop and fix before proceeding

Exploration Dashboard Spec

When --render=json-render or --render=both is passed to /ork:explore, Phase 8 emits a json-render-compatible JSON spec to .claude/chain/explore-dashboard.json instead of (or in addition to) the markdown report.

The spec follows the flat element-map format documented in ork:mcp-visual-output — { root, elements } with each element keyed by id and referencing children by id. This is the format consumed by @json-render/mcp 0.17+ when an MCP host iframe-renders it, and is also consumable by downstream skills as a structured handoff.

Catalog

These are the only component types the spec is allowed to use. They map to @json-render/shadcn registry entries when rendered visually.

trend enum: up | down | flat. color enum: green | red | yellow | blue | gray.

Elements may reference children only by id from the same elements map. Recursion is bounded — Cards can contain other Cards but no deeper than 2 levels.

Example

A complete spec for /ork:explore authentication:

{
  "root": "report",
  "version": "1.0.0",
  "skill": "explore",
  "topic": "authentication",
  "elements": {
    "report": {
      "type": "Card",
      "props": { "title": "Exploration Report — authentication" },
      "children": ["summary", "health", "deps", "files"]
    },
    "summary": {
      "type": "StatGrid",
      "props": {
        "items": [
          { "label": "Files matched", "value": "23" },
          { "label": "Health score", "value": "7.4/10", "color": "green" },
          { "label": "Coupling", "value": "Medium", "color": "yellow" },
          { "label": "Patterns", "value": "service-layer, repository" }
        ]
      }
    },
    "health": {
      "type": "Card",
      "props": { "title": "Code Health" },
      "children": ["health-readability", "health-maintainability", "health-testability"]
    },
    "health-readability": { "type": "BarMeter", "props": { "label": "Readability", "value": 8.0, "color": "green" } },
    "health-maintainability": { "type": "BarMeter", "props": { "label": "Maintainability", "value": 7.0, "color": "green" } },
    "health-testability": { "type": "BarMeter", "props": { "label": "Testability", "value": 6.5, "color": "yellow" } },
    "deps": {
      "type": "Card",
      "props": { "title": "Dependency Hotspots" },
      "children": ["deps-table"]
    },
    "deps-table": {
      "type": "DataTable",
      "props": {
        "columns": [
          { "key": "file", "label": "File" },
          { "key": "fanin", "label": "Fan-in" },
          { "key": "fanout", "label": "Fan-out" },
          { "key": "score", "label": "Coupling" }
        ],
        "rows": [
          { "file": "src/auth/session.ts", "fanin": "12", "fanout": "4", "score": "high" },
          { "file": "src/auth/jwt.ts", "fanin": "8", "fanout": "2", "score": "med" }
        ]
      }
    },
    "files": {
      "type": "DataTable",
      "props": {
        "columns": [
          { "key": "file", "label": "File" },
          { "key": "purpose", "label": "Purpose" },
          { "key": "score", "label": "Health" }
        ],
        "rows": [
          { "file": "src/auth/session.ts", "purpose": "Session tokens + refresh", "score": "8.0" },
          { "file": "src/auth/jwt.ts", "purpose": "JWT sign/verify wrapper", "score": "7.5" }
        ]
      }
    }
  }
}

Token cost (measured, not promised)

The example above serializes to ~700 tokens (compact JSON). The equivalent markdown report from references/exploration-report-template.md is ~3000 tokens when filled with the same content, mostly because of repeated table syntax and ASCII art.

The savings show up when downstream skills (e.g., /ork:fix-issue, /ork:implement) parse this spec from .claude/chain/explore-dashboard.json instead of re-reading the human-facing markdown. The markdown still gets written for the human reader when --render=both (the default for /ork:explore).

Validation

The companion script scripts/render-spec.mjs validates the spec on emission:

• All children ids resolve in elements
• Component types are in the catalog
• Required props are present
• BarMeter values are in [0, 10]
• DataTable rows match column keys

Validation failure aborts emission with a non-zero exit. The skill MUST fall back to markdown when validation fails — never emit a partial or invalid spec.

How downstream skills consume it

spec = JSON.parse(Read(".claude/chain/explore-dashboard.json"))
hotspots = spec.elements["deps-table"].props.rows  # structured rows
overall_health = spec.elements["summary"].props.items[1].value  # "7.4/10"

No regex. No markdown table parsing. The spec is the structured handoff; the markdown is the human view.

Dependency Analysis

Identify coupling hotspots and dependency patterns in codebases.

Fan-In / Fan-Out Metrics

Ideal Patterns:

• Core utilities: High fan-in, low fan-out (stable)
• Feature modules: Low fan-in, moderate fan-out
• Entry points: Low fan-in, high fan-out

---

Hotspot Identification

High-Risk Indicators

Coupling Score Formula

coupling_score = min(10, (fan_in + fan_out) / 3)

• 0-3: Low coupling (healthy)
• 4-6: Moderate coupling (monitor)
• 7-10: High coupling (refactor)

---

Circular Dependency Detection

Signs of Circular Dependencies: 1. Import errors at runtime 2. Mysterious None values 3. Files that always change together 4. Cannot extract to separate package

Detection Approach:

A imports B
B imports C
C imports A  <- CIRCULAR

Resolution Strategies: 1. Extract shared interface 2. Dependency inversion (depend on abstractions) 3. Merge tightly coupled modules 4. Event-driven decoupling

---

Change Impact Analysis

Questions to Answer: 1. If I modify this file, what breaks? 2. Which files always change together? 3. What is the blast radius of a refactor?

Measuring Impact:

• Direct Impact: Files importing the changed module
• Transitive Impact: Files importing those files
• Co-Change Frequency: Git history of files changed together

High Impact Indicators:

• > 5 direct dependents
• > 20 transitive dependents
• > 80% co-change frequency with another file

Exploration Report Template

Use this template for Phase 8 report generation.

# Exploration Report: $ARGUMENTS

## Quick Answer
[1-2 sentence summary]

## File Locations
| File | Purpose | Health Score |
|------|---------|--------------|
| `path/to/file.py` | [description] | [N.N/10] |

## Code Health Summary
| Dimension | Score | Notes |
|-----------|-------|-------|
| Readability | [N/10] | [note] |
| Maintainability | [N/10] | [note] |
| Testability | [N/10] | [note] |
| Complexity | [N/10] | [note] |
| Documentation | [N/10] | [note] |
| **Overall** | **[N.N/10]** | |

## Architecture Overview
[ASCII diagram]

## Dependency Hotspot Map

[Incoming deps] → [TARGET] → [Outgoing deps]

- **Coupling Score:** [N/10]
- **Fan-in:** [N] files depend on this
- **Fan-out:** [M] dependencies
- **Circular Dependencies:** [list or "None"]

## Data Flow
1. [Entry] → 2. [Processing] → 3. [Storage]

## Findability & Entry Points
| Entry Point | Why Start Here |
|-------------|----------------|
| `path/to/file.py` | [reason] |

**Search Keywords:** [keyword1], [keyword2], [keyword3]

## Product Context
- **Business Purpose:** [what problem this solves]
- **Primary Users:** [who uses this]
- **Documentation Gaps:** [what's missing]

## How to Modify
1. [Step 1]
2. [Step 2]

## Recommendations
1. [Health improvement]
2. [Findability improvement]
3. [Documentation improvement]

Findability Patterns

Improve code discoverability for developers exploring the codebase.

Naming Conventions for Searchability

Anti-Patterns:

• Abbreviations: usr, mgr, svc (hard to search)
• Generic names: utils.py, helpers.js (too broad)
• Inconsistent casing: getUserData, get_user_data

---

Documentation Placement

Entry Point Strategy: 1. Every directory should have a README or index 2. Complex modules need architecture diagrams 3. Public APIs need usage examples 4. Workflows need sequence diagrams

---

Module Organization

Vertical Slice Architecture

features/
  auth/
    api.py          # Entry point
    service.py      # Business logic
    repository.py   # Data access
    models.py       # Domain models
    tests/          # Co-located tests

Benefits:

• Related code together
• Easy to find all auth-related files
• Clear boundaries

Horizontal Layer Architecture

api/
  auth.py
  users.py
services/
  auth.py
  users.py

Benefits:

• Technical cohesion
• Easier cross-cutting concerns

---

Improving Discoverability

Quick Wins

1. Add index files: Export public API from __init__.py or index.ts 2. Use consistent prefixes: handle_, on_, create_, get_ 3. Create README per directory: Brief purpose + key files 4. Tag with keywords: Add searchable comments for concepts

Search Optimization

# Keywords: authentication, login, JWT, OAuth, session
# See also: user_service.py, token_handler.py

Metadata in Files:

• Related files cross-reference
• Alternative terms for the concept
• Links to documentation

Rule Categories

1. Agent Orchestration -- HIGH -- 2 rules

Patterns for spawning and coordinating parallel exploration agents.

• agent-teams-mode.md -- Multi-agent team formation with real-time discovery sharing
• exploration-agents.md -- Task tool mode with 4 parallel background explorers

2. Code Analysis -- MEDIUM -- 3 rules

Specialized assessment prompts for code quality and architecture analysis.

• code-health-assessment.md -- Five-dimension code quality scoring (0-10)
• dependency-hotspot-analysis.md -- Coupling detection and change impact analysis
• product-perspective.md -- Business context and findability assessment

Agent Teams Mode

In Agent Teams mode, form an exploration team where explorers share discoveries in real-time:

TeamCreate(team_name="explore-{topic}", description="Explore {topic}")

Agent(subagent_type="Explore", name="structure-explorer",
     team_name="explore-{topic}",
     prompt="""Find all files, classes, and functions related to: {topic}
     When you discover key entry points, message data-flow-explorer so they
     can trace data paths from those points.
     When you find backend patterns, message backend-explorer.
     When you find frontend components, message frontend-explorer.""")

Agent(subagent_type="Explore", name="data-flow-explorer",
     team_name="explore-{topic}",
     prompt="""Trace entry points, processing, and storage for: {topic}
     When structure-explorer shares entry points, start tracing from those.
     When you discover cross-boundary data flows (frontend→backend or vice versa),
     message both backend-explorer and frontend-explorer.""")

Agent(subagent_type="ork:backend-system-architect", name="backend-explorer",
     team_name="explore-{topic}",
     prompt="""Analyze backend architecture patterns for: {topic}
     When structure-explorer or data-flow-explorer share backend findings,
     investigate deeper — API design, database schema, service patterns.
     Share integration points with frontend-explorer for consistency.""")

Agent(subagent_type="ork:frontend-ui-developer", name="frontend-explorer",
     team_name="explore-{topic}",
     prompt="""Analyze frontend components, state, and routes for: {topic}
     When structure-explorer shares component locations, investigate deeper.
     When backend-explorer shares API patterns, verify frontend alignment.
     Share component hierarchy with data-flow-explorer.""")

Team Teardown

After report generation:

# TeamDelete() shuts down all teammates — no manual shutdown_request needed
TeamDelete()

# Worktree cleanup (CC 2.1.72)
ExitWorktree(action="keep")

Fallback: If team formation fails, use standard Task tool spawns. See exploration-agents.md.

Incorrect — Sequential exploration without coordination:

Agent(subagent_type="Explore", prompt="Find auth files")
# Wait for result...
Agent(subagent_type="Explore", prompt="Trace auth data flow")
# Sequential, no sharing between agents

Correct — Team mode with real-time discovery sharing:

TeamCreate(team_name="explore-auth")
Agent(subagent_type="Explore", name="structure-explorer",
     team_name="explore-auth",
     prompt="Find auth files. Message data-flow-explorer with entry points.")
Agent(subagent_type="Explore", name="data-flow-explorer",
     team_name="explore-auth",
     prompt="When structure-explorer shares entry points, trace data flows.")
# Parallel execution, coordinated via messages

Code Health Assessment

Rate found code quality 0-10 with specific dimensions. See code-health-rubric.md for scoring criteria.

Agent(
  subagent_type="ork:code-quality-reviewer",
  prompt="""CODE HEALTH ASSESSMENT for files related to: $ARGUMENTS

  Rate each dimension 0-10:

  1. READABILITY (0-10)
     - Clear naming conventions?
     - Appropriate comments?
     - Logical organization?

  2. MAINTAINABILITY (0-10)
     - Single responsibility?
     - Low coupling?
     - Easy to modify?

  3. TESTABILITY (0-10)
     - Pure functions where possible?
     - Dependency injection?
     - Existing test coverage?

  4. COMPLEXITY (0-10, inverted: 10=simple, 0=complex)
     - Cyclomatic complexity?
     - Nesting depth?
     - Function length?

  5. DOCUMENTATION (0-10)
     - API docs present?
     - Usage examples?
     - Architecture notes?

  Output:
  {
    "overall_score": N.N,
    "dimensions": {
      "readability": N,
      "maintainability": N,
      "testability": N,
      "complexity": N,
      "documentation": N
    },
    "hotspots": ["file:line - issue"],
    "recommendations": ["improvement suggestion"]
  }

  SUMMARY: End with: "HEALTH: [N.N]/10 - [best dimension] strong, [worst dimension] needs work"
  """,
  run_in_background=True,
  max_turns=25
)

Incorrect — Vague code quality feedback:

Code Review: The code looks okay. Some parts are complex.
Maybe add more tests.

Correct — Structured health assessment with scores:

{
  "overall_score": 6.2,
  "dimensions": {
    "readability": 8,
    "maintainability": 5,
    "testability": 4,
    "complexity": 6,
    "documentation": 8
  },
  "hotspots": [
    "auth.ts:45 - nested if/else 5 levels deep",
    "utils.ts:120 - 200-line function, no SRP"
  ],
  "recommendations": [
    "Extract auth.ts:45-80 to separate validation functions",
    "Add unit tests for utils.ts edge cases"
  ]
}

Dependency Hotspot Analysis

Identify highly-coupled code and dependency bottlenecks. See dependency-analysis.md for metrics and formulas.

Agent(
  subagent_type="ork:backend-system-architect",
  prompt="""DEPENDENCY HOTSPOT ANALYSIS for: $ARGUMENTS

  Analyze coupling and dependencies:

  1. IMPORT ANALYSIS
     - Which files import this code?
     - What does this code import?
     - Circular dependencies?

  2. COUPLING SCORE (0-10, 10=highly coupled)
     - How many files would break if this changes?
     - Fan-in (incoming dependencies)
     - Fan-out (outgoing dependencies)

  3. CHANGE IMPACT
     - Blast radius of modifications
     - Files that always change together

  4. HOTSPOT VISUALIZATION

[Module A] --depends--> [Target] <--depends-- [Module B] | v [Module C]

  Output:
  {
    "coupling_score": N,
    "fan_in": N,
    "fan_out": N,
    "circular_deps": [],
    "change_impact": ["file - reason"],
    "hotspot_diagram": "ASCII diagram"
  }

  SUMMARY: End with: "COUPLING: [N]/10 - [N] incoming, [M] outgoing deps - [key concern]"
  """,
  run_in_background=True,
  max_turns=25
)

Incorrect — Listing imports without analysis:

auth.ts imports:
- utils.ts
- config.ts
- db.ts

Correct — Hotspot analysis with coupling score:

{
  "coupling_score": 8,
  "fan_in": 12,
  "fan_out": 5,
  "circular_deps": ["auth.ts → user.ts → auth.ts"],
  "change_impact": [
    "auth.ts change breaks 12 files",
    "utils.ts and auth.ts always change together"
  ],
  "hotspot_diagram": "
    [12 files] --depend on--> [auth.ts]
                                  |
                              depends on
                                  v
                      [utils, config, db, user, session]
  "
}

Exploration Agents (Task Tool Mode)

Launch 4 specialized explorers in ONE message with run_in_background: true:

# PARALLEL - All 4 in ONE message
Agent(
  subagent_type="Explore",
  prompt="""Code Structure: Find all files, classes, functions related to: $ARGUMENTS

  Scope: ONLY read files directly relevant to the topic. Do NOT explore the entire codebase.

  SUMMARY: End with: "RESULT: [N] files, [M] classes - [key location, e.g., 'src/auth/']"
  """,
  run_in_background=True,
  max_turns=25
)
Agent(
  subagent_type="Explore",
  prompt="""Data Flow: Trace entry points, processing, storage for: $ARGUMENTS

  Scope: ONLY read files directly relevant to the topic. Do NOT explore the entire codebase.

  SUMMARY: End with: "RESULT: [entry] → [processing] → [storage] - [N] hop flow"
  """,
  run_in_background=True,
  max_turns=25
)
Agent(
  subagent_type="ork:backend-system-architect",
  prompt="""Backend Patterns: Analyze architecture patterns, integrations, dependencies for: $ARGUMENTS

  Scope: ONLY read files directly relevant to the topic. Do NOT explore the entire codebase.

  SUMMARY: End with: "RESULT: [pattern name] - [N] integrations, [M] dependencies"
  """,
  run_in_background=True,
  max_turns=25
)
Agent(
  subagent_type="ork:frontend-ui-developer",
  prompt="""Frontend Analysis: Find components, state management, routes for: $ARGUMENTS

  Scope: ONLY read files directly relevant to the topic. Do NOT explore the entire codebase.

  SUMMARY: End with: "RESULT: [N] components, [state lib] - [key route]"
  """,
  run_in_background=True,
  max_turns=25
)

Fork Pattern (CC 2.1.89 — #1227)

These agents are fork-eligible: short prompts (<500 words), no custom model, no worktree isolation. CC automatically shares the parent's cached API prefix across all 4 forks, reducing cost by ~60%.

See chain-patterns/references/fork-pattern.md for full details.

Do NOT add model= or isolation="worktree" to these agents — it breaks cache sharing.

Explorer Roles

1. Code Structure Explorer - Files, classes, functions 2. Data Flow Explorer - Entry points, processing, storage 3. Backend Architect - Patterns, integration, dependencies 4. Frontend Developer - Components, state, routes

Incorrect — Sequential exploration:

Agent(subagent_type="Explore", prompt="Find auth files")
# Wait...
Agent(subagent_type="Explore", prompt="Trace auth flow")
# Wait...
Agent(subagent_type="ork:backend-system-architect", prompt="Analyze patterns")
# Slow, sequential

Correct — Parallel exploration in one message:

# All 4 in ONE message with run_in_background: true
Agent(subagent_type="Explore", prompt="Code Structure: Find all files related to auth",
     run_in_background=True, max_turns=25)
Agent(subagent_type="Explore", prompt="Data Flow: Trace auth entry→storage",
     run_in_background=True, max_turns=25)
Agent(subagent_type="ork:backend-system-architect", prompt="Backend Patterns: Analyze auth architecture",
     run_in_background=True, max_turns=25)
Agent(subagent_type="ork:frontend-ui-developer", prompt="Frontend: Find auth components",
     run_in_background=True, max_turns=25)
# Parallel execution

Product Perspective

Add business context and findability suggestions. See findability-patterns.md for discoverability best practices.

Agent(
  subagent_type="ork:product-strategist",
  prompt="""PRODUCT PERSPECTIVE for: $ARGUMENTS

  Analyze from a product/business viewpoint:

  1. BUSINESS CONTEXT
     - What user problem does this code solve?
     - What feature/capability does it enable?
     - Who are the users of this code?

  2. FINDABILITY SUGGESTIONS
     - Better naming for discoverability?
     - Missing documentation entry points?
     - Where should someone look first?

  3. KNOWLEDGE GAPS
     - What context is missing for new developers?
     - What tribal knowledge exists?
     - What should be documented?

  4. SEARCH OPTIMIZATION
     - Keywords someone might use to find this
     - Alternative terms for the same concept
     - Related concepts to cross-reference

  Output:
  {
    "business_purpose": "description",
    "primary_users": ["user type"],
    "findability_issues": ["issue - suggestion"],
    "recommended_entry_points": ["file - why start here"],
    "search_keywords": ["keyword"],
    "documentation_gaps": ["gap"]
  }

  SUMMARY: End with: "FINDABILITY: [N] issues - start at [recommended entry point]"
  """,
  run_in_background=True,
  max_turns=25)

Incorrect — Technical analysis without business context:

Found auth.ts, user.ts, session.ts
Uses JWT tokens, bcrypt hashing
Database: PostgreSQL users table

Correct — Product perspective with findability:

{
  "business_purpose": "Secure user authentication and session management",
  "primary_users": ["End users logging in", "Developers integrating auth"],
  "findability_issues": [
    "auth.ts - generic name, try auth/core.ts",
    "Missing README in auth/ - devs don't know where to start"
  ],
  "recommended_entry_points": [
    "auth/README.md (missing - create this!)",
    "auth/core.ts - main authentication flow"
  ],
  "search_keywords": ["login", "authentication", "session", "JWT", "security"],
  "documentation_gaps": [
    "No auth flow diagram",
    "Token refresh logic undocumented"
  ]
}