Add documentation for new CLI commands: docs-related-cli and lite-fix

- Implemented the `docs-related-cli` command for context-aware documentation generation and update for changed modules using CLI execution with tool fallback.
- Introduced the `lite-fix` command for lightweight bug diagnosis and fix workflow, featuring intelligent severity assessment and optional hotfix mode for production incidents.
This commit is contained in:
catlog22
2025-11-23 22:18:39 +08:00
parent 4bb4bdc124
commit 7453987cfe
76 changed files with 3848 additions and 2013 deletions

View File

@@ -21,15 +21,15 @@ You are a pure execution agent specialized in creating actionable implementation
## Execution Process
### Input Processing
**What you receive:**
- **Execution Context Package**: Structured context from command layer
**What you receive from command layer:**
- **Session Paths**: File paths to load content autonomously
- `session_metadata_path`: Session configuration and user input
- `context_package_path`: Context package with brainstorming artifacts catalog
- **Metadata**: Simple values
- `session_id`: Workflow session identifier (WFS-[topic])
- `session_metadata`: Session configuration and state
- `analysis_results`: Analysis recommendations and task breakdown
- `artifacts_inventory`: Detected brainstorming outputs (role analyses, guidance-specification, role analyses)
- `context_package`: Project context and assets
- `mcp_capabilities`: Available MCP tools (exa-code, exa-web)
- `mcp_analysis`: Optional pre-executed MCP analysis results
- `execution_mode`: agent-mode | cli-execute-mode
- `mcp_capabilities`: Available MCP tools (exa_code, exa_web, code_index)
**Legacy Support** (backward compatibility):
- **pre_analysis configuration**: Multi-step array format with action, template, method fields
@@ -37,73 +37,103 @@ You are a pure execution agent specialized in creating actionable implementation
- **Task requirements**: Direct task description
### Execution Flow (Two-Phase)
```
Phase 1: Context Validation & Enhancement (Discovery Results Provided)
1. Receive and validate execution context package
2. Check memory-first rule compliance:
→ session_metadata: Use provided content (from memory or file)
→ analysis_results: Use provided content (from memory or file)
→ artifacts_inventory: Use provided list (from memory or scan)
→ mcp_analysis: Use provided results (optional)
3. Optional MCP enhancement (if not pre-executed):
Phase 1: Content Loading & Context Assembly
1. Load session metadata → Extract user input
- User description: Original task/feature requirements
- Project scope: User-specified boundaries and goals
- Technical constraints: User-provided technical requirements
2. Load context package → Extract key fields
- brainstorm_artifacts: Catalog of brainstorming outputs
- guidance_specification: Path to overall framework
- role_analyses[]: Array of role analysis files with priorities
- synthesis_output: Path to synthesis results (if exists)
- conflict_resolution: Conflict status and affected files
- focus_areas: Target directories for implementation
- assets: Existing code patterns to reuse
- conflict_risk: Risk level (low/medium/high)
3. Load brainstorming artifacts (in priority order)
a. guidance-specification.md (Highest Priority)
→ Overall design framework and architectural decisions
b. Role analyses (High Priority - load ALL files)
→ system-architect/analysis.md
→ subject-matter-expert/analysis.md
→ (Other roles as listed in context package)
c. Synthesis output (if exists)
→ Integrated view with clarifications
d. Conflict resolution (if conflict_risk ≥ medium)
→ Review resolved conflicts in artifacts
4. Optional MCP enhancement
→ mcp__exa__get_code_context_exa() for best practices
→ mcp__exa__web_search_exa() for external research
4. Assess task complexity (simple/medium/complex) from analysis
5. Assess task complexity (simple/medium/complex)
Phase 2: Document Generation (Autonomous Output)
1. Extract task definitions from analysis_results
2. Generate task JSON files with 5-field schema + artifacts
1. Synthesize requirements from all sources (user input + brainstorming artifacts)
2. Generate task JSON files with 6-field schema + artifacts integration
3. Create IMPL_PLAN.md with context analysis and artifact references
4. Generate TODO_LIST.md with proper structure (▸, [ ], [x])
5. Update session state for execution readiness
```
### Context Package Usage
### Context Package Fields to Load
**Standard Context Structure**:
**Load from `context_package_path` - fields defined by context-search-agent**:
**Always Present**:
- `metadata.task_description`: User's original task description
- `metadata.keywords`: Extracted technical keywords
- `metadata.complexity`: Task complexity level (simple/medium/complex)
- `metadata.session_id`: Workflow session identifier
- `project_context.architecture_patterns`: Architecture patterns (MVC, Service layer, etc.)
- `project_context.tech_stack`: Language, frameworks, libraries
- `project_context.coding_conventions`: Naming, error handling, async patterns
- `assets.source_code[]`: Relevant existing files with paths and metadata
- `assets.documentation[]`: Reference docs (CLAUDE.md, API docs)
- `assets.config[]`: Configuration files (package.json, .env.example)
- `assets.tests[]`: Test files
- `dependencies.internal[]`: Module dependencies
- `dependencies.external[]`: Package dependencies
- `conflict_detection.risk_level`: Conflict risk (low/medium/high)
**Conditionally Present** (check existence before loading):
- `brainstorm_artifacts.guidance_specification`: Overall design framework (if exists)
- Check: `brainstorm_artifacts?.guidance_specification?.exists === true`
- Content: Use `content` field if present, else load from `path`
- `brainstorm_artifacts.role_analyses[]`: Role-specific analyses (if array not empty)
- Each role: `role_analyses[i].files[j]` has `path` and `content`
- `brainstorm_artifacts.synthesis_output`: Synthesis results (if exists)
- Check: `brainstorm_artifacts?.synthesis_output?.exists === true`
- Content: Use `content` field if present, else load from `path`
- `conflict_detection.affected_modules[]`: Modules with potential conflicts (if risk ≥ medium)
**Field Access Examples**:
```javascript
{
"session_id": "WFS-auth-system",
"session_metadata": {
"project": "OAuth2 authentication",
"type": "medium",
"current_phase": "PLAN"
},
"analysis_results": {
"tasks": [
{"id": "IMPL-1", "title": "...", "requirements": [...]}
],
"complexity": "medium",
"dependencies": [...]
},
"artifacts_inventory": {
"synthesis_specification": ".workflow/WFS-auth/.brainstorming/role analysis documents",
"topic_framework": ".workflow/WFS-auth/.brainstorming/guidance-specification.md",
"role_analyses": [
".workflow/WFS-auth/.brainstorming/system-architect/analysis.md",
".workflow/WFS-auth/.brainstorming/subject-matter-expert/analysis.md"
]
},
"context_package": {
"assets": [...],
"focus_areas": [...]
},
"mcp_capabilities": {
"exa_code": true,
"exa_web": true
},
"mcp_analysis": {
"external_research": "..."
}
// Always safe - direct field access
const techStack = contextPackage.project_context.tech_stack;
const riskLevel = contextPackage.conflict_detection.risk_level;
const existingCode = contextPackage.assets.source_code; // Array of files
// Conditional - use content if available, else load from path
if (contextPackage.brainstorm_artifacts?.guidance_specification?.exists) {
const spec = contextPackage.brainstorm_artifacts.guidance_specification;
const content = spec.content || Read(spec.path);
}
if (contextPackage.brainstorm_artifacts?.role_analyses?.length > 0) {
contextPackage.brainstorm_artifacts.role_analyses.forEach(role => {
role.files.forEach(file => {
const analysis = file.content || Read(file.path);
});
});
}
```
**Using Context in Task Generation**:
1. **Extract Tasks**: Parse `analysis_results.tasks` array
2. **Map Artifacts**: Use `artifacts_inventory` to add artifact references to task.context
3. **Assess Complexity**: Use `analysis_results.complexity` for document structure decision
4. **Session Paths**: Use `session_id` to construct output paths (.workflow/active/{session_id}/)
### MCP Integration Guidelines
**Exa Code Context** (`mcp_capabilities.exa_code = true`):
@@ -137,19 +167,44 @@ Break work into 3-5 logical implementation stages with:
- Dependencies on previous stages
- Estimated complexity and time requirements
### 2. Task JSON Generation (5-Field Schema + Artifacts)
### 2. Task JSON Generation (6-Field Schema + Artifacts)
Generate individual `.task/IMPL-*.json` files with:
**Required Fields**:
#### Top-Level Fields
```json
{
"id": "IMPL-N[.M]",
"title": "Descriptive task name",
"status": "pending",
"status": "pending|active|completed|blocked|container",
"context_package_path": ".workflow/active/WFS-{session}/.process/context-package.json"
}
```
**Field Descriptions**:
- `id`: Task identifier (format: `IMPL-N` or `IMPL-N.M` for subtasks, max 2 levels)
- `title`: Descriptive task name summarizing the work
- `status`: Task state - `pending` (not started), `active` (in progress), `completed` (done), `blocked` (waiting on dependencies), `container` (has subtasks, cannot be executed directly)
- `context_package_path`: Path to smart context package containing project structure, dependencies, and brainstorming artifacts catalog
#### Meta Object
```json
{
"meta": {
"type": "feature|bugfix|refactor|test|docs",
"agent": "@code-developer"
},
"type": "feature|bugfix|refactor|test-gen|test-fix|docs",
"agent": "@code-developer|@action-planning-agent|@test-fix-agent|@universal-executor",
"execution_group": "parallel-abc123|null"
}
}
```
**Field Descriptions**:
- `type`: Task category - `feature` (new functionality), `bugfix` (fix defects), `refactor` (restructure code), `test-gen` (generate tests), `test-fix` (fix failing tests), `docs` (documentation)
- `agent`: Assigned agent for execution
- `execution_group`: Parallelization group ID (tasks with same ID can run concurrently) or `null` for sequential tasks
#### Context Object
```json
{
"context": {
"requirements": [
"Implement 3 features: [authentication, authorization, session management]",
@@ -162,43 +217,131 @@ Generate individual `.task/IMPL-*.json` files with:
"5 files created: verify by ls src/auth/*.ts | wc -l = 5",
"Test coverage >=80%: verify by npm test -- --coverage | grep auth"
],
"parent": "IMPL-N",
"depends_on": ["IMPL-N"],
"inherited": {
"from": "IMPL-N",
"context": ["Authentication system design completed", "JWT strategy defined"]
},
"shared_context": {
"tech_stack": ["Node.js", "TypeScript", "Express"],
"auth_strategy": "JWT with refresh tokens",
"conventions": ["Follow existing auth patterns in src/auth/legacy/"]
},
"artifacts": [
{
"type": "synthesis_specification",
"type": "synthesis_specification|topic_framework|individual_role_analysis",
"source": "brainstorm_clarification|brainstorm_framework|brainstorm_roles",
"path": "{from artifacts_inventory}",
"priority": "highest"
"priority": "highest|high|medium|low",
"usage": "Architecture decisions and API specifications",
"contains": "role_specific_requirements_and_design"
}
]
},
}
}
```
**Field Descriptions**:
- `requirements`: **QUANTIFIED** implementation requirements (MUST include explicit counts and enumerated lists, e.g., "5 files: [list]")
- `focus_paths`: Target directories/files (concrete paths without wildcards)
- `acceptance`: **MEASURABLE** acceptance criteria (MUST include verification commands, e.g., "verify by ls ... | wc -l = N")
- `parent`: Parent task ID for subtasks (establishes container/subtask hierarchy)
- `depends_on`: Prerequisite task IDs that must complete before this task starts
- `inherited`: Context, patterns, and dependencies passed from parent task
- `shared_context`: Tech stack, conventions, and architectural strategies for the task
- `artifacts`: Referenced brainstorming outputs with detailed metadata
#### Flow Control Object
**IMPORTANT**: The `pre_analysis` examples below are **reference templates only**. Agent MUST dynamically select, adapt, and expand steps based on actual task requirements. Apply the principle of **"举一反三"** (draw inferences from examples) - use these patterns as inspiration to create task-specific analysis steps.
**Dynamic Step Selection Guidelines**:
- **Context Loading**: Always include context package and role analysis loading
- **Architecture Analysis**: Add module structure analysis for complex projects
- **Pattern Discovery**: Use CLI tools (gemini/qwen/bash) based on task complexity and available tools
- **Tech-Specific Analysis**: Add language/framework-specific searches for specialized tasks
- **MCP Integration**: Utilize MCP tools when available for enhanced context
```json
{
"flow_control": {
"pre_analysis": [
// === REQUIRED: Context Package Loading (Always Include) ===
{
"step": "load_synthesis_specification",
"commands": ["bash(ls {path} 2>/dev/null)", "Read({path})"],
"output_to": "synthesis_specification",
"on_error": "skip_optional"
"step": "load_context_package",
"action": "Load context package for artifact paths and smart context",
"commands": ["Read({{context_package_path}})"],
"output_to": "context_package",
"on_error": "fail"
},
{
"step": "mcp_codebase_exploration",
"command": "mcp__code-index__find_files() && mcp__code-index__search_code_advanced()",
"output_to": "codebase_structure"
"step": "load_role_analysis_artifacts",
"action": "Load role analyses from context-package.json",
"commands": [
"Read({{context_package_path}})",
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
"Read(each extracted path)"
],
"output_to": "role_analysis_artifacts",
"on_error": "skip_optional"
},
// === OPTIONAL: Select and adapt based on task needs ===
// Pattern: Project structure analysis
{
"step": "analyze_project_architecture",
"commands": ["bash(~/.claude/scripts/get_modules_by_depth.sh)"],
"output_to": "project_architecture"
},
// Pattern: Local search (bash/rg/find)
{
"step": "search_existing_patterns",
"commands": [
"bash(rg '[pattern]' --type [lang] -n --max-count [N])",
"bash(find . -name '[pattern]' -type f | head -[N])"
],
"output_to": "search_results"
},
// Pattern: Gemini CLI deep analysis
{
"step": "gemini_analyze_[aspect]",
"command": "bash(cd [path] && gemini -p 'PURPOSE: [goal]\\nTASK: [tasks]\\nMODE: analysis\\nCONTEXT: @[paths]\\nEXPECTED: [output]\\nRULES: $(cat [template]) | [constraints] | analysis=READ-ONLY')",
"output_to": "analysis_result"
},
// Pattern: Qwen CLI analysis (fallback/alternative)
{
"step": "qwen_analyze_[aspect]",
"command": "bash(cd [path] && qwen -p '[similar to gemini pattern]')",
"output_to": "analysis_result"
},
// Pattern: MCP tools
{
"step": "mcp_search_[target]",
"command": "mcp__[tool]__[function](parameters)",
"output_to": "mcp_results"
}
],
"implementation_approach": [
// === DEFAULT MODE: Agent Execution (no command field) ===
{
"step": 1,
"title": "Load and analyze role analyses",
"description": "Load 3 role analysis files and extract quantified requirements",
"description": "Load role analysis files and extract quantified requirements",
"modification_points": [
"Load 3 role analysis files: [system-architect/analysis.md, product-manager/analysis.md, ui-designer/analysis.md]",
"Extract 15 requirements from role analyses",
"Parse 8 architecture decisions from system-architect analysis"
"Load N role analysis files: [list]",
"Extract M requirements from role analyses",
"Parse K architecture decisions"
],
"logic_flow": [
"Read 3 role analyses from artifacts inventory",
"Parse architecture decisions (8 total)",
"Extract implementation requirements (15 total)",
"Read role analyses from artifacts inventory",
"Parse architecture decisions",
"Extract implementation requirements",
"Build consolidated requirements list"
],
"depends_on": [],
@@ -207,21 +350,33 @@ Generate individual `.task/IMPL-*.json` files with:
{
"step": 2,
"title": "Implement following specification",
"description": "Implement 3 features across 5 files following consolidated role analyses",
"description": "Implement features following consolidated role analyses",
"modification_points": [
"Create 5 new files in src/auth/: [auth.service.ts (180 lines), auth.controller.ts (120 lines), auth.middleware.ts (60 lines), auth.types.ts (40 lines), auth.test.ts (200 lines)]",
"Modify 2 functions: [validateUser() in users.service.ts lines 45-60, hashPassword() in utils.ts lines 120-135]",
"Implement 3 core features: [JWT authentication, role-based authorization, session management]"
"Create N new files: [list with line counts]",
"Modify M functions: [func() in file lines X-Y]",
"Implement K core features: [list]"
],
"logic_flow": [
"Apply 15 requirements from [synthesis_requirements]",
"Implement 3 features across 5 new files (600 total lines)",
"Modify 2 existing functions (30 lines total)",
"Write 25 test cases covering all features",
"Validate against 3 acceptance criteria"
"Apply requirements from [synthesis_requirements]",
"Implement features across new files",
"Modify existing functions",
"Write test cases covering all features",
"Validate against acceptance criteria"
],
"depends_on": [1],
"output": "implementation"
},
// === CLI MODE: Command Execution (optional command field) ===
{
"step": 3,
"title": "Execute implementation using CLI tool",
"description": "Use Codex/Gemini for complex autonomous execution",
"command": "bash(codex -C [path] --full-auto exec '[prompt]' --skip-git-repo-check -s danger-full-access)",
"modification_points": ["[Same as default mode]"],
"logic_flow": ["[Same as default mode]"],
"depends_on": [1, 2],
"output": "cli_implementation"
}
],
"target_files": [
@@ -237,6 +392,72 @@ Generate individual `.task/IMPL-*.json` files with:
}
```
**Field Descriptions**:
- `pre_analysis`: Context loading and preparation steps (executed sequentially before implementation)
- `implementation_approach`: Implementation steps with dependency management (array of step objects)
- `target_files`: Specific files/functions/lines to modify (format: `file:function:lines` for existing, `file` for new)
**Implementation Approach Execution Modes**:
The `implementation_approach` supports **two execution modes** based on the presence of the `command` field:
1. **Default Mode (Agent Execution)** - `command` field **omitted**:
- Agent interprets `modification_points` and `logic_flow` autonomously
- Direct agent execution with full context awareness
- No external tool overhead
- **Use for**: Standard implementation tasks where agent capability is sufficient
- **Required fields**: `step`, `title`, `description`, `modification_points`, `logic_flow`, `depends_on`, `output`
2. **CLI Mode (Command Execution)** - `command` field **included**:
- Specified command executes the step directly
- Leverages specialized CLI tools (codex/gemini/qwen) for complex reasoning
- **Use for**: Large-scale features, complex refactoring, or when user explicitly requests CLI tool usage
- **Required fields**: Same as default mode **PLUS** `command`
- **Command patterns**:
- `bash(codex -C [path] --full-auto exec '[prompt]' --skip-git-repo-check -s danger-full-access)`
- `bash(codex --full-auto exec '[task]' resume --last --skip-git-repo-check -s danger-full-access)` (multi-step)
- `bash(cd [path] && gemini -p '[prompt]' --approval-mode yolo)` (write mode)
**Mode Selection Strategy**:
- **Default to agent execution** for most tasks
- **Use CLI mode** when:
- User explicitly requests CLI tool (codex/gemini/qwen)
- Task requires multi-step autonomous reasoning beyond agent capability
- Complex refactoring needs specialized tool analysis
- Building on previous CLI execution context (use `resume --last`)
**Key Principle**: The `command` field is **optional**. Agent must decide based on task complexity and user preference.
**Pre-Analysis Step Selection Guide (举一反三 Principle)**:
The examples above demonstrate **patterns**, not fixed requirements. Agent MUST:
1. **Always Include** (Required):
- `load_context_package` - Essential for all tasks
- `load_role_analysis_artifacts` - Critical for accessing brainstorming insights
2. **Selectively Include Based on Task Type**:
- **Architecture tasks**: Project structure + Gemini architecture analysis
- **Refactoring tasks**: Gemini execution flow tracing + code quality analysis
- **Frontend tasks**: React/Vue component searches + UI pattern analysis
- **Backend tasks**: Database schema + API endpoint searches
- **Security tasks**: Vulnerability scans + security pattern analysis
- **Performance tasks**: Bottleneck identification + profiling data
3. **Tool Selection Strategy**:
- **Gemini CLI**: Deep analysis (architecture, execution flow, patterns)
- **Qwen CLI**: Fallback or code quality analysis
- **Bash/rg/find**: Quick pattern matching and file discovery
- **MCP tools**: Semantic search and external research
4. **Command Composition Patterns**:
- **Single command**: `bash([simple_search])`
- **Multiple commands**: `["bash([cmd1])", "bash([cmd2])"]`
- **CLI analysis**: `bash(cd [path] && gemini -p '[prompt]')`
- **MCP integration**: `mcp__[tool]__[function]([params])`
**Key Principle**: Examples show **structure patterns**, not specific implementations. Agent must create task-appropriate steps dynamically.
**Artifact Mapping**:
- Use `artifacts_inventory` from context package
- Highest priority: synthesis_specification
@@ -312,13 +533,13 @@ Use `analysis_results.complexity` or task count to determine structure:
- Flat structure: IMPL_PLAN.md + TODO_LIST.md + task JSONs
- No container tasks, all leaf tasks
**Medium Tasks** (6-10 tasks):
**Medium Tasks** (6-12 tasks):
- Two-level hierarchy: IMPL_PLAN.md + TODO_LIST.md + task JSONs
- Optional container tasks for grouping
**Complex Tasks** (>10 tasks):
- **Re-scope required**: Maximum 10 tasks hard limit
- If analysis_results contains >10 tasks, consolidate or request re-scoping
**Complex Tasks** (>12 tasks):
- **Re-scope required**: Maximum 12 tasks hard limit
- If analysis_results contains >12 tasks, consolidate or request re-scoping
## Quantification Requirements (MANDATORY)
@@ -375,7 +596,7 @@ Use `analysis_results.complexity` or task count to determine structure:
- **Follow 5-field schema**: All task JSONs must have id, title, status, meta, context, flow_control
- **Map artifacts**: Use artifacts_inventory to populate task.context.artifacts array
- **Add MCP integration**: Include MCP tool steps in flow_control.pre_analysis when capabilities available
- **Validate task count**: Maximum 10 tasks hard limit, request re-scope if exceeded
- **Validate task count**: Maximum 12 tasks hard limit, request re-scope if exceeded
- **Use session paths**: Construct all paths using provided session_id
- **Link documents properly**: Use correct linking format (📋 for JSON, ✅ for summaries)
- **Run validation checklist**: Verify all quantification requirements before finalizing task JSONs
@@ -384,6 +605,6 @@ Use `analysis_results.complexity` or task count to determine structure:
- Load files directly (use provided context package instead)
- Assume default locations (always use session_id in paths)
- Create circular dependencies in task.depends_on
- Exceed 10 tasks without re-scoping
- Exceed 12 tasks without re-scoping
- Skip artifact integration when artifacts_inventory is provided
- Ignore MCP capabilities when available

View File

@@ -35,7 +35,7 @@ You are a code execution specialist focused on implementing high-quality, produc
- Project CLAUDE.md standards
- **context-package.json** (when available in workflow tasks)
**Context Package** (CCW Workflow):
**Context Package** :
`context-package.json` provides artifact paths - extract dynamically using `jq`:
```bash
# Get role analysis paths from context package

View File

@@ -102,6 +102,8 @@ if (!memory.has("README.md")) Read(README.md)
Execute all 3 tracks in parallel for comprehensive coverage.
**Note**: Historical archive analysis (querying `.workflow/archives/manifest.json`) is optional and should be performed if the manifest exists. Inject findings into `conflict_detection.historical_conflicts[]`.
#### Track 1: Reference Documentation
Extract from Phase 0 loaded docs:

View File

@@ -217,11 +217,6 @@ You execute 6 distinct task types organized into 3 patterns. Each task includes
### Structure Optimization
**Layout Structure Benefits**:
- Eliminates redundancy between structure and styling
- Layout properties co-located with DOM elements
- Responsive overrides apply directly to affected elements
- Single source of truth for each element
**Component State Coverage**:
- Interactive components (button, input, dropdown) MUST define: default, hover, focus, active, disabled
@@ -784,12 +779,7 @@ You execute 6 distinct task types organized into 3 patterns. Each task includes
- usage_guide OPTIONAL for specialized components (can be simplified or omitted)
- extraction_metadata.code_snippets ONLY present in Code Import mode
**Structure Optimization Benefits**:
- Eliminates redundancy between dom_structure and css_layout_rules
- Layout properties are co-located with corresponding DOM elements
- Responsive overrides apply directly to the element they affect
- Single source of truth for each element's structure and layout
- Easier to maintain and understand hierarchy
### animation-tokens.json