Intelligent task initialization with deep codebase exploration, architecture design, and implementation planning.
Orchestrates intelligent task initialization with deep codebase exploration, architecture design, and implementation planning.
/plugin marketplace add rafaelkamimura/claude-tools/plugin install rafaelkamimura-claude-tools@rafaelkamimura/claude-toolsIntelligent task initialization with deep codebase exploration, architecture design, and implementation planning.
Streamline task initialization by:
Before running the full workflow, detect task complexity to adjust phases:
Simple Task Indicators (skip Phases 2 and 4):
Complex Task Indicators (run full 7 phases):
Output detected complexity and workflow path before proceeding.
Goal: Understand the project and the task
Launch Discovery Agent (Background)
Use Task tool with subagent_type="general-purpose" and run_in_background=true:
description: "Discover project context"
prompt: "Analyze this project for task initialization.
Read and summarize these files (continue if any don't exist):
Detect project type by checking for:
Analyze complexity indicators:
Return JSON: { project_type: string, docs_found: string[], technologies: string[], complexity_indicators: string[], suggested_complexity: 'simple' | 'complex', key_patterns: string[], test_framework: string | null }"
Use TodoWrite tool to create initial phase tracking (while agent runs):
- Phase 1: Discovery (in_progress)
- Phase 2: Codebase Exploration (pending)
- Phase 3: Clarifying Questions (pending)
- Phase 4: Architecture Design (pending)
- Phase 5: Plan & Task History (pending)
- Phase 6: Implementation (pending)
- Phase 7: Quality Review (pending)
Use TaskOutput to retrieve discovery results:
Output context summary from agent results:
Use AskUserQuestion tool for input mode:
If user selects "Guided":
Use AskUserQuestion tool:
Output: "Describe the specific task within this category:" WAIT for user's task description.
If user selects "Free-text": Output: "Please describe your task:" WAIT for user's task description.
Goal: Deeply understand relevant existing code and patterns
SKIP this phase if task is detected as SIMPLE
Launch Exploration Agents (Background)
Use Task tool to launch 2 feature-dev:code-explorer agents IN PARALLEL with run_in_background=true:
Task tool call 1:
subagent_type: "feature-dev:code-explorer"
run_in_background: true
description: "Explore similar features"
prompt: "CRITICAL DATABASE INSTRUCTIONS:
Find features similar to [USER'S TASK] and trace their implementation comprehensively. Focus on:
Return a list of 5-10 key files that are essential to understand for this task."
Task tool call 2:
subagent_type: "feature-dev:code-explorer"
run_in_background: true
description: "Explore architecture patterns"
prompt: "CRITICAL DATABASE INSTRUCTIONS:
Map the architecture and abstractions relevant to [USER'S TASK]. Focus on:
Return a list of 5-10 key files that are essential to understand the architecture."
Use TaskOutput to retrieve results from both exploration agents:
Use Read tool to read ALL key files identified by both agents (up to 15 files).
Launch Validation Agent (Background)
Use Task tool with subagent_type="Explore" and run_in_background=true:
description: "Validate exploration completeness"
prompt: "Review these exploration findings for completeness:
[INSERT EXPLORATION RESULTS FROM BOTH AGENTS]
For implementing: [USER'S TASK]
Identify any gaps or missing context. If gaps exist, search for the missing information. Return JSON: { gaps_found: boolean, additional_findings: string[], confidence_level: 'high' | 'medium' | 'low' }"
Present initial exploration findings to user (don't wait for validation):
Use TaskOutput to retrieve validation results:
Update TodoWrite: Mark Phase 2 as completed, Phase 3 as in_progress.
Use AskUserQuestion tool for exploration approval:
If user selects "Need more exploration":
Use AskUserQuestion tool:
Use Task tool with subagent_type="feature-dev:code-explorer":
prompt: "Focus on [SELECTED FOCUS AREA] for task: [USER'S TASK]
Previous findings: [SUMMARY]
Provide additional insights on the selected focus area."
Return to step 6 (present updated findings).
If user selects "Start over": Return to Phase 1 step 6 (task input).
Goal: Resolve all ambiguities before designing
CRITICAL: This phase must NOT be skipped
Review exploration findings and original task description.
Scope Category Questions
Use AskUserQuestion tool:
Quality Category Questions
Use AskUserQuestion tool:
Integration Category Questions (ask only if task involves system integration)
Use AskUserQuestion tool:
Additional Context (if selections suggest complexity)
Based on user selections, identify if any need clarification:
For each clarification needed: Output: "You selected [aspect]. Please provide more details about [specific question]:" WAIT for user's detailed response.
Launch Requirements Analyzer Agent (Background)
Use Task tool with subagent_type="general-purpose" and run_in_background=true:
description: "Analyze requirements for completeness"
prompt: "Analyze these requirements for task: [USER'S TASK]
Scope selections: [SCOPE SELECTIONS] Quality priorities: [QUALITY SELECTIONS] Integration constraints: [INTEGRATION SELECTIONS] Exploration context: [EXPLORATION_RESULTS SUMMARY]
Identify:
Return JSON: { gaps: string[], conflicts: string[], dependencies: string[], risks: string[] }"
Summarize Requirements (don't wait for analyzer)
Output summary of all gathered requirements:
## Requirements Summary
- Scope: [selections]
- Quality priorities: [selections]
- Integration constraints: [selections]
- Additional context: [user responses]
Use TaskOutput to retrieve analyzer results:
Use AskUserQuestion tool for requirements confirmation:
If user selects "Need to modify" or "Add more context": Output: "What needs to be changed or added?" WAIT for user's modification. Return to step 7 (summarize updated requirements).
Update TodoWrite: Mark Phase 3 as completed, Phase 4 as in_progress.
Goal: Design multiple implementation approaches with trade-offs
SKIP this phase if task is detected as SIMPLE
Launch Architecture Agents (Background)
Use Task tool to launch 2-3 feature-dev:code-architect agents IN PARALLEL with run_in_background=true:
Task tool call 1 (Minimal Approach):
subagent_type: "feature-dev:code-architect"
run_in_background: true
description: "Design minimal implementation"
prompt: "CRITICAL DATABASE INSTRUCTIONS:
Design the MINIMAL implementation for: [USER'S TASK]
Context from exploration: [INSERT EXPLORATION FINDINGS]
User answers to questions: [INSERT USER ANSWERS]
Focus on: Smallest change possible, maximum reuse of existing code, fastest path to working solution.
Provide: Patterns found, architecture decision, files to create/modify, build sequence."
Task tool call 2 (Clean Architecture Approach):
subagent_type: "feature-dev:code-architect"
run_in_background: true
description: "Design clean architecture"
prompt: "CRITICAL DATABASE INSTRUCTIONS:
Design a CLEAN ARCHITECTURE implementation for: [USER'S TASK]
Context from exploration: [INSERT EXPLORATION FINDINGS]
User answers to questions: [INSERT USER ANSWERS]
Focus on: Elegant abstractions, maintainability, testability, proper separation of concerns.
Provide: Patterns found, architecture decision, files to create/modify, build sequence."
Task tool call 3 (Pragmatic Balance) - optional for complex tasks:
Use TaskOutput to retrieve results from all architecture agents:
Parallel Refinement - Consolidate AND Quality Review (Background)
Use Task tool to launch 2 agents IN PARALLEL with run_in_background=true:
Task 1 (Consolidation):
subagent_type: "Plan"
run_in_background: true
description: "Consolidate architecture options"
prompt: "Review and consolidate these architecture options for: [USER'S TASK]
Requirements from Phase 3: [INSERT REQUIREMENTS SUMMARY]
Option 1 (Minimal Approach): [INSERT AGENT 1 RESULTS]
Option 2 (Clean Architecture): [INSERT AGENT 2 RESULTS]
Option 3 (Pragmatic Balance) - if provided: [INSERT AGENT 3 RESULTS]
Your task:
Return: recommended_approach, confidence, reasoning, hybrid_elements (optional)"
Task 2 (Pre-Quality Check):
subagent_type: "feature-dev:code-reviewer"
run_in_background: true
description: "Pre-review architecture options"
prompt: "Review these architecture options for quality issues:
Task: [USER'S TASK] Requirements: [REQUIREMENTS SUMMARY]
Option 1 (Minimal): [SUMMARY] Option 2 (Clean Architecture): [SUMMARY] Option 3 (Pragmatic) - if provided: [SUMMARY]
Check ALL options for:
Return: issues_per_option[], common_issues[], suggestions[], overall_quality (excellent/good/needs_work)"
Use TaskOutput to retrieve results from both refinement agents:
Merge Findings
Combine consolidation recommendation with quality findings:
Present refined architecture comparison to user:
## Architecture Analysis (Refined)
### Recommended: [APPROACH NAME]
**Confidence**: [high/medium/low]
**Files to modify/create**: [list]
**Why this approach**: [consolidated reasoning]
### Key Trade-offs Considered
- [trade-off 1]
- [trade-off 2]
### Alternative Approaches Available
- [Brief mention of other options]
### Quality Review Notes
- [Any issues addressed or remaining considerations]
Use AskUserQuestion tool for architecture selection:
If user selects "Custom requirements":
Use AskUserQuestion tool:
Use Task tool with subagent_type="feature-dev:code-architect":
run_in_background: true
description: "Design custom architecture"
prompt: "Design architecture with these priorities: [SELECTED PRIORITIES]
Task: [USER'S TASK] Requirements: [REQUIREMENTS SUMMARY] Exploration context: [EXPLORATION FINDINGS]
Create a custom architecture design that prioritizes the selected aspects."
Use TaskOutput to retrieve custom architecture results.
Update TodoWrite: Mark Phase 4 as completed, Phase 5 as in_progress.
Goal: Create actionable implementation plan and persistent tracking
Launch Plan Generator Agent (Background)
Use Task tool with subagent_type="general-purpose" and run_in_background=true:
description: "Generate implementation plan"
prompt: "Generate complete implementation plan for: [USER'S TASK]
Chosen Architecture: [CHOSEN ARCHITECTURE or 'Direct implementation' for simple tasks] Requirements Summary: [REQUIREMENTS_SUMMARY from Phase 3] Files Identified: [FILES from exploration/architecture phases] Project Context: [DISCOVERY_CONTEXT from Phase 1]
Generate THREE outputs:
Implementation Plan Markdown with sections:
Task History File Content for .claude/task-history/[timestamp]-[slug].md:
TodoWrite Items Array (3-7 items): Each item needs:
Return JSON: { plan_markdown: string, task_history_content: string, task_history_filename: string (format: YYYYMMDD-HHMMSS-slug.md), todo_items: [{content: string, activeForm: string}] }"
While agent generates plan, detect project root and create task history directory:
Use Bash tool:
PROJECT_ROOT=$(pwd); if [ -f "$PROJECT_ROOT/CLAUDE.md" ] || [ -d "$PROJECT_ROOT/.git" ]; then TASK_HISTORY_DIR="$PROJECT_ROOT/.claude/task-history"; else TASK_HISTORY_DIR="$HOME/.claude/task-history"; fi; mkdir -p "$TASK_HISTORY_DIR" && echo "$TASK_HISTORY_DIR"Use TaskOutput to retrieve plan generator results:
Use Bash tool to add task history to gitignore (only if in a git repo):
if [ -f .gitignore ]; then grep -q "^.claude/task-history/" .gitignore 2>/dev/null || echo ".claude/task-history/" >> .gitignore; fiUse Write tool to create task history file from agent output:
[TASK_HISTORY_DIR from step 2]/[task_history_filename from agent]Use TodoWrite tool to create implementation task breakdown from agent output:
Output implementation plan summary (plan_markdown from agent).
Use AskUserQuestion tool for plan approval:
If user selects "Revise plan":
Use AskUserQuestion tool:
Output: "Please describe the specific changes needed:" WAIT for user's revision details. Apply revisions and return to step 7 (output updated plan).
If user selects "Need more details": Expand the implementation plan with more granular steps. Return to step 7 (output expanded plan).
If user selects "Start over": Return to Phase 4 step 1 (architecture design).
Update TodoWrite: Mark Phase 5 as completed, Phase 6 as in_progress.
Goal: Build the feature following approved architecture
DO NOT START WITHOUT USER APPROVAL from Phase 5
Launch Agent Preparation Analyzer (Background)
Use Task tool with subagent_type="general-purpose" and run_in_background=true:
description: "Prepare specialized agent prompts"
prompt: "Analyze this implementation plan and prepare specialized agent contexts:
Implementation Plan: [PLAN_MARKDOWN from Phase 5] Files to Modify: [FILES LIST] Architecture Approach: [CHOSEN_ARCHITECTURE]
For each file in the plan, determine if these specialized agents will be needed:
security-auditor: Needed if file touches:
database-optimizer: Needed if file touches:
test-automator: Needed if:
performance-engineer: Needed if file touches:
For each needed agent, prepare a READY-TO-USE prompt with:
Return JSON: { security_auditor: { needed: boolean, files: string[], prompt: string }, database_optimizer: { needed: boolean, files: string[], prompt: string }, test_automator: { needed: boolean, files: string[], prompt: string }, performance_engineer: { needed: boolean, files: string[], prompt: string }, summary: string (brief overview of which agents are needed and why) }"
Mark first implementation todo item as "in_progress" using TodoWrite.
Use TaskOutput to retrieve prepared agent prompts:
Use Read tool to read all relevant files identified in previous phases.
Implement following the approved plan:
Use prepared specialized agents as needed:
For each agent where PREPARED_PROMPTS.[agent].needed is true:
Database instructions to include when using database-related agents:
CRITICAL DATABASE INSTRUCTIONS:
- For PostgreSQL queries: ALWAYS use mcp__postgres__query tool. NEVER use bash psql commands.
- For MariaDB/MySQL queries: ALWAYS use mysql CLI via Bash tool with environment variables:
mysql -h "$MARIADB_HOST" -P "$MARIADB_PORT" -u "$MARIADB_USER" -p"$MARIADB_PASSWORD" {DATABASE_NAME} -e "YOUR_QUERY"
- Load environment variables first: set -a && source .env && set +a
After each major implementation step:
Update TodoWrite: Mark implementation items as completed, Phase 7 as in_progress.
Goal: Ensure code quality and document accomplishments
Launch Quality Review Agents (Background - Parallel)
Use Task tool to launch 3 feature-dev:code-reviewer agents IN PARALLEL with run_in_background=true:
Task tool call 1 (Simplicity Focus):
subagent_type: "feature-dev:code-reviewer"
run_in_background: true
description: "Review for simplicity"
prompt: "CRITICAL DATABASE INSTRUCTIONS:
Review the implementation for SIMPLICITY, DRY, and ELEGANCE.
Files modified: [LIST OF FILES]
Focus on: Code readability, unnecessary complexity, duplicated logic, elegant solutions. Only report issues with confidence >= 80."
Task tool call 2 (Correctness Focus):
Task tool call 3 (Conventions Focus):
Use TaskOutput to retrieve results from all 3 review agents:
Consolidate findings and identify highest severity issues.
Present findings to user:
## Quality Review Results
### Critical Issues (Must Fix)
- [issue with file:line]
### Recommendations (Should Fix)
- [issue with file:line]
### Minor Suggestions (Nice to Have)
- [suggestion]
Use AskUserQuestion tool for quality review decision:
If user selects "Fix critical issues now" or "Fix all issues now":
If user selects "Review specific issues":
Use AskUserQuestion tool:
Present detailed explanation of selected issues. Output: "Would you like to fix these issues?" WAIT for user's decision. If yes, address issues and return to step 4.
Generate final summary:
## Task Completed
### What Was Built
- [description of implementation]
### Key Decisions Made
- [architectural choices]
- [trade-offs accepted]
### Files Modified
- [list with brief descriptions]
### Tests Added/Updated
- [test files]
### Suggested Next Steps
- [recommendations for future work]
Update task history file with completion status and summary.
Update TodoWrite: Mark all items as completed.
Note which agent failed and why
Use AskUserQuestion tool for recovery:
If retry selected: Re-launch the failed agent with same prompt
If alternative selected: Use Task tool with backup agent type (e.g., "Explore" instead of "feature-dev:code-explorer")
Use AskUserQuestion tool:
Based on selection, return to appropriate phase
.claude/task-history/:
PROJECT_ROOT/.claude/task-history/~/.claude/task-history/ (global)This skill uses a Coordinator + Worker Agents pattern to optimize context usage:
Main Conversation (Coordinator):
Background Agents (Workers):
Async Patterns by Phase:
| Phase | Background Agent | Purpose |
|---|---|---|
| 1 | Discovery Agent | Read docs, detect project type, analyze complexity |
| 2 | Validation Agent | Verify exploration completeness (runs while presenting) |
| 3 | Requirements Analyzer | Identify gaps, conflicts, dependencies, risks |
| 4 | Consolidation + Quality (parallel) | Merge approaches + pre-review quality |
| 5 | Plan Generator | Generate plan, task history, and todos |
| 6 | Agent Preparation | Prepare prompts for specialized agents |
| 7 | Quality Reviewers (3 parallel) | Multi-perspective code review |
Key Patterns:
Launch Early, Retrieve Later:
1. Use Task tool with run_in_background=true
2. Do other work while agent runs
3. Use TaskOutput to retrieve results
Progress Indicators for Long Waits:
Use TaskOutput to retrieve results:
- If wait exceeds 10s, output: "Processing message..."
Parallel Independent Agents:
Use Task tool to launch N agents IN PARALLEL with run_in_background=true:
- All agents run concurrently
- Use TaskOutput for each to retrieve results
Present While Validating:
1. Launch validation agent in background
2. Present initial findings to user (don't wait)
3. Use TaskOutput to get validation results
4. Append additional findings if any
Prepared Prompts Pattern:
1. Agent analyzes what specialized agents are needed
2. Prepares ready-to-use prompts with file context
3. Use prepared prompts during implementation
Benefits: