mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-14 02:42:04 +08:00
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
@@ -324,14 +324,6 @@ Synthesis: .workflow/active/WFS-{topic}/.brainstorming/synthesis-specification.m
|
||||
- **Dynamic Role Count**: `--count N` parameter determines number of Phase 2 parallel tasks (default: 3, max: 9)
|
||||
- **Mixed Execution**: Sequential (Phase 1, 3) and Parallel (Phase 2) task execution
|
||||
|
||||
**Benefits**:
|
||||
- Real-time visibility into attached tasks during execution
|
||||
- Clean orchestrator-level summary after tasks complete
|
||||
- Clear mental model: SlashCommand/Task = attach tasks, not delegate work
|
||||
- Parallel execution support for concurrent role analysis
|
||||
- Dynamic attachment/collapse maintains clarity
|
||||
|
||||
**Note**: See individual Phase descriptions (Phase 1, 2, 3) for detailed TodoWrite Update examples with full JSON structures.
|
||||
|
||||
## Input Processing
|
||||
|
||||
|
||||
@@ -381,6 +381,64 @@ Updated {role2}/analysis.md with Clarifications section + enhanced content
|
||||
- Ambiguities resolved, placeholders removed
|
||||
- Consistent terminology
|
||||
|
||||
### Phase 6: Update Context Package
|
||||
|
||||
**Purpose**: Sync updated role analyses to context-package.json to avoid stale cache
|
||||
|
||||
**Operations**:
|
||||
```bash
|
||||
context_pkg_path = ".workflow/active/WFS-{session}/.process/context-package.json"
|
||||
|
||||
# 1. Read existing package
|
||||
context_pkg = Read(context_pkg_path)
|
||||
|
||||
# 2. Re-read brainstorm artifacts (now with synthesis enhancements)
|
||||
brainstorm_dir = ".workflow/active/WFS-{session}/.brainstorming"
|
||||
|
||||
# 2.1 Update guidance-specification if exists
|
||||
IF exists({brainstorm_dir}/guidance-specification.md):
|
||||
context_pkg.brainstorm_artifacts.guidance_specification.content = Read({brainstorm_dir}/guidance-specification.md)
|
||||
context_pkg.brainstorm_artifacts.guidance_specification.updated_at = NOW()
|
||||
|
||||
# 2.2 Update synthesis-specification if exists
|
||||
IF exists({brainstorm_dir}/synthesis-specification.md):
|
||||
IF context_pkg.brainstorm_artifacts.synthesis_output:
|
||||
context_pkg.brainstorm_artifacts.synthesis_output.content = Read({brainstorm_dir}/synthesis-specification.md)
|
||||
context_pkg.brainstorm_artifacts.synthesis_output.updated_at = NOW()
|
||||
|
||||
# 2.3 Re-read all role analysis files
|
||||
role_analysis_files = Glob({brainstorm_dir}/*/analysis*.md)
|
||||
context_pkg.brainstorm_artifacts.role_analyses = []
|
||||
|
||||
FOR file IN role_analysis_files:
|
||||
role_name = extract_role_from_path(file) # e.g., "ui-designer"
|
||||
relative_path = file.replace({brainstorm_dir}/, "")
|
||||
|
||||
context_pkg.brainstorm_artifacts.role_analyses.push({
|
||||
"role": role_name,
|
||||
"files": [{
|
||||
"path": relative_path,
|
||||
"type": "primary",
|
||||
"content": Read(file),
|
||||
"updated_at": NOW()
|
||||
}]
|
||||
})
|
||||
|
||||
# 3. Update metadata
|
||||
context_pkg.metadata.updated_at = NOW()
|
||||
context_pkg.metadata.synthesis_timestamp = NOW()
|
||||
|
||||
# 4. Write back
|
||||
Write(context_pkg_path, JSON.stringify(context_pkg, indent=2))
|
||||
|
||||
REPORT: "✅ Updated context-package.json with synthesis results"
|
||||
```
|
||||
|
||||
**TodoWrite Update**:
|
||||
```json
|
||||
{"content": "Update context package with synthesis results", "status": "completed", "activeForm": "Updating context package"}
|
||||
```
|
||||
|
||||
## Session Metadata
|
||||
|
||||
Update `workflow-session.json`:
|
||||
|
||||
@@ -15,13 +15,6 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
|
||||
|
||||
**Lazy Loading**: Task JSONs read **on-demand** during execution, not upfront. TODO_LIST.md + IMPL_PLAN.md provide metadata for planning.
|
||||
|
||||
| Metric | Before | After | Improvement |
|
||||
|--------|--------|-------|-------------|
|
||||
| **Initial Load** | All task JSONs (~2,300 lines) | TODO_LIST.md only (~650 lines) | **72% reduction** |
|
||||
| **Startup Time** | Seconds | Milliseconds | **~90% faster** |
|
||||
| **Memory** | All tasks | 1-2 tasks | **90% less** |
|
||||
| **Scalability** | 10-20 tasks | 100+ tasks | **5-10x** |
|
||||
|
||||
**Loading Strategy**:
|
||||
- **TODO_LIST.md**: Read in Phase 2 (task metadata, status, dependencies)
|
||||
- **IMPL_PLAN.md**: Read existence in Phase 2, parse execution strategy when needed
|
||||
@@ -31,6 +24,7 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
|
||||
**Complete entire workflow autonomously without user interruption, using TodoWrite for comprehensive progress tracking.**
|
||||
**Execute all discovered pending tasks until workflow completion or blocking dependency.**
|
||||
**Auto-complete session when all tasks finished: Call `/workflow:session:complete` upon workflow completion.**
|
||||
**ONE AGENT = ONE TASK JSON: Each agent instance executes exactly one task JSON file - never batch multiple tasks into single agent execution.**
|
||||
|
||||
## Core Responsibilities
|
||||
- **Session Discovery**: Identify and select active workflow sessions
|
||||
@@ -42,10 +36,6 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
|
||||
- **Session Auto-Complete**: Call `/workflow:session:complete` when all workflow tasks finished
|
||||
|
||||
## Execution Philosophy
|
||||
- **IMPL_PLAN-driven**: Follow execution strategy from IMPL_PLAN.md Section 4
|
||||
- **Discovery-first**: Auto-discover existing plans and tasks
|
||||
- **Status-aware**: Execute only ready tasks with resolved dependencies
|
||||
- **Context-rich**: Provide complete task JSON and accumulated context to agents
|
||||
- **Progress tracking**: Continuous TodoWrite updates throughout entire workflow execution
|
||||
- **Autonomous completion**: Execute all tasks without user interruption until workflow complete
|
||||
|
||||
@@ -54,13 +44,64 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
|
||||
### Phase 1: Discovery
|
||||
**Applies to**: Normal mode only (skipped in resume mode)
|
||||
|
||||
**Process**:
|
||||
1. **Check Active Sessions**: Find sessions in `.workflow/active/` directory
|
||||
2. **Select Session**: If multiple found, prompt user selection
|
||||
3. **Load Session Metadata**: Read `workflow-session.json` ONLY (minimal context)
|
||||
4. **DO NOT read task JSONs yet** - defer until execution phase
|
||||
**Purpose**: Find and select active workflow session with user confirmation when multiple sessions exist
|
||||
|
||||
**Resume Mode**: This phase is completely skipped when `--resume-session="session-id"` flag is provided.
|
||||
**Process**:
|
||||
|
||||
#### Step 1.1: Count Active Sessions
|
||||
```bash
|
||||
bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | wc -l)
|
||||
```
|
||||
|
||||
#### Step 1.2: Handle Session Selection
|
||||
|
||||
**Case A: No Sessions** (count = 0)
|
||||
```
|
||||
ERROR: No active workflow sessions found
|
||||
Run /workflow:plan "task description" to create a session
|
||||
```
|
||||
|
||||
**Case B: Single Session** (count = 1)
|
||||
```bash
|
||||
bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename)
|
||||
```
|
||||
Auto-select and continue to Phase 2.
|
||||
|
||||
**Case C: Multiple Sessions** (count > 1)
|
||||
|
||||
List sessions with metadata and prompt user selection:
|
||||
```bash
|
||||
bash(for dir in .workflow/active/WFS-*/; do
|
||||
session=$(basename "$dir")
|
||||
project=$(jq -r '.project // "Unknown"' "$dir/workflow-session.json" 2>/dev/null)
|
||||
total=$(grep -c "^- \[" "$dir/TODO_LIST.md" 2>/dev/null || echo "0")
|
||||
completed=$(grep -c "^- \[x\]" "$dir/TODO_LIST.md" 2>/dev/null || echo "0")
|
||||
[ "$total" -gt 0 ] && progress=$((completed * 100 / total)) || progress=0
|
||||
echo "${session} | ${project} | ${completed}/${total} tasks (${progress}%)"
|
||||
done)
|
||||
```
|
||||
|
||||
Use AskUserQuestion to present formatted options:
|
||||
```
|
||||
Multiple active workflow sessions detected. Please select one:
|
||||
|
||||
1. WFS-auth-system | Authentication System | 3/5 tasks (60%)
|
||||
2. WFS-payment-module | Payment Integration | 0/8 tasks (0%)
|
||||
|
||||
Enter number, full session ID, or partial match:
|
||||
```
|
||||
|
||||
Parse user input (supports: number "1", full ID "WFS-auth-system", or partial "auth"), validate selection, and continue to Phase 2.
|
||||
|
||||
#### Step 1.3: Load Session Metadata
|
||||
```bash
|
||||
bash(cat .workflow/active/${sessionId}/workflow-session.json)
|
||||
```
|
||||
|
||||
**Output**: Store session metadata in memory
|
||||
**DO NOT read task JSONs yet** - defer until execution phase (lazy loading)
|
||||
|
||||
**Resume Mode**: This entire phase is skipped when `--resume-session="session-id"` flag is provided.
|
||||
|
||||
### Phase 2: Planning Document Analysis
|
||||
**Applies to**: Normal mode only (skipped in resume mode)
|
||||
@@ -68,14 +109,14 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
|
||||
**Optimized to avoid reading all task JSONs upfront**
|
||||
|
||||
**Process**:
|
||||
1. **Read IMPL_PLAN.md**: Check existence, understand overall strategy
|
||||
1. **Check IMPL_PLAN.md**: Verify file exists and has valid structure (defer detailed parsing to Phase 4)
|
||||
2. **Read TODO_LIST.md**: Get current task statuses and execution progress
|
||||
3. **Extract Task Metadata**: Parse task IDs, titles, and dependency relationships from TODO_LIST.md
|
||||
4. **Build Execution Queue**: Determine ready tasks based on TODO_LIST.md status and dependencies
|
||||
|
||||
**Key Optimization**: Use IMPL_PLAN.md (existence check only) and TODO_LIST.md as primary sources instead of reading all task JSONs
|
||||
**Key Optimization**: Use IMPL_PLAN.md (existence check only) and TODO_LIST.md as primary sources instead of reading all task JSONs. Detailed IMPL_PLAN.md parsing happens in Phase 4A.
|
||||
|
||||
**Resume Mode**: This phase is skipped when `--resume-session` flag is provided (session already known).
|
||||
**Resume Mode**: When `--resume-session` flag is provided, **session discovery** (Phase 1) is skipped, but **task metadata loading** (TODO_LIST.md reading) still occurs in Phase 3 for TodoWrite generation.
|
||||
|
||||
### Phase 3: TodoWrite Generation
|
||||
**Applies to**: Both normal and resume modes (resume mode entry point)
|
||||
@@ -85,14 +126,11 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
|
||||
- Parse TODO_LIST.md to extract all tasks with current statuses
|
||||
- Identify first pending task with met dependencies
|
||||
- Generate comprehensive TodoWrite covering entire workflow
|
||||
2. **Mark Initial Status**: Set first ready task(s) as `in_progress` in TodoWrite
|
||||
- **Sequential execution**: Mark ONE task as `in_progress`
|
||||
- **Parallel batch**: Mark ALL tasks in current batch as `in_progress`
|
||||
3. **Prepare Session Context**: Inject workflow paths for agent use (using provided session-id)
|
||||
4. **Validate Prerequisites**: Ensure IMPL_PLAN.md and TODO_LIST.md exist and are valid
|
||||
2. **Prepare Session Context**: Inject workflow paths for agent use (using provided session-id)
|
||||
3. **Validate Prerequisites**: Ensure IMPL_PLAN.md and TODO_LIST.md exist and are valid
|
||||
|
||||
**Resume Mode Behavior**:
|
||||
- Load existing TODO_LIST.md directly from `.workflow/active//{session-id}/`
|
||||
- Load existing TODO_LIST.md directly from `.workflow/active/{session-id}/`
|
||||
- Extract current progress from TODO_LIST.md
|
||||
- Generate TodoWrite from TODO_LIST.md state
|
||||
- Proceed immediately to agent execution (Phase 4)
|
||||
@@ -132,14 +170,10 @@ while (TODO_LIST.md has pending tasks) {
|
||||
4. **Launch Agent**: Invoke specialized agent with complete context including flow control steps
|
||||
5. **Monitor Progress**: Track agent execution and handle errors without user interruption
|
||||
6. **Collect Results**: Gather implementation results and outputs
|
||||
7. **Update TODO_LIST.md**: Mark current task as completed in TODO_LIST.md
|
||||
8. **Continue Workflow**: Identify next pending task from TODO_LIST.md and repeat
|
||||
7. **Continue Workflow**: Identify next pending task from TODO_LIST.md and repeat
|
||||
|
||||
**Note**: TODO_LIST.md updates are handled by agents (e.g., code-developer.md), not by the orchestrator.
|
||||
|
||||
**Benefits**:
|
||||
- Reduces initial context loading by ~90%
|
||||
- Only reads task JSON when actually executing
|
||||
- Scales better for workflows with many tasks
|
||||
- Faster startup time for workflow execution
|
||||
|
||||
### Phase 5: Completion
|
||||
**Applies to**: Both normal and resume modes
|
||||
@@ -186,8 +220,9 @@ while (TODO_LIST.md has pending tasks) {
|
||||
|
||||
#### 2. Parallel Execution
|
||||
**When**: IMPL_PLAN specifies "Parallel" with clear parallelization opportunities
|
||||
**Pattern**: Execute independent task groups concurrently
|
||||
**Pattern**: Execute independent task groups concurrently by launching multiple agent instances
|
||||
**TodoWrite**: MULTIPLE tasks (in same batch) marked as `in_progress` simultaneously
|
||||
**Agent Instantiation**: Launch one agent instance per task (respects ONE AGENT = ONE TASK JSON rule)
|
||||
|
||||
#### 3. Phased Execution
|
||||
**When**: IMPL_PLAN specifies "Phased" with phase breakdown
|
||||
@@ -275,232 +310,47 @@ TodoWrite({
|
||||
});
|
||||
```
|
||||
|
||||
### TODO_LIST.md Update Timing
|
||||
**Single source of truth for task status** - enables lazy loading by providing task metadata without reading JSONs
|
||||
|
||||
- **Before Agent Launch**: Mark task as `in_progress`
|
||||
- **After Task Complete**: Mark as `completed`, advance to next
|
||||
- **On Error**: Keep as `in_progress`, add error note
|
||||
- **Workflow Complete**: Call `/workflow:session:complete`
|
||||
|
||||
## Agent Context Management
|
||||
|
||||
### Context Sources (Priority Order)
|
||||
1. **Complete Task JSON**: Full task definition including all fields and artifacts
|
||||
2. **Artifacts Context**: Brainstorming outputs and role analyses from task.context.artifacts
|
||||
3. **Flow Control Context**: Accumulated outputs from pre_analysis steps (including artifact loading)
|
||||
4. **Dependency Summaries**: Previous task completion summaries
|
||||
5. **Session Context**: Workflow paths and session metadata
|
||||
6. **Inherited Context**: Parent task context and shared variables
|
||||
|
||||
### Context Assembly Process
|
||||
```
|
||||
1. Load Task JSON → Base context (including artifacts array)
|
||||
2. Load Artifacts → Synthesis specifications and brainstorming outputs
|
||||
3. Execute Flow Control → Accumulated context (with artifact loading steps)
|
||||
4. Load Dependencies → Dependency context
|
||||
5. Prepare Session Paths → Session context
|
||||
6. Combine All → Complete agent context with artifact integration
|
||||
```
|
||||
|
||||
### Agent Context Package Structure
|
||||
```json
|
||||
{
|
||||
"task": { /* Complete task JSON with artifacts array */ },
|
||||
"artifacts": {
|
||||
"synthesis_specification": { "path": "{{from context-package.json → brainstorm_artifacts.synthesis_output.path}}", "priority": "highest" },
|
||||
"guidance_specification": { "path": "{{from context-package.json → brainstorm_artifacts.guidance_specification.path}}", "priority": "medium" },
|
||||
"role_analyses": [ /* From context-package.json → brainstorm_artifacts.role_analyses[] */ ],
|
||||
"conflict_resolution": { "path": "{{from context-package.json → brainstorm_artifacts.conflict_resolution.path}}", "conditional": true }
|
||||
},
|
||||
"flow_context": {
|
||||
"step_outputs": {
|
||||
"synthesis_specification": "...",
|
||||
"individual_artifacts": "...",
|
||||
"pattern_analysis": "...",
|
||||
"dependency_context": "..."
|
||||
}
|
||||
},
|
||||
"session": {
|
||||
"workflow_dir": ".workflow/active/WFS-session/",
|
||||
"context_package_path": ".workflow/active/WFS-session/.process/context-package.json",
|
||||
"todo_list_path": ".workflow/active/WFS-session/TODO_LIST.md",
|
||||
"summaries_dir": ".workflow/active/WFS-session/.summaries/",
|
||||
"task_json_path": ".workflow/active/WFS-session/.task/IMPL-1.1.json"
|
||||
},
|
||||
"dependencies": [ /* Task summaries from depends_on */ ],
|
||||
"inherited": { /* Parent task context */ }
|
||||
}
|
||||
```
|
||||
|
||||
### Context Validation Rules
|
||||
- **Task JSON Complete**: All 5 fields present and valid, including artifacts array in context
|
||||
- **Artifacts Available**: All artifacts loaded from context-package.json
|
||||
- **Flow Control Ready**: All pre_analysis steps completed including artifact loading steps
|
||||
- **Dependencies Loaded**: All depends_on summaries available
|
||||
- **Session Paths Valid**: All workflow paths exist and accessible (verified via context-package.json)
|
||||
- **Agent Assignment**: Valid agent type specified in meta.agent
|
||||
|
||||
## Agent Execution Pattern
|
||||
|
||||
### Flow Control Execution
|
||||
**[FLOW_CONTROL]** marker indicates task JSON contains `flow_control.pre_analysis` steps for context preparation.
|
||||
|
||||
**Orchestrator Responsibility**:
|
||||
- Pass complete task JSON to agent (including `flow_control` block)
|
||||
- Provide session paths for artifact access
|
||||
- Monitor agent completion
|
||||
|
||||
**Agent Responsibility**:
|
||||
- Parse `flow_control.pre_analysis` array from JSON
|
||||
- Execute steps sequentially with variable substitution
|
||||
- Accumulate context from artifacts and dependencies
|
||||
- Follow error handling per `step.on_error`
|
||||
- Complete implementation using accumulated context
|
||||
|
||||
**Orchestrator does NOT execute flow control steps - Agent interprets and executes them from JSON.**
|
||||
**Note**: Orchestrator does NOT execute flow control steps - Agent interprets and executes them autonomously.
|
||||
|
||||
### Agent Prompt Template
|
||||
**Dynamic Generation**: Before agent invocation, read task JSON and extract key requirements.
|
||||
|
||||
```bash
|
||||
Task(subagent_type="{meta.agent}",
|
||||
prompt="**EXECUTE TASK FROM JSON**
|
||||
prompt="Execute task: {task.title}
|
||||
|
||||
## Task JSON Location
|
||||
{session.task_json_path}
|
||||
{[FLOW_CONTROL]}
|
||||
|
||||
## Instructions
|
||||
1. **Load Complete Task JSON**: Read and validate all fields (id, title, status, meta, context, flow_control)
|
||||
2. **Execute Flow Control**: If `flow_control.pre_analysis` exists, execute steps sequentially:
|
||||
- Load artifacts (role analysis documents, role analyses) using commands in each step
|
||||
- Accumulate context from step outputs using variable substitution [variable_name]
|
||||
- Handle errors per step.on_error (skip_optional | fail | retry_once)
|
||||
3. **Implement Solution**: Follow `flow_control.implementation_approach` using accumulated context
|
||||
4. **Complete Task**:
|
||||
- Update task status: `jq '.status = \"completed\"' {session.task_json_path} > temp.json && mv temp.json {session.task_json_path}`
|
||||
- Update TODO_LIST.md: Mark task as [x] completed in {session.todo_list_path}
|
||||
- Generate summary: {session.summaries_dir}/{task.id}-summary.md
|
||||
- Check workflow completion and call `/workflow:session:complete` if all tasks done
|
||||
**Task Objectives** (from task JSON):
|
||||
{task.context.objective}
|
||||
|
||||
## Context Sources (All from JSON)
|
||||
- Requirements: `context.requirements`
|
||||
- Focus Paths: `context.focus_paths`
|
||||
- Acceptance: `context.acceptance`
|
||||
- Artifacts: `context.artifacts` (synthesis specs, brainstorming outputs)
|
||||
- Dependencies: `context.depends_on`
|
||||
- Target Files: `flow_control.target_files`
|
||||
**Expected Deliverables** (from task JSON):
|
||||
{task.context.deliverables}
|
||||
|
||||
## Session Paths
|
||||
**Quality Standards** (from task JSON):
|
||||
{task.context.acceptance_criteria}
|
||||
|
||||
**MANDATORY FIRST STEPS**:
|
||||
1. Read complete task JSON: {session.task_json_path}
|
||||
2. Load context package: {session.context_package_path}
|
||||
|
||||
Follow complete execution guidelines in @.claude/agents/{meta.agent}.md
|
||||
|
||||
**Session Paths**:
|
||||
- Workflow Dir: {session.workflow_dir}
|
||||
- TODO List: {session.todo_list_path}
|
||||
- Summaries: {session.summaries_dir}
|
||||
- Flow Context: {flow_context.step_outputs}
|
||||
- Summaries Dir: {session.summaries_dir}
|
||||
- Context Package: {session.context_package_path}
|
||||
|
||||
**Complete JSON structure is authoritative - load and follow it exactly.**"),
|
||||
description="Execute task: {task.id}")
|
||||
**Success Criteria**: Complete all objectives, meet all quality standards, deliver all outputs as specified above.",
|
||||
description="Executing: {task.title}")
|
||||
```
|
||||
|
||||
### Agent JSON Loading Specification
|
||||
**MANDATORY AGENT PROTOCOL**: All agents must follow this exact loading sequence:
|
||||
|
||||
1. **JSON Loading**: First action must be `cat {session.task_json_path}`
|
||||
2. **Field Validation**: Verify all 5 required fields exist: `id`, `title`, `status`, `meta`, `context`, `flow_control`
|
||||
3. **Structure Parsing**: Parse nested fields correctly:
|
||||
- `meta.type` and `meta.agent` (NOT flat `task_type`)
|
||||
- `context.requirements`, `context.focus_paths`, `context.acceptance`
|
||||
- `context.depends_on`, `context.inherited`
|
||||
- `flow_control.pre_analysis` array, `flow_control.target_files`
|
||||
4. **Flow Control Execution**: If `flow_control.pre_analysis` exists, execute steps sequentially
|
||||
5. **Status Management**: Update JSON status upon completion
|
||||
|
||||
**JSON Field Reference**:
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-1.2",
|
||||
"title": "Task title",
|
||||
"status": "pending|active|completed|blocked",
|
||||
"meta": {
|
||||
"type": "feature|bugfix|refactor|test-gen|test-fix|docs",
|
||||
"agent": "@code-developer|@test-fix-agent|@universal-executor"
|
||||
},
|
||||
"context": {
|
||||
"requirements": ["req1", "req2"],
|
||||
"focus_paths": ["src/path1", "src/path2"],
|
||||
"acceptance": ["criteria1", "criteria2"],
|
||||
"depends_on": ["IMPL-1.1"],
|
||||
"inherited": { "from": "parent", "context": ["info"] },
|
||||
"artifacts": [
|
||||
{
|
||||
"type": "synthesis_specification",
|
||||
"source": "context-package.json → brainstorm_artifacts.synthesis_output",
|
||||
"path": "{{loaded dynamically from context-package.json}}",
|
||||
"priority": "highest",
|
||||
"contains": "complete_integrated_specification"
|
||||
},
|
||||
{
|
||||
"type": "individual_role_analysis",
|
||||
"source": "context-package.json → brainstorm_artifacts.role_analyses[]",
|
||||
"path": "{{loaded dynamically from context-package.json}}",
|
||||
"note": "Supports analysis*.md pattern (analysis.md, analysis-01.md, analysis-api.md, etc.)",
|
||||
"priority": "low",
|
||||
"contains": "role_specific_analysis_fallback"
|
||||
}
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_synthesis_specification",
|
||||
"action": "Load synthesis specification from context-package.json",
|
||||
"commands": [
|
||||
"Read(.workflow/active/WFS-[session]/.process/context-package.json)",
|
||||
"Extract(brainstorm_artifacts.synthesis_output.path)",
|
||||
"Read(extracted path)"
|
||||
],
|
||||
"output_to": "synthesis_specification",
|
||||
"on_error": "skip_optional"
|
||||
},
|
||||
{
|
||||
"step": "step_name",
|
||||
"command": "bash_command",
|
||||
"output_to": "variable",
|
||||
"on_error": "skip_optional|fail|retry_once"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Implement task following role analyses",
|
||||
"description": "Implement '[title]' following role analyses. PRIORITY: Use role analysis documents as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
|
||||
"modification_points": [
|
||||
"Apply consolidated requirements from role analysis documents",
|
||||
"Follow technical guidelines from synthesis",
|
||||
"Consult artifacts for implementation details when needed",
|
||||
"Integrate with existing patterns"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Load role analyses",
|
||||
"Parse architecture and requirements",
|
||||
"Implement following specification",
|
||||
"Consult artifacts for technical details when needed",
|
||||
"Validate against acceptance criteria"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "implementation"
|
||||
}
|
||||
],
|
||||
"target_files": ["file:function:lines", "path/to/NewFile.ts"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Execution Flow
|
||||
1. **Load Task JSON**: Agent reads and validates complete JSON structure
|
||||
2. **Execute Flow Control**: Agent runs pre_analysis steps if present
|
||||
3. **Prepare Implementation**: Agent uses implementation_approach from JSON
|
||||
4. **Launch Implementation**: Agent follows focus_paths and target_files
|
||||
5. **Update Status**: Agent marks JSON status as completed
|
||||
6. **Generate Summary**: Agent creates completion summary
|
||||
|
||||
### Agent Assignment Rules
|
||||
```
|
||||
meta.agent specified → Use specified agent
|
||||
@@ -517,7 +367,7 @@ meta.agent missing → Infer from meta.type:
|
||||
.workflow/active/WFS-[topic-slug]/
|
||||
├── workflow-session.json # Session state and metadata
|
||||
├── IMPL_PLAN.md # Planning document and requirements
|
||||
├── TODO_LIST.md # Progress tracking (auto-updated)
|
||||
├── TODO_LIST.md # Progress tracking (updated by agents)
|
||||
├── .task/ # Task definitions (JSON only)
|
||||
│ ├── IMPL-1.json # Main task definitions
|
||||
│ └── IMPL-1.1.json # Subtask definitions
|
||||
@@ -552,28 +402,3 @@ meta.agent missing → Infer from meta.type:
|
||||
- **Dependency Validation**: Check all depends_on references exist
|
||||
- **Context Verification**: Ensure all required context is available
|
||||
|
||||
### Recovery Procedures
|
||||
|
||||
**Session Recovery**:
|
||||
```bash
|
||||
# Check session integrity
|
||||
find .workflow/active/ -name "WFS-*" -type d | while read session_dir; do
|
||||
session=$(basename "$session_dir")
|
||||
[ ! -f "$session_dir/workflow-session.json" ] && \
|
||||
echo '{"session_id":"'$session'","status":"active"}' > "$session_dir/workflow-session.json"
|
||||
done
|
||||
```
|
||||
|
||||
**Task Recovery**:
|
||||
```bash
|
||||
# Validate task JSON integrity
|
||||
for task_file in .workflow/active/$session/.task/*.json; do
|
||||
jq empty "$task_file" 2>/dev/null || echo "Corrupted: $task_file"
|
||||
done
|
||||
|
||||
# Fix missing dependencies
|
||||
missing_deps=$(jq -r '.context.depends_on[]?' .workflow/active/$session/.task/*.json | sort -u)
|
||||
for dep in $missing_deps; do
|
||||
[ ! -f ".workflow/active/$session/.task/$dep.json" ] && echo "Missing dependency: $dep"
|
||||
done
|
||||
```
|
||||
|
||||
@@ -10,12 +10,14 @@ examples:
|
||||
# Workflow Init Command (/workflow:init)
|
||||
|
||||
## Overview
|
||||
Initializes `.workflow/project.json` with comprehensive project understanding by leveraging **cli-explore-agent** for intelligent analysis.
|
||||
Initializes `.workflow/project.json` with comprehensive project understanding by leveraging **cli-explore-agent** for intelligent analysis and **memory discovery** for SKILL package indexing.
|
||||
|
||||
**Key Features**:
|
||||
- **Intelligent Project Analysis**: Uses cli-explore-agent's Deep Scan mode
|
||||
- **Technology Stack Detection**: Identifies languages, frameworks, build tools
|
||||
- **Architecture Overview**: Discovers patterns, layers, key components
|
||||
- **Memory Discovery**: Scans and indexes available SKILL packages
|
||||
- **Smart Recommendations**: Suggests memory commands based on project state
|
||||
- **One-time Initialization**: Skips if project.json exists (unless --regenerate)
|
||||
|
||||
## Usage
|
||||
@@ -246,13 +248,19 @@ Files: ${metrics.total_files}
|
||||
LOC: ${metrics.lines_of_code}
|
||||
Complexity: ${metrics.complexity}
|
||||
|
||||
## Next Steps
|
||||
1. Start a workflow: /workflow:plan "feature description"
|
||||
2. View project state: /workflow:status --project
|
||||
3. View details: cat .workflow/project.json
|
||||
### Memory Resources
|
||||
SKILL Packages: ${memory_resources.skills.length}
|
||||
Documentation: ${memory_resources.documentation.length} project(s)
|
||||
Module Docs: ${memory_resources.module_docs.length} file(s)
|
||||
Gaps: ${memory_resources.gaps.join(', ') || 'none'}
|
||||
|
||||
## Quick Start
|
||||
• /workflow:plan "feature description" - Start new workflow
|
||||
• /workflow:status --project - View project state
|
||||
|
||||
---
|
||||
Project state saved to: .workflow/project.json
|
||||
Memory index updated: ${memory_resources.last_scanned}
|
||||
```
|
||||
|
||||
## Extended project.json Schema
|
||||
@@ -321,14 +329,130 @@ Project state saved to: .workflow/project.json
|
||||
"last_updated": "2025-01-18T10:00:00Z"
|
||||
},
|
||||
|
||||
"memory_resources": {
|
||||
"skills": [
|
||||
{"name": "claude_dms3", "type": "project_docs", "path": ".claude/skills/claude_dms3"},
|
||||
{"name": "workflow-progress", "type": "workflow_progress", "path": ".claude/skills/workflow-progress"}
|
||||
],
|
||||
"documentation": [
|
||||
{
|
||||
"name": "claude_dms3",
|
||||
"path": ".workflow/docs/claude_dms3",
|
||||
"has_readme": true,
|
||||
"has_architecture": true
|
||||
}
|
||||
],
|
||||
"module_docs": [
|
||||
".claude/commands/workflow/CLAUDE.md",
|
||||
".claude/agents/CLAUDE.md"
|
||||
],
|
||||
"gaps": ["tech_stack"],
|
||||
"last_scanned": "2025-01-18T10:05:00Z"
|
||||
},
|
||||
|
||||
"_metadata": {
|
||||
"initialized_by": "cli-explore-agent",
|
||||
"analysis_timestamp": "2025-01-18T10:00:00Z",
|
||||
"analysis_mode": "deep-scan"
|
||||
"analysis_mode": "deep-scan",
|
||||
"memory_scan_timestamp": "2025-01-18T10:05:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 5: Discover Memory Resources
|
||||
|
||||
**Goal**: Scan and index available SKILL packages (memory command products) using agent delegation
|
||||
|
||||
**Invoke general-purpose agent** to discover and catalog all memory products:
|
||||
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="general-purpose",
|
||||
description="Discover memory resources",
|
||||
prompt=`
|
||||
Discover and index all memory command products: SKILL packages, documentation, and CLAUDE.md files.
|
||||
|
||||
## Discovery Scope
|
||||
1. **SKILL Packages** (.claude/skills/) - Generated by /memory:skill-memory, /memory:tech-research, etc.
|
||||
2. **Documentation** (.workflow/docs/) - Generated by /memory:docs
|
||||
3. **Module Docs** (**/CLAUDE.md) - Generated by /memory:update-full, /memory:update-related
|
||||
|
||||
## Discovery Tasks
|
||||
|
||||
### 1. Scan SKILL Packages
|
||||
- List all directories in .claude/skills/
|
||||
- For each: extract name, classify type, record path
|
||||
- Types: workflow-progress | codemap-* | style-* | tech_stacks | project_docs
|
||||
|
||||
### 2. Scan Documentation
|
||||
- List directories in .workflow/docs/
|
||||
- For each project: name, path, check README.md, ARCHITECTURE.md existence
|
||||
|
||||
### 3. Scan CLAUDE.md Files
|
||||
- Find all **/CLAUDE.md (exclude: node_modules, .git, dist, build)
|
||||
- Return path list only
|
||||
|
||||
### 4. Identify Gaps
|
||||
- No project SKILL? → "project_skill"
|
||||
- No documentation? → "documentation"
|
||||
- Missing tech stack SKILL? → "tech_stack"
|
||||
- No workflow-progress? → "workflow_history"
|
||||
- <10% modules have CLAUDE.md? → "module_docs_low_coverage"
|
||||
|
||||
### 5. Return JSON:
|
||||
{
|
||||
"skills": [
|
||||
{"name": "claude_dms3", "type": "project_docs", "path": ".claude/skills/claude_dms3"},
|
||||
{"name": "workflow-progress", "type": "workflow_progress", "path": ".claude/skills/workflow-progress"}
|
||||
],
|
||||
"documentation": [
|
||||
{
|
||||
"name": "my_project",
|
||||
"path": ".workflow/docs/my_project",
|
||||
"has_readme": true,
|
||||
"has_architecture": true
|
||||
}
|
||||
],
|
||||
"module_docs": [
|
||||
"src/core/CLAUDE.md",
|
||||
"lib/utils/CLAUDE.md"
|
||||
],
|
||||
"gaps": ["tech_stack", "module_docs_low_coverage"]
|
||||
}
|
||||
|
||||
## Context
|
||||
- Project tech stack: ${JSON.stringify(analysis.technology_stack)}
|
||||
- Check .workflow/.archives for session history
|
||||
- If directories missing, return empty state with recommendations
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
**Agent Output**: JSON structure with skills, documentation, module_docs, and gaps
|
||||
|
||||
**Update project.json**:
|
||||
```javascript
|
||||
const memoryDiscovery = JSON.parse(agentOutput);
|
||||
|
||||
projectMeta.memory_resources = {
|
||||
...memoryDiscovery,
|
||||
last_scanned: new Date().toISOString()
|
||||
};
|
||||
|
||||
Write('.workflow/project.json', JSON.stringify(projectMeta, null, 2));
|
||||
```
|
||||
|
||||
**Output Summary**:
|
||||
```
|
||||
Memory Resources Indexed:
|
||||
- SKILL Packages: ${skills.length}
|
||||
- Documentation: ${documentation.length} project(s)
|
||||
- Module Docs: ${module_docs.length} file(s)
|
||||
- Gaps: ${gaps.join(', ') || 'none'}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Regeneration Behavior
|
||||
|
||||
When using `--regenerate` flag:
|
||||
@@ -347,7 +471,9 @@ When using `--regenerate` flag:
|
||||
|
||||
3. **Re-run cli-explore-agent analysis**
|
||||
|
||||
4. **Merge preserved data with new analysis**:
|
||||
4. **Re-run memory discovery (Phase 5)**
|
||||
|
||||
5. **Merge preserved data with new analysis**:
|
||||
```javascript
|
||||
const newProjectMeta = {
|
||||
...analysisResults,
|
||||
@@ -356,7 +482,7 @@ When using `--regenerate` flag:
|
||||
};
|
||||
```
|
||||
|
||||
5. **Output**:
|
||||
6. **Output**:
|
||||
```
|
||||
✓ Project analysis regenerated
|
||||
Backup saved: .workflow/project.json.backup
|
||||
@@ -365,6 +491,7 @@ When using `--regenerate` flag:
|
||||
- Technology stack analysis
|
||||
- Architecture overview
|
||||
- Key components discovery
|
||||
- Memory resources index
|
||||
|
||||
Preserved:
|
||||
- ${preservedFeatures.length} existing features
|
||||
@@ -397,3 +524,41 @@ If not in git repo and empty directory:
|
||||
2. Create minimal project.json
|
||||
3. Suggest: "Add code files and run /workflow:init --regenerate"
|
||||
```
|
||||
|
||||
### Memory Discovery Failures
|
||||
|
||||
**Missing Directories**:
|
||||
```
|
||||
If .claude/skills, .workflow/docs, or CLAUDE.md files not found:
|
||||
1. Return empty state for that category
|
||||
2. Mark in gaps.missing array
|
||||
3. Continue initialization
|
||||
```
|
||||
|
||||
**Metadata Read Failures**:
|
||||
```
|
||||
If SKILL.md files are unreadable:
|
||||
1. Include SKILL with basic info: name (from directory), type (inferred), path
|
||||
2. Log warning: "SKILL package {name} has invalid metadata"
|
||||
3. Continue with other SKILLs
|
||||
```
|
||||
|
||||
**Coverage Check Failures**:
|
||||
```
|
||||
If unable to determine module doc coverage:
|
||||
1. Skip adding "module_docs_low_coverage" to gaps
|
||||
2. Continue with other gap checks
|
||||
```
|
||||
|
||||
**Default Empty State**:
|
||||
```json
|
||||
{
|
||||
"memory_resources": {
|
||||
"skills": [],
|
||||
"documentation": [],
|
||||
"module_docs": [],
|
||||
"gaps": ["project_skill", "documentation", "tech_stack", "workflow_history", "module_docs"],
|
||||
"last_scanned": "ISO_TIMESTAMP"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -185,86 +185,104 @@ Execution Complete
|
||||
previousExecutionResults = []
|
||||
```
|
||||
|
||||
### Step 2: Create TodoWrite Execution List
|
||||
### Step 2: Task Grouping & Batch Creation
|
||||
|
||||
**Operations**:
|
||||
- Create execution tracking from task list
|
||||
- Typically single execution call for all tasks
|
||||
- Split into multiple calls if task list very large (>10 tasks)
|
||||
|
||||
**Execution Call Creation**:
|
||||
**Dependency Analysis & Grouping Algorithm**:
|
||||
```javascript
|
||||
function createExecutionCalls(tasks) {
|
||||
const taskTitles = tasks.map(t => t.title || t)
|
||||
// Infer dependencies: same file → sequential, keywords (use/integrate) → sequential
|
||||
function inferDependencies(tasks) {
|
||||
return tasks.map((task, i) => {
|
||||
const deps = []
|
||||
const file = task.file || task.title.match(/in\s+([^\s:]+)/)?.[1]
|
||||
const keywords = (task.description || task.title).toLowerCase()
|
||||
|
||||
// Single call for ≤10 tasks (most common)
|
||||
if (tasks.length <= 10) {
|
||||
return [{
|
||||
method: executionMethod === "Codex" ? "Codex" : "Agent",
|
||||
taskSummary: taskTitles.length <= 3
|
||||
? taskTitles.join(', ')
|
||||
: `${taskTitles.slice(0, 2).join(', ')}, and ${taskTitles.length - 2} more`,
|
||||
tasks: tasks
|
||||
}]
|
||||
}
|
||||
|
||||
// Split into multiple calls for >10 tasks
|
||||
const callSize = 5
|
||||
const calls = []
|
||||
for (let i = 0; i < tasks.length; i += callSize) {
|
||||
const batchTasks = tasks.slice(i, i + callSize)
|
||||
const batchTitles = batchTasks.map(t => t.title || t)
|
||||
calls.push({
|
||||
method: executionMethod === "Codex" ? "Codex" : "Agent",
|
||||
taskSummary: `Tasks ${i + 1}-${Math.min(i + callSize, tasks.length)}: ${batchTitles[0]}...`,
|
||||
tasks: batchTasks
|
||||
})
|
||||
}
|
||||
return calls
|
||||
for (let j = 0; j < i; j++) {
|
||||
const prevFile = tasks[j].file || tasks[j].title.match(/in\s+([^\s:]+)/)?.[1]
|
||||
if (file && prevFile === file) deps.push(j) // Same file
|
||||
else if (/use|integrate|call|import/.test(keywords)) deps.push(j) // Keyword dependency
|
||||
}
|
||||
return { ...task, taskIndex: i, dependencies: deps }
|
||||
})
|
||||
}
|
||||
|
||||
// Create execution calls with IDs
|
||||
executionCalls = createExecutionCalls(planObject.tasks).map((call, index) => ({
|
||||
...call,
|
||||
id: `[${call.method}-${index+1}]`
|
||||
}))
|
||||
// Group into batches: independent → parallel [P1,P2...], dependent → sequential [S1,S2...]
|
||||
function createExecutionCalls(tasks, executionMethod) {
|
||||
const tasksWithDeps = inferDependencies(tasks)
|
||||
const maxBatch = executionMethod === "Codex" ? 4 : 7
|
||||
const calls = []
|
||||
const processed = new Set()
|
||||
|
||||
// Parallel: independent tasks, different files, max batch size
|
||||
const parallelGroups = []
|
||||
tasksWithDeps.forEach(t => {
|
||||
if (t.dependencies.length === 0 && !processed.has(t.taskIndex)) {
|
||||
const group = [t]
|
||||
processed.add(t.taskIndex)
|
||||
tasksWithDeps.forEach(o => {
|
||||
if (!o.dependencies.length && !processed.has(o.taskIndex) &&
|
||||
group.length < maxBatch && t.file !== o.file) {
|
||||
group.push(o)
|
||||
processed.add(o.taskIndex)
|
||||
}
|
||||
})
|
||||
parallelGroups.push(group)
|
||||
}
|
||||
})
|
||||
|
||||
// Sequential: dependent tasks, batch when deps satisfied
|
||||
const remaining = tasksWithDeps.filter(t => !processed.has(t.taskIndex))
|
||||
while (remaining.length > 0) {
|
||||
const batch = remaining.filter((t, i) =>
|
||||
i < maxBatch && t.dependencies.every(d => processed.has(d))
|
||||
)
|
||||
if (!batch.length) break
|
||||
batch.forEach(t => processed.add(t.taskIndex))
|
||||
calls.push({ executionType: "sequential", groupId: `S${calls.length + 1}`, tasks: batch })
|
||||
remaining.splice(0, remaining.length, ...remaining.filter(t => !processed.has(t.taskIndex)))
|
||||
}
|
||||
|
||||
// Combine results
|
||||
return [
|
||||
...parallelGroups.map((g, i) => ({
|
||||
method: executionMethod, executionType: "parallel", groupId: `P${i+1}`,
|
||||
taskSummary: g.map(t => t.title).join(' | '), tasks: g
|
||||
})),
|
||||
...calls.map(c => ({ ...c, method: executionMethod, taskSummary: c.tasks.map(t => t.title).join(' → ') }))
|
||||
]
|
||||
}
|
||||
|
||||
executionCalls = createExecutionCalls(planObject.tasks, executionMethod).map(c => ({ ...c, id: `[${c.groupId}]` }))
|
||||
|
||||
// Create TodoWrite list
|
||||
TodoWrite({
|
||||
todos: executionCalls.map(call => ({
|
||||
content: `${call.id} (${call.taskSummary})`,
|
||||
todos: executionCalls.map(c => ({
|
||||
content: `${c.executionType === "parallel" ? "⚡" : "→"} ${c.id} (${c.tasks.length} tasks)`,
|
||||
status: "pending",
|
||||
activeForm: `Executing ${call.id} (${call.taskSummary})`
|
||||
activeForm: `Executing ${c.id}`
|
||||
}))
|
||||
})
|
||||
```
|
||||
|
||||
**Example Execution Lists**:
|
||||
```
|
||||
Single call (typical):
|
||||
[ ] [Agent-1] (Create AuthService, Add JWT utilities, Implement middleware)
|
||||
|
||||
Few tasks:
|
||||
[ ] [Codex-1] (Create AuthService, Add JWT utilities, and 3 more)
|
||||
|
||||
Large task sets (>10):
|
||||
[ ] [Agent-1] (Tasks 1-5: Create AuthService, Add JWT utilities, ...)
|
||||
[ ] [Agent-2] (Tasks 6-10: Create tests, Update docs, ...)
|
||||
```
|
||||
|
||||
### Step 3: Launch Execution
|
||||
|
||||
**IMPORTANT**: CLI execution MUST run in foreground (no background execution)
|
||||
|
||||
**Execution Loop**:
|
||||
**Execution Flow**: Parallel batches concurrently → Sequential batches in order
|
||||
```javascript
|
||||
for (currentIndex = 0; currentIndex < executionCalls.length; currentIndex++) {
|
||||
const currentCall = executionCalls[currentIndex]
|
||||
const parallel = executionCalls.filter(c => c.executionType === "parallel")
|
||||
const sequential = executionCalls.filter(c => c.executionType === "sequential")
|
||||
|
||||
// Update TodoWrite: mark current call in_progress
|
||||
// Launch execution with previousExecutionResults context
|
||||
// After completion: collect result, add to previousExecutionResults
|
||||
// Update TodoWrite: mark current call completed
|
||||
// Phase 1: Launch all parallel batches (single message with multiple tool calls)
|
||||
if (parallel.length > 0) {
|
||||
TodoWrite({ todos: executionCalls.map(c => ({ status: c.executionType === "parallel" ? "in_progress" : "pending" })) })
|
||||
parallelResults = await Promise.all(parallel.map(c => executeBatch(c)))
|
||||
previousExecutionResults.push(...parallelResults)
|
||||
TodoWrite({ todos: executionCalls.map(c => ({ status: parallel.includes(c) ? "completed" : "pending" })) })
|
||||
}
|
||||
|
||||
// Phase 2: Execute sequential batches one by one
|
||||
for (const call of sequential) {
|
||||
TodoWrite({ todos: executionCalls.map(c => ({ status: c === call ? "in_progress" : "..." })) })
|
||||
result = await executeBatch(call)
|
||||
previousExecutionResults.push(result)
|
||||
TodoWrite({ todos: executionCalls.map(c => ({ status: "completed" or "pending" })) })
|
||||
}
|
||||
```
|
||||
|
||||
@@ -323,12 +341,17 @@ ${result.notes ? `Notes: ${result.notes}` : ''}
|
||||
|
||||
${clarificationContext ? `\n## Clarifications\n${JSON.stringify(clarificationContext, null, 2)}` : ''}
|
||||
|
||||
## Instructions
|
||||
- Reference original request to ensure alignment
|
||||
- Review previous results to understand completed work
|
||||
- Build on previous work, avoid duplication
|
||||
- Test functionality as you implement
|
||||
- Complete all assigned tasks
|
||||
${executionContext?.session?.artifacts ? `\n## Planning Artifacts
|
||||
Detailed planning context available in:
|
||||
${executionContext.session.artifacts.exploration ? `- Exploration: ${executionContext.session.artifacts.exploration}` : ''}
|
||||
- Plan: ${executionContext.session.artifacts.plan}
|
||||
- Task: ${executionContext.session.artifacts.task}
|
||||
|
||||
Read these files for detailed architecture, patterns, and constraints.` : ''}
|
||||
|
||||
## Requirements
|
||||
MUST complete ALL ${planObject.tasks.length} tasks listed above in this single execution.
|
||||
Return only after all tasks are fully implemented and tested.
|
||||
`
|
||||
)
|
||||
```
|
||||
@@ -341,6 +364,11 @@ When to use:
|
||||
- `executionMethod = "Codex"`
|
||||
- `executionMethod = "Auto" AND complexity = "Medium" or "High"`
|
||||
|
||||
**Artifact Path Delegation**:
|
||||
- Include artifact file paths in CLI prompt for enhanced context
|
||||
- Codex can read artifact files for detailed planning information
|
||||
- Example: Reference exploration.json for architecture patterns
|
||||
|
||||
Command format:
|
||||
```bash
|
||||
function formatTaskForCodex(task, index) {
|
||||
@@ -390,12 +418,18 @@ Constraints: ${explorationContext.constraints || 'None'}
|
||||
|
||||
${clarificationContext ? `\n### User Clarifications\n${Object.entries(clarificationContext).map(([q, a]) => `${q}: ${a}`).join('\n')}` : ''}
|
||||
|
||||
## Execution Instructions
|
||||
- Reference original request to ensure alignment
|
||||
- Review previous results for context continuity
|
||||
- Build on previous work, don't duplicate completed tasks
|
||||
- Complete all assigned tasks in single execution
|
||||
- Test functionality as you implement
|
||||
${executionContext?.session?.artifacts ? `\n### Planning Artifact Files
|
||||
Detailed planning context available in session folder:
|
||||
${executionContext.session.artifacts.exploration ? `- Exploration: ${executionContext.session.artifacts.exploration}` : ''}
|
||||
- Plan: ${executionContext.session.artifacts.plan}
|
||||
- Task: ${executionContext.session.artifacts.task}
|
||||
|
||||
Read these files for complete architecture details, code patterns, and integration constraints.
|
||||
` : ''}
|
||||
|
||||
## Requirements
|
||||
MUST complete ALL ${planObject.tasks.length} tasks listed above in this single execution.
|
||||
Return only after all tasks are fully implemented and tested.
|
||||
|
||||
Complexity: ${planObject.complexity}
|
||||
" --skip-git-repo-check -s danger-full-access
|
||||
@@ -414,105 +448,72 @@ bash_result = Bash(
|
||||
|
||||
**Result Collection**: After completion, analyze output and collect result following `executionResult` structure
|
||||
|
||||
### Step 4: Track Execution Progress
|
||||
### Step 4: Progress Tracking
|
||||
|
||||
**Real-time TodoWrite Updates** at execution call level:
|
||||
|
||||
```javascript
|
||||
// When call starts
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{ content: "[Agent-1] (Implement auth + Create JWT utils)", status: "in_progress", activeForm: "..." },
|
||||
{ content: "[Agent-2] (Add middleware + Update routes)", status: "pending", activeForm: "..." }
|
||||
]
|
||||
})
|
||||
|
||||
// When call completes
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{ content: "[Agent-1] (Implement auth + Create JWT utils)", status: "completed", activeForm: "..." },
|
||||
{ content: "[Agent-2] (Add middleware + Update routes)", status: "in_progress", activeForm: "..." }
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
**User Visibility**:
|
||||
- User sees execution call progress (not individual task progress)
|
||||
- Current execution highlighted as "in_progress"
|
||||
- Completed executions marked with checkmark
|
||||
- Each execution shows task summary for context
|
||||
Progress tracked at batch level (not individual task level). Icons: ⚡ (parallel, concurrent), → (sequential, one-by-one)
|
||||
|
||||
### Step 5: Code Review (Optional)
|
||||
|
||||
**Skip Condition**: Only run if `codeReviewTool ≠ "Skip"`
|
||||
|
||||
**Operations**:
|
||||
- Agent Review: Current agent performs direct review
|
||||
- Gemini Review: Execute gemini CLI with review prompt
|
||||
- Custom tool: Execute specified CLI tool (qwen, codex, etc.)
|
||||
**Review Focus**: Verify implementation against task.json acceptance criteria
|
||||
- Read task.json from session artifacts for acceptance criteria
|
||||
- Check each acceptance criterion is fulfilled
|
||||
- Validate code quality and identify issues
|
||||
- Ensure alignment with planned approach
|
||||
|
||||
**Command Formats**:
|
||||
**Operations**:
|
||||
- Agent Review: Current agent performs direct review (read task.json for acceptance criteria)
|
||||
- Gemini Review: Execute gemini CLI with review prompt (task.json in CONTEXT)
|
||||
- Custom tool: Execute specified CLI tool (qwen, codex, etc.) with task.json reference
|
||||
|
||||
**Unified Review Template** (All tools use same standard):
|
||||
|
||||
**Review Criteria**:
|
||||
- **Acceptance Criteria**: Verify each criterion from task.json `context.acceptance`
|
||||
- **Code Quality**: Analyze quality, identify issues, suggest improvements
|
||||
- **Plan Alignment**: Validate implementation matches planned approach
|
||||
|
||||
**Shared Prompt Template** (used by all CLI tools):
|
||||
```
|
||||
PURPOSE: Code review for implemented changes against task.json acceptance criteria
|
||||
TASK: • Verify task.json acceptance criteria fulfillment • Analyze code quality • Identify issues • Suggest improvements • Validate plan adherence
|
||||
MODE: analysis
|
||||
CONTEXT: @**/* @{task.json} @{plan.json} [@{exploration.json}] | Memory: Review lite-execute changes against task.json requirements
|
||||
EXPECTED: Quality assessment with acceptance criteria verification, issue identification, and recommendations. Explicitly check each acceptance criterion from task.json.
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-review-code-quality.txt) | Focus on task.json acceptance criteria and plan adherence | analysis=READ-ONLY
|
||||
```
|
||||
|
||||
**Tool-Specific Execution** (Apply shared prompt template above):
|
||||
|
||||
```bash
|
||||
# Agent Review: Direct agent review (no CLI)
|
||||
# Uses analysis prompt and TodoWrite tools directly
|
||||
# Method 1: Agent Review (current agent)
|
||||
# - Read task.json: ${executionContext.session.artifacts.task}
|
||||
# - Apply unified review criteria (see Shared Prompt Template)
|
||||
# - Report findings directly
|
||||
|
||||
# Gemini Review:
|
||||
gemini -p "
|
||||
PURPOSE: Code review for implemented changes
|
||||
TASK: • Analyze quality • Identify issues • Suggest improvements
|
||||
MODE: analysis
|
||||
CONTEXT: @**/* | Memory: Review lite-execute changes
|
||||
EXPECTED: Quality assessment with recommendations
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-review-code-quality.txt) | Focus on recent changes | analysis=READ-ONLY
|
||||
"
|
||||
# Method 2: Gemini Review (recommended)
|
||||
gemini -p "[Shared Prompt Template with artifacts]"
|
||||
# CONTEXT includes: @**/* @${task.json} @${plan.json} [@${exploration.json}]
|
||||
|
||||
# Qwen Review (custom tool via "Other"):
|
||||
qwen -p "
|
||||
PURPOSE: Code review for implemented changes
|
||||
TASK: • Analyze quality • Identify issues • Suggest improvements
|
||||
MODE: analysis
|
||||
CONTEXT: @**/* | Memory: Review lite-execute changes
|
||||
EXPECTED: Quality assessment with recommendations
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-review-code-quality.txt) | Focus on recent changes | analysis=READ-ONLY
|
||||
"
|
||||
# Method 3: Qwen Review (alternative)
|
||||
qwen -p "[Shared Prompt Template with artifacts]"
|
||||
# Same prompt as Gemini, different execution engine
|
||||
|
||||
# Codex Review (custom tool via "Other"):
|
||||
codex --full-auto exec "Review recent code changes for quality, potential issues, and improvements" --skip-git-repo-check -s danger-full-access
|
||||
# Method 4: Codex Review (autonomous)
|
||||
codex --full-auto exec "[Verify task.json acceptance criteria at ${task.json}]" --skip-git-repo-check -s danger-full-access
|
||||
```
|
||||
|
||||
**Implementation Note**: Replace `[Shared Prompt Template with artifacts]` placeholder with actual template content, substituting:
|
||||
- `@{task.json}` → `@${executionContext.session.artifacts.task}`
|
||||
- `@{plan.json}` → `@${executionContext.session.artifacts.plan}`
|
||||
- `[@{exploration.json}]` → `@${executionContext.session.artifacts.exploration}` (if exists)
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Execution Intelligence
|
||||
|
||||
1. **Context Continuity**: Each execution call receives previous results
|
||||
- Prevents duplication across multiple executions
|
||||
- Maintains coherent implementation flow
|
||||
- Builds on completed work
|
||||
|
||||
2. **Execution Call Tracking**: Progress at call level, not task level
|
||||
- Each call handles all or subset of tasks
|
||||
- Clear visibility of current execution
|
||||
- Simple progress updates
|
||||
|
||||
3. **Flexible Execution**: Multiple input modes supported
|
||||
- In-memory: Seamless lite-plan integration
|
||||
- Prompt: Quick standalone execution
|
||||
- File: Intelligent format detection
|
||||
- Enhanced Task JSON (lite-plan export): Full plan extraction
|
||||
- Plain text: Uses as prompt
|
||||
|
||||
### Task Management
|
||||
|
||||
1. **Live Progress Updates**: Real-time TodoWrite tracking
|
||||
- Execution calls created before execution starts
|
||||
- Updated as executions progress
|
||||
- Clear completion status
|
||||
|
||||
2. **Simple Execution**: Straightforward task handling
|
||||
- All tasks in single call (typical)
|
||||
- Split only for very large task sets (>10)
|
||||
- Agent/Codex determines optimal execution order
|
||||
**Input Modes**: In-memory (lite-plan), prompt (standalone), file (JSON/text)
|
||||
**Batch Limits**: Agent 7 tasks, CLI 4 tasks
|
||||
**Execution**: Parallel batches use single Claude message with multiple tool calls (no concurrency limit)
|
||||
|
||||
## Error Handling
|
||||
|
||||
@@ -546,10 +547,26 @@ Passed from lite-plan via global variable:
|
||||
clarificationContext: {...} | null,
|
||||
executionMethod: "Agent" | "Codex" | "Auto",
|
||||
codeReviewTool: "Skip" | "Gemini Review" | "Agent Review" | string,
|
||||
originalUserInput: string
|
||||
originalUserInput: string,
|
||||
|
||||
// Session artifacts location (saved by lite-plan)
|
||||
session: {
|
||||
id: string, // Session identifier: {taskSlug}-{shortTimestamp}
|
||||
folder: string, // Session folder path: .workflow/.lite-plan/{session-id}
|
||||
artifacts: {
|
||||
exploration: string | null, // exploration.json path (if exploration performed)
|
||||
plan: string, // plan.json path (always present)
|
||||
task: string // task.json path (always exported)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Artifact Usage**:
|
||||
- Artifact files contain detailed planning context
|
||||
- Pass artifact paths to CLI tools and agents for enhanced context
|
||||
- See execution options below for usage examples
|
||||
|
||||
### executionResult (Output)
|
||||
|
||||
Collected after each execution call completes:
|
||||
|
||||
@@ -0,0 +1,760 @@
|
||||
---
|
||||
name: lite-fix
|
||||
description: Lightweight bug diagnosis and fix workflow with intelligent severity assessment and optional hotfix mode for production incidents
|
||||
argument-hint: "[--hotfix] \"bug description or issue reference\""
|
||||
allowed-tools: TodoWrite(*), Task(*), SlashCommand(*), AskUserQuestion(*), Read(*), Bash(*)
|
||||
---
|
||||
|
||||
# Workflow Lite-Fix Command (/workflow:lite-fix)
|
||||
|
||||
## Overview
|
||||
|
||||
Fast-track bug fixing workflow optimized for quick diagnosis, targeted fixes, and streamlined verification. Automatically adjusts process complexity based on impact assessment.
|
||||
|
||||
**Core capabilities:**
|
||||
- Rapid root cause diagnosis with intelligent code search
|
||||
- Automatic severity assessment and adaptive workflow
|
||||
- Fix strategy selection (immediate patch vs comprehensive refactor)
|
||||
- Risk-aware verification (smoke tests to full suite)
|
||||
- Optional hotfix mode for production incidents with branch management
|
||||
- Automatic follow-up task generation for hotfixes
|
||||
|
||||
## Usage
|
||||
|
||||
### Command Syntax
|
||||
```bash
|
||||
/workflow:lite-fix [FLAGS] <BUG_DESCRIPTION>
|
||||
|
||||
# Flags
|
||||
--hotfix, -h Production hotfix mode (creates hotfix branch, auto follow-up)
|
||||
|
||||
# Arguments
|
||||
<bug-description> Bug description or issue reference (required)
|
||||
```
|
||||
|
||||
### Modes
|
||||
|
||||
| Mode | Time Budget | Use Case | Workflow Characteristics |
|
||||
|------|-------------|----------|--------------------------|
|
||||
| **Default** | Auto-adapt (15min-4h) | All standard bugs | Intelligent severity assessment + adaptive process |
|
||||
| **Hotfix** (`--hotfix`) | 15-30 min | Production outage | Minimal diagnosis + hotfix branch + auto follow-up |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Default mode: Automatically adjusts based on impact
|
||||
/workflow:lite-fix "User avatar upload fails with 413 error"
|
||||
/workflow:lite-fix "Shopping cart randomly loses items at checkout"
|
||||
|
||||
# Hotfix mode: Production incident
|
||||
/workflow:lite-fix --hotfix "Payment gateway 5xx errors"
|
||||
```
|
||||
|
||||
## Execution Process
|
||||
|
||||
### Workflow Overview
|
||||
|
||||
```
|
||||
Bug Input → Diagnosis (Phase 1) → Impact Assessment (Phase 2)
|
||||
↓
|
||||
Severity Auto-Detection → Fix Planning (Phase 3)
|
||||
↓
|
||||
Verification Strategy (Phase 4) → User Confirmation (Phase 5) → Execution (Phase 6)
|
||||
```
|
||||
|
||||
### Phase Summary
|
||||
|
||||
| Phase | Default Mode | Hotfix Mode |
|
||||
|-------|--------------|-------------|
|
||||
| 1. Diagnosis | Adaptive search depth | Minimal (known issue) |
|
||||
| 2. Impact Assessment | Full risk scoring | Critical path only |
|
||||
| 3. Fix Planning | Strategy options based on complexity | Single surgical fix |
|
||||
| 4. Verification | Test level matches risk score | Smoke tests only |
|
||||
| 5. User Confirmation | 3 dimensions | 2 dimensions |
|
||||
| 6. Execution | Via lite-execute | Via lite-execute + monitoring |
|
||||
|
||||
---
|
||||
|
||||
## Detailed Phase Execution
|
||||
|
||||
### Phase 1: Diagnosis & Root Cause Analysis
|
||||
|
||||
**Goal**: Identify root cause and affected code paths
|
||||
|
||||
**Session Folder Setup**:
|
||||
```javascript
|
||||
// Generate session identifiers for artifact storage
|
||||
const bugSlug = bug_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
|
||||
const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
|
||||
const shortTimestamp = timestamp.substring(0, 19).replace('T', '-') // YYYY-MM-DD-HH-mm-ss
|
||||
const sessionId = `${bugSlug}-${shortTimestamp}`
|
||||
const sessionFolder = `.workflow/.lite-fix/${sessionId}`
|
||||
```
|
||||
|
||||
**Execution Strategy**:
|
||||
|
||||
**Default Mode** - Adaptive search:
|
||||
- **High confidence keywords** (e.g., specific error messages): Direct grep search (5min)
|
||||
- **Medium confidence**: cli-explore-agent with focused search (10-15min)
|
||||
- **Low confidence** (vague symptoms): cli-explore-agent with broad search (20min)
|
||||
|
||||
```javascript
|
||||
// Confidence-based strategy selection
|
||||
if (has_specific_error_message || has_file_path_hint) {
|
||||
// Quick targeted search
|
||||
grep -r '${error_message}' src/ --include='*.ts' -n | head -10
|
||||
git log --oneline --since='1 week ago' -- '*affected*'
|
||||
} else {
|
||||
// Deep exploration
|
||||
Task(subagent_type="cli-explore-agent", prompt=`
|
||||
Bug: ${bug_description}
|
||||
Execute diagnostic search:
|
||||
1. Search error patterns and similar issues
|
||||
2. Trace execution path in affected modules
|
||||
3. Check recent changes
|
||||
Return: Root cause hypothesis, affected paths, reproduction steps
|
||||
`)
|
||||
}
|
||||
```
|
||||
|
||||
**Hotfix Mode** - Minimal search:
|
||||
```bash
|
||||
Read(suspected_file) # User typically knows the file
|
||||
git blame ${suspected_file}
|
||||
```
|
||||
|
||||
**Output Structure**:
|
||||
```javascript
|
||||
diagnosisContext = {
|
||||
symptom: string,
|
||||
error_message: string | null,
|
||||
keywords: string[],
|
||||
confidence_level: "high" | "medium" | "low",
|
||||
root_cause: {
|
||||
file: "src/auth/tokenValidator.ts",
|
||||
line_range: "45-52",
|
||||
issue: "Token expiration check uses wrong comparison",
|
||||
introduced_by: "commit abc123"
|
||||
},
|
||||
reproduction_steps: ["Login", "Wait 15min", "Access protected route"],
|
||||
affected_scope: {
|
||||
users: "All authenticated users",
|
||||
features: ["login", "API access"],
|
||||
data_risk: "none"
|
||||
}
|
||||
}
|
||||
|
||||
// Save diagnosis results for CLI/agent access in lite-execute
|
||||
const diagnosisFile = `${sessionFolder}/diagnosis.json`
|
||||
Write(diagnosisFile, JSON.stringify(diagnosisContext, null, 2))
|
||||
```
|
||||
|
||||
**Output**: `diagnosisContext` (in-memory)
|
||||
**Artifact**: Saved to `{sessionFolder}/diagnosis.json` for CLI/agent use
|
||||
|
||||
**TodoWrite**: Mark Phase 1 completed, Phase 2 in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Impact Assessment & Severity Auto-Detection
|
||||
|
||||
**Goal**: Quantify blast radius and auto-determine severity
|
||||
|
||||
**Risk Score Calculation**:
|
||||
```javascript
|
||||
risk_score = (user_impact × 0.4) + (system_risk × 0.3) + (business_impact × 0.3)
|
||||
|
||||
// Auto-severity mapping
|
||||
if (risk_score >= 8.0) severity = "critical"
|
||||
else if (risk_score >= 5.0) severity = "high"
|
||||
else if (risk_score >= 3.0) severity = "medium"
|
||||
else severity = "low"
|
||||
|
||||
// Workflow adaptation
|
||||
if (severity >= "high") {
|
||||
diagnosis_depth = "focused"
|
||||
test_strategy = "smoke_and_critical"
|
||||
review_optional = true
|
||||
} else {
|
||||
diagnosis_depth = "comprehensive"
|
||||
test_strategy = "full_suite"
|
||||
review_optional = false
|
||||
}
|
||||
```
|
||||
|
||||
**Assessment Output**:
|
||||
```javascript
|
||||
impactContext = {
|
||||
affected_users: {
|
||||
count: "5000 active users (100%)",
|
||||
severity: "high"
|
||||
},
|
||||
system_risk: {
|
||||
availability: "degraded_30%",
|
||||
cascading_failures: "possible_logout_storm"
|
||||
},
|
||||
business_impact: {
|
||||
revenue: "medium",
|
||||
reputation: "high",
|
||||
sla_breach: "yes"
|
||||
},
|
||||
risk_score: 7.1,
|
||||
severity: "high",
|
||||
workflow_adaptation: {
|
||||
test_strategy: "focused_integration",
|
||||
review_required: false,
|
||||
time_budget: "1_hour"
|
||||
}
|
||||
}
|
||||
|
||||
// Save impact assessment for CLI/agent access
|
||||
const impactFile = `${sessionFolder}/impact.json`
|
||||
Write(impactFile, JSON.stringify(impactContext, null, 2))
|
||||
```
|
||||
|
||||
**Output**: `impactContext` (in-memory)
|
||||
**Artifact**: Saved to `{sessionFolder}/impact.json` for CLI/agent use
|
||||
|
||||
**Hotfix Mode**: Skip detailed assessment, assume critical
|
||||
|
||||
**TodoWrite**: Mark Phase 2 completed, Phase 3 in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Fix Planning & Strategy Selection
|
||||
|
||||
**Goal**: Generate fix options with trade-off analysis
|
||||
|
||||
**Strategy Generation**:
|
||||
|
||||
**Default Mode** - Complexity-adaptive:
|
||||
- **Low risk score (<5.0)**: Generate 2-3 strategy options for user selection
|
||||
- **High risk score (≥5.0)**: Generate single best strategy for speed
|
||||
|
||||
```javascript
|
||||
strategies = generateFixStrategies(root_cause, risk_score)
|
||||
|
||||
if (risk_score >= 5.0 || mode === "hotfix") {
|
||||
// Single best strategy
|
||||
return strategies[0] // Fastest viable fix
|
||||
} else {
|
||||
// Multiple options with trade-offs
|
||||
return strategies // Let user choose
|
||||
}
|
||||
```
|
||||
|
||||
**Example Strategies**:
|
||||
```javascript
|
||||
// Low risk: Multiple options
|
||||
[
|
||||
{
|
||||
strategy: "immediate_patch",
|
||||
description: "Fix comparison operator",
|
||||
estimated_time: "15 minutes",
|
||||
risk: "low",
|
||||
pros: ["Quick fix"],
|
||||
cons: ["Doesn't address underlying issue"]
|
||||
},
|
||||
{
|
||||
strategy: "comprehensive_fix",
|
||||
description: "Refactor token validation logic",
|
||||
estimated_time: "2 hours",
|
||||
risk: "medium",
|
||||
pros: ["Addresses root cause"],
|
||||
cons: ["Longer implementation"]
|
||||
}
|
||||
]
|
||||
|
||||
// High risk or hotfix: Single option
|
||||
{
|
||||
strategy: "surgical_fix",
|
||||
description: "Minimal change to fix comparison",
|
||||
files: ["src/auth/tokenValidator.ts:47"],
|
||||
estimated_time: "5 minutes",
|
||||
risk: "minimal"
|
||||
}
|
||||
```
|
||||
|
||||
**Complexity Assessment**:
|
||||
```javascript
|
||||
if (complexity === "high" && risk_score < 5.0) {
|
||||
suggestCommand("/workflow:plan --mode bugfix")
|
||||
return // Escalate to full planning
|
||||
}
|
||||
|
||||
// Save fix plan for CLI/agent access
|
||||
const planFile = `${sessionFolder}/fix-plan.json`
|
||||
Write(planFile, JSON.stringify(fixPlan, null, 2))
|
||||
```
|
||||
|
||||
**Output**: `fixPlan` (in-memory)
|
||||
**Artifact**: Saved to `{sessionFolder}/fix-plan.json` for CLI/agent use
|
||||
|
||||
**TodoWrite**: Mark Phase 3 completed, Phase 4 in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Verification Strategy
|
||||
|
||||
**Goal**: Define testing approach based on severity
|
||||
|
||||
**Adaptive Test Strategy**:
|
||||
|
||||
| Risk Score | Test Scope | Duration | Automation |
|
||||
|------------|------------|----------|------------|
|
||||
| **< 3.0** (Low) | Full test suite | 15-20 min | `npm test` |
|
||||
| **3.0-5.0** (Medium) | Focused integration | 8-12 min | `npm test -- affected-module.test.ts` |
|
||||
| **5.0-8.0** (High) | Smoke + critical | 5-8 min | `npm test -- critical.smoke.test.ts` |
|
||||
| **≥ 8.0** (Critical) | Smoke only | 2-5 min | `npm test -- smoke.test.ts` |
|
||||
| **Hotfix** | Production smoke | 2-3 min | `npm test -- production.smoke.test.ts` |
|
||||
|
||||
**Branch Strategy**:
|
||||
|
||||
**Default Mode**:
|
||||
```javascript
|
||||
{
|
||||
type: "feature_branch",
|
||||
base: "main",
|
||||
name: "fix/token-expiration-edge-case",
|
||||
merge_target: "main"
|
||||
}
|
||||
```
|
||||
|
||||
**Hotfix Mode**:
|
||||
```javascript
|
||||
{
|
||||
type: "hotfix_branch",
|
||||
base: "production_tag_v2.3.1", // ⚠️ From production tag
|
||||
name: "hotfix/token-validation-fix",
|
||||
merge_target: ["main", "production"] // Dual merge
|
||||
}
|
||||
```
|
||||
|
||||
**TodoWrite**: Mark Phase 4 completed, Phase 5 in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: User Confirmation & Execution Selection
|
||||
|
||||
**Adaptive Confirmation Dimensions**:
|
||||
|
||||
**Default Mode** - 3 dimensions (adapted by risk score):
|
||||
|
||||
```javascript
|
||||
dimensions = [
|
||||
{
|
||||
question: "Confirm fix approach?",
|
||||
options: ["Proceed", "Modify", "Escalate to /workflow:plan"]
|
||||
},
|
||||
{
|
||||
question: "Execution method:",
|
||||
options: ["Agent", "CLI Tool (Codex/Gemini)", "Manual (plan only)"]
|
||||
},
|
||||
{
|
||||
question: "Verification level:",
|
||||
options: adaptedByRiskScore() // Auto-suggest based on Phase 2
|
||||
}
|
||||
]
|
||||
|
||||
// If risk_score >= 5.0, auto-skip code review dimension
|
||||
// If risk_score < 5.0, add optional code review dimension
|
||||
if (risk_score < 5.0) {
|
||||
dimensions.push({
|
||||
question: "Post-fix review:",
|
||||
options: ["Gemini", "Skip"]
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
**Hotfix Mode** - 2 dimensions (minimal):
|
||||
```javascript
|
||||
[
|
||||
{
|
||||
question: "Confirm hotfix deployment:",
|
||||
options: ["Deploy", "Stage First", "Abort"]
|
||||
},
|
||||
{
|
||||
question: "Post-deployment monitoring:",
|
||||
options: ["Real-time (15 min)", "Passive (alerts only)"]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**TodoWrite**: Mark Phase 5 completed, Phase 6 in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 6: Execution Dispatch & Follow-up
|
||||
|
||||
**Export Enhanced Task JSON**:
|
||||
|
||||
```javascript
|
||||
const taskId = `BUGFIX-${shortTimestamp}`
|
||||
const taskFile = `${sessionFolder}/task.json`
|
||||
|
||||
const enhancedTaskJson = {
|
||||
id: taskId,
|
||||
title: bug_description,
|
||||
status: "pending",
|
||||
|
||||
meta: {
|
||||
type: "bugfix",
|
||||
created_at: new Date().toISOString(),
|
||||
severity: impactContext.severity,
|
||||
risk_score: impactContext.risk_score,
|
||||
estimated_time: fixPlan.estimated_time,
|
||||
workflow: mode === "hotfix" ? "lite-fix-hotfix" : "lite-fix",
|
||||
session_id: sessionId,
|
||||
session_folder: sessionFolder
|
||||
},
|
||||
|
||||
context: {
|
||||
requirements: [bug_description],
|
||||
diagnosis: diagnosisContext,
|
||||
impact: impactContext,
|
||||
plan: fixPlan,
|
||||
verification_strategy: verificationStrategy,
|
||||
branch_strategy: branchStrategy
|
||||
}
|
||||
}
|
||||
|
||||
Write(taskFile, JSON.stringify(enhancedTaskJson, null, 2))
|
||||
```
|
||||
|
||||
**Dispatch to lite-execute**:
|
||||
|
||||
```javascript
|
||||
executionContext = {
|
||||
mode: "bugfix",
|
||||
severity: impactContext.severity,
|
||||
planObject: fixPlan,
|
||||
diagnosisContext: diagnosisContext,
|
||||
impactContext: impactContext,
|
||||
verificationStrategy: verificationStrategy,
|
||||
branchStrategy: branchStrategy,
|
||||
executionMethod: user_selection.execution_method,
|
||||
|
||||
// Session artifacts location
|
||||
session: {
|
||||
id: sessionId,
|
||||
folder: sessionFolder,
|
||||
artifacts: {
|
||||
diagnosis: `${sessionFolder}/diagnosis.json`,
|
||||
impact: `${sessionFolder}/impact.json`,
|
||||
plan: `${sessionFolder}/fix-plan.json`,
|
||||
task: `${sessionFolder}/task.json`
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
SlashCommand("/workflow:lite-execute --in-memory --mode bugfix")
|
||||
```
|
||||
|
||||
**Hotfix Auto Follow-up**:
|
||||
|
||||
```javascript
|
||||
if (mode === "hotfix") {
|
||||
follow_up_tasks = [
|
||||
{
|
||||
id: `FOLLOWUP-${taskId}-comprehensive`,
|
||||
title: "Replace hotfix with comprehensive fix",
|
||||
priority: "high",
|
||||
due_date: "within_3_days",
|
||||
description: "Refactor quick hotfix into proper solution with full test coverage"
|
||||
},
|
||||
{
|
||||
id: `FOLLOWUP-${taskId}-postmortem`,
|
||||
title: "Incident postmortem",
|
||||
priority: "medium",
|
||||
due_date: "within_1_week",
|
||||
sections: ["Timeline", "Root cause", "Prevention measures"]
|
||||
}
|
||||
]
|
||||
|
||||
Write(`${sessionFolder}/followup.json`, follow_up_tasks)
|
||||
|
||||
console.log(`
|
||||
⚠️ Hotfix follow-up tasks generated:
|
||||
- Comprehensive fix: ${follow_up_tasks[0].id} (due in 3 days)
|
||||
- Postmortem: ${follow_up_tasks[1].id} (due in 1 week)
|
||||
- Location: ${sessionFolder}/followup.json
|
||||
`)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**TodoWrite**: Mark Phase 6 completed
|
||||
|
||||
---
|
||||
|
||||
## Data Structures
|
||||
|
||||
### diagnosisContext
|
||||
```javascript
|
||||
{
|
||||
symptom: string,
|
||||
error_message: string | null,
|
||||
keywords: string[],
|
||||
confidence_level: "high" | "medium" | "low", // Search confidence
|
||||
root_cause: {
|
||||
file: string,
|
||||
line_range: string,
|
||||
issue: string,
|
||||
introduced_by: string
|
||||
},
|
||||
reproduction_steps: string[],
|
||||
affected_scope: {...}
|
||||
}
|
||||
```
|
||||
|
||||
### impactContext
|
||||
```javascript
|
||||
{
|
||||
affected_users: { count: string, severity: string },
|
||||
system_risk: { availability: string, cascading_failures: string },
|
||||
business_impact: { revenue: string, reputation: string, sla_breach: string },
|
||||
risk_score: number, // 0-10
|
||||
severity: "low" | "medium" | "high" | "critical",
|
||||
workflow_adaptation: {
|
||||
diagnosis_depth: string,
|
||||
test_strategy: string,
|
||||
review_optional: boolean,
|
||||
time_budget: string
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### fixPlan
|
||||
```javascript
|
||||
{
|
||||
strategy: string,
|
||||
summary: string,
|
||||
tasks: [{
|
||||
title: string,
|
||||
file: string,
|
||||
action: "Update" | "Create" | "Delete",
|
||||
implementation: string[],
|
||||
verification: string[]
|
||||
}],
|
||||
estimated_time: string,
|
||||
recommended_execution: "Agent" | "CLI" | "Manual"
|
||||
}
|
||||
```
|
||||
|
||||
### executionContext
|
||||
|
||||
Context passed to lite-execute via --in-memory (Phase 6):
|
||||
|
||||
```javascript
|
||||
{
|
||||
mode: "bugfix",
|
||||
severity: "high" | "medium" | "low" | "critical",
|
||||
|
||||
// Core data objects
|
||||
planObject: {...}, // Complete fixPlan (see above)
|
||||
diagnosisContext: {...}, // Complete diagnosisContext (see above)
|
||||
impactContext: {...}, // Complete impactContext (see above)
|
||||
|
||||
// Verification and branch strategies
|
||||
verificationStrategy: {...},
|
||||
branchStrategy: {...},
|
||||
executionMethod: "Agent" | "CLI" | "Manual",
|
||||
|
||||
// Session artifacts location (for lite-execute to access saved files)
|
||||
session: {
|
||||
id: string, // Session identifier: {bugSlug}-{shortTimestamp}
|
||||
folder: string, // Session folder path: .workflow/.lite-fix/{session-id}
|
||||
artifacts: {
|
||||
diagnosis: string, // diagnosis.json path
|
||||
impact: string, // impact.json path
|
||||
plan: string, // fix-plan.json path
|
||||
task: string // task.json path
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Enhanced Task JSON Export
|
||||
|
||||
Task JSON structure exported in Phase 6:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "BUGFIX-{timestamp}",
|
||||
"title": "Original bug description",
|
||||
"status": "pending",
|
||||
|
||||
"meta": {
|
||||
"type": "bugfix",
|
||||
"created_at": "ISO timestamp",
|
||||
"severity": "low|medium|high|critical",
|
||||
"risk_score": 7.1,
|
||||
"estimated_time": "X minutes",
|
||||
"workflow": "lite-fix|lite-fix-hotfix",
|
||||
"session_id": "{bugSlug}-{shortTimestamp}",
|
||||
"session_folder": ".workflow/.lite-fix/{session-id}"
|
||||
},
|
||||
|
||||
"context": {
|
||||
"requirements": ["Original bug description"],
|
||||
"diagnosis": {/* diagnosisContext */},
|
||||
"impact": {/* impactContext */},
|
||||
"plan": {/* fixPlan */},
|
||||
"verification_strategy": {/* test strategy */},
|
||||
"branch_strategy": {/* branch strategy */}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Schema Notes**:
|
||||
- Aligns with Enhanced Task JSON Schema (6-field structure)
|
||||
- `context_package_path` omitted (not used by lite-fix)
|
||||
- `flow_control` omitted (handled by lite-execute)
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### When to Use Default Mode
|
||||
|
||||
**Use for all standard bugs:**
|
||||
- Automatically adapts to severity (no manual mode selection needed)
|
||||
- Risk score determines workflow complexity
|
||||
- Handles 90% of bug fixing scenarios
|
||||
|
||||
**Typical scenarios:**
|
||||
- UI bugs, logic errors, edge cases
|
||||
- Performance issues (non-critical)
|
||||
- Integration failures
|
||||
- Data validation bugs
|
||||
|
||||
### When to Use Hotfix Mode
|
||||
|
||||
**Only use for production incidents:**
|
||||
- Production is down or critically degraded
|
||||
- Revenue/reputation at immediate risk
|
||||
- SLA breach occurring
|
||||
- Issue is well-understood (minimal diagnosis needed)
|
||||
|
||||
**Hotfix characteristics:**
|
||||
- Creates hotfix branch from production tag
|
||||
- Minimal diagnosis (assumes known issue)
|
||||
- Smoke tests only
|
||||
- Auto-generates follow-up tasks
|
||||
- Requires incident tracking
|
||||
|
||||
### Branching Strategy
|
||||
|
||||
**Default Mode (feature branch)**:
|
||||
```bash
|
||||
# Standard feature branch workflow
|
||||
git checkout -b fix/issue-description main
|
||||
# ... implement fix
|
||||
git checkout main && git merge fix/issue-description
|
||||
```
|
||||
|
||||
**Hotfix Mode (dual merge)**:
|
||||
```bash
|
||||
# ✅ Correct: Branch from production tag
|
||||
git checkout -b hotfix/fix-name v2.3.1
|
||||
|
||||
# Merge to both targets
|
||||
git checkout main && git merge hotfix/fix-name
|
||||
git checkout production && git merge hotfix/fix-name
|
||||
git tag v2.3.2
|
||||
|
||||
# ❌ Wrong: Branch from main
|
||||
git checkout -b hotfix/fix-name main # Contains unreleased code!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Root cause unclear | Vague symptoms | Extend diagnosis time or use /cli:mode:bug-diagnosis |
|
||||
| Multiple potential causes | Complex interaction | Use /cli:discuss-plan for analysis |
|
||||
| Fix too complex | High-risk refactor | Escalate to /workflow:plan --mode bugfix |
|
||||
| High risk score but unsure | Uncertain severity | Default mode will adapt, proceed normally |
|
||||
|
||||
---
|
||||
|
||||
## Session Folder Structure
|
||||
|
||||
Each lite-fix execution creates a dedicated session folder to organize all artifacts:
|
||||
|
||||
```
|
||||
.workflow/.lite-fix/{bug-slug}-{short-timestamp}/
|
||||
├── diagnosis.json # Phase 1: Root cause analysis
|
||||
├── impact.json # Phase 2: Impact assessment
|
||||
├── fix-plan.json # Phase 3: Fix strategy
|
||||
├── task.json # Phase 6: Enhanced Task JSON
|
||||
└── followup.json # Hotfix mode only: Follow-up tasks
|
||||
```
|
||||
|
||||
**Folder Naming Convention**:
|
||||
- `{bug-slug}`: First 40 characters of bug description, lowercased, non-alphanumeric replaced with `-`
|
||||
- `{short-timestamp}`: YYYY-MM-DD-HH-mm-ss format
|
||||
- Example: `.workflow/.lite-fix/user-avatar-upload-fails-413-2025-01-15-14-30-45/`
|
||||
|
||||
**File Contents**:
|
||||
- `diagnosis.json`: Complete diagnosisContext object (Phase 1)
|
||||
- `impact.json`: Complete impactContext object (Phase 2)
|
||||
- `fix-plan.json`: Complete fixPlan object (Phase 3)
|
||||
- `task.json`: Enhanced Task JSON with all context (Phase 6)
|
||||
- `followup.json`: Follow-up tasks (hotfix mode only)
|
||||
|
||||
**Access Patterns**:
|
||||
- **lite-fix**: Creates folder and writes all artifacts during execution, passes paths via `executionContext.session.artifacts`
|
||||
- **lite-execute**: Reads artifact paths from `executionContext.session.artifacts`
|
||||
- **User**: Can inspect artifacts for debugging or reference
|
||||
- **Reuse**: Pass `task.json` path to `/workflow:lite-execute {path}` for re-execution
|
||||
|
||||
|
||||
|
||||
**Legacy Cache** (deprecated, use session folder instead):
|
||||
```
|
||||
.workflow/.lite-fix-cache/
|
||||
└── diagnosis-cache/
|
||||
└── ${bug_hash}.json
|
||||
```
|
||||
|
||||
|
||||
## Quality Gates
|
||||
|
||||
**Before execution** (auto-checked):
|
||||
- [ ] Root cause identified (>70% confidence for default, >90% for hotfix)
|
||||
- [ ] Impact scope defined
|
||||
- [ ] Fix strategy reviewed
|
||||
- [ ] Verification plan matches risk level
|
||||
|
||||
**Hotfix-specific**:
|
||||
- [ ] Production tag identified
|
||||
- [ ] Rollback plan documented
|
||||
- [ ] Follow-up tasks generated
|
||||
- [ ] Monitoring configured
|
||||
|
||||
---
|
||||
|
||||
## When to Use lite-fix
|
||||
|
||||
✅ **Perfect for:**
|
||||
- Any bug with clear symptoms
|
||||
- Localized fixes (1-5 files)
|
||||
- Known technology stack
|
||||
- Time-sensitive but not catastrophic (default mode adapts)
|
||||
- Production incidents (use --hotfix)
|
||||
|
||||
❌ **Not suitable for:**
|
||||
- Root cause completely unclear → use `/cli:mode:bug-diagnosis` first
|
||||
- Requires architectural changes → use `/workflow:plan`
|
||||
- Complex legacy code without tests → use `/workflow:plan --legacy-refactor`
|
||||
- Performance deep-dive → use `/workflow:plan --performance-optimization`
|
||||
- Data migration → use `/workflow:plan --data-migration`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-11-20
|
||||
**Version**: 2.0.0
|
||||
**Status**: Design Document (Simplified)
|
||||
@@ -130,6 +130,13 @@ needsExploration = (
|
||||
|
||||
**Exploration Execution** (if needed):
|
||||
```javascript
|
||||
// Generate session identifiers for artifact storage
|
||||
const taskSlug = task_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
|
||||
const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
|
||||
const shortTimestamp = timestamp.substring(0, 19).replace('T', '-') // YYYY-MM-DD-HH-mm-ss
|
||||
const sessionId = `${taskSlug}-${shortTimestamp}`
|
||||
const sessionFolder = `.workflow/.lite-plan/${sessionId}`
|
||||
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
description="Analyze codebase for task context",
|
||||
@@ -149,9 +156,14 @@ Task(
|
||||
Output Format: JSON-like structured object
|
||||
`
|
||||
)
|
||||
|
||||
// Save exploration results for CLI/agent access in lite-execute
|
||||
const explorationFile = `${sessionFolder}/exploration.json`
|
||||
Write(explorationFile, JSON.stringify(explorationContext, null, 2))
|
||||
```
|
||||
|
||||
**Output**: `explorationContext` (see Data Structures section)
|
||||
**Output**: `explorationContext` (in-memory, see Data Structures section)
|
||||
**Artifact**: Saved to `{sessionFolder}/exploration.json` for CLI/agent use
|
||||
|
||||
**Progress Tracking**:
|
||||
- Mark Phase 1 completed
|
||||
@@ -228,6 +240,14 @@ Current Claude generates plan directly:
|
||||
- Estimated Time: Total implementation time
|
||||
- Recommended Execution: "Agent"
|
||||
|
||||
```javascript
|
||||
// Save planning results to session folder (same as Option B)
|
||||
const planFile = `${sessionFolder}/plan.json`
|
||||
Write(planFile, JSON.stringify(planObject, null, 2))
|
||||
```
|
||||
|
||||
**Artifact**: Saved to `{sessionFolder}/plan.json` for CLI/agent use
|
||||
|
||||
**Option B: Agent-Based Planning (Medium/High Complexity)**
|
||||
|
||||
Delegate to cli-lite-planning-agent:
|
||||
@@ -270,9 +290,14 @@ Task(
|
||||
Format: "{Action} in {file_path}: {details} following {pattern}"
|
||||
`
|
||||
)
|
||||
|
||||
// Save planning results to session folder
|
||||
const planFile = `${sessionFolder}/plan.json`
|
||||
Write(planFile, JSON.stringify(planObject, null, 2))
|
||||
```
|
||||
|
||||
**Output**: `planObject` (see Data Structures section)
|
||||
**Artifact**: Saved to `{sessionFolder}/plan.json` for CLI/agent use
|
||||
|
||||
**Progress Tracking**:
|
||||
- Mark Phase 3 completed
|
||||
@@ -315,7 +340,7 @@ ${i+1}. **${task.title}** (${task.file})
|
||||
|
||||
**Step 4.2: Collect User Confirmation**
|
||||
|
||||
Four questions via single AskUserQuestion call:
|
||||
Three questions via single AskUserQuestion call:
|
||||
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
@@ -353,15 +378,6 @@ Confirm plan? (Multi-select: can supplement via "Other")`,
|
||||
{ label: "Agent Review", description: "@code-reviewer agent" },
|
||||
{ label: "Skip", description: "No review" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Export plan to Enhanced Task JSON file?\n\nAllows reuse with lite-execute later.",
|
||||
header: "Export JSON",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Yes", description: "Export to JSON (recommended for complex tasks)" },
|
||||
{ label: "No", description: "Keep in-memory only" }
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
@@ -384,10 +400,6 @@ Code Review (after execution):
|
||||
├─ Gemini Review → gemini CLI analysis
|
||||
├─ Agent Review → Current Claude review
|
||||
└─ Other → Custom tool (e.g., qwen, codex)
|
||||
|
||||
Export JSON:
|
||||
├─ Yes → Export to .workflow/lite-plans/plan-{timestamp}.json
|
||||
└─ No → In-memory only
|
||||
```
|
||||
|
||||
**Progress Tracking**:
|
||||
@@ -398,48 +410,48 @@ Export JSON:
|
||||
|
||||
### Phase 5: Dispatch to Execution
|
||||
|
||||
**Step 5.1: Export Enhanced Task JSON (Optional)**
|
||||
**Step 5.1: Export Enhanced Task JSON**
|
||||
|
||||
Only execute if `userSelection.export_task_json === "Yes"`:
|
||||
Always export Enhanced Task JSON to session folder:
|
||||
|
||||
```javascript
|
||||
if (userSelection.export_task_json === "Yes") {
|
||||
const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
|
||||
const taskId = `LP-${timestamp}`
|
||||
const filename = `.workflow/lite-plans/${taskId}.json`
|
||||
const taskId = `LP-${shortTimestamp}`
|
||||
const filename = `${sessionFolder}/task.json`
|
||||
|
||||
const enhancedTaskJson = {
|
||||
id: taskId,
|
||||
title: original_task_description,
|
||||
status: "pending",
|
||||
const enhancedTaskJson = {
|
||||
id: taskId,
|
||||
title: original_task_description,
|
||||
status: "pending",
|
||||
|
||||
meta: {
|
||||
type: "planning",
|
||||
created_at: new Date().toISOString(),
|
||||
complexity: planObject.complexity,
|
||||
estimated_time: planObject.estimated_time,
|
||||
recommended_execution: planObject.recommended_execution,
|
||||
workflow: "lite-plan"
|
||||
meta: {
|
||||
type: "planning",
|
||||
created_at: new Date().toISOString(),
|
||||
complexity: planObject.complexity,
|
||||
estimated_time: planObject.estimated_time,
|
||||
recommended_execution: planObject.recommended_execution,
|
||||
workflow: "lite-plan",
|
||||
session_id: sessionId,
|
||||
session_folder: sessionFolder
|
||||
},
|
||||
|
||||
context: {
|
||||
requirements: [original_task_description],
|
||||
plan: {
|
||||
summary: planObject.summary,
|
||||
approach: planObject.approach,
|
||||
tasks: planObject.tasks
|
||||
},
|
||||
|
||||
context: {
|
||||
requirements: [original_task_description],
|
||||
plan: {
|
||||
summary: planObject.summary,
|
||||
approach: planObject.approach,
|
||||
tasks: planObject.tasks
|
||||
},
|
||||
exploration: explorationContext || null,
|
||||
clarifications: clarificationContext || null,
|
||||
focus_paths: explorationContext?.relevant_files || [],
|
||||
acceptance: planObject.tasks.flatMap(t => t.acceptance)
|
||||
}
|
||||
exploration: explorationContext || null,
|
||||
clarifications: clarificationContext || null,
|
||||
focus_paths: explorationContext?.relevant_files || [],
|
||||
acceptance: planObject.tasks.flatMap(t => t.acceptance)
|
||||
}
|
||||
|
||||
Write(filename, JSON.stringify(enhancedTaskJson, null, 2))
|
||||
console.log(`Enhanced Task JSON exported to: ${filename}`)
|
||||
console.log(`Reuse with: /workflow:lite-execute ${filename}`)
|
||||
}
|
||||
|
||||
Write(filename, JSON.stringify(enhancedTaskJson, null, 2))
|
||||
console.log(`Enhanced Task JSON exported to: ${filename}`)
|
||||
console.log(`Session folder: ${sessionFolder}`)
|
||||
console.log(`Reuse with: /workflow:lite-execute ${filename}`)
|
||||
```
|
||||
|
||||
**Step 5.2: Store Execution Context**
|
||||
@@ -451,7 +463,18 @@ executionContext = {
|
||||
clarificationContext: clarificationContext || null,
|
||||
executionMethod: userSelection.execution_method,
|
||||
codeReviewTool: userSelection.code_review_tool,
|
||||
originalUserInput: original_task_description
|
||||
originalUserInput: original_task_description,
|
||||
|
||||
// Session artifacts location
|
||||
session: {
|
||||
id: sessionId,
|
||||
folder: sessionFolder,
|
||||
artifacts: {
|
||||
exploration: explorationContext ? `${sessionFolder}/exploration.json` : null,
|
||||
plan: `${sessionFolder}/plan.json`,
|
||||
task: `${sessionFolder}/task.json` // Always exported
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -462,7 +485,11 @@ SlashCommand(command="/workflow:lite-execute --in-memory")
|
||||
```
|
||||
|
||||
**Execution Handoff**:
|
||||
- lite-execute reads `executionContext` variable
|
||||
- lite-execute reads `executionContext` variable from memory
|
||||
- `executionContext.session.artifacts` contains file paths to saved planning artifacts:
|
||||
- `exploration` - exploration.json (if exploration performed)
|
||||
- `plan` - plan.json (always exists)
|
||||
- `task` - task.json (if user selected export)
|
||||
- All execution logic handled by lite-execute
|
||||
- lite-plan completes after successful handoff
|
||||
|
||||
@@ -502,7 +529,7 @@ SlashCommand(command="/workflow:lite-execute --in-memory")
|
||||
- Plan confirmation (multi-select with supplements)
|
||||
- Execution method selection
|
||||
- Code review tool selection (custom via "Other")
|
||||
- JSON export option
|
||||
- Enhanced Task JSON always exported to session folder
|
||||
- Allows plan refinement without re-selecting execution method
|
||||
|
||||
### Task Management
|
||||
@@ -519,11 +546,11 @@ SlashCommand(command="/workflow:lite-execute --in-memory")
|
||||
- Medium: 5-7 tasks (detailed)
|
||||
- High: 7-10 tasks (comprehensive)
|
||||
|
||||
3. **No File Artifacts During Planning**:
|
||||
- All planning stays in memory
|
||||
- Optional Enhanced Task JSON export (user choice)
|
||||
- Faster workflow, cleaner workspace
|
||||
- Plan context passed directly to execution
|
||||
3. **Session Artifact Management**:
|
||||
- All planning artifacts saved to dedicated session folder
|
||||
- Enhanced Task JSON always exported for reusability
|
||||
- Plan context passed to execution via memory and files
|
||||
- Clean organization with session-based folder structure
|
||||
|
||||
### Planning Standards
|
||||
|
||||
@@ -550,6 +577,34 @@ SlashCommand(command="/workflow:lite-execute --in-memory")
|
||||
| Phase 4 Confirmation Timeout | User no response > 5 minutes | Save context to temp var, display resume instructions, exit gracefully |
|
||||
| Phase 4 Modification Loop | User requests modify > 3 times | Suggest breaking task into smaller pieces or using `/workflow:plan` |
|
||||
|
||||
## Session Folder Structure
|
||||
|
||||
Each lite-plan execution creates a dedicated session folder to organize all artifacts:
|
||||
|
||||
```
|
||||
.workflow/.lite-plan/{task-slug}-{short-timestamp}/
|
||||
├── exploration.json # Exploration results (if exploration performed)
|
||||
├── plan.json # Planning results (always created)
|
||||
└── task.json # Enhanced Task JSON (always created)
|
||||
```
|
||||
|
||||
**Folder Naming Convention**:
|
||||
- `{task-slug}`: First 40 characters of task description, lowercased, non-alphanumeric replaced with `-`
|
||||
- `{short-timestamp}`: YYYY-MM-DD-HH-mm-ss format
|
||||
- Example: `.workflow/.lite-plan/implement-user-auth-jwt-2025-01-15-14-30-45/`
|
||||
|
||||
**File Contents**:
|
||||
- `exploration.json`: Complete explorationContext object (if exploration performed, see Data Structures)
|
||||
- `plan.json`: Complete planObject (always created, see Data Structures)
|
||||
- `task.json`: Enhanced Task JSON with all context (always created, see Data Structures)
|
||||
|
||||
**Access Patterns**:
|
||||
- **lite-plan**: Creates folder and writes all artifacts during execution, passes paths via `executionContext.session.artifacts`
|
||||
- **lite-execute**: Reads artifact paths from `executionContext.session.artifacts` (see lite-execute.md for usage details)
|
||||
- **User**: Can inspect artifacts for debugging or reference
|
||||
- **Reuse**: Pass `task.json` path to `/workflow:lite-execute {path}` for re-execution
|
||||
|
||||
|
||||
## Data Structures
|
||||
|
||||
### explorationContext
|
||||
@@ -621,7 +676,18 @@ Context passed to lite-execute via --in-memory (Phase 5):
|
||||
clarificationContext: {...} | null, // User responses from Phase 2
|
||||
executionMethod: "Agent" | "Codex" | "Auto",
|
||||
codeReviewTool: "Skip" | "Gemini Review" | "Agent Review" | string,
|
||||
originalUserInput: string // User's original task description
|
||||
originalUserInput: string, // User's original task description
|
||||
|
||||
// Session artifacts location (for lite-execute to access saved files)
|
||||
session: {
|
||||
id: string, // Session identifier: {taskSlug}-{shortTimestamp}
|
||||
folder: string, // Session folder path: .workflow/.lite-plan/{session-id}
|
||||
artifacts: {
|
||||
exploration: string | null, // exploration.json path (if exploration performed)
|
||||
plan: string, // plan.json path (always present)
|
||||
task: string // task.json path (always exported)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -72,6 +72,8 @@ CONTEXT: Existing user database schema, REST API endpoints
|
||||
- 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.
|
||||
|
||||
**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
|
||||
|
||||
**After Phase 1**: Return to user showing Phase 1 results, then auto-continue to Phase 2
|
||||
@@ -303,12 +305,7 @@ Quality Gate: Consider running /workflow:action-plan-verify to catch issues earl
|
||||
|
||||
**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary for Phase 2/3, or marked completed for Phase 4) → Next phase begins → Repeat until all phases complete.
|
||||
|
||||
### Benefits
|
||||
|
||||
- ✓ Real-time visibility into sub-task execution
|
||||
- ✓ Clear mental model: SlashCommand = attach → execute → collapse (Phase 2/3) or complete (Phase 4)
|
||||
- ✓ Clean summary after completion
|
||||
- ✓ Easy to track workflow progress
|
||||
|
||||
**Note**: See individual Phase descriptions for detailed TodoWrite Update examples:
|
||||
- **Phase 2, 3**: Multiple sub-tasks with attach/collapse pattern
|
||||
@@ -387,11 +384,6 @@ Return summary to user
|
||||
- Brainstorming artifacts (potentially modified by Phase 3)
|
||||
- Session-specific configuration
|
||||
|
||||
**Structured Description Benefits**:
|
||||
- **Clarity**: Clear separation of goal, scope, and context
|
||||
- **Consistency**: Same format across all phases
|
||||
- **Traceability**: Easy to track what was requested
|
||||
- **Precision**: Better context gathering and analysis
|
||||
|
||||
## Execution Flow Diagram
|
||||
|
||||
|
||||
@@ -476,15 +476,4 @@ Session state: PARTIALLY COMPLETE (session archived, manifest needs update)
|
||||
- Resume from Phase 2 (skip marker creation)
|
||||
- Idempotent operations (safe to retry)
|
||||
|
||||
### Benefits Over Previous Design
|
||||
|
||||
**Old Design Weakness**:
|
||||
- Move first → agent second
|
||||
- Agent failure → session moved but metadata incomplete
|
||||
- Inconsistent state requires manual cleanup
|
||||
|
||||
**New Design Strengths**:
|
||||
- Agent first → move second
|
||||
- Agent failure → session still active, safe to retry
|
||||
- Transactional commit → all-or-nothing file operations
|
||||
- Marker-based state → resume capability
|
||||
|
||||
@@ -1,15 +1,16 @@
|
||||
---
|
||||
name: workflow:status
|
||||
description: Generate on-demand views for project overview and workflow tasks with optional task-id filtering for detailed view
|
||||
argument-hint: "[optional: --project|task-id|--validate]"
|
||||
argument-hint: "[optional: --project|task-id|--validate|--dashboard]"
|
||||
---
|
||||
|
||||
# Workflow Status Command (/workflow:status)
|
||||
|
||||
## Overview
|
||||
Generates on-demand views from project and session data. Supports two modes:
|
||||
Generates on-demand views from project and session data. Supports multiple modes:
|
||||
1. **Project Overview** (`--project`): Shows completed features and project statistics
|
||||
2. **Workflow Tasks** (default): Shows current session task progress
|
||||
3. **HTML Dashboard** (`--dashboard`): Generates interactive HTML task board with active and archived sessions
|
||||
|
||||
No synchronization needed - all views are calculated from current JSON state.
|
||||
|
||||
@@ -19,6 +20,7 @@ No synchronization needed - all views are calculated from current JSON state.
|
||||
/workflow:status --project # Show project-level feature registry
|
||||
/workflow:status impl-1 # Show specific task details
|
||||
/workflow:status --validate # Validate workflow integrity
|
||||
/workflow:status --dashboard # Generate HTML dashboard board
|
||||
```
|
||||
|
||||
## Implementation Flow
|
||||
@@ -192,4 +194,135 @@ find .workflow/active/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null |
|
||||
|
||||
## Completed Tasks
|
||||
- [COMPLETED] impl-0: Setup completed
|
||||
```
|
||||
|
||||
## Dashboard Mode (HTML Board)
|
||||
|
||||
### Step 1: Check for --dashboard flag
|
||||
```bash
|
||||
# If --dashboard flag present → Execute Dashboard Mode
|
||||
```
|
||||
|
||||
### Step 2: Collect Workflow Data
|
||||
|
||||
**Collect Active Sessions**:
|
||||
```bash
|
||||
# Find all active sessions
|
||||
find .workflow/active/ -name "WFS-*" -type d 2>/dev/null
|
||||
|
||||
# For each active session, read metadata and tasks
|
||||
for session in $(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null); do
|
||||
cat "$session/workflow-session.json"
|
||||
find "$session/.task/" -name "*.json" -type f 2>/dev/null
|
||||
done
|
||||
```
|
||||
|
||||
**Collect Archived Sessions**:
|
||||
```bash
|
||||
# Find all archived sessions
|
||||
find .workflow/archives/ -name "WFS-*" -type d 2>/dev/null
|
||||
|
||||
# Read manifest if exists
|
||||
cat .workflow/archives/manifest.json 2>/dev/null
|
||||
|
||||
# For each archived session, read metadata
|
||||
for archive in $(find .workflow/archives/ -name "WFS-*" -type d 2>/dev/null); do
|
||||
cat "$archive/workflow-session.json" 2>/dev/null
|
||||
# Count completed tasks
|
||||
find "$archive/.task/" -name "*.json" -type f 2>/dev/null | wc -l
|
||||
done
|
||||
```
|
||||
|
||||
### Step 3: Process and Structure Data
|
||||
|
||||
**Build data structure for dashboard**:
|
||||
```javascript
|
||||
const dashboardData = {
|
||||
activeSessions: [],
|
||||
archivedSessions: [],
|
||||
generatedAt: new Date().toISOString()
|
||||
};
|
||||
|
||||
// Process active sessions
|
||||
for each active_session in active_sessions:
|
||||
const sessionData = JSON.parse(Read(active_session/workflow-session.json));
|
||||
const tasks = [];
|
||||
|
||||
// Load all tasks for this session
|
||||
for each task_file in find(active_session/.task/*.json):
|
||||
const taskData = JSON.parse(Read(task_file));
|
||||
tasks.push({
|
||||
task_id: taskData.task_id,
|
||||
title: taskData.title,
|
||||
status: taskData.status,
|
||||
type: taskData.type
|
||||
});
|
||||
|
||||
dashboardData.activeSessions.push({
|
||||
session_id: sessionData.session_id,
|
||||
project: sessionData.project,
|
||||
status: sessionData.status,
|
||||
created_at: sessionData.created_at || sessionData.initialized_at,
|
||||
tasks: tasks
|
||||
});
|
||||
|
||||
// Process archived sessions
|
||||
for each archived_session in archived_sessions:
|
||||
const sessionData = JSON.parse(Read(archived_session/workflow-session.json));
|
||||
const taskCount = bash(find archived_session/.task/*.json | wc -l);
|
||||
|
||||
dashboardData.archivedSessions.push({
|
||||
session_id: sessionData.session_id,
|
||||
project: sessionData.project,
|
||||
archived_at: sessionData.completed_at || sessionData.archived_at,
|
||||
taskCount: parseInt(taskCount),
|
||||
archive_path: archived_session
|
||||
});
|
||||
```
|
||||
|
||||
### Step 4: Generate HTML from Template
|
||||
|
||||
**Load template and inject data**:
|
||||
```javascript
|
||||
// Read the HTML template
|
||||
const template = Read("~/.claude/templates/workflow-dashboard.html");
|
||||
|
||||
// Prepare data for injection
|
||||
const dataJson = JSON.stringify(dashboardData, null, 2);
|
||||
|
||||
// Replace placeholder with actual data
|
||||
const htmlContent = template.replace('{{WORKFLOW_DATA}}', dataJson);
|
||||
|
||||
// Ensure .workflow directory exists
|
||||
bash(mkdir -p .workflow);
|
||||
```
|
||||
|
||||
### Step 5: Write HTML File
|
||||
|
||||
```bash
|
||||
# Write the generated HTML to .workflow/dashboard.html
|
||||
Write({
|
||||
file_path: ".workflow/dashboard.html",
|
||||
content: htmlContent
|
||||
})
|
||||
```
|
||||
|
||||
### Step 6: Display Success Message
|
||||
|
||||
```markdown
|
||||
Dashboard generated successfully!
|
||||
|
||||
Location: .workflow/dashboard.html
|
||||
|
||||
Open in browser:
|
||||
file://$(pwd)/.workflow/dashboard.html
|
||||
|
||||
Features:
|
||||
- 📊 Active sessions overview
|
||||
- 📦 Archived sessions history
|
||||
- 🔍 Search and filter
|
||||
- 📈 Progress tracking
|
||||
- 🎨 Dark/light theme
|
||||
|
||||
Refresh data: Re-run /workflow:status --dashboard
|
||||
```
|
||||
@@ -93,11 +93,7 @@ TEST_FOCUS: [Test scenarios]
|
||||
|
||||
**Parse**: Extract testContextPath (`.workflow/active/[sessionId]/.process/test-context-package.json`)
|
||||
|
||||
**Benefits**:
|
||||
- Makes TDD aware of existing environment
|
||||
- Identifies reusable test patterns
|
||||
- Prevents duplicate test creation
|
||||
- Enables integration with existing tests
|
||||
|
||||
|
||||
<!-- TodoWrite: When test-context-gather invoked, INSERT 3 test-context-gather tasks -->
|
||||
|
||||
@@ -345,12 +341,7 @@ Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task
|
||||
- **Phase 5**: Generated IMPL tasks contain internal Red-Green-Refactor cycles
|
||||
- **Conditional Phase 4**: Conflict resolution only if conflict_risk ≥ medium
|
||||
|
||||
### Benefits
|
||||
|
||||
- ✓ Real-time visibility into TDD workflow execution
|
||||
- ✓ Clear mental model: SlashCommand = attach → execute → collapse
|
||||
- ✓ Test-aware planning with coverage analysis
|
||||
- ✓ Self-contained TDD cycles within each IMPL task
|
||||
|
||||
**Note**: See individual Phase descriptions (Phase 3, 4, 5) for detailed TodoWrite Update examples with full JSON structures.
|
||||
|
||||
@@ -417,64 +408,6 @@ Convert user input to TDD-structured format:
|
||||
- **Command failure**: Keep phase in_progress, report error
|
||||
- **TDD validation failure**: Report incomplete chains or wrong dependencies
|
||||
|
||||
#### 3. Agent-Driven Planning
|
||||
**From plan --agent workflow**
|
||||
|
||||
Supports action-planning-agent for more autonomous TDD planning with:
|
||||
- MCP tool integration (code-index, exa)
|
||||
- Memory-first principles
|
||||
- Brainstorming artifact integration
|
||||
- Task merging over decomposition
|
||||
|
||||
### Workflow Comparison
|
||||
|
||||
| Aspect | Previous | Current (Optimized) |
|
||||
|--------|----------|---------------------|
|
||||
| **Phases** | 6 (with test coverage) | 7 (added concept verification) |
|
||||
| **Context** | Greenfield assumption | Existing codebase aware |
|
||||
| **Task Structure** | 1 feature = 3 tasks (TEST/IMPL/REFACTOR) | 1 feature = 1 task (internal TDD cycle) |
|
||||
| **Task Count** | 5 features = 15 tasks | 5 features = 5 tasks (70% reduction) |
|
||||
| **Green Phase** | Single implementation | Iterative with fix cycle |
|
||||
| **Failure Handling** | Manual intervention | Auto-diagnose + fix + revert |
|
||||
| **Test Analysis** | None | Deep coverage analysis |
|
||||
| **Feedback Loop** | Post-execution | During Green phase |
|
||||
| **Task Management** | High overhead (15 tasks) | Low overhead (5 tasks) |
|
||||
| **Execution Efficiency** | Frequent context switching | Continuous context per feature |
|
||||
|
||||
### Migration Notes
|
||||
|
||||
**Backward Compatibility**: Fully compatible
|
||||
- Existing TDD workflows continue to work
|
||||
- New features are additive, not breaking
|
||||
- Phase 3 can be skipped if test-context-gather not available
|
||||
|
||||
**Session Structure**:
|
||||
```
|
||||
.workflow/active/WFS-xxx/
|
||||
├── IMPL_PLAN.md (unified plan with TDD Implementation Tasks section)
|
||||
├── TODO_LIST.md (with internal TDD phase indicators)
|
||||
├── .process/
|
||||
│ ├── context-package.json
|
||||
│ ├── test-context-package.json
|
||||
│ ├── ANALYSIS_RESULTS.md (enhanced with TDD breakdown)
|
||||
│ └── green-fix-iteration-*.md (fix logs from Green phase cycles)
|
||||
└── .task/
|
||||
├── IMPL-1.json (Complete TDD task: Red-Green-Refactor internally)
|
||||
├── IMPL-2.json (Complete TDD task)
|
||||
├── IMPL-3.json (Complex feature container, if needed)
|
||||
├── IMPL-3.1.json (Complex feature subtask, if needed)
|
||||
└── IMPL-3.2.json (Complex feature subtask, if needed)
|
||||
```
|
||||
|
||||
**File Count Comparison**:
|
||||
- **Old structure**: 5 features = 15 task files (TEST/IMPL/REFACTOR × 5)
|
||||
- **New structure**: 5 features = 5 task files (IMPL-N × 5)
|
||||
- **Complex features**: Add container + subtasks only when necessary
|
||||
|
||||
**Configuration Options** (in IMPL tasks):
|
||||
- `meta.max_iterations`: Fix attempts (default: 3)
|
||||
- `meta.use_codex`: Auto-fix mode (default: false)
|
||||
|
||||
## Related Commands
|
||||
|
||||
**Prerequisite Commands**:
|
||||
|
||||
@@ -278,57 +278,85 @@ Task(
|
||||
subagent_type="cli-planning-agent",
|
||||
description=`Analyze test failures and generate fix task (iteration ${currentIteration})`,
|
||||
prompt=`
|
||||
## Context Package
|
||||
{
|
||||
"session_id": "${sessionId}",
|
||||
"iteration": ${currentIteration},
|
||||
"analysis_type": "test-failure",
|
||||
"failure_context": {
|
||||
"failed_tests": ${JSON.stringify(failedTests)},
|
||||
"error_messages": ${JSON.stringify(errorMessages)},
|
||||
"test_output": "${testOutputPath}",
|
||||
"pass_rate": ${passRate},
|
||||
"previous_attempts": ${JSON.stringify(previousAttempts)}
|
||||
},
|
||||
"cli_config": {
|
||||
"tool": "gemini",
|
||||
"model": "gemini-3-pro-preview-11-2025",
|
||||
"template": "01-diagnose-bug-root-cause.txt",
|
||||
"timeout": 2400000,
|
||||
"fallback": "qwen"
|
||||
},
|
||||
"task_config": {
|
||||
"agent": "@test-fix-agent",
|
||||
"type": "test-fix-iteration",
|
||||
"max_iterations": ${maxIterations},
|
||||
"use_codex": false
|
||||
}
|
||||
}
|
||||
## Task Objective
|
||||
Analyze test failures and generate structured fix task JSON for iteration ${currentIteration}
|
||||
|
||||
## Your Task
|
||||
1. Execute CLI analysis using Gemini (fallback to Qwen if needed)
|
||||
2. Parse CLI output and extract fix strategy with specific modification points
|
||||
3. Generate IMPL-fix-${currentIteration}.json using your internal task template
|
||||
4. Save analysis report to .process/iteration-${currentIteration}-analysis.md
|
||||
5. Report success and task ID back to orchestrator
|
||||
## MANDATORY FIRST STEPS
|
||||
1. Read test results: {session.test_results_path}
|
||||
2. Read test output: {session.test_output_path}
|
||||
3. Read iteration state: {session.iteration_state_path}
|
||||
4. Read fix history (if exists): {session.fix_history_path}
|
||||
|
||||
## Session Paths
|
||||
- Workflow Dir: {session.workflow_dir}
|
||||
- Test Results: {session.test_results_path}
|
||||
- Test Output: {session.test_output_path}
|
||||
- Iteration State: {session.iteration_state_path}
|
||||
- Fix History: {session.fix_history_path}
|
||||
- Task Output Dir: {session.task_dir}
|
||||
- Analysis Output: {session.process_dir}/iteration-${currentIteration}-analysis.md
|
||||
- CLI Output: {session.process_dir}/iteration-${currentIteration}-cli-output.txt
|
||||
|
||||
## Context Metadata
|
||||
- Session ID: ${sessionId}
|
||||
- Current Iteration: ${currentIteration}
|
||||
- Max Iterations: ${maxIterations}
|
||||
- Current Pass Rate: ${passRate}%
|
||||
|
||||
## CLI Configuration
|
||||
- Tool: gemini (fallback: qwen)
|
||||
- Model: gemini-3-pro-preview-11-2025
|
||||
- Template: 01-diagnose-bug-root-cause.txt
|
||||
- Timeout: 2400000ms
|
||||
|
||||
## Expected Deliverables
|
||||
1. Task JSON file: {session.task_dir}/IMPL-fix-${currentIteration}.json
|
||||
2. Analysis report: {session.process_dir}/iteration-${currentIteration}-analysis.md
|
||||
3. CLI raw output: {session.process_dir}/iteration-${currentIteration}-cli-output.txt
|
||||
4. Return task ID to orchestrator
|
||||
|
||||
## Quality Standards
|
||||
- Fix strategy must include specific modification points (file:function:lines)
|
||||
- Analysis must identify root causes, not just symptoms
|
||||
- Task JSON must be valid and complete with all required fields
|
||||
- All deliverables saved to specified paths
|
||||
|
||||
## Success Criteria
|
||||
Generate valid IMPL-fix-${currentIteration}.json with:
|
||||
- Concrete fix strategy with modification points
|
||||
- Root cause analysis from CLI tool
|
||||
- All required task JSON fields (id, title, status, meta, context, flow_control)
|
||||
- Return task ID for orchestrator to queue
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
#### Agent Response
|
||||
#### Agent Response Format
|
||||
**Agent must return structured response with deliverable paths:**
|
||||
|
||||
```javascript
|
||||
{
|
||||
"status": "success",
|
||||
"task_id": "IMPL-fix-${iteration}",
|
||||
"task_path": ".workflow/${session}/.task/IMPL-fix-${iteration}.json",
|
||||
"analysis_report": ".process/iteration-${iteration}-analysis.md",
|
||||
"cli_output": ".process/iteration-${iteration}-cli-output.txt",
|
||||
"summary": "Fix authentication token validation and null check issues",
|
||||
"modification_points_count": 2,
|
||||
"estimated_complexity": "low"
|
||||
"deliverables": {
|
||||
"task_json": ".workflow/${session}/.task/IMPL-fix-${iteration}.json",
|
||||
"analysis_report": ".workflow/${session}/.process/iteration-${iteration}-analysis.md",
|
||||
"cli_output": ".workflow/${session}/.process/iteration-${iteration}-cli-output.txt"
|
||||
},
|
||||
"summary": {
|
||||
"root_causes": ["Authentication token validation missing", "Null check missing"],
|
||||
"modification_points": [
|
||||
"src/auth/client.ts:sendRequest:45-50",
|
||||
"src/validators/user.ts:validateUser:23-25"
|
||||
],
|
||||
"estimated_complexity": "low",
|
||||
"expected_pass_rate_improvement": "85% → 95%"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Orchestrator validates all deliverable paths exist before proceeding.**
|
||||
|
||||
#### Generated Analysis Report Structure
|
||||
The @cli-planning-agent generates `.process/iteration-N-analysis.md`:
|
||||
|
||||
@@ -503,54 +531,55 @@ TodoWrite({
|
||||
4. **Iteration Complete**: Mark iteration item completed
|
||||
5. **All Complete**: Mark parent task completed
|
||||
|
||||
## Agent Context Package
|
||||
## Agent Context Loading
|
||||
|
||||
**Generated by test-cycle-execute orchestrator before launching agents.**
|
||||
**Orchestrator provides file paths, agents load content themselves.**
|
||||
|
||||
The orchestrator assembles this context package from:
|
||||
- Task JSON file (IMPL-*.json)
|
||||
- Iteration state files
|
||||
- Test results and failure context
|
||||
- Session metadata
|
||||
### Path References Provided to Agents
|
||||
|
||||
This package is passed to agents via the Task tool's prompt context.
|
||||
**Orchestrator passes these paths via Task tool prompt:**
|
||||
|
||||
### Enhanced Context for Test-Fix Agent
|
||||
```json
|
||||
```javascript
|
||||
{
|
||||
"task": { /* IMPL-fix-N.json */ },
|
||||
"iteration_context": {
|
||||
"current_iteration": N,
|
||||
"max_iterations": 5,
|
||||
"previous_attempts": [
|
||||
{
|
||||
"iteration": N-1,
|
||||
"failures": ["test1", "test2"],
|
||||
"fixes_attempted": ["fix1", "fix2"],
|
||||
"result": "partial_success"
|
||||
}
|
||||
],
|
||||
"failure_analysis": {
|
||||
"source": "gemini_cli",
|
||||
"analysis_file": ".process/iteration-N-analysis.md",
|
||||
"fix_strategy": { /* from CLI */ }
|
||||
}
|
||||
},
|
||||
"test_context": {
|
||||
"test_framework": "jest|pytest|...",
|
||||
"test_files": ["path/to/test1.test.ts"],
|
||||
"test_command": "npm test",
|
||||
"coverage_target": 80
|
||||
},
|
||||
"session": {
|
||||
"workflow_dir": ".workflow/active/WFS-test-{session}/",
|
||||
"iteration_state_file": ".process/iteration-state.json",
|
||||
"test_results_file": ".process/test-results.json",
|
||||
"fix_history_file": ".process/fix-history.json"
|
||||
}
|
||||
// Primary Task Definition
|
||||
"task_json_path": ".workflow/active/WFS-test-{session}/.task/IMPL-fix-N.json",
|
||||
|
||||
// Iteration Context Paths
|
||||
"iteration_state_path": ".workflow/active/WFS-test-{session}/.process/iteration-state.json",
|
||||
"fix_history_path": ".workflow/active/WFS-test-{session}/.process/fix-history.json",
|
||||
|
||||
// Test Context Paths
|
||||
"test_results_path": ".workflow/active/WFS-test-{session}/.process/test-results.json",
|
||||
"test_output_path": ".workflow/active/WFS-test-{session}/.process/test-output.log",
|
||||
"test_context_path": ".workflow/active/WFS-test-{session}/.process/TEST_ANALYSIS_RESULTS.md",
|
||||
|
||||
// Analysis & Strategy Paths (for fix-iteration tasks)
|
||||
"analysis_path": ".workflow/active/WFS-test-{session}/.process/iteration-N-analysis.md",
|
||||
"cli_output_path": ".workflow/active/WFS-test-{session}/.process/iteration-N-cli-output.txt",
|
||||
|
||||
// Session Management Paths
|
||||
"workflow_dir": ".workflow/active/WFS-test-{session}/",
|
||||
"summaries_dir": ".workflow/active/WFS-test-{session}/.summaries/",
|
||||
"todo_list_path": ".workflow/active/WFS-test-{session}/TODO_LIST.md",
|
||||
|
||||
// Metadata (simple values, not file content)
|
||||
"session_id": "WFS-test-{session}",
|
||||
"current_iteration": N,
|
||||
"max_iterations": 5
|
||||
}
|
||||
```
|
||||
|
||||
### Agent Loading Sequence
|
||||
|
||||
**Agents must load files in this order:**
|
||||
|
||||
1. **Task JSON** (`task_json_path`) - Get task definition, requirements, fix strategy
|
||||
2. **Iteration State** (`iteration_state_path`) - Understand current iteration context
|
||||
3. **Test Results** (`test_results_path`) - Analyze current test status
|
||||
4. **Test Output** (`test_output_path`) - Review detailed test execution logs
|
||||
5. **Analysis Report** (`analysis_path`, for fix tasks) - Load CLI-generated fix strategy
|
||||
6. **Fix History** (`fix_history_path`) - Review previous fix attempts to avoid repetition
|
||||
|
||||
## File Structure
|
||||
|
||||
### Test-Fix Session Files
|
||||
@@ -616,77 +645,66 @@ This package is passed to agents via the Task tool's prompt context.
|
||||
|
||||
## Agent Prompt Template
|
||||
|
||||
**Unified template for all agent tasks (orchestrator invokes with Task tool):**
|
||||
**Dynamic Generation**: Before agent invocation, orchestrator reads task JSON and extracts key requirements.
|
||||
|
||||
```bash
|
||||
Task(subagent_type="{meta.agent}",
|
||||
prompt="**TASK EXECUTION: {task.title}**
|
||||
prompt="Execute task: {task.title}
|
||||
|
||||
## STEP 1: Load Complete Task JSON
|
||||
**MANDATORY**: First load the complete task JSON from: {session.task_json_path}
|
||||
{[FLOW_CONTROL]}
|
||||
|
||||
cat {session.task_json_path}
|
||||
**Task Objectives** (from task JSON):
|
||||
{task.context.requirements}
|
||||
|
||||
**CRITICAL**: Validate all required fields present
|
||||
**Expected Deliverables**:
|
||||
- For test-gen: Test files in target directories, test coverage report
|
||||
- For test-fix: Test execution results saved to test-results.json, test-output.log
|
||||
- For test-fix-iteration: Fixed code files, updated test results, iteration summary
|
||||
|
||||
## STEP 2: Task Context (From Loaded JSON)
|
||||
**ID**: {task.id}
|
||||
**Type**: {task.meta.type}
|
||||
**Agent**: {task.meta.agent}
|
||||
**Quality Standards**:
|
||||
- All tests must execute without errors
|
||||
- Test results must be saved in structured JSON format
|
||||
- All deliverables must be saved to specified paths
|
||||
- Task status must be updated in task JSON
|
||||
|
||||
## STEP 3: Execute Task Based on Type
|
||||
**MANDATORY FIRST STEPS**:
|
||||
1. Read complete task JSON: {session.task_json_path}
|
||||
2. Load iteration state (if applicable): {session.iteration_state_path}
|
||||
3. Load test context: {session.test_context_path}
|
||||
|
||||
### For test-gen (IMPL-001):
|
||||
- Generate tests based on TEST_ANALYSIS_RESULTS.md
|
||||
- Follow test framework conventions
|
||||
- Create test files in target_files
|
||||
Follow complete execution guidelines in @.claude/agents/{meta.agent}.md
|
||||
|
||||
### For test-fix (IMPL-002):
|
||||
- Run test suite: {test_command}
|
||||
- Collect results to .process/test-results.json
|
||||
- Report results to orchestrator (do NOT analyze failures)
|
||||
- Orchestrator will handle failure detection and iteration decisions
|
||||
- If success: Mark complete
|
||||
**Session Paths** (use these for all file operations):
|
||||
- Workflow Dir: {session.workflow_dir}
|
||||
- Task JSON: {session.task_json_path}
|
||||
- TODO List: {session.todo_list_path}
|
||||
- Summaries Dir: {session.summaries_dir}
|
||||
- Test Results: {session.test_results_path}
|
||||
- Test Output Log: {session.test_output_path}
|
||||
- Iteration State: {session.iteration_state_path}
|
||||
- Fix History: {session.fix_history_path}
|
||||
|
||||
### For test-fix-iteration (IMPL-fix-N):
|
||||
- Load fix strategy from context.fix_strategy (CONTENT, not path)
|
||||
- Apply surgical fixes to identified files
|
||||
- Return results to orchestrator
|
||||
- Do NOT run tests independently - orchestrator manages all test execution
|
||||
- Do NOT handle failures - orchestrator analyzes and decides next iteration
|
||||
**Critical Rules**:
|
||||
- For test-fix tasks: Run tests and save results, do NOT analyze failures
|
||||
- For fix-iteration tasks: Apply fixes from task JSON, do NOT run tests independently
|
||||
- Orchestrator manages iteration loop and failure analysis
|
||||
- Return results to orchestrator for next-step decisions
|
||||
|
||||
## STEP 4: Implementation Context (From JSON)
|
||||
**Requirements**: {context.requirements}
|
||||
**Fix Strategy**: {context.fix_strategy} (full content provided in task JSON)
|
||||
**Failure Context**: {context.failure_context}
|
||||
**Iteration History**: {context.inherited.iteration_history}
|
||||
|
||||
## STEP 5: Flow Control Execution
|
||||
If flow_control.pre_analysis exists, execute steps sequentially
|
||||
|
||||
## STEP 6: Agent Completion
|
||||
1. Execute task following implementation_approach
|
||||
2. Update task status in JSON
|
||||
3. Update TODO_LIST.md
|
||||
4. Generate summary in .summaries/
|
||||
5. **CRITICAL**: Save results for orchestrator to analyze
|
||||
|
||||
**Output Requirements**:
|
||||
- test-results.json: Structured test results
|
||||
- test-output.log: Full test output
|
||||
- iteration-state.json: Current iteration state (if applicable)
|
||||
- task-summary.md: Completion summary
|
||||
|
||||
**Return to Orchestrator**: Agent completes and returns. Orchestrator decides next action.
|
||||
"),
|
||||
description="Execute {task.type} task with JSON validation")
|
||||
**Success Criteria**:
|
||||
- Complete all task objectives as specified in task JSON
|
||||
- Deliver all required outputs to specified paths
|
||||
- Update task status and TODO_LIST.md
|
||||
- Generate completion summary in .summaries/
|
||||
",
|
||||
description="Executing: {task.title}")
|
||||
```
|
||||
|
||||
**Key Points**:
|
||||
- Agent executes single task and returns
|
||||
- Orchestrator analyzes results and decides next step
|
||||
- Fix strategy content (not path) embedded in task JSON by orchestrator
|
||||
- Agent does not manage iteration loop
|
||||
**Key Changes from Previous Version**:
|
||||
1. **Paths over Content**: Provide JSON paths for agent to read, not embedded content
|
||||
2. **MANDATORY FIRST STEPS**: Explicit requirement to load task JSON and context
|
||||
3. **Complete Session Paths**: All file paths provided for agent operations
|
||||
4. **Emphasized Deliverables**: Clear deliverable requirements per task type
|
||||
5. **Simplified Structure**: Removed type-specific instructions (agent reads from JSON)
|
||||
|
||||
## Error Handling & Recovery
|
||||
|
||||
|
||||
@@ -374,14 +374,6 @@ CRITICAL - Next Steps:
|
||||
- **Phase 4**: Multi-task generation with quality gate (IMPL-001, IMPL-001.5-review, IMPL-002)
|
||||
- **Fix Mode Configuration**: `--use-codex` flag controls IMPL-002 fix mode (manual vs automated)
|
||||
|
||||
**Benefits**:
|
||||
- Real-time visibility into attached tasks during execution
|
||||
- Clean orchestrator-level summary after tasks complete
|
||||
- Clear mental model: SlashCommand = attach tasks, not delegate work
|
||||
- Dual-mode support: Both Session Mode and Prompt Mode use same attachment pattern
|
||||
- Dynamic attachment/collapse maintains clarity
|
||||
|
||||
**Note**: Unlike other workflow orchestrators, this file consolidates TodoWrite examples in this section rather than distributing them across Phase descriptions for better dual-mode clarity.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -355,11 +355,7 @@ Ready for execution. Use appropriate workflow commands to proceed.
|
||||
- **Phase 4**: Dual-task generation (IMPL-001 for test generation, IMPL-002 for test execution)
|
||||
- **Fix Mode Configuration**: `--use-codex` flag controls IMPL-002 fix mode (manual vs automated)
|
||||
|
||||
**Benefits**:
|
||||
- Real-time visibility into attached tasks during execution
|
||||
- Clean orchestrator-level summary after tasks complete
|
||||
- Clear mental model: SlashCommand = attach tasks, not delegate work
|
||||
- Dynamic attachment/collapse maintains clarity
|
||||
|
||||
|
||||
**Note**: See individual Phase descriptions (Phase 2, 3, 4) for detailed TodoWrite Update examples with full JSON structures.
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ examples:
|
||||
# Conflict Resolution Command
|
||||
|
||||
## Purpose
|
||||
Analyzes conflicts between implementation plans and existing codebase, generating multiple resolution strategies.
|
||||
Analyzes conflicts between implementation plans and existing codebase, **including module scenario uniqueness detection**, generating multiple resolution strategies with **iterative clarification until boundaries are clear**.
|
||||
|
||||
**Scope**: Detection and strategy generation only - NO code modification or task creation.
|
||||
|
||||
@@ -21,11 +21,14 @@ Analyzes conflicts between implementation plans and existing codebase, generatin
|
||||
| Responsibility | Description |
|
||||
|---------------|-------------|
|
||||
| **Detect Conflicts** | Analyze plan vs existing code inconsistencies |
|
||||
| **Scenario Uniqueness** | **NEW**: Search and compare new modules with existing modules for functional overlaps |
|
||||
| **Generate Strategies** | Provide 2-4 resolution options per conflict |
|
||||
| **Iterative Clarification** | **NEW**: Ask unlimited questions until scenario boundaries are clear and unique |
|
||||
| **Agent Re-analysis** | **NEW**: Dynamically update strategies based on user clarifications |
|
||||
| **CLI Analysis** | Use Gemini/Qwen (Claude fallback) |
|
||||
| **User Decision** | Present options, never auto-apply |
|
||||
| **User Decision** | Present options ONE BY ONE, never auto-apply |
|
||||
| **Direct Text Output** | Output questions via text directly, NEVER use bash echo/printf |
|
||||
| **Single Output** | `CONFLICT_RESOLUTION.md` with findings |
|
||||
| **Structured Data** | JSON output for programmatic processing, NO file generation |
|
||||
|
||||
## Conflict Categories
|
||||
|
||||
@@ -49,6 +52,13 @@ Analyzes conflicts between implementation plans and existing codebase, generatin
|
||||
- Setup conflicts
|
||||
- Breaking updates
|
||||
|
||||
### 5. Module Scenario Overlap
|
||||
- **NEW**: Functional overlap between new and existing modules
|
||||
- Scenario boundary ambiguity
|
||||
- Duplicate responsibility detection
|
||||
- Module merge/split decisions
|
||||
- **Requires iterative clarification until uniqueness confirmed**
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Phase 1: Validation
|
||||
@@ -76,20 +86,28 @@ Task(subagent_type="cli-execution-agent", prompt=`
|
||||
- Load plan from .workflow/active/{session_id}/.process/context-package.json
|
||||
- Extract role analyses and requirements
|
||||
|
||||
### 2. Execute CLI Analysis
|
||||
### 2. Execute CLI Analysis (Enhanced with Scenario Uniqueness Detection)
|
||||
|
||||
Primary (Gemini):
|
||||
cd {project_root} && gemini -p "
|
||||
PURPOSE: Detect conflicts between plan and codebase
|
||||
PURPOSE: Detect conflicts between plan and codebase, including module scenario overlaps
|
||||
TASK:
|
||||
• Compare architectures
|
||||
• Identify breaking API changes
|
||||
• Detect data model incompatibilities
|
||||
• Assess dependency conflicts
|
||||
• **NEW: Analyze module scenario uniqueness**
|
||||
- Extract new module functionality from plan
|
||||
- Search all existing modules with similar functionality
|
||||
- Compare scenario coverage and identify overlaps
|
||||
- Generate clarification questions for boundary definition
|
||||
MODE: analysis
|
||||
CONTEXT: @{existing_files} @.workflow/active/{session_id}/**/*
|
||||
EXPECTED: Conflict list with severity ratings
|
||||
RULES: Focus on breaking changes and migration needs
|
||||
CONTEXT: @**/*.ts @**/*.js @**/*.tsx @**/*.jsx @.workflow/active/{session_id}/**/*
|
||||
EXPECTED: Conflict list with severity ratings, including ModuleOverlap conflicts with:
|
||||
- Existing module list with scenarios
|
||||
- Overlap analysis matrix
|
||||
- Targeted clarification questions
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on breaking changes, migration needs, and functional overlaps | analysis=READ-ONLY
|
||||
"
|
||||
|
||||
Fallback: Qwen (same prompt) → Claude (manual analysis)
|
||||
@@ -98,9 +116,11 @@ Task(subagent_type="cli-execution-agent", prompt=`
|
||||
|
||||
Template per conflict:
|
||||
- Severity: Critical/High/Medium
|
||||
- Category: Architecture/API/Data/Dependency
|
||||
- Category: Architecture/API/Data/Dependency/ModuleOverlap
|
||||
- Affected files + impact
|
||||
- **For ModuleOverlap**: Include overlap_analysis with existing modules and scenarios
|
||||
- Options with pros/cons, effort, risk
|
||||
- **For ModuleOverlap strategies**: Add clarification_needed questions for boundary definition
|
||||
- Recommended strategy + rationale
|
||||
|
||||
### 4. Return Structured Conflict Data
|
||||
@@ -116,10 +136,10 @@ Task(subagent_type="cli-execution-agent", prompt=`
|
||||
"id": "CON-001",
|
||||
"brief": "一行中文冲突摘要",
|
||||
"severity": "Critical|High|Medium",
|
||||
"category": "Architecture|API|Data|Dependency",
|
||||
"category": "Architecture|API|Data|Dependency|ModuleOverlap",
|
||||
"affected_files": [
|
||||
".workflow/session/{session}/.brainstorm/guidance-specification.md",
|
||||
".workflow/session/{session}/.brainstorm/system-architect/analysis.md"
|
||||
".workflow/active/{session}/.brainstorm/guidance-specification.md",
|
||||
".workflow/active/{session}/.brainstorm/system-architect/analysis.md"
|
||||
],
|
||||
"description": "详细描述冲突 - 什么不兼容",
|
||||
"impact": {
|
||||
@@ -128,6 +148,23 @@ Task(subagent_type="cli-execution-agent", prompt=`
|
||||
"migration_required": true|false,
|
||||
"estimated_effort": "人天估计"
|
||||
},
|
||||
"overlap_analysis": {
|
||||
"// NOTE": "仅当 category=ModuleOverlap 时需要此字段",
|
||||
"new_module": {
|
||||
"name": "新模块名称",
|
||||
"scenarios": ["场景1", "场景2", "场景3"],
|
||||
"responsibilities": "职责描述"
|
||||
},
|
||||
"existing_modules": [
|
||||
{
|
||||
"file": "src/existing/module.ts",
|
||||
"name": "现有模块名称",
|
||||
"scenarios": ["场景A", "场景B"],
|
||||
"overlap_scenarios": ["重叠场景1", "重叠场景2"],
|
||||
"responsibilities": "现有模块职责"
|
||||
}
|
||||
]
|
||||
},
|
||||
"strategies": [
|
||||
{
|
||||
"name": "策略名称（中文）",
|
||||
@@ -137,9 +174,15 @@ Task(subagent_type="cli-execution-agent", prompt=`
|
||||
"effort": "时间估计",
|
||||
"pros": ["优点1", "优点2"],
|
||||
"cons": ["缺点1", "缺点2"],
|
||||
"clarification_needed": [
|
||||
"// NOTE: 仅当需要用户进一步澄清时需要此字段（尤其是 ModuleOverlap）",
|
||||
"新模块的核心职责边界是什么？",
|
||||
"如何与现有模块 X 协作？",
|
||||
"哪些场景应该由新模块处理？"
|
||||
],
|
||||
"modifications": [
|
||||
{
|
||||
"file": ".workflow/session/{session}/.brainstorm/guidance-specification.md",
|
||||
"file": ".workflow/active/{session}/.brainstorm/guidance-specification.md",
|
||||
"section": "## 2. System Architect Decisions",
|
||||
"change_type": "update",
|
||||
"old_content": "原始内容片段（用于定位）",
|
||||
@@ -147,7 +190,7 @@ Task(subagent_type="cli-execution-agent", prompt=`
|
||||
"rationale": "为什么这样改"
|
||||
},
|
||||
{
|
||||
"file": ".workflow/session/{session}/.brainstorm/system-architect/analysis.md",
|
||||
"file": ".workflow/active/{session}/.brainstorm/system-architect/analysis.md",
|
||||
"section": "## Design Decisions",
|
||||
"change_type": "update",
|
||||
"old_content": "原始内容片段",
|
||||
@@ -204,155 +247,251 @@ Task(subagent_type="cli-execution-agent", prompt=`
|
||||
`)
|
||||
```
|
||||
|
||||
**Agent Internal Flow**:
|
||||
**Agent Internal Flow** (Enhanced):
|
||||
```
|
||||
1. Load context package
|
||||
2. Check conflict_risk (exit if none/low)
|
||||
3. Read existing files + plan artifacts
|
||||
4. Run CLI analysis (Gemini→Qwen→Claude)
|
||||
5. Parse conflict findings
|
||||
6. Generate 2-4 strategies per conflict with modifications
|
||||
4. Run CLI analysis (Gemini→Qwen→Claude) with enhanced tasks:
|
||||
- Standard conflict detection (Architecture/API/Data/Dependency)
|
||||
- **NEW: Module scenario uniqueness detection**
|
||||
* Extract new module functionality from plan
|
||||
* Search all existing modules with similar keywords/functionality
|
||||
* Compare scenario coverage and responsibilities
|
||||
* Identify functional overlaps and boundary ambiguities
|
||||
* Generate ModuleOverlap conflicts with overlap_analysis
|
||||
5. Parse conflict findings (including ModuleOverlap category)
|
||||
6. Generate 2-4 strategies per conflict:
|
||||
- Include modifications for each strategy
|
||||
- **For ModuleOverlap**: Add clarification_needed questions for boundary definition
|
||||
7. Return JSON to stdout (NOT file write)
|
||||
8. Return execution log path
|
||||
```
|
||||
|
||||
### Phase 3: User Confirmation via Text Interaction
|
||||
### Phase 3: Iterative User Interaction with Clarification Loop
|
||||
|
||||
**Command parses agent JSON output and presents conflicts to user via text**:
|
||||
**Execution Flow**:
|
||||
```
|
||||
FOR each conflict (逐个处理，无数量限制):
|
||||
clarified = false
|
||||
round = 0
|
||||
userClarifications = []
|
||||
|
||||
WHILE (!clarified && round < 10):
|
||||
round++
|
||||
|
||||
// 1. Display conflict (包含所有关键字段)
|
||||
- category, id, brief, severity, description
|
||||
- IF ModuleOverlap: 展示 overlap_analysis
|
||||
* new_module: {name, scenarios, responsibilities}
|
||||
* existing_modules[]: {file, name, scenarios, overlap_scenarios, responsibilities}
|
||||
|
||||
// 2. Display strategies (2-4个策略 + 自定义选项)
|
||||
- FOR each strategy: {name, approach, complexity, risk, effort, pros, cons}
|
||||
* IF clarification_needed: 展示待澄清问题列表
|
||||
- 自定义选项: {suggestions: modification_suggestions[]}
|
||||
|
||||
// 3. User selects strategy
|
||||
userChoice = readInput()
|
||||
|
||||
IF userChoice == "自定义":
|
||||
customConflicts.push({id, brief, category, suggestions, overlap_analysis})
|
||||
clarified = true
|
||||
BREAK
|
||||
|
||||
selectedStrategy = strategies[userChoice]
|
||||
|
||||
// 4. Clarification loop
|
||||
IF selectedStrategy.clarification_needed.length > 0:
|
||||
// 收集澄清答案
|
||||
FOR each question:
|
||||
answer = readInput()
|
||||
userClarifications.push({question, answer})
|
||||
|
||||
// Agent 重新分析
|
||||
reanalysisResult = Task(cli-execution-agent, prompt={
|
||||
冲突信息: {id, brief, category, 策略}
|
||||
用户澄清: userClarifications[]
|
||||
场景分析: overlap_analysis (if ModuleOverlap)
|
||||
|
||||
输出: {
|
||||
uniqueness_confirmed: bool,
|
||||
rationale: string,
|
||||
updated_strategy: {name, approach, complexity, risk, effort, modifications[]},
|
||||
remaining_questions: [] (如果仍有歧义)
|
||||
}
|
||||
})
|
||||
|
||||
IF reanalysisResult.uniqueness_confirmed:
|
||||
selectedStrategy = updated_strategy
|
||||
selectedStrategy.clarifications = userClarifications
|
||||
clarified = true
|
||||
ELSE:
|
||||
// 更新澄清问题，继续下一轮
|
||||
selectedStrategy.clarification_needed = remaining_questions
|
||||
ELSE:
|
||||
clarified = true
|
||||
|
||||
resolvedConflicts.push({conflict, strategy: selectedStrategy})
|
||||
END WHILE
|
||||
END FOR
|
||||
|
||||
// Build output
|
||||
selectedStrategies = resolvedConflicts.map(r => ({
|
||||
conflict_id, strategy, clarifications[]
|
||||
}))
|
||||
```
|
||||
|
||||
**Key Data Structures**:
|
||||
|
||||
```javascript
|
||||
// 1. Parse agent JSON output
|
||||
const conflictData = JSON.parse(agentOutput);
|
||||
const conflicts = conflictData.conflicts; // No 4-conflict limit
|
||||
|
||||
// 2. Format conflicts as text output (max 10 per round)
|
||||
const batchSize = 10;
|
||||
const batches = chunkArray(conflicts, batchSize);
|
||||
|
||||
for (const [batchIdx, batch] of batches.entries()) {
|
||||
const totalBatches = batches.length;
|
||||
|
||||
// Output batch header
|
||||
console.log(`===== 冲突解决 (第 ${batchIdx + 1}/${totalBatches} 轮) =====\n`);
|
||||
|
||||
// Output each conflict in batch
|
||||
batch.forEach((conflict, idx) => {
|
||||
const questionNum = batchIdx * batchSize + idx + 1;
|
||||
console.log(`【问题${questionNum} - ${conflict.category}】${conflict.id}: ${conflict.brief}`);
|
||||
|
||||
conflict.strategies.forEach((strategy, sIdx) => {
|
||||
const optionLetter = String.fromCharCode(97 + sIdx); // a, b, c, ...
|
||||
console.log(`${optionLetter}) ${strategy.name}`);
|
||||
console.log(` 说明：${strategy.approach}`);
|
||||
console.log(` 复杂度: ${strategy.complexity} | 风险: ${strategy.risk} | 工作量: ${strategy.effort}`);
|
||||
});
|
||||
|
||||
// Add custom option
|
||||
const customLetter = String.fromCharCode(97 + conflict.strategies.length);
|
||||
console.log(`${customLetter}) 自定义修改`);
|
||||
console.log(` 说明：根据修改建议自行处理，不应用预设策略`);
|
||||
|
||||
// Show modification suggestions
|
||||
if (conflict.modification_suggestions && conflict.modification_suggestions.length > 0) {
|
||||
console.log(` 修改建议：`);
|
||||
conflict.modification_suggestions.forEach(suggestion => {
|
||||
console.log(` - ${suggestion}`);
|
||||
});
|
||||
}
|
||||
console.log();
|
||||
});
|
||||
|
||||
console.log(`请回答 (格式: 1a 2b 3c...)：`);
|
||||
|
||||
// Wait for user input
|
||||
const userInput = await readUserInput();
|
||||
|
||||
// Parse answers
|
||||
const answers = parseUserAnswers(userInput, batch);
|
||||
// Custom conflict tracking
|
||||
customConflicts[] = {
|
||||
id, brief, category,
|
||||
suggestions: modification_suggestions[],
|
||||
overlap_analysis: { new_module{}, existing_modules[] } // ModuleOverlap only
|
||||
}
|
||||
|
||||
// 3. Build selected strategies (exclude custom selections)
|
||||
const selectedStrategies = answers.filter(a => !a.isCustom).map(a => a.strategy);
|
||||
const customConflicts = answers.filter(a => a.isCustom).map(a => ({
|
||||
id: a.conflict.id,
|
||||
brief: a.conflict.brief,
|
||||
suggestions: a.conflict.modification_suggestions
|
||||
}));
|
||||
// Agent re-analysis prompt output
|
||||
{
|
||||
uniqueness_confirmed: bool,
|
||||
rationale: string,
|
||||
updated_strategy: {
|
||||
name, approach, complexity, risk, effort,
|
||||
modifications: [{file, section, change_type, old_content, new_content, rationale}]
|
||||
},
|
||||
remaining_questions: string[]
|
||||
}
|
||||
```
|
||||
|
||||
**Text Output Example**:
|
||||
**Text Output Example** (展示关键字段):
|
||||
|
||||
```markdown
|
||||
===== 冲突解决 (第 1/1 轮) =====
|
||||
============================================================
|
||||
冲突 1/3 - 第 1 轮
|
||||
============================================================
|
||||
【ModuleOverlap】CON-001: 新增用户认证服务与现有模块功能重叠
|
||||
严重程度: High | 描述: 计划中的 UserAuthService 与现有 AuthManager 场景重叠
|
||||
|
||||
【问题1 - Architecture】CON-001: 现有认证系统与计划不兼容
|
||||
a) 渐进式迁移
|
||||
说明：保留现有系统，逐步迁移到新方案
|
||||
复杂度: Medium | 风险: Low | 工作量: 3-5天
|
||||
b) 完全重写
|
||||
说明：废弃旧系统，从零实现新认证
|
||||
复杂度: High | 风险: Medium | 工作量: 7-10天
|
||||
c) 自定义修改
|
||||
说明：根据修改建议自行处理，不应用预设策略
|
||||
修改建议：
|
||||
- 评估现有认证系统的兼容性，考虑是否可以通过适配器模式桥接
|
||||
- 检查JWT token格式和验证逻辑是否需要调整
|
||||
- 确保用户会话管理与新架构保持一致
|
||||
--- 场景重叠分析 ---
|
||||
新模块: UserAuthService | 场景: 登录, Token验证, 权限, MFA
|
||||
现有模块: AuthManager (src/auth/AuthManager.ts) | 重叠: 登录, Token验证
|
||||
|
||||
【问题2 - Data】CON-002: 数据库 schema 冲突
|
||||
a) 添加迁移脚本
|
||||
说明：创建数据库迁移脚本处理 schema 变更
|
||||
复杂度: Low | 风险: Low | 工作量: 1-2天
|
||||
b) 自定义修改
|
||||
说明：根据修改建议自行处理，不应用预设策略
|
||||
修改建议：
|
||||
- 检查现有表结构是否支持新增字段，避免破坏性变更
|
||||
- 考虑使用数据库版本控制工具（如Flyway或Liquibase）
|
||||
- 准备数据迁移和回滚策略
|
||||
--- 解决策略 ---
|
||||
1) 合并 (Low复杂度 | Low风险 | 2-3天)
|
||||
⚠️ 需澄清: AuthManager是否能承担MFA？
|
||||
|
||||
请回答 (格式: 1a 2b)：
|
||||
2) 拆分边界 (Medium复杂度 | Medium风险 | 4-5天)
|
||||
⚠️ 需澄清: 基础/高级认证边界? Token验证归谁?
|
||||
|
||||
3) 自定义修改
|
||||
建议: 评估扩展性; 策略模式分离; 定义接口边界
|
||||
|
||||
请选择 (1-3): > 2
|
||||
|
||||
--- 澄清问答 (第1轮) ---
|
||||
Q: 基础/高级认证边界?
|
||||
A: 基础=密码登录+token验证, 高级=MFA+OAuth+SSO
|
||||
|
||||
Q: Token验证归谁?
|
||||
A: 统一由 AuthManager 负责
|
||||
|
||||
🔄 重新分析...
|
||||
✅ 唯一性已确认 | 理由: 边界清晰 - AuthManager(基础+token), UserAuthService(MFA+OAuth+SSO)
|
||||
|
||||
============================================================
|
||||
冲突 2/3 - 第 1 轮 [下一个冲突]
|
||||
============================================================
|
||||
```
|
||||
|
||||
**User Input Examples**:
|
||||
- `1a 2a` → Conflict 1: 渐进式迁移, Conflict 2: 添加迁移脚本
|
||||
- `1b 2b` → Conflict 1: 完全重写, Conflict 2: 自定义修改
|
||||
- `1c 2c` → Both choose custom modification (user handles manually with suggestions)
|
||||
**Loop Characteristics**: 逐个处理 | 无限轮次(max 10) | 动态问题生成 | Agent重新分析判断唯一性 | ModuleOverlap场景边界澄清
|
||||
|
||||
### Phase 4: Apply Modifications
|
||||
|
||||
```javascript
|
||||
// 1. Extract modifications from selected strategies
|
||||
// 1. Extract modifications from resolved strategies
|
||||
const modifications = [];
|
||||
selectedStrategies.forEach(strategy => {
|
||||
if (strategy !== "skip") {
|
||||
modifications.push(...strategy.modifications);
|
||||
selectedStrategies.forEach(item => {
|
||||
if (item.strategy && item.strategy.modifications) {
|
||||
modifications.push(...item.strategy.modifications.map(mod => ({
|
||||
...mod,
|
||||
conflict_id: item.conflict_id,
|
||||
clarifications: item.clarifications
|
||||
})));
|
||||
}
|
||||
});
|
||||
|
||||
console.log(`\n正在应用 ${modifications.length} 个修改...`);
|
||||
|
||||
// 2. Apply each modification using Edit tool
|
||||
modifications.forEach(mod => {
|
||||
if (mod.change_type === "update") {
|
||||
Edit({
|
||||
file_path: mod.file,
|
||||
old_string: mod.old_content,
|
||||
new_string: mod.new_content
|
||||
});
|
||||
const appliedModifications = [];
|
||||
const failedModifications = [];
|
||||
|
||||
modifications.forEach((mod, idx) => {
|
||||
try {
|
||||
console.log(`[${idx + 1}/${modifications.length}] 修改 ${mod.file}...`);
|
||||
|
||||
if (mod.change_type === "update") {
|
||||
Edit({
|
||||
file_path: mod.file,
|
||||
old_string: mod.old_content,
|
||||
new_string: mod.new_content
|
||||
});
|
||||
} else if (mod.change_type === "add") {
|
||||
// Handle addition - append or insert based on section
|
||||
const fileContent = Read(mod.file);
|
||||
const updated = insertContentAfterSection(fileContent, mod.section, mod.new_content);
|
||||
Write(mod.file, updated);
|
||||
} else if (mod.change_type === "remove") {
|
||||
Edit({
|
||||
file_path: mod.file,
|
||||
old_string: mod.old_content,
|
||||
new_string: ""
|
||||
});
|
||||
}
|
||||
|
||||
appliedModifications.push(mod);
|
||||
console.log(` ✓ 成功`);
|
||||
} catch (error) {
|
||||
console.log(` ✗ 失败: ${error.message}`);
|
||||
failedModifications.push({ ...mod, error: error.message });
|
||||
}
|
||||
// Handle "add" and "remove" similarly
|
||||
});
|
||||
|
||||
// 3. Update context-package.json
|
||||
// 3. Update context-package.json with resolution details
|
||||
const contextPackage = JSON.parse(Read(contextPath));
|
||||
contextPackage.conflict_detection.conflict_risk = "resolved";
|
||||
contextPackage.conflict_detection.resolved_conflicts = conflicts.map(c => c.id);
|
||||
contextPackage.conflict_detection.resolved_conflicts = selectedStrategies.map(s => ({
|
||||
conflict_id: s.conflict_id,
|
||||
strategy_name: s.strategy.name,
|
||||
clarifications: s.clarifications
|
||||
}));
|
||||
contextPackage.conflict_detection.custom_conflicts = customConflicts.map(c => c.id);
|
||||
contextPackage.conflict_detection.resolved_at = new Date().toISOString();
|
||||
Write(contextPath, JSON.stringify(contextPackage, null, 2));
|
||||
|
||||
// 4. Output custom conflict summary (if any)
|
||||
// 4. Output custom conflict summary with overlap analysis (if any)
|
||||
if (customConflicts.length > 0) {
|
||||
console.log("\n===== 需要自定义处理的冲突 =====\n");
|
||||
console.log(`\n${'='.repeat(60)}`);
|
||||
console.log(`需要自定义处理的冲突 (${customConflicts.length})`);
|
||||
console.log(`${'='.repeat(60)}\n`);
|
||||
|
||||
customConflicts.forEach(conflict => {
|
||||
console.log(`【${conflict.id}】${conflict.brief}`);
|
||||
console.log("修改建议：");
|
||||
console.log(`【${conflict.category}】${conflict.id}: ${conflict.brief}`);
|
||||
|
||||
// Show overlap analysis for ModuleOverlap conflicts
|
||||
if (conflict.category === 'ModuleOverlap' && conflict.overlap_analysis) {
|
||||
console.log(`\n场景重叠信息:`);
|
||||
console.log(` 新模块: ${conflict.overlap_analysis.new_module.name}`);
|
||||
console.log(` 场景: ${conflict.overlap_analysis.new_module.scenarios.join(', ')}`);
|
||||
console.log(`\n 与以下模块重叠:`);
|
||||
conflict.overlap_analysis.existing_modules.forEach(mod => {
|
||||
console.log(` - ${mod.name} (${mod.file})`);
|
||||
console.log(` 重叠场景: ${mod.overlap_scenarios.join(', ')}`);
|
||||
});
|
||||
}
|
||||
|
||||
console.log(`\n修改建议:`);
|
||||
conflict.suggestions.forEach(suggestion => {
|
||||
console.log(` - ${suggestion}`);
|
||||
});
|
||||
@@ -360,24 +499,42 @@ if (customConflicts.length > 0) {
|
||||
});
|
||||
}
|
||||
|
||||
// 5. Return summary
|
||||
// 5. Output failure summary (if any)
|
||||
if (failedModifications.length > 0) {
|
||||
console.log(`\n⚠️ 部分修改失败 (${failedModifications.length}):`);
|
||||
failedModifications.forEach(mod => {
|
||||
console.log(` - ${mod.file}: ${mod.error}`);
|
||||
});
|
||||
}
|
||||
|
||||
// 6. Return summary
|
||||
return {
|
||||
resolved: modifications.length,
|
||||
custom: customConflicts.length,
|
||||
modified_files: [...new Set(modifications.map(m => m.file))],
|
||||
custom_conflicts: customConflicts
|
||||
total_conflicts: conflicts.length,
|
||||
resolved_with_strategy: selectedStrategies.length,
|
||||
custom_handling: customConflicts.length,
|
||||
modifications_applied: appliedModifications.length,
|
||||
modifications_failed: failedModifications.length,
|
||||
modified_files: [...new Set(appliedModifications.map(m => m.file))],
|
||||
custom_conflicts: customConflicts,
|
||||
clarification_records: selectedStrategies.filter(s => s.clarifications.length > 0)
|
||||
};
|
||||
```
|
||||
|
||||
**Validation**:
|
||||
```
|
||||
✓ Agent returns valid JSON structure
|
||||
✓ Text output displays all conflicts (max 10 per round)
|
||||
✓ User selections captured correctly
|
||||
✓ Agent returns valid JSON structure with ModuleOverlap conflicts
|
||||
✓ Conflicts processed ONE BY ONE (not in batches)
|
||||
✓ ModuleOverlap conflicts include overlap_analysis field
|
||||
✓ Strategies with clarification_needed display questions
|
||||
✓ User selections captured correctly per conflict
|
||||
✓ Clarification loop continues until uniqueness confirmed
|
||||
✓ Agent re-analysis returns uniqueness_confirmed and updated_strategy
|
||||
✓ Maximum 10 rounds per conflict safety limit enforced
|
||||
✓ Edit tool successfully applies modifications
|
||||
✓ guidance-specification.md updated
|
||||
✓ Role analyses (*.md) updated
|
||||
✓ context-package.json marked as resolved
|
||||
✓ context-package.json marked as resolved with clarification records
|
||||
✓ Custom conflicts display overlap_analysis for manual handling
|
||||
✓ Agent log saved to .workflow/active/{session_id}/.chat/
|
||||
```
|
||||
|
||||
@@ -441,24 +598,38 @@ If Edit tool fails mid-application:
|
||||
- NO report file generation
|
||||
|
||||
**User Interaction**:
|
||||
- Text-based strategy selection (max 10 conflicts per round)
|
||||
- **Iterative conflict processing**: One conflict at a time, not in batches
|
||||
- Each conflict: 2-4 strategy options + "自定义修改" option (with suggestions)
|
||||
- **Clarification loop**: Unlimited questions per conflict until uniqueness confirmed (max 10 rounds)
|
||||
- **ModuleOverlap conflicts**: Display overlap_analysis with existing modules
|
||||
- **Agent re-analysis**: Dynamic strategy updates based on user clarifications
|
||||
|
||||
### Success Criteria
|
||||
```
|
||||
✓ CLI analysis returns valid JSON structure
|
||||
✓ Conflicts presented in batches (max 10 per round)
|
||||
✓ CLI analysis returns valid JSON structure with ModuleOverlap category
|
||||
✓ Agent performs scenario uniqueness detection (searches existing modules)
|
||||
✓ Conflicts processed ONE BY ONE with iterative clarification
|
||||
✓ Min 2 strategies per conflict with modifications
|
||||
✓ ModuleOverlap conflicts include overlap_analysis with existing modules
|
||||
✓ Strategies requiring clarification include clarification_needed questions
|
||||
✓ Each conflict includes 2-5 modification_suggestions
|
||||
✓ Text output displays all conflicts correctly with suggestions
|
||||
✓ User selections captured and processed
|
||||
✓ Text output displays conflict with overlap analysis (if ModuleOverlap)
|
||||
✓ User selections captured per conflict
|
||||
✓ Clarification loop continues until uniqueness confirmed (unlimited rounds, max 10)
|
||||
✓ Agent re-analysis with user clarifications updates strategy
|
||||
✓ Uniqueness confirmation based on clear scenario boundaries
|
||||
✓ Edit tool applies modifications successfully
|
||||
✓ Custom conflicts displayed with suggestions for manual handling
|
||||
✓ Custom conflicts displayed with overlap_analysis for manual handling
|
||||
✓ guidance-specification.md updated with resolved conflicts
|
||||
✓ Role analyses (*.md) updated with resolved conflicts
|
||||
✓ context-package.json marked as "resolved"
|
||||
✓ context-package.json marked as "resolved" with clarification records
|
||||
✓ No CONFLICT_RESOLUTION.md file generated
|
||||
✓ Modification summary includes custom conflict count
|
||||
✓ Modification summary includes:
|
||||
- Total conflicts
|
||||
- Resolved with strategy (count)
|
||||
- Custom handling (count)
|
||||
- Clarification records
|
||||
- Overlap analysis for custom ModuleOverlap conflicts
|
||||
✓ Agent log saved to .workflow/active/{session_id}/.chat/
|
||||
✓ Error handling robust (validate/retry/degrade)
|
||||
```
|
||||
|
||||
@@ -22,7 +22,7 @@ Orchestrator command that invokes `context-search-agent` to gather comprehensive
|
||||
- **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/session/{session}/.process/context-package.json`
|
||||
- **Standardized Output**: Generate `.workflow/active/{session}/.process/context-package.json`
|
||||
|
||||
## Execution Flow
|
||||
|
||||
@@ -57,8 +57,6 @@ Task(
|
||||
subagent_type="context-search-agent",
|
||||
description="Gather comprehensive context for plan",
|
||||
prompt=`
|
||||
You are executing as context-search-agent (.claude/agents/context-search-agent.md).
|
||||
|
||||
## Execution Mode
|
||||
**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution
|
||||
|
||||
|
||||
@@ -17,242 +17,140 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit
|
||||
- **Two-Phase Flow**: Discovery (context gathering) → Output (document generation)
|
||||
- **Memory-First**: Reuse loaded documents from conversation memory
|
||||
- **MCP-Enhanced**: Use MCP tools for advanced code analysis and research
|
||||
- **Pre-Selected Templates**: Command selects correct template based on `--cli-execute` flag **before** invoking agent
|
||||
- **Agent Simplicity**: Agent receives pre-selected template and focuses only on content generation
|
||||
- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
|
||||
|
||||
## Execution Lifecycle
|
||||
|
||||
### Phase 1: Discovery & Context Loading
|
||||
**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
|
||||
### Phase 1: Context Preparation (Command Responsibility)
|
||||
|
||||
**Agent Context Package**:
|
||||
```javascript
|
||||
{
|
||||
"session_id": "WFS-[session-id]",
|
||||
"execution_mode": "agent-mode" | "cli-execute-mode", // Determined by flag
|
||||
"task_json_template_path": "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt"
|
||||
| "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt",
|
||||
// Path selected by command based on --cli-execute flag, agent reads it
|
||||
"session_metadata": {
|
||||
// If in memory: use cached content
|
||||
// Else: Load from .workflow/active//{session-id}/workflow-session.json
|
||||
},
|
||||
"brainstorm_artifacts": {
|
||||
// Loaded from context-package.json → brainstorm_artifacts section
|
||||
"role_analyses": [
|
||||
{
|
||||
"role": "system-architect",
|
||||
"files": [{"path": "...", "type": "primary|supplementary"}]
|
||||
}
|
||||
],
|
||||
"guidance_specification": {"path": "...", "exists": true},
|
||||
"synthesis_output": {"path": "...", "exists": true},
|
||||
"conflict_resolution": {"path": "...", "exists": true} // if conflict_risk >= medium
|
||||
},
|
||||
"context_package_path": ".workflow/active//{session-id}/.process/context-package.json",
|
||||
"context_package": {
|
||||
// If in memory: use cached content
|
||||
// Else: Load from .workflow/active//{session-id}/.process/context-package.json
|
||||
},
|
||||
"mcp_capabilities": {
|
||||
"code_index": true,
|
||||
"exa_code": true,
|
||||
"exa_web": true
|
||||
}
|
||||
}
|
||||
**Command prepares session paths and metadata, agent loads content autonomously.**
|
||||
|
||||
**Session Path Structure**:
|
||||
```
|
||||
.workflow/active/WFS-{session-id}/
|
||||
├── workflow-session.json # Session metadata
|
||||
├── .process/
|
||||
│ └── context-package.json # Context package with artifact catalog
|
||||
├── .task/ # Output: Task JSON files
|
||||
├── IMPL_PLAN.md # Output: Implementation plan
|
||||
└── TODO_LIST.md # Output: TODO list
|
||||
```
|
||||
|
||||
**Discovery Actions**:
|
||||
1. **Load Session Context** (if not in memory)
|
||||
```javascript
|
||||
if (!memory.has("workflow-session.json")) {
|
||||
Read(.workflow/active//{session-id}/workflow-session.json)
|
||||
}
|
||||
```
|
||||
**Command Preparation**:
|
||||
1. **Assemble Session Paths** for agent prompt:
|
||||
- `session_metadata_path`
|
||||
- `context_package_path`
|
||||
- Output directory paths
|
||||
|
||||
2. **Load Context Package** (if not in memory)
|
||||
```javascript
|
||||
if (!memory.has("context-package.json")) {
|
||||
Read(.workflow/active//{session-id}/.process/context-package.json)
|
||||
}
|
||||
```
|
||||
2. **Provide Metadata** (simple values):
|
||||
- `session_id`
|
||||
- `execution_mode` (agent-mode | cli-execute-mode)
|
||||
- `mcp_capabilities` (available MCP tools)
|
||||
|
||||
3. **Extract & Load Role Analyses** (from context-package.json)
|
||||
```javascript
|
||||
// Extract role analysis paths from context package
|
||||
const roleAnalysisPaths = contextPackage.brainstorm_artifacts.role_analyses
|
||||
.flatMap(role => role.files.map(f => f.path));
|
||||
|
||||
// Load each role analysis file
|
||||
roleAnalysisPaths.forEach(path => Read(path));
|
||||
```
|
||||
|
||||
4. **Load Conflict Resolution** (from context-package.json, if exists)
|
||||
```javascript
|
||||
if (contextPackage.brainstorm_artifacts.conflict_resolution?.exists) {
|
||||
Read(contextPackage.brainstorm_artifacts.conflict_resolution.path)
|
||||
}
|
||||
```
|
||||
|
||||
5. **Code Analysis with Native Tools** (optional - enhance understanding)
|
||||
```bash
|
||||
# Find relevant files for task context
|
||||
find . -name "*auth*" -type f
|
||||
rg "authentication|oauth" -g "*.ts"
|
||||
```
|
||||
|
||||
6. **MCP External Research** (optional - gather best practices)
|
||||
```javascript
|
||||
// Get external examples for implementation
|
||||
mcp__exa__get_code_context_exa(
|
||||
query="TypeScript JWT authentication best practices",
|
||||
tokensNum="dynamic"
|
||||
)
|
||||
```
|
||||
**Note**: Agent autonomously loads files based on context package content (dynamic, not fixed template). Brainstorming artifacts only loaded if they exist in session.
|
||||
|
||||
### Phase 2: Agent Execution (Document Generation)
|
||||
|
||||
**Pre-Agent Template Selection** (Command decides path before invoking agent):
|
||||
```javascript
|
||||
// Command checks flag and selects template PATH (not content)
|
||||
const templatePath = hasCliExecuteFlag
|
||||
? "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt"
|
||||
: "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt";
|
||||
```
|
||||
|
||||
**Agent Invocation**:
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="action-planning-agent",
|
||||
description="Generate task JSON and implementation plan",
|
||||
prompt=`
|
||||
## Execution Context
|
||||
## Task Objective
|
||||
Generate implementation plan (IMPL_PLAN.md), task JSONs, and TODO list for workflow session
|
||||
|
||||
**Session ID**: WFS-{session-id}
|
||||
**Execution Mode**: {agent-mode | cli-execute-mode}
|
||||
**Task JSON Template Path**: {template_path}
|
||||
## MANDATORY FIRST STEPS
|
||||
1. Read session metadata: {session.session_metadata_path}
|
||||
2. Load context package: {session.context_package_path}
|
||||
3. **Dynamically load files based on context package content** (see below)
|
||||
|
||||
## Phase 1: Discovery Results (Provided Context)
|
||||
## Dynamic Content Loading Strategy
|
||||
|
||||
### Session Metadata
|
||||
{session_metadata_content}
|
||||
**Load files based on what exists in context package - NOT a fixed template**
|
||||
|
||||
### Role Analyses (Enhanced by Synthesis)
|
||||
{role_analyses_content}
|
||||
- Includes requirements, design specs, enhancements, and clarifications from synthesis phase
|
||||
### Step 1: Always Load (Required)
|
||||
- **Session Metadata** → Extract user input
|
||||
- User description: Original task requirements
|
||||
- Project scope and boundaries
|
||||
- Technical constraints
|
||||
|
||||
### Artifacts Inventory
|
||||
- **Guidance Specification**: {guidance_spec_path}
|
||||
- **Role Analyses**: {role_analyses_list}
|
||||
### Step 2: Check Context Package (Conditional Loading)
|
||||
|
||||
### Context Package
|
||||
{context_package_summary}
|
||||
- Includes conflict_risk assessment
|
||||
**If `brainstorm_artifacts` exists in context package:**
|
||||
- Load artifacts **in priority order** as listed below
|
||||
- **If `brainstorm_artifacts` does NOT exist**: Skip to Step 3
|
||||
|
||||
### Conflict Resolution (Conditional)
|
||||
If conflict_risk was medium/high, modifications have been applied to:
|
||||
- **guidance-specification.md**: Design decisions updated to resolve conflicts
|
||||
- **Role analyses (*.md)**: Recommendations adjusted for compatibility
|
||||
- **context-package.json**: Marked as "resolved" with conflict IDs
|
||||
- NO separate CONFLICT_RESOLUTION.md file (conflicts resolved in-place)
|
||||
**Priority Loading (when artifacts exist):**
|
||||
1. **guidance-specification.md** (if `guidance_specification.exists = true`)
|
||||
- Overall design framework - use as primary reference
|
||||
|
||||
### MCP Analysis Results (Optional)
|
||||
**Code Structure**: {mcp_code_index_results}
|
||||
**External Research**: {mcp_exa_research_results}
|
||||
2. **Role Analyses** (if `role_analyses[]` array exists)
|
||||
- Load ALL role analysis files listed in array
|
||||
- Each file path: `role_analyses[i].files[j].path`
|
||||
|
||||
## Phase 2: Document Generation Task
|
||||
3. **Synthesis Output** (if `synthesis_output.exists = true`)
|
||||
- Integrated view with clarifications
|
||||
|
||||
**Agent Configuration Reference**: All task generation rules, quantification requirements, quality standards, and execution details are defined in action-planning-agent.
|
||||
4. **Conflict Resolution** (if `conflict_risk` = "medium" or "high")
|
||||
- Check `conflict_resolution.status`
|
||||
- If "resolved": Use updated artifacts (conflicts pre-addressed)
|
||||
|
||||
Refer to: @.claude/agents/action-planning-agent.md for:
|
||||
- Task Decomposition Standards
|
||||
- Quantification Requirements (MANDATORY)
|
||||
- 5-Field Task JSON Schema
|
||||
- IMPL_PLAN.md Structure
|
||||
- TODO_LIST.md Format
|
||||
- Execution Flow & Quality Validation
|
||||
### Step 3: Extract Project Context
|
||||
- `focus_areas`: Target directories for implementation
|
||||
- `assets`: Existing code patterns to reuse
|
||||
|
||||
### Required Outputs Summary
|
||||
## Session Paths
|
||||
- Session Metadata: .workflow/active/{session-id}/workflow-session.json
|
||||
- Context Package: .workflow/active/{session-id}/.process/context-package.json
|
||||
- Output Task Dir: .workflow/active/{session-id}/.task/
|
||||
- Output IMPL_PLAN: .workflow/active/{session-id}/IMPL_PLAN.md
|
||||
- Output TODO_LIST: .workflow/active/{session-id}/TODO_LIST.md
|
||||
|
||||
#### 1. Task JSON Files (.task/IMPL-*.json)
|
||||
- **Location**: `.workflow/active//{session-id}/.task/`
|
||||
- **Template**: Read from `{template_path}` (pre-selected by command based on `--cli-execute` flag)
|
||||
- **Schema**: 5-field structure (id, title, status, meta, context, flow_control) with artifacts integration
|
||||
- **Details**: See action-planning-agent.md § Task JSON Generation
|
||||
## Context Metadata
|
||||
- Session ID: {session-id}
|
||||
- Execution Mode: {agent-mode | cli-execute-mode}
|
||||
- MCP Capabilities Available: {exa_code, exa_web, code_index}
|
||||
|
||||
#### 2. IMPL_PLAN.md
|
||||
- **Location**: `.workflow/active//{session-id}/IMPL_PLAN.md`
|
||||
- **Template**: `~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt`
|
||||
- **Details**: See action-planning-agent.md § Implementation Plan Creation
|
||||
**Note**: Content loading is **dynamic** based on actual files in session, not a fixed template
|
||||
|
||||
#### 3. TODO_LIST.md
|
||||
- **Location**: `.workflow/active//{session-id}/TODO_LIST.md`
|
||||
- **Format**: Hierarchical task list with status indicators (▸, [ ], [x]) and JSON links
|
||||
- **Details**: See action-planning-agent.md § TODO List Generation
|
||||
## Expected Deliverables
|
||||
1. **Task JSON Files** (.task/IMPL-*.json)
|
||||
- 6-field schema (id, title, status, context_package_path, meta, context, flow_control)
|
||||
- Quantified requirements with explicit counts
|
||||
- Artifacts integration from context package
|
||||
- Flow control with pre_analysis steps
|
||||
|
||||
### Agent Execution Summary
|
||||
2. **Implementation Plan** (IMPL_PLAN.md)
|
||||
- Context analysis and artifact references
|
||||
- Task breakdown and execution strategy
|
||||
- Complete structure per agent definition
|
||||
|
||||
**Key Steps** (Detailed instructions in action-planning-agent.md):
|
||||
1. Load task JSON template from provided path
|
||||
2. Extract and decompose tasks with quantification
|
||||
3. Generate task JSON files enforcing quantification requirements
|
||||
4. Create IMPL_PLAN.md using template
|
||||
5. Generate TODO_LIST.md matching task JSONs
|
||||
6. Update session state
|
||||
3. **TODO List** (TODO_LIST.md)
|
||||
- Hierarchical structure with status indicators (▸, [ ], [x])
|
||||
- Links to task JSONs and summaries
|
||||
- Matches task JSON hierarchy
|
||||
|
||||
**Quality Gates** (Full checklist in action-planning-agent.md):
|
||||
- ✓ Quantification requirements enforced (explicit counts, measurable acceptance, exact targets)
|
||||
- ✓ Task count ≤10 (hard limit)
|
||||
- ✓ Artifact references mapped correctly
|
||||
- ✓ MCP tool integration added
|
||||
- ✓ Documents follow template structure
|
||||
## Quality Standards
|
||||
- Task count ≤12 (hard limit)
|
||||
- All requirements quantified (explicit counts and lists)
|
||||
- Acceptance criteria measurable (verification commands)
|
||||
- Artifact references mapped from context package
|
||||
- All documents follow agent-defined structure
|
||||
|
||||
## Output
|
||||
|
||||
Generate all three documents and report completion status:
|
||||
- Task JSON files created: N files
|
||||
- Artifacts integrated: synthesis-spec, guidance-specification, N role analyses
|
||||
- MCP enhancements: code-index, exa-research
|
||||
- Session ready for execution: /workflow:execute
|
||||
## Success Criteria
|
||||
- All task JSONs valid and saved to .task/ directory
|
||||
- IMPL_PLAN.md created with complete structure
|
||||
- TODO_LIST.md generated matching task JSONs
|
||||
- Return completion status with file count
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
|
||||
### Agent Context Passing
|
||||
|
||||
**Memory-Aware Context Assembly**:
|
||||
```javascript
|
||||
// Assemble context package for agent
|
||||
const agentContext = {
|
||||
session_id: "WFS-[id]",
|
||||
|
||||
// Use memory if available, else load
|
||||
session_metadata: memory.has("workflow-session.json")
|
||||
? memory.get("workflow-session.json")
|
||||
: Read(.workflow/active/WFS-[id]/workflow-session.json),
|
||||
|
||||
context_package_path: ".workflow/active/WFS-[id]/.process/context-package.json",
|
||||
|
||||
context_package: memory.has("context-package.json")
|
||||
? memory.get("context-package.json")
|
||||
: Read(".workflow/active/WFS-[id]/.process/context-package.json"),
|
||||
|
||||
// Extract brainstorm artifacts from context package
|
||||
brainstorm_artifacts: extractBrainstormArtifacts(context_package),
|
||||
|
||||
// Load role analyses using paths from context package
|
||||
role_analyses: brainstorm_artifacts.role_analyses
|
||||
.flatMap(role => role.files)
|
||||
.map(file => Read(file.path)),
|
||||
|
||||
// Load conflict resolution if exists (from context package)
|
||||
conflict_resolution: brainstorm_artifacts.conflict_resolution?.exists
|
||||
? Read(brainstorm_artifacts.conflict_resolution.path)
|
||||
: null,
|
||||
|
||||
// Optional MCP enhancements
|
||||
mcp_analysis: executeMcpDiscovery()
|
||||
}
|
||||
```
|
||||
**Key Changes from Previous Version**:
|
||||
1. **Paths over Content**: Provide file paths for agent to read, not embedded content
|
||||
2. **MANDATORY FIRST STEPS**: Explicit requirement to load session metadata and context package
|
||||
3. **Complete Session Paths**: All file paths provided for agent operations
|
||||
4. **Emphasized Deliverables**: Clear deliverable requirements with quality standards
|
||||
5. **No Agent Self-Reference**: Removed "Refer to action-planning-agent.md" (agent knows its own definition)
|
||||
6. **No Template Paths**: Removed all template references (agent has complete schema/structure definitions)
|
||||
|
||||
@@ -30,11 +30,6 @@ Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent
|
||||
- **1 feature = 1 task** containing complete TDD cycle internally
|
||||
- Each task executes Red-Green-Refactor phases sequentially
|
||||
- Task count = Feature count (typically 5 features = 5 tasks)
|
||||
- **Benefits**:
|
||||
- 70% reduction in task management overhead
|
||||
- Continuous context per feature (no switching between TEST/IMPL/REFACTOR)
|
||||
- Simpler dependency management
|
||||
- Maintains TDD rigor through internal phase structure
|
||||
|
||||
**Previous Approach** (Deprecated):
|
||||
- 1 feature = 3 separate tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M)
|
||||
@@ -499,11 +494,7 @@ IMPL (Green phase) tasks include automatic test-fix cycle:
|
||||
- **Repeat**: Up to max_iterations (default: 3)
|
||||
5. **Safety Net**: Auto-revert all changes if max iterations reached
|
||||
|
||||
**Key Benefits**:
|
||||
- Faster feedback loop within Green phase
|
||||
- Autonomous recovery from initial implementation errors
|
||||
- Systematic debugging with Gemini's bug-fix template
|
||||
- Safe rollback prevents broken TDD state
|
||||
|
||||
|
||||
## Configuration Options
|
||||
- **meta.max_iterations**: Number of fix attempts (default: 3 for TDD, 5 for test-gen)
|
||||
|
||||
@@ -120,11 +120,7 @@ ELSE:
|
||||
- Infers animation patterns from UI element positioning and design style
|
||||
- Generates context-aware animation specifications based on visual analysis
|
||||
|
||||
**Benefits**:
|
||||
- ✅ Flexible input - works with screenshots, mockups, or design files
|
||||
- ✅ AI-driven inference from visual cues
|
||||
- ✅ No external dependencies on MCP tools
|
||||
- ✅ Combines visual analysis with industry best practices
|
||||
|
||||
|
||||
### Step 3: Load Design Tokens Context
|
||||
|
||||
|
||||
@@ -480,11 +480,7 @@ TodoWrite({todos: [
|
||||
// - Orchestrator's own task (no SlashCommand attachment)
|
||||
// - Mark Phase 3 as completed
|
||||
// - Final state: All 4 orchestrator tasks completed
|
||||
//
|
||||
// Benefits:
|
||||
// ✓ Real-time visibility into attached tasks during execution
|
||||
// ✓ Clean orchestrator-level summary after tasks complete
|
||||
// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
|
||||
|
||||
// ✓ Dynamic attachment/collapse maintains clarity
|
||||
```
|
||||
|
||||
@@ -623,17 +619,7 @@ File discovery is fully automatic - no glob patterns needed.
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
- **Simplified Interface**: Single path parameter with intelligent defaults
|
||||
- **Auto-Generation**: Package names auto-generated from directory names
|
||||
- **Automatic Discovery**: No need to specify file patterns - finds all style files automatically
|
||||
- **Pure Orchestrator**: No direct agent execution, delegates to specialized commands
|
||||
- **Auto-Continue**: Autonomous 4-phase execution without user interaction
|
||||
- **Safety First**: Overwrite protection, validation checks, error handling
|
||||
- **Code Reuse**: Leverages existing `import-from-code` and `reference-page-generator` commands
|
||||
- **Clean Separation**: Each command has single responsibility
|
||||
- **Easy Maintenance**: Changes to sub-commands automatically apply
|
||||
|
||||
## Architecture
|
||||
|
||||
|
||||
@@ -227,7 +227,68 @@ Write(file_path=".workflow/active/WFS-{session}/.brainstorming/ui-designer/desig
|
||||
content="[generated content with @ references]")
|
||||
```
|
||||
|
||||
### Phase 5: Completion
|
||||
### Phase 5: Update Context Package
|
||||
|
||||
**Purpose**: Sync design system references to context-package.json
|
||||
|
||||
**Operations**:
|
||||
```bash
|
||||
context_pkg_path = ".workflow/active/WFS-{session}/.process/context-package.json"
|
||||
|
||||
# 1. Read existing package
|
||||
context_pkg = Read(context_pkg_path)
|
||||
|
||||
# 2. Update brainstorm_artifacts (role analyses now contain @ design references)
|
||||
brainstorm_dir = ".workflow/active/WFS-{session}/.brainstorming"
|
||||
role_analysis_files = Glob({brainstorm_dir}/*/analysis*.md)
|
||||
|
||||
context_pkg.brainstorm_artifacts.role_analyses = []
|
||||
FOR file IN role_analysis_files:
|
||||
role_name = extract_role_from_path(file)
|
||||
relative_path = file.replace({brainstorm_dir}/, "")
|
||||
|
||||
context_pkg.brainstorm_artifacts.role_analyses.push({
|
||||
"role": role_name,
|
||||
"files": [{
|
||||
"path": relative_path,
|
||||
"type": "primary",
|
||||
"content": Read(file), # Contains @ design system references
|
||||
"updated_at": NOW()
|
||||
}]
|
||||
})
|
||||
|
||||
# 3. Add design_system_references field
|
||||
context_pkg.design_system_references = {
|
||||
"design_run_id": design_id,
|
||||
"tokens": `${design_id}/${design_tokens_path}`,
|
||||
"style_guide": `${design_id}/${style_guide_path}`,
|
||||
"prototypes": selected_list.map(p => `${design_id}/prototypes/${p}.html`),
|
||||
"updated_at": NOW()
|
||||
}
|
||||
|
||||
# 4. Optional: Add animations and layouts if they exist
|
||||
IF exists({latest_design}/animation-extraction/animation-tokens.json):
|
||||
context_pkg.design_system_references.animations = `${design_id}/animation-extraction/animation-tokens.json`
|
||||
|
||||
IF exists({latest_design}/layout-extraction/layout-templates.json):
|
||||
context_pkg.design_system_references.layouts = `${design_id}/layout-extraction/layout-templates.json`
|
||||
|
||||
# 5. Update metadata
|
||||
context_pkg.metadata.updated_at = NOW()
|
||||
context_pkg.metadata.design_sync_timestamp = NOW()
|
||||
|
||||
# 6. Write back
|
||||
Write(context_pkg_path, JSON.stringify(context_pkg, indent=2))
|
||||
|
||||
REPORT: "✅ Updated context-package.json with design system references"
|
||||
```
|
||||
|
||||
**TodoWrite Update**:
|
||||
```json
|
||||
{"content": "Update context package with design references", "status": "completed", "activeForm": "Updating context package"}
|
||||
```
|
||||
|
||||
### Phase 6: Completion
|
||||
|
||||
```javascript
|
||||
TodoWrite({todos: [
|
||||
|
||||
@@ -24,8 +24,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
|
||||
- **IF should_extract_animation**: **Attach tasks → Execute → Collapse** → Auto-continues to Phase 9
|
||||
- **ELSE**: Skip (use code import) → Auto-continues to Phase 9
|
||||
5. Phase 9 (layout-extract) → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 10
|
||||
6. **Phase 10 (ui-assembly)** → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 11
|
||||
7. **Phase 11 (preview-generation)** → **Execute script → Generate preview files** → Reports completion
|
||||
6. **Phase 10 (ui-assembly)** → **Attach tasks → Execute → Collapse** → Workflow complete
|
||||
|
||||
**Phase Transition Mechanism**:
|
||||
- **Phase 5 (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 7
|
||||
@@ -33,10 +32,9 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
|
||||
- **Task Execution**: Orchestrator **EXECUTES** these attached tasks itself
|
||||
- **Task Collapse**: After tasks complete, collapse them into phase summary
|
||||
- **Phase Transition**: Automatically execute next phase after collapsing
|
||||
- **Phase 11 (Script Execution)**: Execute preview generation script
|
||||
- No additional user interaction after Phase 5 confirmation
|
||||
|
||||
**Auto-Continue Mechanism**: TodoWrite tracks phase status with dynamic task attachment/collapse. After executing all attached tasks, you MUST immediately collapse them, restore phase summary, and execute the next phase. No user intervention required. The workflow is NOT complete until reaching Phase 11 (preview generation).
|
||||
**Auto-Continue Mechanism**: TodoWrite tracks phase status with dynamic task attachment/collapse. After executing all attached tasks, you MUST immediately collapse them, restore phase summary, and execute the next phase. No user intervention required. The workflow is NOT complete until Phase 10 (UI assembly) finishes.
|
||||
|
||||
**Task Attachment Model**: SlashCommand invocation is NOT delegation - it's task expansion. The orchestrator executes these attached tasks itself, not waiting for external completion.
|
||||
|
||||
@@ -50,7 +48,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
|
||||
4. **Default to All**: When selecting variants/prototypes, use ALL generated items
|
||||
5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
|
||||
6. **⚠️ CRITICAL: Task Attachment Model** - SlashCommand invocation **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these attached tasks itself, not waiting for external completion. This is NOT delegation - it's task expansion.
|
||||
7. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After executing all attached tasks, you MUST immediately collapse them and execute the next phase. Workflow is NOT complete until Phase 11 (preview generation).
|
||||
7. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After executing all attached tasks, you MUST immediately collapse them and execute the next phase. Workflow is NOT complete until Phase 10 (UI assembly) finishes.
|
||||
|
||||
## Parameter Requirements
|
||||
|
||||
@@ -127,140 +125,78 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
|
||||
**Integrated vs. Standalone**:
|
||||
- `--session` flag determines session integration or standalone execution
|
||||
|
||||
## 11-Phase Execution
|
||||
## 10-Phase Execution
|
||||
|
||||
### Phase 1: Parameter Parsing & Input Detection
|
||||
|
||||
**Unified Principle**: Detect → Classify → Store (avoid string concatenation and escaping)
|
||||
|
||||
**Step 1: Parameter Normalization**
|
||||
```bash
|
||||
# Step 0: Parse and normalize parameters
|
||||
images_input = null
|
||||
prompt_text = null
|
||||
|
||||
# Handle legacy parameters with deprecation warning
|
||||
# Legacy parameters (deprecated)
|
||||
IF --images OR --prompt:
|
||||
WARN: "⚠️ DEPRECATION: --images and --prompt are deprecated. Use --input instead."
|
||||
WARN: " Example: --input \"design-refs/*\" or --input \"modern dashboard\""
|
||||
images_input = --images
|
||||
prompt_text = --prompt
|
||||
WARN: "⚠️ --images/--prompt deprecated. Use --input"
|
||||
images_input = --images; prompt_text = --prompt
|
||||
|
||||
# Parse unified --input parameter
|
||||
IF --input:
|
||||
# Split by | separator for multiple inputs
|
||||
input_parts = split(--input, "|")
|
||||
|
||||
FOR part IN input_parts:
|
||||
part = trim(part)
|
||||
|
||||
# Detection logic
|
||||
IF contains(part, "*") OR glob_matches_files(part):
|
||||
# Glob pattern detected → images
|
||||
images_input = part
|
||||
ELSE IF file_or_directory_exists(part):
|
||||
# File/directory path → will be handled in code detection
|
||||
IF NOT prompt_text:
|
||||
prompt_text = part
|
||||
ELSE:
|
||||
prompt_text = prompt_text + " " + part
|
||||
ELSE:
|
||||
# Pure text → prompt
|
||||
IF NOT prompt_text:
|
||||
prompt_text = part
|
||||
ELSE:
|
||||
prompt_text = prompt_text + " " + part
|
||||
|
||||
# Step 1: Detect design source from parsed inputs
|
||||
code_files_detected = false
|
||||
code_base_path = null
|
||||
has_visual_input = false
|
||||
|
||||
IF prompt_text:
|
||||
# Extract potential file paths from prompt
|
||||
potential_paths = extract_paths_from_text(prompt_text)
|
||||
FOR path IN potential_paths:
|
||||
IF file_or_directory_exists(path):
|
||||
code_files_detected = true
|
||||
code_base_path = path
|
||||
BREAK
|
||||
|
||||
IF images_input:
|
||||
# Check if images parameter points to existing files
|
||||
IF glob_matches_files(images_input):
|
||||
has_visual_input = true
|
||||
|
||||
# Step 2: Determine design source strategy
|
||||
design_source = "unknown"
|
||||
IF code_files_detected AND has_visual_input:
|
||||
design_source = "hybrid" # Both code and visual
|
||||
ELSE IF code_files_detected:
|
||||
design_source = "code_only" # Only code files
|
||||
ELSE IF has_visual_input OR --prompt:
|
||||
design_source = "visual_only" # Only visual/prompt
|
||||
ELSE:
|
||||
ERROR: "No design source provided (code files, images, or prompt required)"
|
||||
EXIT 1
|
||||
|
||||
STORE: design_source, code_base_path, has_visual_input
|
||||
# Unified --input (split by "|")
|
||||
ELSE IF --input:
|
||||
FOR part IN split(--input, "|"):
|
||||
IF "*" IN part OR glob_exists(part): images_input = part
|
||||
ELSE IF path_exists(part): prompt_text += part
|
||||
ELSE: prompt_text += part
|
||||
```
|
||||
|
||||
**Step 2: Design Source Detection**
|
||||
```bash
|
||||
code_base_path = extract_first_valid_path(prompt_text)
|
||||
has_visual_input = (images_input AND glob_exists(images_input))
|
||||
|
||||
design_source = classify_source(code_base_path, has_visual_input):
|
||||
• code + visual → "hybrid"
|
||||
• code only → "code_only"
|
||||
• visual/prompt → "visual_only"
|
||||
• none → ERROR
|
||||
```
|
||||
|
||||
**Stored Variables**: `design_source`, `code_base_path`, `has_visual_input`, `images_input`, `prompt_text`
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Intelligent Prompt Parsing
|
||||
|
||||
**Unified Principle**: explicit > inferred > default
|
||||
|
||||
```bash
|
||||
# Parse variant counts from prompt or use explicit/default values
|
||||
IF prompt_text AND (NOT --style-variants OR NOT --layout-variants):
|
||||
style_variants = regex_extract(prompt_text, r"(\d+)\s*style") OR --style-variants OR 3
|
||||
layout_variants = regex_extract(prompt_text, r"(\d+)\s*layout") OR --layout-variants OR 3
|
||||
ELSE:
|
||||
style_variants = --style-variants OR 3
|
||||
layout_variants = --layout-variants OR 3
|
||||
# Variant counts (priority chain)
|
||||
style_variants = --style-variants OR extract_number(prompt_text, "style") OR 3
|
||||
layout_variants = --layout-variants OR extract_number(prompt_text, "layout") OR 3
|
||||
|
||||
VALIDATE: 1 <= style_variants <= 5, 1 <= layout_variants <= 5
|
||||
|
||||
# Interactive mode (always enabled)
|
||||
interactive_mode = true # Always use interactive mode
|
||||
VALIDATE: 1 ≤ variants ≤ 5
|
||||
```
|
||||
|
||||
**Stored Variables**: `style_variants`, `layout_variants`
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Device Type Inference
|
||||
|
||||
**Unified Principle**: explicit > prompt keywords > target_type > default
|
||||
|
||||
```bash
|
||||
# Device type inference
|
||||
device_type = "auto"
|
||||
# Device type (priority chain)
|
||||
device_type = --device-type (if != "auto")
|
||||
OR detect_keywords(prompt_text, ["mobile", "desktop", "tablet", "responsive"])
|
||||
OR infer_from_target(target_type) # component→desktop, page→responsive
|
||||
OR "responsive"
|
||||
|
||||
# Step 1: Explicit parameter (highest priority)
|
||||
IF --device-type AND --device-type != "auto":
|
||||
device_type = --device-type
|
||||
device_source = "explicit"
|
||||
ELSE:
|
||||
# Step 2: Prompt analysis
|
||||
IF prompt_text:
|
||||
device_keywords = {
|
||||
"desktop": ["desktop", "web", "laptop", "widescreen", "large screen"],
|
||||
"mobile": ["mobile", "phone", "smartphone", "ios", "android"],
|
||||
"tablet": ["tablet", "ipad", "medium screen"],
|
||||
"responsive": ["responsive", "adaptive", "multi-device", "cross-platform"]
|
||||
}
|
||||
detected_device = detect_device_from_prompt(prompt_text, device_keywords)
|
||||
IF detected_device:
|
||||
device_type = detected_device
|
||||
device_source = "prompt_inference"
|
||||
|
||||
# Step 3: Target type inference
|
||||
IF device_type == "auto":
|
||||
# Components are typically desktop-first, pages can vary
|
||||
device_type = target_type == "component" ? "desktop" : "responsive"
|
||||
device_source = "target_type_inference"
|
||||
|
||||
STORE: device_type, device_source
|
||||
device_source = track_detection_source()
|
||||
```
|
||||
|
||||
**Device Type Presets**:
|
||||
- **Desktop**: 1920×1080px - Mouse-driven, spacious layouts
|
||||
- **Mobile**: 375×812px - Touch-friendly, compact layouts
|
||||
- **Tablet**: 768×1024px - Hybrid touch/mouse layouts
|
||||
- **Responsive**: 1920×1080px base with mobile-first breakpoints
|
||||
**Detection Keywords**: mobile, phone, smartphone → mobile | desktop, web, laptop → desktop | tablet, ipad → tablet | responsive, adaptive → responsive
|
||||
|
||||
**Detection Keywords**:
|
||||
- Prompt contains "mobile", "phone", "smartphone" → mobile
|
||||
- Prompt contains "tablet", "ipad" → tablet
|
||||
- Prompt contains "desktop", "web", "laptop" → desktop
|
||||
- Prompt contains "responsive", "adaptive" → responsive
|
||||
- Otherwise: Inferred from target type (components→desktop, pages→responsive)
|
||||
**Device Presets**: Desktop (1920×1080) | Mobile (375×812) | Tablet (768×1024) | Responsive (1920×1080 + breakpoints)
|
||||
|
||||
**Stored Variables**: `device_type`, `device_source`
|
||||
|
||||
### Phase 4: Run Initialization & Directory Setup
|
||||
```bash
|
||||
@@ -466,13 +402,13 @@ IF design_source IN ["code_only", "hybrid"]:
|
||||
|
||||
# Animation reuse confirmation (code import with complete animations)
|
||||
IF design_source == "code_only" AND animation_complete:
|
||||
REPORT: "✅ 检测到完整的动画系统（来自代码导入）"
|
||||
REPORT: "✅ Complete animation system detected (from code import)"
|
||||
REPORT: " Duration scales: {duration_count} | Easing functions: {easing_count}"
|
||||
REPORT: ""
|
||||
REPORT: "Options:"
|
||||
REPORT: " • 'reuse' (默认) - 复用已有动画系统"
|
||||
REPORT: " • 'regenerate' - 重新生成动画系统（交互式）"
|
||||
REPORT: " • 'cancel' - 取消工作流"
|
||||
REPORT: " • 'reuse' (default) - Reuse existing animation system"
|
||||
REPORT: " • 'regenerate' - Regenerate animation system (interactive)"
|
||||
REPORT: " • 'cancel' - Cancel workflow"
|
||||
user_response = WAIT_FOR_USER_INPUT()
|
||||
MATCH user_response:
|
||||
"reuse" → skip_animation_extraction = true
|
||||
@@ -580,63 +516,22 @@ REPORT: " → Assembly tasks: {total} combinations"
|
||||
SlashCommand(command)
|
||||
|
||||
# After executing all attached tasks, collapse them into phase summary
|
||||
# When phase finishes, IMMEDIATELY execute Phase 11 (auto-continue)
|
||||
# Output:
|
||||
# Workflow complete - generate command handles preview file generation (compare.html, PREVIEW.md)
|
||||
# Output (generated by generate command):
|
||||
# - {target}-style-{s}-layout-{l}.html (assembled prototypes)
|
||||
# - {target}-style-{s}-layout-{l}.css
|
||||
# Note: compare.html and PREVIEW.md will be generated in Phase 11
|
||||
```
|
||||
|
||||
### Phase 11: Generate Preview Files
|
||||
```bash
|
||||
REPORT: "🚀 Phase 11: Generate Preview Files"
|
||||
|
||||
# Update TodoWrite to reflect preview generation phase
|
||||
TodoWrite({todos: [
|
||||
{"content": "Execute style extraction", "status": "completed", "activeForm": "Executing style extraction"},
|
||||
{"content": "Execute animation extraction", "status": "completed", "activeForm": "Executing animation extraction"},
|
||||
{"content": "Execute layout extraction", "status": "completed", "activeForm": "Executing layout extraction"},
|
||||
{"content": "Execute UI assembly", "status": "completed", "activeForm": "Executing UI assembly"},
|
||||
{"content": "Generate preview files", "status": "in_progress", "activeForm": "Generating preview files"}
|
||||
]})
|
||||
|
||||
# Execute preview generation script
|
||||
Bash(~/.claude/scripts/ui-generate-preview.sh "${base_path}/prototypes")
|
||||
|
||||
# Verify output files
|
||||
IF NOT exists("${base_path}/prototypes/compare.html"):
|
||||
ERROR: "Preview generation failed: compare.html not found"
|
||||
EXIT 1
|
||||
|
||||
IF NOT exists("${base_path}/prototypes/PREVIEW.md"):
|
||||
ERROR: "Preview generation failed: PREVIEW.md not found"
|
||||
EXIT 1
|
||||
|
||||
# Mark preview generation as complete
|
||||
TodoWrite({todos: [
|
||||
{"content": "Execute style extraction", "status": "completed", "activeForm": "Executing style extraction"},
|
||||
{"content": "Execute animation extraction", "status": "completed", "activeForm": "Executing animation extraction"},
|
||||
{"content": "Execute layout extraction", "status": "completed", "activeForm": "Executing layout extraction"},
|
||||
{"content": "Execute UI assembly", "status": "completed", "activeForm": "Executing UI assembly"},
|
||||
{"content": "Generate preview files", "status": "completed", "activeForm": "Generating preview files"}
|
||||
]})
|
||||
|
||||
REPORT: "✅ Preview files generated successfully"
|
||||
REPORT: " → compare.html (interactive matrix view)"
|
||||
REPORT: " → PREVIEW.md (usage instructions)"
|
||||
|
||||
# Workflow complete, display final report
|
||||
# - compare.html (interactive matrix view)
|
||||
# - PREVIEW.md (usage instructions)
|
||||
```
|
||||
|
||||
## TodoWrite Pattern
|
||||
```javascript
|
||||
// Initialize IMMEDIATELY after Phase 5 user confirmation to track multi-phase execution (5 orchestrator-level tasks)
|
||||
// Initialize IMMEDIATELY after Phase 5 user confirmation to track multi-phase execution (4 orchestrator-level tasks)
|
||||
TodoWrite({todos: [
|
||||
{"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing style extraction"},
|
||||
{"content": "Execute animation extraction", "status": "pending", "activeForm": "Executing animation extraction"},
|
||||
{"content": "Execute layout extraction", "status": "pending", "activeForm": "Executing layout extraction"},
|
||||
{"content": "Execute UI assembly", "status": "pending", "activeForm": "Executing UI assembly"},
|
||||
{"content": "Generate preview files", "status": "pending", "activeForm": "Generating preview files"}
|
||||
{"content": "Execute UI assembly", "status": "pending", "activeForm": "Executing UI assembly"}
|
||||
]})
|
||||
|
||||
// ⚠️ CRITICAL: Dynamic TodoWrite task attachment strategy:
|
||||
@@ -651,19 +546,8 @@ TodoWrite({todos: [
|
||||
// 4. After all attached tasks complete, COLLAPSE them into phase summary
|
||||
// 5. Update next phase to in_progress
|
||||
// 6. IMMEDIATELY execute next phase (auto-continue)
|
||||
// 7. After Phase 10 completes, workflow finishes (generate command handles preview files)
|
||||
//
|
||||
// Phase 11 Script Execution Pattern:
|
||||
// 1. Mark "Generate preview files" as in_progress
|
||||
// 2. Execute preview generation script via Bash tool
|
||||
// 3. Verify output files (compare.html, PREVIEW.md)
|
||||
// 4. Mark "Generate preview files" as completed
|
||||
//
|
||||
// Benefits:
|
||||
// ✓ Real-time visibility into sub-command task progress
|
||||
// ✓ Clean orchestrator-level summary after each phase
|
||||
// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
|
||||
// ✓ Script execution for preview generation (no delegation)
|
||||
// ✓ Dynamic attachment/collapse maintains clarity
|
||||
```
|
||||
|
||||
## Completion Output
|
||||
@@ -682,7 +566,7 @@ Phase 9: {n×l} layout templates (layout-extract with multi-select)
|
||||
Phase 10: UI Assembly (generate)
|
||||
- Pure assembly: layout templates + design tokens
|
||||
- {s}×{l}×{n} = {total} final prototypes
|
||||
Phase 11: Preview files generated (compare.html, PREVIEW.md)
|
||||
- Preview files: compare.html, PREVIEW.md (auto-generated by generate command)
|
||||
|
||||
Assembly Process:
|
||||
✅ Separation of Concerns: Layout (structure) + Style (tokens) kept separate
|
||||
|
||||
@@ -591,11 +591,6 @@ TodoWrite({todos: [
|
||||
// 5. Update next phase to in_progress
|
||||
// 6. IMMEDIATELY execute next phase SlashCommand (auto-continue)
|
||||
//
|
||||
// Benefits:
|
||||
// ✓ Real-time visibility into sub-command task progress
|
||||
// ✓ Clean orchestrator-level summary after each phase
|
||||
// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
|
||||
// ✓ Dynamic attachment/collapse maintains clarity
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: layout-extract
|
||||
description: Extract structural layout information from reference images, URLs, or text prompts using Claude analysis with variant generation or refinement mode
|
||||
argument-hint: [--design-id <id>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--targets "<list>"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]
|
||||
description: Extract structural layout information from reference images or text prompts using Claude analysis with variant generation or refinement mode
|
||||
argument-hint: [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--targets "<list>"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), AskUserQuestion(*), Task(ui-design-agent), mcp__exa__web_search_exa(*)
|
||||
---
|
||||
|
||||
@@ -9,7 +9,7 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), AskUserQuestio
|
||||
|
||||
## Overview
|
||||
|
||||
Extract structural layout information from reference images, URLs, or text prompts using AI analysis. Supports two modes:
|
||||
Extract structural layout information from reference images or text prompts using AI analysis. Supports two modes:
|
||||
1. **Exploration Mode** (default): Generate multiple contrasting layout variants
|
||||
2. **Refinement Mode** (`--refine`): Refine a single existing layout through detailed adjustments
|
||||
|
||||
@@ -29,23 +29,7 @@ This command separates the "scaffolding" (HTML structure and CSS layout) from th
|
||||
|
||||
```bash
|
||||
# Detect input source
|
||||
# Priority: --urls + --images → hybrid | --urls → url | --images → image | --prompt → text
|
||||
|
||||
# Parse URLs if provided (format: "target:url,target:url,...")
|
||||
IF --urls:
|
||||
url_list = []
|
||||
FOR pair IN split(--urls, ","):
|
||||
IF ":" IN pair:
|
||||
target, url = pair.split(":", 1)
|
||||
url_list.append({target: target.strip(), url: url.strip()})
|
||||
ELSE:
|
||||
# Single URL without target
|
||||
url_list.append({target: "page", url: pair.strip()})
|
||||
|
||||
has_urls = true
|
||||
ELSE:
|
||||
has_urls = false
|
||||
url_list = []
|
||||
# Priority: --images → image | --prompt → text
|
||||
|
||||
# Detect refinement mode
|
||||
refine_mode = --refine OR false
|
||||
@@ -62,11 +46,9 @@ ELSE:
|
||||
REPORT: "🔍 Exploration mode: Will generate {variants_count} contrasting layout concepts per target"
|
||||
|
||||
# Resolve targets
|
||||
# Priority: --targets → url_list targets → prompt analysis → default ["page"]
|
||||
# Priority: --targets → prompt analysis → default ["page"]
|
||||
IF --targets:
|
||||
targets = split(--targets, ",")
|
||||
ELSE IF has_urls:
|
||||
targets = [url_info.target for url_info in url_list]
|
||||
ELSE IF --prompt:
|
||||
# Extract targets from prompt using pattern matching
|
||||
# Looks for keywords: "page names", target descriptors (login, dashboard, etc.)
|
||||
@@ -107,10 +89,6 @@ bash(echo "✓ Base path: $base_path")
|
||||
bash(ls {images_pattern}) # Expand glob pattern
|
||||
Read({image_path}) # Load each image
|
||||
|
||||
# For URL mode
|
||||
# Parse URL list format: "target:url,target:url"
|
||||
# Validate URLs are accessible
|
||||
|
||||
# For text mode
|
||||
# Validate --prompt is non-empty
|
||||
|
||||
@@ -118,97 +96,6 @@ Read({image_path}) # Load each image
|
||||
bash(mkdir -p {base_path}/layout-extraction)
|
||||
```
|
||||
|
||||
### Step 2.5: Extract DOM Structure (URL Mode - Auto-Trigger)
|
||||
```bash
|
||||
# AUTO-TRIGGER: If URLs are available (from --urls parameter), automatically extract real DOM structure
|
||||
# This provides accurate layout data to supplement visual analysis
|
||||
|
||||
# Check if URLs provided via --urls parameter
|
||||
IF --urls AND url_list:
|
||||
REPORT: "🔍 Auto-triggering URL mode: Extracting DOM structure"
|
||||
|
||||
bash(mkdir -p {base_path}/.intermediates/layout-analysis)
|
||||
|
||||
# For each URL in url_list:
|
||||
FOR url_info IN url_list:
|
||||
target = url_info.target
|
||||
url = url_info.url
|
||||
|
||||
IF mcp_chrome_devtools_available:
|
||||
REPORT: " Processing: {target} ({url})"
|
||||
|
||||
# Read extraction script
|
||||
script_content = Read(~/.claude/scripts/extract-layout-structure.js)
|
||||
|
||||
# Open page in Chrome DevTools
|
||||
mcp__chrome-devtools__navigate_page(url=url)
|
||||
|
||||
# Execute layout extraction script
|
||||
result = mcp__chrome-devtools__evaluate_script(function=script_content)
|
||||
|
||||
# Save DOM structure for this target (intermediate file)
|
||||
Write({base_path}/.intermediates/layout-analysis/dom-structure-{target}.json, result)
|
||||
|
||||
REPORT: " ✅ DOM structure extracted for '{target}'"
|
||||
ELSE:
|
||||
REPORT: " ⚠️ Chrome DevTools MCP not available, falling back to visual analysis"
|
||||
BREAK
|
||||
|
||||
dom_structure_available = mcp_chrome_devtools_available
|
||||
ELSE:
|
||||
dom_structure_available = false
|
||||
```
|
||||
|
||||
**Extraction Script Reference**: `~/.claude/scripts/extract-layout-structure.js`
|
||||
|
||||
**Usage**: Read the script file and use content directly in `mcp__chrome-devtools__evaluate_script()`
|
||||
|
||||
**Script returns**:
|
||||
- `metadata`: Extraction timestamp, URL, method, version
|
||||
- `patterns`: Layout pattern statistics (flexColumn, flexRow, grid counts)
|
||||
- `structure`: Hierarchical DOM tree with layout properties
|
||||
- `exploration`: (Optional) Progressive exploration results when standard selectors fail
|
||||
|
||||
**Benefits**:
|
||||
- ✅ Real flex/grid configuration (justifyContent, alignItems, gap, etc.)
|
||||
- ✅ Accurate element bounds (x, y, width, height)
|
||||
- ✅ Structural hierarchy with depth control
|
||||
- ✅ Layout pattern identification (flex-row, flex-column, grid-NCol)
|
||||
- ✅ Progressive exploration: Auto-discovers missing selectors
|
||||
|
||||
**Progressive Exploration Strategy** (v2.2.0+):
|
||||
|
||||
When script finds <3 main containers, it automatically:
|
||||
1. **Scans** all large visible containers (≥500×300px)
|
||||
2. **Extracts** class patterns matching: `main|content|wrapper|container|page|layout|app`
|
||||
3. **Suggests** new selectors to add to script
|
||||
4. **Returns** exploration data in `result.exploration`:
|
||||
```json
|
||||
{
|
||||
"triggered": true,
|
||||
"discoveredCandidates": [{classes, bounds, display}],
|
||||
"suggestedSelectors": [".wrapper", ".page-index"],
|
||||
"recommendation": ".wrapper, .page-index, .app-container"
|
||||
}
|
||||
```
|
||||
|
||||
**Using Exploration Results**:
|
||||
```javascript
|
||||
// After extraction, check for suggestions
|
||||
IF result.exploration?.triggered:
|
||||
REPORT: result.exploration.warning
|
||||
REPORT: "Suggested selectors: " + result.exploration.recommendation
|
||||
|
||||
// Update script by adding to commonClassSelectors array
|
||||
// Then re-run extraction for better coverage
|
||||
```
|
||||
|
||||
**Selector Update Workflow**:
|
||||
1. Run extraction on unfamiliar site
|
||||
2. Check `result.exploration.suggestedSelectors`
|
||||
3. Add relevant selectors to script's `commonClassSelectors`
|
||||
4. Re-run extraction → improved container detection
|
||||
|
||||
### Step 3: Memory Check
|
||||
```bash
|
||||
# 1. Check if inputs cached in session memory
|
||||
@@ -711,13 +598,6 @@ Configuration:
|
||||
- Device Type: {device_type}
|
||||
- Targets: {targets.join(", ")}
|
||||
- Total Templates: {total_tasks} ({targets.length} targets with multi-selection)
|
||||
{IF has_urls AND dom_structure_available:
|
||||
- 🔍 URL Mode: DOM structure extracted from {len(url_list)} URL(s)
|
||||
- Accuracy: Real flex/grid properties from live pages
|
||||
}
|
||||
{IF has_urls AND NOT dom_structure_available:
|
||||
- ⚠️ URL Mode: Chrome DevTools unavailable, used visual analysis fallback
|
||||
}
|
||||
|
||||
User Selections:
|
||||
{FOR each target in targets:
|
||||
@@ -734,10 +614,7 @@ Generated Templates:
|
||||
|
||||
Intermediate Files:
|
||||
- {base_path}/.intermediates/layout-analysis/
|
||||
├── analysis-options.json (concept proposals + user selections embedded)
|
||||
{IF dom_structure_available:
|
||||
├── dom-structure-*.json ({len(url_list)} DOM extracts)
|
||||
}
|
||||
└── analysis-options.json (concept proposals + user selections embedded)
|
||||
|
||||
Next: /workflow:ui-design:generate will combine these structural templates with design systems to produce final prototypes.
|
||||
```
|
||||
@@ -867,15 +744,11 @@ ERROR: MCP search failed
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Auto-Trigger URL Mode** - Automatically extracts DOM structure when --urls provided (no manual flag needed)
|
||||
- **Hybrid Extraction Strategy** - Combines real DOM structure data with AI visual analysis
|
||||
- **Accurate Layout Properties** - Chrome DevTools extracts real flex/grid configurations, bounds, and hierarchy
|
||||
- **Separation of Concerns** - Decouples layout (structure) from style (visuals)
|
||||
- **Multi-Selection Workflow** - Generate N concepts → User selects multiple → Parallel template generation
|
||||
- **Structural Exploration** - Enables A/B testing of different layouts through multi-selection
|
||||
- **Token-Based Layout** - CSS uses `var()` placeholders for instant design system adaptation
|
||||
- **Device-Specific** - Tailored structures for different screen sizes
|
||||
- **Graceful Fallback** - Falls back to visual analysis if Chrome DevTools unavailable
|
||||
- **Foundation for Assembly** - Provides structural blueprint for prototype generation
|
||||
- **Agent-Powered** - Deep structural analysis with AI
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: style-extract
|
||||
description: Extract design style from reference images or text prompts using Claude analysis with variant generation or refinement mode
|
||||
argument-hint: "[--design-id <id>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--variants <count>] [--interactive] [--refine]"
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), AskUserQuestion(*), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__evaluate_script(*)
|
||||
argument-hint: "[--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--variants <count>] [--interactive] [--refine]"
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), AskUserQuestion(*)
|
||||
---
|
||||
|
||||
# Style Extraction Command
|
||||
@@ -24,23 +24,7 @@ Extract design style from reference images or text prompts using Claude's built-
|
||||
### Step 1: Detect Input Mode, Extraction Mode & Base Path
|
||||
```bash
|
||||
# Detect input source
|
||||
# Priority: --urls + --images + --prompt → hybrid-url | --urls + --images → url-image | --urls → url | --images + --prompt → hybrid | --images → image | --prompt → text
|
||||
|
||||
# Parse URLs if provided (format: "target:url,target:url,...")
|
||||
IF --urls:
|
||||
url_list = []
|
||||
FOR pair IN split(--urls, ","):
|
||||
IF ":" IN pair:
|
||||
target, url = pair.split(":", 1)
|
||||
url_list.append({target: target.strip(), url: url.strip()})
|
||||
ELSE:
|
||||
# Single URL without target
|
||||
url_list.append({target: "page", url: pair.strip()})
|
||||
|
||||
has_urls = true
|
||||
primary_url = url_list[0].url # First URL as primary source
|
||||
ELSE:
|
||||
has_urls = false
|
||||
# Priority: --images + --prompt → hybrid | --images → image | --prompt → text
|
||||
|
||||
# Detect refinement mode
|
||||
refine_mode = --refine OR false
|
||||
@@ -79,64 +63,7 @@ base_path=$(cd "$relative_path" && pwd)
|
||||
bash(echo "✓ Base path: $base_path")
|
||||
```
|
||||
|
||||
### Step 2: Extract Computed Styles (URL Mode - Auto-Trigger)
|
||||
```bash
|
||||
# AUTO-TRIGGER: If URLs are available (from --urls parameter or capture metadata), automatically extract real CSS values
|
||||
# This provides accurate design tokens to supplement visual analysis
|
||||
|
||||
# Priority 1: Check for --urls parameter
|
||||
IF has_urls:
|
||||
url_to_extract = primary_url
|
||||
url_source = "--urls parameter"
|
||||
|
||||
# Priority 2: Check for URL metadata from capture phase
|
||||
ELSE IF exists({base_path}/.metadata/capture-urls.json):
|
||||
capture_urls = Read({base_path}/.metadata/capture-urls.json)
|
||||
url_to_extract = capture_urls[0] # Use first URL
|
||||
url_source = "capture metadata"
|
||||
ELSE:
|
||||
url_to_extract = null
|
||||
|
||||
# Execute extraction if URL available
|
||||
IF url_to_extract AND mcp_chrome_devtools_available:
|
||||
REPORT: "🔍 Auto-triggering URL mode: Extracting computed styles from {url_source}"
|
||||
REPORT: " URL: {url_to_extract}"
|
||||
|
||||
# Read extraction script
|
||||
script_content = Read(~/.claude/scripts/extract-computed-styles.js)
|
||||
|
||||
# Open page in Chrome DevTools
|
||||
mcp__chrome-devtools__navigate_page(url=url_to_extract)
|
||||
|
||||
# Execute extraction script directly
|
||||
result = mcp__chrome-devtools__evaluate_script(function=script_content)
|
||||
|
||||
# Save computed styles to intermediates directory
|
||||
bash(mkdir -p {base_path}/.intermediates/style-analysis)
|
||||
Write({base_path}/.intermediates/style-analysis/computed-styles.json, result)
|
||||
|
||||
computed_styles_available = true
|
||||
REPORT: " ✅ Computed styles extracted and saved"
|
||||
ELSE:
|
||||
computed_styles_available = false
|
||||
IF url_to_extract:
|
||||
REPORT: "⚠️ Chrome DevTools MCP not available, falling back to visual analysis"
|
||||
```
|
||||
|
||||
**Extraction Script Reference**: `~/.claude/scripts/extract-computed-styles.js`
|
||||
|
||||
**Usage**: Read the script file and use content directly in `mcp__chrome-devtools__evaluate_script()`
|
||||
|
||||
**Script returns**:
|
||||
- `metadata`: Extraction timestamp, URL, method
|
||||
- `tokens`: Organized design tokens (colors, borderRadii, shadows, fontSizes, fontWeights, spacing)
|
||||
|
||||
**Benefits**:
|
||||
- ✅ Pixel-perfect accuracy for border-radius, box-shadow, padding, etc.
|
||||
- ✅ Eliminates guessing from visual analysis
|
||||
- ✅ Provides ground truth for design tokens
|
||||
|
||||
### Step 3: Load Inputs
|
||||
### Step 2: Load Inputs
|
||||
```bash
|
||||
# For image mode
|
||||
bash(ls {images_pattern}) # Expand glob pattern
|
||||
@@ -161,7 +88,7 @@ IF exists: SKIP to completion
|
||||
|
||||
---
|
||||
|
||||
**Phase 0 Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `loaded_images[]` or `prompt_guidance`, `has_urls`, `url_list[]`, `computed_styles_available`
|
||||
**Phase 0 Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `loaded_images[]` or `prompt_guidance`
|
||||
|
||||
## Phase 1: Design Direction or Refinement Options Generation
|
||||
|
||||
@@ -571,9 +498,8 @@ FOR variant_index IN 1..actual_variants_count:
|
||||
- Preview Border Radius: ${selected_direction.preview.border_radius_base}
|
||||
|
||||
## Input Analysis
|
||||
- Input mode: {input_mode} (image/text/hybrid${has_urls ? "/url" : ""})
|
||||
- Input mode: {input_mode} (image/text/hybrid)
|
||||
- Visual references: {loaded_images OR prompt_guidance}
|
||||
${computed_styles_available ? "- Computed styles: Use as ground truth (Read from .intermediates/style-analysis/computed-styles.json)" : ""}
|
||||
|
||||
## Generation Rules
|
||||
- Develop the selected design direction into a complete design system
|
||||
@@ -587,7 +513,7 @@ FOR variant_index IN 1..actual_variants_count:
|
||||
* innovation → token naming, experimental values
|
||||
- Honor search_keywords for design inspiration
|
||||
- Avoid anti_keywords patterns
|
||||
- All colors in OKLCH format ${computed_styles_available ? "(convert from computed RGB)" : ""}
|
||||
- All colors in OKLCH format
|
||||
- WCAG AA compliance: 4.5:1 text contrast, 3:1 UI contrast
|
||||
|
||||
## Generate
|
||||
@@ -656,16 +582,9 @@ TodoWrite({todos: [
|
||||
Configuration:
|
||||
- Session: {session_id}
|
||||
- Extraction Mode: {extraction_mode} (imitate/explore)
|
||||
- Input Mode: {input_mode} (image/text/hybrid{"/url" if has_urls else ""})
|
||||
- Input Mode: {input_mode} (image/text/hybrid)
|
||||
- Variants: {variants_count}
|
||||
- Production-Ready: Complete design systems generated
|
||||
{IF has_urls AND computed_styles_available:
|
||||
- 🔍 URL Mode: Computed styles extracted from {len(url_list)} URL(s)
|
||||
- Accuracy: Pixel-perfect design tokens from DOM
|
||||
}
|
||||
{IF has_urls AND NOT computed_styles_available:
|
||||
- ⚠️ URL Mode: Chrome DevTools unavailable, used visual analysis fallback
|
||||
}
|
||||
|
||||
{IF extraction_mode == "explore":
|
||||
Design Direction Selection:
|
||||
@@ -676,11 +595,6 @@ Design Direction Selection:
|
||||
Generated Files:
|
||||
{base_path}/style-extraction/
|
||||
└── style-1/design-tokens.json
|
||||
|
||||
{IF computed_styles_available:
|
||||
Intermediate Analysis:
|
||||
{base_path}/.intermediates/style-analysis/computed-styles.json (extracted from {primary_url})
|
||||
}
|
||||
{IF extraction_mode == "explore":
|
||||
{base_path}/.intermediates/style-analysis/analysis-options.json (design direction options + user selection)
|
||||
}
|
||||
@@ -811,15 +725,11 @@ ERROR: Claude JSON parsing error
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Auto-Trigger URL Mode** - Automatically extracts computed styles when --urls provided (no manual flag needed)
|
||||
- **Direct Design System Generation** - Complete design-tokens.json + style-guide.md in one step
|
||||
- **Hybrid Extraction Strategy** - Combines computed CSS values (ground truth) with AI visual analysis
|
||||
- **Pixel-Perfect Accuracy** - Chrome DevTools extracts exact border-radius, shadows, spacing values
|
||||
- **AI-Driven Design Space Exploration** - 6D attribute space analysis for maximum contrast
|
||||
- **Variant-Specific Directions** - Each variant has unique philosophy, keywords, anti-patterns
|
||||
- **Maximum Contrast Guarantee** - Variants maximally distant in attribute space
|
||||
- **Flexible Input** - Images, text, URLs, or hybrid mode
|
||||
- **Graceful Fallback** - Falls back to pure visual inference if Chrome DevTools unavailable
|
||||
- **Flexible Input** - Images, text, or hybrid mode
|
||||
- **Production-Ready** - OKLCH colors, WCAG AA compliance, semantic naming
|
||||
- **Agent-Driven** - Autonomous multi-file generation with ui-design-agent
|
||||
|
||||
|
||||
Reference in New Issue
Block a user