explore

KnowzCode Explore

Explore a topic, investigate the codebase, or produce a structured implementation plan before committing to implementation.

Usage: /knowzcode:explore <topic, question, or feature to plan>

Examples:

/knowzcode:explore "is the API using proper error handling?"
/knowzcode:explore "add user authentication with JWT"
/knowzcode:explore "how does caching work in this codebase?"
/knowzcode:explore "plan the migration to PostgreSQL"
/knowzcode:explore "design a notification system"

When NOT to Trigger

• User wants to implement or build -> use /knowzcode:work
• User wants a single-file fix -> use /knowzcode:fix
• User wants to audit or scan existing code -> use /knowzcode:audit
• User wants to save a learning -> use /knowz save
• User says "implement the plan" or "go ahead" after research -> use /knowzcode:start-work (trigger skill)

Common Invocation Patterns

These phrases indicate /knowzcode:explore intent:

• "explore how X works", "investigate X", "research X"
• "what's the architecture of X", "how does X work"
• "is X using proper Y?", "analyze X"
• "plan for X", "plan adding X", "evaluate options for X"
• "design X", "prepare for X", "explore adding X"

---

Step 1: Validate Input

If no argument provided, ask: "What would you like me to explore?"

Step 1.5: Auto-Detect Depth

Classify the query into one of two modes:

Exploration Mode (lightweight)

Triggers on: questions ("how does X work?", "is X correct?", "analyze X"), "what's the architecture of X", investigative phrasing without action verbs.

• Keep 10-tool-call-per-agent behavior
• Output: inline findings report (no file saved)
• Agents: knowledge-liaison + analyst + architect + reviewer (standard behavior)

Planning Mode (deep)

Triggers on: "plan X", "explore adding X", "design X", "prepare for X", action verbs + feature nouns, "evaluate options for X", any phrasing that implies building or changing something.

• Remove tool call limits (agents get full research depth)
• Add project management research angle
• Add structured vault queries
• Output: plan document saved to knowzcode/planning/{slug}.md
• Agents: knowledge-liaison + analyst + architect + reviewer + lead project analysis

Announce the detected mode: **Mode: Exploration** (lightweight research) or **Mode: Planning** (deep research with plan output)

Step 2: Check Initialization

If knowzcode/ doesn't exist, inform user to run /knowzcode:init first. STOP.

Step 3: Set Up Execution Mode

Attempt TeamCreate(team_name="kc-explore-{slug}") (2-4 word kebab-case from topic):

• If TeamCreate succeeds -> Agent Teams mode:

  1. Announce: **Execution Mode: Agent Teams** — created team kc-explore-{slug}
  2. Read knowzcode/claude_code_execution.md for team conventions.
  3. You are the team lead — coordinate research, synthesize findings.

• If TeamCreate fails (error, unrecognized tool, timeout) -> Subagent Delegation:

  • Announce: **Execution Mode: Subagent Delegation** — Agent Teams not available, using Task() fallback

The user MUST see the execution mode announcement before investigation begins.

Step 3.5: Load Orchestration Config (Optional)

If knowzcode/knowzcode_orchestration.md exists, parse:

1. MCP_AGENTS_ENABLED = mcp_agents_enabled value (default: true)

Flag overrides: --no-mcp -> MCP_AGENTS_ENABLED = false

If file doesn't exist, use defaults. Other config settings (max_builders, default_specialists) are not applicable to /knowzcode:explore.

Step 4: Launch Parallel Investigation

Use task lists to plan and track your research throughout. Add new tasks as discoveries expand the scope.

MCP Probe

If MCP_AGENTS_ENABLED = false (from Step 3.5, e.g. --no-mcp), skip the MCP Probe and Step 4.1 entirely. Set MCP_ACTIVE = false, VAULTS_CONFIGURED = false, VAULT_BASELINE = null.

Before spawning agents, determine vault availability:

1. Read knowz-vaults.md from project root — parse vault IDs. If file not found, call list_vaults(includeStats=true) to discover vaults.
2. If list_vaults() fails AND no knowz-vaults.md exists -> MCP_ACTIVE = false, VAULTS_CONFIGURED = false. Announce: **MCP Status: Not connected**
3. If list_vaults() fails BUT knowz-vaults.md has vault IDs -> MCP_ACTIVE = true, VAULTS_CONFIGURED = true. Announce: **MCP Status: Lead probe failed — vault agents will verify independently**
4. If vaults discovered but no knowz-vaults.md exists -> suggest "Run /knowz setup to configure vault routing." Set VAULTS_CONFIGURED = true (use discovered IDs for baseline).
5. Set MCP_ACTIVE and VAULTS_CONFIGURED based on results. Announce: **MCP Status: Connected — N vault(s) available** or **MCP Status: Connected — no vaults configured (knowledge capture disabled)**

If no vaults are configured, suggest /knowz setup.

Vault research is mandatory when available. The lead performs baseline vault queries directly (Step 4.1) whenever VAULTS_CONFIGURED = true and MCP_ACTIVE = true — this is the guaranteed minimum. When agents are available, the knowledge-liaison performs deeper targeted queries beyond the baseline. Only skip all vault queries when MCP is genuinely unavailable (MCP_ACTIVE = false).

Step 4.1: Baseline Vault Query (Lead-Direct)

If VAULTS_CONFIGURED = true AND MCP_ACTIVE = true, the lead performs baseline vault queries directly BEFORE spawning any agents. This ensures vault context is available regardless of agent availability.

1. Using vault configuration from the MCP Probe above (already loaded), resolve configured vault IDs and types.
2. For each configured vault, call search_knowledge({vault_id}, "past decisions, conventions, patterns related to {topic}").
   • For finalizations-type vaults: search_knowledge({vault_id}, "past work related to {topic}").
   • One broad query per vault — the goal is baseline coverage, not exhaustive research.
3. Store all results as VAULT_BASELINE:

   VAULT_BASELINE:
   - {vault_name} ({vault_type}): {summary of results, or "No relevant results found"}
   

4. Failure handling: If search_knowledge fails for a vault, log the failure and continue with remaining vaults. A partial baseline is better than none. If ALL queries fail, set VAULT_BASELINE = "Vault queries failed — MCP may be degraded" and continue.
5. Announce: **Vault Baseline: {N} vault(s) queried — {M} results found**

If VAULTS_CONFIGURED = false OR MCP_ACTIVE = false, set VAULT_BASELINE = null and skip this step.

This step is non-skippable when MCP is available. It runs before agent spawning and does not depend on agent availability.

Agent Teams Mode

Create tasks first, pre-assign, then spawn with task IDs:

1. TaskCreate("Knowledge liaison: context & vault research for {topic}") -> TaskUpdate(owner: "knowledge-liaison")
2. TaskCreate("Research: code exploration") -> TaskUpdate(owner: "analyst")
3. TaskCreate("Research: architecture") -> TaskUpdate(owner: "architect")
4. TaskCreate("Research: security + quality") -> TaskUpdate(owner: "reviewer")

Spawn teammates with their task IDs:

1. Spawn knowledge-liaison teammate:

   Your Task: #{task-id} — claim immediately (TaskUpdate(status: "in_progress")). Mark completed with summary when done. Read agents/knowledge-liaison.md for your full role definition. Read knowzcode/claude_code_execution.md for team conventions. Goal: Research "{topic}" — gather local context and vault knowledge. Vault config: knowz-vaults.md (project root) Lead Vault Baseline: {VAULT_BASELINE or "No baseline — MCP not available or no vaults configured"} Context gathering: Read local context directly (specs, workgroups, tracker, architecture) using Read/Glob tools. If baseline results are provided above, skip broad vault queries and dispatch deeper targeted research instead. If no baseline, perform full vault queries per your startup sequence. Deliverable: Push Context Briefing to analyst and architect with local + vault findings.

2. Spawn analyst teammate:

   Exploration mode prompt:

   Your Task: #{task-id} — claim immediately (TaskUpdate(status: "in_progress")). Mark completed with summary when done. You are researching "{topic}" from a code exploration angle. Read agents/analyst.md for your role definition. Read knowzcode/claude_code_execution.md for team conventions. Investigate: affected files, dependencies, existing patterns. Max 10 tool calls. Write findings to a concise summary.

   Planning mode prompt:

   Your Task: #{task-id} — claim immediately (TaskUpdate(status: "in_progress")). Mark completed with summary when done. You are researching "{topic}" from an impact analysis angle. Read agents/analyst.md for your full role definition. Read knowzcode/claude_code_execution.md for team conventions. Investigate: affected files, dependencies, existing patterns. Produce a preliminary Change Set estimate:

   • Potential NodeIDs with descriptions
   • Affected files list with change types (new/modify)
   • Dependency map (which NodeIDs share files)
   • Risk assessment with rationale Write findings to a detailed summary.

3. Spawn architect teammate:

   Exploration mode prompt:

   Your Task: #{task-id} — claim immediately (TaskUpdate(status: "in_progress")). Mark completed with summary when done. You are researching "{topic}" from an architecture angle. Read agents/architect.md for your role definition. Read knowzcode/claude_code_execution.md for team conventions. Investigate: layer analysis, design implications, pattern fit. Max 10 tool calls. Write findings to a concise summary.

   Planning mode prompt:

   Your Task: #{task-id} — claim immediately (TaskUpdate(status: "in_progress")). Mark completed with summary when done. You are researching "{topic}" from an architecture and design angle. Read agents/architect.md for your full role definition. Read knowzcode/claude_code_execution.md for team conventions. Investigate: layer analysis, design implications, pattern fit. Propose an implementation approach:

   • Recommended design with rationale
   • Alternatives considered and why rejected
   • Constraints from architecture docs
   • Spec consolidation opportunities (check existing specs for overlap) Write findings to a detailed summary.

4. Spawn reviewer teammate:

   Exploration mode prompt:

   Your Task: #{task-id} — claim immediately (TaskUpdate(status: "in_progress")). Mark completed with summary when done. You are researching "{topic}" from a security and quality angle. Read agents/reviewer.md for your role definition. Read knowzcode/claude_code_execution.md for team conventions. Investigate: risks, performance concerns, quality gaps. Max 10 tool calls. Write findings to a concise summary.

   Planning mode prompt:

   Your Task: #{task-id} — claim immediately (TaskUpdate(status: "in_progress")). Mark completed with summary when done. You are researching "{topic}" from a security and quality angle. Read agents/reviewer.md for your full role definition. Read knowzcode/claude_code_execution.md for team conventions. Investigate: risks, performance concerns, quality gaps. Write findings to a detailed summary.

Knowledge-liaison pushes Context Briefings to analyst and architect; all core researchers consume them. Wait for all to complete, then synthesize in Step 5.

Subagent Mode

Delegate to up to four agents in parallel via Task():

1. knowledge-liaison — Local context + vault knowledge:

   • Task(subagent_type="knowzcode:knowledge-liaison", description="Context & vault research for {topic}", prompt="Read agents/knowledge-liaison.md for your full role definition. Goal: Research \"{topic}\" — gather local context and vault knowledge. Vault config: knowz-vaults.md (project root). Lead Vault Baseline: {VAULT_BASELINE or 'No baseline — MCP not available or no vaults configured'}. Read local context files directly (specs, workgroups, tracker, architecture) using Read and Glob tools. If baseline results are provided, skip broad vault queries and dispatch deeper targeted research instead. If no baseline, perform full vault queries per your startup sequence. Return consolidated Context Briefing with local + vault findings.")

2. analyst — Code exploration / Impact analysis:

   • subagent_type: "analyst"

   Exploration mode:

   • prompt: Research "{topic}" from a code exploration angle. Investigate: affected files, dependencies, existing patterns. Max 10 tool calls. Write findings to a concise summary.
   • description: "Explore research: code exploration"

   Planning mode:

   • prompt: Research "{topic}" from an impact analysis angle. Read agents/analyst.md for your full role definition. Investigate: affected files, dependencies, existing patterns. Produce a preliminary Change Set estimate: Potential NodeIDs with descriptions, Affected files list with change types (new/modify), Dependency map (which NodeIDs share files), Risk assessment with rationale. Write findings to a detailed summary.
   • description: "Explore research: impact analysis"

3. architect — Architecture assessment / Design:

   • subagent_type: "architect"

   Exploration mode:

   • prompt: Research "{topic}" from an architecture angle. Investigate: layer analysis, design implications, pattern fit. Max 10 tool calls. Write findings to a concise summary.
   • description: "Explore research: architecture"

   Planning mode:

   • prompt: Research "{topic}" from an architecture and design angle. Read agents/architect.md for your full role definition. Investigate: layer analysis, design implications, pattern fit. Propose an implementation approach: Recommended design with rationale, Alternatives considered and why rejected, Constraints from architecture docs, Spec consolidation opportunities (check existing specs for overlap). Write findings to a detailed summary.
   • description: "Explore research: architecture and design"

4. reviewer — Security and quality:

   • subagent_type: "reviewer"

   Exploration mode:

   • prompt: Research "{topic}" from a security and quality angle. Investigate: risks, performance concerns, quality gaps. Max 10 tool calls. Write findings to a concise summary.
   • description: "Explore research: security and quality"

   Planning mode:

   • prompt: Research "{topic}" from a security and quality angle. Read agents/reviewer.md for your full role definition. Investigate: risks, performance concerns, quality gaps. Write findings to a detailed summary.
   • description: "Explore research: security and quality"

Solo Mode (No Agents Available)

If BOTH TeamCreate fails AND Task() is unavailable or fails, the lead performs all research directly:

1. Announce: **Execution Mode: Solo** — Agent Teams and Subagent Delegation not available, lead performing research directly

2. Vault knowledge: Already available from Step 4.1 (VAULT_BASELINE). If deeper vault queries are needed for specific aspects:

   • Call search_knowledge({vault_id}, "{specific_aspect_of_topic}") for targeted follow-ups.
   • Call ask_question({vault_id}, "{question_about_topic}") for synthesized answers.

3. Local context (lead reads directly):

   • Glob("knowzcode/specs/*.md") — scan for related specs
   • Read("knowzcode/knowzcode_architecture.md") — architecture context
   • Read("knowzcode/knowzcode_project.md") — project standards
   • Glob("knowzcode/workgroups/*.md") — prior WorkGroups
   • Read("knowzcode/knowzcode_tracker.md") — active WIP, REFACTOR tasks

4. Codebase exploration (lead reads directly):

   • Grep for topic-related keywords across source files
   • Read top affected files to understand patterns and dependencies
   • Check test coverage for the topic area

5. Proceed to Step 5 (Synthesis) with VAULT_BASELINE + local findings + codebase findings.

Project Management Analysis (Planning Mode Only)

After spawning agents (or completing Solo Mode research) and before synthesizing findings, the lead performs project management research directly:

1. Read knowzcode/knowzcode_tracker.md for WIP conflicts (overlapping NodeIDs/files)
2. Read knowzcode/knowzcode_tracker.md for related REFACTOR tasks to bundle
3. Read knowzcode/knowzcode_log.md for recent similar completions
4. Check knowzcode/knowzcode_architecture.md for constraint violations

Store findings for inclusion in the plan output.

Step 5: Synthesize Findings

Exploration Mode Output

Present findings inline (no file saved):

## Investigation: {topic}

### Code Analysis
{summarized findings from analyst}

### Architecture Assessment
{summarized findings from architect}

### Security & Quality
{summarized findings from reviewer}

### Existing Knowledge
- **Relevant Specs**: {list or "None found"}
- **Prior WorkGroups**: {list or "None found"}
- **Vault Knowledge (Baseline)**: {VAULT_BASELINE results or "N/A — MCP not configured"}
- **Vault Knowledge (Deep)**: {knowledge-liaison findings beyond baseline, or "N/A — agents not available" or "N/A — MCP not configured"}

### Recommended Approaches

**Option 1**: {approach}
- Pros: ...
- Cons: ...

**Option 2**: {approach}
- Pros: ...
- Cons: ...

### Risks & Considerations
{synthesized risks}

### Complexity Assessment
- **Files identified**: {count} — {file list}
- **Potential NodeIDs**: {count} — {brief descriptions}
- **Architectural impact**: Yes/No — {reason if yes}
- **Security-sensitive**: Yes/No — {reason if yes}
- **External integrations**: Yes/No — {list if yes}
- **Estimated scope**: ~{N} lines across {M} files
- **Recommended tier**: Tier 2 (Light) / Tier 3 (Full)

Tier recommendation follows work.md's classification rules:
- **Tier 3** if ANY: >3 files, >1 NodeID, architectural impact, security-sensitive, external integrations
- **Tier 2** if ALL: <=3 files, single NodeID, no arch changes, no security, no external APIs

---

**Ready to implement?** Say "implement", "do option 1", or "go ahead" to start `/knowzcode:work` with this context.

Planning Mode Output

Save to knowzcode/planning/{slug}.md where slug is derived from the topic (2-4 word kebab-case):

# Implementation Plan: {topic}

## Goal
{clear statement of what will be built}

## Prior Knowledge (from vaults)
**Baseline** (lead-direct): {VAULT_BASELINE results or "N/A — MCP not configured"}
**Deep research** (knowledge-liaison): {liaison findings beyond baseline, or "N/A — agents not available"}

## Impact Analysis
- **Estimated NodeIDs**: {list with descriptions}
- **Affected files**: {file list with change types}
- **Dependency map**: {which NodeIDs can parallelize}

## Architecture Proposal
- **Recommended approach**: {design with rationale}
- **Alternatives considered**: {why rejected}
- **Constraints**: {from vault knowledge + architecture docs}
- **Spec consolidation**: {existing specs to update vs new specs}

## Project Context
- **WIP conflicts**: {overlapping tracker items, or "None"}
- **Related backlog**: {REFACTOR tasks to bundle, or "None"}
- **Recent similar work**: {relevant log entries, or "None"}

## Risk Assessment
{risk with mitigation, one per bullet}

## Complexity
- **Files**: {count} — {file list}
- **Potential NodeIDs**: {count}
- **Tier**: 2 (Light) / 3 (Full)
- **Security-sensitive**: Yes/No
- **External integrations**: Yes/No

---
Ready to implement? Say "implement" or "go ahead".

Step 5.5: Vault Capture Prompt

If VAULTS_CONFIGURED = true AND MCP_ACTIVE = true, present after findings:

**Save to vault?** These findings can be captured to Knowz for future reference.
  **A) Save all findings** (analysis + architecture + discoveries)
  **B) Select which to save**
  **C) Skip**

Handling:

• A: Dispatch knowz:writer with a self-contained prompt summarizing all findings, tagged with the topic. Read knowz-vaults.md (project root) to resolve the target vault (use ecosystem-type vault). Check for duplicates via search_knowledge before writing.
• B: Ask user which sections to save, then dispatch knowz:writer with selected content.
• C: Proceed to Step 6.

If VAULTS_CONFIGURED = false or MCP_ACTIVE = false, skip this step silently.

Vault Write Continuation

After Step 5.5 resolves (including if the user chose C/Skip), remain responsive to vault-write intent in follow-up messages. Watch for:

• "save this to vault", "capture this", "document this in the vault"
• "save as {type}" (e.g., "save as Guidelines", "save as a Decision")
• "put this in knowz", "add this to the vault"
• Any follow-up referencing vault/knowz + save/capture/document intent

When detected:

1. Ask the user what content to save (or confirm if they specified)
2. Resolve target vault from knowz-vaults.md (project root)
3. Dispatch knowz:writer via Task() with a self-contained prompt:
   • Content to save (from exploration findings or user-specified content)
   • Target vault ID
   • Title and tags derived from the content
   • Category hint if the user specified one (e.g., "Guidelines")
4. Report success/failure to the user

This ensures vault writes work even after the structured A/B/C window closes.

Step 6: Listen for Implementation Intent

Watch for: "implement", "do it", "go ahead", "option N", "start work", "build this"

When triggered:

Exploration mode: Invoke /knowzcode:work "{original_topic}" --tier {recommended_tier} and include a summary of investigation findings:

Explore investigation context:

• Files: {file list from complexity assessment}
• Potential NodeIDs: {list}
• Key risks: {top risks}
• Recommended approach: {selected option or top recommendation}

Planning mode: Invoke /knowzcode:work --context "knowzcode/planning/{slug}.md" passing the full plan file path. The plan document contains all the context work needs to proceed.

This context gives work's analyst a head start and ensures correct tier classification.

---

Cleanup

After synthesis is complete (or if the user cancels):

Agent Teams Mode:

1. Shut down all active teammates. Wait for each to confirm shutdown.
2. Once all teammates have shut down, clean up the team. No teammates or team resources should remain after the research ends.

Subagent Mode: No cleanup needed — Task() calls are self-contained.

---

Related Skills

• /knowzcode:work — Execute implementation after research
• /knowzcode:audit — Read-only quality scan (not exploratory)
• /knowzcode:fix — Single-file micro-fix
• /knowzcode:start-work — Trigger: "implement the plan" after research

Notes

• Exploration mode agents use focused, efficient scoping (max 10 tool calls each)
• Planning mode agents get full research depth (no tool call limits)
• Investigation context is preserved when transitioning to /knowzcode:work
• Planning mode saves structured plan documents to knowzcode/planning/
• This replaces the old planning types (strategy, ideas, pre-flight, etc.)