catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-05 01:50:27 +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
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)`
- Consistent ID schemes (IMPL-XXX, IMPL-XXX.Y, IMPL-XXX.Y.Z)

99
.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:
→ Proceed with execution
ELIF context insufficient OR task has analysis marker:
→ Check for [MULTI_STEP_ANALYSIS] marker:
- Execute comprehensive pre-analysis BEFORE implementation begins
- Process each step with specified method (gemini/codex/manual/auto-detected)
- Expand brief actions into comprehensive analysis tasks
→ Extract patterns and conventions
ELIF context insufficient OR task has flow control marker:
→ Check for [FLOW_CONTROL] marker:
- Execute flow_control.pre_analysis steps sequentially BEFORE implementation
- Process each step with command execution and context accumulation
- Load dependency summaries and parent task context
- Execute CLI tools, scripts, and agent commands as specified
- Pass context between steps via [variable_name] references
→ Extract patterns and conventions from accumulated context
→ Proceed with execution
```
**Pre-Execution Analysis System**:
- **[MULTI_STEP_ANALYSIS]**: Mandatory pre-execution analysis flag
- **Trigger**: Auto-added when task.pre_analysis is an array (default format)
- **Action**: MUST run multi-step pre-analysis first to gather comprehensive context
- **Purpose**: Ensures code aligns with existing patterns through comprehensive pre-execution analysis
**Flow Control Execution System**:
- **[FLOW_CONTROL]**: Mandatory flow control execution flag
- **Sequential Processing**: Execute pre_analysis steps in order with context flow
- **Variable Accumulation**: Build comprehensive context through step chain
- **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**:
- **Multi-step Processing**: Execute each analysis step sequentially with specified templates
- **Method Selection**: Use method specified in each step (gemini/codex/manual/auto-detected)
- **CLI Commands**:
- **Gemini**: `bash(~/.claude/scripts/gemini-wrapper -p "$(cat template_path) [expanded_action]")`
- **Codex**: `bash(codex --full-auto exec "$(cat template_path) [expanded_action]")`
**Flow Control Execution Standards**:
- **Sequential Step Processing**: Execute flow_control.pre_analysis steps in defined order
- **Context Variable Handling**: Process [variable_name] references in commands
- **Command Types**:
- **CLI Analysis**: Execute gemini/codex commands with context variables
- **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
@@ -114,7 +121,7 @@ ELIF context insufficient OR task has analysis marker:
```
.workflow/WFS-[session-id]/ # (Path provided in session context)
├── 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
```
@@ -123,12 +130,12 @@ ELIF context insufficient OR task has analysis marker:
# Tasks: User Authentication System
## Task Progress
▸ **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)
- [ ] **IMPL-001.2**: API endpoints → [📋](./.task/impl-001.2.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)
- [ ] **IMPL-001.2**: API endpoints → [📋](./.task/IMPL-001.2.json)
- [ ] **IMPL-002**: Add JWT validation → [📋](./.task/impl-002.json)
- [ ] **IMPL-003**: OAuth2 integration → [📋](./.task/impl-003.json)
- [ ] **IMPL-002**: Add JWT validation → [📋](./.task/IMPL-002.json)
- [ ] **IMPL-003**: OAuth2 integration → [📋](./.task/IMPL-003.json)
## Status Legend
- `▸` = Container task (has subtasks)
@@ -141,15 +148,44 @@ ELIF context insufficient OR task has analysis marker:
- Use exact paths from session context (e.g., `.workflow/WFS-[session-id]/.summaries/`)
- Link summary in TODO_LIST.md using relative path
**Summary Template**:
**Enhanced Summary Template**:
```markdown
# Task: [Task-ID] [Name]
## Completed
- Files modified: [list]
- Tests added: [count]
- Key changes: [brief list]
## Implementation Summary
### Files Modified
- `[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
```
@@ -178,6 +214,7 @@ Before completing any task, verify:
- [ ] ASCII-only characters (no emojis/Unicode)
- [ ] GBK encoding compatible
- [ ] TODO list updated
- [ ] Comprehensive summary document generated with all new components/methods listed
## Key Reminders
@@ -196,3 +233,5 @@ Before completing any task, verify:
- Follow existing patterns and conventions
- Handle errors appropriately
- 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

83
.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 Marker Detection**
When task assignment includes analysis marker:
- **[MULTI_STEP_ANALYSIS]**: Execute sequential analysis steps with specified templates, expanding brief actions
**🎯 Flow Control Detection**
When task assignment includes flow control marker:
- **[FLOW_CONTROL]**: Execute sequential flow control steps with context accumulation and variable passing
**Multi-Step Analysis Support**:
- **Process pre_analysis array**: Handle multi-step array format
- **Expand brief actions**: Convert 2-3 word descriptions into comprehensive analysis tasks
- **Sequential execution**: Execute each analysis step in order, accumulating context
- **Template integration**: Use full template paths for enhanced analysis prompts
**Flow Control Support**:
- **Process flow_control.pre_analysis array**: Handle multi-step flow control format
- **Context variable handling**: Process [variable_name] references in commands
- **Sequential execution**: Execute each step in order, accumulating context through variables
- **Error handling**: Apply per-step error strategies
**Context Gathering Decision Logic**:
```
IF task contains [MULTI_STEP_ANALYSIS] flag:
→ Execute each analysis step sequentially with specified templates
→ Expand brief actions into comprehensive analysis tasks
→ Use method specified in each step (gemini/codex/manual/auto-detected)
→ Accumulate results for comprehensive context
IF task contains [FLOW_CONTROL] flag:
→ Execute each flow control step sequentially with context variables
→ Load dependency summaries from connections.depends_on
→ Process [variable_name] references in commands
→ Accumulate context through step outputs
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:
→ 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
When [MULTI_STEP_ANALYSIS] flag is present, execute comprehensive pre-review analysis:
### Flow Control Execution
When [FLOW_CONTROL] flag is present, execute comprehensive pre-review analysis:
Process each step from pre_analysis array sequentially:
@@ -163,12 +163,12 @@ if [FAST_MODE]: apply targeted review process
- Concurrency issues (race conditions, deadlocks)
- 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
- Clear variable and function names
- Appropriate abstraction levels
- No code duplication (DRY principle)
- Proper documentation for complex logic
### Performance
- Algorithm complexity (time and space)
@@ -201,40 +201,15 @@ if [FAST_MODE]: apply targeted review process
```markdown
# Review Summary: [Task-ID] [Review Name]
## Review Scope
- [Files/components reviewed]
- [Lines of code reviewed]
- [Review depth applied: Deep/Fast Mode]
## Critical Findings
- [Bugs found and fixed]
- [Security issues identified]
- [Breaking changes prevented]
## Quality Improvements
- [Code quality enhancements]
- [Performance optimizations]
- [Architecture improvements]
## Test Implementation
- [Tests written or updated]
## Issues Fixed
- [Bugs/security issues resolved]
- [Missing imports added]
- [Unused imports removed]
- [Import path errors corrected]
## Tests Added
- [Test files created/updated]
- [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
- [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
### Detection and Activation
When receiving task prompt, check for analysis marker:
- **[MULTI_STEP_ANALYSIS]** - Execute mandatory multi-step pre-execution analysis
When receiving task prompt, check for flow control marker:
- **[FLOW_CONTROL]** - Execute mandatory flow control steps with context accumulation
- **ASSIGNED_ROLE** - Extract the specific role for focused analysis
- **ANALYSIS_DIMENSIONS** - Load role-specific analysis dimensions
@@ -49,28 +49,28 @@ def handle_analysis_markers(prompt):
dimensions = extract_value("ANALYSIS_DIMENSIONS", prompt)
topic = extract_topic(prompt)
if "[MULTI_STEP_ANALYSIS]" in prompt:
analysis_steps = extract_pre_analysis_array(prompt)
for step in analysis_steps:
if "[FLOW_CONTROL]" in prompt:
flow_steps = extract_flow_control_array(prompt)
context_vars = {}
for step in flow_steps:
step_name = step["step"]
action = step["action"]
template = step["template"]
method = step["method"]
command = step["command"]
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":
result = execute_gemini_cli(
command=f"bash(~/.claude/scripts/gemini-wrapper -p \"$(cat {template}) {expanded_action}\")",
role_context=role,
topic=topic
)
elif method == "codex":
result = execute_codex_cli(
command=f"bash(codex --full-auto exec \"$(cat {template}) {expanded_action}\")",
role_context=role,
topic=topic
)
integrate_autonomous_insights(result, role)
try:
result = execute_command(processed_command, role_context=role, topic=topic)
if output_to:
context_vars[output_to] = result
except Exception as e:
handle_step_error(e, on_error, step_name)
integrate_flow_results(context_vars, role)
```
### Role-Specific Analysis Dimensions

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

@@ -75,7 +75,7 @@ model: sonnet
# Execute specific workflow task
/gemini:execute IMPL-001
# Loads from: .task/impl-001.json
# Loads from: .task/IMPL-001.json
# Uses: task context, brainstorming refs, scope definitions
# 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.
## 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
⚠️ **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
1. **Session Check**: Verify active session contains parent task
2. **Task Validation**: Ensure parent is `pending` status
3. **AI Decomposition**: Generate subtasks based on parent title
4. **Context Distribution**: Inherit parent requirements and scope
5. **Agent Assignment**: Auto-assign agents based on subtask type
3. **10-Task Limit Check**: Verify breakdown won't exceed total limit
4. **Manual Decomposition**: User defines subtasks with validation
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
- Only `pending` tasks can be broken down
- **Manual breakdown only**: Automated breakdown disabled to prevent violations
- 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
- 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
@@ -45,23 +54,33 @@ Breaks down complex tasks into executable subtasks with context inheritance and
Interactive process:
```
Task: Build authentication module
Current total tasks: 6/10
Suggested subtasks:
1. Design authentication schema
2. Implement core auth logic
3. Add security middleware
4. Write comprehensive tests
⚠️ MANUAL BREAKDOWN REQUIRED
Define subtasks manually (remaining capacity: 4 tasks):
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:
▸ impl-1: Build authentication module (container)
├── 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
2. Enter subtask title: OAuth integration
Focus files: services/OAuthService.js, routes/oauth.js
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
@@ -77,9 +96,39 @@ Files created: .task/impl-1.json + 4 subtask files
- Scope refined for specific subtask
- 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
See @~/.claude/workflows/task-core.md for:
See @~/.claude/workflows/workflow-architecture.md for:
- Complete task JSON schema
- Implementation field structure
- Context inheritance rules
@@ -92,12 +141,17 @@ See @~/.claude/workflows/task-core.md for:
2. Task found in session
3. Task status is `pending`
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
1. Update parent to `container` status
2. Create subtask JSON files
3. Update parent subtasks list
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
@@ -115,17 +169,35 @@ See @~/.claude/workflows/task-core.md for:
```bash
# Task not found
❌ Task impl-5 not found
❌ Task IMPL-5 not found
# Already broken down
⚠️ Task impl-1 already has subtasks
⚠️ Task IMPL-1 already has subtasks
# 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
- `/task:create` - Create new tasks
- `/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
### 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
- **JSON Creation**: Creates task JSON in active session
- **Status Setting**: Initial status = "pending"
@@ -42,7 +42,7 @@ Creates new implementation tasks with automatic context awareness and ID generat
Output:
```
✅ Task created: impl-1
✅ Task created: IMPL-1
Title: Build authentication module
Type: feature
Agent: code-developer
@@ -59,7 +59,7 @@ Status: pending
## Task Creation Process
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
4. **Implementation Setup**: Initialize implementation field
5. **Agent Assignment**: Select appropriate agent
@@ -85,7 +85,7 @@ Suggest running: gemini analysis for file locations and dependencies
## File Management
### 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
- **Updates**: Session stats only
@@ -100,7 +100,7 @@ Suggest running: gemini analysis for file locations and dependencies
Tasks inherit from:
1. **Active Session** - Requirements and scope from workflow-session.json
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
@@ -125,12 +125,12 @@ Based on task type and title keywords:
→ Use: /workflow init "project name"
# Duplicate task
⚠️ Similar task exists: impl-3
⚠️ Similar task exists: IMPL-3
→ Continue anyway? (y/n)
# Max depth exceeded
❌ Cannot create impl-1.2.1 (max 2 levels)
→ Use: impl-2 for new main task
❌ Cannot create IMPL-1.2.1 (max 2 levels)
→ Use: IMPL-2 for new main task
```
## Examples
@@ -139,7 +139,7 @@ Based on task type and title keywords:
```bash
/task:create "Implement user authentication"
✅ Created impl-1: Implement user authentication
✅ Created IMPL-1: Implement user authentication
Type: feature
Agent: code-developer
Status: pending
@@ -149,7 +149,7 @@ Status: pending
```bash
/task:create "Fix login validation bug" --type=bugfix
✅ Created impl-2: Fix login validation bug
✅ Created IMPL-2: Fix login validation bug
Type: bugfix
Agent: code-developer
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>
argument-hint: task-id
examples:
- /task:execute impl-1
- /task:execute impl-1.2
- /task:execute impl-3
- /task:execute IMPL-1
- /task:execute IMPL-1.2
- /task:execute IMPL-3
---
### 🚀 **Command Overview: `/task:execute`**
@@ -134,7 +134,7 @@ This is the simplified data structure loaded to provide context for task executi
```json
{
"task": {
"id": "impl-1",
"id": "IMPL-1",
"title": "Build authentication module",
"type": "feature",
"status": "active",
@@ -147,8 +147,8 @@ This is the simplified data structure loaded to provide context for task executi
},
"relations": {
"parent": null,
"subtasks": ["impl-1.1", "impl-1.2"],
"dependencies": ["impl-0"]
"subtasks": ["IMPL-1.1", "IMPL-1.2"],
"dependencies": ["IMPL-0"]
},
"implementation": {
"files": [
@@ -252,10 +252,10 @@ Different agents receive context tailored to their function, including implement
### 📝 **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
# Task Summary: impl-1 Build Authentication Module
# Task Summary: IMPL-1 Build Authentication Module
## What Was Done
- 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]
argument-hint: task-id ["text"|file.md|ISS-001]
examples:
- /task:replan impl-1 "Add OAuth2 authentication support"
- /task:replan impl-1 updated-specs.md
- /task:replan impl-1 ISS-001
- /task:replan IMPL-1 "Add OAuth2 authentication support"
- /task:replan IMPL-1 updated-specs.md
- /task:replan IMPL-1 ISS-001
---
# Task Replan Command (/task:replan)
@@ -29,24 +29,24 @@ Replans individual tasks with multiple input options, change tracking, and versi
### Direct Text (Default)
```bash
/task:replan impl-1 "Add OAuth2 authentication support"
/task:replan IMPL-1 "Add OAuth2 authentication support"
```
### File-based Input
```bash
/task:replan impl-1 updated-specs.md
/task:replan IMPL-1 updated-specs.md
```
Supports: .md, .txt, .json, .yaml
### Issue Reference
```bash
/task:replan impl-1 ISS-001
/task:replan IMPL-1 ISS-001
```
Loads issue description and requirements
### Interactive Mode
```bash
/task:replan impl-1 --interactive
/task:replan IMPL-1 --interactive
```
Guided step-by-step modification process with validation
@@ -65,14 +65,14 @@ Guided step-by-step modification process with validation
Tasks maintain version history:
```json
{
"id": "impl-1",
"id": "IMPL-1",
"version": "1.2",
"replan_history": [
{
"version": "1.2",
"reason": "Add OAuth2 support",
"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
```
.task/
├── impl-1.json # Current version
├── IMPL-1.json # Current version
├── versions/
│ └── impl-1-v1.1.json # Previous backup
│ └── IMPL-1-v1.1.json # Previous backup
└── [new subtasks as needed]
```
@@ -135,7 +135,7 @@ Updates workflow-session.json with:
## Rollback Support
```bash
/task:replan impl-1 --rollback v1.1
/task:replan IMPL-1 --rollback v1.1
Rollback to version 1.1:
- Restore task from backup
@@ -151,7 +151,7 @@ Confirm rollback? (y/n): y
### Text Input
```bash
/task:replan impl-1 "Add OAuth2 authentication support"
/task:replan IMPL-1 "Add OAuth2 authentication support"
Processing changes...
Proposed updates:
@@ -167,7 +167,7 @@ Apply changes? (y/n): y
### File Input
```bash
/task:replan impl-2 requirements.md
/task:replan IMPL-2 requirements.md
Loading requirements.md...
Applying specification changes...
@@ -180,11 +180,11 @@ Applying specification changes...
```bash
# Task not found
❌ Task impl-5 not found
❌ Task IMPL-5 not found
→ Check task ID with /context
# Task completed
⚠️ Task impl-1 is completed (cannot replan)
⚠️ Task IMPL-1 is completed (cannot replan)
→ Create new task for additional work
# File not found

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

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

@@ -56,7 +56,7 @@ Simple keyword-based filtering:
🔗 ISS-004: Implement rate limiting
Type: Feature | Priority: Medium
Status: Integrated → IMPL-003
Integrated: 2025-09-06 | Task: impl-3.json
Integrated: 2025-09-06 | Task: IMPL-3.json
```
## 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)
- Skip PRD processing (no PRD provided)
- 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
- 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
- Generate TODO_LIST.md for tracking
@@ -126,7 +126,7 @@ def process_plan_deep_command(input):
TASK: {task_description}
MANDATORY FLAGS:
- MULTI_STEP_ANALYSIS = true
- FLOW_CONTROL = true
- pre_analysis = multi-step array format for comprehensive pre-analysis
- FORCE_PARALLEL_ANALYSIS = 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
**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
```bash
/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
2. **Decomposition Strategy**: Based on complexity, decide:
- 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)
- File grouping strategy (cohesive files together)
3. **Quantity Prediction**: Calculate expected:
- Total main tasks (IMPL-XXX)
- Subtasks per main task (impl-N.M)
- Subtasks per main task (IMPL-N.M)
- Container vs leaf task ratio
**Pre-Planning Outputs**:
- Complexity level: Simple (≤8) | Medium (9-15) | Complex (>15)
- Decomposition approach: Flat | Two-level hierarchy
- Estimated task count: [number] main tasks, [number] total leaf tasks
- Complexity level: Simple (≤5) | Medium (6-10) | Over-scoped (>10, requires re-scoping)
- Decomposition approach: Flat | Two-level hierarchy | Re-scope required
- Estimated task count: [number] main tasks, [number] total leaf tasks (max 10)
- Document set: Which documents will be generated (IMPL_PLAN.md, TODO_LIST.md, .task/*.json)
- **Re-scoping recommendation**: If >10 tasks, provide guidance for breaking into iterations
**Only after completing pre-planning analysis**: Proceed to generate actual plan documents
### Complexity Detection with Saturation
*Based on Pre-Planning Analysis results:*
- **Simple**: ≤8 saturated tasks → Direct IMPL_PLAN.md
- **Medium**: 9-15 saturated tasks → IMPL_PLAN.md + TODO_LIST.md
- **Complex**: >15 saturated tasks → Full decomposition
- **Simple**: ≤5 saturated tasks → Direct IMPL_PLAN.md
- **Medium**: 6-10 saturated tasks → IMPL_PLAN.md + TODO_LIST.md
- **Complex**: Exceeding 10 tasks requires re-scoping (maximum enforced)
**10-Task Hard Limit**: Projects exceeding 10 tasks must be re-scoped into smaller iterations
**Note**: 1 complex preparation task = 0.5 saturated task for counting
### Task Granularity Principles
- **Decompose by function, not by file**: Each task should complete a whole functional unit
- **Maintain functional integrity**: Each task produces independently runnable or testable functionality
- **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
- **Maximum 10 tasks**: Hard limit enforced; re-scope if exceeded
### Task Decomposition Anti-patterns
❌ **Wrong Example - File/Step-based Decomposition**:
- IMPL-001: Create database model
- IMPL-002: Create API endpoint
@@ -111,9 +121,18 @@ The command automatically detects input type:
- IMPL-004: Add routing configuration
- IMPL-005: Write unit tests
✅ **Correct Example - Function-based Decomposition**:
- IMPL-001: Implement user authentication feature (includes model, API, UI, tests)
- IMPL-002: Implement data export functionality (includes processing logic, UI, file generation)
❌ **Wrong Example - Same File Split Across Tasks**:
- IMPL-001: Add authentication routes to routes/auth.js
- IMPL-002: Add user validation to routes/auth.js
- IMPL-003: Add session handling to routes/auth.js
✅ **Correct Example - Function-based with File Cohesion**:
- IMPL-001: Implement user authentication (includes models/User.js, routes/auth.js, components/LoginForm.jsx, middleware/auth.js, tests/auth.test.js)
- IMPL-002: Implement data export functionality (includes services/export.js, routes/export.js, components/ExportButton.jsx, utils/fileGenerator.js, tests/export.test.js)
✅ **Correct Example - Related Files Grouped**:
- IMPL-001: User management system (includes User model, UserController, UserService, user routes, user tests)
- IMPL-002: Product catalog system (includes Product model, ProductController, catalog components, product tests)
### Task Generation with Saturation Control
*Using decomposition strategy determined in Pre-Planning Analysis:*
@@ -152,45 +171,53 @@ Three analysis levels available:
3. Populates task paths automatically
### 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):
- All components of the same functional module
- Frontend and backend paired implementation
- Features with their corresponding tests
- Related files that work together (UI, logic, tests, config)
- Features with their corresponding tests and documentation
- Configuration with its usage code
- Multiple small interdependent functions
- Files that share common interfaces or data structures
**Only Separate Tasks When**:
- Completely independent functional modules (no shared code)
- Independent services with different tech stacks (e.g., separate frontend/backend deployment)
- Completely independent functional modules (no shared code or interfaces)
- Independent services with different tech stacks (e.g., separate deployment units)
- Modules requiring different expertise (e.g., ML model training vs Web development)
- Large features with clear sequential dependencies
- **Critical**: Would exceed 10-task limit otherwise
**Task Examples**:
- **Merged Example**: "IMPL-001: Implement user authentication system (includes JWT management, API endpoints, UI components, and tests)"
- **Separated Example**: "IMPL-001: Design cross-service authentication architecture" + "IMPL-002: Implement frontend authentication module" + "IMPL-003: Implement backend authentication service"
**File Cohesion Examples**:
- **Merged**: "IMPL-001: Implement user authentication (includes models/User.js, routes/auth.js, components/LoginForm.jsx, tests/auth.test.js)"
- **Separated**: "IMPL-001: User service authentication" + "IMPL-002: Admin dashboard authentication" (different user contexts)
**10-Task Compliance**: Always prioritize related file grouping to stay within limit
### Task Breakdown Process
- **Automatic decomposition**: Only when task count >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
- **Container tasks**: Parent tasks with subtasks become containers (marked with ▸ in TODO_LIST)
- **Smart decomposition**: AI analyzes task title to suggest logical functional subtask structure
- **Complete unit principle**: Each subtask must still represent a complete functional unit
- **Context inheritance**: Subtasks inherit parent's requirements and scope, refined for specific needs
- **Agent assignment**: Automatic agent mapping based on subtask type (planning/code/test/review)
- **Maximum depth**: 2 levels (impl-N.M) to maintain manageable hierarchy
- **Maximum depth**: 2 levels (IMPL-N.M) to maintain manageable hierarchy
- **10-task enforcement**: Exceeding 10 tasks requires project re-scoping
### Implementation Field Requirements
- **pre_analysis**: Multi-step analysis configuration array containing:
- `action`: Brief 2-3 word description (e.g., "analyze patterns", "review security") - agent expands based on context
- `template`: Full template path (e.g., "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt")
- `method`: Analysis method ("manual"|"auto-detected"|"gemini"|"codex")
- **Agent Behavior**: Agents interpret brief actions and expand them into comprehensive analysis tasks
- **Execution**: Steps processed sequentially, results accumulated for comprehensive context
- **Auto-assignment**: Defaults to appropriate multi-step configuration based on complexity
- **Required fields**: files (with path/location/modifications), context_notes, pre_analysis
- **Paths format**: Semicolon-separated list (e.g., "src/auth;tests/auth;config/auth.json")
### Flow Control Field Requirements
- **flow_control**: Universal process manager containing:
- `pre_analysis`: Array of sequential process steps with:
- `step`: Unique identifier for the step
- `action`: Human-readable description
- `command`: Executable command with embedded context variables (e.g., `${variable_name}`)
- `output_to`: Variable name to store step results (optional for final steps)
- `on_error`: Error handling strategy
- `implementation_approach`: Brief one-line strategy description
- `target_files`: Array of "file:function:lines" format strings
- **Auto-generation**: Creates flow based on task type and complexity
- **Required fields**: meta (type, agent), context (requirements, focus_paths, acceptance, depends_on), flow_control
- **Focus paths format**: Array of strings (e.g., ["src/auth", "tests/auth", "config/auth.json"])
## Session Check Process
⚠️ **CRITICAL**: Check for existing active session before planning
@@ -208,9 +235,9 @@ Evaluates whether to merge preparation and execution:
- Used by: `/workflow:execute` for context loading
- 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
- 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`
- Used by: `/workflow:execute` for status tracking
@@ -233,7 +260,7 @@ Evaluates whether to merge preparation and execution:
```
### 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
- Container tasks (with subtasks) marked with `▸` symbol
@@ -258,18 +285,20 @@ Generated in .task/ directory when decomposition enabled
### Recommended Task Patterns
#### 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
"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
"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
"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
"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
**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
```bash
/workflow:resume [--from TASK-ID] [--retry] [--skip TASK-ID] [--force]
@@ -152,7 +156,7 @@ function detect_interruption():
```bash
# Reconstruct complete agent context from interruption point
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:
- Interruption Type: agent_timeout
@@ -160,6 +164,7 @@ Task(subagent_type="code-developer",
- Completed Tasks: impl-1.1 (auth schema design)
- Current Task State: in_progress
- Recovery Strategy: retry_with_enhanced_context
- Interrupted at Flow Step: analyze_patterns
AVAILABLE CONTEXT:
- 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
- Session State: .workflow/WFS-user-auth/workflow-session.json
PRE-ANALYSIS REQUIREMENTS:
$(cat .workflow/WFS-user-auth/.task/impl-1.2.json | jq -r '.implementation.pre_analysis[] | "- " + .action + " (" + .method + "): " + .template')
FLOW CONTROL RECOVERY:
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:
1. Review previous completion summaries for context
2. Check current codebase state against expected progress
3. Identify any changes since last execution
4. Resume from detected interruption point
5. Complete remaining task objectives
CONTEXT RECOVERY STEPS:
1. MANDATORY: Read previous task summary documents for all dependencies
2. Load dependency summaries from context.depends_on
3. Restore previous step outputs if available
4. Resume from interrupted flow control step
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)
Analysis Command: ~/.claude/scripts/gemini-wrapper -p \"$(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}\"",
Focus Paths: $(cat .workflow/WFS-user-auth/.task/impl-1.2.json | jq -r '.context.focus_paths[]')
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
@@ -197,7 +210,7 @@ Task(subagent_type="code-developer",
## Resume Execution Plan
- [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-004**: Update session state and mark workflow complete
@@ -326,10 +339,34 @@ Task(subagent_type="code-developer",
## 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
- **Automatic Checkpoints**: Created after each successful task completion
- **Checkpoint Validation**: Verify codebase state matches expected progress
- **Rollback Capability**: Option to resume from previous valid checkpoint
- **Step-Level Checkpoints**: Created after each successful flow control step
- **Context State Snapshots**: Save variable states at each checkpoint
- **Rollback Capability**: Option to resume from previous valid step checkpoint
### Parallel Task Recovery
```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:
✅ IMPL_PLAN.md (Complete)
✅ TODO_LIST.md (Auto-updated)
📝 .task/impl-*.json (5 tasks)
📝 .task/IMPL-*.json (5 tasks)
📊 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 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
{
"id": "impl-1",
"title": "Build authentication module",
"id": "IMPL-1.2",
"title": "Implement JWT authentication",
"status": "pending|active|completed|blocked|container",
"type": "feature|bugfix|refactor|test|docs",
"agent": "code-developer|planning-agent|code-review-test-agent",
"paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts",
"meta": {
"type": "feature|bugfix|refactor|test|docs",
"agent": "code-developer|planning-agent|code-review-test-agent"
},
"context": {
"requirements": ["JWT authentication", "OAuth2 support"],
"scope": ["src/auth/*", "tests/auth/*"],
"acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"],
"inherited_from": "WFS-user-auth"
},
"relations": {
"parent": null,
"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"
"focus_paths": ["src/auth", "tests/auth", "config/auth.json"],
"acceptance": ["JWT validation works", "OAuth flow complete"],
"parent": "IMPL-1",
"depends_on": ["IMPL-1.1"],
"inherited": {
"from": "IMPL-1",
"context": ["Authentication system design completed"]
},
"shared_context": {
"auth_strategy": "JWT with refresh tokens"
}
},
"flow_control": {
"pre_analysis": [
{
"action": "analyze patterns",
"template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt",
"method": "gemini"
},
{
"action": "implement feature",
"template": "~/.claude/workflows/cli-templates/prompts/development/feature.txt",
"method": "codex"
"step": "gather_context",
"action": "Read dependency summaries",
"command": "bash(cat .workflow/*/summaries/IMPL-1.1-summary.md)",
"output_to": "auth_design_context",
"on_error": "skip_optional"
}
],
"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
- **simple**: <30min prep, ≤3 files, single module → merge with execution
- **moderate**: Cross-module analysis, 30min-2h → consider separation
- **complex**: Architecture design, >2h, >5 modules → separate preparation
### focus_paths Field (within context)
**Purpose**: Specifies concrete project paths relevant to task implementation
### files Array Structure
- **path**: Specific file path
- **location**: Function/class/line range
- **original_code**: Current code (or "requires gemini analysis")
- **modifications**: Detailed change specification
**Format**:
- **Array of strings**: `["folder1", "folder2", "specific_file.ts"]`
- **Concrete paths**: Use actual directory/file names without wildcards
- **Mixed types**: Can include both directories and specific files
- **Relative paths**: From project root (e.g., `src/auth`, not `./src/auth`)
### context_notes Requirements
- **dependencies**: Required packages
- **affected_modules**: Impact scope
- **risks**: Specific implementation risks
- **performance_considerations**: Performance impact
- **error_handling**: Error handling requirements
**Examples**:
```json
// Authentication system task
"focus_paths": ["src/auth", "tests/auth", "config/auth.json", "src/middleware/auth.ts"]
### pre_analysis Options
- **manual**: User-provided details
- **auto-detected**: System-inferred
- **gemini**: Requires Gemini CLI analysis
- **codex**: Requires Codex CLI analysis
// UI component task
"focus_paths": ["src/components/Button", "src/styles", "tests/components"]
```
### 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
### 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
- **10-Task Limit**: Hard limit enforced across all tasks
- **Container Tasks**: Parents with subtasks (not 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
- **pending**: Ready for execution
@@ -143,7 +137,7 @@ Tasks inherit from:
3. `IMPL_PLAN.md` - Planning document
### 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`
- **Planning Doc**: `.workflow/WFS-[topic]/IMPL_PLAN.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
- **review-agent**: Quality standards, security considerations
## Paths Field Format
## Deprecated Fields
### Structure
Semicolon-separated list of concrete paths:
### Legacy paths Field
**Deprecated**: The semicolon-separated `paths` field has been replaced by `context.focus_paths` array.
**Old Format** (no longer used):
```json
"paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts"
```
### Selection Strategy
- **Directories**: Relevant module directories
- **Specific Files**: Explicitly mentioned files
- **No Wildcards**: Use concrete paths only
- **Focus Scope**: Only task-related paths
**New Format** (use this instead):
```json
"context": {
"focus_paths": ["src/auth", "tests/auth", "config/auth.json", "src/middleware/auth.ts"]
}
```
## Validation Rules
@@ -184,7 +181,9 @@ Semicolon-separated list of concrete paths:
2. Task status allows operation
3. Dependencies are met
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
- Parent-child relationships valid

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

@@ -1,179 +1,85 @@
# 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
- **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
## Data Architecture
## 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
**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
- **Task State**: Stored exclusively in `.task/IMPL-*.json` files
- **Documents**: Generated on-demand from JSON data
- **No Synchronization**: Eliminates bidirectional sync complexity
- **Performance**: Direct JSON access without parsing overhead
### Task JSON Schema
All task files use this 10-field schema:
All task files use this simplified 5-field schema:
```json
{
"id": "impl-1",
"title": "Build authentication module",
"id": "IMPL-1.2",
"title": "Implement JWT authentication",
"status": "pending|active|completed|blocked|container",
"type": "feature|bugfix|refactor|test|docs",
"agent": "code-developer|planning-agent|code-review-test-agent",
"paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts",
"meta": {
"type": "feature|bugfix|refactor|test|docs",
"agent": "code-developer|planning-agent|code-review-test-agent"
},
"context": {
"requirements": ["JWT authentication", "OAuth2 support"],
"scope": ["src/auth/*", "tests/auth/*"],
"acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"],
"inherited_from": "WFS-user-auth"
},
"relations": {
"parent": null,
"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"
"focus_paths": ["src/auth", "tests/auth", "config/auth.json"],
"acceptance": ["JWT validation works", "OAuth flow complete"],
"parent": "IMPL-1",
"depends_on": ["IMPL-1.1"],
"inherited": {
"from": "IMPL-1",
"context": ["Authentication system design completed"]
},
"shared_context": {
"auth_strategy": "JWT with refresh tokens"
}
},
"flow_control": {
"pre_analysis": [
{
"action": "analyze patterns",
"template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt",
"method": "gemini"
},
{
"action": "generate implementation",
"template": "~/.claude/workflows/cli-templates/prompts/development/feature.txt",
"method": "codex"
"step": "gather_context",
"action": "Read dependency summaries",
"command": "bash(cat .workflow/*/summaries/IMPL-1.1-summary.md)",
"output_to": "auth_design_context",
"on_error": "skip_optional"
}
],
"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
- **Semicolon-separated list**: `"folder1;folder2;specific_file.ts"`
#### Focus Paths Format
- **Array of strings**: `["folder1", "folder2", "specific_file.ts"]`
- **Concrete paths**: Use actual directory/file names without wildcards
- **Mixed types**: Can include both directories and specific files
- **Relative paths**: From project root (e.g., `src/auth`, not `./src/auth`)
@@ -187,193 +93,226 @@ The **paths** field specifies concrete project paths (folders and files) relevan
#### Examples
```json
// 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
"paths": "src/components/Button;src/styles;tests/components"
"focus_paths": ["src/components/Button", "src/styles", "tests/components"]
// Database migration task
"paths": "migrations;src/models;config/database.json"
// Database migration task
"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
- **path**: File path or filename
- **location**: Specific code location (function name, class name, line range)
- **original_code**: Original code snippet to be modified (mark as "requires gemini analysis" if not obtained)
- **modifications**: Modification details
- **current_state**: Brief description of current code state
- **proposed_changes**: Step-by-step list of modification points
- **logic_flow**: Data flow and call relationship diagram
- **reason**: Modification rationale and objectives
- **expected_outcome**: Expected results
#### pre_analysis Array - Sequential Process Steps
Each step contains:
- **step**: Unique identifier for the step
- **action**: Human-readable description of what the step does
- **command**: Executable command wrapped in `bash()` with embedded context variables (e.g., `bash(command with [variable_name])`)
- **output_to**: Variable name to store step results (optional for final steps)
- **on_error**: Error handling strategy (`skip_optional`, `fail`, `retry_once`, `manual_intervention`)
- **success_criteria**: Optional validation criteria (e.g., `exit_code:0`)
#### preparation_complexity - Task Saturation Assessment
- **simple**: Preparation work < 30min, ≤ 3 files, single module → Merge with execution
- **moderate**: Cross-module analysis needed, 30min-2h prep → Consider separation
- **complex**: Architecture design, >2h prep, >5 modules → Separate preparation task
#### Context Flow Management
- **Variable Accumulation**: Each step can reference outputs from previous steps via `[variable_name]`
- **Context Inheritance**: Steps can use dependency summaries and parent task context
- **Pipeline Processing**: Results flow sequentially through the analysis chain
#### preparation_tasks - Preparation Work List
- Array of specific preparation activities to be performed
- Used to estimate complexity and decide merge/split strategy
- Examples: ["Review patterns", "Check dependencies", "Analyze performance"]
#### Variable Reference Format
- **Context Variables**: Use `[variable_name]` to reference step outputs
- **Task Properties**: Use `[depends_on]`, `[focus_paths]` to reference task JSON properties
- **Bash Compatibility**: Avoids conflicts with bash `${}` variable expansion
#### estimated_prep_time - Time Estimation
- String format time estimate (e.g., "20min", "2h", "half-day")
- Helps determine if preparation should be merged with execution
#### Command Types Supported
- **CLI Analysis**: `bash(~/.claude/scripts/gemini-wrapper -p 'prompt')`
- **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
- **dependencies**: Required dependency packages or modules
- **affected_modules**: Other modules that will be affected
- **risks**: Potential risk points and cascading effects
- **performance_considerations**: Performance impact assessment
- **error_handling**: Error handling requirements
#### Error Handling Strategies
- **skip_optional**: Continue execution, step result is empty
- **fail**: Stop execution, mark task as failed
- **retry_once**: Retry step once, then fail if still unsuccessful
- **manual_intervention**: Pause execution for manual review
#### pre_analysis - Information Source Identifier
- **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
#### Example Flow Control Patterns
### Hierarchical Task System
**Maximum Depth**: 2 levels (impl-N.M format)
```
impl-1 # Main task
impl-1.1 # Subtask of impl-1 (dynamically created)
impl-1.2 # Another subtask of impl-1
impl-2 # Another main task
impl-2.1 # Subtask of impl-2 (dynamically created)
**Pattern 1: Multi-Step Analysis**
```json
"pre_analysis": [
{
"step": "gather_dependencies",
"command": "bash(for dep in ${depends_on}; do cat .summaries/$dep-summary.md; done)",
"output_to": "dependency_context"
},
{
"step": "analyze_codebase",
"command": "bash(gemini -p '@{[focus_paths]} using context: [dependency_context]')",
"output_to": "codebase_analysis"
}
]
```
**Task Status Rules**:
- **Container tasks**: Parent tasks with subtasks (cannot be directly executed)
- **Leaf tasks**: Only these can be executed directly
**Pattern 2: Direct Implementation**
```json
"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
## File Structure
## Session Management
### Unified File Structure
All workflows use the same file structure definition regardless of complexity. **Directories and files are created on-demand as needed**, not all at once during initialization.
### Active Session Marker System
**Ultra-Simple Tracking**: `.workflow/.active-[session-name]`
```bash
.workflow/
├── WFS-oauth-integration/ # Session directory (paused)
├── WFS-user-profile/ # Session directory (paused)
├── WFS-bug-fix-123/ # Session directory (completed)
└── .active-WFS-user-profile # Marker file (active session)
```
**Benefits**:
- **Zero Parsing**: File existence check is atomic
- **Atomic Operations**: File creation/deletion is naturally atomic
- **Visual Discovery**: `ls .workflow/.active-*` shows active session
- **Simple Switching**: Delete old + create new marker
### Session Operations
```bash
# Detect active session
active_session=$(find .workflow -name ".active-*" | head -1)
if [ -n "$active_session" ]; then
session_name=$(basename "$active_session" | sed 's/^\.active-//')
echo "Active session: $session_name"
fi
# Switch session
find .workflow -name ".active-*" -delete && touch .workflow/.active-WFS-new-feature
```
### Session State
Each session directory contains `workflow-session.json`:
```json
{
"session_id": "WFS-[topic-slug]",
"project": "feature description",
"type": "simple|medium|complex",
"current_phase": "PLAN|IMPLEMENT|REVIEW",
"status": "active|paused|completed",
"progress": {
"completed_phases": ["PLAN"],
"current_tasks": ["IMPL-1", "IMPL-2"]
}
}
```
## File Organization
### Unified Structure
All workflows use the same structure regardless of complexity. **Files created on-demand only.**
#### Complete Structure Reference
```
.workflow/WFS-[topic-slug]/
├── workflow-session.json # Session metadata and state (REQUIRED)
├── [.brainstorming/] # Optional brainstorming phase (created when needed)
├── [.chat/] # CLI interaction sessions (created when analysis is run)
│ ├── chat-*.md # Saved chat sessions
│ └── analysis-*.md # Analysis results
├── workflow-session.json # Session state (REQUIRED)
├── IMPL_PLAN.md # Planning document (REQUIRED)
├── TODO_LIST.md # Progress tracking (REQUIRED)
├── [.summaries/] # Task completion summaries (created when tasks complete)
│ ├── IMPL-*.md # Main task summaries
│ └── IMPL-*.*.md # Subtask summaries
└── .task/ # Task definitions (REQUIRED)
├── impl-*.json # Main task definitions
└── impl-*.*.json # Subtask definitions (created dynamically)
├── .task/ # Task definitions (REQUIRED)
│ ├── IMPL-*.json # Main task definitions
│ └── IMPL-*.*.json # Subtask definitions (dynamic)
├── [.brainstorming/] # Brainstorming phase (on-demand)
├── [.chat/] # CLI sessions (on-demand)
│ ├── 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
- **Initial Setup**: Create only `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`, and `.task/` directory
- **On-Demand Creation**: Other directories created when first needed:
- `.brainstorming/` → When brainstorming phase is initiated
- `.chat/` → When CLI analysis commands are executed
- `.summaries/` → When first task is completed
- **Dynamic Files**: Subtask JSON files created during task decomposition
### Creation Strategy
- **Initial**: Only `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`, `.task/`
- **On-Demand**:
- `.brainstorming/` → When brainstorming initiated
- `.chat/` → When analysis commands executed
- `.summaries/` → When first task completed
### 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
**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`)
## Workflow Classification
#### Document Naming
- `workflow-session.json` - Session state (required)
- `IMPL_PLAN.md` - Planning document (required)
- `TODO_LIST.md` - Progress tracking (auto-generated when needed)
- Chat sessions: `chat-analysis-*.md`
- Task summaries: `IMPL-[task-id]-summary.md`
### Complexity Types
**Based on task count and decomposition needs:**
## 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
**Complexity is determined by task count and decomposition needs:**
### Characteristics
| Complexity | Task Count | Hierarchy Depth | Decomposition Behavior |
|------------|------------|----------------|----------------------|
| **Simple** | <5 tasks | 1 level (impl-N) | Direct execution, minimal decomposition |
| **Medium** | 5-15 tasks | 2 levels (impl-N.M) | Moderate decomposition, context coordination |
| **Complex** | >15 tasks | 2 levels (impl-N.M) | Frequent decomposition, multi-agent orchestration |
**Simple**: Bug fixes, small features, config changes
- Single-level tasks, direct execution, ≤5 tasks
### Simple Workflows
**Characteristics**: Direct implementation tasks with clear, limited scope
- **Examples**: Bug fixes, small feature additions, configuration changes
- **Task Decomposition**: Usually single-level tasks, minimal breakdown needed
- **Agent Coordination**: Direct execution without complex orchestration
**Medium**: New features, API endpoints, schema changes
- Two-level hierarchy, context coordination, 6-10 tasks
### Medium Workflows
**Characteristics**: Feature implementation requiring moderate task breakdown
- **Examples**: New features, API endpoints with integration, database schema changes
- **Task Decomposition**: Two-level hierarchy when decomposition is needed
- **Agent Coordination**: Context coordination between related tasks
**Over-scope**: Major features exceeding 10 tasks
- Requires re-scoping into smaller iterations, never >10 tasks
### Complex Workflows
**Characteristics**: System-wide changes requiring detailed decomposition
- **Examples**: Major features, architecture refactoring, security implementations, multi-service deployments
- **Task Decomposition**: Frequent use of two-level hierarchy with dynamic subtask creation
- **Agent Coordination**: Multi-agent orchestration with deep context analysis
### 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
### Automatic Assessment & Upgrades
- **During Creation**: System evaluates requirements and assigns complexity
- **During Execution**: Can upgrade (Simple→Medium→Complex) but never downgrade
- **Override Allowed**: Users can specify higher complexity manually
## Task Execution Framework
## Document Templates
### Agent Integration
### IMPL_PLAN.md
Generated based on task complexity and requirements. Contains overview, requirements, and task structure.
### TODO_LIST.md Template
```markdown
# Tasks: [Session Topic]
## Task Progress
▸ **IMPL-001**: [Main Task Group] → [📋](./.task/impl-001.json)
- [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/impl-001.1.json)
- [x] **IMPL-001.2**: [Subtask] → [📋](./.task/impl-001.2.json) | [✅](./.summaries/IMPL-001.2.md)
- [x] **IMPL-002**: [Simple Task] → [📋](./.task/impl-002.json) | [✅](./.summaries/IMPL-002.md)
▸ **IMPL-003**: [Main Task Group] → [📋](./.task/impl-003.json)
- [ ] **IMPL-003.1**: [Subtask] → [📋](./.task/impl-003.1.json)
- [ ] **IMPL-003.2**: [Subtask] → [📋](./.task/impl-003.2.json)
## Status Legend
- `▸` = Container task (has subtasks)
- `- [ ]` = Pending leaf task
- `- [x]` = Completed leaf task
- Maximum 2 levels: Main tasks and subtasks only
## Notes
[Optional notes]
```
## Agent Integration
### Agent Assignment
Based on task type and title keywords:
- **Planning tasks** → planning-agent
- **Implementation** → code-developer
**Assignment Rules** (based on task type/keywords):
- **Planning** → planning-agent
- **Implementation** → code-developer
- **Testing** → code-review-test-agent
- **Review** → review-agent
### Execution Context
Agents receive complete task JSON plus workflow context:
**Execution Context** (agents receive):
```json
{
"task": { /* complete task JSON */ },
@@ -383,63 +322,47 @@ Agents receive complete task JSON plus workflow context:
}
}
```
## Operations Guide
### Basic Operations
## Data Operations
### Session Initialization
```bash
# Create minimal required structure
# 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
```bash
echo '{"id":"impl-1","title":"New task",...}' > .task/impl-1.json
```
# Task creation
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
jq '.status = "active"' .task/IMPL-1.json > temp && mv temp .task/IMPL-1.json
### 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
# Document generation
generate_todo_list_from_json .task/
```
## Validation and Error Handling
### Task Integrity Rules
### Validation 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
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
### Session Consistency Checks
```bash
# Validate active session integrity
# 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"
@@ -447,12 +370,46 @@ if [ -n "$active_marker" ]; then
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
## 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
# Tasks: [Session Topic]
## Task Progress
▸ **IMPL-001**: [Main Task Group] → [📋](./.task/IMPL-001.json)
- [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/IMPL-001.1.json)
- [x] **IMPL-001.2**: [Subtask] → [📋](./.task/IMPL-001.2.json) | [✅](./.summaries/IMPL-001.2.md)
- [x] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json) | [✅](./.summaries/IMPL-002.md)
▸ **IMPL-003**: [Main Task Group] → [📋](./.task/IMPL-003.json)
- [ ] **IMPL-003.1**: [Subtask] → [📋](./.task/IMPL-003.1.json)
- [ ] **IMPL-003.2**: [Subtask] → [📋](./.task/IMPL-003.2.json)
## Status Legend
- `▸` = Container task (has subtasks)
- `- [ ]` = Pending leaf task
- `- [x]` = Completed leaf task
- Maximum 2 levels: Main tasks and subtasks only
## Notes
[Optional notes]
```
---
**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.