feat: explore skill (claude only)

.buildforce/context/_index.yaml

@@ -58,7 +58,7 @@ version: "2.1"
 
 # Timestamps (populated by /buildforce.extract on first run)
 generated_at: "2026-02-02"
-last_updated: "2026-02-02"
+last_updated: "2026-02-05"
 
 # ============================================================================
 # CODEBASE PROFILE
@@ -267,6 +267,33 @@ domains:
         tags: [ slash-command, extract, context-mining, sub-agents, claude-code-only, coverage-map ]
         related_context: [ slash-commands, cli-architecture, upgrade-command ]
 
+      - id: context-search-skill
+        file: architecture/context-search-skill.yaml
+        type: structural
+        status: extracted
+        depth: moderate
+        description: Claude Code skill for searching the context repository with hook-based Explore agent redirection
+        tags: [ skill, context-search, context-retrieval, sub-agents, hooks, model-invocable, user-invocable ]
+        related_context: [ extract-command, research-slash-command, cli-architecture, sub-agent-architecture ]
+
+      - id: explorer-agent
+        file: architecture/explorer-agent.yaml
+        type: structural
+        status: extracted
+        depth: moderate
+        description: Buildforce Explorer wrapper agent and PreToolUse hook that intercepts built-in Explore and redirects through context repository
+        tags: [ agent, hook, explore-redirect, context-search, pretooluse, settings-merge ]
+        related_context: [ context-search-skill, sub-agent-architecture, cli-architecture ]
+
+      - id: sub-agent-architecture
+        file: architecture/sub-agent-architecture.yaml
+        type: structural
+        status: extracted
+        depth: deep
+        description: Claude Code sub-agent pattern with Explorer/Extractor/Archiver families, Task tool spawning, and distribution mechanism
+        tags: [ core, architecture, sub-agents, task-tool, claude-code-only, agent-families, distribution ]
+        related_context: [ extract-command, context-search-skill, explorer-agent, cli-architecture, agent-template-conventions ]
+
   conventions:
     description: |
       Convention context about HOW things are done here.
@@ -366,6 +393,16 @@ domains:
         enforcement: strict
         related_context: [ yaml-extension-standard ]
 
+      - id: agent-template-conventions
+        file: conventions/agent-template-conventions.yaml
+        type: convention
+        status: extracted
+        depth: moderate
+        description: Conventions for writing buildforce agent templates (frontmatter, tools, output formats)
+        sub_type: code-convention
+        enforcement: strict
+        related_context: [ sub-agent-architecture, extract-command, context-search-skill ]
+
   verification:
     description: |
       Verification context about HOW to know if code is right.
@@ -427,9 +464,9 @@ domains:
 
 summary:
   overall_coverage: 100
-  total_items: 35
-  extracted_items: 35
-  iterations_completed: 2
+  total_items: 39
+  extracted_items: 39
+  iterations_completed: 4
 
 # ============================================================================
 # EXTRACTION STATE

.buildforce/context/architecture/cli-architecture.yaml

@@ -3,7 +3,7 @@ name: Buildforce CLI Architecture
 type: structural
 status: production
 created: 2025-10-27
-last_updated: "2026-02-02"
+last_updated: "2026-02-05"
 
 summary: |
   Comprehensive architecture of the Buildforce CLI tool - a Node.js-based command-line
@@ -235,6 +235,7 @@ architecture_patterns:
     - .buildforce/templates/ - Local templates
     - buildforce.json - Project configuration with aiAssistant, scriptType, version, sessionsFolder
     - Agent folders (.claude/, .github/, etc.) - Agent-specific files with commands nested in buildforce/ subdirectory
+    - .claude/agents/ - Sub-agent templates (Claude Code only)
 
     Extraction Flow:
     1. Download ZIP to temp directory
@@ -243,6 +244,21 @@ architecture_patterns:
     4. Copy files to project path (merge mode)
     5. Clean up temp files
 
+    Sub-Agent Distribution (Claude Code only):
+    - Source: src/templates/agents/*.md with agents: [claude] frontmatter
+    - Build: generate_agents() in create-release-packages.sh filters and processes
+    - Package: Agents included in Claude ZIP at .claude/agents/
+    - Init: Extracted automatically as part of ZIP (no special handling)
+    - Upgrade: Full replacement of .claude/agents/ folder (backup + remove + copy)
+    - Other agents don't support sub-agents (no Task tool equivalent)
+
+    Key difference from commands distribution:
+    - Commands go to all 11 agents with format variations (md, toml, prompt.md)
+    - Agents go ONLY to Claude (Task tool is Claude Code-specific)
+    - Both use same agents: field filtering mechanism
+
+    See sub-agent-architecture context file for detailed agent specification.
+
   context_management: |
     Directory Structure (v2.0 - Context Taxonomy):
     .buildforce/context/
@@ -504,6 +520,11 @@ related_specs:
   - "context-taxonomy-align-20260123143000"
   - "claude-code-extract-command-20260127152345"
 
+related_context:
+  - sub-agent-architecture
+  - extract-command
+  - explore-command
+
 extension_points:
   command_registration: |
     New CLI commands are added via Commander.js program.command() pattern:

.buildforce/context/architecture/context-search-skill.yaml

@@ -0,0 +1,155 @@
+# Context Search Skill Architecture Context
+# Created: 2026-02-05
+# Updated: 2026-02-10 — Converted from /buildforce.explore slash command to context-search skill
+# Source: explore-command-20260202090346 spec session (original), manual conversion (v2.0)
+
+id: context-search-skill
+name: "context-search Skill"
+type: structural
+status: production
+created: "2026-02-05"
+last_updated: "2026-02-10"  # v2.0 skill conversion
+
+summary: |
+  Claude Code skill that searches the Buildforce context repository for curated codebase knowledge.
+  Both users (/context-search) and the agent (proactive invocation) can use it to enrich agentic
+  search with structured understanding that source files lack — architecture decisions, conventions,
+  verification standards, and design rationale. Uses a PreToolUse hook to transparently redirect
+  Claude's built-in Explore sub-agent through the context repository instead of raw file search.
+
+responsibilities:
+  - Intent analysis (new topic, question, open exploration)
+  - Selective dispatch of Context Explorers based on detected intent
+  - Synthesis of findings into context-enriching responses
+  - Transparent interception of built-in Explore agent via PreToolUse hook
+
+dependencies:
+  internal:
+    - context-repo: "Requires extracted context in architecture/, conventions/, verification/ domains"
+    - _index.yaml: "Uses context index for navigation and discovery"
+  external:
+    - task-tool: "Claude Code Task tool for sub-agent spawning"
+    - hooks-system: "Claude Code PreToolUse hooks for Explore agent redirection"
+    - skills-system: "Claude Code Skills for user-invocable and model-invocable activation"
+
+files:
+  primary:
+    - src/templates/skills/context-search/SKILL.md
+  secondary:
+    - src/templates/agents/buildforce-explorer.md
+    - src/templates/agents/buildforce-structural-explorer.md
+    - src/templates/agents/buildforce-convention-explorer.md
+    - src/templates/agents/buildforce-verification-explorer.md
+    - src/templates/hooks/setup-explorer-subagent.sh
+    - src/utils/hooks.ts
+  distribution:
+    - .github/workflows/scripts/create-release-packages.sh
+    - src/commands/init/setup.ts
+    - src/commands/upgrade/execution.ts
+
+interfaces:
+  skill:
+    - name: "context-search"
+      invocation: "/context-search [optional-topic-or-question]"
+      user_invocable: true
+      model_invocable: true
+      description: "Searches the context repository for curated codebase knowledge"
+  hook:
+    - name: "setup-explorer-subagent"
+      event: "PreToolUse"
+      matcher: "Task"
+      description: "Intercepts Task calls with subagent_type=Explore and redirects to buildforce-explorer"
+      config_location: ".claude/settings.local.json"
+  sub_agents:
+    - name: "Buildforce Explorer"
+      type: "buildforce-explorer"
+      purpose: "Wrapper that reads context-search SKILL.md and executes it; replaces built-in Explore"
+      tools: "Task, Read, Glob, Grep"
+    - name: "Structural Explorer"
+      type: "buildforce-structural-explorer"
+      domain: "architecture/"
+      tools: "Read, Glob, Grep (read-only)"
+    - name: "Convention Explorer"
+      type: "buildforce-convention-explorer"
+      domain: "conventions/"
+      tools: "Read, Glob, Grep (read-only)"
+    - name: "Verification Explorer"
+      type: "buildforce-verification-explorer"
+      domain: "verification/"
+      tools: "Read, Glob, Grep (read-only)"
+
+design_decisions:
+  - decision: "Convert from slash command to Claude Code Skill"
+    rationale: "Skills support proactive model invocation — Claude can automatically use the skill when the conversation needs curated context, without the user typing /context-search. The description field is loaded into context so Claude knows when to use it."
+
+  - decision: "Redirect built-in Explore agent via PreToolUse hook"
+    rationale: "Claude Code's default Explore agent does raw file search. By intercepting Task calls with subagent_type=Explore, all exploration transparently goes through the context repository first. This makes context enrichment automatic without requiring user awareness."
+
+  - decision: "Hook writes to settings.local.json via mergeHooksSettings utility"
+    rationale: "settings.local.json is a user-specific file with accumulated permissions. The utility idempotently merges hook config without clobbering existing settings. Both init and upgrade call it."
+
+  - decision: "Rename from buildforce.explore to context-search"
+    rationale: "Avoids collision with Claude Code's built-in Explore agent type. The name 'context-search' clearly signals the purpose — searching curated context, not exploring raw files."
+
+  - decision: "Remove archiver and session persistence"
+    rationale: "As a skill (not a workflow), context-search is a focused search tool. Persistence added complexity without clear value for single-query context retrieval."
+
+  - decision: "Remove brainstorming/session framing"
+    rationale: "Moving from workflow mentality to tool mentality. Both user and agent should understand this is a context search utility, not a multi-turn conversation session."
+
+  - decision: "Use same three-domain architecture as extract (structural, conventions, verification)"
+    rationale: "Consistency with existing patterns, reuses domain expertise, aligns with context repo structure"
+
+  - decision: "Explorers return structured YAML findings, not raw file content"
+    rationale: "Enables manager to synthesize intelligently; findings include relevance scoring, excerpts, connections, and gaps"
+
+  - decision: "Selective explorer dispatch based on intent classification"
+    rationale: "Performance optimization — no need to search all domains for focused queries; reduces latency"
+
+  - decision: "Explicit 'not found vs tangentially related' distinction in synthesis"
+    rationale: "Prevent the agent from presenting tangentially related information as if it answers the user's actual question. Must acknowledge when requested functionality doesn't exist."
+
+  - decision: "ensureHooksExecutable sets chmod on hook scripts during init/upgrade"
+    rationale: "ZIP extraction and fs.copy don't preserve execute bits. Without this, the hook script fails with 'Permission denied' on first run after upgrade."
+
+evolution:
+  - version: "1.0"
+    date: "2026-02-05"
+    changes: "Initial implementation as /buildforce.explore slash command with Explorers and Archiver"
+
+  - version: "1.1"
+    date: "2026-02-05"
+    changes: |
+      Bug fixes: Archiver forbidden paths, 'not found vs tangentially related' distinction,
+      archiver timing (spawned only after complete response, completion events ignored)
+
+  - version: "2.0"
+    date: "2026-02-10"
+    changes: |
+      Major conversion from slash command to Claude Code Skill:
+      - Renamed from /buildforce.explore to /context-search
+      - Converted to .claude/skills/context-search/SKILL.md format
+      - Added PreToolUse hook (setup-explorer-subagent.sh) to redirect built-in Explore agent
+      - Added buildforce-explorer wrapper sub-agent
+      - Removed archiver and session persistence
+      - Removed brainstorming/session framing
+      - Added skills + hooks support to build script (generate_skills, hooks copying)
+      - Added skills + hooks backup/replace/rollback to upgrade command
+      - Added mergeHooksSettings utility for idempotent settings.local.json merging
+      - Added ensureHooksExecutable for chmod on deployed hook scripts
+
+related_specs:
+  - explore-command-20260202090346
+
+notes: |
+  The hook-based Explore redirection is the key architectural innovation in v2.0. It solves the
+  problem that Claude Code's built-in Explore agent does raw file search, which bypasses the
+  curated context repository entirely. By intercepting at the PreToolUse level, any time Claude
+  would normally dispatch an Explore agent (including proactively), the query goes through
+  the context repository first.
+
+  The buildforce-explorer wrapper agent is intentionally thin — it reads SKILL.md and follows
+  its instructions. This keeps the skill as the single source of truth for context search logic.
+
+  Distribution chain: src/templates/ → build script → .genreleases/ ZIP → init/upgrade extracts
+  to .claude/skills/, .claude/agents/, .claude/hooks/ → mergeHooksSettings writes settings.local.json.