mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-10 02:24:35 +08:00
Refactor workflow plan command and architecture documentation
- Simplified argument hints and examples in plan.md - Enhanced input detection logic for files, issues, and text - Introduced analysis levels for improved context analysis - Updated core rules for task limits and decomposition strategies - Improved session management with active session marker system - Expanded file structure reference and naming conventions - Clarified task hierarchy and status rules - Added detailed validation and error handling procedures - Streamlined document templates for implementation plans and task summaries
This commit is contained in:
catlog22
@@ -1,23 +1,77 @@
|
||||
# Workflow Architecture
|
||||
|
||||
## Overview & Core Principles
|
||||
## Overview
|
||||
|
||||
This document defines a streamlined workflow system architecture featuring **JSON-only data model**, **marker-based session management**, and **unified file structure** with dynamic task decomposition.
|
||||
This document defines the complete workflow system architecture using a **JSON-only data model**, **marker-based session management**, and **unified file structure** with dynamic task decomposition.
|
||||
|
||||
### Design Philosophy
|
||||
- **JSON-first data model** - JSON files are single source of truth; markdown is generated views
|
||||
- **Marker-based sessions** - Ultra-simple active session tracking via marker files
|
||||
- **Unified structure** - Same file template for all workflows, created on-demand
|
||||
- **Dynamic decomposition** - Tasks break down as needed during execution
|
||||
- **On-demand creation** - Files and directories created only when required
|
||||
- **Agent autonomy** - Complete context preserved for independent execution
|
||||
## Core Architecture Principles
|
||||
|
||||
## Data Architecture
|
||||
### Key Design Decisions
|
||||
- **JSON files are the single source of truth** - All markdown documents are read-only generated views
|
||||
- **Marker files for session tracking** - Ultra-simple active session management
|
||||
- **Unified file structure definition** - Same structure template for all workflows, created on-demand
|
||||
- **Dynamic task decomposition** - Subtasks created as needed during execution
|
||||
- **On-demand file creation** - Directories and files created only when required
|
||||
- **Agent-agnostic task definitions** - Complete context preserved for autonomous execution
|
||||
|
||||
### JSON-Only Data Model
|
||||
**Core Principle**: JSON files are the authoritative source; markdown documents are read-only generated views.
|
||||
## Session Management
|
||||
|
||||
- **Task State**: Stored exclusively in `.task/IMPL-*.json` files
|
||||
### Active Session Marker System
|
||||
**Ultra-Simple Active Tracking**: `.workflow/.active-[session-name]`
|
||||
|
||||
```bash
|
||||
.workflow/
|
||||
├── WFS-oauth-integration/ # Session directory (paused)
|
||||
├── WFS-user-profile/ # Session directory (paused)
|
||||
├── WFS-bug-fix-123/ # Session directory (completed)
|
||||
└── .active-WFS-user-profile # Marker file (indicates active session)
|
||||
```
|
||||
|
||||
**Marker File Benefits**:
|
||||
- **Zero Parsing**: File existence check is atomic and instant
|
||||
- **Atomic Operations**: File creation/deletion is naturally atomic
|
||||
- **Visual Discovery**: `ls .workflow/.active-*` shows active session immediately
|
||||
- **Simple Switching**: Delete old marker + create new marker = session switch
|
||||
|
||||
### Session Operations
|
||||
|
||||
#### Detect Active Session
|
||||
```bash
|
||||
active_session=$(find .workflow -name ".active-*" | head -1)
|
||||
if [ -n "$active_session" ]; then
|
||||
session_name=$(basename "$active_session" | sed 's/^\.active-//')
|
||||
echo "Active session: $session_name"
|
||||
fi
|
||||
```
|
||||
|
||||
#### Switch Session
|
||||
```bash
|
||||
find .workflow -name ".active-*" -delete && touch .workflow/.active-WFS-new-feature
|
||||
```
|
||||
|
||||
### Individual Session Tracking
|
||||
Each session directory contains `workflow-session.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "WFS-[topic-slug]",
|
||||
"project": "feature description",
|
||||
"type": "simple|medium|complex",
|
||||
"current_phase": "PLAN|IMPLEMENT|REVIEW",
|
||||
"status": "active|paused|completed",
|
||||
"progress": {
|
||||
"completed_phases": ["PLAN"],
|
||||
"current_tasks": ["IMPL-1", "IMPL-2"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Data Model
|
||||
|
||||
### JSON-Only Architecture
|
||||
**JSON files (.task/IMPL-*.json) are the only authoritative source of task state. All markdown documents are read-only generated views.**
|
||||
|
||||
- **Task State**: Stored exclusively in JSON files
|
||||
- **Documents**: Generated on-demand from JSON data
|
||||
- **No Synchronization**: Eliminates bidirectional sync complexity
|
||||
- **Performance**: Direct JSON access without parsing overhead
|
||||
@@ -59,12 +113,35 @@ All task files use this simplified 5-field schema:
|
||||
"command": "bash(cat .workflow/*/summaries/IMPL-1.1-summary.md)",
|
||||
"output_to": "auth_design_context",
|
||||
"on_error": "skip_optional"
|
||||
},
|
||||
{
|
||||
"step": "analyze_patterns",
|
||||
"action": "Analyze existing auth patterns",
|
||||
"command": "bash(~/.claude/scripts/gemini-wrapper -p '@{src/auth/**/*} analyze authentication patterns using context: [auth_design_context]')",
|
||||
"output_to": "pattern_analysis",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "implement",
|
||||
"action": "Implement JWT based on analysis",
|
||||
"command": "bash(codex --full-auto exec 'Implement JWT using analysis: [pattern_analysis] and dependency context: [auth_design_context]')",
|
||||
"on_error": "manual_intervention"
|
||||
}
|
||||
],
|
||||
"implementation_approach": {
|
||||
"task_description": "Implement comprehensive JWT authentication system...",
|
||||
"modification_points": ["Add JWT token generation...", "..."],
|
||||
"logic_flow": ["User login request → validate credentials...", "..."]
|
||||
"task_description": "Implement comprehensive JWT authentication system with secure token management and validation middleware. Reference [inherited.context] from parent task [parent] for architectural consistency. Apply [shared_context.auth_strategy] across authentication modules. Focus implementation on [focus_paths] directories following established patterns.",
|
||||
"modification_points": [
|
||||
"Add JWT token generation in login handler (src/auth/login.ts:handleLogin:75-120) following [shared_context.auth_strategy]",
|
||||
"Implement token validation middleware (src/middleware/auth.ts:validateToken) referencing [inherited.context] design patterns",
|
||||
"Add refresh token mechanism for session management using [shared_context] token strategy",
|
||||
"Update user authentication flow to support JWT tokens in [focus_paths] modules"
|
||||
],
|
||||
"logic_flow": [
|
||||
"User login request → validate credentials → generate JWT token using [shared_context.auth_strategy] → store refresh token",
|
||||
"Protected route access → extract JWT from headers → validate token against [inherited.context] schema → allow/deny access",
|
||||
"Token expiry handling → use refresh token following [shared_context] strategy → generate new JWT → continue session",
|
||||
"Logout process → invalidate refresh token → clear client-side tokens in [focus_paths] components"
|
||||
]
|
||||
},
|
||||
"target_files": [
|
||||
"src/auth/login.ts:handleLogin:75-120",
|
||||
@@ -137,32 +214,45 @@ Each step contains:
|
||||
- **retry_once**: Retry step once, then fail if still unsuccessful
|
||||
- **manual_intervention**: Pause execution for manual review
|
||||
|
||||
#### Example Flow Control Patterns
|
||||
|
||||
**Pattern 1: Multi-Step Analysis**
|
||||
#### Example Flow Control
|
||||
```json
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "gather_dependencies",
|
||||
"command": "bash(for dep in ${depends_on}; do cat .summaries/$dep-summary.md; done)",
|
||||
"output_to": "dependency_context"
|
||||
{
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "gather_dependencies",
|
||||
"action": "Load context from completed dependencies",
|
||||
"command": "bash(for dep in ${depends_on}; do cat .summaries/$dep-summary.md 2>/dev/null || echo \"No summary for $dep\"; done)",
|
||||
"output_to": "dependency_context",
|
||||
"on_error": "skip_optional"
|
||||
},
|
||||
{
|
||||
"step": "analyze_codebase",
|
||||
"action": "Understand current implementation",
|
||||
"command": "bash(gemini -p '@{[focus_paths]} analyze current patterns using context: [dependency_context]')",
|
||||
"output_to": "codebase_analysis",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "implement",
|
||||
"action": "Execute implementation based on analysis",
|
||||
"command": "bash(codex --full-auto exec 'Implement based on: [codebase_analysis] with dependency context: [dependency_context]')",
|
||||
"on_error": "manual_intervention"
|
||||
}
|
||||
],
|
||||
"implementation_approach": {
|
||||
"task_description": "Execute implementation following [codebase_analysis] patterns and [dependency_context] requirements",
|
||||
"modification_points": [
|
||||
"Update target files in [focus_paths] following established patterns",
|
||||
"Apply [dependency_context] insights to maintain consistency"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Analyze existing patterns → apply dependency context → implement changes → validate results"
|
||||
]
|
||||
},
|
||||
{
|
||||
"step": "analyze_codebase",
|
||||
"command": "bash(gemini -p '@{[focus_paths]} using context: [dependency_context]')",
|
||||
"output_to": "codebase_analysis"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Pattern 2: Direct Implementation**
|
||||
```json
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "implement",
|
||||
"command": "bash(codex --full-auto exec 'Implement [title] in [focus_paths]')"
|
||||
}
|
||||
]
|
||||
"target_files": [
|
||||
"file:function:lines format for precise targeting"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Benefits of Flow Control
|
||||
@@ -172,205 +262,146 @@ Each step contains:
|
||||
- **Command Flexibility**: Supports any executable command or agent
|
||||
- **Dependency Integration**: Automatic loading of prerequisite task results
|
||||
|
||||
### Task Hierarchy
|
||||
**Structure**: Maximum 2 levels (IMPL-N.M format)
|
||||
### Hierarchical Task System
|
||||
**Maximum Depth**: 2 levels (IMPL-N.M format)
|
||||
|
||||
```
|
||||
IMPL-1 # Main task
|
||||
IMPL-1.1 # Subtask (dynamically created)
|
||||
IMPL-1.2 # Another subtask
|
||||
IMPL-1.1 # Subtask of IMPL-1 (dynamically created)
|
||||
IMPL-1.2 # Another subtask of IMPL-1
|
||||
IMPL-2 # Another main task
|
||||
IMPL-2.1 # Subtask (dynamically created)
|
||||
IMPL-2.1 # Subtask of IMPL-2 (dynamically created)
|
||||
```
|
||||
|
||||
**Rules**:
|
||||
- **Container tasks**: Parent tasks with subtasks (cannot execute directly)
|
||||
- **Leaf tasks**: Only executable tasks
|
||||
**Task Status Rules**:
|
||||
- **Container tasks**: Parent tasks with subtasks (cannot be directly executed)
|
||||
- **Leaf tasks**: Only these can be executed directly
|
||||
- **Status inheritance**: Parent status derived from subtask completion
|
||||
|
||||
## Session Management
|
||||
## File Structure
|
||||
|
||||
### Active Session Marker System
|
||||
**Ultra-Simple Tracking**: `.workflow/.active-[session-name]`
|
||||
|
||||
```bash
|
||||
.workflow/
|
||||
├── WFS-oauth-integration/ # Session directory (paused)
|
||||
├── WFS-user-profile/ # Session directory (paused)
|
||||
├── WFS-bug-fix-123/ # Session directory (completed)
|
||||
└── .active-WFS-user-profile # Marker file (active session)
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- **Zero Parsing**: File existence check is atomic
|
||||
- **Atomic Operations**: File creation/deletion is naturally atomic
|
||||
- **Visual Discovery**: `ls .workflow/.active-*` shows active session
|
||||
- **Simple Switching**: Delete old + create new marker
|
||||
|
||||
### Session Operations
|
||||
|
||||
```bash
|
||||
# Detect active session
|
||||
active_session=$(find .workflow -name ".active-*" | head -1)
|
||||
if [ -n "$active_session" ]; then
|
||||
session_name=$(basename "$active_session" | sed 's/^\.active-//')
|
||||
echo "Active session: $session_name"
|
||||
fi
|
||||
|
||||
# Switch session
|
||||
find .workflow -name ".active-*" -delete && touch .workflow/.active-WFS-new-feature
|
||||
```
|
||||
|
||||
### Session State
|
||||
Each session directory contains `workflow-session.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "WFS-[topic-slug]",
|
||||
"project": "feature description",
|
||||
"type": "simple|medium|complex",
|
||||
"current_phase": "PLAN|IMPLEMENT|REVIEW",
|
||||
"status": "active|paused|completed",
|
||||
"progress": {
|
||||
"completed_phases": ["PLAN"],
|
||||
"current_tasks": ["IMPL-1", "IMPL-2"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## File Organization
|
||||
|
||||
### Unified Structure
|
||||
All workflows use the same structure regardless of complexity. **Files created on-demand only.**
|
||||
### Unified File Structure
|
||||
All workflows use the same file structure definition regardless of complexity. **Directories and files are created on-demand as needed**, not all at once during initialization.
|
||||
|
||||
#### Complete Structure Reference
|
||||
```
|
||||
.workflow/WFS-[topic-slug]/
|
||||
├── workflow-session.json # Session state (REQUIRED)
|
||||
├── IMPL_PLAN.md # Planning document (REQUIRED)
|
||||
├── TODO_LIST.md # Progress tracking (REQUIRED)
|
||||
├── .task/ # Task definitions (REQUIRED)
|
||||
│ ├── IMPL-*.json # Main task definitions
|
||||
│ └── IMPL-*.*.json # Subtask definitions (dynamic)
|
||||
├── [.brainstorming/] # Brainstorming phase (on-demand)
|
||||
├── [.chat/] # CLI sessions (on-demand)
|
||||
├── workflow-session.json # Session metadata and state (REQUIRED)
|
||||
├── [.brainstorming/] # Optional brainstorming phase (created when needed)
|
||||
├── [.chat/] # CLI interaction sessions (created when analysis is run)
|
||||
│ ├── chat-*.md # Saved chat sessions
|
||||
│ └── analysis-*.md # Analysis results
|
||||
└── [.summaries/] # Task summaries (on-demand)
|
||||
├── IMPL-*.md # Main task summaries
|
||||
└── IMPL-*.*.md # Subtask summaries
|
||||
├── IMPL_PLAN.md # Planning document (REQUIRED)
|
||||
├── TODO_LIST.md # Progress tracking (REQUIRED)
|
||||
├── [.summaries/] # Task completion summaries (created when tasks complete)
|
||||
│ ├── IMPL-*.md # Main task summaries
|
||||
│ └── IMPL-*.*.md # Subtask summaries
|
||||
└── .task/ # Task definitions (REQUIRED)
|
||||
├── IMPL-*.json # Main task definitions
|
||||
└── IMPL-*.*.json # Subtask definitions (created dynamically)
|
||||
```
|
||||
|
||||
### Creation Strategy
|
||||
- **Initial**: Only `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`, `.task/`
|
||||
- **On-Demand**:
|
||||
- `.brainstorming/` → When brainstorming initiated
|
||||
- `.chat/` → When analysis commands executed
|
||||
- `.summaries/` → When first task completed
|
||||
#### Creation Strategy
|
||||
- **Initial Setup**: Create only `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`, and `.task/` directory
|
||||
- **On-Demand Creation**: Other directories created when first needed:
|
||||
- `.brainstorming/` → When brainstorming phase is initiated
|
||||
- `.chat/` → When CLI analysis commands are executed
|
||||
- `.summaries/` → When first task is completed
|
||||
- **Dynamic Files**: Subtask JSON files created during task decomposition
|
||||
|
||||
### Naming Conventions
|
||||
- **Sessions**: `WFS-[topic-slug]` (lowercase with hyphens)
|
||||
- **Conflicts**: Add `-NNN` suffix if needed
|
||||
- **Documents**: Standard names (`workflow-session.json`, `IMPL_PLAN.md`, etc.)
|
||||
- **Chat**: `chat-analysis-*.md`
|
||||
- **Summaries**: `IMPL-[task-id]-summary.md`
|
||||
### File Naming Conventions
|
||||
|
||||
## Workflow Classification
|
||||
#### Session Identifiers
|
||||
**Format**: `WFS-[topic-slug]`
|
||||
- Convert topic to lowercase with hyphens (e.g., "User Auth System" → `WFS-user-auth-system`)
|
||||
- Add `-NNN` suffix only if conflicts exist (e.g., `WFS-payment-integration-002`)
|
||||
|
||||
### Complexity Types
|
||||
**Based on task count and decomposition needs:**
|
||||
#### Document Naming
|
||||
- `workflow-session.json` - Session state (required)
|
||||
- `IMPL_PLAN.md` - Planning document (required)
|
||||
- `TODO_LIST.md` - Progress tracking (auto-generated when needed)
|
||||
- Chat sessions: `chat-analysis-*.md`
|
||||
- Task summaries: `IMPL-[task-id]-summary.md`
|
||||
|
||||
| Type | Tasks | Depth | Behavior |
|
||||
|------|-------|-------|----------|
|
||||
| **Simple** | ≤5 | 1 level | Direct execution, minimal decomposition |
|
||||
| **Medium** | 6-10 | 2 levels | Moderate decomposition, context coordination |
|
||||
| **Over-scope** | >10 | Re-scope | Requires project re-scoping into iterations |
|
||||
## Complexity Classification
|
||||
|
||||
### Characteristics
|
||||
### Task Complexity Rules
|
||||
**Complexity is determined by task count and decomposition needs:**
|
||||
|
||||
**Simple**: Bug fixes, small features, config changes
|
||||
- Single-level tasks, direct execution, ≤5 tasks
|
||||
| Complexity | Task Count | Hierarchy Depth | Decomposition Behavior |
|
||||
|------------|------------|----------------|----------------------|
|
||||
| **Simple** | <5 tasks | 1 level (IMPL-N) | Direct execution, minimal decomposition |
|
||||
| **Medium** | 5-15 tasks | 2 levels (IMPL-N.M) | Moderate decomposition, context coordination |
|
||||
| **Complex** | >15 tasks | 2 levels (IMPL-N.M) | Frequent decomposition, multi-agent orchestration |
|
||||
|
||||
**Medium**: New features, API endpoints, schema changes
|
||||
- Two-level hierarchy, context coordination, 6-10 tasks
|
||||
### Simple Workflows
|
||||
**Characteristics**: Direct implementation tasks with clear, limited scope
|
||||
- **Examples**: Bug fixes, small feature additions, configuration changes
|
||||
- **Task Decomposition**: Usually single-level tasks, minimal breakdown needed
|
||||
- **Agent Coordination**: Direct execution without complex orchestration
|
||||
|
||||
**Over-scope**: Major features exceeding 10 tasks
|
||||
- Requires re-scoping into smaller iterations, never >10 tasks
|
||||
### Medium Workflows
|
||||
**Characteristics**: Feature implementation requiring moderate task breakdown
|
||||
- **Examples**: New features, API endpoints with integration, database schema changes
|
||||
- **Task Decomposition**: Two-level hierarchy when decomposition is needed
|
||||
- **Agent Coordination**: Context coordination between related tasks
|
||||
|
||||
### Assessment Rules
|
||||
- **Creation**: System evaluates and assigns complexity
|
||||
- **10-task limit**: Hard limit enforced - exceeding requires re-scoping
|
||||
- **Execution**: Can upgrade (Simple→Medium→Over-scope), triggers re-scoping
|
||||
- **Override**: Users can manually specify complexity within 10-task limit
|
||||
### Complex Workflows
|
||||
**Characteristics**: System-wide changes requiring detailed decomposition
|
||||
- **Examples**: Major features, architecture refactoring, security implementations, multi-service deployments
|
||||
- **Task Decomposition**: Frequent use of two-level hierarchy with dynamic subtask creation
|
||||
- **Agent Coordination**: Multi-agent orchestration with deep context analysis
|
||||
|
||||
## Task Execution Framework
|
||||
### Automatic Assessment & Upgrades
|
||||
- **During Creation**: System evaluates requirements and assigns complexity
|
||||
- **During Execution**: Can upgrade (Simple→Medium→Complex) but never downgrade
|
||||
- **Override Allowed**: Users can specify higher complexity manually
|
||||
|
||||
### Agent Integration
|
||||
## Document Templates
|
||||
|
||||
**Assignment Rules** (based on task type/keywords):
|
||||
- **Planning** → planning-agent
|
||||
- **Implementation** → code-developer
|
||||
- **Testing** → code-review-test-agent
|
||||
- **Review** → review-agent
|
||||
### IMPL_PLAN.md
|
||||
Generated based on task complexity and requirements. Contains overview, requirements, and task structure.
|
||||
|
||||
**Execution Context** (agents receive):
|
||||
### Task Summary Template (.summaries/IMPL-X.X-summary.md)
|
||||
Enhanced summary documents for context inheritance and dependency resolution:
|
||||
|
||||
```markdown
|
||||
# Task Summary: [task-id] - [title]
|
||||
|
||||
## Context Provided
|
||||
- **Parent Context**: [inherited context from parent task]
|
||||
- **Dependencies Resolved**:
|
||||
- [dep-1]: [brief description of what was provided]
|
||||
- [dep-2]: [brief description of what was provided]
|
||||
|
||||
## Implementation Details
|
||||
### Approach
|
||||
[Brief description of the implementation strategy used]
|
||||
|
||||
### Files Modified
|
||||
- `[file-path]`: [description of changes made]
|
||||
- `[file-path]`: [description of changes made]
|
||||
|
||||
### Key Decisions
|
||||
- [Decision 1]: [rationale]
|
||||
- [Decision 2]: [rationale]
|
||||
|
||||
## Outputs for Dependent Tasks
|
||||
### Shared Context
|
||||
```json
|
||||
{
|
||||
"task": { /* complete task JSON */ },
|
||||
"workflow": {
|
||||
"session": "WFS-user-auth",
|
||||
"phase": "IMPLEMENT"
|
||||
"key_component": "location or identifier",
|
||||
"configuration": {
|
||||
"setting1": "value1",
|
||||
"setting2": "value2"
|
||||
},
|
||||
"integration_points": ["endpoint1", "function2"],
|
||||
"important_constants": {
|
||||
"timeout": "30s",
|
||||
"max_retries": 3
|
||||
}
|
||||
}
|
||||
```
|
||||
## Operations Guide
|
||||
|
||||
### Basic Operations
|
||||
|
||||
```bash
|
||||
# Session initialization
|
||||
mkdir -p .workflow/WFS-topic-slug/.task
|
||||
echo '{"session_id":"WFS-topic-slug",...}' > .workflow/WFS-topic-slug/workflow-session.json
|
||||
echo '# Implementation Plan' > .workflow/WFS-topic-slug/IMPL_PLAN.md
|
||||
echo '# Tasks' > .workflow/WFS-topic-slug/TODO_LIST.md
|
||||
|
||||
# Task creation
|
||||
echo '{"id":"IMPL-1","title":"New task",...}' > .task/IMPL-1.json
|
||||
|
||||
# Task updates
|
||||
jq '.status = "active"' .task/IMPL-1.json > temp && mv temp .task/IMPL-1.json
|
||||
|
||||
# Document generation
|
||||
generate_todo_list_from_json .task/
|
||||
```
|
||||
|
||||
### Validation Rules
|
||||
1. **ID Uniqueness**: All task IDs must be unique
|
||||
2. **Format**: IMPL-N[.M] pattern (max 2 levels)
|
||||
3. **References**: Parent IDs must exist as JSON files
|
||||
4. **Fields**: All 5 core fields required (id, title, status, meta, context, flow_control)
|
||||
5. **Paths**: context.focus_paths must contain valid project paths
|
||||
6. **Dependencies**: context.depends_on task IDs must exist
|
||||
|
||||
### Error Recovery
|
||||
- **Missing Session**: Remove orphaned active marker
|
||||
- **Multiple Active**: Keep newest, remove others
|
||||
- **Corrupted Session**: Recreate from template
|
||||
- **Broken Hierarchy**: Reconstruct parent-child relationships
|
||||
|
||||
```bash
|
||||
# Session consistency check
|
||||
active_marker=$(find .workflow -name ".active-*" | head -1)
|
||||
if [ -n "$active_marker" ]; then
|
||||
session_name=$(basename "$active_marker" | sed 's/^\.active-//')
|
||||
session_dir=".workflow/$session_name"
|
||||
if [ ! -d "$session_dir" ]; then
|
||||
echo "⚠️ Orphaned active marker, removing..."
|
||||
rm "$active_marker"
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
## Reference Templates
|
||||
|
||||
### Integration Points
|
||||
- **[Component Name]**: [how to use/integrate]
|
||||
@@ -385,7 +416,15 @@ fi
|
||||
## Notes for Future Tasks
|
||||
[Any important considerations, limitations, or follow-up items]
|
||||
```
|
||||
### TODO List (TODO_LIST.md)
|
||||
|
||||
#### Summary Document Purpose
|
||||
- **Context Inheritance**: Provides structured context for dependent tasks
|
||||
- **Integration Guidance**: Offers clear integration points and usage instructions
|
||||
- **Quality Assurance**: Documents testing and validation performed
|
||||
- **Decision History**: Preserves rationale for implementation choices
|
||||
- **Dependency Chain**: Enables automatic context accumulation through task dependencies
|
||||
|
||||
### TODO_LIST.md Template
|
||||
```markdown
|
||||
# Tasks: [Session Topic]
|
||||
|
||||
@@ -393,7 +432,7 @@ fi
|
||||
▸ **IMPL-001**: [Main Task Group] → [📋](./.task/IMPL-001.json)
|
||||
- [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/IMPL-001.1.json)
|
||||
- [x] **IMPL-001.2**: [Subtask] → [📋](./.task/IMPL-001.2.json) | [✅](./.summaries/IMPL-001.2.md)
|
||||
|
||||
|
||||
- [x] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json) | [✅](./.summaries/IMPL-002.md)
|
||||
|
||||
▸ **IMPL-003**: [Main Task Group] → [📋](./.task/IMPL-003.json)
|
||||
@@ -402,7 +441,7 @@ fi
|
||||
|
||||
## Status Legend
|
||||
- `▸` = Container task (has subtasks)
|
||||
- `- [ ]` = Pending leaf task
|
||||
- `- [ ]` = Pending leaf task
|
||||
- `- [x]` = Completed leaf task
|
||||
- Maximum 2 levels: Main tasks and subtasks only
|
||||
|
||||
@@ -410,6 +449,97 @@ fi
|
||||
[Optional notes]
|
||||
```
|
||||
|
||||
## Agent Integration
|
||||
|
||||
### Agent Assignment
|
||||
Based on task type and title keywords:
|
||||
- **Planning tasks** → planning-agent
|
||||
- **Implementation** → code-developer
|
||||
- **Testing** → code-review-test-agent
|
||||
- **Review** → review-agent
|
||||
|
||||
### Execution Context
|
||||
Agents receive complete task JSON plus workflow context:
|
||||
```json
|
||||
{
|
||||
"task": { /* complete task JSON */ },
|
||||
"workflow": {
|
||||
"session": "WFS-user-auth",
|
||||
"phase": "IMPLEMENT"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Data Operations
|
||||
|
||||
### Session Initialization
|
||||
```bash
|
||||
# Create minimal required structure
|
||||
mkdir -p .workflow/WFS-topic-slug/.task
|
||||
echo '{"session_id":"WFS-topic-slug",...}' > .workflow/WFS-topic-slug/workflow-session.json
|
||||
echo '# Implementation Plan' > .workflow/WFS-topic-slug/IMPL_PLAN.md
|
||||
echo '# Tasks' > .workflow/WFS-topic-slug/TODO_LIST.md
|
||||
```
|
||||
|
||||
### Task Creation
|
||||
```bash
|
||||
echo '{"id":"IMPL-1","title":"New task",...}' > .task/IMPL-1.json
|
||||
```
|
||||
|
||||
### Directory Creation (On-Demand)
|
||||
```bash
|
||||
# Create directories only when needed
|
||||
mkdir -p .brainstorming # When brainstorming is initiated
|
||||
mkdir -p .chat # When analysis commands are run
|
||||
mkdir -p .summaries # When first task completes
|
||||
```
|
||||
|
||||
### Task Updates
|
||||
```bash
|
||||
jq '.status = "active"' .task/IMPL-1.json > temp && mv temp .task/IMPL-1.json
|
||||
```
|
||||
|
||||
### Document Generation
|
||||
```bash
|
||||
# Generate TODO_LIST.md from current JSON state
|
||||
generate_todo_list_from_json .task/
|
||||
```
|
||||
|
||||
## Validation and Error Handling
|
||||
|
||||
### Task Integrity Rules
|
||||
1. **ID Uniqueness**: All task IDs must be unique
|
||||
2. **Hierarchical Format**: Must follow IMPL-N[.M] pattern (maximum 2 levels)
|
||||
3. **Parent References**: All parent IDs must exist as JSON files
|
||||
4. **Depth Limits**: Maximum 2 levels deep
|
||||
5. **Status Consistency**: Status values from defined enumeration
|
||||
6. **Required Fields**: All 5 core fields must be present (id, title, status, meta, context, flow_control)
|
||||
7. **Focus Paths Structure**: context.focus_paths array must contain valid project paths
|
||||
8. **Flow Control Format**: flow_control.pre_analysis must be array with step, action, command fields
|
||||
9. **Dependency Integrity**: All context.depends_on task IDs must exist as JSON files
|
||||
|
||||
### Session Consistency Checks
|
||||
```bash
|
||||
# Validate active session integrity
|
||||
active_marker=$(find .workflow -name ".active-*" | head -1)
|
||||
if [ -n "$active_marker" ]; then
|
||||
session_name=$(basename "$active_marker" | sed 's/^\.active-//')
|
||||
session_dir=".workflow/$session_name"
|
||||
|
||||
if [ ! -d "$session_dir" ]; then
|
||||
echo "⚠️ Orphaned active marker, removing..."
|
||||
rm "$active_marker"
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
### Recovery Strategies
|
||||
- **Missing Session Directory**: Remove orphaned active marker
|
||||
- **Multiple Active Markers**: Keep newest, remove others
|
||||
- **Corrupted Session File**: Recreate from template
|
||||
- **Broken Task Hierarchy**: Reconstruct parent-child relationships
|
||||
|
||||
---
|
||||
|
||||
**System Design**: Unified workflow architecture featuring ultra-fast session management, JSON-only data model, and consistent file structure across all workflow types.
|
||||
**System ensures**: Unified workflow architecture with ultra-fast session management, JSON-only data model, and unified file structure for all workflows regardless of complexity.
|
||||
Reference in New Issue
Block a user