---
title: "Explore"
description: "Multi-angle codebase exploration spawning 3-5 parallel agents for code structure, data flow, architecture patterns, and health assessment. Generates ASCII visualizations, import graphs, and design pattern detection with cross-session memory storage. Use when exploring a repo, discovering architecture, onboarding to a new codebase, or analyzing design patterns."
canonical: "https://orchestkit.yonyon.ai/docs/reference/skills/explore"
---
# Explore
Multi-angle codebase exploration spawning 3-5 parallel agents for code structure, data flow, architecture patterns, and health assessment. Generates ASCII visualizations, import graphs, and design pattern detection with cross-session memory storage. Use when exploring a repo, discovering architecture, onboarding to a new codebase, or analyzing design patterns.
Command high
```bash title="Invoke"
/ork:explore
```
> **Explore** Multi-angle codebase exploration spawning 3-5 parallel agents for code structure, data flow, architecture patterns, and health assessment. Generates ASCII visualizations, import graphs, and design pattern detection with cross-session memory storage. Use when exploring a repo, discovering architecture, onboarding to a new codebase, or analyzing design patterns.
# Codebase Exploration
Multi-angle codebase exploration using 3-5 parallel agents.
## π― Quick Start
```bash
/ork:explore authentication
```
> **Opus 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.
```python
# 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
```
| Effort | Agent count | Phases | Time |
|--------|-------------|--------|------|
| `low` | 1 (structure-only) | 1, 2, 8 | ~1 min |
| `medium` | 2 (structure + data flow) | 1, 2, 3 (subset), 8 | ~3 min |
| `high` (default) | 4 (full parallel team) | 1β8 | ~6 min |
| `xhigh` (Opus 5) | 5 (+ uncertainty pass on health scores) | 1β8 + caveats | ~8 min |
**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 5.
---
## STEP 0: Verify User Intent with AskUserQuestion
**BEFORE creating tasks**, clarify what the user wants to explore:
```python
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
```python
# 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:
```python
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)
| Aspect | Task Tool | Agent Teams |
|--------|-----------|-------------|
| Discovery sharing | Lead synthesizes after all complete | Explorers share discoveries as they go |
| Cross-referencing | Lead connects dots | Data flow explorer alerts architecture explorer |
| Cost | ~150K tokens | ~400K tokens |
| Best for | Quick/focused searches | Deep full-codebase exploration |
> **Fallback:** If Agent Teams encounters issues, fall back to Task 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:**
```python
# 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. 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
| Phase | Activities | Output |
|-------|------------|--------|
| **1. Initial Search** | Grep, Glob for matches | File locations |
| **2. Memory Check** | Search knowledge graph | Prior context |
| **3. Deep Exploration** | 4 parallel explorers | Multi-angle analysis |
| **4. AI System (if applicable)** | LangGraph, prompts, RAG | AI-specific findings |
| **5. Code Health** | Rate code 0-10 | Quality scores |
| **6. Dependency Hotspots** | Identify coupling | Hotspot visualization |
| **7. Product Perspective** | Business context | Findability suggestions |
| **8. Report Generation** | Compile findings | Actionable report |
### Progressive Output (CC 2.1.76)
Output findings **incrementally** as each phase completes β don't batch until the report:
| After Phase | Show User |
|-------------|-----------|
| 1. Initial Search | File matches, grep results |
| 2. Memory Check | Prior decisions and relevant context |
| 3. Deep Exploration | Each explorer agent's findings as they return |
| 5. Code Health | Health score with dimension breakdown |
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
```python
# PARALLEL - Quick searches
Grep(pattern="$ARGUMENTS[0]", output_mode="files_with_matches")
Glob(pattern="**/*$ARGUMENTS[0]*")
```
### Phase 2: Memory Check
```python
mcp__memory__search_nodes(query="$ARGUMENTS[0]")
mcp__memory__search_nodes(query="architecture")
```
### Phase 3: Parallel Deep Exploration (4 Agents)
Load `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/explore/rules/exploration-agents.md")` for Task tool mode prompts.
Load `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/explore/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_PLUGIN_ROOT\}/skills/explore/rules/code-health-assessment.md")` for agent prompt. Load `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/explore/references/code-health-rubric.md")` for scoring criteria.
### Phase 6: Dependency Hotspot Map
Load `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/explore/rules/dependency-hotspot-analysis.md")` for agent prompt. Load `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/explore/references/dependency-analysis.md")` for metrics.
### Phase 7: Product Perspective
Load `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/explore/rules/product-perspective.md")` for agent prompt. Load `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/explore/references/findability-patterns.md")` for best practices.
### Phase 8: Generate Report
Load `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/explore/references/exploration-report-template.md")`.
### Phase 8b: Emit Dashboard Spec (json-render)
Parse `--render=` from `$ARGUMENTS`. Default is `both`.
| Mode | Behavior |
|------|----------|
| `markdown` | Current behavior β markdown report only. No spec emitted. |
| `json-render` | Emit `.claude/chain/explore-dashboard.json` only. Skip markdown report. |
| `both` | Emit spec **and** markdown. Default β gives the human a report and downstream skills a structured handoff. |
When emitting a spec:
1. Load the format and catalog: `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/explore/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:
```bash
node "${CLAUDE_PLUGIN_ROOT}/skills/explore/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:
```bash
node "${CLAUDE_PLUGIN_ROOT}/skills/explore/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:
```bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/explore/scripts/post_explore_summary.py "$CLAUDE_JOB_DIR"
```
Auto-skip conditions (all exit 0, all WARN-logged):
| Skip reason | Trigger |
|-------------|---------|
| `signal absent` | `len(dirs_scanned) < 3` (or field missing on `explore-output.json`) |
| `yg-mcp-core not importable` | `yg-mcp-core>=0.3.0` not installed (orchestkit is public; yg-mcp-core lives on private `pypi.yonyon.ai` β HQ-only) |
| `hq-content MCP unreachable` | MCP server down OR `.mcp.json` doesn't define `hq-content` |
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, or stop after 10 turns
```
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)
---
## Rules (5)
### Coordinate multi-agent exploration teams with real-time discovery sharing β HIGH
# Agent Teams Mode
In Agent Teams mode, form an exploration team where explorers share discoveries in real-time:
```python
# CC 2.1.178+: one implicit team per session β no TeamCreate.
# Spawn teammates directly via Agent(name=...). Requires
# CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (set in ork.settings.json).
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:
```python
# CC 2.1.178+: no TeamDelete β teammates wind down at turn end
# (press Ctrl+F twice to stop lingering background teammates).
# Worktree cleanup (CC 2.1.72)
ExitWorktree(action="keep")
```
> **Fallback:** If team formation fails, use standard Task tool spawns. See [exploration-agents.md](exploration-agents.md).
**Incorrect β Sequential exploration without coordination:**
```python
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:**
```python
# CC 2.1.178+: one implicit team per session β no TeamCreate.
# Spawn teammates directly via Agent(name=...). Requires
# CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (set in ork.settings.json).
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
```
### Score code health across five quality dimensions with structured assessment criteria β MEDIUM
# Code Health Assessment
Rate found code quality 0-10 with specific dimensions. See [code-health-rubric.md](../references/code-health-rubric.md) for scoring criteria.
```python
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:**
```markdown
Code Review: The code looks okay. Some parts are complex.
Maybe add more tests.
```
**Correct β Structured health assessment with scores:**
```json
{
"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"
]
}
```
```
```
### Identify highly-coupled code and dependency bottlenecks to reduce change risk β MEDIUM
# Dependency Hotspot Analysis
Identify highly-coupled code and dependency bottlenecks. See [dependency-analysis.md](../references/dependency-analysis.md) for metrics and formulas.
```python
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:**
```markdown
auth.ts imports:
- utils.ts
- config.ts
- db.ts
```
**Correct β Hotspot analysis with coupling score:**
```json
{
"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]
"
}
```
```
```
### Spawn parallel exploration agents using Task tool for concurrent codebase analysis β HIGH
# Exploration Agents (Task Tool Mode)
Launch 4 specialized explorers in ONE message with `run_in_background: true`:
```python
# 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:**
```python
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:**
```python
# 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
```
### Add business context and findability analysis to technical codebase exploration β MEDIUM
# Product Perspective
Add business context and findability suggestions. See [findability-patterns.md](../references/findability-patterns.md) for discoverability best practices.
```python
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:**
```markdown
Found auth.ts, user.ts, session.ts
Uses JWT tokens, bcrypt hashing
Database: PostgreSQL users table
```
**Correct β Product perspective with findability:**
```json
{
"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"
]
}
```
```
```
---
## References (5)
### Code Health Rubric
# Code Health Rubric
Standardized 0-10 scoring criteria for assessing code quality across five dimensions.
## Scoring Scale
| Score | Rating | Description |
|-------|--------|-------------|
| 9-10 | Excellent | Production-ready, exemplary code |
| 7-8 | Good | Minor improvements possible |
| 5-6 | Adequate | Functional but needs attention |
| 3-4 | Poor | Significant issues, refactor recommended |
| 0-2 | Critical | Major problems, immediate action required |
---
## 1. Readability (0-10)
| Score | Criteria |
|-------|----------|
| 10 | Self-documenting, intuitive naming, perfect structure |
| 7-8 | Clear names, logical flow, minimal cognitive load |
| 5-6 | Understandable with effort, some unclear sections |
| 3-4 | Confusing logic, poor naming, requires context |
| 0-2 | Incomprehensible, magic numbers, no conventions |
## 2. Maintainability (0-10)
| Score | Criteria |
|-------|----------|
| 10 | SRP adherence, loose coupling, DRY, easy to modify |
| 7-8 | Good separation, minor duplication, clear boundaries |
| 5-6 | Some coupling, moderate duplication, changes ripple |
| 3-4 | High coupling, significant duplication, fragile |
| 0-2 | Spaghetti code, any change breaks multiple areas |
## 3. Testability (0-10)
| Score | Criteria |
|-------|----------|
| 10 | Pure functions, DI, 90%+ coverage, mocks easy |
| 7-8 | Most logic testable, some DI, 70%+ coverage |
| 5-6 | Testable with effort, some hidden dependencies |
| 3-4 | Hard to isolate, global state, 30% coverage |
| 0-2 | Untestable, tightly coupled, no test infrastructure |
## 4. Complexity (0-10, inverted: 10=simple)
| Score | Criteria |
|-------|----------|
| 10 | Cyclomatic <5, max 2 nesting, <20 line functions |
| 7-8 | Cyclomatic 5-10, 3 nesting, <40 line functions |
| 5-6 | Cyclomatic 10-15, 4 nesting, some long functions |
| 3-4 | Cyclomatic 15-25, deep nesting, 100+ line functions |
| 0-2 | Cyclomatic >25, 6+ nesting, god functions |
## 5. Documentation (0-10)
| Score | Criteria |
|-------|----------|
| 10 | Complete API docs, examples, architecture notes |
| 7-8 | Public API documented, inline comments where needed |
| 5-6 | Some docstrings, missing edge cases |
| 3-4 | Sparse comments, outdated documentation |
| 0-2 | No documentation, misleading comments |
---
## 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 (json-render) β HIGH
# 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.
| Type | Purpose | Required Props |
|------|---------|----------------|
| `Card` | Section wrapper with optional title | `title?: string` |
| `StatGrid` | 2β6 metrics in a grid | `items: \{ label, value, trend?, color? \}[]` |
| `DataTable` | Tabular rows | `columns: \{ key, label \}[]`, `rows: Record<string,string>[]` |
| `StatusBadge` | Single status indicator | `label: string`, `status: success|warning|error|info|pending` |
| `BarMeter` | 0-10 score bar | `label: string`, `value: number` (0-10), `color?: string` |
| `Heatmap` | Coupling/dependency matrix | `xLabels: string[]`, `yLabels: string[]`, `cells: number[][]` |
| `Markdown` | Free-text fallback for prose sections | `content: string` |
`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`:
```json
{
"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
```python
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
# Dependency Analysis
Identify coupling hotspots and dependency patterns in codebases.
## Fan-In / Fan-Out Metrics
| Metric | Definition | Implication |
|--------|------------|-------------|
| **Fan-In** | Files that import this module | High = many dependents, changes risky |
| **Fan-Out** | Modules this file imports | High = many dependencies, fragile |
| **Instability** | Fan-Out / (Fan-In + Fan-Out) | 0 = stable, 1 = unstable |
**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
| Pattern | Risk | Action |
|---------|------|--------|
| Fan-in > 10 | Blast radius large | Add interface/abstraction |
| Fan-out > 8 | Too many dependencies | Extract facades |
| Instability = 1, Fan-in > 5 | Unstable core | Stabilize or decouple |
### 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
# Exploration Report Template
Use this template for Phase 8 report generation.
```markdown
# 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
# Findability Patterns
Improve code discoverability for developers exploring the codebase.
## Naming Conventions for Searchability
| Pattern | Example | Searchability |
|---------|---------|---------------|
| Domain prefix | `auth_login()`, `auth_logout()` | Grep "auth_" finds all |
| Feature suffix | `UserService`, `UserRepository` | Grep "User" finds related |
| Action verbs | `create_user`, `delete_order` | Grep "create_" finds patterns |
| Consistent pluralization | `users/`, `orders/` | Predictable directory names |
**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
| Location | Purpose | Findability |
|----------|---------|-------------|
| `README.md` in directory | Module overview | First thing developers see |
| Inline docstrings | Function behavior | IDE tooltips, grep |
| `docs/architecture/` | System design | High-level understanding |
| `CLAUDE.md` / `CONTRIBUTING.md` | Development guide | Onboarding entry |
**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
```python
# 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