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

- 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>
2026-02-12 02:37:45 +08:00 · 2025-09-15 21:55:28 +08:00
parent 2b7aad6d65
commit 9371af8d8d
17 changed files with 878 additions and 776 deletions
--- a/.claude/commands/task/breakdown.md
+++ b/.claude/commands/task/breakdown.md
@@ -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
--- a/.claude/commands/task/create.md
+++ b/.claude/commands/task/create.md
@@ -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
--- a/.claude/commands/task/execute.md
+++ b/.claude/commands/task/execute.md
@@ -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
--- a/.claude/commands/task/replan.md
+++ b/.claude/commands/task/replan.md
@@ -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