devflow-kit 1.8.2 → 2.0.0

package/dist/commands/explore.md

@@ -0,0 +1,208 @@
+---
+description: Explore codebase with structured analysis and optional feature knowledge creation
+---
+# Explore Command
+
+Explore a codebase area by spawning parallel agents for flow tracing, dependency mapping, and pattern analysis. Findings are synthesized into structured output with file:line references, with optional feature knowledge created as a byproduct.
+
+## Usage
+
+```
+/explore "how does the auth system work"
+/explore "trace the request lifecycle from API to database"
+/explore "what patterns does the payments module use"
+```
+
+## Input
+
+`$ARGUMENTS` contains whatever follows `/explore`:
+- Area description: "how does the auth system work"
+- Flow question: "trace the request lifecycle"
+- Empty: use conversation context
+
+## Phases
+
+### Phase 1: Load Decisions (Orchestrator-Local)
+
+**Produces:** DECISIONS_CONTEXT
+
+### Load DECISIONS_CONTEXT
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+
+**Step 1 — Read the pre-rendered index:**
+
+Attempt to read `{worktree}/.devflow/learning/index.md`.
+
+- If the file exists and contains non-empty content: use that content as `DECISIONS_CONTEXT`.
+- If the file is absent or empty: set `DECISIONS_CONTEXT` to `(none)`.
+
+**No subprocess, no `.cjs` script.** This is a single direct file read — the index is written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md`.
+
+**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+
+When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
+
+The orchestrator uses `DECISIONS_CONTEXT` locally when framing exploration — prior decisions and pitfalls suggest specific areas to investigate. Follow `devflow:apply-decisions` to Read full entry bodies on demand. **Do NOT pass `DECISIONS_CONTEXT` to Explore sub-agents** — decisions context stays in the orchestrator, not in the investigation workers.
+
+**No up-front feature knowledge load** — explore investigation workers read code directly to avoid confirmation bias. Feature knowledge is only created as a write-back at the end, after exploration is complete.
+
+### Phase 2: Orient
+
+**Produces:** ORIENT_OUTPUT
+
+Spawn `Agent(subagent_type="Skim")` to get codebase overview relevant to the exploration question:
+
+- File structure and module boundaries in the target area
+- Entry points and key abstractions
+- Related patterns and conventions
+
+### Phase 3: Explore
+
+**Produces:** EXPLORE_OUTPUT
+**Requires:** ORIENT_OUTPUT
+
+Based on Skim agent findings, spawn 2-3 `Agent(subagent_type="Explore")` agents **in a single message** (parallel execution):
+
+- **Flow explorer**: Trace the primary call chain end-to-end — entry point through to side effects
+- **Dependency explorer**: Map imports, shared types, module boundaries, and integration points
+- **Pattern explorer**: Identify recurring patterns, conventions, and architectural decisions in the area
+
+Adjust explorer focus based on the specific exploration question.
+
+### Phase 4: Synthesize
+
+**Produces:** MERGED_FINDINGS
+**Requires:** EXPLORE_OUTPUT
+
+Spawn `Agent(subagent_type="Synthesize")` in `exploration` mode with combined findings:
+
+- Merge overlapping discoveries from parallel explorers
+- Resolve any contradictions between explorer findings
+- Organize into the Output format below
+
+### Phase 5: Present
+
+**Requires:** MERGED_FINDINGS
+
+Main session reviews synthesis for:
+
+- **Gaps**: Areas the explorers missed or couldn't reach
+- **Surprises**: Unexpected patterns, hidden dependencies, non-obvious design choices
+- **Depth**: Areas where the user might want to drill deeper
+
+Present findings to user. Use AskUserQuestion to offer focused follow-up exploration.
+
+### Phase 6: Suggest Feature Knowledge Creation (Conditional)
+
+**Requires:** MERGED_FINDINGS, DECISIONS_CONTEXT
+**Produces:** FEATURE_KNOWLEDGE_STATUS (created | skipped)
+
+1. Check if matching feature knowledge already exists by reading `{worktree}/.devflow/features/index.md` (or globbing frontmatter if absent). If covered → skip
+2. Use AskUserQuestion: "No feature knowledge exists for {explored area}. Create one to capture these patterns?"
+3. If user declines → set FEATURE_KNOWLEDGE_STATUS = skipped
+4. If user accepts: proceed with write-back below.
+
+### Feature Knowledge Write-Back (Conditional)
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+
+**Step 1 — Check the opt-out gate:**
+
+Read `{worktree}/.devflow/config.json`. If the `knowledge` field is `false`, skip write-back entirely — the user has disabled it.
+
+If `.devflow/config.json` does not exist, proceed (default is enabled).
+
+**Step 2 — Evaluate whether write-back is warranted:**
+
+Only proceed if **at least one** of these is true:
+- This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed).
+- This workflow surfaced durable, cross-cutting knowledge about a codebase area that would help future agents working in the same area — patterns, anti-patterns, integration points, gotchas not visible from a single file read.
+
+**Never spawn unconditionally.** If neither condition is met, skip write-back silently.
+
+**Step 3 — Spawn the Knowledge agent:**
+
+Spawn `Agent(subagent_type="Knowledge")` with the following context:
+
+```
+"WORKTREE_PATH: {worktree root}
+FEATURE_SLUG: {slug derived from primary changed directory, kebab-case}
+FEATURE_NAME: {human-readable name}
+DIRECTORIES: {list of primary directories touched by this workflow}
+FILES_CHANGED: {list of files changed}
+DECISIONS_CONTEXT: {DECISIONS_CONTEXT if available, else (none)}
+
+Load the devflow:feature-knowledge skill and follow its authoring process.
+
+Write the knowledge base to:
+  {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
+
+Then update the index cache by performing a read-modify-write on:
+  {worktree}/.devflow/features/index.md
+
+Index line format: `- **{slug}** — {areas} — {Use-when description}`
+
+If the line for this slug already exists in index.md, replace it. If it does not exist, append it. If index.md does not exist, create it with just this line.
+
+The frontmatter in KNOWLEDGE.md is the source of truth — index.md is only a cache. Write the two files directly — no intermediate result JSON files, no external scripts.
+
+After writing, commit the two files to the current worktree branch yourself by running git via your Bash tool (do not use a script). Stage ONLY .devflow/features/index.md and .devflow/features/{slug}/KNOWLEDGE.md, then commit just those paths with a docs(knowledge): message. Do NOT push, do NOT force, do NOT stage anything else. Follow your Commit Protocol — it is non-blocking, so if any git step fails, report KB_COMMIT and finish normally."
+```
+
+**Failure handling**: Non-blocking. If the Knowledge agent fails, log the failure and continue — the workflow outcome is not affected by write-back success.
+
+Set FEATURE_KNOWLEDGE_STATUS = created (if agent spawned) or skipped.
+
+**Failure handling**: Non-blocking. If Knowledge agent fails, log and continue.
+
+## Worktree Support
+
+If the orchestrator receives a `WORKTREE_PATH` context (e.g., from multi-worktree workflows), pass it through to all spawned agents. Each agent's "Worktree Support" section handles path resolution.
+
+## Output
+
+Structured exploration findings with concrete code references:
+
+- Scope (what was explored and boundaries)
+- Architecture Map (modules, layers, key abstractions with file:line)
+- Flow Trace (call chain from entry to exit with file:line at each step)
+- Integration Points (module boundaries, shared types, external dependencies)
+- Patterns (recurring conventions, design decisions observed)
+- Key Insights (non-obvious findings, surprises, potential concerns)
+
+## Architecture
+
+```
+/explore (orchestrator)
+│
+├─ Phase 1: Load Decisions (Orchestrator-Local)
+│
+├─ Phase 2: Orient
+│  └─ Skim agent (codebase overview)
+│
+├─ Phase 3: Parallel exploration
+│  └─ 2-3 Explore agents (flow, dependency, pattern) in single message
+│
+├─ Phase 4: Synthesize
+│  └─ Synthesize agent aggregates findings in exploration mode
+│
+├─ Phase 5: Present findings with drill-down offer
+│
+└─ Phase 6: Suggest feature knowledge creation (conditional)
+   └─ Knowledge agent write-back (if user accepts and no existing feature knowledge)
+```
+
+## Principles
+
+1. **Structure over browsing** - Every claim must cite file:line references
+2. **Parallel execution** - All explorers run simultaneously for speed
+3. **Knowledge-informed** - Prior decisions guide where to look; NO pre-loaded feature knowledge in sub-agents (avoids confirmation bias)
+4. **User-driven depth** - Present findings, then offer drill-down into specific areas
+
+## Error Handling
+
+- If Skim agent returns no relevant files: report "No files found matching exploration scope"
+- If all explorers error: report partial findings from any that succeeded, note gaps
+- If an explorer errors: continue with remaining results, note the gap
+- If feature knowledge creation fails: log failure, report exploration results normally