**Used by**: `ultrawork.md`, `ultrawork-plan.md`
Orchestrates multi-stage codebase exploration to identify relevant areas for implementation tasks.
/plugin marketplace add mnthe/hardworker-marketplace/plugin install ultrawork@hardworker-marketplacereferences/Used by: ultrawork.md, ultrawork-plan.md
Purpose: Quickly understand codebase structure and identify areas for detailed exploration based on goal.
Invoke the overview-exploration skill directly (no agent spawn):
Skill(skill="ultrawork:overview-exploration")
The skill will:
exploration/overview.md (in session directory)context.jsonTime budget: ~30 seconds, max 5-7 file reads
This is synchronous - no polling needed. Proceed to Stage 2 after skill completes.
Update exploration_stage to "analyzing":
bun "${CLAUDE_PLUGIN_ROOT}/src/scripts/session-update.js" --session {SESSION_ID} --exploration-stage analyzing
Based on Overview + Goal, decide what areas need detailed exploration.
| Goal Keywords | Detected Stack | Explore Areas |
|---|---|---|
| auth, login, user | Next.js | middleware, api/auth, existing user model |
| auth, login, user | Express | routes, passport config, session |
| api, endpoint | Any | existing routes, controllers, schemas |
| database, model | Prisma | schema.prisma, migrations, existing models |
| database, model | TypeORM | entities, migrations |
| test, coverage | Any | existing tests, test config, mocks |
| ui, component | React/Next | components/, design system, styles |
| bug, fix, error | Any | related files from error context |
# Analyze overview + goal
hints = analyze_exploration_needs(overview, goal)
# Example outputs:
# Goal: "Add user authentication"
# Overview: Next.js with Prisma, no existing auth
# → hints = [
# "Authentication patterns: middleware, session, JWT",
# "Database: user model patterns in existing Prisma schema",
# "API routes: existing route patterns in app/api/"
# ]
# Generate expected explorer IDs
expected_ids="overview"
for i, hint in enumerate(hints):
expected_ids += f",exp-{i+1}"
# Initialize context.json with expected explorers
bun "${CLAUDE_PLUGIN_ROOT}/src/scripts/context-init.js" --session {SESSION_ID} --expected "{expected_ids}"
This ensures:
expected_explorers is set before spawningexploration_complete auto-updates when all explorers finishUpdate exploration_stage to "targeted":
bun "${CLAUDE_PLUGIN_ROOT}/src/scripts/session-update.js" --session {SESSION_ID} --exploration-stage targeted
Spawn explorers for each identified area (parallel, in single message):
# Get session_dir via: Bash('"bun ${CLAUDE_PLUGIN_ROOT}/src/scripts/session-get.js" --session {SESSION_ID} --dir')
# Call multiple Tasks in single message = automatic parallel execution
for i, hint in enumerate(hints):
Task(
subagent_type="ultrawork:explorer:explorer",
model="haiku", # or sonnet for complex areas
prompt=f"""
SESSION_ID: {SESSION_ID}
EXPLORER_ID: exp-{i+1}
SEARCH_HINT: {hint}
CONTEXT: {overview_summary}
"""
)
# All explorers run in parallel and results are collected
After all explorers complete, update exploration_stage to "complete":
bun "${CLAUDE_PLUGIN_ROOT}/src/scripts/session-update.js" --session {SESSION_ID} --exploration-stage complete
Before starting exploration, check session state to determine where to resume:
# SESSION_ID from hook output, session_dir derived from it
# Get session_dir via: Bash('"bun ${CLAUDE_PLUGIN_ROOT}/src/scripts/session-get.js" --session {SESSION_ID} --dir')
# Read session.json
session = Bash(f'cat {session_dir}/session.json')
exploration_stage = session.get("exploration_stage", "not_started")
# Read context.json
context = Read(f"{session_dir}/context.json")
exploration_complete = context.get("exploration_complete", False) if context else False
expected_explorers = context.get("expected_explorers", []) if context else []
actual_explorers = [e["id"] for e in context.get("explorers", [])] if context else []
| Stage | Status | Action |
|---|---|---|
not_started | Fresh start | Begin from Stage 1 (Overview) |
overview | Overview running/done | Check overview.md exists → proceed to Stage 2 |
analyzing | Hints generated, no targeted yet | Re-run hint analysis, set expected_explorers |
targeted | Targeted explorers running | Check expected vs actual, wait or re-spawn missing |
complete | Exploration done | Skip to Planning |
if exploration_stage == "not_started":
# Fresh start - go to Stage 1
pass
elif exploration_stage == "overview":
# Check if overview actually completed
if Path(f"{session_dir}/exploration/overview.md").exists():
# Proceed to Stage 2 (analyze & plan targeted)
pass
else:
# Re-spawn overview explorer
pass
elif exploration_stage == "analyzing":
# Overview done, need to generate hints and set expected_explorers
# Go to Stage 2
pass
elif exploration_stage == "targeted":
if expected_explorers and not exploration_complete:
missing = set(expected_explorers) - set(actual_explorers)
if missing:
print(f"Exploration incomplete. Missing: {missing}")
# Re-spawn missing explorers
pass
elif exploration_stage == "complete":
# Skip to planning
pass
Key checks:
exploration_stage in session.json determines resume pointexpected_explorers vs explorers[].id identifies missing workexploration_complete confirms all expected explorers finishedExplorers will create:
exploration/overview.md - Project overviewexploration/exp-1.md, exp-2.md, ... - Targeted findingscontext.json - Aggregated summary with links (exploration_complete=true when all done)