Claude-Code-Workflow/.claude/commands/workflow/tools/context-gather.md

---
name: gather
description: Intelligently collect project context using universal-executor agent based on task description and package into standardized JSON
argument-hint: "--session WFS-session-id \"task description\""
examples:
  - /workflow:tools:context-gather --session WFS-user-auth "Implement user authentication system"
  - /workflow:tools:context-gather --session WFS-payment "Refactor payment module API"
  - /workflow:tools:context-gather --session WFS-bugfix "Fix login validation error"
---

# Context Gather Command (/workflow:tools:context-gather)

## Overview
Agent-driven intelligent context collector that gathers relevant information from project codebase, documentation, and dependencies based on task descriptions, generating standardized context packages.

## Core Philosophy
- **Agent-Driven**: Delegate execution to universal-executor agent for autonomous operation
- **Two-Phase Flow**: Discovery (context loading) → Execution (context gathering and packaging)
- **Memory-First**: Reuse loaded documents from conversation memory
- **Ripgrep-Enhanced**: Use ripgrep and native tools for code analysis and file discovery
- **Intelligent Collection**: Auto-identify relevant resources based on keyword analysis
- **Comprehensive Coverage**: Collect code, documentation, configurations, and dependencies
- **Standardized Output**: Generate unified format context-package.json

## Execution Lifecycle

### Phase 1: Discovery & Context Loading
**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory

**Agent Context Package**:
```javascript
{
  "session_id": "WFS-[session-id]",
  "task_description": "[user provided task description]",
  "session_metadata": {
    // If in memory: use cached content
    // Else: Load from .workflow/{session-id}/workflow-session.json
  },
  "search_tools": {
    // Agent will use these native tools to discover project context
    "ripgrep": true,
    "find": true,
    "exa_code": true,
    "exa_web": true
  }
}

// Agent will autonomously execute:
// - Project structure analysis: bash(~/.claude/scripts/get_modules_by_depth.sh)
// - Documentation loading: Read(CLAUDE.md), Read(README.md)
```

**Discovery Actions**:
1. **Load Session Context** (if not in memory)
   ```javascript
   if (!memory.has("workflow-session.json")) {
     Read(.workflow/{session-id}/workflow-session.json)
   }
   ```

### Phase 2: Agent Execution (Context Gathering & Packaging)

**Agent**: context-search-agent
**Documentation**: `.claude/agents/context-search-agent.md`

**Agent Invocation**:
```javascript
Task(
  subagent_type="universal-executor",
  description="Gather project context and generate context package",
  prompt=`
You are executing as the context-search-agent. Follow the complete execution process documented in .claude/agents/context-search-agent.md.

## Execution Context

**Session ID**: WFS-{session-id}
**Task Description**: {task_description}
**Mode**: Agent-Driven Context Gathering

## Phase 1: Discovery Results (Provided Context)

### Session Metadata
{session_metadata_content}

### Search Tools Available
- ripgrep: Content search and pattern matching
- find: File discovery
- exa-code: External research (MCP)
- exa-web: Web search (MCP)

## Your Mission

Execute the complete context-search-agent workflow documented in .claude/agents/context-search-agent.md. For detailed specifications, refer to the agent documentation which includes:

### Core Responsibilities
1. **Project Structure Analysis**: Execute get_modules_by_depth.sh for architecture overview
2. **Documentation Loading**: Load CLAUDE.md, README.md and relevant documentation
3. **Keyword Extraction**: Extract core keywords from task description
4. **Smart File Discovery**: Use ripgrep and find to locate relevant files
5. **Code Structure Analysis**: Analyze project structure to identify relevant modules
6. **Dependency Discovery**: Identify tech stack and dependency relationships
7. **Context Packaging**: Generate standardized JSON context package

### Execution Process

#### Step 0: Foundation Setup (Execute First)
1. **Project Structure Analysis**
   Execute to get comprehensive architecture overview:
   \`\`\`javascript
   bash(~/.claude/scripts/get_modules_by_depth.sh)
   \`\`\`

2. **Load Project Documentation** (if not in memory)
   Load core project documentation:
   \`\`\`javascript
   Read(CLAUDE.md)
   Read(README.md)
   // Load other relevant documentation based on session context
   \`\`\`

#### Step 1: Task Analysis
1. **Keyword Extraction**
   - Parse task description to extract core keywords
   - Identify technical domain (auth, API, frontend, backend, etc.)
   - Determine complexity level (simple, medium, complex)

2. **Scope Determination**
   - Define collection scope based on keywords
   - Identify potentially involved modules and components
   - Set file type filters

#### Step 2: File Discovery with Native Tools
1. **Code File Location**
   Use ripgrep and find commands:
   \`\`\`bash
   # Find files by pattern
   find . -name "*{keyword}*" -type f

   # Search code content with ripgrep
   rg "{keyword_patterns}" --type-add 'custom:*.{ts,js,py,go,md}' -t custom -C 3

   # Get file summaries (find function/class definitions)
   rg "^(class|function|export|def|interface)" relevant/file.ts
   \`\`\`

2. **Configuration Files Discovery**
   Locate: package.json, requirements.txt, Cargo.toml, tsconfig.json, etc.

3. **Test Files Location**
   Find test files related to task keywords

#### Step 3: Intelligent Filtering & Association
1. **Relevance Scoring**
   - Score based on keyword match degree
   - Score based on file path relevance
   - Score based on code content relevance

2. **Dependency Analysis**
   - Analyze import/require statements
   - Identify inter-module dependencies
   - Determine core and optional dependencies

#### Step 3.5: Brainstorm Artifacts Discovery
Discover and catalog brainstorming documents (if `.brainstorming/` exists):
- Guidance specification, role analyses (`*/analysis*.md`), synthesis output
- Catalog role analyses by role with file type and timestamp

#### Step 4: Context Packaging
Generate standardized context-package.json following the format below

#### Step 5: Conflict Detection & Risk Assessment
**Purpose**: Analyze existing codebase to determine conflict risk level

1. **Existing Code Detection**
   - Count relevant existing source files discovered in Step 2
   - Identify modules that overlap with task scope
   - Flag existence of implementations related to task keywords

2. **Architecture Analysis**
   - Compare task requirements with existing architecture patterns
   - Identify potential architectural changes required
   - Detect breaking changes to current structure

3. **API & Dependency Analysis**
   - Check for existing API endpoints/contracts that may change
   - Identify shared dependencies and interface changes
   - Detect potential breaking changes to public APIs

4. **Data Model Analysis**
   - Identify existing data models/schemas in task scope
   - Check for schema modification requirements
   - Detect potential data migration needs

5. **Risk Level Calculation**
   Calculate conflict_risk based on:
   - **none**: No existing code, new feature/module
   - **low**: < 5 existing files, minimal changes
   - **medium**: 5-15 existing files OR architectural changes OR API changes
   - **high**: >15 existing files OR data model changes OR breaking changes

### Required Output

**Output Location**: \`.workflow/{session-id}/.process/context-package.json\`

**Output Format**:
\`\`\`json
{
  "metadata": {
    "task_description": "Implement user authentication system",
    "timestamp": "2025-09-29T10:30:00Z",
    "keywords": ["user", "authentication", "JWT", "login"],
    "complexity": "medium",
    "tech_stack": ["typescript", "node.js", "express"],
    "session_id": "WFS-user-auth"
  },
  "assets": [
    {
      "type": "documentation",
      "path": "CLAUDE.md",
      "relevance": "Project development standards and conventions",
      "priority": "high"
    },
    {
      "type": "documentation",
      "path": ".workflow/docs/architecture/security.md",
      "relevance": "Security architecture design guidance",
      "priority": "high"
    },
    {
      "type": "source_code",
      "path": "src/auth/AuthService.ts",
      "relevance": "Existing authentication service implementation",
      "priority": "high"
    },
    {
      "type": "source_code",
      "path": "src/models/User.ts",
      "relevance": "User data model definition",
      "priority": "medium"
    },
    {
      "type": "config",
      "path": "package.json",
      "relevance": "Project dependencies and tech stack",
      "priority": "medium"
    },
    {
      "type": "test",
      "path": "tests/auth/*.test.ts",
      "relevance": "Authentication related test cases",
      "priority": "medium"
    }
  ],
  "tech_stack": {
    "frameworks": ["express", "typescript"],
    "libraries": ["jsonwebtoken", "bcrypt"],
    "testing": ["jest", "supertest"]
  },
  "statistics": {
    "total_files": 15,
    "source_files": 8,
    "docs_files": 4,
    "config_files": 2,
    "test_files": 1
  },
  "brainstorm_artifacts": {
    "guidance_specification": {
      "path": ".workflow/WFS-user-auth/.brainstorming/guidance-specification.md",
      "exists": true
    },
    "role_analyses": [
      {
        "role": "system-architect",
        "files": [
          {"path": ".workflow/WFS-user-auth/.brainstorming/system-architect/analysis.md", "type": "primary"},
          {"path": ".workflow/WFS-user-auth/.brainstorming/system-architect/analysis-api.md", "type": "supplementary"}
        ]
      },
      {
        "role": "ui-designer",
        "files": [
          {"path": ".workflow/WFS-user-auth/.brainstorming/ui-designer/analysis.md", "type": "primary"}
        ]
      }
    ],
    "synthesis_output": {
      "path": ".workflow/WFS-user-auth/.brainstorming/synthesis-specification.md",
      "exists": true
    }
  },
  "conflict_detection": {
    "conflict_risk": "medium",
    "existing_files": [
      "src/auth/AuthService.ts",
      "src/models/User.ts",
      "src/middleware/auth.ts"
    ],
    "has_existing_code": true,
    "affected_modules": ["auth", "user-model"],
    "detection_criteria": {
      "existing_code_count": 8,
      "architecture_changes": false,
      "api_changes": true,
      "data_model_changes": false
    },
    "risk_rationale": "Medium risk due to existing auth code and potential API changes"
  }
}
\`\`\`

### Quality Validation

Before completion, verify:
- [ ] context-package.json created in correct location
- [ ] Valid JSON format with all required fields
- [ ] Metadata includes task description, keywords, complexity
- [ ] Assets array contains relevant files with priorities
- [ ] Tech stack accurately identified
- [ ] Statistics section provides file counts
- [ ] File relevance accuracy >80%
- [ ] No sensitive information exposed

### Performance Optimization

**Large Project Optimization**:
- File count limit: Maximum 50 files per type
- Size filtering: Skip oversized files (>10MB)
- Depth limit: Maximum search depth of 3 levels
- Use ripgrep for efficient discovery

**Native Tools Integration**:
Agent should use ripgrep and find commands:
\`\`\`bash
# Find files by pattern
find . -name "*{keyword}*" -type f

# Search code content with ripgrep
rg "{keyword_patterns}" --type ts --type js --type py --type go --type md -C 3

# Alternative: use glob patterns
rg "{keyword_patterns}" -g "*.{ts,js,py,go,md}" -C 3

# Count matches
rg "{keyword_patterns}" -c

# List files with matches
rg "{keyword_patterns}" --files-with-matches
\`\`\`

## Output

Generate context-package.json and report completion:
- Task description: {description}
- Keywords extracted: {count}
- Files collected: {total}
  - Source files: {count}
  - Documentation: {count}
  - Configuration: {count}
  - Tests: {count}
- Tech stack identified: {frameworks/libraries}
- Output location: .workflow/{session-id}/.process/context-package.json
\`
)
\`\`\`

## Command Integration

### Usage
```bash
# Basic usage
/workflow:tools:context-gather --session WFS-auth "Implement JWT authentication"

# Called by /workflow:plan
SlashCommand(command="/workflow:tools:context-gather --session WFS-[id] \\"[task description]\\"")
```

### Agent Context Passing

**Memory-Aware Context Assembly**:
```javascript
// Assemble minimal context package for agent
// Agent will execute project structure analysis and documentation loading
const agentContext = {
  session_id: "WFS-[id]",
  task_description: "[user provided task description]",

  // Use memory if available, else load
  session_metadata: memory.has("workflow-session.json")
    ? memory.get("workflow-session.json")
    : Read(.workflow/WFS-[id]/workflow-session.json),

  // Search tools - agent will use these native tools
  search_tools: {
    ripgrep: true,
    find: true,
    exa_code: true,
    exa_web: true
  }
}

// Note: Agent will execute these steps autonomously:
// - bash(~/.claude/scripts/get_modules_by_depth.sh) for project structure
// - Read(CLAUDE.md) and Read(README.md) for documentation
```

## Session ID Integration

### Session ID Usage
- **Required Parameter**: `--session WFS-session-id`
- **Session Context Loading**: Load existing session state and metadata
- **Session Continuity**: Maintain context across workflow pipeline phases

### Session Validation
```javascript
// Validate session exists
const sessionPath = `.workflow/${session_id}`;
if (!fs.existsSync(sessionPath)) {
  console.error(`❌ Session ${session_id} not found`);
  process.exit(1);
}
```

## Success Criteria
- Valid context-package.json generated in correct location
- Contains sufficient relevant information (>80% relevance)
- Execution completes within reasonable time (<2 minutes)
- All required fields present and properly formatted
- Agent reports completion status with statistics

## Agent Reference

For complete execution details, refer to the context-search-agent documentation:
- **Location**: `.claude/agents/context-search-agent.md`
- **Capabilities**: Multi-layer discovery, intelligent filtering, dependency analysis, conflict detection
- **Output Format**: Standardized context-package.json with metadata, assets, dependencies, and risk assessment