feat: Streamline agents to pure executor roles with enhanced workflow architecture

## Agent Streamlining - **code-developer.md**: Reduce from 315 to 122 lines - pure code execution focus - **action-planning-agent.md**: Reduce from 502 to 124 lines - pure planning execution - Remove complex decision logic - commands layer now handles control flow - Add clean code rules: minimize debug output, GBK compatibility, ASCII-only ## Workflow Architecture Enhancements - Enhanced workflow-architecture.md with progressive complexity system - Clear separation: Commands (control) → Agents (execution) → Output - Improved task decomposition and TODO_LIST.md examples - Added Gemini CLI standards references ## Command System Updates - Updated task and workflow commands with enhanced functionality - Better integration with streamlined agents - Improved error handling and user experience 🤖 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-10 21:41:58 +08:00
parent 44287cf80e
commit 5b80c9c242
14 changed files with 777 additions and 874 deletions
--- a/.claude/commands/task/breakdown.md
+++ b/.claude/commands/task/breakdown.md
@@ -82,7 +82,7 @@ Agents assigned:
 - impl-1.1 → planning-agent
 - impl-1.2 → code-developer
 - impl-1.3 → code-developer
- impl-1.4 → test-agent
+- impl-1.4 → code-review-test-agent

 JSON files created:
 - .task/impl-1.1.json
@@ -152,20 +152,81 @@ Parent context is intelligently distributed:
        "parent": "impl-1",
        "subtasks": [],
        "dependencies": []
+      },
+      "implementation": {
+        "files": [
+          {
+            "path": "src/auth/models/User.ts",
+            "location": {
+              "function": "UserSchema",
+              "lines": "auto-detect",
+              "description": "User schema definition for authentication"
+            },
+            "original_code": "// Requires gemini analysis for current schema structure",
+            "modifications": {
+              "current_state": "Basic user model without auth fields",
+              "proposed_changes": [
+                "Add JWT token storage fields",
+                "Include authentication provider fields",
+                "Add timestamp tracking for security"
+              ],
+              "logic_flow": [
+                "defineSchema() ───► addAuthFields() ───► validateStructure()",
+                "◊─── if JWT ───► addTokenFields() ───► addExpirationLogic()",
+                "◊─── if OAuth ───► addProviderFields() ───► linkExternalAccounts()"
+              ],
+              "reason": "Support comprehensive authentication system requirements",
+              "expected_outcome": "Robust user schema supporting multiple authentication methods"
+            }
+          }
+        ],
+        "context_notes": {
+          "dependencies": ["mongoose", "jsonwebtoken"],
+          "affected_modules": ["auth-service", "user-controller"],
+          "risks": [
+            "Database migration required for existing users",
+            "Schema validation complexity with multiple auth types"
+          ],
+          "performance_considerations": "Index auth fields for fast lookups",
+          "error_handling": "Graceful validation errors for schema changes"
+        },
+        "analysis_source": "auto-detected"
      }
    }
  ]
 }
 ```

+## Implementation Field Inheritance
+
+### Parent to Subtask Context Flow
+When breaking down tasks, implementation details are inherited and refined:
+
+**Parent Implementation Context**:
+- High-level file scope (e.g., "src/auth/*")
+- General requirements and dependencies
+- Architecture-level risks and considerations
+
+**Subtask Implementation Refinement**:
+- Specific file paths (e.g., "src/auth/models/User.ts")
+- Precise function locations and line ranges
+- Detailed modification steps and logic flows
+- Subtask-specific risks and dependencies
+
+**Auto-Population Strategy for Subtasks**:
+1. **Inherit from Parent**: Copy relevant files from parent.implementation.files
+2. **Refine Scope**: Narrow down to subtask-specific files and functions
+3. **Generate Details**: Create subtask-specific modifications and logic flows
+4. **Risk Analysis**: Identify subtask-level risks from parent context
+5. **Gemini Trigger**: Mark analysis_source as "gemini" when details need extraction
+
 ## Agent Assignment Logic

-Based on subtask type:
- **Design/Planning** → `planning-agent`
- **Implementation** → `code-developer`
- **Testing** → `test-agent`
- **Documentation** → `docs-agent`
- **Review** → `review-agent`
+Based on subtask type and implementation complexity:
+- **Design/Planning** → `planning-agent` (architectural implementation planning)
+- **Implementation** → `code-developer` (file-level code changes)
+- **Testing** → `code-review-test-agent` (test implementation for specific functions)
+- **Review** → `review-agent` (code review with implementation context)

 ## Validation

--- a/.claude/commands/task/create.md
+++ b/.claude/commands/task/create.md
@@ -65,7 +65,7 @@ Context inherited from workflow
 - `bugfix` - Bug fixes
 - `refactor` - Code improvements
 - `test` - Test implementation
- `docs` - Documentation
+- `docs` - Documentation (handled by code-developer)

 ### Priority Levels (Optional - moved to context)
 - `low` - Can be deferred  
@@ -103,26 +103,90 @@ Context inherited from workflow
    "last_attempt": null
  },
  
+  "implementation": {
+    "files": [
+      {
+        "path": "src/auth/login.ts",
+        "location": {
+          "function": "handleLogin",
+          "lines": "auto-detect",
+          "description": "Login handler function"
+        },
+        "original_code": "// Requires gemini analysis for code extraction",
+        "modifications": {
+          "current_state": "Basic password authentication",
+          "proposed_changes": [
+            "Add JWT token generation",
+            "Integrate OAuth2 flow"
+          ],
+          "logic_flow": [
+            "validateInput() ───► checkCredentials()",
+            "◊─── if valid ───► generateJWT() ───► return token"
+          ],
+          "reason": "Implement modern authentication standards",
+          "expected_outcome": "Secure, flexible authentication system"
+        }
+      }
+    ],
+    "context_notes": {
+      "dependencies": ["jsonwebtoken", "passport"],
+      "affected_modules": ["user-management", "session-handler"],
+      "risks": [
+        "Breaking changes to existing auth middleware",
+        "Database schema changes required"
+      ],
+      "performance_considerations": "JWT validation adds ~5ms per request",
+      "error_handling": "Ensure no sensitive data in error responses"
+    },
+    "analysis_source": "auto-detected"
+  }
 }
 ```

-## Simplified File Generation
+## Implementation Field Generation

-### JSON Task File Only
+### Auto-Population Strategy
+**Sufficient Information**: When task description contains specific details
+- Extract file paths from scope or task description
+- Identify functions/classes mentioned in requirements
+- Generate basic implementation structure automatically
+
+**Insufficient Information**: When details are vague or missing
+- Mark `analysis_source` as "gemini" 
+- Set `original_code` to "// Requires gemini analysis for code extraction"
+- Prompt user for gemini analysis:
+```bash
+⚠️ Implementation details incomplete for task: [task-title]
+Recommend running: 
+gemini --all-files -p "@{scope-patterns} @{CLAUDE.md} 
+Analyze task: [task-description]
+Extract: 1) File locations and functions 2) Current code state 3) Risks and dependencies"
+```
+
+### Implementation Quality Standards
+- **File paths**: Must be specific (not wildcards like "src/*")
+- **Location details**: Include function name or line range, not just file name
+- **Logic flow**: Use standard symbols (───►, ◊───, ◄───)
+- **Risk assessment**: At least 1 specific, actionable risk
+- **Dependencies**: Actual package names, not generic descriptions
+
+### Simplified File Generation
+
+### JSON Task File Only  
 **File Location**: `.task/impl-[N].json`
-**Naming**: Follows impl-N.M.P format for nested tasks  
-**Content**: Contains all task data (no document coordination needed)
+**Naming**: Follows impl-N.M.P format for nested tasks
+**Content**: Contains all task data including implementation details

 ### No Document Synchronization
- Creates JSON task file only
- Updates workflow-session.json stats only  
- No automatic TODO_LIST.md generation
+- Creates JSON task file only with complete implementation field
+- Updates workflow-session.json stats only
+- No automatic TODO_LIST.md generation  
 - No complex cross-referencing needed

 ### View Generation On-Demand
 - Use `/context` to generate views when needed
 - No persistent markdown files created
- All data stored in JSON only
+- All data including implementation stored in JSON only

 ## Simplified Task Management

@@ -160,7 +224,7 @@ Based on title analysis:

 Suggestions:
 - Related task: impl-1 (Build authentication module)
- Suggested agent: test-agent
+- Suggested agent: code-review-test-agent
 - Estimated effort: 2h
 - Dependencies: [impl-1]
 - Suggested hierarchy: impl-1.3 (as subtask of impl-1)
--- a/.claude/commands/task/execute.md
+++ b/.claude/commands/task/execute.md
@@ -46,7 +46,7 @@ FUNCTION select_agent(task, agent_override):
            WHEN CONTAINS "Design schema", "Plan":
                RETURN "planning-agent"
            WHEN CONTAINS "Write tests":
-                RETURN "test-agent"
+                RETURN "code-review-test-agent"
            WHEN CONTAINS "Review code":
                RETURN "review-agent"
            DEFAULT:
@@ -154,6 +154,47 @@ This is the simplified data structure loaded to provide context for task executi
      "parent": null,
      "subtasks": ["impl-1.1", "impl-1.2"],
      "dependencies": ["impl-0"]
+    },
+    "implementation": {
+      "files": [
+        {
+          "path": "src/auth/login.ts",
+          "location": {
+            "function": "authenticateUser",
+            "lines": "25-65",
+            "description": "Main authentication logic"
+          },
+          "original_code": "// Code snippet extracted via gemini analysis",
+          "modifications": {
+            "current_state": "Basic password authentication only",
+            "proposed_changes": [
+              "Add JWT token generation",
+              "Implement OAuth2 callback handling",
+              "Add multi-factor authentication support"
+            ],
+            "logic_flow": [
+              "validateCredentials() ───► checkUserExists()",
+              "◊─── if password ───► generateJWT() ───► return token",
+              "◊─── if OAuth ───► validateOAuthCode() ───► exchangeForToken()",
+              "◊─── if MFA ───► sendMFACode() ───► awaitVerification()"
+            ],
+            "reason": "Support modern authentication standards and security requirements",
+            "expected_outcome": "Comprehensive authentication system supporting multiple methods"
+          }
+        }
+      ],
+      "context_notes": {
+        "dependencies": ["jsonwebtoken", "passport", "speakeasy"],
+        "affected_modules": ["user-session", "auth-middleware", "api-routes"],
+        "risks": [
+          "Breaking changes to existing login endpoints",
+          "Token storage and rotation complexity",
+          "OAuth provider configuration dependencies"
+        ],
+        "performance_considerations": "JWT validation adds ~10ms per request, OAuth callbacks may timeout",
+        "error_handling": "Ensure sensitive authentication errors don't leak user enumeration data"
+      },
+      "analysis_source": "gemini"
    }
  },
  "workflow": {
@@ -170,11 +211,31 @@ This is the simplified data structure loaded to provide context for task executi

 ### 🎯 **Agent-Specific Context**

-Different agents receive context tailored to their function:
-   **`code-developer`**: Code patterns, dependencies, file scopes.
-   **`planning-agent`**: High-level requirements, constraints, success criteria.
-   **`test-agent`**: Test requirements, code to be tested, coverage goals.
-   **`review-agent`**: Quality standards, style guides, review criteria.
+Different agents receive context tailored to their function, including implementation details:
+
+**`code-developer`**: 
+- Complete implementation.files array with file paths and locations
+- original_code snippets and proposed_changes for precise modifications
+- logic_flow diagrams for understanding data flow
+- Dependencies and affected modules for integration planning
+- Performance and error handling considerations
+
+**`planning-agent`**: 
+- High-level requirements, constraints, success criteria
+- Implementation risks and mitigation strategies
+- Architecture implications from implementation.context_notes
+
+**`code-review-test-agent`**: 
+- Files to test from implementation.files[].path
+- Logic flows to validate from implementation.modifications.logic_flow
+- Error conditions to test from implementation.context_notes.error_handling
+- Performance benchmarks from implementation.context_notes.performance_considerations
+
+**`review-agent`**: 
+- Code quality standards and implementation patterns
+- Security considerations from implementation.context_notes.risks
+- Dependency validation from implementation.context_notes.dependencies
+- Architecture compliance checks

 ### 🗃️ **Simplified File Output**

--- a/.claude/commands/task/replan.md
+++ b/.claude/commands/task/replan.md
@@ -65,6 +65,7 @@ This command operates on **individual tasks only**. For workflow-wide changes, u
 4. **Dependencies**: Update task relationships?
 5. **Success Criteria**: Modify completion conditions?
 6. **Agent Assignment**: Change assigned agent?
+7. **Implementation Details**: Update file paths, code locations, and logic flows?

 ### Interactive Mode
 ```bash
@@ -154,6 +155,44 @@ Each replan creates a new version with complete history:
    "requirements": ["Basic auth", "Session mgmt", "OAuth2 support"],
    "scope": ["src/auth/*", "tests/auth/*"],
    "acceptance": ["All auth methods work"]
+  },
+  "implementation": {
+    "files": [
+      {
+        "path": "src/auth/oauth.ts",
+        "location": {
+          "function": "handleOAuthCallback",
+          "lines": "45-80",
+          "description": "OAuth callback handler (added in replan)"
+        },
+        "original_code": "// New file - requires creation",
+        "modifications": {
+          "current_state": "File does not exist",
+          "proposed_changes": [
+            "Create OAuth2 callback handler",
+            "Integrate with existing auth system"
+          ],
+          "logic_flow": [
+            "receiveCallback() ───► validateAuthCode()",
+            "◊─── if valid ───► exchangeForToken() ───► storeUserSession()",
+            "◊─── if invalid ───► logError() ───► redirectToLogin()"
+          ],
+          "reason": "Support external authentication providers",
+          "expected_outcome": "Seamless OAuth2 integration"
+        }
+      }
+    ],
+    "context_notes": {
+      "dependencies": ["passport-oauth2", "express-session"],
+      "affected_modules": ["auth-middleware", "user-session"],
+      "risks": [
+        "OAuth provider configuration complexity",
+        "Session management conflicts with existing auth"
+      ],
+      "performance_considerations": "External API calls may add 200-500ms latency",
+      "error_handling": "Graceful fallback to standard login on OAuth failure"
+    },
+    "analysis_source": "manual"
  }
 }
 ```
@@ -170,6 +209,48 @@ Each replan creates a new version with complete history:
    └── replan-impl-1-20250908.md  # Change log
 ```

+## Implementation Field Updates
+
+### Implementation Change Detection
+When replanning, the system analyzes changes to the implementation field:
+
+**Implementation Changes Tracked**:
+- New files added to implementation.files array
+- Modified file paths or locations
+- Updated original_code snippets (via gemini re-analysis if needed)
+- Changed logic flows and data flow diagrams
+- Modified dependencies and risk assessments
+- Updated performance considerations and error handling
+
+**Gemini Re-analysis Triggers**:
+- New file paths that need code extraction
+- Changed function locations requiring updated code snippets
+- Modified scope requiring dependency re-evaluation
+- When analysis_source was "gemini" and major changes occur
+
+**Example Implementation Update**:
+```json
+"implementation": {
+  "files": [
+    {
+      "path": "src/auth/oauth.ts", // NEW FILE ADDED
+      "original_code": "// New file - requires creation",
+      "modifications": {
+        "logic_flow": [
+          "// NEW FLOW ADDED FOR OAUTH"
+        ]
+      }
+    }
+  ],
+  "context_notes": {
+    "dependencies": ["passport-oauth2"], // NEW DEPENDENCY
+    "risks": [
+      "OAuth provider configuration complexity" // NEW RISK
+    ]
+  }
+}
+```
+
 ## IMPL_PLAN.md Updates

 ### Automatic Plan Regeneration
--- a/.claude/commands/workflow/execute.md
+++ b/.claude/commands/workflow/execute.md
@@ -74,6 +74,43 @@ For each executable task:
      "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"
+      },
+      "analysis_source": "auto-detected"
    }
  },
  "workflow": {
@@ -87,17 +124,33 @@ For each executable task:
 ```

 **Context Assignment Rules:**
- **Complete Context**: Use full task JSON context for agent execution
+- **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
 - **Workflow Integration**: Include session state and IMPL_PLAN.md context
- **Scope Focus**: Direct agents to specific files from task.context.scope
- **Gemini Flags**: Automatically add [GEMINI_CLI_REQUIRED] for multi-file tasks
+- **Scope Focus**: Direct agents to specific files from implementation.files[].path
+- **Gemini Flags**: Auto-add [GEMINI_CLI_REQUIRED] when analysis_source is "gemini"

 ### 4. Agent Execution & Progress Tracking

 ```bash
 Task(subagent_type="code-developer",
-     prompt="[GEMINI_CLI_REQUIRED] Implement authentication logic based on schema",
-     description="Execute impl-1.2 with full workflow context and status tracking")
+     prompt="[GEMINI_CLI_REQUIRED] Implement authentication logic based on schema
+     
+     Task Context: impl-1.2 - Implement auth logic
+     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
+     
+     Use implementation details above for precise, targeted development.",
+     description="Execute impl-1.2 with full workflow context and implementation details")
 ```

 **Execution Protocol:**
@@ -141,8 +194,8 @@ Based on discovered task data:
 - **task.agent field**: Use specified agent from task JSON
 - **task.type analysis**: 
  - "feature" → code-developer
-  - "test" → test-agent  
-  - "docs" → docs-agent
+  - "test" → code-review-test-agent  
+  - "docs" → code-developer
  - "review" → code-review-agent
 - **Gemini context**: Auto-assign based on task.context.scope and requirements

--- a/.claude/commands/workflow/plan.md
+++ b/.claude/commands/workflow/plan.md
@@ -80,6 +80,29 @@ The command automatically detects input type:
 - Generates hierarchical task structure (max 3 levels)
 - Updates session state with task references

+### Implementation Field Requirements
+⚠️ **CRITICAL**: All generated tasks must include detailed implementation guidance
+
+**Auto-fill Strategy**:
+1. **Sufficient Information**: Auto-fill implementation field based on user input and project context
+2. **Insufficient Information**: Mark analysis_source as "gemini" and prompt:
+   ```
+   ⚠️ Implementation details incomplete, recommend using gemini analysis:
+   gemini --all-files -p "@{relevant-file-patterns} @{CLAUDE.md} 
+   Analyze task: [task description]
+   Extract: 1) File locations and code snippets 2) Modification logic and data flow 3) Risks and dependencies"
+   ```
+
+**Required Implementation Sub-fields**:
+- **files**: Must contain at least 1 file with detailed info (path, location, original_code, modifications)
+- **context_notes**: Dependencies, risks, performance considerations
+- **analysis_source**: manual|gemini|auto-detected
+
+**Quality Standards**:
+- logic_flow must use specified symbols (───►, ◊───, ◄───)
+- Each file must have specific location (function name or line range)
+- risks array cannot be empty, must contain at least 1 risk assessment
+
 ## Session Check Process
 ⚠️ **CRITICAL**: Check for existing active session before planning