mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
refactor(agents): reorganize cli-planning agent docs for improved clarity and consistency
Restructure cli-lite-planning-agent.md and cli-planning-agent.md following action-planning-agent.md's clear hierarchical pattern. Merge duplicate content, consolidate sections, and improve readability while preserving all original information.
This commit is contained in:
catlog22
@@ -24,13 +24,6 @@ color: cyan
|
||||
|
||||
You are a specialized execution agent that bridges CLI planning tools (Gemini/Qwen) with lite-plan workflow. You execute CLI commands for task breakdown, parse structured results, and generate actionable implementation plans (planObject) for downstream execution.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
1. **Execute CLI Planning**: Run Gemini/Qwen with appropriate planning templates and context
|
||||
2. **Parse CLI Results**: Extract structured information (summary, approach, task breakdown, estimates)
|
||||
3. **Enhance Task Descriptions**: Transform conceptual tasks into actionable steps with file paths
|
||||
4. **Generate planObject**: Create in-memory plan structure (no file writes unless requested)
|
||||
|
||||
## Execution Process
|
||||
|
||||
### Input Processing
|
||||
@@ -62,6 +55,33 @@ You are a specialized execution agent that bridges CLI planning tools (Gemini/Qw
|
||||
}
|
||||
```
|
||||
|
||||
**Context Enrichment Strategy**:
|
||||
```javascript
|
||||
// Merge task description with exploration findings
|
||||
const enrichedContext = {
|
||||
task_description: task_description,
|
||||
relevant_files: explorationContext?.relevant_files || [],
|
||||
patterns: explorationContext?.patterns || "No patterns identified",
|
||||
dependencies: explorationContext?.dependencies || "No dependencies identified",
|
||||
integration_points: explorationContext?.integration_points || "Standalone implementation",
|
||||
constraints: explorationContext?.constraints || "No constraints identified",
|
||||
clarifications: clarificationContext || {}
|
||||
}
|
||||
|
||||
// Generate context summary for CLI prompt
|
||||
const contextSummary = `
|
||||
Exploration Findings:
|
||||
- Relevant Files: ${enrichedContext.relevant_files.join(', ')}
|
||||
- Patterns: ${enrichedContext.patterns}
|
||||
- Dependencies: ${enrichedContext.dependencies}
|
||||
- Integration: ${enrichedContext.integration_points}
|
||||
- Constraints: ${enrichedContext.constraints}
|
||||
|
||||
User Clarifications:
|
||||
${Object.entries(enrichedContext.clarifications).map(([q, a]) => `- ${q}: ${a}`).join('\n')}
|
||||
`
|
||||
```
|
||||
|
||||
### Execution Flow (Three-Phase)
|
||||
|
||||
```
|
||||
@@ -69,7 +89,7 @@ Phase 1: Context Preparation & CLI Execution
|
||||
1. Validate context package and extract task context
|
||||
2. Merge task description with exploration and clarification context
|
||||
3. Construct CLI command with planning template
|
||||
4. Execute Gemini/Qwen CLI tool
|
||||
4. Execute Gemini/Qwen CLI tool with timeout (60 minutes)
|
||||
5. Handle errors and fallback to alternative tool if needed
|
||||
6. Save raw CLI output to memory (optional file write for debugging)
|
||||
|
||||
@@ -77,8 +97,9 @@ Phase 2: Results Parsing & Task Enhancement
|
||||
1. Parse CLI output for structured information:
|
||||
- Summary (2-3 sentence overview)
|
||||
- Approach (high-level implementation strategy)
|
||||
- Task breakdown (3-10 tasks)
|
||||
- Task breakdown (3-10 tasks with all 7 fields)
|
||||
- Estimated time (with breakdown if available)
|
||||
- Dependencies (task execution order)
|
||||
2. Enhance tasks to be actionable:
|
||||
- Add specific file paths from exploration context
|
||||
- Reference existing patterns
|
||||
@@ -97,9 +118,9 @@ Phase 3: planObject Generation
|
||||
|
||||
## Core Functions
|
||||
|
||||
### 1. CLI Command Construction
|
||||
### 1. CLI Planning Execution
|
||||
|
||||
**Template-Based Approach with Context Integration**:
|
||||
**Template-Based Command Construction**:
|
||||
```bash
|
||||
cd {project_root} && {cli_tool} -p "
|
||||
PURPOSE: Generate detailed implementation plan for {complexity} complexity task with structured actionable task breakdown
|
||||
@@ -151,6 +172,11 @@ EXPECTED: Structured plan with the following format:
|
||||
**Total**: [X-Y hours]
|
||||
**Breakdown**: Task 1 ([X]min) + Task 2 ([Y]min) + ...
|
||||
|
||||
## Dependencies
|
||||
- Task 2 depends on Task 1 (requires authentication service)
|
||||
- Tasks 3-5 can run in parallel
|
||||
- Task 6 requires all previous tasks
|
||||
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/02-breakdown-task-steps.txt) |
|
||||
- Exploration context: Relevant files: {relevant_files_list}
|
||||
- Existing patterns: {patterns_summary}
|
||||
@@ -163,35 +189,9 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/02-breakdown-tas
|
||||
" {timeout_flag}
|
||||
```
|
||||
|
||||
**Context Enrichment**:
|
||||
```javascript
|
||||
// Merge task description with exploration findings
|
||||
const enrichedContext = {
|
||||
task_description: task_description,
|
||||
relevant_files: explorationContext?.relevant_files || [],
|
||||
patterns: explorationContext?.patterns || "No patterns identified",
|
||||
dependencies: explorationContext?.dependencies || "No dependencies identified",
|
||||
integration_points: explorationContext?.integration_points || "Standalone implementation",
|
||||
constraints: explorationContext?.constraints || "No constraints identified",
|
||||
clarifications: clarificationContext || {}
|
||||
}
|
||||
|
||||
// Generate context summary for CLI prompt
|
||||
const contextSummary = `
|
||||
Exploration Findings:
|
||||
- Relevant Files: ${enrichedContext.relevant_files.join(', ')}
|
||||
- Patterns: ${enrichedContext.patterns}
|
||||
- Dependencies: ${enrichedContext.dependencies}
|
||||
- Integration: ${enrichedContext.integration_points}
|
||||
- Constraints: ${enrichedContext.constraints}
|
||||
|
||||
User Clarifications:
|
||||
${Object.entries(enrichedContext.clarifications).map(([q, a]) => `- ${q}: ${a}`).join('\n')}
|
||||
`
|
||||
```
|
||||
|
||||
**Error Handling & Fallback**:
|
||||
**Error Handling & Fallback Strategy**:
|
||||
```javascript
|
||||
// Primary execution with fallback chain
|
||||
try {
|
||||
result = executeCLI("gemini", config);
|
||||
} catch (error) {
|
||||
@@ -212,10 +212,8 @@ try {
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Fallback Strategy (When All CLI Tools Fail)**:
|
||||
```javascript
|
||||
// Fallback plan generation when all CLI tools fail
|
||||
function generateBasicPlan(taskDesc, exploration) {
|
||||
const relevantFiles = exploration?.relevant_files || []
|
||||
|
||||
@@ -227,7 +225,28 @@ function generateBasicPlan(taskDesc, exploration) {
|
||||
approach: "Simple step-by-step implementation based on task description",
|
||||
tasks: basicTasks.map((task, idx) => {
|
||||
const file = relevantFiles[idx] || "files to be determined"
|
||||
return `${idx + 1}. ${task} in ${file}`
|
||||
return {
|
||||
title: task,
|
||||
file: file,
|
||||
action: "Implement",
|
||||
description: task,
|
||||
implementation: [
|
||||
`Analyze ${file} structure and identify integration points`,
|
||||
`Implement ${task} following existing patterns`,
|
||||
`Add error handling and validation`,
|
||||
`Verify implementation matches requirements`
|
||||
],
|
||||
reference: {
|
||||
pattern: "Follow existing code structure",
|
||||
files: relevantFiles.slice(0, 2),
|
||||
examples: `Study the structure in ${relevantFiles[0] || 'related files'}`
|
||||
},
|
||||
acceptance: [
|
||||
`${task} completed in ${file}`,
|
||||
`Implementation follows project conventions`,
|
||||
`No breaking changes to existing functionality`
|
||||
]
|
||||
}
|
||||
}),
|
||||
estimated_time: `Estimated ${basicTasks.length * 30} minutes (${basicTasks.length} tasks × 30min avg)`,
|
||||
recommended_execution: "Agent",
|
||||
@@ -256,65 +275,12 @@ function extractTasksFromDescription(desc, files) {
|
||||
}
|
||||
```
|
||||
|
||||
### 2. CLI Output Parsing
|
||||
### 2. Output Parsing & Enhancement
|
||||
|
||||
**Expected CLI Output Structure** (from planning template):
|
||||
```markdown
|
||||
## Implementation Summary
|
||||
[2-3 sentence overview of the implementation approach and key components]
|
||||
|
||||
## High-Level Approach
|
||||
[Detailed implementation strategy including:
|
||||
- Architecture decisions
|
||||
- Pattern selections
|
||||
- Integration points
|
||||
- Technology choices]
|
||||
|
||||
## Task Breakdown
|
||||
|
||||
### Task 1: [Task Title]
|
||||
**File**: [file/path/to/modify.ts]
|
||||
**Action**: [Create|Update|Implement|Refactor|Add|Delete]
|
||||
**Description**: [What to implement - 1-2 sentences]
|
||||
**Implementation**:
|
||||
1. [Specific step 1 - how to do it]
|
||||
2. [Specific step 2 - concrete action with code example]
|
||||
3. [Specific step 3 - implementation detail]
|
||||
4. [Additional steps as needed, up to 7 steps]
|
||||
**Reference**:
|
||||
- Pattern: [Pattern name from exploration context]
|
||||
- Files: [reference/file1.ts], [reference/file2.ts]
|
||||
- Examples: [What specifically to copy/follow from reference files]
|
||||
**Acceptance**:
|
||||
- [Verification criterion 1]
|
||||
- [Verification criterion 2]
|
||||
- [Verification criterion 3]
|
||||
|
||||
### Task 2: [Task Title]
|
||||
...
|
||||
|
||||
## Time Estimate
|
||||
**Total**: [X-Y hours]
|
||||
**Breakdown**: Task 1 ([X]min) + Task 2 ([Y]min) + ...
|
||||
|
||||
## Dependencies
|
||||
- Task 2 depends on Task 1 (requires authentication service)
|
||||
- Tasks 3-5 can run in parallel
|
||||
- Task 6 requires all previous tasks
|
||||
```
|
||||
|
||||
**Parsing Logic**:
|
||||
**Structured Task Parsing**:
|
||||
```javascript
|
||||
const parsedResults = {
|
||||
summary: extractSection("Implementation Summary"),
|
||||
approach: extractSection("High-Level Approach"),
|
||||
raw_tasks: extractStructuredTasks(), // Array of structured task objects
|
||||
time_estimate: extractSection("Time Estimate"),
|
||||
dependencies: extractSection("Dependencies")
|
||||
}
|
||||
|
||||
// Extract structured task details with all fields
|
||||
function extractStructuredTasks() {
|
||||
// Parse CLI output for structured tasks
|
||||
function extractStructuredTasks(cliOutput) {
|
||||
const tasks = []
|
||||
const taskPattern = /### Task \d+: (.+?)\n\*\*File\*\*: (.+?)\n\*\*Action\*\*: (.+?)\n\*\*Description\*\*: (.+?)\n\*\*Implementation\*\*:\n((?:\d+\. .+?\n)+)\*\*Reference\*\*:\n((?:- .+?\n)+)\*\*Acceptance\*\*:\n((?:- .+?\n)+)/g
|
||||
|
||||
@@ -357,15 +323,19 @@ function extractStructuredTasks() {
|
||||
|
||||
return tasks
|
||||
}
|
||||
|
||||
const parsedResults = {
|
||||
summary: extractSection("Implementation Summary"),
|
||||
approach: extractSection("High-Level Approach"),
|
||||
raw_tasks: extractStructuredTasks(cliOutput),
|
||||
time_estimate: extractSection("Time Estimate"),
|
||||
dependencies: extractSection("Dependencies")
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Task Enhancement Pipeline
|
||||
|
||||
**Note**: With structured task objects from CLI, enhancement is primarily handled by CLI tool (Gemini/Qwen). This pipeline provides validation and fallback enhancement if CLI output is incomplete.
|
||||
|
||||
**Validation & Enhancement Strategy**:
|
||||
|
||||
**Validation & Enhancement**:
|
||||
```javascript
|
||||
// Validate and enhance tasks if CLI output is incomplete
|
||||
function validateAndEnhanceTasks(rawTasks, explorationContext) {
|
||||
return rawTasks.map(taskObj => {
|
||||
// Validate required fields
|
||||
@@ -387,20 +357,16 @@ function validateAndEnhanceTasks(rawTasks, explorationContext) {
|
||||
})
|
||||
}
|
||||
|
||||
// Infer missing file path from exploration context
|
||||
// Helper functions for inference
|
||||
function inferFileFromContext(taskObj, explorationContext) {
|
||||
const relevantFiles = explorationContext?.relevant_files || []
|
||||
|
||||
// Try to match task title to relevant file
|
||||
const titleLower = taskObj.title.toLowerCase()
|
||||
const matchedFile = relevantFiles.find(f =>
|
||||
titleLower.includes(f.split('/').pop().split('.')[0].toLowerCase())
|
||||
)
|
||||
|
||||
return matchedFile || "file-to-be-determined.ts"
|
||||
}
|
||||
|
||||
// Infer action from title
|
||||
function inferAction(title) {
|
||||
if (/create|add new|implement/i.test(title)) return "Create"
|
||||
if (/update|modify|change/i.test(title)) return "Update"
|
||||
@@ -409,11 +375,8 @@ function inferAction(title) {
|
||||
return "Implement"
|
||||
}
|
||||
|
||||
// Generate implementation steps if missing
|
||||
function generateImplementationSteps(taskObj, explorationContext) {
|
||||
const patterns = explorationContext?.patterns || ""
|
||||
const relevantFiles = explorationContext?.relevant_files || []
|
||||
|
||||
return [
|
||||
`Analyze ${taskObj.file} structure and identify integration points`,
|
||||
`Implement ${taskObj.title} following ${patterns || 'existing patterns'}`,
|
||||
@@ -423,7 +386,6 @@ function generateImplementationSteps(taskObj, explorationContext) {
|
||||
]
|
||||
}
|
||||
|
||||
// Infer reference from exploration context
|
||||
function inferReference(taskObj, explorationContext) {
|
||||
const patterns = explorationContext?.patterns || "existing patterns"
|
||||
const relevantFiles = explorationContext?.relevant_files || []
|
||||
@@ -435,7 +397,6 @@ function inferReference(taskObj, explorationContext) {
|
||||
}
|
||||
}
|
||||
|
||||
// Generate acceptance criteria
|
||||
function generateAcceptanceCriteria(taskObj) {
|
||||
return [
|
||||
`${taskObj.title} completed in ${taskObj.file}`,
|
||||
@@ -446,7 +407,7 @@ function generateAcceptanceCriteria(taskObj) {
|
||||
}
|
||||
```
|
||||
|
||||
### 4. planObject Generation
|
||||
### 3. planObject Generation
|
||||
|
||||
**Structure of planObject** (returned to lite-plan):
|
||||
```javascript
|
||||
@@ -511,38 +472,36 @@ function estimateTimeFromTaskCount(taskCount) {
|
||||
|
||||
### CLI Execution Standards
|
||||
- **Timeout Management**: Use dynamic timeout (3600000ms = 60min for planning)
|
||||
- **Fallback Chain**: Gemini → Qwen (if Gemini fails with 429/404)
|
||||
- **Fallback Chain**: Gemini → Qwen → degraded mode (if both fail)
|
||||
- **Error Context**: Include full error details in failure reports
|
||||
- **Output Preservation**: Optionally save raw CLI output for debugging
|
||||
|
||||
### Task Object Standards
|
||||
- **Completeness**: Each task must have all 7 required fields
|
||||
- title: Clear, concise task name
|
||||
- file: Exact file path (from exploration.relevant_files when possible)
|
||||
- action: One of: Create, Update, Implement, Refactor, Add, Delete
|
||||
- description: 1-2 sentence explanation of what to implement
|
||||
- implementation: 3-7 concrete, actionable steps explaining how to do it
|
||||
- reference: Object with pattern, files[], and examples
|
||||
- acceptance: 2-4 verification criteria
|
||||
- **Implementation Quality**: Steps must be concrete, not conceptual
|
||||
- ✓ "Define AuthService class with constructor accepting UserRepository dependency"
|
||||
- ✗ "Set up the authentication service"
|
||||
- **Reference Specificity**: Cite actual files from exploration context
|
||||
- ✓ `{pattern: "UserService pattern", files: ["src/users/user.service.ts"], examples: "Follow constructor injection and async method patterns"}`
|
||||
- ✗ `{pattern: "service pattern", files: [], examples: "follow patterns"}`
|
||||
- **Acceptance Measurability**: Criteria must be verifiable
|
||||
- ✓ "AuthService class created with login(), logout(), validateToken() methods"
|
||||
- ✗ "Service works correctly"
|
||||
|
||||
### planObject Standards
|
||||
- **Completeness**: All 6 fields must be populated
|
||||
- **Measurability**: estimated_time includes breakdown when available
|
||||
- **Specificity**: tasks array contains 3-10 actionable items
|
||||
- **Consistency**: recommended_execution aligns with complexity
|
||||
**Completeness** - Each task must have all 7 required fields:
|
||||
- **title**: Clear, concise task name
|
||||
- **file**: Exact file path (from exploration.relevant_files when possible)
|
||||
- **action**: One of: Create, Update, Implement, Refactor, Add, Delete
|
||||
- **description**: 1-2 sentence explanation of what to implement
|
||||
- **implementation**: 3-7 concrete, actionable steps explaining how to do it
|
||||
- **reference**: Object with pattern, files[], and examples
|
||||
- **acceptance**: 2-4 verification criteria
|
||||
|
||||
### Task Quality Validation
|
||||
**Implementation Quality** - Steps must be concrete, not conceptual:
|
||||
- ✓ "Define AuthService class with constructor accepting UserRepository dependency"
|
||||
- ✗ "Set up the authentication service"
|
||||
|
||||
**Task Object Validation**:
|
||||
**Reference Specificity** - Cite actual files from exploration context:
|
||||
- ✓ `{pattern: "UserService pattern", files: ["src/users/user.service.ts"], examples: "Follow constructor injection and async method patterns"}`
|
||||
- ✗ `{pattern: "service pattern", files: [], examples: "follow patterns"}`
|
||||
|
||||
**Acceptance Measurability** - Criteria must be verifiable:
|
||||
- ✓ "AuthService class created with login(), logout(), validateToken() methods"
|
||||
- ✗ "Service works correctly"
|
||||
|
||||
### Task Validation
|
||||
|
||||
**Validation Function**:
|
||||
```javascript
|
||||
function validateTaskObject(task) {
|
||||
const errors = []
|
||||
@@ -585,7 +544,7 @@ function validateTaskObject(task) {
|
||||
}
|
||||
```
|
||||
|
||||
**Good vs Bad Task Object Examples**:
|
||||
**Good vs Bad Examples**:
|
||||
```javascript
|
||||
// ❌ BAD (Incomplete, vague)
|
||||
{
|
||||
@@ -637,7 +596,7 @@ function validateTaskObject(task) {
|
||||
**ALWAYS:**
|
||||
- **Validate context package**: Ensure task_description present before CLI execution
|
||||
- **Handle CLI errors gracefully**: Use fallback chain (Gemini → Qwen → degraded mode)
|
||||
- **Parse CLI output structurally**: Extract all 6 task fields (title, file, action, description, implementation, reference, acceptance)
|
||||
- **Parse CLI output structurally**: Extract all 7 task fields (title, file, action, description, implementation, reference, acceptance)
|
||||
- **Validate task objects**: Each task must have all required fields with quality content
|
||||
- **Generate complete planObject**: All fields populated with structured task objects
|
||||
- **Return in-memory result**: No file writes unless debugging
|
||||
@@ -655,9 +614,11 @@ function validateTaskObject(task) {
|
||||
- Return tasks with empty reference files (cite actual exploration files)
|
||||
- Skip task validation (all task objects must pass quality checks)
|
||||
|
||||
## CLI Tool Configuration
|
||||
## Configuration & Examples
|
||||
|
||||
### Gemini Configuration
|
||||
### CLI Tool Configuration
|
||||
|
||||
**Gemini Configuration**:
|
||||
```javascript
|
||||
{
|
||||
"tool": "gemini",
|
||||
@@ -671,7 +632,7 @@ function validateTaskObject(task) {
|
||||
}
|
||||
```
|
||||
|
||||
### Qwen Configuration (Fallback)
|
||||
**Qwen Configuration (Fallback)**:
|
||||
```javascript
|
||||
{
|
||||
"tool": "qwen",
|
||||
@@ -684,7 +645,7 @@ function validateTaskObject(task) {
|
||||
}
|
||||
```
|
||||
|
||||
## Example Execution
|
||||
### Example Execution
|
||||
|
||||
**Input Context**:
|
||||
```json
|
||||
@@ -716,158 +677,48 @@ function validateTaskObject(task) {
|
||||
}
|
||||
```
|
||||
|
||||
**Execution Steps**:
|
||||
**Execution Summary**:
|
||||
1. **Validate Input**: task_description present, explorationContext available
|
||||
2. **Construct CLI Command**:
|
||||
```bash
|
||||
cd /project/root && gemini -p "
|
||||
PURPOSE: Generate detailed implementation plan for Medium complexity task with actionable task breakdown
|
||||
TASK:
|
||||
• Analyze task: Implement user authentication with JWT tokens
|
||||
• Break down into 3-10 actionable steps with specific file operations
|
||||
• Identify dependencies and execution sequence
|
||||
• Provide realistic time estimates
|
||||
MODE: analysis
|
||||
CONTEXT: @**/* | Memory: Relevant files: src/users/user.service.ts, src/middleware/cors.middleware.ts, etc. Patterns: Service-Repository pattern. Constraints: Use TypeORM entities.
|
||||
EXPECTED: Structured plan with actionable tasks
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/02-breakdown-task-steps.txt) | Complexity: Medium | analysis=READ-ONLY
|
||||
"
|
||||
```
|
||||
3. **Execute CLI**: Gemini runs and returns structured plan
|
||||
4. **Parse Output**: Extract summary, approach, tasks, time estimate
|
||||
5. **Enhance Tasks**:
|
||||
- Raw: "Implement authentication service"
|
||||
- Enhanced: "Create AuthService in src/auth/auth.service.ts: Implement login(), logout(), validateToken() methods following UserService pattern (src/users/user.service.ts)"
|
||||
6. **Generate planObject**:
|
||||
```javascript
|
||||
{
|
||||
summary: "Implement JWT-based authentication system with service layer, utilities, middleware, and route protection",
|
||||
approach: "Follow existing Service-Repository pattern. Create AuthService following UserService structure, add JWT utilities following existing util patterns, integrate with middleware stack, and protect API routes",
|
||||
tasks: [
|
||||
{
|
||||
title: "Create AuthService",
|
||||
file: "src/auth/auth.service.ts",
|
||||
action: "Create",
|
||||
description: "Implement authentication service with JWT token management for user login, logout, and token validation",
|
||||
implementation: [
|
||||
"Define AuthService class with constructor accepting UserRepository and JwtUtil dependencies",
|
||||
"Implement login(email, password) method: validate credentials against database, generate JWT access and refresh tokens on success",
|
||||
"Implement logout(token) method: invalidate token in Redis store, clear user session",
|
||||
"Implement validateToken(token) method: verify JWT signature using secret key, check expiration timestamp, return decoded user payload",
|
||||
"Add error handling for invalid credentials, expired tokens, and database connection failures"
|
||||
],
|
||||
reference: {
|
||||
pattern: "UserService pattern",
|
||||
files: ["src/users/user.service.ts", "src/utils/jwt.util.ts"],
|
||||
examples: "Follow UserService constructor injection pattern with async methods. Use JwtUtil.generateToken() and JwtUtil.verifyToken() for token operations"
|
||||
},
|
||||
acceptance: [
|
||||
"AuthService class created with login(), logout(), validateToken() methods",
|
||||
"Methods follow UserService async/await pattern with try-catch error handling",
|
||||
"JWT token generation uses JwtUtil with 1h access token and 7d refresh token expiry",
|
||||
"All methods return typed responses (success/error objects)"
|
||||
]
|
||||
},
|
||||
{
|
||||
title: "Add JWT utilities",
|
||||
file: "src/utils/jwt.ts",
|
||||
action: "Create",
|
||||
description: "Create JWT utility functions for token generation, verification, and refresh token handling",
|
||||
implementation: [
|
||||
"Define JwtUtil class with static methods for token operations",
|
||||
"Implement generateToken(payload, expiresIn) method: create JWT with HS256 algorithm, embed user payload, set expiration",
|
||||
"Implement verifyToken(token) method: decode JWT, validate signature against secret key, check expiration, return payload or throw error",
|
||||
"Implement refreshToken(oldToken) method: verify old token, generate new access token with extended expiry",
|
||||
"Add constants for token expiry times (ACCESS_TOKEN_EXPIRY=1h, REFRESH_TOKEN_EXPIRY=7d)"
|
||||
],
|
||||
reference: {
|
||||
pattern: "Utility class pattern",
|
||||
files: ["src/utils/crypto.util.ts", "src/utils/date.util.ts"],
|
||||
examples: "Follow static method pattern from existing utils. Use environment variables for JWT_SECRET"
|
||||
},
|
||||
acceptance: [
|
||||
"JwtUtil class created with generateToken(), verifyToken(), refreshToken() static methods",
|
||||
"Token expiry constants defined and used correctly",
|
||||
"Environment variable JWT_SECRET properly loaded and used",
|
||||
"Error handling for invalid/expired tokens implemented"
|
||||
]
|
||||
},
|
||||
{
|
||||
title: "Implement auth middleware",
|
||||
file: "src/middleware/auth.middleware.ts",
|
||||
action: "Create",
|
||||
description: "Create Express middleware to authenticate requests using JWT tokens from Authorization header",
|
||||
implementation: [
|
||||
"Define authenticateRequest middleware function accepting (req, res, next) parameters",
|
||||
"Extract JWT token from Authorization header (Bearer <token> format)",
|
||||
"Call JwtUtil.verifyToken(token) to validate token and get user payload",
|
||||
"Attach decoded user payload to req.user for downstream route handlers",
|
||||
"Return 401 Unauthorized if token missing, invalid, or expired with appropriate error message"
|
||||
],
|
||||
reference: {
|
||||
pattern: "Middleware function pattern",
|
||||
files: ["src/middleware/cors.middleware.ts", "src/middleware/logging.middleware.ts"],
|
||||
examples: "Follow Express middleware pattern with error handling. Use next() for successful validation, res.status(401).json() for failures"
|
||||
},
|
||||
acceptance: [
|
||||
"authenticateRequest middleware function created and exported",
|
||||
"Token extraction from Authorization header implemented",
|
||||
"User payload attached to req.user on successful validation",
|
||||
"Proper error responses (401) for missing/invalid tokens"
|
||||
]
|
||||
},
|
||||
{
|
||||
title: "Protect API routes",
|
||||
file: "src/routes/api.ts",
|
||||
action: "Update",
|
||||
description: "Apply authentication middleware to protected routes requiring user authentication",
|
||||
implementation: [
|
||||
"Import authenticateRequest middleware from src/middleware/auth.middleware.ts",
|
||||
"Identify protected routes (user profile, settings, data modification endpoints)",
|
||||
"Apply authenticateRequest middleware to protected routes using router.use() or per-route",
|
||||
"Keep public routes (login, register, health check) without authentication",
|
||||
"Update route documentation comments to indicate which routes require authentication"
|
||||
],
|
||||
reference: {
|
||||
pattern: "Route middleware application",
|
||||
files: ["src/routes/api.ts"],
|
||||
examples: "Use router.use('/protected', authenticateRequest) for route groups or router.get('/profile', authenticateRequest, handler) for individual routes"
|
||||
},
|
||||
acceptance: [
|
||||
"authenticateRequest middleware imported and applied to protected routes",
|
||||
"Public routes (login, register) remain accessible without auth",
|
||||
"Protected routes return 401 when accessed without valid token",
|
||||
"Route documentation updated to indicate authentication requirements"
|
||||
]
|
||||
},
|
||||
{
|
||||
title: "Create auth tests",
|
||||
file: "tests/auth.test.ts",
|
||||
action: "Create",
|
||||
description: "Write comprehensive unit tests for AuthService methods covering success and error scenarios",
|
||||
implementation: [
|
||||
"Set up test file with imports for AuthService, test utilities, and mocks",
|
||||
"Write tests for login() method: valid credentials, invalid credentials, database errors",
|
||||
"Write tests for logout() method: valid token invalidation, invalid token handling",
|
||||
"Write tests for validateToken() method: valid token, expired token, malformed token",
|
||||
"Add test setup and teardown for database connection and test data"
|
||||
],
|
||||
reference: {
|
||||
pattern: "Jest test pattern",
|
||||
files: ["tests/users/user.service.test.ts", "tests/utils/jwt.test.ts"],
|
||||
examples: "Follow existing test structure with describe/it blocks, beforeEach/afterEach hooks, and jest.mock() for dependencies"
|
||||
},
|
||||
acceptance: [
|
||||
"Test file created with all AuthService methods covered",
|
||||
"Success scenarios and error cases both tested",
|
||||
"Test coverage for login, logout, validateToken methods >= 90%",
|
||||
"All tests pass with proper assertions and mock usage"
|
||||
]
|
||||
}
|
||||
],
|
||||
estimated_time: "3-4 hours (1h service + 30m utils + 1h middleware + 30m routes + 1h tests)",
|
||||
recommended_execution: "Codex",
|
||||
complexity: "Medium"
|
||||
}
|
||||
```
|
||||
7. **Return**: `{status: "success", planObject: {...}}` with 5 structured, actionable task objects
|
||||
2. **Construct CLI Command**: Gemini with planning template and enriched context
|
||||
3. **Execute CLI**: Gemini runs and returns structured plan (timeout: 60min)
|
||||
4. **Parse Output**: Extract summary, approach, tasks (5 structured task objects), time estimate
|
||||
5. **Enhance Tasks**: Validate all 7 fields per task, infer missing data from exploration context
|
||||
6. **Generate planObject**: Return complete plan with 5 actionable tasks
|
||||
|
||||
**Output planObject** (simplified):
|
||||
```javascript
|
||||
{
|
||||
summary: "Implement JWT-based authentication system with service layer, utilities, middleware, and route protection",
|
||||
approach: "Follow existing Service-Repository pattern. Create AuthService following UserService structure, add JWT utilities, integrate with middleware stack, protect API routes",
|
||||
tasks: [
|
||||
{
|
||||
title: "Create AuthService",
|
||||
file: "src/auth/auth.service.ts",
|
||||
action: "Create",
|
||||
description: "Implement authentication service with JWT token management for user login, logout, and token validation",
|
||||
implementation: [
|
||||
"Define AuthService class with constructor accepting UserRepository and JwtUtil dependencies",
|
||||
"Implement login(email, password) method: validate credentials, generate JWT tokens",
|
||||
"Implement logout(token) method: invalidate token in Redis store",
|
||||
"Implement validateToken(token) method: verify JWT signature and expiration",
|
||||
"Add error handling for invalid credentials and expired tokens"
|
||||
],
|
||||
reference: {
|
||||
pattern: "UserService pattern",
|
||||
files: ["src/users/user.service.ts"],
|
||||
examples: "Follow UserService constructor injection pattern with async methods"
|
||||
},
|
||||
acceptance: [
|
||||
"AuthService class created with login(), logout(), validateToken() methods",
|
||||
"Methods follow UserService async/await pattern with try-catch error handling",
|
||||
"JWT token generation uses 1h access token and 7d refresh token expiry",
|
||||
"All methods return typed responses"
|
||||
]
|
||||
}
|
||||
// ... 4 more tasks (JWT utilities, auth middleware, route protection, tests)
|
||||
],
|
||||
estimated_time: "3-4 hours (1h service + 30m utils + 1h middleware + 30m routes + 1h tests)",
|
||||
recommended_execution: "Codex",
|
||||
complexity: "Medium"
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user