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

refactor: Enforce 10-task limit and file cohesion across workflow system

Browse Source 
- Update workflow-architecture.md: Streamline structure, enforce 10-task hard limit
- Update workflow plan.md: Add file cohesion rules, similar functionality warnings
- Update task breakdown.md: Manual breakdown controls, conflict detection
- Update task-core.md: Sync JSON schema with workflow-architecture.md
- Establish consistent 10-task maximum across all workflow commands
- Add file cohesion enforcement to prevent splitting related files
- Replace "Complex" classification with "Over-scope" requiring re-planning

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-09-15 21:55:28 +08:00
parent 2b7aad6d65
commit 9371af8d8d
17 changed files with 878 additions and 776 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.claude/agents/action-planning-agent.md
View File

@@ -102,7 +102,7 @@ For tasks requiring >5 subtasks or spanning >3 modules:
### 4. Document Generation ### 4. Document Generation
Create workflow documents with proper linking: Create workflow documents with proper linking:
- Todo items link to task JSON: `[📋 Details](./.task/impl-XXX.json)` - Todo items link to task JSON: `[📋 Details](./.task/IMPL-XXX.json)`
- Completed tasks link to summaries: `[✅ Summary](./.summaries/IMPL-XXX-summary.md)` - Completed tasks link to summaries: `[✅ Summary](./.summaries/IMPL-XXX-summary.md)`
- Consistent ID schemes (IMPL-XXX, IMPL-XXX.Y, IMPL-XXX.Y.Z) - Consistent ID schemes (IMPL-XXX, IMPL-XXX.Y, IMPL-XXX.Y.Z)

95
.claude/agents/code-developer.md
View File

@@ -37,27 +37,34 @@ You are a code execution specialist focused on implementing high-quality, produc
``` ```
IF context sufficient for implementation: IF context sufficient for implementation:
→ Proceed with execution → Proceed with execution
ELIF context insufficient OR task has analysis marker: ELIF context insufficient OR task has flow control marker:
→ Check for [MULTI_STEP_ANALYSIS] marker: → Check for [FLOW_CONTROL] marker:
- Execute comprehensive pre-analysis BEFORE implementation begins - Execute flow_control.pre_analysis steps sequentially BEFORE implementation
- Process each step with specified method (gemini/codex/manual/auto-detected) - Process each step with command execution and context accumulation
- Expand brief actions into comprehensive analysis tasks - Load dependency summaries and parent task context
→ Extract patterns and conventions - Execute CLI tools, scripts, and agent commands as specified
- Pass context between steps via [variable_name] references
→ Extract patterns and conventions from accumulated context
→ Proceed with execution → Proceed with execution
``` ```
**Pre-Execution Analysis System**: **Flow Control Execution System**:
- **[MULTI_STEP_ANALYSIS]**: Mandatory pre-execution analysis flag - **[FLOW_CONTROL]**: Mandatory flow control execution flag
- **Trigger**: Auto-added when task.pre_analysis is an array (default format) - **Sequential Processing**: Execute pre_analysis steps in order with context flow
- **Action**: MUST run multi-step pre-analysis first to gather comprehensive context - **Variable Accumulation**: Build comprehensive context through step chain
- **Purpose**: Ensures code aligns with existing patterns through comprehensive pre-execution analysis - **Error Handling**: Apply per-step error strategies (skip_optional, fail, retry_once, manual_intervention)
- **Trigger**: Auto-added when task.flow_control.pre_analysis exists (default format)
- **Action**: MUST run flow control steps first to gather comprehensive context
- **Purpose**: Ensures code aligns with existing patterns through comprehensive context accumulation
**Pre-Analysis CLI Usage Standards**: **Flow Control Execution Standards**:
- **Multi-step Processing**: Execute each analysis step sequentially with specified templates - **Sequential Step Processing**: Execute flow_control.pre_analysis steps in defined order
- **Method Selection**: Use method specified in each step (gemini/codex/manual/auto-detected) - **Context Variable Handling**: Process [variable_name] references in commands
- **CLI Commands**: - **Command Types**:
- **Gemini**: `bash(~/.claude/scripts/gemini-wrapper -p "$(cat template_path) [expanded_action]")` - **CLI Analysis**: Execute gemini/codex commands with context variables
- **Codex**: `bash(codex --full-auto exec "$(cat template_path) [expanded_action]")` - **Dependency Loading**: Read summaries from context.depends_on automatically
- **Context Accumulation**: Pass step outputs to subsequent steps via [variable_name]
- **Error Handling**: Apply on_error strategies per step (skip_optional, fail, retry_once, manual_intervention)
- **Follow Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md and @~/.claude/workflows/tools-implementation-guide.md - **Follow Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md and @~/.claude/workflows/tools-implementation-guide.md
@@ -114,7 +121,7 @@ ELIF context insufficient OR task has analysis marker:
``` ```
.workflow/WFS-[session-id]/ # (Path provided in session context) .workflow/WFS-[session-id]/ # (Path provided in session context)
├── TODO_LIST.md # Progress tracking document ├── TODO_LIST.md # Progress tracking document
├── .task/impl-*.json # Task definitions (source of truth) ├── .task/IMPL-*.json # Task definitions (source of truth)
└── .summaries/IMPL-*.md # Task completion summaries └── .summaries/IMPL-*.md # Task completion summaries
``` ```
@@ -123,12 +130,12 @@ ELIF context insufficient OR task has analysis marker:
# Tasks: User Authentication System # Tasks: User Authentication System
## Task Progress ## Task Progress
▸ **IMPL-001**: Create auth module → [📋](./.task/impl-001.json) ▸ **IMPL-001**: Create auth module → [📋](./.task/IMPL-001.json)
- [x] **IMPL-001.1**: Database schema → [📋](./.task/impl-001.1.json) | [✅](./.summaries/IMPL-001.1.md) - [x] **IMPL-001.1**: Database schema → [📋](./.task/IMPL-001.1.json) | [✅](./.summaries/IMPL-001.1.md)
- [ ] **IMPL-001.2**: API endpoints → [📋](./.task/impl-001.2.json) - [ ] **IMPL-001.2**: API endpoints → [📋](./.task/IMPL-001.2.json)
- [ ] **IMPL-002**: Add JWT validation → [📋](./.task/impl-002.json) - [ ] **IMPL-002**: Add JWT validation → [📋](./.task/IMPL-002.json)
- [ ] **IMPL-003**: OAuth2 integration → [📋](./.task/impl-003.json) - [ ] **IMPL-003**: OAuth2 integration → [📋](./.task/IMPL-003.json)
## Status Legend ## Status Legend
- `▸` = Container task (has subtasks) - `▸` = Container task (has subtasks)
@@ -141,14 +148,43 @@ ELIF context insufficient OR task has analysis marker:
- Use exact paths from session context (e.g., `.workflow/WFS-[session-id]/.summaries/`) - Use exact paths from session context (e.g., `.workflow/WFS-[session-id]/.summaries/`)
- Link summary in TODO_LIST.md using relative path - Link summary in TODO_LIST.md using relative path
**Summary Template**: **Enhanced Summary Template**:
```markdown ```markdown
# Task: [Task-ID] [Name] # Task: [Task-ID] [Name]
## Completed ## Implementation Summary
- Files modified: [list]
- Tests added: [count] ### Files Modified
- Key changes: [brief list] - `[file-path]`: [brief description of changes]
- `[file-path]`: [brief description of changes]
### Content Added
- **[ComponentName]** (`[file-path]`): [purpose/functionality]
- **[functionName()]** (`[file:line]`): [purpose/parameters/returns]
- **[InterfaceName]** (`[file:line]`): [properties/purpose]
- **[CONSTANT_NAME]** (`[file:line]`): [value/purpose]
## Outputs for Dependent Tasks
### Available Components
```typescript
// New components ready for import/use
import { ComponentName } from '[import-path]';
import { functionName } from '[import-path]';
import { InterfaceName } from '[import-path]';
```
### Integration Points
- **[Component/Function]**: Use `[import-statement]` to access `[functionality]`
- **[API Endpoint]**: `[method] [url]` for `[purpose]`
- **[Configuration]**: Set `[config-key]` in `[config-file]` for `[behavior]`
### Usage Examples
```typescript
// Basic usage patterns for new components
const example = new ComponentName(params);
const result = functionName(input);
```
## Status: ✅ Complete ## Status: ✅ Complete
``` ```
@@ -178,6 +214,7 @@ Before completing any task, verify:
- [ ] ASCII-only characters (no emojis/Unicode) - [ ] ASCII-only characters (no emojis/Unicode)
- [ ] GBK encoding compatible - [ ] GBK encoding compatible
- [ ] TODO list updated - [ ] TODO list updated
- [ ] Comprehensive summary document generated with all new components/methods listed
## Key Reminders ## Key Reminders
@@ -196,3 +233,5 @@ Before completing any task, verify:
- Follow existing patterns and conventions - Follow existing patterns and conventions
- Handle errors appropriately - Handle errors appropriately
- Keep functions small and focused - Keep functions small and focused
- Generate detailed summary documents with complete component/method listings
- Document all new interfaces, types, and constants for dependent task reference

81
.claude/agents/code-review-test-agent.md
View File

@@ -49,33 +49,33 @@ You will review code changes AND handle test implementation by understanding the
## Analysis CLI Context Activation Rules ## Analysis CLI Context Activation Rules
**🎯 Analysis Marker Detection** **🎯 Flow Control Detection**
When task assignment includes analysis marker: When task assignment includes flow control marker:
- **[MULTI_STEP_ANALYSIS]**: Execute sequential analysis steps with specified templates, expanding brief actions - **[FLOW_CONTROL]**: Execute sequential flow control steps with context accumulation and variable passing
**Multi-Step Analysis Support**: **Flow Control Support**:
- **Process pre_analysis array**: Handle multi-step array format - **Process flow_control.pre_analysis array**: Handle multi-step flow control format
- **Expand brief actions**: Convert 2-3 word descriptions into comprehensive analysis tasks - **Context variable handling**: Process [variable_name] references in commands
- **Sequential execution**: Execute each analysis step in order, accumulating context - **Sequential execution**: Execute each step in order, accumulating context through variables
- **Template integration**: Use full template paths for enhanced analysis prompts - **Error handling**: Apply per-step error strategies
**Context Gathering Decision Logic**: **Context Gathering Decision Logic**:
``` ```
IF task contains [MULTI_STEP_ANALYSIS] flag: IF task contains [FLOW_CONTROL] flag:
→ Execute each analysis step sequentially with specified templates → Execute each flow control step sequentially with context variables
→ Expand brief actions into comprehensive analysis tasks → Load dependency summaries from connections.depends_on
→ Use method specified in each step (gemini/codex/manual/auto-detected) → Process [variable_name] references in commands
→ Accumulate results for comprehensive context → Accumulate context through step outputs
ELIF reviewing >3 files OR security changes OR architecture modifications: ELIF reviewing >3 files OR security changes OR architecture modifications:
→ Execute default multi-step analysis (AUTO-TRIGGER) → Execute default flow control analysis (AUTO-TRIGGER)
ELSE: ELSE:
→ Proceed with review using standard quality checks → Proceed with review using standard quality checks
``` ```
## Multi-Step Pre-Analysis Phase (Execute When Required) ## Flow Control Pre-Analysis Phase (Execute When Required)
### Multi-Step Analysis Execution ### Flow Control Execution
When [MULTI_STEP_ANALYSIS] flag is present, execute comprehensive pre-review analysis: When [FLOW_CONTROL] flag is present, execute comprehensive pre-review analysis:
Process each step from pre_analysis array sequentially: Process each step from pre_analysis array sequentially:
@@ -163,12 +163,12 @@ if [FAST_MODE]: apply targeted review process
- Concurrency issues (race conditions, deadlocks) - Concurrency issues (race conditions, deadlocks)
- Input validation and sanitization - Input validation and sanitization
### Code Quality ### Code Quality & Dependencies
- Import/export correctness and path validation
- Missing or unused imports identification
- Circular dependency detection
- Single responsibility principle - Single responsibility principle
- Clear variable and function names - Clear variable and function names
- Appropriate abstraction levels
- No code duplication (DRY principle)
- Proper documentation for complex logic
### Performance ### Performance
- Algorithm complexity (time and space) - Algorithm complexity (time and space)
@@ -201,40 +201,15 @@ if [FAST_MODE]: apply targeted review process
```markdown ```markdown
# Review Summary: [Task-ID] [Review Name] # Review Summary: [Task-ID] [Review Name]
## Review Scope ## Issues Fixed
- [Files/components reviewed] - [Bugs/security issues resolved]
- [Lines of code reviewed] - [Missing imports added]
- [Review depth applied: Deep/Fast Mode] - [Unused imports removed]
- [Import path errors corrected]
## Critical Findings ## Tests Added
- [Bugs found and fixed] - [Test files created/updated]
- [Security issues identified]
- [Breaking changes prevented]
## Quality Improvements
- [Code quality enhancements]
- [Performance optimizations]
- [Architecture improvements]
## Test Implementation
- [Tests written or updated]
- [Coverage improvements] - [Coverage improvements]
- [Test quality enhancements]
## Compliance Check
- [Standards adherence verified]
- [Convention violations fixed]
- [Documentation completeness]
## Recommendations Implemented
- [Suggested improvements applied]
- [Refactoring performed]
- [Test coverage added]
## Outstanding Items
- [Deferred improvements]
- [Future considerations]
- [Technical debt noted]
## Approval Status ## Approval Status
- [x] Approved / [ ] Approved with minor changes / [ ] Needs revision / [ ] Rejected - [x] Approved / [ ] Approved with minor changes / [ ] Needs revision / [ ] Rejected

42
.claude/agents/conceptual-planning-agent.md
View File

@@ -37,8 +37,8 @@ You are a conceptual planning specialist focused on single-role strategic thinki
## Analysis Method Integration ## Analysis Method Integration
### Detection and Activation ### Detection and Activation
When receiving task prompt, check for analysis marker: When receiving task prompt, check for flow control marker:
- **[MULTI_STEP_ANALYSIS]** - Execute mandatory multi-step pre-execution analysis - **[FLOW_CONTROL]** - Execute mandatory flow control steps with context accumulation
- **ASSIGNED_ROLE** - Extract the specific role for focused analysis - **ASSIGNED_ROLE** - Extract the specific role for focused analysis
- **ANALYSIS_DIMENSIONS** - Load role-specific analysis dimensions - **ANALYSIS_DIMENSIONS** - Load role-specific analysis dimensions
@@ -49,28 +49,28 @@ def handle_analysis_markers(prompt):
dimensions = extract_value("ANALYSIS_DIMENSIONS", prompt) dimensions = extract_value("ANALYSIS_DIMENSIONS", prompt)
topic = extract_topic(prompt) topic = extract_topic(prompt)
if "[MULTI_STEP_ANALYSIS]" in prompt: if "[FLOW_CONTROL]" in prompt:
analysis_steps = extract_pre_analysis_array(prompt) flow_steps = extract_flow_control_array(prompt)
for step in analysis_steps: context_vars = {}
for step in flow_steps:
step_name = step["step"]
action = step["action"] action = step["action"]
template = step["template"] command = step["command"]
method = step["method"] output_to = step.get("output_to")
on_error = step.get("on_error", "fail")
expanded_action = expand_brief_action(action, role, topic) # Process context variables in command
processed_command = process_context_variables(command, context_vars)
if method == "gemini": try:
result = execute_gemini_cli( result = execute_command(processed_command, role_context=role, topic=topic)
command=f"bash(~/.claude/scripts/gemini-wrapper -p \"$(cat {template}) {expanded_action}\")", if output_to:
role_context=role, context_vars[output_to] = result
topic=topic except Exception as e:
) handle_step_error(e, on_error, step_name)
elif method == "codex":
result = execute_codex_cli( integrate_flow_results(context_vars, role)
command=f"bash(codex --full-auto exec \"$(cat {template}) {expanded_action}\")",
role_context=role,
topic=topic
)
integrate_autonomous_insights(result, role)
``` ```
### Role-Specific Analysis Dimensions ### Role-Specific Analysis Dimensions

2
.claude/commands/gemini/execute.md
View File

@@ -75,7 +75,7 @@ model: sonnet
# Execute specific workflow task # Execute specific workflow task
/gemini:execute IMPL-001 /gemini:execute IMPL-001
# Loads from: .task/impl-001.json # Loads from: .task/IMPL-001.json
# Uses: task context, brainstorming refs, scope definitions # Uses: task context, brainstorming refs, scope definitions
# Updates: workflow status, generates summary # Updates: workflow status, generates summary
``` ```

120
.claude/commands/task/breakdown.md
View File

@@ -15,25 +15,34 @@ examples:
Breaks down complex tasks into executable subtasks with context inheritance and agent assignment. Breaks down complex tasks into executable subtasks with context inheritance and agent assignment.
## Core Principles ## Core Principles
**Task System:** @~/.claude/workflows/task-core.md **Task System:** @~/.claude/workflows/workflow-architecture.md
**File Cohesion:** Related files must stay in same task
**10-Task Limit:** Total tasks cannot exceed 10 (triggers re-scoping)
## Core Features ## Core Features
⚠️ **CRITICAL**: Check for active session before breakdown to avoid conflicts. ⚠️ **CRITICAL**: Manual breakdown with safety controls to prevent file conflicts and task limit violations.
### Breakdown Process ### Breakdown Process
1. **Session Check**: Verify active session contains parent task 1. **Session Check**: Verify active session contains parent task
2. **Task Validation**: Ensure parent is `pending` status 2. **Task Validation**: Ensure parent is `pending` status
3. **AI Decomposition**: Generate subtasks based on parent title 3. **10-Task Limit Check**: Verify breakdown won't exceed total limit
4. **Context Distribution**: Inherit parent requirements and scope 4. **Manual Decomposition**: User defines subtasks with validation
5. **Agent Assignment**: Auto-assign agents based on subtask type 5. **File Conflict Detection**: Warn if same files appear in multiple subtasks
6. **Similar Function Warning**: Alert if subtasks have overlapping functionality
7. **Context Distribution**: Inherit parent requirements and scope
8. **Agent Assignment**: Auto-assign agents based on subtask type
9. **TODO_LIST Update**: Regenerate TODO_LIST.md with new structure
### Breakdown Rules ### Breakdown Rules
- Only `pending` tasks can be broken down - Only `pending` tasks can be broken down
- **Manual breakdown only**: Automated breakdown disabled to prevent violations
- Parent becomes `container` status (not executable) - Parent becomes `container` status (not executable)
- Subtasks use format: impl-N.M (max 2 levels) - Subtasks use format: IMPL-N.M (max 2 levels)
- Context flows from parent to subtasks - Context flows from parent to subtasks
- All relationships tracked in JSON - All relationships tracked in JSON
- **10-task limit enforced**: Breakdown rejected if total would exceed 10 tasks
- **File cohesion preserved**: Same files cannot be split across subtasks
## Usage ## Usage
@@ -45,23 +54,33 @@ Breaks down complex tasks into executable subtasks with context inheritance and
Interactive process: Interactive process:
``` ```
Task: Build authentication module Task: Build authentication module
Current total tasks: 6/10
Suggested subtasks: ⚠️ MANUAL BREAKDOWN REQUIRED
1. Design authentication schema Define subtasks manually (remaining capacity: 4 tasks):
2. Implement core auth logic
3. Add security middleware
4. Write comprehensive tests
Accept breakdown? (y/n): y 1. Enter subtask title: User authentication core
Focus files: models/User.js, routes/auth.js, middleware/auth.js
✅ Task impl-1 broken down: 2. Enter subtask title: OAuth integration
▸ impl-1: Build authentication module (container) Focus files: services/OAuthService.js, routes/oauth.js
├── impl-1.1: Design schema → planning-agent
├── impl-1.2: Implement logic → code-developer
├── impl-1.3: Add middleware → code-developer
└── impl-1.4: Write tests → code-review-test-agent
Files created: .task/impl-1.json + 4 subtask files ⚠️ FILE CONFLICT DETECTED:
- routes/auth.js appears in multiple subtasks
- Recommendation: Merge related authentication routes
⚠️ SIMILAR FUNCTIONALITY WARNING:
- "User authentication" and "OAuth integration" both handle auth
- Consider combining into single task
Proceed with breakdown? (y/n): y
✅ Task IMPL-1 broken down:
▸ IMPL-1: Build authentication module (container)
├── IMPL-1.1: User authentication core → code-developer
└── IMPL-1.2: OAuth integration → code-developer
Files updated: .task/IMPL-1.json + 2 subtask files + TODO_LIST.md
``` ```
## Decomposition Logic ## Decomposition Logic
@@ -77,9 +96,39 @@ Files created: .task/impl-1.json + 4 subtask files
- Scope refined for specific subtask - Scope refined for specific subtask
- Implementation details distributed appropriately - Implementation details distributed appropriately
## Safety Controls
### File Conflict Detection
**Validates file cohesion across subtasks:**
- Scans `focus_paths` in all subtasks
- Warns if same file appears in multiple subtasks
- Suggests merging subtasks with overlapping files
- Blocks breakdown if critical conflicts detected
### Similar Functionality Detection
**Prevents functional overlap:**
- Analyzes subtask titles for similar keywords
- Warns about potential functional redundancy
- Suggests consolidation of related functionality
- Examples: "user auth" + "login system" → merge recommendation
### 10-Task Limit Enforcement
**Hard limit compliance:**
- Counts current total tasks in session
- Calculates breakdown impact on total
- Rejects breakdown if would exceed 10 tasks
- Suggests re-scoping if limit reached
### Manual Control Requirements
**User-driven breakdown only:**
- No automatic subtask generation
- User must define each subtask title and scope
- Real-time validation during input
- Confirmation required before execution
## Implementation Details ## Implementation Details
See @~/.claude/workflows/task-core.md for: See @~/.claude/workflows/workflow-architecture.md for:
- Complete task JSON schema - Complete task JSON schema
- Implementation field structure - Implementation field structure
- Context inheritance rules - Context inheritance rules
@@ -92,12 +141,17 @@ See @~/.claude/workflows/task-core.md for:
2. Task found in session 2. Task found in session
3. Task status is `pending` 3. Task status is `pending`
4. Not already broken down 4. Not already broken down
5. **10-task limit compliance**: Total tasks + new subtasks ≤ 10
6. **Manual mode enabled**: No automatic breakdown allowed
### Post-breakdown Actions ### Post-breakdown Actions
1. Update parent to `container` status 1. Update parent to `container` status
2. Create subtask JSON files 2. Create subtask JSON files
3. Update parent subtasks list 3. Update parent subtasks list
4. Update session stats 4. Update session stats
5. **Regenerate TODO_LIST.md** with new hierarchy
6. Validate file paths in focus_paths
7. Update session task count
## Examples ## Examples
@@ -115,17 +169,35 @@ See @~/.claude/workflows/task-core.md for:
```bash ```bash
# Task not found # Task not found
❌ Task impl-5 not found ❌ Task IMPL-5 not found
# Already broken down # Already broken down
⚠️ Task impl-1 already has subtasks ⚠️ Task IMPL-1 already has subtasks
# Wrong status # Wrong status
❌ Cannot breakdown completed task impl-2 ❌ Cannot breakdown completed task IMPL-2
# 10-task limit exceeded
❌ Breakdown would exceed 10-task limit (current: 8, proposed: 4)
Suggestion: Re-scope project into smaller iterations
# File conflicts detected
⚠️ File conflict: routes/auth.js appears in IMPL-1.1 and IMPL-1.2
Recommendation: Merge subtasks or redistribute files
# Similar functionality warning
⚠️ Similar functions detected: "user login" and "authentication"
Consider consolidating related functionality
# Manual breakdown required
❌ Automatic breakdown disabled. Use manual breakdown process.
``` ```
## Related Commands ## Related Commands
- `/task:create` - Create new tasks - `/task:create` - Create new tasks
- `/task:execute` - Execute subtasks - `/task:execute` - Execute subtasks
- `/context` - View task hierarchy - `/workflow:status` - View task hierarchy
- `/workflow:plan` - Plan within 10-task limit
**System ensures**: Manual breakdown control with file cohesion enforcement, similar functionality detection, and 10-task limit compliance

20
.claude/commands/task/create.md
View File

@@ -20,7 +20,7 @@ Creates new implementation tasks with automatic context awareness and ID generat
## Core Features ## Core Features
### Automatic Behaviors ### Automatic Behaviors
- **ID Generation**: Auto-generates impl-N format (max 2 levels) - **ID Generation**: Auto-generates IMPL-N format (max 2 levels)
- **Context Inheritance**: Inherits from active workflow session - **Context Inheritance**: Inherits from active workflow session
- **JSON Creation**: Creates task JSON in active session - **JSON Creation**: Creates task JSON in active session
- **Status Setting**: Initial status = "pending" - **Status Setting**: Initial status = "pending"
@@ -42,7 +42,7 @@ Creates new implementation tasks with automatic context awareness and ID generat
Output: Output:
``` ```
✅ Task created: impl-1 ✅ Task created: IMPL-1
Title: Build authentication module Title: Build authentication module
Type: feature Type: feature
Agent: code-developer Agent: code-developer
@@ -59,7 +59,7 @@ Status: pending
## Task Creation Process ## Task Creation Process
1. **Session Validation**: Check active workflow session 1. **Session Validation**: Check active workflow session
2. **ID Generation**: Auto-increment impl-N 2. **ID Generation**: Auto-increment IMPL-N
3. **Context Inheritance**: Load workflow context 3. **Context Inheritance**: Load workflow context
4. **Implementation Setup**: Initialize implementation field 4. **Implementation Setup**: Initialize implementation field
5. **Agent Assignment**: Select appropriate agent 5. **Agent Assignment**: Select appropriate agent
@@ -85,7 +85,7 @@ Suggest running: gemini analysis for file locations and dependencies
## File Management ## File Management
### JSON Task File ### JSON Task File
- **Location**: `.task/impl-[N].json` in active session - **Location**: `.task/IMPL-[N].json` in active session
- **Content**: Complete task with implementation field - **Content**: Complete task with implementation field
- **Updates**: Session stats only - **Updates**: Session stats only
@@ -100,7 +100,7 @@ Suggest running: gemini analysis for file locations and dependencies
Tasks inherit from: Tasks inherit from:
1. **Active Session** - Requirements and scope from workflow-session.json 1. **Active Session** - Requirements and scope from workflow-session.json
2. **Planning Document** - Context from IMPL_PLAN.md 2. **Planning Document** - Context from IMPL_PLAN.md
3. **Parent Task** - For subtasks (impl-N.M format) 3. **Parent Task** - For subtasks (IMPL-N.M format)
## Agent Assignment ## Agent Assignment
@@ -125,12 +125,12 @@ Based on task type and title keywords:
→ Use: /workflow init "project name" → Use: /workflow init "project name"
# Duplicate task # Duplicate task
⚠️ Similar task exists: impl-3 ⚠️ Similar task exists: IMPL-3
→ Continue anyway? (y/n) → Continue anyway? (y/n)
# Max depth exceeded # Max depth exceeded
❌ Cannot create impl-1.2.1 (max 2 levels) ❌ Cannot create IMPL-1.2.1 (max 2 levels)
→ Use: impl-2 for new main task → Use: IMPL-2 for new main task
``` ```
## Examples ## Examples
@@ -139,7 +139,7 @@ Based on task type and title keywords:
```bash ```bash
/task:create "Implement user authentication" /task:create "Implement user authentication"
✅ Created impl-1: Implement user authentication ✅ Created IMPL-1: Implement user authentication
Type: feature Type: feature
Agent: code-developer Agent: code-developer
Status: pending Status: pending
@@ -149,7 +149,7 @@ Status: pending
```bash ```bash
/task:create "Fix login validation bug" --type=bugfix /task:create "Fix login validation bug" --type=bugfix
✅ Created impl-2: Fix login validation bug ✅ Created IMPL-2: Fix login validation bug
Type: bugfix Type: bugfix
Agent: code-developer Agent: code-developer
Status: pending Status: pending

16
.claude/commands/task/execute.md
View File

@@ -4,9 +4,9 @@ description: Execute tasks with appropriate agents and context-aware orchestrati
usage: /task:execute <task-id> usage: /task:execute <task-id>
argument-hint: task-id argument-hint: task-id
examples: examples:
- /task:execute impl-1 - /task:execute IMPL-1
- /task:execute impl-1.2 - /task:execute IMPL-1.2
- /task:execute impl-3 - /task:execute IMPL-3
--- ---
### 🚀 **Command Overview: `/task:execute`** ### 🚀 **Command Overview: `/task:execute`**
@@ -134,7 +134,7 @@ This is the simplified data structure loaded to provide context for task executi
```json ```json
{ {
"task": { "task": {
"id": "impl-1", "id": "IMPL-1",
"title": "Build authentication module", "title": "Build authentication module",
"type": "feature", "type": "feature",
"status": "active", "status": "active",
@@ -147,8 +147,8 @@ This is the simplified data structure loaded to provide context for task executi
}, },
"relations": { "relations": {
"parent": null, "parent": null,
"subtasks": ["impl-1.1", "impl-1.2"], "subtasks": ["IMPL-1.1", "IMPL-1.2"],
"dependencies": ["impl-0"] "dependencies": ["IMPL-0"]
}, },
"implementation": { "implementation": {
"files": [ "files": [
@@ -252,10 +252,10 @@ Different agents receive context tailored to their function, including implement
### 📝 **Simplified Summary Template** ### 📝 **Simplified Summary Template**
Optional summary file generated at `.summaries/impl-[task-id]-summary.md`. Optional summary file generated at `.summaries/IMPL-[task-id]-summary.md`.
```markdown ```markdown
# Task Summary: impl-1 Build Authentication Module # Task Summary: IMPL-1 Build Authentication Module
## What Was Done ## What Was Done
- Created src/auth/login.ts with JWT validation - Created src/auth/login.ts with JWT validation

32
.claude/commands/task/replan.md
View File

@@ -4,9 +4,9 @@ description: Replan individual tasks with detailed user input and change trackin
usage: /task:replan <task-id> [input] usage: /task:replan <task-id> [input]
argument-hint: task-id ["text"|file.md|ISS-001] argument-hint: task-id ["text"|file.md|ISS-001]
examples: examples:
- /task:replan impl-1 "Add OAuth2 authentication support" - /task:replan IMPL-1 "Add OAuth2 authentication support"
- /task:replan impl-1 updated-specs.md - /task:replan IMPL-1 updated-specs.md
- /task:replan impl-1 ISS-001 - /task:replan IMPL-1 ISS-001
--- ---
# Task Replan Command (/task:replan) # Task Replan Command (/task:replan)
@@ -29,24 +29,24 @@ Replans individual tasks with multiple input options, change tracking, and versi
### Direct Text (Default) ### Direct Text (Default)
```bash ```bash
/task:replan impl-1 "Add OAuth2 authentication support" /task:replan IMPL-1 "Add OAuth2 authentication support"
``` ```
### File-based Input ### File-based Input
```bash ```bash
/task:replan impl-1 updated-specs.md /task:replan IMPL-1 updated-specs.md
``` ```
Supports: .md, .txt, .json, .yaml Supports: .md, .txt, .json, .yaml
### Issue Reference ### Issue Reference
```bash ```bash
/task:replan impl-1 ISS-001 /task:replan IMPL-1 ISS-001
``` ```
Loads issue description and requirements Loads issue description and requirements
### Interactive Mode ### Interactive Mode
```bash ```bash
/task:replan impl-1 --interactive /task:replan IMPL-1 --interactive
``` ```
Guided step-by-step modification process with validation Guided step-by-step modification process with validation
@@ -65,14 +65,14 @@ Guided step-by-step modification process with validation
Tasks maintain version history: Tasks maintain version history:
```json ```json
{ {
"id": "impl-1", "id": "IMPL-1",
"version": "1.2", "version": "1.2",
"replan_history": [ "replan_history": [
{ {
"version": "1.2", "version": "1.2",
"reason": "Add OAuth2 support", "reason": "Add OAuth2 support",
"input_source": "direct_text", "input_source": "direct_text",
"backup_location": ".task/versions/impl-1-v1.1.json" "backup_location": ".task/versions/IMPL-1-v1.1.json"
} }
] ]
} }
@@ -83,9 +83,9 @@ Tasks maintain version history:
### File Structure ### File Structure
``` ```
.task/ .task/
├── impl-1.json # Current version ├── IMPL-1.json # Current version
├── versions/ ├── versions/
│ └── impl-1-v1.1.json # Previous backup │ └── IMPL-1-v1.1.json # Previous backup
└── [new subtasks as needed] └── [new subtasks as needed]
``` ```
@@ -135,7 +135,7 @@ Updates workflow-session.json with:
## Rollback Support ## Rollback Support
```bash ```bash
/task:replan impl-1 --rollback v1.1 /task:replan IMPL-1 --rollback v1.1
Rollback to version 1.1: Rollback to version 1.1:
- Restore task from backup - Restore task from backup
@@ -151,7 +151,7 @@ Confirm rollback? (y/n): y
### Text Input ### Text Input
```bash ```bash
/task:replan impl-1 "Add OAuth2 authentication support" /task:replan IMPL-1 "Add OAuth2 authentication support"
Processing changes... Processing changes...
Proposed updates: Proposed updates:
@@ -167,7 +167,7 @@ Apply changes? (y/n): y
### File Input ### File Input
```bash ```bash
/task:replan impl-2 requirements.md /task:replan IMPL-2 requirements.md
Loading requirements.md... Loading requirements.md...
Applying specification changes... Applying specification changes...
@@ -180,11 +180,11 @@ Applying specification changes...
```bash ```bash
# Task not found # Task not found
❌ Task impl-5 not found ❌ Task IMPL-5 not found
→ Check task ID with /context → Check task ID with /context
# Task completed # Task completed
⚠️ Task impl-1 is completed (cannot replan) ⚠️ Task IMPL-1 is completed (cannot replan)
→ Create new task for additional work → Create new task for additional work
# File not found # File not found

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

@@ -23,20 +23,22 @@ The intelligent execution approach focuses on:
- **Dynamic task orchestration** - Coordinate based on discovered task relationships - **Dynamic task orchestration** - Coordinate based on discovered task relationships
- **Progress tracking** - Update task status after agent completion - **Progress tracking** - Update task status after agent completion
**Analysis Marker**: **Flow Control Execution**:
- **[MULTI_STEP_ANALYSIS]**: Indicates sequential pre-execution analysis required - **[FLOW_CONTROL]**: Indicates sequential flow control execution required
- **Auto-trigger**: When task.pre_analysis is an array (default format) - **Auto-trigger**: When task.flow_control.pre_analysis is an array (default format)
- **Agent Action**: Execute comprehensive pre-analysis BEFORE implementation begins - **Agent Action**: Execute flow control steps sequentially BEFORE implementation begins
- Process each step sequentially with specified templates and methods - Process each step with command execution and context accumulation
- Expand brief actions into full analysis tasks - Load dependency summaries and parent task context
- Gather context, understand patterns, identify requirements - Execute CLI tools, scripts, and agent commands as specified
- Use method specified in each step (gemini/codex/manual/auto-detected) - Pass context between steps via named variables
- Handle errors according to per-step error strategies
**pre_analysis to Marker Mapping**: **Flow Control Step Processing**:
- **Array format (multi-step pre-analysis)**: - **Sequential Execution**: Steps processed in order with context flow
- Add [MULTI_STEP_ANALYSIS] - triggers comprehensive pre-execution analysis - Each step can use outputs from previous steps via ${variable_name}
- Agent processes each step with specified method (gemini/codex/manual/auto-detected) - Dependency summaries loaded automatically from .summaries/
- Agent expands each action into comprehensive analysis based on template - Context accumulates through the execution chain
- Error handling per step (skip_optional, fail, retry_once, manual_intervention)
## Execution Flow ## Execution Flow
@@ -53,7 +55,7 @@ Workflow Discovery:
**Discovery Logic:** **Discovery Logic:**
- **Folder Detection**: Use provided folder or find current active session - **Folder Detection**: Use provided folder or find current active session
- **Task Inventory**: Load all impl-*.json files from .task/ directory - **Task Inventory**: Load all IMPL-*.json files from .task/ directory
- **Status Analysis**: Check pending/active/completed/blocked states - **Status Analysis**: Check pending/active/completed/blocked states
- **Dependency Check**: Verify all task dependencies are met - **Dependency Check**: Verify all task dependencies are met
- **Execution Queue**: Build list of ready-to-execute tasks - **Execution Queue**: Build list of ready-to-execute tasks
@@ -66,14 +68,13 @@ Workflow Discovery:
*Session: WFS-[topic-slug]* *Session: WFS-[topic-slug]*
## Execution Plan ## Execution Plan
- [ ] **TASK-001**: [Agent: planning-agent] [MULTI_STEP_ANALYSIS] Design auth schema (impl-1.1) - [ ] **TASK-001**: [Agent: planning-agent] [FLOW_CONTROL] Design auth schema (IMPL-1.1)
- [ ] **TASK-002**: [Agent: code-developer] [MULTI_STEP_ANALYSIS] Implement auth logic (impl-1.2) - [ ] **TASK-002**: [Agent: code-developer] [FLOW_CONTROL] Implement auth logic (IMPL-1.2)
- [ ] **TASK-003**: [Agent: code-review-agent] Review implementations - [ ] **TASK-003**: [Agent: code-review-agent] Review implementations
- [ ] **TASK-004**: Update task statuses and session state - [ ] **TASK-004**: Update task statuses and session state
**Marker Legend**: **Marker Legend**:
- [MULTI_STEP_ANALYSIS] = Agent must execute multi-step pre-execution analysis - [FLOW_CONTROL] = Agent must execute flow control steps with context accumulation
- [PREPARATION_INCLUDED] = Task includes preparation phase (analyze then implement)
``` ```
### 3. Agent Context Assignment ### 3. Agent Context Assignment
@@ -82,64 +83,56 @@ For each executable task:
```json ```json
{ {
"task": { "task": {
"id": "impl-1.1", "id": "IMPL-1.1",
"title": "Design auth schema", "title": "Design auth schema",
"status": "pending",
"meta": {
"type": "feature",
"agent": "code-developer"
},
"context": { "context": {
"requirements": ["JWT authentication", "User model design"], "requirements": ["JWT authentication", "User model design"],
"scope": ["src/auth/models/*"], "focus_paths": ["src/auth/models", "tests/auth"],
"acceptance": ["Schema validates JWT tokens"] "acceptance": ["Schema validates JWT tokens"],
}, "parent": "IMPL-1",
"implementation": { "depends_on": [],
"files": [ "inherited": {
{ "from": "IMPL-1",
"path": "src/auth/models/User.ts", "context": ["Authentication system architecture completed"]
"location": {
"function": "UserSchema",
"lines": "10-50",
"description": "User model definition"
},
"original_code": "// Requires gemini analysis for current schema",
"modifications": {
"current_state": "Basic user model without auth fields",
"proposed_changes": [
"Add JWT token fields to schema",
"Include OAuth provider fields"
],
"logic_flow": [
"createUser() ───► validateSchema() ───► generateJWT()",
"◊─── if OAuth ───► linkProvider() ───► storeTokens()"
],
"reason": "Support modern authentication patterns",
"expected_outcome": "Flexible user schema supporting multiple auth methods"
}
}
],
"context_notes": {
"dependencies": ["mongoose", "jsonwebtoken"],
"affected_modules": ["auth-middleware", "user-service"],
"risks": [
"Schema changes require database migration",
"Existing user data compatibility"
],
"performance_considerations": "Index JWT fields for faster lookups",
"error_handling": "Graceful schema validation errors"
}, },
"shared_context": {
"auth_strategy": "JWT with refresh tokens"
}
},
"flow_control": {
"pre_analysis": [ "pre_analysis": [
{ {
"action": "analyze auth", "step": "gather_context",
"template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt", "action": "Load dependency summaries",
"method": "gemini" "command": "bash(echo 'No dependencies for this initial task')",
"output_to": "dependency_context",
"on_error": "skip_optional"
}, },
{ {
"action": "security review", "step": "analyze_patterns",
"template": "~/.claude/workflows/cli-templates/prompts/analysis/security.txt", "action": "Analyze existing auth patterns",
"method": "gemini" "command": "bash(~/.claude/scripts/gemini-wrapper -p '@{src/auth/**/*} analyze authentication patterns with context: [dependency_context]')",
"output_to": "pattern_analysis",
"on_error": "fail"
}, },
{ {
"action": "implement feature", "step": "implement",
"template": "~/.claude/workflows/cli-templates/prompts/development/feature.txt", "action": "Design JWT schema based on analysis",
"method": "codex" "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"
] ]
} }
}, },
@@ -147,61 +140,62 @@ For each executable task:
"session": "WFS-user-auth", "session": "WFS-user-auth",
"phase": "IMPLEMENT", "phase": "IMPLEMENT",
"plan_context": "Authentication system with OAuth2 support" "plan_context": "Authentication system with OAuth2 support"
}, }
"focus_modules": ["src/auth/", "tests/auth/"]
} }
``` ```
**Context Assignment Rules:** **Context Assignment Rules:**
- **Complete Context**: Use full task JSON context including implementation field for agent execution - **Complete Context**: Use full task JSON context including flow_control field for agent execution
- **Implementation Details**: Pass complete implementation.files array to agents for precise execution - **Flow Control Processing**: Execute flow_control.pre_analysis steps sequentially with context accumulation
- **Code Context**: Include original_code snippets and logic_flow diagrams in agent prompts - **Dependency Integration**: Load summaries from context.depends_on automatically
- **Risk Awareness**: Alert agents to implementation.context_notes.risks before execution - **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 - **Workflow Integration**: Include session state and IMPL_PLAN.md context
- **Scope Focus**: Direct agents to specific files from implementation.files[].path - **Focus Scope**: Direct agents to specific paths from context.focus_paths array
- **Analysis Marker**: Auto-add [MULTI_STEP_ANALYSIS] when pre_analysis is array format - **Flow Control Marker**: Auto-add [FLOW_CONTROL] when flow_control.pre_analysis exists
- **Merged Task Handling**: Add [PREPARATION_INCLUDED] marker when preparation_complexity exists - **Target File Guidance**: Use flow_control.target_files for precise file targeting
### 4. Agent Execution & Progress Tracking ### 4. Agent Execution & Progress Tracking
```bash ```bash
Task(subagent_type="code-developer", Task(subagent_type="code-developer",
prompt="[PREPARATION_INCLUDED] [MULTI_STEP_ANALYSIS] Analyze auth patterns and implement JWT authentication system prompt="[FLOW_CONTROL] Execute IMPL-1.2: Implement JWT authentication system with flow control
Task Context: impl-1.2 - Saturated task with merged preparation and execution Task Context: IMPL-1.2 - Flow control managed execution
PREPARATION PHASE (preparation_complexity: simple, estimated_prep_time: 20min): FLOW CONTROL EXECUTION:
1. Review existing auth patterns in the codebase Execute the following steps sequentially with context accumulation:
2. Check JWT library compatibility with current stack
3. Analyze current session management approach
EXECUTION PHASE: Step 1 (gather_context): Load dependency summaries
Based on preparation findings, implement JWT authentication system Command: for dep in ${depends_on}; do cat .summaries/$dep-summary.md 2>/dev/null || echo "No summary for $dep"; done
Output: dependency_context
Step 2 (analyze_patterns): Analyze existing auth patterns
Command: ~/.claude/scripts/gemini-wrapper -p '@{src/auth/**/*} analyze authentication patterns with context: [dependency_context]'
Output: pattern_analysis
Step 3 (implement): Implement JWT based on analysis
Command: codex --full-auto exec 'Implement JWT using analysis: [pattern_analysis] and context: [dependency_context]'
Session Context: Session Context:
- Workflow Directory: .workflow/WFS-user-auth/ - Workflow Directory: .workflow/WFS-user-auth/
- TODO_LIST Location: .workflow/WFS-user-auth/TODO_LIST.md - TODO_LIST Location: .workflow/WFS-user-auth/TODO_LIST.md
- Summaries Directory: .workflow/WFS-user-auth/.summaries/ - Summaries Directory: .workflow/WFS-user-auth/.summaries/
- Task JSON Location: .workflow/WFS-user-auth/.task/impl-1.2.json - Task JSON Location: .workflow/WFS-user-auth/.task/IMPL-1.2.json
Implementation Details: Implementation Guidance:
- Target File: src/auth/models/User.ts - Approach: Design flexible user schema supporting JWT and OAuth authentication
- Function: UserSchema (lines 10-50) - Target Files: src/auth/models/User.ts:UserSchema:10-50
- Current State: Basic user model without auth fields - Focus Paths: src/auth/models, tests/auth
- Required Changes: Add JWT token fields, Include OAuth provider fields - Dependencies: From context.depends_on
- Logic Flow: createUser() ───► validateSchema() ───► generateJWT() - Inherited Context: [context.inherited]
- Dependencies: mongoose, jsonwebtoken
- Risks: Schema changes require database migration, Existing user data compatibility
- Performance: Index JWT fields for faster lookups
Focus Paths (from task JSON): $(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json)
Gemini Command: ~/.claude/scripts/gemini-wrapper -p "$(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}"
IMPORTANT: IMPORTANT:
1. Document both preparation analysis results and implementation in summary 1. Execute flow control steps in sequence with error handling
2. Update TODO_LIST.md and create summary in provided directories upon completion 2. Accumulate context through step chain
3. Use preparation findings to inform implementation decisions", 3. Create comprehensive summary with 'Outputs for Dependent Tasks' section
description="Execute saturated task with preparation and implementation phases") 4. Update TODO_LIST.md upon completion",
description="Execute task with flow control step processing")
``` ```
**Execution Protocol:** **Execution Protocol:**
@@ -218,9 +212,9 @@ Task(subagent_type="code-developer",
├── workflow-session.json # Session state and stats ├── workflow-session.json # Session state and stats
├── IMPL_PLAN.md # Workflow context and requirements ├── IMPL_PLAN.md # Workflow context and requirements
├── .task/ # Task definitions ├── .task/ # Task definitions
│ ├── impl-1.json # Main tasks │ ├── IMPL-1.json # Main tasks
│ ├── impl-1.1.json # Subtasks │ ├── IMPL-1.1.json # Subtasks
│ └── impl-1.2.json # Detailed tasks │ └── IMPL-1.2.json # Detailed tasks
└── .summaries/ # Completed task summaries └── .summaries/ # Completed task summaries
``` ```
@@ -256,7 +250,7 @@ Based on discovered task data:
```bash ```bash
# Agent receives complete discovered context with saturation handling # Agent receives complete discovered context with saturation handling
Task(subagent_type="code-developer", Task(subagent_type="code-developer",
prompt="[PREPARATION_INCLUDED] [MULTI_STEP_ANALYSIS] Execute impl-1.2: Analyze and implement auth logic prompt="[FLOW_CONTROL] Execute IMPL-1.2: Analyze and implement auth logic
TASK TYPE: Saturated task (preparation_complexity: simple) TASK TYPE: Saturated task (preparation_complexity: simple)
@@ -271,17 +265,17 @@ Task(subagent_type="code-developer",
Context from discovery: Context from discovery:
- Requirements: JWT authentication, OAuth2 support - Requirements: JWT authentication, OAuth2 support
- Scope: src/auth/*, tests/auth/* - Scope: src/auth/*, tests/auth/*
- Dependencies: impl-1.1 (completed) - Dependencies: IMPL-1.1 (completed)
- Workflow: WFS-user-auth authentication system - Workflow: WFS-user-auth authentication system
Session Context: Session Context:
- Workflow Directory: .workflow/WFS-user-auth/ - Workflow Directory: .workflow/WFS-user-auth/
- TODO_LIST Location: .workflow/WFS-user-auth/TODO_LIST.md - TODO_LIST Location: .workflow/WFS-user-auth/TODO_LIST.md
- Summaries Directory: .workflow/WFS-user-auth/.summaries/ - Summaries Directory: .workflow/WFS-user-auth/.summaries/
- Task JSON: .workflow/WFS-user-auth/.task/impl-1.2.json - 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) 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}\" 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: CRITICAL:
1. Execute preparation phase first, then use findings for implementation 1. Execute preparation phase first, then use findings for implementation
@@ -295,7 +289,7 @@ Task(subagent_type="code-developer",
### Status Tracking Integration ### Status Tracking Integration
```bash ```bash
# After agent completion, update discovered task status # After agent completion, update discovered task status
update_task_status("impl-1.2", "completed") update_task_status("IMPL-1.2", "completed")
mark_dependent_tasks_ready(task_dependencies) mark_dependent_tasks_ready(task_dependencies)
``` ```
@@ -318,7 +312,7 @@ mark_dependent_tasks_ready(task_dependencies)
```json ```json
// Before execution // Before execution
{ {
"id": "impl-1.2", "id": "IMPL-1.2",
"status": "pending", "status": "pending",
"execution": { "execution": {
"attempts": 0, "attempts": 0,
@@ -328,7 +322,7 @@ mark_dependent_tasks_ready(task_dependencies)
// After execution // After execution
{ {
"id": "impl-1.2", "id": "IMPL-1.2",
"status": "completed", "status": "completed",
"execution": { "execution": {
"attempts": 1, "attempts": 1,
@@ -358,7 +352,7 @@ mark_dependent_tasks_ready(task_dependencies)
→ Check: /context for task status overview → Check: /context for task status overview
# Missing task files # Missing task files
❌ Task impl-1.2 referenced but JSON file missing ❌ Task IMPL-1.2 referenced but JSON file missing
→ Fix: /task/create or repair task references → Fix: /task/create or repair task references
``` ```
@@ -379,7 +373,7 @@ mark_dependent_tasks_ready(task_dependencies)
```bash ```bash
# After /workflow:execute completion # After /workflow:execute completion
/context # View updated task status /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 /workflow:review # Move to review phase when complete
``` ```

2
.claude/commands/workflow/issue/list.md
View File

@@ -56,7 +56,7 @@ Simple keyword-based filtering:
🔗 ISS-004: Implement rate limiting 🔗 ISS-004: Implement rate limiting
Type: Feature | Priority: Medium Type: Feature | Priority: Medium
Status: Integrated → IMPL-003 Status: Integrated → IMPL-003
Integrated: 2025-09-06 | Task: impl-3.json Integrated: 2025-09-06 | Task: IMPL-3.json
``` ```
## Summary Stats ## Summary Stats

6
.claude/commands/workflow/plan-deep.md
View File

@@ -90,9 +90,9 @@ Task(action-planning-agent):
- Execute comprehensive Gemini CLI analysis (4 dimensions) - Execute comprehensive Gemini CLI analysis (4 dimensions)
- Skip PRD processing (no PRD provided) - Skip PRD processing (no PRD provided)
- Skip session inheritance (standalone planning) - Skip session inheritance (standalone planning)
- Force MULTI_STEP_ANALYSIS flag = true - Force FLOW_CONTROL flag = true
- Set pre_analysis = multi-step array format with comprehensive analysis steps - Set pre_analysis = multi-step array format with comprehensive analysis steps
- Generate hierarchical task decomposition (max 2 levels: impl-N.M) - Generate hierarchical task decomposition (max 2 levels: IMPL-N.M)
- Create detailed IMPL_PLAN.md with subtasks - Create detailed IMPL_PLAN.md with subtasks
- Generate TODO_LIST.md for tracking - Generate TODO_LIST.md for tracking
@@ -126,7 +126,7 @@ def process_plan_deep_command(input):
TASK: {task_description} TASK: {task_description}
MANDATORY FLAGS: MANDATORY FLAGS:
- MULTI_STEP_ANALYSIS = true - FLOW_CONTROL = true
- pre_analysis = multi-step array format for comprehensive pre-analysis - pre_analysis = multi-step array format for comprehensive pre-analysis
- FORCE_PARALLEL_ANALYSIS = true - FORCE_PARALLEL_ANALYSIS = true
- SKIP_PRD = true - SKIP_PRD = true

111
.claude/commands/workflow/plan.md
View File

@@ -17,6 +17,10 @@ Creates actionable implementation plans with intelligent input source detection.
## Core Principles ## Core Principles
**File Structure:** @~/.claude/workflows/workflow-architecture.md **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
## Usage ## Usage
```bash ```bash
/workflow:plan [--AM gemini|codex] <input> /workflow:plan [--AM gemini|codex] <input>
@@ -74,36 +78,42 @@ The command automatically detects input type:
1. **Complexity Assessment**: Analyze requirements to determine total saturated task count 1. **Complexity Assessment**: Analyze requirements to determine total saturated task count
2. **Decomposition Strategy**: Based on complexity, decide: 2. **Decomposition Strategy**: Based on complexity, decide:
- Task structure (flat vs hierarchical) - Task structure (flat vs hierarchical)
- Subtask necessity (>15 tasks triggers decomposition) - Re-scoping necessity (>10 tasks triggers re-scoping)
- Task saturation level (merged vs separated) - Task saturation level (merged vs separated)
- File grouping strategy (cohesive files together)
3. **Quantity Prediction**: Calculate expected: 3. **Quantity Prediction**: Calculate expected:
- Total main tasks (IMPL-XXX) - Total main tasks (IMPL-XXX)
- Subtasks per main task (impl-N.M) - Subtasks per main task (IMPL-N.M)
- Container vs leaf task ratio - Container vs leaf task ratio
**Pre-Planning Outputs**: **Pre-Planning Outputs**:
- Complexity level: Simple (≤8) | Medium (9-15) | Complex (>15) - Complexity level: Simple (≤5) | Medium (6-10) | Over-scoped (>10, requires re-scoping)
- Decomposition approach: Flat | Two-level hierarchy - Decomposition approach: Flat | Two-level hierarchy | Re-scope required
- Estimated task count: [number] main tasks, [number] total leaf tasks - 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) - 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 **Only after completing pre-planning analysis**: Proceed to generate actual plan documents
### Complexity Detection with Saturation ### Complexity Detection with Saturation
*Based on Pre-Planning Analysis results:* *Based on Pre-Planning Analysis results:*
- **Simple**: ≤8 saturated tasks → Direct IMPL_PLAN.md - **Simple**: ≤5 saturated tasks → Direct IMPL_PLAN.md
- **Medium**: 9-15 saturated tasks → IMPL_PLAN.md + TODO_LIST.md - **Medium**: 6-10 saturated tasks → IMPL_PLAN.md + TODO_LIST.md
- **Complex**: >15 saturated tasks → Full decomposition - **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 **Note**: 1 complex preparation task = 0.5 saturated task for counting
### Task Granularity Principles ### Task Granularity Principles
- **Decompose by function, not by file**: Each task should complete a whole functional unit - **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 - **Maintain functional integrity**: Each task produces independently runnable or testable functionality
- **Implement related components together**: UI, logic, tests and other related parts in the same task - **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 - **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 ### Task Decomposition Anti-patterns
❌ **Wrong Example - File/Step-based Decomposition**: ❌ **Wrong Example - File/Step-based Decomposition**:
- IMPL-001: Create database model - IMPL-001: Create database model
- IMPL-002: Create API endpoint - IMPL-002: Create API endpoint
@@ -111,9 +121,18 @@ The command automatically detects input type:
- IMPL-004: Add routing configuration - IMPL-004: Add routing configuration
- IMPL-005: Write unit tests - IMPL-005: Write unit tests
✅ **Correct Example - Function-based Decomposition**: ❌ **Wrong Example - Same File Split Across Tasks**:
- IMPL-001: Implement user authentication feature (includes model, API, UI, tests) - IMPL-001: Add authentication routes to routes/auth.js
- IMPL-002: Implement data export functionality (includes processing logic, UI, file generation) - 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 ### Task Generation with Saturation Control
*Using decomposition strategy determined in Pre-Planning Analysis:* *Using decomposition strategy determined in Pre-Planning Analysis:*
@@ -152,45 +171,53 @@ Three analysis levels available:
3. Populates task paths automatically 3. Populates task paths automatically
### Task Saturation Assessment ### Task Saturation Assessment
Evaluates whether to merge preparation and execution: Evaluates whether to merge preparation and execution within 10-task limit:
**Default Merge Principles** (Saturated Tasks): **Default Merge Principles** (Saturated Tasks):
- All components of the same functional module - All components of the same functional module
- Frontend and backend paired implementation - Related files that work together (UI, logic, tests, config)
- Features with their corresponding tests - Features with their corresponding tests and documentation
- Configuration with its usage code - Configuration with its usage code
- Multiple small interdependent functions - Multiple small interdependent functions
- Files that share common interfaces or data structures
**Only Separate Tasks When**: **Only Separate Tasks When**:
- Completely independent functional modules (no shared code) - Completely independent functional modules (no shared code or interfaces)
- Independent services with different tech stacks (e.g., separate frontend/backend deployment) - Independent services with different tech stacks (e.g., separate deployment units)
- Modules requiring different expertise (e.g., ML model training vs Web development) - Modules requiring different expertise (e.g., ML model training vs Web development)
- Large features with clear sequential dependencies - Large features with clear sequential dependencies
- **Critical**: Would exceed 10-task limit otherwise
**Task Examples**: **File Cohesion Examples**:
- **Merged Example**: "IMPL-001: Implement user authentication system (includes JWT management, API endpoints, UI components, and tests)" - **Merged**: "IMPL-001: Implement user authentication (includes models/User.js, routes/auth.js, components/LoginForm.jsx, tests/auth.test.js)"
- **Separated Example**: "IMPL-001: Design cross-service authentication architecture" + "IMPL-002: Implement frontend authentication module" + "IMPL-003: Implement backend authentication service" - **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 ### Task Breakdown Process
- **Automatic decomposition**: Only when task count >15 are tasks broken into subtasks (impl-N.M format) - **Automatic decomposition**: Only when task count >10 triggers re-scoping (not decomposition)
- **Function-based decomposition**: Split by independent functional boundaries, not by technical layers - **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) - **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 - **Smart decomposition**: AI analyzes task title to suggest logical functional subtask structure
- **Complete unit principle**: Each subtask must still represent a complete functional unit - **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 - **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) - **Agent assignment**: Automatic agent mapping based on subtask type (planning/code/test/review)
- **Maximum depth**: 2 levels (impl-N.M) to maintain manageable hierarchy - **Maximum depth**: 2 levels (IMPL-N.M) to maintain manageable hierarchy
- **10-task enforcement**: Exceeding 10 tasks requires project re-scoping
### Implementation Field Requirements ### Flow Control Field Requirements
- **pre_analysis**: Multi-step analysis configuration array containing: - **flow_control**: Universal process manager containing:
- `action`: Brief 2-3 word description (e.g., "analyze patterns", "review security") - agent expands based on context - `pre_analysis`: Array of sequential process steps with:
- `template`: Full template path (e.g., "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt") - `step`: Unique identifier for the step
- `method`: Analysis method ("manual"|"auto-detected"|"gemini"|"codex") - `action`: Human-readable description
- **Agent Behavior**: Agents interpret brief actions and expand them into comprehensive analysis tasks - `command`: Executable command with embedded context variables (e.g., `${variable_name}`)
- **Execution**: Steps processed sequentially, results accumulated for comprehensive context - `output_to`: Variable name to store step results (optional for final steps)
- **Auto-assignment**: Defaults to appropriate multi-step configuration based on complexity - `on_error`: Error handling strategy
- **Required fields**: files (with path/location/modifications), context_notes, pre_analysis - `implementation_approach`: Brief one-line strategy description
- **Paths format**: Semicolon-separated list (e.g., "src/auth;tests/auth;config/auth.json") - `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 ## Session Check Process
⚠️ **CRITICAL**: Check for existing active session before planning ⚠️ **CRITICAL**: Check for existing active session before planning
@@ -208,9 +235,9 @@ Evaluates whether to merge preparation and execution:
- Used by: `/workflow:execute` for context loading - Used by: `/workflow:execute` for context loading
- Contains: Requirements, task overview, success criteria - Contains: Requirements, task overview, success criteria
- **Task Definitions**: `.workflow/WFS-[topic-slug]/.task/impl-*.json` - **Task Definitions**: `.workflow/WFS-[topic-slug]/.task/IMPL-*.json`
- Used by: Agents for implementation context - Used by: Agents for implementation context
- Contains: Complete task details with implementation field including preparation_complexity - Contains: Complete task details with 7-field structure including flow_control process manager
- **Progress Tracking**: `.workflow/WFS-[topic-slug]/TODO_LIST.md` - **Progress Tracking**: `.workflow/WFS-[topic-slug]/TODO_LIST.md`
- Used by: `/workflow:execute` for status tracking - Used by: `/workflow:execute` for status tracking
@@ -233,7 +260,7 @@ Evaluates whether to merge preparation and execution:
``` ```
### Optional TODO_LIST.md (Auto-triggered) ### Optional TODO_LIST.md (Auto-triggered)
Created when complexity > simple or task count > 5 Created when complexity > simple or task count > 3
**TODO_LIST Structure**: Uses unified hierarchical list format **TODO_LIST Structure**: Uses unified hierarchical list format
- Container tasks (with subtasks) marked with `▸` symbol - Container tasks (with subtasks) marked with `▸` symbol
@@ -258,18 +285,20 @@ Generated in .task/ directory when decomposition enabled
### Recommended Task Patterns ### Recommended Task Patterns
#### Complete Feature Implementation #### Complete Feature Implementation
"Implement user management system" - includes CRUD operations, permissions, UI components, API endpoints, and tests "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 #### End-to-End Features
"Add Excel export functionality" - includes data processing, file generation, download API, UI buttons, and error handling "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 #### System Integration
"Integrate payment gateway" - includes API integration, order processing, payment flows, webhook handling, and testing "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 #### Problem Resolution
"Fix and optimize search functionality" - includes bug fixes, performance optimization, UI improvements, and related tests "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 #### Module Development
"Create notification system" - includes email/SMS sending, template management, subscription handling, and admin interface "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
**System ensures**: Unified planning interface with intelligent input detection and function-based task granularity **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

69
.claude/commands/workflow/resume.md
View File

@@ -18,6 +18,10 @@ Intelligently resumes interrupted workflows with automatic detection of interrup
## Core Principles ## Core Principles
**File Structure:** @~/.claude/workflows/workflow-architecture.md **File Structure:** @~/.claude/workflows/workflow-architecture.md
**Dependency Context Rules:**
- **For tasks with dependencies**: MUST read previous task summary documents before resuming
- **Context inheritance**: Use dependency summaries to maintain consistency and avoid duplicate work
## Usage ## Usage
```bash ```bash
/workflow:resume [--from TASK-ID] [--retry] [--skip TASK-ID] [--force] /workflow:resume [--from TASK-ID] [--retry] [--skip TASK-ID] [--force]
@@ -152,7 +156,7 @@ function detect_interruption():
```bash ```bash
# Reconstruct complete agent context from interruption point # Reconstruct complete agent context from interruption point
Task(subagent_type="code-developer", Task(subagent_type="code-developer",
prompt="[RESUME_CONTEXT] [MULTI_STEP_ANALYSIS] Resume impl-1.2: Implement JWT authentication prompt="[RESUME_CONTEXT] [FLOW_CONTROL] Resume impl-1.2: Implement JWT authentication
RESUMPTION CONTEXT: RESUMPTION CONTEXT:
- Interruption Type: agent_timeout - Interruption Type: agent_timeout
@@ -160,6 +164,7 @@ Task(subagent_type="code-developer",
- Completed Tasks: impl-1.1 (auth schema design) - Completed Tasks: impl-1.1 (auth schema design)
- Current Task State: in_progress - Current Task State: in_progress
- Recovery Strategy: retry_with_enhanced_context - Recovery Strategy: retry_with_enhanced_context
- Interrupted at Flow Step: analyze_patterns
AVAILABLE CONTEXT: AVAILABLE CONTEXT:
- Completed Task Summaries: .workflow/WFS-user-auth/.summaries/impl-1.1-summary.md - Completed Task Summaries: .workflow/WFS-user-auth/.summaries/impl-1.1-summary.md
@@ -167,20 +172,28 @@ Task(subagent_type="code-developer",
- Task Definition: .workflow/WFS-user-auth/.task/impl-1.2.json - Task Definition: .workflow/WFS-user-auth/.task/impl-1.2.json
- Session State: .workflow/WFS-user-auth/workflow-session.json - Session State: .workflow/WFS-user-auth/workflow-session.json
PRE-ANALYSIS REQUIREMENTS: FLOW CONTROL RECOVERY:
$(cat .workflow/WFS-user-auth/.task/impl-1.2.json | jq -r '.implementation.pre_analysis[] | "- " + .action + " (" + .method + "): " + .template') Resume from step: analyze_patterns
$(cat .workflow/WFS-user-auth/.task/impl-1.2.json | jq -r '.flow_control.pre_analysis[] | "- Step: " + .step + " | Action: " + .action + " | Command: " + .command')
CONTINUATION INSTRUCTIONS: CONTEXT RECOVERY STEPS:
1. Review previous completion summaries for context 1. MANDATORY: Read previous task summary documents for all dependencies
2. Check current codebase state against expected progress 2. Load dependency summaries from context.depends_on
3. Identify any changes since last execution 3. Restore previous step outputs if available
4. Resume from detected interruption point 4. Resume from interrupted flow control step
5. Complete remaining task objectives 5. Execute remaining steps with accumulated context
6. Generate comprehensive summary with dependency outputs
Focus Paths: $(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) Focus Paths: $(cat .workflow/WFS-user-auth/.task/impl-1.2.json | jq -r '.context.focus_paths[]')
Analysis Command: ~/.claude/scripts/gemini-wrapper -p \"$(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}\"", Target Files: $(cat .workflow/WFS-user-auth/.task/impl-1.2.json | jq -r '.flow_control.target_files[]')
description="Resume interrupted task with complete context reconstruction") IMPORTANT:
1. Resume flow control from interrupted step with error recovery
2. Ensure context continuity through step chain
3. Create enhanced summary for dependent tasks
4. Update progress tracking upon successful completion",
description="Resume interrupted task with flow control step recovery")
``` ```
### 4. Resume Coordination with TodoWrite ### 4. Resume Coordination with TodoWrite
@@ -197,7 +210,7 @@ Task(subagent_type="code-developer",
## Resume Execution Plan ## Resume Execution Plan
- [x] **TASK-001**: [Completed] Design auth schema (impl-1.1) - [x] **TASK-001**: [Completed] Design auth schema (impl-1.1)
- [ ] **TASK-002**: [RESUME] [Agent: code-developer] [MULTI_STEP_ANALYSIS] Implement JWT authentication (impl-1.2) - [ ] **TASK-002**: [RESUME] [Agent: code-developer] [FLOW_CONTROL] Implement JWT authentication (impl-1.2)
- [ ] **TASK-003**: [Pending] [Agent: code-review-agent] Review implementations (impl-1.3) - [ ] **TASK-003**: [Pending] [Agent: code-review-agent] Review implementations (impl-1.3)
- [ ] **TASK-004**: Update session state and mark workflow complete - [ ] **TASK-004**: Update session state and mark workflow complete
@@ -326,10 +339,34 @@ Task(subagent_type="code-developer",
## Advanced Resume Features ## Advanced Resume Features
### Step-Level Recovery
- **Flow Control Interruption Detection**: Identify which flow control step was interrupted
- **Step Context Restoration**: Restore accumulated context up to interruption point
- **Partial Step Recovery**: Resume from specific flow control step
- **Context Chain Validation**: Verify context continuity through step sequence
#### Step-Level Resume Options
```bash
# Resume from specific flow control step
/workflow:resume --from-step analyze_patterns impl-1.2
# Retry specific step with enhanced context
/workflow:resume --retry-step gather_context impl-1.2
# Skip failing step and continue with next
/workflow:resume --skip-step analyze_patterns impl-1.2
```
### Enhanced Context Recovery
- **Dependency Summary Integration**: Automatic loading of prerequisite task summaries
- **Variable State Restoration**: Restore step output variables from previous execution
- **Command State Recovery**: Detect partial command execution and resume appropriately
- **Error Context Preservation**: Maintain error information for improved retry strategies
### Checkpoint System ### Checkpoint System
- **Automatic Checkpoints**: Created after each successful task completion - **Step-Level Checkpoints**: Created after each successful flow control step
- **Checkpoint Validation**: Verify codebase state matches expected progress - **Context State Snapshots**: Save variable states at each checkpoint
- **Rollback Capability**: Option to resume from previous valid checkpoint - **Rollback Capability**: Option to resume from previous valid step checkpoint
### Parallel Task Recovery ### Parallel Task Recovery
```bash ```bash

2
.claude/commands/workflow/session/status.md
View File

@@ -53,7 +53,7 @@ Display comprehensive status information for the currently active workflow sessi
📄 Generated Documents: 📄 Generated Documents:
✅ IMPL_PLAN.md (Complete) ✅ IMPL_PLAN.md (Complete)
✅ TODO_LIST.md (Auto-updated) ✅ TODO_LIST.md (Auto-updated)
📝 .task/impl-*.json (5 tasks) 📝 .task/IMPL-*.json (5 tasks)
📊 reports/ (Ready for generation) 📊 reports/ (Ready for generation)
``` ```

197
.claude/workflows/task-core.md
View File

@@ -4,122 +4,116 @@
Task commands provide single-execution workflow capabilities with full context awareness, hierarchical organization, and agent orchestration. Task commands provide single-execution workflow capabilities with full context awareness, hierarchical organization, and agent orchestration.
## Task JSON Schema ## Task JSON Schema
All task files use this unified 10-field structure: All task files use this simplified 5-field schema (aligned with workflow-architecture.md):
```json ```json
{ {
"id": "impl-1", "id": "IMPL-1.2",
"title": "Build authentication module", "title": "Implement JWT authentication",
"status": "pending|active|completed|blocked|container", "status": "pending|active|completed|blocked|container",
"type": "feature|bugfix|refactor|test|docs",
"agent": "code-developer|planning-agent|code-review-test-agent", "meta": {
"paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts", "type": "feature|bugfix|refactor|test|docs",
"agent": "code-developer|planning-agent|code-review-test-agent"
},
"context": { "context": {
"requirements": ["JWT authentication", "OAuth2 support"], "requirements": ["JWT authentication", "OAuth2 support"],
"scope": ["src/auth/*", "tests/auth/*"], "focus_paths": ["src/auth", "tests/auth", "config/auth.json"],
"acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"], "acceptance": ["JWT validation works", "OAuth flow complete"],
"inherited_from": "WFS-user-auth" "parent": "IMPL-1",
}, "depends_on": ["IMPL-1.1"],
"inherited": {
"relations": { "from": "IMPL-1",
"parent": null, "context": ["Authentication system design completed"]
"subtasks": ["impl-1.1", "impl-1.2"],
"dependencies": ["impl-0"]
},
"execution": {
"attempts": 0,
"last_attempt": null
},
"implementation": {
"preparation_complexity": "simple|moderate|complex",
"preparation_tasks": [
"Review existing auth patterns",
"Check JWT library compatibility"
],
"estimated_prep_time": "20min",
"files": [
{
"path": "src/auth/login.ts",
"location": {
"function": "handleLogin",
"lines": "75-120",
"description": "Core login handler function"
},
"original_code": "// Requires gemini analysis for code extraction",
"modifications": {
"current_state": "Basic password validation",
"proposed_changes": [
"Add JWT token generation",
"Integrate OAuth2 flow"
],
"logic_flow": [
"validateInput() ───► checkCredentials()",
"◊─── if valid ───► generateJWT() ───► return token"
],
"reason": "Meet JWT and OAuth2 requirements",
"expected_outcome": "Flexible login system"
}
}
],
"context_notes": {
"dependencies": ["jsonwebtoken", "passport-oauth2"],
"affected_modules": ["user-profile", "session-manager"],
"risks": ["Breaking auth middleware changes"],
"performance_considerations": "JWT adds ~5ms latency",
"error_handling": "No sensitive data in errors"
}, },
"shared_context": {
"auth_strategy": "JWT with refresh tokens"
}
},
"flow_control": {
"pre_analysis": [ "pre_analysis": [
{ {
"action": "analyze patterns", "step": "gather_context",
"template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt", "action": "Read dependency summaries",
"method": "gemini" "command": "bash(cat .workflow/*/summaries/IMPL-1.1-summary.md)",
}, "output_to": "auth_design_context",
{ "on_error": "skip_optional"
"action": "implement feature",
"template": "~/.claude/workflows/cli-templates/prompts/development/feature.txt",
"method": "codex"
} }
],
"implementation_approach": {
"task_description": "Implement comprehensive JWT authentication system...",
"modification_points": ["Add JWT token generation...", "..."],
"logic_flow": ["User login request → validate credentials...", "..."]
},
"target_files": [
"src/auth/login.ts:handleLogin:75-120",
"src/middleware/auth.ts:validateToken"
] ]
} }
} }
``` ```
## Implementation Field Details ## Field Structure Details
### preparation_complexity Assessment ### focus_paths Field (within context)
- **simple**: <30min prep, ≤3 files, single module → merge with execution **Purpose**: Specifies concrete project paths relevant to task implementation
- **moderate**: Cross-module analysis, 30min-2h → consider separation
- **complex**: Architecture design, >2h, >5 modules → separate preparation
### files Array Structure **Format**:
- **path**: Specific file path - **Array of strings**: `["folder1", "folder2", "specific_file.ts"]`
- **location**: Function/class/line range - **Concrete paths**: Use actual directory/file names without wildcards
- **original_code**: Current code (or "requires gemini analysis") - **Mixed types**: Can include both directories and specific files
- **modifications**: Detailed change specification - **Relative paths**: From project root (e.g., `src/auth`, not `./src/auth`)
### context_notes Requirements **Examples**:
- **dependencies**: Required packages ```json
- **affected_modules**: Impact scope // Authentication system task
- **risks**: Specific implementation risks "focus_paths": ["src/auth", "tests/auth", "config/auth.json", "src/middleware/auth.ts"]
- **performance_considerations**: Performance impact
- **error_handling**: Error handling requirements
### pre_analysis Options // UI component task
- **manual**: User-provided details "focus_paths": ["src/components/Button", "src/styles", "tests/components"]
- **auto-detected**: System-inferred ```
- **gemini**: Requires Gemini CLI analysis
- **codex**: Requires Codex CLI analysis ### flow_control Field Structure
**Purpose**: Universal process manager for task execution
**Components**:
- **pre_analysis**: Array of sequential process steps
- **implementation_approach**: Task execution strategy
- **target_files**: Specific files to modify in "file:function:lines" format
**Step Structure**:
```json
{
"step": "gather_context",
"action": "Human-readable description",
"command": "bash(executable command with [variables])",
"output_to": "variable_name",
"on_error": "skip_optional|fail|retry_once|manual_intervention"
}
```
## Hierarchical System ## Hierarchical System
### Task Hierarchy Rules ### Task Hierarchy Rules
- **Format**: impl-N (main), impl-N.M (subtasks) - **Format**: IMPL-N (main), IMPL-N.M (subtasks) - uppercase required
- **Maximum Depth**: 2 levels only - **Maximum Depth**: 2 levels only
- **10-Task Limit**: Hard limit enforced across all tasks
- **Container Tasks**: Parents with subtasks (not executable) - **Container Tasks**: Parents with subtasks (not executable)
- **Leaf Tasks**: No subtasks (executable) - **Leaf Tasks**: No subtasks (executable)
- **File Cohesion**: Related files must stay in same task
### Task Complexity Classifications
- **Simple**: ≤5 tasks, single-level tasks, direct execution
- **Medium**: 6-10 tasks, two-level hierarchy, context coordination
- **Over-scope**: >10 tasks requires project re-scoping into iterations
### Complexity 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
### Status Rules ### Status Rules
- **pending**: Ready for execution - **pending**: Ready for execution
@@ -143,7 +137,7 @@ Tasks inherit from:
3. `IMPL_PLAN.md` - Planning document 3. `IMPL_PLAN.md` - Planning document
### File Locations ### File Locations
- **Task JSON**: `.workflow/WFS-[topic]/.task/impl-*.json` - **Task JSON**: `.workflow/WFS-[topic]/.task/IMPL-*.json` (uppercase required)
- **Session State**: `.workflow/WFS-[topic]/workflow-session.json` - **Session State**: `.workflow/WFS-[topic]/workflow-session.json`
- **Planning Doc**: `.workflow/WFS-[topic]/IMPL_PLAN.md` - **Planning Doc**: `.workflow/WFS-[topic]/IMPL_PLAN.md`
- **Progress**: `.workflow/WFS-[topic]/TODO_LIST.md` - **Progress**: `.workflow/WFS-[topic]/TODO_LIST.md`
@@ -163,19 +157,22 @@ Each agent receives tailored context:
- **test-agent**: Files to test, logic flows to validate - **test-agent**: Files to test, logic flows to validate
- **review-agent**: Quality standards, security considerations - **review-agent**: Quality standards, security considerations
## Paths Field Format ## Deprecated Fields
### Structure ### Legacy paths Field
Semicolon-separated list of concrete paths: **Deprecated**: The semicolon-separated `paths` field has been replaced by `context.focus_paths` array.
**Old Format** (no longer used):
```json ```json
"paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts" "paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts"
``` ```
### Selection Strategy **New Format** (use this instead):
- **Directories**: Relevant module directories ```json
- **Specific Files**: Explicitly mentioned files "context": {
- **No Wildcards**: Use concrete paths only "focus_paths": ["src/auth", "tests/auth", "config/auth.json", "src/middleware/auth.ts"]
- **Focus Scope**: Only task-related paths }
```
## Validation Rules ## Validation Rules
@@ -184,7 +181,9 @@ Semicolon-separated list of concrete paths:
2. Task status allows operation 2. Task status allows operation
3. Dependencies are met 3. Dependencies are met
4. Active workflow session exists 4. Active workflow session exists
5. Implementation field is complete 5. All 5 core fields present (id, title, status, meta, context, flow_control)
6. Total task count ≤ 10 (hard limit)
7. File cohesion maintained in focus_paths
### Hierarchy Validation ### Hierarchy Validation
- Parent-child relationships valid - Parent-child relationships valid

671
.claude/workflows/workflow-architecture.md
View File

@@ -1,179 +1,85 @@
# Workflow Architecture # Workflow Architecture
## Overview ## Overview & Core Principles
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. 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.
## Core Architecture Principles ### 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
### Key Design Decisions ## Data Architecture
- **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
## Session Management ### JSON-Only Data Model
**Core Principle**: JSON files are the authoritative source; markdown documents are read-only generated views.
### Active Session Marker System - **Task State**: Stored exclusively in `.task/IMPL-*.json` files
**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 - **Documents**: Generated on-demand from JSON data
- **No Synchronization**: Eliminates bidirectional sync complexity - **No Synchronization**: Eliminates bidirectional sync complexity
- **Performance**: Direct JSON access without parsing overhead - **Performance**: Direct JSON access without parsing overhead
### Task JSON Schema ### Task JSON Schema
All task files use this 10-field schema: All task files use this simplified 5-field schema:
```json ```json
{ {
"id": "impl-1", "id": "IMPL-1.2",
"title": "Build authentication module", "title": "Implement JWT authentication",
"status": "pending|active|completed|blocked|container", "status": "pending|active|completed|blocked|container",
"type": "feature|bugfix|refactor|test|docs",
"agent": "code-developer|planning-agent|code-review-test-agent", "meta": {
"paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts", "type": "feature|bugfix|refactor|test|docs",
"agent": "code-developer|planning-agent|code-review-test-agent"
},
"context": { "context": {
"requirements": ["JWT authentication", "OAuth2 support"], "requirements": ["JWT authentication", "OAuth2 support"],
"scope": ["src/auth/*", "tests/auth/*"], "focus_paths": ["src/auth", "tests/auth", "config/auth.json"],
"acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"], "acceptance": ["JWT validation works", "OAuth flow complete"],
"inherited_from": "WFS-user-auth" "parent": "IMPL-1",
}, "depends_on": ["IMPL-1.1"],
"inherited": {
"relations": { "from": "IMPL-1",
"parent": null, "context": ["Authentication system design completed"]
"subtasks": ["impl-1.1", "impl-1.2"],
"dependencies": ["impl-0"]
},
"execution": {
"attempts": 0,
"last_attempt": null
},
"implementation": {
"preparation_complexity": "simple|moderate|complex",
"preparation_tasks": [
"Review existing auth patterns",
"Check JWT library compatibility",
"Analyze current session management"
],
"estimated_prep_time": "20min",
"files": [
{
"path": "src/auth/login.ts",
"location": {
"function": "handleLogin",
"lines": "75-120",
"description": "Core logic of login handler function"
},
"original_code": "// Related code not provided, requires gemini analysis",
"modifications": {
"current_state": "Currently using simple password validation",
"proposed_changes": [
"Add JWT token generation logic",
"Integrate OAuth2 authentication flow",
"Enhance error handling mechanisms"
],
"logic_flow": [
"validateInput() ───► checkCredentials()",
"◊─── if valid ───► generateJWT() ───► return token",
"◊─── if OAuth ───► redirectToProvider() ───► handleCallback()",
"◊─── if error ───► logError() ───► return errorResponse"
],
"reason": "Meet JWT and OAuth2 authentication requirements, enhance security",
"expected_outcome": "Flexible login system supporting multiple authentication methods"
}
}
],
"context_notes": {
"dependencies": ["jsonwebtoken", "passport-oauth2"],
"affected_modules": ["user-profile", "session-manager"],
"risks": [
"Need to update authentication middleware for all API endpoints",
"May affect existing user sessions",
"Require database migration to add token storage table"
],
"performance_considerations": "JWT validation will add approximately 5ms latency",
"error_handling": "Ensure sensitive information is not leaked in error responses"
}, },
"shared_context": {
"auth_strategy": "JWT with refresh tokens"
}
},
"flow_control": {
"pre_analysis": [ "pre_analysis": [
{ {
"action": "analyze patterns", "step": "gather_context",
"template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt", "action": "Read dependency summaries",
"method": "gemini" "command": "bash(cat .workflow/*/summaries/IMPL-1.1-summary.md)",
}, "output_to": "auth_design_context",
{ "on_error": "skip_optional"
"action": "generate implementation",
"template": "~/.claude/workflows/cli-templates/prompts/development/feature.txt",
"method": "codex"
} }
],
"implementation_approach": {
"task_description": "Implement comprehensive JWT authentication system...",
"modification_points": ["Add JWT token generation...", "..."],
"logic_flow": ["User login request → validate credentials...", "..."]
},
"target_files": [
"src/auth/login.ts:handleLogin:75-120",
"src/middleware/auth.ts:validateToken"
] ]
} }
} }
``` ```
### Paths Field Details ### Focus Paths Field Details
The **paths** field specifies concrete project paths (folders and files) relevant to the task implementation: The **focus_paths** field within **context** specifies concrete project paths relevant to the task implementation:
#### Path Format #### Focus Paths Format
- **Semicolon-separated list**: `"folder1;folder2;specific_file.ts"` - **Array of strings**: `["folder1", "folder2", "specific_file.ts"]`
- **Concrete paths**: Use actual directory/file names without wildcards - **Concrete paths**: Use actual directory/file names without wildcards
- **Mixed types**: Can include both directories and specific files - **Mixed types**: Can include both directories and specific files
- **Relative paths**: From project root (e.g., `src/auth`, not `./src/auth`) - **Relative paths**: From project root (e.g., `src/auth`, not `./src/auth`)
@@ -187,171 +93,312 @@ The **paths** field specifies concrete project paths (folders and files) relevan
#### Examples #### Examples
```json ```json
// Authentication system task // Authentication system task
"paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts" "focus_paths": ["src/auth", "tests/auth", "config/auth.json", "src/middleware/auth.ts"]
// UI component task // UI component task
"paths": "src/components/Button;src/styles;tests/components" "focus_paths": ["src/components/Button", "src/styles", "tests/components"]
// Database migration task // Database migration task
"paths": "migrations;src/models;config/database.json" "focus_paths": ["migrations", "src/models", "config/database.json"]
``` ```
### Implementation Field Details ### Flow Control Field Details
The **implementation** field provides detailed code implementation guidance with 4 core components: The **flow_control** field serves as a universal process manager for task execution with comprehensive flow orchestration:
#### files Array - Detailed File Information #### pre_analysis Array - Sequential Process Steps
- **path**: File path or filename Each step contains:
- **location**: Specific code location (function name, class name, line range) - **step**: Unique identifier for the step
- **original_code**: Original code snippet to be modified (mark as "requires gemini analysis" if not obtained) - **action**: Human-readable description of what the step does
- **modifications**: Modification details - **command**: Executable command wrapped in `bash()` with embedded context variables (e.g., `bash(command with [variable_name])`)
- **current_state**: Brief description of current code state - **output_to**: Variable name to store step results (optional for final steps)
- **proposed_changes**: Step-by-step list of modification points - **on_error**: Error handling strategy (`skip_optional`, `fail`, `retry_once`, `manual_intervention`)
- **logic_flow**: Data flow and call relationship diagram - **success_criteria**: Optional validation criteria (e.g., `exit_code:0`)
- **reason**: Modification rationale and objectives
- **expected_outcome**: Expected results
#### preparation_complexity - Task Saturation Assessment #### Context Flow Management
- **simple**: Preparation work < 30min, ≤ 3 files, single module → Merge with execution - **Variable Accumulation**: Each step can reference outputs from previous steps via `[variable_name]`
- **moderate**: Cross-module analysis needed, 30min-2h prep → Consider separation - **Context Inheritance**: Steps can use dependency summaries and parent task context
- **complex**: Architecture design, >2h prep, >5 modules → Separate preparation task - **Pipeline Processing**: Results flow sequentially through the analysis chain
#### preparation_tasks - Preparation Work List #### Variable Reference Format
- Array of specific preparation activities to be performed - **Context Variables**: Use `[variable_name]` to reference step outputs
- Used to estimate complexity and decide merge/split strategy - **Task Properties**: Use `[depends_on]`, `[focus_paths]` to reference task JSON properties
- Examples: ["Review patterns", "Check dependencies", "Analyze performance"] - **Bash Compatibility**: Avoids conflicts with bash `${}` variable expansion
#### estimated_prep_time - Time Estimation #### Command Types Supported
- String format time estimate (e.g., "20min", "2h", "half-day") - **CLI Analysis**: `bash(~/.claude/scripts/gemini-wrapper -p 'prompt')`
- Helps determine if preparation should be merged with execution - **Agent Execution**: `bash(codex --full-auto exec 'task description')`
- **Shell Commands**: `bash(cat)`, `bash(grep)`, `bash(find)`, `bash(custom scripts)`
- **Context Processing**: `bash(file reading)`, `bash(dependency loading)`, `bash(context merging)`
#### context_notes - Implementation Context Information #### Error Handling Strategies
- **dependencies**: Required dependency packages or modules - **skip_optional**: Continue execution, step result is empty
- **affected_modules**: Other modules that will be affected - **fail**: Stop execution, mark task as failed
- **risks**: Potential risk points and cascading effects - **retry_once**: Retry step once, then fail if still unsuccessful
- **performance_considerations**: Performance impact assessment - **manual_intervention**: Pause execution for manual review
- **error_handling**: Error handling requirements
#### pre_analysis - Information Source Identifier #### Example Flow Control Patterns
- **manual**: Detailed information manually provided by user
- **gemini**: Automatically obtained through Gemini CLI analysis
- **codex**: Automatically obtained through Codex CLI analysis
- **auto-detected**: Auto-detected based on task type and context
### Hierarchical Task System **Pattern 1: Multi-Step Analysis**
**Maximum Depth**: 2 levels (impl-N.M format) ```json
"pre_analysis": [
``` {
impl-1 # Main task "step": "gather_dependencies",
impl-1.1 # Subtask of impl-1 (dynamically created) "command": "bash(for dep in ${depends_on}; do cat .summaries/$dep-summary.md; done)",
impl-1.2 # Another subtask of impl-1 "output_to": "dependency_context"
impl-2 # Another main task },
impl-2.1 # Subtask of impl-2 (dynamically created) {
"step": "analyze_codebase",
"command": "bash(gemini -p '@{[focus_paths]} using context: [dependency_context]')",
"output_to": "codebase_analysis"
}
]
``` ```
**Task Status Rules**: **Pattern 2: Direct Implementation**
- **Container tasks**: Parent tasks with subtasks (cannot be directly executed) ```json
- **Leaf tasks**: Only these can be executed directly "pre_analysis": [
{
"step": "implement",
"command": "bash(codex --full-auto exec 'Implement [title] in [focus_paths]')"
}
]
```
#### Benefits of Flow Control
- **Universal Process Manager**: Handles any type of analysis or implementation flow
- **Context Accumulation**: Builds comprehensive context through step chain
- **Error Recovery**: Granular error handling at step level
- **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)
```
IMPL-1 # Main task
IMPL-1.1 # Subtask (dynamically created)
IMPL-1.2 # Another subtask
IMPL-2 # Another main task
IMPL-2.1 # Subtask (dynamically created)
```
**Rules**:
- **Container tasks**: Parent tasks with subtasks (cannot execute directly)
- **Leaf tasks**: Only executable tasks
- **Status inheritance**: Parent status derived from subtask completion - **Status inheritance**: Parent status derived from subtask completion
## File Structure ## Session Management
### Unified File Structure ### Active Session Marker System
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. **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.**
#### Complete Structure Reference
``` ```
.workflow/WFS-[topic-slug]/ .workflow/WFS-[topic-slug]/
├── workflow-session.json # Session metadata and state (REQUIRED) ├── workflow-session.json # Session 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
├── IMPL_PLAN.md # Planning document (REQUIRED) ├── IMPL_PLAN.md # Planning document (REQUIRED)
├── TODO_LIST.md # Progress tracking (REQUIRED) ├── TODO_LIST.md # Progress tracking (REQUIRED)
├── [.summaries/] # Task completion summaries (created when tasks complete) ├── .task/ # Task definitions (REQUIRED)
│ ├── IMPL-*.md # Main task summaries │ ├── IMPL-*.json # Main task definitions
│ └── IMPL-*.*.md # Subtask summaries │ └── IMPL-*.*.json # Subtask definitions (dynamic)
└── .task/ # Task definitions (REQUIRED) ├── [.brainstorming/] # Brainstorming phase (on-demand)
├── impl-*.json # Main task definitions ├── [.chat/] # CLI sessions (on-demand)
└── impl-*.*.json # Subtask definitions (created dynamically) │ ├── chat-*.md # Saved chat sessions
│ └── analysis-*.md # Analysis results
└── [.summaries/] # Task summaries (on-demand)
├── IMPL-*.md # Main task summaries
└── IMPL-*.*.md # Subtask summaries
``` ```
#### Creation Strategy ### Creation Strategy
- **Initial Setup**: Create only `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`, and `.task/` directory - **Initial**: Only `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`, `.task/`
- **On-Demand Creation**: Other directories created when first needed: - **On-Demand**:
- `.brainstorming/` → When brainstorming phase is initiated - `.brainstorming/` → When brainstorming initiated
- `.chat/` → When CLI analysis commands are executed - `.chat/` → When analysis commands executed
- `.summaries/` → When first task is completed - `.summaries/` → When first task completed
- **Dynamic Files**: Subtask JSON files created during task decomposition
### File Naming Conventions ### 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`
#### Session Identifiers ## Workflow Classification
**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`)
#### Document Naming ### Complexity Types
- `workflow-session.json` - Session state (required) **Based on task count and decomposition needs:**
- `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`
## Complexity Classification | 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 |
### Task Complexity Rules ### Characteristics
**Complexity is determined by task count and decomposition needs:**
| Complexity | Task Count | Hierarchy Depth | Decomposition Behavior | **Simple**: Bug fixes, small features, config changes
|------------|------------|----------------|----------------------| - Single-level tasks, direct execution, ≤5 tasks
| **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 |
### Simple Workflows **Medium**: New features, API endpoints, schema changes
**Characteristics**: Direct implementation tasks with clear, limited scope - Two-level hierarchy, context coordination, 6-10 tasks
- **Examples**: Bug fixes, small feature additions, configuration changes
- **Task Decomposition**: Usually single-level tasks, minimal breakdown needed
- **Agent Coordination**: Direct execution without complex orchestration
### Medium Workflows **Over-scope**: Major features exceeding 10 tasks
**Characteristics**: Feature implementation requiring moderate task breakdown - Requires re-scoping into smaller iterations, never >10 tasks
- **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
### Complex Workflows ### Assessment Rules
**Characteristics**: System-wide changes requiring detailed decomposition - **Creation**: System evaluates and assigns complexity
- **Examples**: Major features, architecture refactoring, security implementations, multi-service deployments - **10-task limit**: Hard limit enforced - exceeding requires re-scoping
- **Task Decomposition**: Frequent use of two-level hierarchy with dynamic subtask creation - **Execution**: Can upgrade (Simple→Medium→Over-scope), triggers re-scoping
- **Agent Coordination**: Multi-agent orchestration with deep context analysis - **Override**: Users can manually specify complexity within 10-task limit
### Automatic Assessment & Upgrades ## Task Execution Framework
- **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
## Document Templates ### Agent Integration
### IMPL_PLAN.md **Assignment Rules** (based on task type/keywords):
Generated based on task complexity and requirements. Contains overview, requirements, and task structure. - **Planning** → planning-agent
- **Implementation** → code-developer
- **Testing** → code-review-test-agent
- **Review** → review-agent
### TODO_LIST.md Template **Execution Context** (agents receive):
```json
{
"task": { /* complete task JSON */ },
"workflow": {
"session": "WFS-user-auth",
"phase": "IMPLEMENT"
}
}
```
## 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]
- **[API Endpoint]**: [usage details]
- **[Configuration]**: [location and format]
## Testing Verification
- [Test type]: [location/results]
- [Validation]: [confirmation method]
- [Quality checks]: [what was verified]
## Notes for Future Tasks
[Any important considerations, limitations, or follow-up items]
```
### TODO List (TODO_LIST.md)
```markdown ```markdown
# Tasks: [Session Topic] # Tasks: [Session Topic]
## Task Progress ## Task Progress
▸ **IMPL-001**: [Main Task Group] → [📋](./.task/impl-001.json) ▸ **IMPL-001**: [Main Task Group] → [📋](./.task/IMPL-001.json)
- [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/impl-001.1.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-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) - [x] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json) | [✅](./.summaries/IMPL-002.md)
▸ **IMPL-003**: [Main Task Group] → [📋](./.task/impl-003.json) ▸ **IMPL-003**: [Main Task Group] → [📋](./.task/IMPL-003.json)
- [ ] **IMPL-003.1**: [Subtask] → [📋](./.task/impl-003.1.json) - [ ] **IMPL-003.1**: [Subtask] → [📋](./.task/IMPL-003.1.json)
- [ ] **IMPL-003.2**: [Subtask] → [📋](./.task/impl-003.2.json) - [ ] **IMPL-003.2**: [Subtask] → [📋](./.task/IMPL-003.2.json)
## Status Legend ## Status Legend
- `▸` = Container task (has subtasks) - `▸` = Container task (has subtasks)
@@ -363,96 +410,6 @@ Generated based on task complexity and requirements. Contains overview, requirem
[Optional notes] [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 9 core fields must be present
7. **Implementation Structure**: implementation.files array must contain valid file paths
8. **Pre-Analysis Source**: pre_analysis must be multi-step array format with action, template, method
### 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 ensures**: Unified workflow architecture with ultra-fast session management, JSON-only data model, and unified file structure for all workflows regardless of complexity. **System Design**: Unified workflow architecture featuring ultra-fast session management, JSON-only data model, and consistent file structure across all workflow types.