Enhance workflow commands and context management

- Updated `plan.md` to include new fields in context-package.json: prioritized_context, user_intent, priority_tiers, dependency_order, and sorting_rationale. - Added validation for the existence of the prioritized_context field in context-package.json. - Modified user decision flow in task generation to present action choices after planning completion. - Improved context-gathering process in `context-gather.md` to integrate user intent and prioritize context based on user goals. - Revised conflict-resolution documentation to require planning notes records after conflict analysis. - Streamlined task generation in `task-generate-agent.md` to utilize pre-sorted context without redundant sorting. - Removed unused settings persistence functions and corresponding tests from `claude-cli-tools.ts` and `settings-persistence.test.ts`.
2026-03-28 20:01:17 +08:00 · 2026-01-28 00:02:45 +08:00
parent 9989cfcf21
commit b3c47294e7
8 changed files with 744 additions and 1176 deletions
--- a/.claude/commands/workflow/tools/conflict-resolution.md
+++ b/.claude/commands/workflow/tools/conflict-resolution.md
@@ -186,6 +186,17 @@ Task(subagent_type="cli-execution-agent", run_in_background=false, prompt=`
  - modifications.old_content: 20-100 chars for unique Edit tool matching
  - modifications.new_content: preserves markdown formatting
  - modification_suggestions: 2-5 actionable suggestions for custom handling
+
+  ### 5. Planning Notes Record (REQUIRED)
+  After analysis complete, append a brief execution record to planning-notes.md:
+
+  **File**: .workflow/active/{session_id}/planning-notes.md
+  **Location**: Under "## Conflict Decisions (Phase 3)" section
+  **Format**:
+  \`\`\`
+  ### [Conflict-Resolution Agent] YYYY-MM-DD
+  - **Note**: [智能补充：简短总结冲突类型、解决策略、关键决策等]
+  \`\`\`
 `)
 ```

--- a/.claude/commands/workflow/tools/context-gather.md
+++ b/.claude/commands/workflow/tools/context-gather.md
@@ -35,7 +35,7 @@ Step 1: Context-Package Detection
      ├─ Valid package exists → Return existing (skip execution)
      └─ No valid package → Continue to Step 2

-Step 2: Complexity Assessment & Parallel Explore (NEW)
+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
@@ -213,19 +213,37 @@ Write(`${sessionFolder}/explorations-manifest.json`, JSON.stringify(explorationM
 **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();
+}
+
 Task(
  subagent_type="context-search-agent",
  run_in_background=false,
  description="Gather comprehensive context for plan",
  prompt=`
 ## Execution Mode
-**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution
+**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}
@@ -245,7 +263,13 @@ Execute complete context-search-agent workflow for implementation planning:
 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:
+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)
@@ -254,13 +278,45 @@ Execute all discovery tracks:

 ### Phase 3: Synthesis, Assessment & Packaging
 1. Apply relevance scoring and build dependency graph
-2. **Synthesize 4-source data**: Merge findings from all sources (archive > docs > code > web). **Prioritize the context from `project-tech.json`** for architecture and tech stack unless code analysis reveals it's outdated.
-3. **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.
-4. **Populate `project_guidelines`**: Load conventions, constraints, and learnings from `project-guidelines.json` into a dedicated section.
-5. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
-6. Perform conflict detection with risk assessment
-7. **Inject historical conflicts** from archive analysis into conflict_detection
-8. Generate and validate context-package.json
+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:
@@ -272,6 +328,7 @@ Complete context-package.json with:
 - **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:
@@ -282,6 +339,17 @@ Before completion verify:
 - [ ] 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**: [智能补充：简短总结关键发现，如探索角度、关键文件、冲突风险等]
+\`\`\`
+
 Execute autonomously following agent documentation.
 Report completion with statistics.
 `
@@ -326,6 +394,7 @@ Refer to `context-search-agent.md` Phase 3.7 for complete `context-package.json`
 - **brainstorm_artifacts**: Brainstorm documents with full content (if exists)
 - **conflict_detection**: Risk assessment with mitigation strategies and historical conflicts
 - **exploration_results**: Aggregated exploration insights (from parallel explore phase)
+- **prioritized_context**: Pre-sorted context with user intent and priority tiers (critical/high/medium/low)

 ## Historical Archive Analysis

@@ -435,7 +504,10 @@ if (historicalConflicts.length > 0 && currentRisk === "low") {
 ## Notes

 - **Detection-first**: Always check for existing package before invoking agent
+- **User intent integration**: Load user intent from planning-notes.md (Phase 1 output) to ensure context aligns with user goals
+- **Priority sorting in Phase 2**: Track -1 (User Intent & Priority Foundation) establishes baseline priorities BEFORE other track analysis
 - **Dual project file integration**: Agent reads both `.workflow/project-tech.json` (tech analysis) and `.workflow/project-guidelines.json` (user constraints) as primary sources
 - **Guidelines injection**: Project guidelines are included in context-package to ensure task generation respects user-defined constraints
- **No redundancy**: This command is a thin orchestrator, all logic in agent
+- **Prioritized context output**: `prioritized_context` field provides pre-sorted context with priority tiers
+- **No redundancy**: Context sorting happens once (Phase 2 Track -1 + Phase 3), not duplicated in Phase 4
 - **Plan-specific**: Use this for implementation planning; brainstorm mode uses direct agent call
--- a/.claude/commands/workflow/tools/task-generate-agent.md
+++ b/.claude/commands/workflow/tools/task-generate-agent.md
@@ -19,6 +19,10 @@ Generate implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.
 ## Core Philosophy
 - **Planning Only**: Generate planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) - does NOT implement code
 - **Agent-Driven Document Generation**: Delegate plan generation to action-planning-agent
+- **NO Redundant Context Sorting**: Context priority sorting is ALREADY completed in context-gather Phase 2/3
+  - Use `context-package.json.prioritized_context` directly
+  - DO NOT re-sort files or re-compute priorities
+  - `priority_tiers` and `dependency_order` are pre-computed and ready-to-use
 - **N+1 Parallel Planning**: Auto-detect multi-module projects, enable parallel planning (2+1 or 3+1 mode)
 - **Progressive Loading**: Load context incrementally (Core → Selective → On-Demand) due to analysis.md file size
 - **Memory-First**: Reuse loaded documents from conversation memory
@@ -161,13 +165,13 @@ const userConfig = {

 ### Phase 1: Context Preparation & Module Detection (Command Responsibility)

-**Command prepares session paths, metadata, detects module structure, and loads planning-notes.md.**
+**Command prepares session paths, metadata, detects module structure. Context priority sorting is NOT performed here - it's already completed in context-gather Phase 2/3.**

 **Session Path Structure**:
 ```
 .workflow/active/WFS-{session-id}/
 ├── workflow-session.json          # Session metadata
-├── planning-notes.md              # Consolidated planning notes (NEW)
+├── planning-notes.md              # Consolidated planning notes
 ├── .process/
 │   └── context-package.json       # Context package with artifact catalog
 ├── .task/                         # Output: Task JSON files
@@ -263,7 +267,7 @@ This document contains:
 ## SESSION PATHS
 Input:
  - Session Metadata: .workflow/active/{session-id}/workflow-session.json
-  - Planning Notes: .workflow/active/{session-id}/planning-notes.md (NEW)
+  - Planning Notes: .workflow/active/{session-id}/planning-notes.md
  - Context Package: .workflow/active/{session-id}/.process/context-package.json

 Output:
@@ -291,7 +295,17 @@ CLI Resume Support (MANDATORY for all CLI commands):
 - Read previous task's cliExecutionId from session state
 - Format: ccw cli -p "[prompt]" --resume ${previousCliId} --tool ${tool} --mode write

-## EXPLORATION CONTEXT (from context-package.exploration_results)
+## PRIORITIZED CONTEXT (from context-package.prioritized_context) - ALREADY SORTED
+Context sorting is ALREADY COMPLETED in context-gather Phase 2/3. DO NOT re-sort.
+Direct usage:
+- **user_intent**: Use goal/scope/key_constraints for task alignment
+- **priority_tiers.critical**: These files are PRIMARY focus for task generation
+- **priority_tiers.high**: These files are SECONDARY focus
+- **dependency_order**: Use this for task sequencing - already computed
+- **sorting_rationale**: Reference for understanding priority decisions
+
+## EXPLORATION CONTEXT (from context-package.exploration_results) - SUPPLEMENT ONLY
+If prioritized_context is incomplete, fall back to exploration_results:
 - Load exploration_results from context-package.json
 - Use aggregated_insights.critical_files for focus_paths generation
 - Apply aggregated_insights.constraints to acceptance criteria
@@ -311,8 +325,10 @@ CLI Resume Support (MANDATORY for all CLI commands):
   - 6-field schema (id, title, status, context_package_path, meta, context, flow_control)
   - Quantified requirements with explicit counts
   - Artifacts integration from context package
-   - **focus_paths enhanced with exploration critical_files**
-   - Flow control with pre_analysis steps (include exploration integration_points analysis)
+   - **focus_paths generated directly from prioritized_context.priority_tiers (critical + high)**
+     - NO re-sorting or re-prioritization - use pre-computed tiers as-is
+     - Critical files are PRIMARY focus, High files are SECONDARY
+   - Flow control with pre_analysis steps (use prioritized_context.dependency_order for task sequencing)
   - **CLI Execution IDs and strategies (MANDATORY)**

 2. Implementation Plan (IMPL_PLAN.md)
@@ -360,6 +376,19 @@ Hard Constraints:
  - IMPL_PLAN.md created with complete structure
  - TODO_LIST.md generated matching task JSONs
 - Return completion status with document count and task breakdown summary
+
+## PLANNING NOTES RECORD (REQUIRED)
+After completing all documents, append a brief execution record to planning-notes.md:
+
+**File**: .workflow/active/{session_id}/planning-notes.md
+**Location**: Create new section after "## Consolidated Constraints"
+**Format**:
+\`\`\`
+## Task Generation (Phase 4)
+
+### [Action-Planning Agent] YYYY-MM-DD
+- **Note**: [智能补充：简短总结任务数量、关键任务、依赖关系等]
+\`\`\`
 `
 )
 ```
@@ -404,7 +433,7 @@ This document contains consolidated constraints and user intent to guide module-
 ## SESSION PATHS
 Input:
  - Session Metadata: .workflow/active/{session-id}/workflow-session.json
-  - Planning Notes: .workflow/active/{session-id}/planning-notes.md (NEW)
+  - Planning Notes: .workflow/active/{session-id}/planning-notes.md
  - Context Package: .workflow/active/{session-id}/.process/context-package.json

 Output:
@@ -430,7 +459,16 @@ CLI Resume Support (MANDATORY for all CLI commands):
 - Read previous task's cliExecutionId from session state
 - Format: ccw cli -p "[prompt]" --resume ${previousCliId} --tool ${tool} --mode write

-## EXPLORATION CONTEXT (from context-package.exploration_results)
+## PRIORITIZED CONTEXT (from context-package.prioritized_context) - ALREADY SORTED
+Context sorting is ALREADY COMPLETED in context-gather Phase 2/3. DO NOT re-sort.
+Filter by module scope (${module.paths.join(', ')}):
+- **user_intent**: Use for task alignment within module
+- **priority_tiers.critical**: Filter for files in ${module.paths.join(', ')} → PRIMARY focus
+- **priority_tiers.high**: Filter for files in ${module.paths.join(', ')} → SECONDARY focus
+- **dependency_order**: Use module-relevant entries for task sequencing
+
+## EXPLORATION CONTEXT (from context-package.exploration_results) - SUPPLEMENT ONLY
+If prioritized_context is incomplete for this module, fall back to exploration_results:
 - Load exploration_results from context-package.json
 - Filter for ${module.name} module: Use aggregated_insights.critical_files matching ${module.paths.join(', ')}
 - Apply module-relevant constraints from aggregated_insights.constraints
@@ -457,8 +495,10 @@ Task JSON Files (.task/IMPL-${module.prefix}*.json):
  - Task ID format: IMPL-${module.prefix}1, IMPL-${module.prefix}2, ...
  - Quantified requirements with explicit counts
  - Artifacts integration from context package (filtered for ${module.name})
-  - **focus_paths enhanced with exploration critical_files (module-scoped)**
-  - Flow control with pre_analysis steps (include exploration integration_points analysis)
+  - **focus_paths generated directly from prioritized_context.priority_tiers filtered by ${module.paths.join(', ')}**
+    - NO re-sorting - use pre-computed tiers filtered for this module
+    - Critical files are PRIMARY focus, High files are SECONDARY
+  - Flow control with pre_analysis steps (use prioritized_context.dependency_order for module task sequencing)
  - **CLI Execution IDs and strategies (MANDATORY)**
  - Focus ONLY on ${module.name} module scope

@@ -501,6 +541,21 @@ Hard Constraints:
 - Cross-module dependencies use CROSS:: placeholder format consistently
 - Focus paths scoped to ${module.paths.join(', ')} only
 - Return: task count, task IDs, dependency summary (internal + cross-module)
+
+## PLANNING NOTES RECORD (REQUIRED)
+After completing module task JSONs, append a brief execution record to planning-notes.md:
+
+**File**: .workflow/active/{session_id}/planning-notes.md
+**Location**: Create new section after "## Consolidated Constraints" (if not exists)
+**Format**:
+\`\`\`
+## Task Generation (Phase 4)
+
+### [Action-Planning Agent - ${module.name}] YYYY-MM-DD
+- **Note**: [智能补充：简短总结本模块任务数量、关键任务等]
+\`\`\`
+
+**Note**: Multiple module agents will append their records. Phase 3 Integration Coordinator will add final summary.
    `
  )
 );
@@ -581,6 +636,17 @@ Module Count: ${modules.length}
 - No CROSS:: placeholders remaining in task JSONs
 - IMPL_PLAN.md and TODO_LIST.md generated with multi-module structure
 - Return: task count, per-module breakdown, resolved dependency count
+
+## PLANNING NOTES RECORD (REQUIRED)
+After completing integration, append final summary to planning-notes.md:
+
+**File**: .workflow/active/{session_id}/planning-notes.md
+**Location**: Under "## Task Generation (Phase 4)" section (after module agent records)
+**Format**:
+\`\`\`
+### [Integration Coordinator] YYYY-MM-DD
+- **Note**: [智能补充：简短总结总任务数、跨模块依赖解决情况等]
+\`\`\`
  `
 )
 ```