Add tests for CLI command generation and model alias resolution

- Implement `test-cli-command-gen.js` to verify the logic of `buildCliCommand` function. - Create `test-e2e-model-alias.js` for end-to-end testing of model alias resolution in `ccw cli`. - Add `test-model-alias.js` to test model alias resolution for different models. - Introduce `test-model-alias.txt` for prompt testing with model alias. - Develop `test-update-claude-command.js` to test command generation for `update_module_claude`. - Create a test file in `test-update-claude/src` for future tests.
2026-02-11 02:33:51 +08:00 · 2026-02-05 20:17:10 +08:00
parent 6576886457
commit 01459a34a5
193 changed files with 4796 additions and 9405 deletions
--- a/.codex/skills/workflow-plan/phases/01-session-discovery.md
+++ b/.codex/skills/workflow-plan/phases/01-session-discovery.md
@@ -0,0 +1,282 @@
+# Phase 1: Session Discovery
+
+Discover existing sessions or start new workflow session with intelligent session management and conflict detection.
+
+## Objective
+
+- Ensure project-level state exists (first-time initialization)
+- Create or discover workflow session for the planning workflow
+- Generate unique session ID (WFS-xxx format)
+- Initialize session directory structure
+
+## Step 0: Initialize Project State (First-time Only)
+
+**Executed before all modes** - Ensures project-level state files exist by calling `workflow:init`.
+
+### Check and Initialize
+```bash
+# Check if project state exists (both files required)
+bash(test -f .workflow/project-tech.json && echo "TECH_EXISTS" || echo "TECH_NOT_FOUND")
+bash(test -f .workflow/project-guidelines.json && echo "GUIDELINES_EXISTS" || echo "GUIDELINES_NOT_FOUND")
+```
+
+**If either NOT_FOUND**, delegate to `workflow:init`:
+```javascript
+// Codex: Execute workflow:init command for intelligent project analysis
+codex workflow:init
+
+// Wait for init completion
+// project-tech.json and project-guidelines.json will be created
+```
+
+**Output**:
+- If BOTH_EXIST: `PROJECT_STATE: initialized`
+- If NOT_FOUND: Calls `workflow:init` → creates:
+  - `.workflow/project-tech.json` with full technical analysis
+  - `.workflow/project-guidelines.json` with empty scaffold
+
+**Note**: `workflow:init` uses cli-explore-agent to build comprehensive project understanding (technology stack, architecture, key components). This step runs once per project. Subsequent executions skip initialization.
+
+## Execution
+
+### Step 1.1: Execute Session Start
+
+```javascript
+// Codex: Execute session start command
+codex workflow:session:start --auto "[structured-task-description]"
+```
+
+**Task Description Structure**:
+```
+GOAL: [Clear, concise objective]
+SCOPE: [What's included/excluded]
+CONTEXT: [Relevant background or constraints]
+```
+
+**Example**:
+```
+GOAL: Build JWT-based authentication system
+SCOPE: User registration, login, token validation
+CONTEXT: Existing user database schema, REST API endpoints
+```
+
+### Step 1.2: Parse Output
+
+- Extract: `SESSION_ID: WFS-[id]` (store as `sessionId`)
+
+### Step 1.3: Validate
+
+- Session ID successfully extracted
+- Session directory `.workflow/active/[sessionId]/` exists
+
+**Note**: Session directory contains `workflow-session.json` (metadata). Do NOT look for `manifest.json` here - it only exists in `.workflow/archives/` for archived sessions.
+
+### Step 1.4: Initialize Planning Notes
+
+Create `planning-notes.md` with N+1 context support:
+
+```javascript
+const planningNotesPath = `.workflow/active/${sessionId}/planning-notes.md`
+const userGoal = structuredDescription.goal
+const userConstraints = structuredDescription.context || "None specified"
+
+Write(planningNotesPath, `# Planning Notes
+
+**Session**: ${sessionId}
+**Created**: ${new Date().toISOString()}
+
+## User Intent (Phase 1)
+
+- **GOAL**: ${userGoal}
+- **KEY_CONSTRAINTS**: ${userConstraints}
+
+---
+
+## Context Findings (Phase 2)
+(To be filled by context-gather)
+
+## Conflict Decisions (Phase 3)
+(To be filled if conflicts detected)
+
+## Consolidated Constraints (Phase 4 Input)
+1. ${userConstraints}
+
+---
+
+## Task Generation (Phase 4)
+(To be filled by action-planning-agent)
+
+## N+1 Context
+### Decisions
+| Decision | Rationale | Revisit? |
+|----------|-----------|----------|
+
+### Deferred
+- [ ] (For N+1)
+`)
+```
+
+## Session Types
+
+The `--type` parameter classifies sessions for CCW dashboard organization:
+
+| Type | Description | Default For |
+|------|-------------|-------------|
+| `workflow` | Standard implementation (default) | `workflow:plan` |
+| `review` | Code review sessions | `workflow:review-module-cycle` |
+| `tdd` | TDD-based development | `workflow:tdd-plan` |
+| `test` | Test generation/fix sessions | `workflow:test-fix-gen` |
+| `docs` | Documentation sessions | `memory:docs` |
+
+**Validation**: If `--type` is provided with invalid value, return error:
+```
+ERROR: Invalid session type. Valid types: workflow, review, tdd, test, docs
+```
+
+## Mode 1: Discovery Mode (Default)
+
+### Usage
+```bash
+workflow:session:start
+```
+
+### Step 1: List Active Sessions
+```bash
+bash(ls -1 .workflow/active/ 2>/dev/null | head -5)
+```
+
+### Step 2: Display Session Metadata
+```bash
+bash(cat .workflow/active/WFS-promptmaster-platform/workflow-session.json)
+```
+
+### Step 4: User Decision
+Present session information and wait for user to select or create session.
+
+**Output**: `SESSION_ID: WFS-[user-selected-id]`
+
+## Mode 2: Auto Mode (Intelligent)
+
+### Usage
+```bash
+workflow:session:start --auto "task description"
+```
+
+### Step 1: Check Active Sessions Count
+```bash
+bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | wc -l)
+```
+
+### Step 2a: No Active Sessions → Create New
+```bash
+# Generate session slug
+bash(echo "implement OAuth2 auth" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]' | cut -c1-50)
+
+# Create directory structure
+bash(mkdir -p .workflow/active/WFS-implement-oauth2-auth/.process)
+bash(mkdir -p .workflow/active/WFS-implement-oauth2-auth/.task)
+bash(mkdir -p .workflow/active/WFS-implement-oauth2-auth/.summaries)
+
+# Create metadata (include type field, default to "workflow" if not specified)
+bash(echo '{"session_id":"WFS-implement-oauth2-auth","project":"implement OAuth2 auth","status":"planning","type":"workflow","created_at":"2024-12-04T08:00:00Z"}' > .workflow/active/WFS-implement-oauth2-auth/workflow-session.json)
+```
+
+**Output**: `SESSION_ID: WFS-implement-oauth2-auth`
+
+### Step 2b: Single Active Session → Check Relevance
+```bash
+# Extract session ID
+bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename)
+
+# Read project name from metadata
+bash(cat .workflow/active/WFS-promptmaster-platform/workflow-session.json | grep -o '"project":"[^"]*"' | cut -d'"' -f4)
+
+# Check keyword match (manual comparison)
+# If task contains project keywords → Reuse session
+# If task unrelated → Create new session (use Step 2a)
+```
+
+**Output (reuse)**: `SESSION_ID: WFS-promptmaster-platform`
+**Output (new)**: `SESSION_ID: WFS-[new-slug]`
+
+### Step 2c: Multiple Active Sessions → Use First
+```bash
+# Get first active session
+bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename)
+
+# Output warning and session ID
+# WARNING: Multiple active sessions detected
+# SESSION_ID: WFS-first-session
+```
+
+## Mode 3: Force New Mode
+
+### Usage
+```bash
+workflow:session:start --new "task description"
+```
+
+### Step 1: Generate Unique Session Slug
+```bash
+# Convert to slug
+bash(echo "fix login bug" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]' | cut -c1-50)
+
+# Check if exists, add counter if needed
+bash(ls .workflow/active/WFS-fix-login-bug 2>/dev/null && echo "WFS-fix-login-bug-2" || echo "WFS-fix-login-bug")
+```
+
+### Step 2: Create Session Structure
+```bash
+bash(mkdir -p .workflow/active/WFS-fix-login-bug/.process)
+bash(mkdir -p .workflow/active/WFS-fix-login-bug/.task)
+bash(mkdir -p .workflow/active/WFS-fix-login-bug/.summaries)
+```
+
+### Step 3: Create Metadata
+```bash
+# Include type field from --type parameter (default: "workflow")
+bash(echo '{"session_id":"WFS-fix-login-bug","project":"fix login bug","status":"planning","type":"workflow","created_at":"2024-12-04T08:00:00Z"}' > .workflow/active/WFS-fix-login-bug/workflow-session.json)
+```
+
+**Output**: `SESSION_ID: WFS-fix-login-bug`
+
+## Execution Guideline
+
+- **Non-interrupting**: When called from other commands, this command completes and returns control to the caller without interrupting subsequent tasks.
+
+## Session ID Format
+
+- Pattern: `WFS-[lowercase-slug]`
+- Characters: `a-z`, `0-9`, `-` only
+- Max length: 50 characters
+- Uniqueness: Add numeric suffix if collision (`WFS-auth-2`, `WFS-auth-3`)
+
+## Output Format Specification
+
+### Success
+```
+SESSION_ID: WFS-session-slug
+```
+
+### Error
+```
+ERROR: --auto mode requires task description
+ERROR: Failed to create session directory
+```
+
+### Analysis (Auto Mode)
+```
+ANALYSIS: Task relevance = high
+DECISION: Reusing existing session
+SESSION_ID: WFS-promptmaster-platform
+```
+
+## Output
+
+- **Variable**: `sessionId` (e.g., `WFS-implement-oauth2-auth`)
+- **File**: `.workflow/active/{sessionId}/planning-notes.md`
+- **TodoWrite**: Mark Phase 1 completed, Phase 2 in_progress
+
+## Next Phase
+
+Return to orchestrator showing Phase 1 results, then auto-continue to [Phase 2: Context Gathering](02-context-gathering.md).
--- a/.codex/skills/workflow-plan/phases/02-context-gathering.md
+++ b/.codex/skills/workflow-plan/phases/02-context-gathering.md
@@ -0,0 +1,476 @@
+# Phase 2: Context Gathering
+
+Intelligently collect project context using context-search-agent based on task description, packages into standardized JSON.
+
+## Objective
+
+- Check for existing valid context-package before executing
+- Assess task complexity and launch parallel exploration agents
+- Invoke context-search-agent to analyze codebase
+- Generate standardized `context-package.json` with prioritized context
+- Detect conflict risk level for Phase 3 decision
+
+## Core Philosophy
+
+- **Agent Delegation**: Delegate all discovery to `context-search-agent` for autonomous execution
+- **Detection-First**: Check for existing context-package before executing
+- **Plan Mode**: Full comprehensive analysis (vs lightweight brainstorm mode)
+- **Standardized Output**: Generate `.workflow/active/{session}/.process/context-package.json`
+- **Explicit Lifecycle**: Manage subagent creation, waiting, and cleanup
+
+## Execution Process
+
+```
+Input Parsing:
+   ├─ Parse flags: --session
+   └─ Parse: task_description (required)
+
+Step 1: Context-Package Detection
+   └─ Decision (existing package):
+      ├─ Valid package exists → Return existing (skip execution)
+      └─ No valid package → Continue to Step 2
+
+Step 2: Complexity Assessment & Parallel Explore
+   ├─ Analyze task_description → classify Low/Medium/High
+   ├─ Select exploration angles (1-4 based on complexity)
+   ├─ Launch N cli-explore-agents in parallel (spawn_agent)
+   │  └─ Each outputs: exploration-{angle}.json
+   ├─ Wait for all agents (batch wait)
+   ├─ Close all agents
+   └─ Generate explorations-manifest.json
+
+Step 3: Invoke Context-Search Agent (with exploration input)
+   ├─ Phase 1: Initialization & Pre-Analysis
+   ├─ Phase 2: Multi-Source Discovery
+   │  ├─ Track 0: Exploration Synthesis (prioritize & deduplicate)
+   │  ├─ Track 1-4: Existing tracks
+   └─ Phase 3: Synthesis & Packaging
+      └─ Generate context-package.json with exploration_results
+   └─ Lifecycle: spawn_agent → wait → close_agent
+
+Step 4: Output Verification
+   └─ Verify context-package.json contains exploration_results
+```
+
+## Execution Flow
+
+### Step 1: Context-Package Detection
+
+**Execute First** - Check if valid package already exists:
+
+```javascript
+const contextPackagePath = `.workflow/${session_id}/.process/context-package.json`;
+
+if (file_exists(contextPackagePath)) {
+  const existing = Read(contextPackagePath);
+
+  // Validate package belongs to current session
+  if (existing?.metadata?.session_id === session_id) {
+    console.log("Valid context-package found for session:", session_id);
+    console.log("Stats:", existing.statistics);
+    console.log("Conflict Risk:", existing.conflict_detection.risk_level);
+    return existing; // Skip execution, return existing
+  } else {
+    console.warn("Invalid session_id in existing package, re-generating...");
+  }
+}
+```
+
+### Step 2: Complexity Assessment & Parallel Explore
+
+**Only execute if Step 1 finds no valid package**
+
+```javascript
+// 2.1 Complexity Assessment
+function analyzeTaskComplexity(taskDescription) {
+  const text = taskDescription.toLowerCase();
+  if (/architect|refactor|restructure|modular|cross-module/.test(text)) return 'High';
+  if (/multiple|several|integrate|migrate|extend/.test(text)) return 'Medium';
+  return 'Low';
+}
+
+const ANGLE_PRESETS = {
+  architecture: ['architecture', 'dependencies', 'modularity', 'integration-points'],
+  security: ['security', 'auth-patterns', 'dataflow', 'validation'],
+  performance: ['performance', 'bottlenecks', 'caching', 'data-access'],
+  bugfix: ['error-handling', 'dataflow', 'state-management', 'edge-cases'],
+  feature: ['patterns', 'integration-points', 'testing', 'dependencies'],
+  refactor: ['architecture', 'patterns', 'dependencies', 'testing']
+};
+
+function selectAngles(taskDescription, complexity) {
+  const text = taskDescription.toLowerCase();
+  let preset = 'feature';
+  if (/refactor|architect|restructure/.test(text)) preset = 'architecture';
+  else if (/security|auth|permission/.test(text)) preset = 'security';
+  else if (/performance|slow|optimi/.test(text)) preset = 'performance';
+  else if (/fix|bug|error|issue/.test(text)) preset = 'bugfix';
+
+  const count = complexity === 'High' ? 4 : (complexity === 'Medium' ? 3 : 1);
+  return ANGLE_PRESETS[preset].slice(0, count);
+}
+
+const complexity = analyzeTaskComplexity(task_description);
+const selectedAngles = selectAngles(task_description, complexity);
+const sessionFolder = `.workflow/active/${session_id}/.process`;
+
+// 2.2 Launch Parallel Explore Agents
+const explorationAgents = [];
+
+// Spawn all agents in parallel
+selectedAngles.forEach((angle, index) => {
+  const agentId = spawn_agent({
+    message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
+2. Read: .workflow/project-tech.json
+3. Read: .workflow/project-guidelines.json
+
+---
+
+## Task Objective
+Execute **${angle}** exploration for task planning context. Analyze codebase from this specific angle to discover relevant structure, patterns, and constraints.
+
+## Assigned Context
+- **Exploration Angle**: ${angle}
+- **Task Description**: ${task_description}
+- **Session ID**: ${session_id}
+- **Exploration Index**: ${index + 1} of ${selectedAngles.length}
+- **Output File**: ${sessionFolder}/exploration-${angle}.json
+
+## MANDATORY FIRST STEPS (Execute by Agent)
+**You (cli-explore-agent) MUST execute these steps in order:**
+1. Run: ccw tool exec get_modules_by_depth '{}' (project structure)
+2. Run: rg -l "{keyword_from_task}" --type ts (locate relevant files)
+3. Execute: cat ~/.claude/workflows/cli-templates/schemas/explore-json-schema.json (get output schema reference)
+
+## Exploration Strategy (${angle} focus)
+
+**Step 1: Structural Scan** (Bash)
+- get_modules_by_depth.sh → identify modules related to ${angle}
+- find/rg → locate files relevant to ${angle} aspect
+- Analyze imports/dependencies from ${angle} perspective
+
+**Step 2: Semantic Analysis** (Gemini CLI)
+- How does existing code handle ${angle} concerns?
+- What patterns are used for ${angle}?
+- Where would new code integrate from ${angle} viewpoint?
+
+**Step 3: Write Output**
+- Consolidate ${angle} findings into JSON
+- Identify ${angle}-specific clarification needs
+
+## Expected Output
+
+**File**: ${sessionFolder}/exploration-${angle}.json
+
+**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 3, follow schema exactly
+
+**Required Fields** (all ${angle} focused):
+- project_structure: Modules/architecture relevant to ${angle}
+- relevant_files: Files affected from ${angle} perspective
+  **IMPORTANT**: Use object format with relevance scores for synthesis:
+  \`[{path: "src/file.ts", relevance: 0.85, rationale: "Core ${angle} logic"}]\`
+  Scores: 0.7+ high priority, 0.5-0.7 medium, <0.5 low
+- patterns: ${angle}-related patterns to follow
+- dependencies: Dependencies relevant to ${angle}
+- integration_points: Where to integrate from ${angle} viewpoint (include file:line locations)
+- constraints: ${angle}-specific limitations/conventions
+- clarification_needs: ${angle}-related ambiguities (options array + recommended index)
+- _metadata.exploration_angle: "${angle}"
+
+## Success Criteria
+- [ ] Schema obtained via cat explore-json-schema.json
+- [ ] get_modules_by_depth.sh executed
+- [ ] At least 3 relevant files identified with ${angle} rationale
+- [ ] Patterns are actionable (code examples, not generic advice)
+- [ ] Integration points include file:line locations
+- [ ] Constraints are project-specific to ${angle}
+- [ ] JSON output follows schema exactly
+- [ ] clarification_needs includes options + recommended
+
+## Output
+Write: ${sessionFolder}/exploration-${angle}.json
+Return: 2-3 sentence summary of ${angle} findings
+`
+  });
+  
+  explorationAgents.push(agentId);
+});
+
+// 2.3 Batch wait for all exploration agents
+const explorationResults = wait({
+  ids: explorationAgents,
+  timeout_ms: 600000  // 10 minutes
+});
+
+// Check for timeouts
+if (explorationResults.timed_out) {
+  console.log('Some exploration agents timed out - continuing with completed results');
+}
+
+// 2.4 Close all exploration agents
+explorationAgents.forEach(agentId => {
+  close_agent({ id: agentId });
+});
+
+// 2.5 Generate Manifest after all complete
+const explorationFiles = bash(`find ${sessionFolder} -name "exploration-*.json" -type f`).split('\n').filter(f => f.trim());
+const explorationManifest = {
+  session_id,
+  task_description,
+  timestamp: new Date().toISOString(),
+  complexity,
+  exploration_count: selectedAngles.length,
+  angles_explored: selectedAngles,
+  explorations: explorationFiles.map(file => {
+    const data = JSON.parse(Read(file));
+    return { angle: data._metadata.exploration_angle, file: file.split('/').pop(), path: file, index: data._metadata.exploration_index };
+  })
+};
+Write(`${sessionFolder}/explorations-manifest.json`, JSON.stringify(explorationManifest, null, 2));
+```
+
+### Step 3: Invoke Context-Search Agent
+
+**Only execute after Step 2 completes**
+
+```javascript
+// Load user intent from planning-notes.md (from Phase 1)
+const planningNotesPath = `.workflow/active/${session_id}/planning-notes.md`;
+let userIntent = { goal: task_description, key_constraints: "None specified" };
+
+if (file_exists(planningNotesPath)) {
+  const notesContent = Read(planningNotesPath);
+  const goalMatch = notesContent.match(/\*\*GOAL\*\*:\s*(.+)/);
+  const constraintsMatch = notesContent.match(/\*\*KEY_CONSTRAINTS\*\*:\s*(.+)/);
+  if (goalMatch) userIntent.goal = goalMatch[1].trim();
+  if (constraintsMatch) userIntent.key_constraints = constraintsMatch[1].trim();
+}
+
+// Spawn context-search-agent
+const contextAgentId = spawn_agent({
+  message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/context-search-agent.md (MUST read first)
+2. Read: .workflow/project-tech.json
+3. Read: .workflow/project-guidelines.json
+
+---
+
+## Execution Mode
+**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution with priority sorting
+
+## Session Information
+- **Session ID**: ${session_id}
+- **Task Description**: ${task_description}
+- **Output Path**: .workflow/${session_id}/.process/context-package.json
+
+## User Intent (from Phase 1 - Planning Notes)
+**GOAL**: ${userIntent.goal}
+**KEY_CONSTRAINTS**: ${userIntent.key_constraints}
+
+This is the PRIMARY context source - all subsequent analysis must align with user intent.
+
+## Exploration Input (from Step 2)
+- **Manifest**: ${sessionFolder}/explorations-manifest.json
+- **Exploration Count**: ${explorationManifest.exploration_count}
+- **Angles**: ${explorationManifest.angles_explored.join(', ')}
+- **Complexity**: ${complexity}
+
+## Mission
+Execute complete context-search-agent workflow for implementation planning:
+
+### Phase 1: Initialization & Pre-Analysis
+1. **Project State Loading**:
+   - Read and parse \`.workflow/project-tech.json\`. Use its \`overview\` section as the foundational \`project_context\`. This is your primary source for architecture, tech stack, and key components.
+   - Read and parse \`.workflow/project-guidelines.json\`. Load \`conventions\`, \`constraints\`, and \`learnings\` into a \`project_guidelines\` section.
+   - If files don't exist, proceed with fresh analysis.
+2. **Detection**: Check for existing context-package (early exit if valid)
+3. **Foundation**: Initialize CodexLens, get project structure, load docs
+4. **Analysis**: Extract keywords, determine scope, classify complexity based on task description and project state
+
+### Phase 2: Multi-Source Context Discovery
+Execute all discovery tracks (WITH USER INTENT INTEGRATION):
+- **Track -1**: User Intent & Priority Foundation (EXECUTE FIRST)
+  - Load user intent (GOAL, KEY_CONSTRAINTS) from session input
+  - Map user requirements to codebase entities (files, modules, patterns)
+  - Establish baseline priority scores based on user goal alignment
+  - Output: user_intent_mapping.json with preliminary priority scores
+
+- **Track 0**: Exploration Synthesis (load ${sessionFolder}/explorations-manifest.json, prioritize critical_files, deduplicate patterns/integration_points)
+- **Track 1**: Historical archive analysis (query manifest.json for lessons learned)
+- **Track 2**: Reference documentation (CLAUDE.md, architecture docs)
+- **Track 3**: Web examples (use Exa MCP for unfamiliar tech/APIs)
+- **Track 4**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests)
+
+### Phase 3: Synthesis, Assessment & Packaging
+1. Apply relevance scoring and build dependency graph
+2. **Synthesize 5-source data** (including Track -1): Merge findings from all sources
+   - Priority order: User Intent > Archive > Docs > Exploration > Code > Web
+   - **Prioritize the context from \`project-tech.json\`** for architecture and tech stack unless code analysis reveals it's outdated
+3. **Context Priority Sorting**:
+   a. Combine scores from Track -1 (user intent alignment) + relevance scores + exploration critical_files
+   b. Classify files into priority tiers:
+      - **Critical** (score >= 0.85): Directly mentioned in user goal OR exploration critical_files
+      - **High** (0.70-0.84): Key dependencies, patterns required for goal
+      - **Medium** (0.50-0.69): Supporting files, indirect dependencies
+      - **Low** (< 0.50): Contextual awareness only
+   c. Generate dependency_order: Based on dependency graph + user goal sequence
+   d. Document sorting_rationale: Explain prioritization logic
+
+4. **Populate \`project_context\`**: Directly use the \`overview\` from \`project-tech.json\` to fill the \`project_context\` section. Include description, technology_stack, architecture, and key_components.
+5. **Populate \`project_guidelines\`**: Load conventions, constraints, and learnings from \`project-guidelines.json\` into a dedicated section.
+6. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
+7. Perform conflict detection with risk assessment
+8. **Inject historical conflicts** from archive analysis into conflict_detection
+9. **Generate prioritized_context section**:
+   \`\`\`json
+   {
+     "prioritized_context": {
+       "user_intent": {
+         "goal": "...",
+         "scope": "...",
+         "key_constraints": ["..."]
+       },
+       "priority_tiers": {
+         "critical": [{ "path": "...", "relevance": 0.95, "rationale": "..." }],
+         "high": [...],
+         "medium": [...],
+         "low": [...]
+       },
+       "dependency_order": ["module1", "module2", "module3"],
+       "sorting_rationale": "Based on user goal alignment (Track -1), exploration critical files, and dependency graph analysis"
+     }
+   }
+   \`\`\`
+10. Generate and validate context-package.json with prioritized_context field
+
+## Output Requirements
+Complete context-package.json with:
+- **metadata**: task_description, keywords, complexity, tech_stack, session_id
+- **project_context**: description, technology_stack, architecture, key_components (sourced from \`project-tech.json\`)
+- **project_guidelines**: {conventions, constraints, quality_rules, learnings} (sourced from \`project-guidelines.json\`)
+- **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores
+- **dependencies**: {internal[], external[]} with dependency graph
+- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content
+- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy, historical_conflicts[]}
+- **exploration_results**: {manifest_path, exploration_count, angles, explorations[], aggregated_insights} (from Track 0)
+- **prioritized_context**: {user_intent, priority_tiers{critical, high, medium, low}, dependency_order[], sorting_rationale}
+
+## Quality Validation
+Before completion verify:
+- [ ] Valid JSON format with all required fields
+- [ ] File relevance accuracy >80%
+- [ ] Dependency graph complete (max 2 transitive levels)
+- [ ] Conflict risk level calculated correctly
+- [ ] No sensitive data exposed
+- [ ] Total files <=50 (prioritize high-relevance)
+
+## Planning Notes Record (REQUIRED)
+After completing context-package.json, append a brief execution record to planning-notes.md:
+
+**File**: .workflow/active/${session_id}/planning-notes.md
+**Location**: Under "## Context Findings (Phase 2)" section
+**Format**:
+\`\`\`
+### [Context-Search Agent] YYYY-MM-DD
+- **Note**: [brief summary of key findings]
+\`\`\`
+
+Execute autonomously following agent documentation.
+Report completion with statistics.
+`
+});
+
+// Wait for context agent to complete
+const contextResult = wait({
+  ids: [contextAgentId],
+  timeout_ms: 900000  // 15 minutes
+});
+
+// Close context agent
+close_agent({ id: contextAgentId });
+```
+
+### Step 4: Output Verification
+
+After agent completes, verify output:
+
+```javascript
+// Verify file was created
+const outputPath = `.workflow/${session_id}/.process/context-package.json`;
+if (!file_exists(outputPath)) {
+  throw new Error("Agent failed to generate context-package.json");
+}
+
+// Verify exploration_results included
+const pkg = JSON.parse(Read(outputPath));
+if (pkg.exploration_results?.exploration_count > 0) {
+  console.log(`Exploration results aggregated: ${pkg.exploration_results.exploration_count} angles`);
+}
+```
+
+## Parameter Reference
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `--session` | string | Yes | Workflow session ID (e.g., WFS-user-auth) |
+| `task_description` | string | Yes | Detailed task description for context extraction |
+
+## Post-Phase Update
+
+After context-gather completes, update planning-notes.md:
+
+```javascript
+const contextPackage = JSON.parse(Read(contextPath))
+const conflictRisk = contextPackage.conflict_detection?.risk_level || 'low'
+const criticalFiles = (contextPackage.exploration_results?.aggregated_insights?.critical_files || [])
+  .slice(0, 5).map(f => f.path)
+const archPatterns = contextPackage.project_context?.architecture_patterns || []
+const constraints = contextPackage.exploration_results?.aggregated_insights?.constraints || []
+
+// Update Phase 2 section
+Edit(planningNotesPath, {
+  old: '## Context Findings (Phase 2)\n(To be filled by context-gather)',
+  new: `## Context Findings (Phase 2)
+
+- **CRITICAL_FILES**: ${criticalFiles.join(', ') || 'None identified'}
+- **ARCHITECTURE**: ${archPatterns.join(', ') || 'Not detected'}
+- **CONFLICT_RISK**: ${conflictRisk}
+- **CONSTRAINTS**: ${constraints.length > 0 ? constraints.join('; ') : 'None'}`
+})
+
+// Append Phase 2 constraints to consolidated list
+Edit(planningNotesPath, {
+  old: '## Consolidated Constraints (Phase 4 Input)',
+  new: `## Consolidated Constraints (Phase 4 Input)
+${constraints.map((c, i) => `${i + 2}. [Context] ${c}`).join('\n')}`
+})
+```
+
+## Notes
+
+- **Detection-first**: Always check for existing package before invoking agent
+- **User intent integration**: Load user intent from planning-notes.md (Phase 1 output)
+- **Output**: Generates `context-package.json` with `prioritized_context` field
+- **Plan-specific**: Use this for implementation planning; brainstorm mode uses direct agent call
+- **Explicit Lifecycle**: Always close_agent after wait to free resources
+- **Batch Wait**: Use single wait call for multiple parallel agents for efficiency
+
+## Output
+
+- **Variable**: `contextPath` (e.g., `.workflow/active/WFS-xxx/.process/context-package.json`)
+- **Variable**: `conflictRisk` (none/low/medium/high)
+- **File**: Updated `planning-notes.md` with context findings
+- **Decision**: If `conflictRisk >= medium` → Phase 3, else → Phase 4
+
+## Next Phase
+
+Return to orchestrator showing Phase 2 results, then auto-continue:
+- If `conflict_risk >= medium` → [Phase 3: Conflict Resolution](03-conflict-resolution.md)
+- If `conflict_risk < medium` → [Phase 4: Task Generation](04-task-generation.md)