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

Refactor workflow plan command and architecture documentation

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

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

@@ -2,303 +2,116 @@
name: plan
description: Create implementation plans with intelligent input detection
usage: /workflow:plan <input>
argument-hint: "text description"|file.md|ISS-001|template-name
argument-hint: "text description"|file.md|ISS-001
examples:
- /workflow:plan "Build authentication system"
- /workflow:plan requirements.md
- /workflow:plan ISS-001
---
# Workflow Plan Command (/workflow:plan)
## Overview
Creates actionable implementation plans with intelligent input source detection. Supports text, files, issues, and templates through automatic recognition.
## Core Principles
**File Structure:** @~/.claude/workflows/workflow-architecture.md
**Dependency Context Rules:**
- **For tasks with dependencies**: MUST read previous task summary documents before planning
- **Context inheritance**: Use dependency summaries to maintain consistency and avoid duplicate work
# Workflow Plan Command
## Usage
```bash
/workflow:plan [--AM gemini|codex] <input>
/workflow:plan [--AM gemini|codex] [--analyze|--deep] <input>
```
### Analysis Method Flag (--AM)
Optional flag to specify which CLI tool to use for context analysis:
- **gemini** (default): Uses Gemini CLI for pattern-based analysis, architectural understanding, and broader context acquisition
- **codex**: Uses Codex CLI for autonomous development context gathering with intelligent file discovery
## Input Detection
- **Files**: `.md/.txt/.json/.yaml/.yml` → Reads content and extracts requirements
- **Issues**: `ISS-*`, `ISSUE-*`, `*-request-*` → Loads issue data and acceptance criteria
- **Text**: Everything else → Parses natural language requirements
**Examples**:
```bash
/workflow:plan --AM codex "Build authentication system"
/workflow:plan --AM gemini requirements.md
```
## Analysis Levels
- **Quick** (default): Structure only (5s)
- **--analyze**: Structure + context analysis (30s)
- **--deep**: Structure + comprehensive parallel analysis (1-2m)
## Input Detection Logic
The command automatically detects input type:
## Core Rules
### File Input (Auto-detected)
```bash
/workflow:plan requirements.md
/workflow:plan config.json
```
**Triggers**: Extensions: .md, .txt, .json, .yaml, .yml
**Processing**: Reads file contents and extracts requirements
### File Structure Reference
**Architecture**: @~/.claude/workflows/workflow-architecture.md
### Issue Input (Auto-detected)
```bash
/workflow:plan ISS-001
/workflow:plan ISSUE-123
```
**Triggers**: Patterns: ISS-*, ISSUE-*, *-request-*
**Processing**: Loads issue data and acceptance criteria
### Task Limits & Decomposition
- **Maximum 10 tasks**: Hard enforced limit - projects exceeding must be re-scoped
- **Function-based decomposition**: By complete functional units, not files/steps
- **File cohesion**: Group related files (UI + logic + tests + config) in same task
- **Task saturation**: Merge "analyze + implement" by default (0.5 count for complex prep tasks)
### Text Input (Default)
```bash
/workflow:plan "Build user authentication with JWT and OAuth2"
```
**Triggers**: Everything else
**Processing**: Parse natural language requirements
## Automatic Behaviors
### Pre-Planning Analysis (CRITICAL)
⚠️ **Must complete BEFORE generating any plan documents**
1. **Complexity assessment**: Count total saturated tasks
2. **Decomposition strategy**: Flat (≤5) | Hierarchical (6-10) | Re-scope (>10)
3. **File grouping**: Identify cohesive file sets
4. **Quantity prediction**: Estimate main tasks, subtasks, container vs leaf ratio
### Session Management
- Creates new session if none exists
- Uses active session if available
- Generates session ID: WFS-[topic-slug]
- **Active session check**: Check for `.workflow/.active-*` marker first
- Auto-creates new session: `WFS-[topic-slug]`
- Uses existing active session if available
- **Dependency context**: MUST read previous task summary documents before planning
### Pre-Planning Analysis
⚠️ **CRITICAL**: Determine decomposition strategy BEFORE generating any plan documents
## Task Patterns
**Required Pre-Analysis Steps**:
1. **Complexity Assessment**: Analyze requirements to determine total saturated task count
2. **Decomposition Strategy**: Based on complexity, decide:
- Task structure (flat vs hierarchical)
- Re-scoping necessity (>10 tasks triggers re-scoping)
- Task saturation level (merged vs separated)
- File grouping strategy (cohesive files together)
3. **Quantity Prediction**: Calculate expected:
- Total main tasks (IMPL-XXX)
- Subtasks per main task (IMPL-N.M)
- Container vs leaf task ratio
### ✅ Correct (Function-based)
- `IMPL-001: User authentication system` (models + routes + components + middleware + tests)
- `IMPL-002: Data export functionality` (service + routes + UI + utils + tests)
**Pre-Planning Outputs**:
- Complexity level: Simple (≤5) | Medium (6-10) | Over-scoped (>10, requires re-scoping)
- Decomposition approach: Flat | Two-level hierarchy | Re-scope required
- Estimated task count: [number] main tasks, [number] total leaf tasks (max 10)
- Document set: Which documents will be generated (IMPL_PLAN.md, TODO_LIST.md, .task/*.json)
- **Re-scoping recommendation**: If >10 tasks, provide guidance for breaking into iterations
**Only after completing pre-planning analysis**: Proceed to generate actual plan documents
### Complexity Detection with Saturation
*Based on Pre-Planning Analysis results:*
- **Simple**: ≤5 saturated tasks → Direct IMPL_PLAN.md
- **Medium**: 6-10 saturated tasks → IMPL_PLAN.md + TODO_LIST.md
- **Complex**: Exceeding 10 tasks requires re-scoping (maximum enforced)
**10-Task Hard Limit**: Projects exceeding 10 tasks must be re-scoped into smaller iterations
**Note**: 1 complex preparation task = 0.5 saturated task for counting
### Task Granularity Principles
- **Decompose by function, not by file**: Each task should complete a whole functional unit
- **Maintain functional integrity**: Each task produces independently runnable or testable functionality
- **Group related files together**: Keep related files (UI, logic, tests, config) in same task
- **File cohesion rule**: Files that work together should be modified in the same task
- **Avoid technical step decomposition**: Don't make "create file" or "add function" as separate tasks
- **Maximum 10 tasks**: Hard limit enforced; re-scope if exceeded
### Task Decomposition Anti-patterns
❌ **Wrong Example - File/Step-based Decomposition**:
- IMPL-001: Create database model
- IMPL-002: Create API endpoint
- IMPL-003: Create frontend component
- IMPL-004: Add routing configuration
- IMPL-005: Write unit tests
❌ **Wrong Example - Same File Split Across Tasks**:
- IMPL-001: Add authentication routes to routes/auth.js
- IMPL-002: Add user validation to routes/auth.js
- IMPL-003: Add session handling to routes/auth.js
✅ **Correct Example - Function-based with File Cohesion**:
- IMPL-001: Implement user authentication (includes models/User.js, routes/auth.js, components/LoginForm.jsx, middleware/auth.js, tests/auth.test.js)
- IMPL-002: Implement data export functionality (includes services/export.js, routes/export.js, components/ExportButton.jsx, utils/fileGenerator.js, tests/export.test.js)
✅ **Correct Example - Related Files Grouped**:
- IMPL-001: User management system (includes User model, UserController, UserService, user routes, user tests)
- IMPL-002: Product catalog system (includes Product model, ProductController, catalog components, product tests)
### Task Generation with Saturation Control
*Using decomposition strategy determined in Pre-Planning Analysis:*
- **Task Saturation Assessment**: Evaluates whether to merge preparation and execution
- **Default merge mode**: "Analyze and implement X" instead of "Analyze X" + "Implement X"
- **Smart splitting**: Only separate when preparation complexity > threshold
- Automatically creates .task/ files when complexity warrants
- Generates hierarchical task structure (max 2 levels)
- Main tasks with subtasks become container tasks (not directly executable)
- Updates session state with task references
- Runs project structure analysis to populate paths field
### Project Analysis Options
Three analysis levels available:
```bash
# Quick - Structure only (5 seconds)
/workflow:plan "requirements"
# Standard - Structure + Gemini analysis (30 seconds)
/workflow:plan --analyze "requirements"
# Deep - Structure + Parallel comprehensive analysis (1-2 minutes)
/workflow:plan --deep "requirements"
```
**Analysis Selection**:
- Default: Auto-selects based on project complexity
- Manual: Use flags to override automatic selection
- Strategy: See @~/.claude/workflows/intelligent-tools-strategy.md for tool selection principles
**Execution**:
1. Always runs `get_modules_by_depth.sh` for structure
2. Applies selected analysis level
3. Populates task paths automatically
### Task Saturation Assessment
Evaluates whether to merge preparation and execution within 10-task limit:
**Default Merge Principles** (Saturated Tasks):
- All components of the same functional module
- Related files that work together (UI, logic, tests, config)
- Features with their corresponding tests and documentation
- Configuration with its usage code
- Multiple small interdependent functions
- Files that share common interfaces or data structures
**Only Separate Tasks When**:
- Completely independent functional modules (no shared code or interfaces)
- Independent services with different tech stacks (e.g., separate deployment units)
- Modules requiring different expertise (e.g., ML model training vs Web development)
- Large features with clear sequential dependencies
- **Critical**: Would exceed 10-task limit otherwise
**File Cohesion Examples**:
- **Merged**: "IMPL-001: Implement user authentication (includes models/User.js, routes/auth.js, components/LoginForm.jsx, tests/auth.test.js)"
- **Separated**: "IMPL-001: User service authentication" + "IMPL-002: Admin dashboard authentication" (different user contexts)
**10-Task Compliance**: Always prioritize related file grouping to stay within limit
### Task Breakdown Process
- **Automatic decomposition**: Only when task count >10 triggers re-scoping (not decomposition)
- **Function-based decomposition**: Split by independent functional boundaries, not by technical layers
- **Container tasks**: Parent tasks with subtasks become containers (marked with ▸ in TODO_LIST)
- **Smart decomposition**: AI analyzes task title to suggest logical functional subtask structure
- **Complete unit principle**: Each subtask must still represent a complete functional unit
- **Context inheritance**: Subtasks inherit parent's requirements and scope, refined for specific needs
- **Agent assignment**: Automatic agent mapping based on subtask type (planning/code/test/review)
- **Maximum depth**: 2 levels (IMPL-N.M) to maintain manageable hierarchy
- **10-task enforcement**: Exceeding 10 tasks requires project re-scoping
### Flow Control Field Requirements
- **flow_control**: Universal process manager containing:
- `pre_analysis`: Array of sequential process steps with:
- `step`: Unique identifier for the step
- `action`: Human-readable description
- `command`: Executable command with embedded context variables (e.g., `${variable_name}`)
- `output_to`: Variable name to store step results (optional for final steps)
- `on_error`: Error handling strategy
- `implementation_approach`: Brief one-line strategy description
- `target_files`: Array of "file:function:lines" format strings
- **Auto-generation**: Creates flow based on task type and complexity
- **Required fields**: meta (type, agent), context (requirements, focus_paths, acceptance, depends_on), flow_control
- **Focus paths format**: Array of strings (e.g., ["src/auth", "tests/auth", "config/auth.json"])
## Session Check Process
⚠️ **CRITICAL**: Check for existing active session before planning
1. **Check Active Session**: Check for `.workflow/.active-*` marker file
2. **Session Selection**: Use existing active session or create new
3. **Context Integration**: Load session state and existing context
### ❌ Wrong (File/step-based)
- `IMPL-001: Create database model`
- `IMPL-002: Create API endpoint`
- `IMPL-003: Create frontend component`
## Output Documents
### Document References for Execution
### Always Created
- **IMPL_PLAN.md**: Requirements, task breakdown, success criteria
- **Session state**: Task references and paths
#### Primary References
- **Planning Document**: `.workflow/WFS-[topic-slug]/IMPL_PLAN.md`
- Used by: `/workflow:execute` for context loading
- Contains: Requirements, task overview, success criteria
### Auto-Created (complexity > simple)
- **TODO_LIST.md**: Hierarchical progress tracking
- **.task/*.json**: Individual task definitions with flow_control
- **Task Definitions**: `.workflow/WFS-[topic-slug]/.task/IMPL-*.json`
- Used by: Agents for implementation context
- Contains: Complete task details with 7-field structure including flow_control process manager
- **Progress Tracking**: `.workflow/WFS-[topic-slug]/TODO_LIST.md`
- Used by: `/workflow:execute` for status tracking
- Updated by: Agents after task completion
### IMPL_PLAN.md (Always Created)
```markdown
# Implementation Plan - [Project Name]
*Generated from: [input_source]*
## Requirements
[Extracted requirements from input source]
## Task Breakdown
- **IMPL-001**: [Saturated task description with merged preparation and execution]
- **IMPL-002**: [Task description]
## Success Criteria
[Measurable completion conditions]
### Document Structure
```
.workflow/WFS-[topic]/
├── IMPL_PLAN.md # Main planning document
├── TODO_LIST.md # Progress tracking (if complex)
└── .task/
├── IMPL-001.json # Task definitions
└── IMPL-002.json
```
### Optional TODO_LIST.md (Auto-triggered)
Created when complexity > simple or task count > 3
## Task Saturation Assessment
**Default Merge** (cohesive files together):
- Functional modules with UI + logic + tests + config
- Features with their tests and documentation
- Files sharing common interfaces/data structures
**TODO_LIST Structure**: Uses unified hierarchical list format
- Container tasks (with subtasks) marked with `▸` symbol
- Leaf tasks use standard `- [ ]` / `- [x]` checkboxes
- Indentation shows hierarchy (2 spaces per level)
- Container tasks represent logical grouping, not executable items
**Only Separate When**:
- Completely independent functional modules
- Different tech stacks or deployment units
- Would exceed 10-task limit otherwise
### Task JSON Files (Auto-created)
Generated in .task/ directory when decomposition enabled
## Flow Control Schema
Each task.json includes required fields:
- **meta**: type, agent assignment
- **context**: requirements, focus_paths, acceptance, depends_on
- **flow_control**:
- `pre_analysis`: Steps with commands and context variables (${var})
- `implementation_approach`: One-line strategy
- `target_files`: "file:function:lines" format
## Execution Integration
Documents created for `/workflow:execute`:
- **IMPL_PLAN.md**: Context loading and requirements
- **.task/*.json**: Agent implementation context
- **TODO_LIST.md**: Status tracking (container tasks with ▸, leaf tasks with checkboxes)
## Error Handling
- **Vague input**: Auto-reject ("fix it", "make better", etc.)
- **File not found**: Clear suggestions
- **>10 tasks**: Force re-scoping into iterations
### Input Processing Errors
- **File not found**: Clear error message with suggestions
- **Invalid issue**: Verify issue ID exists
- **Unknown template**: List available templates
- **Empty input**: Prompt for valid input
- **Vague text input**: Auto-reject without guidance
- Rejected examples: "do something", "fix it", "make it better", "add feature"
- Response: Direct rejection message, no further assistance
### Recommended Task Patterns
#### Complete Feature Implementation
"Implement user management system" - includes all related files: models/User.js, controllers/UserController.js, routes/users.js, components/UserList.jsx, services/UserService.js, tests/user.test.js
#### End-to-End Features
"Add Excel export functionality" - includes cohesive file set: services/ExportService.js, utils/excelGenerator.js, routes/export.js, components/ExportButton.jsx, middleware/downloadHandler.js, tests/export.test.js
#### System Integration
"Integrate payment gateway" - includes integration files: services/PaymentService.js, controllers/PaymentController.js, models/Payment.js, components/PaymentForm.jsx, webhooks/paymentWebhook.js, tests/payment.test.js
#### Problem Resolution
"Fix and optimize search functionality" - includes related files: services/SearchService.js, utils/searchOptimizer.js, components/SearchBar.jsx, controllers/SearchController.js, tests/search.test.js
#### Module Development
"Create notification system" - includes module files: services/NotificationService.js, models/Notification.js, templates/emailTemplates.js, components/NotificationCenter.jsx, workers/notificationQueue.js, tests/notification.test.js
**File Cohesion Principle**: Each task includes ALL files that work together to deliver the complete functionality
**System ensures**: Unified planning interface with intelligent input detection, function-based task granularity, file cohesion enforcement, and 10-task maximum limit
## Analysis Method (--AM)
- **gemini** (default): Pattern analysis, architectural understanding
- **codex**: Autonomous development, intelligent file discovery