explore

Codebase Exploration

Host-neutral workflow. Invoke by skill name (explore). Claude Code slash routing, YAML hook loaders, and .claude/chain live in references/claude-code.md.

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

🎯 Quick Start

explore authentication

Opus 5.5: 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"

Override gate: if the user passes --effort=high explicitly while $CLAUDE_EFFORT is low, the flag wins. doctor warns only when xhigh is configured on a model in its XHIGH_UNSUPPORTED_PREFIXES table.

STEP 0: Verify User Intent with AskUserQuestion

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

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

Exploration Handoff

After exploration completes, write results for downstream skills:

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

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

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

Model cost (CC 2.1.198+): the built-in Explore agent inherits the session model capped at Opus — it no longer runs on haiku. From a premium-model session (Opus, Fable), budget Explore fan-outs at Opus rates; there is no knob to pin the built-in Explore back to haiku. ork's own explorer agents can still pin a cheaper model via frontmatter.

🚨 Task Management (MANDATORY)

BEFORE doing ANYTHING else, create tasks to show progress:

🔄 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

Load the repo map first. A fork skill never runs frontmatter hooks (#4683), so run the loader yourself and keep its additionalContext in mind:

Phase 2: Memory Check

Phase 3: Parallel Deep Exploration (4 Agents)

Load Read("rules/exploration-agents.md") for Agent tool mode prompts.

Load Read("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("rules/code-health-assessment.md") for agent prompt. Load Read("references/code-health-rubric.md") for scoring criteria.

Phase 6: Dependency Hotspot Map

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

Phase 7: Product Perspective

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

Phase 8: Generate Report

Load Read("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("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:

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:

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 (fix-issue, implement, 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:

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 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:

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

Quality Bar

Done means all of these hold:

• Every architectural or data-flow claim cites concrete evidence (file:line or a file path), not prose assertion
• Code health is reported as 0-10 scores with a per-dimension breakdown, not a bare number
• Dependency hotspots / coupling are named along with the files that drive them
• The report includes an architecture or structure visualization for the explored scope
• If a json-render spec is emitted, it passes render-spec.mjs --check; on failure fall back to markdown-only and never write a partial spec

📜 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)