catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-11 02:33:51 +08:00
Code Issues Packages Projects Releases Wiki Activity

Refactor workflow plan command and architecture documentation

Browse Source 
- Simplified argument hints and examples in plan.md
- Enhanced input detection logic for files, issues, and text
- Introduced analysis levels for improved context analysis
- Updated core rules for task limits and decomposition strategies
- Improved session management with active session marker system
- Expanded file structure reference and naming conventions
- Clarified task hierarchy and status rules
- Added detailed validation and error handling procedures
- Streamlined document templates for implementation plans and task summaries
This commit is contained in:
catlog22
2025-09-15 22:11:31 +08:00
parent 9371af8d8d
commit 6570af264d
3 changed files with 515 additions and 733 deletions
Download Patch File Download Diff File Expand all files Collapse all files

353
.claude/commands/workflow/execute.md
View File

@@ -7,69 +7,46 @@ examples:
- /workflow:execute
---
# Workflow Execute Command (/workflow:execute)
# Workflow Execute Command
## Overview
Coordinates multiple agents for executing existing workflow tasks through automatic discovery and intelligent task orchestration. Analyzes workflow folders, checks task statuses, and coordinates agent execution based on discovered plans.
## Core Principles
Coordinates agents for executing workflow tasks through automatic discovery and orchestration. Discovers plans, checks statuses, and executes ready tasks with complete context.
## Execution Philosophy
- **Discovery-first**: Auto-discover existing plans and tasks
- **Status-aware**: Execute only ready tasks
- **Context-rich**: Use complete task JSON data for agents
- **Progress tracking**: Update status after completion
The intelligent execution approach focuses on:
- **Discovery-first execution** - Automatically discover existing plans and tasks
- **Status-aware coordination** - Execute only tasks that are ready
- **Context-rich agent assignment** - Use complete task JSON data for agent context
- **Dynamic task orchestration** - Coordinate based on discovered task relationships
- **Progress tracking** - Update task status after agent completion
**Flow Control Execution**:
- **[FLOW_CONTROL]**: Indicates sequential flow control execution required
- **Auto-trigger**: When task.flow_control.pre_analysis is an array (default format)
- **Agent Action**: Execute flow control steps sequentially BEFORE implementation begins
- Process each step with command execution and context accumulation
- Load dependency summaries and parent task context
- Execute CLI tools, scripts, and agent commands as specified
- Pass context between steps via named variables
- Handle errors according to per-step error strategies
**Flow Control Step Processing**:
- **Sequential Execution**: Steps processed in order with context flow
- Each step can use outputs from previous steps via ${variable_name}
- Dependency summaries loaded automatically from .summaries/
- Context accumulates through the execution chain
- Error handling per step (skip_optional, fail, retry_once, manual_intervention)
## Flow Control Execution
**[FLOW_CONTROL]** marker indicates sequential step execution required:
- **Auto-trigger**: When `task.flow_control.pre_analysis` exists
- **Process**: Execute steps sequentially BEFORE implementation
- Load dependency summaries and parent context
- Execute CLI tools, scripts, and commands as specified
- Pass context between steps via `${variable_name}`
- Handle errors per step strategy
## Execution Flow
### 1. Discovery & Analysis Phase
### 1. Discovery Phase
```
Workflow Discovery:
├── Locate workflow folder (provided or current session)
├── Load workflow-session.json for session state
├── Scan .task/ directory for all task JSON files
├── Read IMPL_PLAN.md for workflow context
├── Locate workflow folder (current session)
├── Load workflow-session.json and IMPL_PLAN.md
├── Scan .task/ directory for task JSON files
├── Analyze task statuses and dependencies
└── Determine executable tasks
└── Build execution queue of ready tasks
```
**Discovery Logic:**
- **Folder Detection**: Use provided folder or find current active session
- **Task Inventory**: Load all IMPL-*.json files from .task/ directory
- **Status Analysis**: Check pending/active/completed/blocked states
- **Dependency Check**: Verify all task dependencies are met
- **Execution Queue**: Build list of ready-to-execute tasks
### 2. TodoWrite Coordination Setup
**Always First**: Create comprehensive TodoWrite based on discovered tasks
### 2. TodoWrite Coordination
Create comprehensive TodoWrite based on discovered tasks:
```markdown
# Workflow Execute Coordination
*Session: WFS-[topic-slug]*
## Execution Plan
- [ ] **TASK-001**: [Agent: planning-agent] [FLOW_CONTROL] Design auth schema (IMPL-1.1)
- [ ] **TASK-002**: [Agent: code-developer] [FLOW_CONTROL] Implement auth logic (IMPL-1.2)
- [ ] **TASK-001**: [Agent: code-developer] [FLOW_CONTROL] Design auth schema (IMPL-1.1)
- [ ] **TASK-002**: [Agent: code-developer] [FLOW_CONTROL] Implement auth logic (IMPL-1.2)
- [ ] **TASK-003**: [Agent: code-review-agent] Review implementations
- [ ] **TASK-004**: Update task statuses and session state
@@ -78,84 +55,45 @@ Workflow Discovery:
```
### 3. Agent Context Assignment
For each executable task:
**Task JSON Structure**:
```json
{
"task": {
"id": "IMPL-1.1",
"title": "Design auth schema",
"status": "pending",
"meta": {
"type": "feature",
"agent": "code-developer"
},
"context": {
"requirements": ["JWT authentication", "User model design"],
"focus_paths": ["src/auth/models", "tests/auth"],
"acceptance": ["Schema validates JWT tokens"],
"parent": "IMPL-1",
"depends_on": [],
"inherited": {
"from": "IMPL-1",
"context": ["Authentication system architecture completed"]
},
"shared_context": {
"auth_strategy": "JWT with refresh tokens"
}
},
"flow_control": {
"pre_analysis": [
{
"step": "gather_context",
"action": "Load dependency summaries",
"command": "bash(echo 'No dependencies for this initial task')",
"output_to": "dependency_context",
"on_error": "skip_optional"
},
{
"step": "analyze_patterns",
"action": "Analyze existing auth patterns",
"command": "bash(~/.claude/scripts/gemini-wrapper -p '@{src/auth/**/*} analyze authentication patterns with context: [dependency_context]')",
"output_to": "pattern_analysis",
"on_error": "fail"
},
{
"step": "implement",
"action": "Design JWT schema based on analysis",
"command": "bash(codex --full-auto exec 'Design JWT schema using analysis: [pattern_analysis] and context: [dependency_context]')",
"on_error": "manual_intervention"
}
],
"implementation_approach": "Design flexible user schema supporting JWT and OAuth authentication",
"target_files": [
"src/auth/models/User.ts:UserSchema:10-50"
]
}
"id": "IMPL-1.1",
"title": "Design auth schema",
"status": "pending",
"meta": { "type": "feature", "agent": "code-developer" },
"context": {
"requirements": ["JWT authentication", "User model design"],
"focus_paths": ["src/auth/models", "tests/auth"],
"acceptance": ["Schema validates JWT tokens"],
"depends_on": [],
"inherited": { "from": "IMPL-1", "context": ["..."] }
},
"workflow": {
"session": "WFS-user-auth",
"phase": "IMPLEMENT",
"plan_context": "Authentication system with OAuth2 support"
"flow_control": {
"pre_analysis": [
{
"step": "analyze_patterns",
"action": "Analyze existing auth patterns",
"command": "~/.claude/scripts/gemini-wrapper -p '@{src/auth/**/*} analyze patterns'",
"output_to": "pattern_analysis",
"on_error": "fail"
}
],
"implementation_approach": "Design flexible user schema",
"target_files": ["src/auth/models/User.ts:UserSchema:10-50"]
}
}
```
**Context Assignment Rules:**
- **Complete Context**: Use full task JSON context including flow_control field for agent execution
- **Flow Control Processing**: Execute flow_control.pre_analysis steps sequentially with context accumulation
- **Dependency Integration**: Load summaries from context.depends_on automatically
- **Mandatory Dependency Reading**: For tasks with dependencies, MUST read previous task summary documents
- **Context Inheritance**: Use dependency summaries to maintain consistency and include context.inherited data from parent tasks
- **Workflow Integration**: Include session state and IMPL_PLAN.md context
- **Focus Scope**: Direct agents to specific paths from context.focus_paths array
- **Flow Control Marker**: Auto-add [FLOW_CONTROL] when flow_control.pre_analysis exists
- **Target File Guidance**: Use flow_control.target_files for precise file targeting
**Context Assignment Rules**:
- Use complete task JSON including flow_control
- Load dependency summaries from context.depends_on
- Execute flow_control.pre_analysis steps sequentially
- Direct agents to context.focus_paths
- Auto-add [FLOW_CONTROL] marker when pre_analysis exists
### 4. Agent Execution & Progress Tracking
### 4. Agent Execution Pattern
```bash
Task(subagent_type="code-developer",
@@ -198,182 +136,83 @@ Task(subagent_type="code-developer",
description="Execute task with flow control step processing")
```
**Execution Protocol:**
- **Sequential Execution**: Respect task dependencies and execution order
- **Progress Monitoring**: Track through TodoWrite updates
- **Status Updates**: Update task JSON status after each completion
- **Cross-Agent Handoffs**: Coordinate results between related tasks
**Execution Protocol**:
- Sequential execution respecting dependencies
- Progress tracking through TodoWrite updates
- Status updates after completion
- Cross-agent result coordination
## Discovery & Analysis Process
## File Structure & Analysis
### File Structure Analysis
### Workflow Structure
```
.workflow/WFS-[topic-slug]/
├── workflow-session.json # Session state and stats
├── IMPL_PLAN.md # Workflow context and requirements
├── workflow-session.json # Session state
├── IMPL_PLAN.md # Requirements
├── .task/ # Task definitions
│ ├── IMPL-1.json # Main tasks
│ ├── IMPL-1.1.json # Subtasks
│ └── IMPL-1.2.json # Detailed tasks
└── .summaries/ # Completed task summaries
│ ├── IMPL-1.json
│ └── IMPL-1.1.json
└── .summaries/ # Completion summaries
```
### Task Status Assessment
```pseudo
function analyze_tasks(task_files):
executable_tasks = []
for task in task_files:
if task.status == "pending" and dependencies_met(task):
if task.subtasks.length == 0: // leaf task
executable_tasks.append(task)
else: // container task - check subtasks
if all_subtasks_ready(task):
executable_tasks.extend(task.subtasks)
return executable_tasks
### Task Status Logic
```
pending + dependencies_met → executable
completed → skip
blocked → skip until dependencies clear
```
### Automatic Agent Assignment
Based on discovered task data:
- **task.agent field**: Use specified agent from task JSON
- **task.type analysis**:
### Agent Assignment
- **task.agent field**: Use specified agent
- **task.type fallback**:
- "feature" → code-developer
- "test" → code-review-test-agent
- "docs" → code-developer
- "test" → code-review-test-agent
- "review" → code-review-agent
- **Gemini context**: Auto-assign based on task.context.scope and requirements
## Agent Task Assignment Patterns
### Discovery-Based Assignment
```bash
# Agent receives complete discovered context with saturation handling
Task(subagent_type="code-developer",
prompt="[FLOW_CONTROL] Execute IMPL-1.2: Analyze and implement auth logic
TASK TYPE: Saturated task (preparation_complexity: simple)
PREPARATION PHASE:
- Review existing auth patterns and conventions
- Check JWT library compatibility
- Analyze current session management
EXECUTION PHASE:
Implement JWT authentication based on preparation findings
Context from discovery:
- Requirements: JWT authentication, OAuth2 support
- Scope: src/auth/*, tests/auth/*
- Dependencies: IMPL-1.1 (completed)
- Workflow: WFS-user-auth authentication system
Session Context:
- Workflow Directory: .workflow/WFS-user-auth/
- TODO_LIST Location: .workflow/WFS-user-auth/TODO_LIST.md
- Summaries Directory: .workflow/WFS-user-auth/.summaries/
- Task JSON: .workflow/WFS-user-auth/.task/IMPL-1.2.json
Focus Paths: $(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/IMPL-1.2.json)
Analysis Command: Use ~/.claude/scripts/gemini-wrapper -p \"$(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/IMPL-1.2.json) @{CLAUDE.md}\"
CRITICAL:
1. Execute preparation phase first, then use findings for implementation
2. Use task-specific paths for focused analysis
3. Document both phases in completion summary
4. Update TODO_LIST.md and create completion summary using provided paths.",
description="Agent executes saturated task with preparation and implementation phases")
```
### Status Tracking Integration
```bash
# After agent completion, update discovered task status
update_task_status("IMPL-1.2", "completed")
mark_dependent_tasks_ready(task_dependencies)
```
## Coordination Strategies
### Automatic Coordination
- **Task Dependencies**: Execute in dependency order from discovered relationships
- **Agent Handoffs**: Pass results between agents based on task hierarchy
- **Progress Updates**: Update TodoWrite and JSON files after each completion
### Context Distribution
- **Rich Context**: Each agent gets complete task JSON + workflow context
- **Focus Areas**: Direct agents to specific files from task.context.scope
- **Inheritance**: Subtasks inherit parent context automatically
- **Session Integration**: Include workflow-session.json state in agent context
## Status Management
## Status Management & Coordination
### Task Status Updates
```json
// Before execution
{
"id": "IMPL-1.2",
"status": "pending",
"execution": {
"attempts": 0,
"last_attempt": null
}
}
{ "id": "IMPL-1.2", "status": "pending", "execution": { "attempts": 0 } }
// After execution
{
"id": "IMPL-1.2",
"status": "completed",
"execution": {
"attempts": 1,
"last_attempt": "2025-09-08T14:30:00Z"
}
}
// After execution
{ "id": "IMPL-1.2", "status": "completed", "execution": { "attempts": 1, "last_attempt": "2025-09-08T14:30:00Z" } }
```
### Session State Updates
```json
{
"current_phase": "EXECUTE",
"last_execute_run": "2025-09-08T14:30:00Z"
}
```
### Coordination Strategies
- **Dependencies**: Execute in dependency order
- **Agent Handoffs**: Pass results between agents
- **Progress Updates**: Update TodoWrite and JSON files
- **Context Distribution**: Complete task JSON + workflow context
- **Focus Areas**: Direct agents to specific paths from task.context.focus_paths
## Error Handling & Recovery
## Error Handling
### Discovery Issues
```bash
# No active session found
❌ No active workflow session found
→ Use: /workflow:session:start "project name" first
# No executable tasks
⚠️ All tasks completed or blocked
→ Check: /context for task status overview
# Missing task files
❌ Task IMPL-1.2 referenced but JSON file missing
→ Fix: /task/create or repair task references
❌ No active workflow session → Use: /workflow:session:start "project"
⚠️ All tasks completed/blocked → Check: /context for status
❌ Missing task files → Fix: /task/create or repair references
```
### Execution Recovery
- **Failed Agent**: Retry with adjusted context or different agent
- **Failed Agent**: Retry with adjusted context
- **Blocked Dependencies**: Skip and continue with available tasks
- **Context Issues**: Reload from JSON files and session state
## Integration Points
## Integration & Next Steps
### Automatic Behaviors
- **Discovery on start** - Analyze workflow folder structure
- **TodoWrite coordination** - Generate based on discovered tasks
- **Agent context preparation** - Use complete task JSON data
- **Status synchronization** - Update JSON files after completion
- Discovery on start - analyze workflow folder structure
- TodoWrite coordination - generate based on discovered tasks
- Agent context preparation - use complete task JSON data
- Status synchronization - update JSON files after completion
### Next Actions
```bash
# After /workflow:execute completion
```bash
/context # View updated task status
/task:execute IMPL-X # Execute specific remaining tasks
/task:execute IMPL-X # Execute specific remaining tasks
/workflow:review # Move to review phase when complete
```