mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
Refactor workflow plan command and architecture documentation
- 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
@@ -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
|
||||
```
|
||||
|
||||
|
||||
@@ -2,303 +2,116 @@
|
||||
name: plan
|
||||
description: Create implementation plans with intelligent input detection
|
||||
usage: /workflow:plan <input>
|
||||
argument-hint: "text description"|file.md|ISS-001|template-name
|
||||
argument-hint: "text description"|file.md|ISS-001
|
||||
examples:
|
||||
- /workflow:plan "Build authentication system"
|
||||
- /workflow:plan requirements.md
|
||||
- /workflow:plan ISS-001
|
||||
---
|
||||
|
||||
# Workflow Plan Command (/workflow:plan)
|
||||
|
||||
## Overview
|
||||
Creates actionable implementation plans with intelligent input source detection. Supports text, files, issues, and templates through automatic recognition.
|
||||
|
||||
## Core Principles
|
||||
**File Structure:** @~/.claude/workflows/workflow-architecture.md
|
||||
|
||||
**Dependency Context Rules:**
|
||||
- **For tasks with dependencies**: MUST read previous task summary documents before planning
|
||||
- **Context inheritance**: Use dependency summaries to maintain consistency and avoid duplicate work
|
||||
# Workflow Plan Command
|
||||
|
||||
## Usage
|
||||
```bash
|
||||
/workflow:plan [--AM gemini|codex] <input>
|
||||
/workflow:plan [--AM gemini|codex] [--analyze|--deep] <input>
|
||||
```
|
||||
|
||||
### Analysis Method Flag (--AM)
|
||||
Optional flag to specify which CLI tool to use for context analysis:
|
||||
- **gemini** (default): Uses Gemini CLI for pattern-based analysis, architectural understanding, and broader context acquisition
|
||||
- **codex**: Uses Codex CLI for autonomous development context gathering with intelligent file discovery
|
||||
## Input Detection
|
||||
- **Files**: `.md/.txt/.json/.yaml/.yml` → Reads content and extracts requirements
|
||||
- **Issues**: `ISS-*`, `ISSUE-*`, `*-request-*` → Loads issue data and acceptance criteria
|
||||
- **Text**: Everything else → Parses natural language requirements
|
||||
|
||||
**Examples**:
|
||||
```bash
|
||||
/workflow:plan --AM codex "Build authentication system"
|
||||
/workflow:plan --AM gemini requirements.md
|
||||
```
|
||||
## Analysis Levels
|
||||
- **Quick** (default): Structure only (5s)
|
||||
- **--analyze**: Structure + context analysis (30s)
|
||||
- **--deep**: Structure + comprehensive parallel analysis (1-2m)
|
||||
|
||||
## Input Detection Logic
|
||||
The command automatically detects input type:
|
||||
## Core Rules
|
||||
|
||||
### File Input (Auto-detected)
|
||||
```bash
|
||||
/workflow:plan requirements.md
|
||||
/workflow:plan config.json
|
||||
```
|
||||
**Triggers**: Extensions: .md, .txt, .json, .yaml, .yml
|
||||
**Processing**: Reads file contents and extracts requirements
|
||||
### File Structure Reference
|
||||
**Architecture**: @~/.claude/workflows/workflow-architecture.md
|
||||
|
||||
### Issue Input (Auto-detected)
|
||||
```bash
|
||||
/workflow:plan ISS-001
|
||||
/workflow:plan ISSUE-123
|
||||
```
|
||||
**Triggers**: Patterns: ISS-*, ISSUE-*, *-request-*
|
||||
**Processing**: Loads issue data and acceptance criteria
|
||||
### Task Limits & Decomposition
|
||||
- **Maximum 10 tasks**: Hard enforced limit - projects exceeding must be re-scoped
|
||||
- **Function-based decomposition**: By complete functional units, not files/steps
|
||||
- **File cohesion**: Group related files (UI + logic + tests + config) in same task
|
||||
- **Task saturation**: Merge "analyze + implement" by default (0.5 count for complex prep tasks)
|
||||
|
||||
|
||||
### Text Input (Default)
|
||||
```bash
|
||||
/workflow:plan "Build user authentication with JWT and OAuth2"
|
||||
```
|
||||
**Triggers**: Everything else
|
||||
**Processing**: Parse natural language requirements
|
||||
|
||||
## Automatic Behaviors
|
||||
### Pre-Planning Analysis (CRITICAL)
|
||||
⚠️ **Must complete BEFORE generating any plan documents**
|
||||
1. **Complexity assessment**: Count total saturated tasks
|
||||
2. **Decomposition strategy**: Flat (≤5) | Hierarchical (6-10) | Re-scope (>10)
|
||||
3. **File grouping**: Identify cohesive file sets
|
||||
4. **Quantity prediction**: Estimate main tasks, subtasks, container vs leaf ratio
|
||||
|
||||
### Session Management
|
||||
- Creates new session if none exists
|
||||
- Uses active session if available
|
||||
- Generates session ID: WFS-[topic-slug]
|
||||
- **Active session check**: Check for `.workflow/.active-*` marker first
|
||||
- Auto-creates new session: `WFS-[topic-slug]`
|
||||
- Uses existing active session if available
|
||||
- **Dependency context**: MUST read previous task summary documents before planning
|
||||
|
||||
### Pre-Planning Analysis
|
||||
⚠️ **CRITICAL**: Determine decomposition strategy BEFORE generating any plan documents
|
||||
## Task Patterns
|
||||
|
||||
**Required Pre-Analysis Steps**:
|
||||
1. **Complexity Assessment**: Analyze requirements to determine total saturated task count
|
||||
2. **Decomposition Strategy**: Based on complexity, decide:
|
||||
- Task structure (flat vs hierarchical)
|
||||
- Re-scoping necessity (>10 tasks triggers re-scoping)
|
||||
- Task saturation level (merged vs separated)
|
||||
- File grouping strategy (cohesive files together)
|
||||
3. **Quantity Prediction**: Calculate expected:
|
||||
- Total main tasks (IMPL-XXX)
|
||||
- Subtasks per main task (IMPL-N.M)
|
||||
- Container vs leaf task ratio
|
||||
### ✅ Correct (Function-based)
|
||||
- `IMPL-001: User authentication system` (models + routes + components + middleware + tests)
|
||||
- `IMPL-002: Data export functionality` (service + routes + UI + utils + tests)
|
||||
|
||||
**Pre-Planning Outputs**:
|
||||
- Complexity level: Simple (≤5) | Medium (6-10) | Over-scoped (>10, requires re-scoping)
|
||||
- Decomposition approach: Flat | Two-level hierarchy | Re-scope required
|
||||
- Estimated task count: [number] main tasks, [number] total leaf tasks (max 10)
|
||||
- Document set: Which documents will be generated (IMPL_PLAN.md, TODO_LIST.md, .task/*.json)
|
||||
- **Re-scoping recommendation**: If >10 tasks, provide guidance for breaking into iterations
|
||||
|
||||
**Only after completing pre-planning analysis**: Proceed to generate actual plan documents
|
||||
|
||||
### Complexity Detection with Saturation
|
||||
*Based on Pre-Planning Analysis results:*
|
||||
- **Simple**: ≤5 saturated tasks → Direct IMPL_PLAN.md
|
||||
- **Medium**: 6-10 saturated tasks → IMPL_PLAN.md + TODO_LIST.md
|
||||
- **Complex**: Exceeding 10 tasks requires re-scoping (maximum enforced)
|
||||
|
||||
**10-Task Hard Limit**: Projects exceeding 10 tasks must be re-scoped into smaller iterations
|
||||
**Note**: 1 complex preparation task = 0.5 saturated task for counting
|
||||
|
||||
### Task Granularity Principles
|
||||
- **Decompose by function, not by file**: Each task should complete a whole functional unit
|
||||
- **Maintain functional integrity**: Each task produces independently runnable or testable functionality
|
||||
- **Group related files together**: Keep related files (UI, logic, tests, config) in same task
|
||||
- **File cohesion rule**: Files that work together should be modified in the same task
|
||||
- **Avoid technical step decomposition**: Don't make "create file" or "add function" as separate tasks
|
||||
- **Maximum 10 tasks**: Hard limit enforced; re-scope if exceeded
|
||||
|
||||
### Task Decomposition Anti-patterns
|
||||
|
||||
❌ **Wrong Example - File/Step-based Decomposition**:
|
||||
- IMPL-001: Create database model
|
||||
- IMPL-002: Create API endpoint
|
||||
- IMPL-003: Create frontend component
|
||||
- IMPL-004: Add routing configuration
|
||||
- IMPL-005: Write unit tests
|
||||
|
||||
❌ **Wrong Example - Same File Split Across Tasks**:
|
||||
- IMPL-001: Add authentication routes to routes/auth.js
|
||||
- IMPL-002: Add user validation to routes/auth.js
|
||||
- IMPL-003: Add session handling to routes/auth.js
|
||||
|
||||
✅ **Correct Example - Function-based with File Cohesion**:
|
||||
- IMPL-001: Implement user authentication (includes models/User.js, routes/auth.js, components/LoginForm.jsx, middleware/auth.js, tests/auth.test.js)
|
||||
- IMPL-002: Implement data export functionality (includes services/export.js, routes/export.js, components/ExportButton.jsx, utils/fileGenerator.js, tests/export.test.js)
|
||||
|
||||
✅ **Correct Example - Related Files Grouped**:
|
||||
- IMPL-001: User management system (includes User model, UserController, UserService, user routes, user tests)
|
||||
- IMPL-002: Product catalog system (includes Product model, ProductController, catalog components, product tests)
|
||||
|
||||
### Task Generation with Saturation Control
|
||||
*Using decomposition strategy determined in Pre-Planning Analysis:*
|
||||
- **Task Saturation Assessment**: Evaluates whether to merge preparation and execution
|
||||
- **Default merge mode**: "Analyze and implement X" instead of "Analyze X" + "Implement X"
|
||||
- **Smart splitting**: Only separate when preparation complexity > threshold
|
||||
- Automatically creates .task/ files when complexity warrants
|
||||
- Generates hierarchical task structure (max 2 levels)
|
||||
- Main tasks with subtasks become container tasks (not directly executable)
|
||||
- Updates session state with task references
|
||||
- Runs project structure analysis to populate paths field
|
||||
|
||||
### Project Analysis Options
|
||||
|
||||
Three analysis levels available:
|
||||
|
||||
```bash
|
||||
# Quick - Structure only (5 seconds)
|
||||
/workflow:plan "requirements"
|
||||
|
||||
# Standard - Structure + Gemini analysis (30 seconds)
|
||||
/workflow:plan --analyze "requirements"
|
||||
|
||||
# Deep - Structure + Parallel comprehensive analysis (1-2 minutes)
|
||||
/workflow:plan --deep "requirements"
|
||||
```
|
||||
|
||||
**Analysis Selection**:
|
||||
- Default: Auto-selects based on project complexity
|
||||
- Manual: Use flags to override automatic selection
|
||||
- Strategy: See @~/.claude/workflows/intelligent-tools-strategy.md for tool selection principles
|
||||
|
||||
**Execution**:
|
||||
1. Always runs `get_modules_by_depth.sh` for structure
|
||||
2. Applies selected analysis level
|
||||
3. Populates task paths automatically
|
||||
|
||||
### Task Saturation Assessment
|
||||
Evaluates whether to merge preparation and execution within 10-task limit:
|
||||
|
||||
**Default Merge Principles** (Saturated Tasks):
|
||||
- All components of the same functional module
|
||||
- Related files that work together (UI, logic, tests, config)
|
||||
- Features with their corresponding tests and documentation
|
||||
- Configuration with its usage code
|
||||
- Multiple small interdependent functions
|
||||
- Files that share common interfaces or data structures
|
||||
|
||||
**Only Separate Tasks When**:
|
||||
- Completely independent functional modules (no shared code or interfaces)
|
||||
- Independent services with different tech stacks (e.g., separate deployment units)
|
||||
- Modules requiring different expertise (e.g., ML model training vs Web development)
|
||||
- Large features with clear sequential dependencies
|
||||
- **Critical**: Would exceed 10-task limit otherwise
|
||||
|
||||
**File Cohesion Examples**:
|
||||
- **Merged**: "IMPL-001: Implement user authentication (includes models/User.js, routes/auth.js, components/LoginForm.jsx, tests/auth.test.js)"
|
||||
- **Separated**: "IMPL-001: User service authentication" + "IMPL-002: Admin dashboard authentication" (different user contexts)
|
||||
|
||||
**10-Task Compliance**: Always prioritize related file grouping to stay within limit
|
||||
|
||||
### Task Breakdown Process
|
||||
- **Automatic decomposition**: Only when task count >10 triggers re-scoping (not decomposition)
|
||||
- **Function-based decomposition**: Split by independent functional boundaries, not by technical layers
|
||||
- **Container tasks**: Parent tasks with subtasks become containers (marked with ▸ in TODO_LIST)
|
||||
- **Smart decomposition**: AI analyzes task title to suggest logical functional subtask structure
|
||||
- **Complete unit principle**: Each subtask must still represent a complete functional unit
|
||||
- **Context inheritance**: Subtasks inherit parent's requirements and scope, refined for specific needs
|
||||
- **Agent assignment**: Automatic agent mapping based on subtask type (planning/code/test/review)
|
||||
- **Maximum depth**: 2 levels (IMPL-N.M) to maintain manageable hierarchy
|
||||
- **10-task enforcement**: Exceeding 10 tasks requires project re-scoping
|
||||
|
||||
### Flow Control Field Requirements
|
||||
- **flow_control**: Universal process manager containing:
|
||||
- `pre_analysis`: Array of sequential process steps with:
|
||||
- `step`: Unique identifier for the step
|
||||
- `action`: Human-readable description
|
||||
- `command`: Executable command with embedded context variables (e.g., `${variable_name}`)
|
||||
- `output_to`: Variable name to store step results (optional for final steps)
|
||||
- `on_error`: Error handling strategy
|
||||
- `implementation_approach`: Brief one-line strategy description
|
||||
- `target_files`: Array of "file:function:lines" format strings
|
||||
- **Auto-generation**: Creates flow based on task type and complexity
|
||||
- **Required fields**: meta (type, agent), context (requirements, focus_paths, acceptance, depends_on), flow_control
|
||||
- **Focus paths format**: Array of strings (e.g., ["src/auth", "tests/auth", "config/auth.json"])
|
||||
|
||||
## Session Check Process
|
||||
⚠️ **CRITICAL**: Check for existing active session before planning
|
||||
|
||||
1. **Check Active Session**: Check for `.workflow/.active-*` marker file
|
||||
2. **Session Selection**: Use existing active session or create new
|
||||
3. **Context Integration**: Load session state and existing context
|
||||
### ❌ Wrong (File/step-based)
|
||||
- `IMPL-001: Create database model`
|
||||
- `IMPL-002: Create API endpoint`
|
||||
- `IMPL-003: Create frontend component`
|
||||
|
||||
## Output Documents
|
||||
|
||||
### Document References for Execution
|
||||
### Always Created
|
||||
- **IMPL_PLAN.md**: Requirements, task breakdown, success criteria
|
||||
- **Session state**: Task references and paths
|
||||
|
||||
#### Primary References
|
||||
- **Planning Document**: `.workflow/WFS-[topic-slug]/IMPL_PLAN.md`
|
||||
- Used by: `/workflow:execute` for context loading
|
||||
- Contains: Requirements, task overview, success criteria
|
||||
### Auto-Created (complexity > simple)
|
||||
- **TODO_LIST.md**: Hierarchical progress tracking
|
||||
- **.task/*.json**: Individual task definitions with flow_control
|
||||
|
||||
- **Task Definitions**: `.workflow/WFS-[topic-slug]/.task/IMPL-*.json`
|
||||
- Used by: Agents for implementation context
|
||||
- Contains: Complete task details with 7-field structure including flow_control process manager
|
||||
|
||||
- **Progress Tracking**: `.workflow/WFS-[topic-slug]/TODO_LIST.md`
|
||||
- Used by: `/workflow:execute` for status tracking
|
||||
- Updated by: Agents after task completion
|
||||
|
||||
### IMPL_PLAN.md (Always Created)
|
||||
```markdown
|
||||
# Implementation Plan - [Project Name]
|
||||
*Generated from: [input_source]*
|
||||
|
||||
## Requirements
|
||||
[Extracted requirements from input source]
|
||||
|
||||
## Task Breakdown
|
||||
- **IMPL-001**: [Saturated task description with merged preparation and execution]
|
||||
- **IMPL-002**: [Task description]
|
||||
|
||||
## Success Criteria
|
||||
[Measurable completion conditions]
|
||||
### Document Structure
|
||||
```
|
||||
.workflow/WFS-[topic]/
|
||||
├── IMPL_PLAN.md # Main planning document
|
||||
├── TODO_LIST.md # Progress tracking (if complex)
|
||||
└── .task/
|
||||
├── IMPL-001.json # Task definitions
|
||||
└── IMPL-002.json
|
||||
```
|
||||
|
||||
### Optional TODO_LIST.md (Auto-triggered)
|
||||
Created when complexity > simple or task count > 3
|
||||
## Task Saturation Assessment
|
||||
**Default Merge** (cohesive files together):
|
||||
- Functional modules with UI + logic + tests + config
|
||||
- Features with their tests and documentation
|
||||
- Files sharing common interfaces/data structures
|
||||
|
||||
**TODO_LIST Structure**: Uses unified hierarchical list format
|
||||
- Container tasks (with subtasks) marked with `▸` symbol
|
||||
- Leaf tasks use standard `- [ ]` / `- [x]` checkboxes
|
||||
- Indentation shows hierarchy (2 spaces per level)
|
||||
- Container tasks represent logical grouping, not executable items
|
||||
**Only Separate When**:
|
||||
- Completely independent functional modules
|
||||
- Different tech stacks or deployment units
|
||||
- Would exceed 10-task limit otherwise
|
||||
|
||||
### Task JSON Files (Auto-created)
|
||||
Generated in .task/ directory when decomposition enabled
|
||||
## Flow Control Schema
|
||||
Each task.json includes required fields:
|
||||
- **meta**: type, agent assignment
|
||||
- **context**: requirements, focus_paths, acceptance, depends_on
|
||||
- **flow_control**:
|
||||
- `pre_analysis`: Steps with commands and context variables (${var})
|
||||
- `implementation_approach`: One-line strategy
|
||||
- `target_files`: "file:function:lines" format
|
||||
|
||||
## Execution Integration
|
||||
Documents created for `/workflow:execute`:
|
||||
- **IMPL_PLAN.md**: Context loading and requirements
|
||||
- **.task/*.json**: Agent implementation context
|
||||
- **TODO_LIST.md**: Status tracking (container tasks with ▸, leaf tasks with checkboxes)
|
||||
|
||||
## Error Handling
|
||||
- **Vague input**: Auto-reject ("fix it", "make better", etc.)
|
||||
- **File not found**: Clear suggestions
|
||||
- **>10 tasks**: Force re-scoping into iterations
|
||||
|
||||
### Input Processing Errors
|
||||
- **File not found**: Clear error message with suggestions
|
||||
- **Invalid issue**: Verify issue ID exists
|
||||
- **Unknown template**: List available templates
|
||||
- **Empty input**: Prompt for valid input
|
||||
- **Vague text input**: Auto-reject without guidance
|
||||
- Rejected examples: "do something", "fix it", "make it better", "add feature"
|
||||
- Response: Direct rejection message, no further assistance
|
||||
|
||||
### Recommended Task Patterns
|
||||
|
||||
#### Complete Feature Implementation
|
||||
"Implement user management system" - includes all related files: models/User.js, controllers/UserController.js, routes/users.js, components/UserList.jsx, services/UserService.js, tests/user.test.js
|
||||
|
||||
#### End-to-End Features
|
||||
"Add Excel export functionality" - includes cohesive file set: services/ExportService.js, utils/excelGenerator.js, routes/export.js, components/ExportButton.jsx, middleware/downloadHandler.js, tests/export.test.js
|
||||
|
||||
#### System Integration
|
||||
"Integrate payment gateway" - includes integration files: services/PaymentService.js, controllers/PaymentController.js, models/Payment.js, components/PaymentForm.jsx, webhooks/paymentWebhook.js, tests/payment.test.js
|
||||
|
||||
#### Problem Resolution
|
||||
"Fix and optimize search functionality" - includes related files: services/SearchService.js, utils/searchOptimizer.js, components/SearchBar.jsx, controllers/SearchController.js, tests/search.test.js
|
||||
|
||||
#### Module Development
|
||||
"Create notification system" - includes module files: services/NotificationService.js, models/Notification.js, templates/emailTemplates.js, components/NotificationCenter.jsx, workers/notificationQueue.js, tests/notification.test.js
|
||||
|
||||
**File Cohesion Principle**: Each task includes ALL files that work together to deliver the complete functionality
|
||||
|
||||
**System ensures**: Unified planning interface with intelligent input detection, function-based task granularity, file cohesion enforcement, and 10-task maximum limit
|
||||
## Analysis Method (--AM)
|
||||
- **gemini** (default): Pattern analysis, architectural understanding
|
||||
- **codex**: Autonomous development, intelligent file discovery
|
||||
@@ -1,23 +1,77 @@
|
||||
# Workflow Architecture
|
||||
|
||||
## Overview & Core Principles
|
||||
## Overview
|
||||
|
||||
This document defines a streamlined workflow system architecture featuring **JSON-only data model**, **marker-based session management**, and **unified file structure** with dynamic task decomposition.
|
||||
This document defines the complete workflow system architecture using a **JSON-only data model**, **marker-based session management**, and **unified file structure** with dynamic task decomposition.
|
||||
|
||||
### Design Philosophy
|
||||
- **JSON-first data model** - JSON files are single source of truth; markdown is generated views
|
||||
- **Marker-based sessions** - Ultra-simple active session tracking via marker files
|
||||
- **Unified structure** - Same file template for all workflows, created on-demand
|
||||
- **Dynamic decomposition** - Tasks break down as needed during execution
|
||||
- **On-demand creation** - Files and directories created only when required
|
||||
- **Agent autonomy** - Complete context preserved for independent execution
|
||||
## Core Architecture Principles
|
||||
|
||||
## Data Architecture
|
||||
### Key Design Decisions
|
||||
- **JSON files are the single source of truth** - All markdown documents are read-only generated views
|
||||
- **Marker files for session tracking** - Ultra-simple active session management
|
||||
- **Unified file structure definition** - Same structure template for all workflows, created on-demand
|
||||
- **Dynamic task decomposition** - Subtasks created as needed during execution
|
||||
- **On-demand file creation** - Directories and files created only when required
|
||||
- **Agent-agnostic task definitions** - Complete context preserved for autonomous execution
|
||||
|
||||
### JSON-Only Data Model
|
||||
**Core Principle**: JSON files are the authoritative source; markdown documents are read-only generated views.
|
||||
## Session Management
|
||||
|
||||
- **Task State**: Stored exclusively in `.task/IMPL-*.json` files
|
||||
### Active Session Marker System
|
||||
**Ultra-Simple Active Tracking**: `.workflow/.active-[session-name]`
|
||||
|
||||
```bash
|
||||
.workflow/
|
||||
├── WFS-oauth-integration/ # Session directory (paused)
|
||||
├── WFS-user-profile/ # Session directory (paused)
|
||||
├── WFS-bug-fix-123/ # Session directory (completed)
|
||||
└── .active-WFS-user-profile # Marker file (indicates active session)
|
||||
```
|
||||
|
||||
**Marker File Benefits**:
|
||||
- **Zero Parsing**: File existence check is atomic and instant
|
||||
- **Atomic Operations**: File creation/deletion is naturally atomic
|
||||
- **Visual Discovery**: `ls .workflow/.active-*` shows active session immediately
|
||||
- **Simple Switching**: Delete old marker + create new marker = session switch
|
||||
|
||||
### Session Operations
|
||||
|
||||
#### Detect Active Session
|
||||
```bash
|
||||
active_session=$(find .workflow -name ".active-*" | head -1)
|
||||
if [ -n "$active_session" ]; then
|
||||
session_name=$(basename "$active_session" | sed 's/^\.active-//')
|
||||
echo "Active session: $session_name"
|
||||
fi
|
||||
```
|
||||
|
||||
#### Switch Session
|
||||
```bash
|
||||
find .workflow -name ".active-*" -delete && touch .workflow/.active-WFS-new-feature
|
||||
```
|
||||
|
||||
### Individual Session Tracking
|
||||
Each session directory contains `workflow-session.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "WFS-[topic-slug]",
|
||||
"project": "feature description",
|
||||
"type": "simple|medium|complex",
|
||||
"current_phase": "PLAN|IMPLEMENT|REVIEW",
|
||||
"status": "active|paused|completed",
|
||||
"progress": {
|
||||
"completed_phases": ["PLAN"],
|
||||
"current_tasks": ["IMPL-1", "IMPL-2"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Data Model
|
||||
|
||||
### JSON-Only Architecture
|
||||
**JSON files (.task/IMPL-*.json) are the only authoritative source of task state. All markdown documents are read-only generated views.**
|
||||
|
||||
- **Task State**: Stored exclusively in JSON files
|
||||
- **Documents**: Generated on-demand from JSON data
|
||||
- **No Synchronization**: Eliminates bidirectional sync complexity
|
||||
- **Performance**: Direct JSON access without parsing overhead
|
||||
@@ -59,12 +113,35 @@ All task files use this simplified 5-field schema:
|
||||
"command": "bash(cat .workflow/*/summaries/IMPL-1.1-summary.md)",
|
||||
"output_to": "auth_design_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 using context: [auth_design_context]')",
|
||||
"output_to": "pattern_analysis",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "implement",
|
||||
"action": "Implement JWT based on analysis",
|
||||
"command": "bash(codex --full-auto exec 'Implement JWT using analysis: [pattern_analysis] and dependency context: [auth_design_context]')",
|
||||
"on_error": "manual_intervention"
|
||||
}
|
||||
],
|
||||
"implementation_approach": {
|
||||
"task_description": "Implement comprehensive JWT authentication system...",
|
||||
"modification_points": ["Add JWT token generation...", "..."],
|
||||
"logic_flow": ["User login request → validate credentials...", "..."]
|
||||
"task_description": "Implement comprehensive JWT authentication system with secure token management and validation middleware. Reference [inherited.context] from parent task [parent] for architectural consistency. Apply [shared_context.auth_strategy] across authentication modules. Focus implementation on [focus_paths] directories following established patterns.",
|
||||
"modification_points": [
|
||||
"Add JWT token generation in login handler (src/auth/login.ts:handleLogin:75-120) following [shared_context.auth_strategy]",
|
||||
"Implement token validation middleware (src/middleware/auth.ts:validateToken) referencing [inherited.context] design patterns",
|
||||
"Add refresh token mechanism for session management using [shared_context] token strategy",
|
||||
"Update user authentication flow to support JWT tokens in [focus_paths] modules"
|
||||
],
|
||||
"logic_flow": [
|
||||
"User login request → validate credentials → generate JWT token using [shared_context.auth_strategy] → store refresh token",
|
||||
"Protected route access → extract JWT from headers → validate token against [inherited.context] schema → allow/deny access",
|
||||
"Token expiry handling → use refresh token following [shared_context] strategy → generate new JWT → continue session",
|
||||
"Logout process → invalidate refresh token → clear client-side tokens in [focus_paths] components"
|
||||
]
|
||||
},
|
||||
"target_files": [
|
||||
"src/auth/login.ts:handleLogin:75-120",
|
||||
@@ -137,32 +214,45 @@ Each step contains:
|
||||
- **retry_once**: Retry step once, then fail if still unsuccessful
|
||||
- **manual_intervention**: Pause execution for manual review
|
||||
|
||||
#### Example Flow Control Patterns
|
||||
|
||||
**Pattern 1: Multi-Step Analysis**
|
||||
#### Example Flow Control
|
||||
```json
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "gather_dependencies",
|
||||
"command": "bash(for dep in ${depends_on}; do cat .summaries/$dep-summary.md; done)",
|
||||
"output_to": "dependency_context"
|
||||
{
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "gather_dependencies",
|
||||
"action": "Load context from completed dependencies",
|
||||
"command": "bash(for dep in ${depends_on}; do cat .summaries/$dep-summary.md 2>/dev/null || echo \"No summary for $dep\"; done)",
|
||||
"output_to": "dependency_context",
|
||||
"on_error": "skip_optional"
|
||||
},
|
||||
{
|
||||
"step": "analyze_codebase",
|
||||
"action": "Understand current implementation",
|
||||
"command": "bash(gemini -p '@{[focus_paths]} analyze current patterns using context: [dependency_context]')",
|
||||
"output_to": "codebase_analysis",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "implement",
|
||||
"action": "Execute implementation based on analysis",
|
||||
"command": "bash(codex --full-auto exec 'Implement based on: [codebase_analysis] with dependency context: [dependency_context]')",
|
||||
"on_error": "manual_intervention"
|
||||
}
|
||||
],
|
||||
"implementation_approach": {
|
||||
"task_description": "Execute implementation following [codebase_analysis] patterns and [dependency_context] requirements",
|
||||
"modification_points": [
|
||||
"Update target files in [focus_paths] following established patterns",
|
||||
"Apply [dependency_context] insights to maintain consistency"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Analyze existing patterns → apply dependency context → implement changes → validate results"
|
||||
]
|
||||
},
|
||||
{
|
||||
"step": "analyze_codebase",
|
||||
"command": "bash(gemini -p '@{[focus_paths]} using context: [dependency_context]')",
|
||||
"output_to": "codebase_analysis"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Pattern 2: Direct Implementation**
|
||||
```json
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "implement",
|
||||
"command": "bash(codex --full-auto exec 'Implement [title] in [focus_paths]')"
|
||||
}
|
||||
]
|
||||
"target_files": [
|
||||
"file:function:lines format for precise targeting"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Benefits of Flow Control
|
||||
@@ -172,205 +262,146 @@ Each step contains:
|
||||
- **Command Flexibility**: Supports any executable command or agent
|
||||
- **Dependency Integration**: Automatic loading of prerequisite task results
|
||||
|
||||
### Task Hierarchy
|
||||
**Structure**: Maximum 2 levels (IMPL-N.M format)
|
||||
### Hierarchical Task System
|
||||
**Maximum Depth**: 2 levels (IMPL-N.M format)
|
||||
|
||||
```
|
||||
IMPL-1 # Main task
|
||||
IMPL-1.1 # Subtask (dynamically created)
|
||||
IMPL-1.2 # Another subtask
|
||||
IMPL-1.1 # Subtask of IMPL-1 (dynamically created)
|
||||
IMPL-1.2 # Another subtask of IMPL-1
|
||||
IMPL-2 # Another main task
|
||||
IMPL-2.1 # Subtask (dynamically created)
|
||||
IMPL-2.1 # Subtask of IMPL-2 (dynamically created)
|
||||
```
|
||||
|
||||
**Rules**:
|
||||
- **Container tasks**: Parent tasks with subtasks (cannot execute directly)
|
||||
- **Leaf tasks**: Only executable tasks
|
||||
**Task Status Rules**:
|
||||
- **Container tasks**: Parent tasks with subtasks (cannot be directly executed)
|
||||
- **Leaf tasks**: Only these can be executed directly
|
||||
- **Status inheritance**: Parent status derived from subtask completion
|
||||
|
||||
## Session Management
|
||||
## File Structure
|
||||
|
||||
### Active Session Marker System
|
||||
**Ultra-Simple Tracking**: `.workflow/.active-[session-name]`
|
||||
|
||||
```bash
|
||||
.workflow/
|
||||
├── WFS-oauth-integration/ # Session directory (paused)
|
||||
├── WFS-user-profile/ # Session directory (paused)
|
||||
├── WFS-bug-fix-123/ # Session directory (completed)
|
||||
└── .active-WFS-user-profile # Marker file (active session)
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- **Zero Parsing**: File existence check is atomic
|
||||
- **Atomic Operations**: File creation/deletion is naturally atomic
|
||||
- **Visual Discovery**: `ls .workflow/.active-*` shows active session
|
||||
- **Simple Switching**: Delete old + create new marker
|
||||
|
||||
### Session Operations
|
||||
|
||||
```bash
|
||||
# Detect active session
|
||||
active_session=$(find .workflow -name ".active-*" | head -1)
|
||||
if [ -n "$active_session" ]; then
|
||||
session_name=$(basename "$active_session" | sed 's/^\.active-//')
|
||||
echo "Active session: $session_name"
|
||||
fi
|
||||
|
||||
# Switch session
|
||||
find .workflow -name ".active-*" -delete && touch .workflow/.active-WFS-new-feature
|
||||
```
|
||||
|
||||
### Session State
|
||||
Each session directory contains `workflow-session.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "WFS-[topic-slug]",
|
||||
"project": "feature description",
|
||||
"type": "simple|medium|complex",
|
||||
"current_phase": "PLAN|IMPLEMENT|REVIEW",
|
||||
"status": "active|paused|completed",
|
||||
"progress": {
|
||||
"completed_phases": ["PLAN"],
|
||||
"current_tasks": ["IMPL-1", "IMPL-2"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## File Organization
|
||||
|
||||
### Unified Structure
|
||||
All workflows use the same structure regardless of complexity. **Files created on-demand only.**
|
||||
### Unified File Structure
|
||||
All workflows use the same file structure definition regardless of complexity. **Directories and files are created on-demand as needed**, not all at once during initialization.
|
||||
|
||||
#### Complete Structure Reference
|
||||
```
|
||||
.workflow/WFS-[topic-slug]/
|
||||
├── workflow-session.json # Session state (REQUIRED)
|
||||
├── IMPL_PLAN.md # Planning document (REQUIRED)
|
||||
├── TODO_LIST.md # Progress tracking (REQUIRED)
|
||||
├── .task/ # Task definitions (REQUIRED)
|
||||
│ ├── IMPL-*.json # Main task definitions
|
||||
│ └── IMPL-*.*.json # Subtask definitions (dynamic)
|
||||
├── [.brainstorming/] # Brainstorming phase (on-demand)
|
||||
├── [.chat/] # CLI sessions (on-demand)
|
||||
├── workflow-session.json # Session metadata and state (REQUIRED)
|
||||
├── [.brainstorming/] # Optional brainstorming phase (created when needed)
|
||||
├── [.chat/] # CLI interaction sessions (created when analysis is run)
|
||||
│ ├── chat-*.md # Saved chat sessions
|
||||
│ └── analysis-*.md # Analysis results
|
||||
└── [.summaries/] # Task summaries (on-demand)
|
||||
├── IMPL-*.md # Main task summaries
|
||||
└── IMPL-*.*.md # Subtask summaries
|
||||
├── IMPL_PLAN.md # Planning document (REQUIRED)
|
||||
├── TODO_LIST.md # Progress tracking (REQUIRED)
|
||||
├── [.summaries/] # Task completion summaries (created when tasks complete)
|
||||
│ ├── IMPL-*.md # Main task summaries
|
||||
│ └── IMPL-*.*.md # Subtask summaries
|
||||
└── .task/ # Task definitions (REQUIRED)
|
||||
├── IMPL-*.json # Main task definitions
|
||||
└── IMPL-*.*.json # Subtask definitions (created dynamically)
|
||||
```
|
||||
|
||||
### Creation Strategy
|
||||
- **Initial**: Only `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`, `.task/`
|
||||
- **On-Demand**:
|
||||
- `.brainstorming/` → When brainstorming initiated
|
||||
- `.chat/` → When analysis commands executed
|
||||
- `.summaries/` → When first task completed
|
||||
#### Creation Strategy
|
||||
- **Initial Setup**: Create only `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`, and `.task/` directory
|
||||
- **On-Demand Creation**: Other directories created when first needed:
|
||||
- `.brainstorming/` → When brainstorming phase is initiated
|
||||
- `.chat/` → When CLI analysis commands are executed
|
||||
- `.summaries/` → When first task is completed
|
||||
- **Dynamic Files**: Subtask JSON files created during task decomposition
|
||||
|
||||
### Naming Conventions
|
||||
- **Sessions**: `WFS-[topic-slug]` (lowercase with hyphens)
|
||||
- **Conflicts**: Add `-NNN` suffix if needed
|
||||
- **Documents**: Standard names (`workflow-session.json`, `IMPL_PLAN.md`, etc.)
|
||||
- **Chat**: `chat-analysis-*.md`
|
||||
- **Summaries**: `IMPL-[task-id]-summary.md`
|
||||
### File Naming Conventions
|
||||
|
||||
## Workflow Classification
|
||||
#### Session Identifiers
|
||||
**Format**: `WFS-[topic-slug]`
|
||||
- Convert topic to lowercase with hyphens (e.g., "User Auth System" → `WFS-user-auth-system`)
|
||||
- Add `-NNN` suffix only if conflicts exist (e.g., `WFS-payment-integration-002`)
|
||||
|
||||
### Complexity Types
|
||||
**Based on task count and decomposition needs:**
|
||||
#### Document Naming
|
||||
- `workflow-session.json` - Session state (required)
|
||||
- `IMPL_PLAN.md` - Planning document (required)
|
||||
- `TODO_LIST.md` - Progress tracking (auto-generated when needed)
|
||||
- Chat sessions: `chat-analysis-*.md`
|
||||
- Task summaries: `IMPL-[task-id]-summary.md`
|
||||
|
||||
| Type | Tasks | Depth | Behavior |
|
||||
|------|-------|-------|----------|
|
||||
| **Simple** | ≤5 | 1 level | Direct execution, minimal decomposition |
|
||||
| **Medium** | 6-10 | 2 levels | Moderate decomposition, context coordination |
|
||||
| **Over-scope** | >10 | Re-scope | Requires project re-scoping into iterations |
|
||||
## Complexity Classification
|
||||
|
||||
### Characteristics
|
||||
### Task Complexity Rules
|
||||
**Complexity is determined by task count and decomposition needs:**
|
||||
|
||||
**Simple**: Bug fixes, small features, config changes
|
||||
- Single-level tasks, direct execution, ≤5 tasks
|
||||
| Complexity | Task Count | Hierarchy Depth | Decomposition Behavior |
|
||||
|------------|------------|----------------|----------------------|
|
||||
| **Simple** | <5 tasks | 1 level (IMPL-N) | Direct execution, minimal decomposition |
|
||||
| **Medium** | 5-15 tasks | 2 levels (IMPL-N.M) | Moderate decomposition, context coordination |
|
||||
| **Complex** | >15 tasks | 2 levels (IMPL-N.M) | Frequent decomposition, multi-agent orchestration |
|
||||
|
||||
**Medium**: New features, API endpoints, schema changes
|
||||
- Two-level hierarchy, context coordination, 6-10 tasks
|
||||
### Simple Workflows
|
||||
**Characteristics**: Direct implementation tasks with clear, limited scope
|
||||
- **Examples**: Bug fixes, small feature additions, configuration changes
|
||||
- **Task Decomposition**: Usually single-level tasks, minimal breakdown needed
|
||||
- **Agent Coordination**: Direct execution without complex orchestration
|
||||
|
||||
**Over-scope**: Major features exceeding 10 tasks
|
||||
- Requires re-scoping into smaller iterations, never >10 tasks
|
||||
### Medium Workflows
|
||||
**Characteristics**: Feature implementation requiring moderate task breakdown
|
||||
- **Examples**: New features, API endpoints with integration, database schema changes
|
||||
- **Task Decomposition**: Two-level hierarchy when decomposition is needed
|
||||
- **Agent Coordination**: Context coordination between related tasks
|
||||
|
||||
### Assessment Rules
|
||||
- **Creation**: System evaluates and assigns complexity
|
||||
- **10-task limit**: Hard limit enforced - exceeding requires re-scoping
|
||||
- **Execution**: Can upgrade (Simple→Medium→Over-scope), triggers re-scoping
|
||||
- **Override**: Users can manually specify complexity within 10-task limit
|
||||
### Complex Workflows
|
||||
**Characteristics**: System-wide changes requiring detailed decomposition
|
||||
- **Examples**: Major features, architecture refactoring, security implementations, multi-service deployments
|
||||
- **Task Decomposition**: Frequent use of two-level hierarchy with dynamic subtask creation
|
||||
- **Agent Coordination**: Multi-agent orchestration with deep context analysis
|
||||
|
||||
## Task Execution Framework
|
||||
### Automatic Assessment & Upgrades
|
||||
- **During Creation**: System evaluates requirements and assigns complexity
|
||||
- **During Execution**: Can upgrade (Simple→Medium→Complex) but never downgrade
|
||||
- **Override Allowed**: Users can specify higher complexity manually
|
||||
|
||||
### Agent Integration
|
||||
## Document Templates
|
||||
|
||||
**Assignment Rules** (based on task type/keywords):
|
||||
- **Planning** → planning-agent
|
||||
- **Implementation** → code-developer
|
||||
- **Testing** → code-review-test-agent
|
||||
- **Review** → review-agent
|
||||
### IMPL_PLAN.md
|
||||
Generated based on task complexity and requirements. Contains overview, requirements, and task structure.
|
||||
|
||||
**Execution Context** (agents receive):
|
||||
### Task Summary Template (.summaries/IMPL-X.X-summary.md)
|
||||
Enhanced summary documents for context inheritance and dependency resolution:
|
||||
|
||||
```markdown
|
||||
# Task Summary: [task-id] - [title]
|
||||
|
||||
## Context Provided
|
||||
- **Parent Context**: [inherited context from parent task]
|
||||
- **Dependencies Resolved**:
|
||||
- [dep-1]: [brief description of what was provided]
|
||||
- [dep-2]: [brief description of what was provided]
|
||||
|
||||
## Implementation Details
|
||||
### Approach
|
||||
[Brief description of the implementation strategy used]
|
||||
|
||||
### Files Modified
|
||||
- `[file-path]`: [description of changes made]
|
||||
- `[file-path]`: [description of changes made]
|
||||
|
||||
### Key Decisions
|
||||
- [Decision 1]: [rationale]
|
||||
- [Decision 2]: [rationale]
|
||||
|
||||
## Outputs for Dependent Tasks
|
||||
### Shared Context
|
||||
```json
|
||||
{
|
||||
"task": { /* complete task JSON */ },
|
||||
"workflow": {
|
||||
"session": "WFS-user-auth",
|
||||
"phase": "IMPLEMENT"
|
||||
"key_component": "location or identifier",
|
||||
"configuration": {
|
||||
"setting1": "value1",
|
||||
"setting2": "value2"
|
||||
},
|
||||
"integration_points": ["endpoint1", "function2"],
|
||||
"important_constants": {
|
||||
"timeout": "30s",
|
||||
"max_retries": 3
|
||||
}
|
||||
}
|
||||
```
|
||||
## Operations Guide
|
||||
|
||||
### Basic Operations
|
||||
|
||||
```bash
|
||||
# Session initialization
|
||||
mkdir -p .workflow/WFS-topic-slug/.task
|
||||
echo '{"session_id":"WFS-topic-slug",...}' > .workflow/WFS-topic-slug/workflow-session.json
|
||||
echo '# Implementation Plan' > .workflow/WFS-topic-slug/IMPL_PLAN.md
|
||||
echo '# Tasks' > .workflow/WFS-topic-slug/TODO_LIST.md
|
||||
|
||||
# Task creation
|
||||
echo '{"id":"IMPL-1","title":"New task",...}' > .task/IMPL-1.json
|
||||
|
||||
# Task updates
|
||||
jq '.status = "active"' .task/IMPL-1.json > temp && mv temp .task/IMPL-1.json
|
||||
|
||||
# Document generation
|
||||
generate_todo_list_from_json .task/
|
||||
```
|
||||
|
||||
### Validation Rules
|
||||
1. **ID Uniqueness**: All task IDs must be unique
|
||||
2. **Format**: IMPL-N[.M] pattern (max 2 levels)
|
||||
3. **References**: Parent IDs must exist as JSON files
|
||||
4. **Fields**: All 5 core fields required (id, title, status, meta, context, flow_control)
|
||||
5. **Paths**: context.focus_paths must contain valid project paths
|
||||
6. **Dependencies**: context.depends_on task IDs must exist
|
||||
|
||||
### Error Recovery
|
||||
- **Missing Session**: Remove orphaned active marker
|
||||
- **Multiple Active**: Keep newest, remove others
|
||||
- **Corrupted Session**: Recreate from template
|
||||
- **Broken Hierarchy**: Reconstruct parent-child relationships
|
||||
|
||||
```bash
|
||||
# Session consistency check
|
||||
active_marker=$(find .workflow -name ".active-*" | head -1)
|
||||
if [ -n "$active_marker" ]; then
|
||||
session_name=$(basename "$active_marker" | sed 's/^\.active-//')
|
||||
session_dir=".workflow/$session_name"
|
||||
if [ ! -d "$session_dir" ]; then
|
||||
echo "⚠️ Orphaned active marker, removing..."
|
||||
rm "$active_marker"
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
## Reference Templates
|
||||
|
||||
### Integration Points
|
||||
- **[Component Name]**: [how to use/integrate]
|
||||
@@ -385,7 +416,15 @@ fi
|
||||
## Notes for Future Tasks
|
||||
[Any important considerations, limitations, or follow-up items]
|
||||
```
|
||||
### TODO List (TODO_LIST.md)
|
||||
|
||||
#### Summary Document Purpose
|
||||
- **Context Inheritance**: Provides structured context for dependent tasks
|
||||
- **Integration Guidance**: Offers clear integration points and usage instructions
|
||||
- **Quality Assurance**: Documents testing and validation performed
|
||||
- **Decision History**: Preserves rationale for implementation choices
|
||||
- **Dependency Chain**: Enables automatic context accumulation through task dependencies
|
||||
|
||||
### TODO_LIST.md Template
|
||||
```markdown
|
||||
# Tasks: [Session Topic]
|
||||
|
||||
@@ -393,7 +432,7 @@ fi
|
||||
▸ **IMPL-001**: [Main Task Group] → [📋](./.task/IMPL-001.json)
|
||||
- [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/IMPL-001.1.json)
|
||||
- [x] **IMPL-001.2**: [Subtask] → [📋](./.task/IMPL-001.2.json) | [✅](./.summaries/IMPL-001.2.md)
|
||||
|
||||
|
||||
- [x] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json) | [✅](./.summaries/IMPL-002.md)
|
||||
|
||||
▸ **IMPL-003**: [Main Task Group] → [📋](./.task/IMPL-003.json)
|
||||
@@ -402,7 +441,7 @@ fi
|
||||
|
||||
## Status Legend
|
||||
- `▸` = Container task (has subtasks)
|
||||
- `- [ ]` = Pending leaf task
|
||||
- `- [ ]` = Pending leaf task
|
||||
- `- [x]` = Completed leaf task
|
||||
- Maximum 2 levels: Main tasks and subtasks only
|
||||
|
||||
@@ -410,6 +449,97 @@ fi
|
||||
[Optional notes]
|
||||
```
|
||||
|
||||
## Agent Integration
|
||||
|
||||
### Agent Assignment
|
||||
Based on task type and title keywords:
|
||||
- **Planning tasks** → planning-agent
|
||||
- **Implementation** → code-developer
|
||||
- **Testing** → code-review-test-agent
|
||||
- **Review** → review-agent
|
||||
|
||||
### Execution Context
|
||||
Agents receive complete task JSON plus workflow context:
|
||||
```json
|
||||
{
|
||||
"task": { /* complete task JSON */ },
|
||||
"workflow": {
|
||||
"session": "WFS-user-auth",
|
||||
"phase": "IMPLEMENT"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Data Operations
|
||||
|
||||
### Session Initialization
|
||||
```bash
|
||||
# Create minimal required structure
|
||||
mkdir -p .workflow/WFS-topic-slug/.task
|
||||
echo '{"session_id":"WFS-topic-slug",...}' > .workflow/WFS-topic-slug/workflow-session.json
|
||||
echo '# Implementation Plan' > .workflow/WFS-topic-slug/IMPL_PLAN.md
|
||||
echo '# Tasks' > .workflow/WFS-topic-slug/TODO_LIST.md
|
||||
```
|
||||
|
||||
### Task Creation
|
||||
```bash
|
||||
echo '{"id":"IMPL-1","title":"New task",...}' > .task/IMPL-1.json
|
||||
```
|
||||
|
||||
### Directory Creation (On-Demand)
|
||||
```bash
|
||||
# Create directories only when needed
|
||||
mkdir -p .brainstorming # When brainstorming is initiated
|
||||
mkdir -p .chat # When analysis commands are run
|
||||
mkdir -p .summaries # When first task completes
|
||||
```
|
||||
|
||||
### Task Updates
|
||||
```bash
|
||||
jq '.status = "active"' .task/IMPL-1.json > temp && mv temp .task/IMPL-1.json
|
||||
```
|
||||
|
||||
### Document Generation
|
||||
```bash
|
||||
# Generate TODO_LIST.md from current JSON state
|
||||
generate_todo_list_from_json .task/
|
||||
```
|
||||
|
||||
## Validation and Error Handling
|
||||
|
||||
### Task Integrity Rules
|
||||
1. **ID Uniqueness**: All task IDs must be unique
|
||||
2. **Hierarchical Format**: Must follow IMPL-N[.M] pattern (maximum 2 levels)
|
||||
3. **Parent References**: All parent IDs must exist as JSON files
|
||||
4. **Depth Limits**: Maximum 2 levels deep
|
||||
5. **Status Consistency**: Status values from defined enumeration
|
||||
6. **Required Fields**: All 5 core fields must be present (id, title, status, meta, context, flow_control)
|
||||
7. **Focus Paths Structure**: context.focus_paths array must contain valid project paths
|
||||
8. **Flow Control Format**: flow_control.pre_analysis must be array with step, action, command fields
|
||||
9. **Dependency Integrity**: All context.depends_on task IDs must exist as JSON files
|
||||
|
||||
### Session Consistency Checks
|
||||
```bash
|
||||
# Validate active session integrity
|
||||
active_marker=$(find .workflow -name ".active-*" | head -1)
|
||||
if [ -n "$active_marker" ]; then
|
||||
session_name=$(basename "$active_marker" | sed 's/^\.active-//')
|
||||
session_dir=".workflow/$session_name"
|
||||
|
||||
if [ ! -d "$session_dir" ]; then
|
||||
echo "⚠️ Orphaned active marker, removing..."
|
||||
rm "$active_marker"
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
### Recovery Strategies
|
||||
- **Missing Session Directory**: Remove orphaned active marker
|
||||
- **Multiple Active Markers**: Keep newest, remove others
|
||||
- **Corrupted Session File**: Recreate from template
|
||||
- **Broken Task Hierarchy**: Reconstruct parent-child relationships
|
||||
|
||||
---
|
||||
|
||||
**System Design**: Unified workflow architecture featuring ultra-fast session management, JSON-only data model, and consistent file structure across all workflow types.
|
||||
**System ensures**: Unified workflow architecture with ultra-fast session management, JSON-only data model, and unified file structure for all workflows regardless of complexity.
|
||||
Reference in New Issue
Block a user