@e0ipso/ai-task-manager 1.2.0 → 1.2.1

package/README.md

@@ -10,6 +10,25 @@ AI-powered task management CLI tool to improve your context. It supports multipl
 - 🤝 **Multi-Assistant Support**: Configure support for Claude, and Gemini
 - 📋 **Template System**: Built-in templates for different project types (basic, development, research)
 
+## 💰 Intelligent Token Usage
+
+**One of the key benefits of this project is dramatically reducing AI costs by using the right model for the right task.**
+
+The AI Task Manager leverages a **staged refinement approach** that maximizes the value of expensive, high-capability models while delegating execution to faster, cheaper models:
+
+### 🧠 Use Premium Models for Complex Analysis
+- **Planning Phase** (`/tasks:create-plan`): Deploy your most capable models (Claude Opus, GPT-5, etc.) for deep requirement analysis, architecture decisions, and strategic planning
+- **Task Generation** (`/tasks:generate-tasks`): Leverage advanced reasoning for complex decomposition, dependency mapping, and scope optimization
+
+### ⚡ Use Fast Models for Execution
+- **Blueprint Execution** (`/tasks:execute-blueprint`): Switch to faster, cost-effective models (Gemini 2.0 Flash, Claude Haiku) for task execution
+- **Individual Tasks**: Sub-agents can also choose to use simpler models since most complexity is resolved during planning
+
+### 💡 Why This Works
+The heavy cognitive lifting happens during plan creation and task generation. By the time you reach execution, the blueprint documents are detailed and specific enough that simpler models can reliably implement them. This approach can **reduce your AI costs** and be **significantly faster** compared to using premium models for all phases.
+
+_The more complex your project, the greater the savings._
+
 ## 🚀 Quick Start
 
 ### 🏗️ Initialize a New Workspace
@@ -29,7 +48,7 @@ The `--destination-directory` flag allows you to specify an alternative director
 # Claude only
 npx @e0ipso/ai-task-manager init --assistants claude
 
-# Gemini only  
+# Gemini only
 npx @e0ipso/ai-task-manager init --assistants gemini
 
 # Both Claude and Gemini

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e0ipso/ai-task-manager",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Task management for AI coding assistants",
   "main": "dist/index.js",
   "bin": {

package/templates/ai-task-manager/TASK_MANAGER_INFO.md

@@ -5,17 +5,17 @@ commands for Claude Code.
 
 ## Types of Documents
 
-Work orders (abbreviated as WO) are complex prompts for programming, 
+Work orders (abbreviated as WO) are complex prompts for programming,
 organizational, or management tasks created by a user. Work orders are
-independent of each other and cannot share any context. By definition 
+independent of each other and cannot share any context. By definition
 different work orders can be worked on independently.
 
 Each work order has plan associated to it. The plan is a comprehensive document
 highlighting all the aspects of the work necessary to accomplish the goals from
 the work order.
 
-Each plan will be broken into tasks. Each task is a logical unit of work that 
-has a single purpose, and is solved using a single skill. All tasks exist as 
+Each plan will be broken into tasks. Each task is a logical unit of work that
+has a single purpose, and is solved using a single skill. All tasks exist as
 part of a plan. Tasks can have dependencies on other tasks. This happens when a
 task cannot be worked on (or completed) before some other task(s) are completed.
 
@@ -53,10 +53,10 @@ Plans are organized as follows:
 ```
 
 Note how in the `.ai/task-manager/plans/` folder we have a sub-folder per plan.
-Each sub-folder will contain the plan document and has a name following a naming 
-pattern `[ID]--[plan-short-name]`. Where the ID is auto-incremental. The plan 
-document has a name following the pattern `plan-[ID]--[plan-short-name].md`. 
-Finally, all tasks are under a `tasks` sub-folder. Each task has a name 
+Each sub-folder will contain the plan document and has a name following a naming
+pattern `[ID]--[plan-short-name]`. Where the ID is auto-incremental. The plan
+document has a name following the pattern `plan-[ID]--[plan-short-name].md`.
+Finally, all tasks are under a `tasks` sub-folder. Each task has a name
 according to the pattern `[incremental-ID]--[task-short-name].md`. IDs for tasks
 are auto-incremental within a plan. Each plan starts their tasks' IDs from 01.
 

package/templates/commands/tasks/create-plan.md

@@ -35,27 +35,172 @@ If any critical context is missing:
 2. Ask targeted follow-up questions grouped by category
 3. Wait for user responses before proceeding to planning
 4. Frame questions clearly with examples when helpful
+5. Be extra cautious. Users miss important context very often. Extract it from them
 
 Example clarifying questions:
 - "What is your primary goal with [specific aspect]?"
 - "Do you have any existing [resources/code/infrastructure] I should consider?"
 - "What is your timeline for completing this?"
 - "Are there specific constraints I should account for?"
+- "Do you want me to write tests for this?"
+- "Are there other systems, projects, or modules that perform a similar task?"
 
 #### Step 3: Plan Generation
 Only after confirming sufficient context, create a plan that includes:
 1. **Executive Summary**: Brief overview of the approach
 2. **Detailed Steps**: Numbered, actionable tasks with clear outcomes
-3. **Implementation Order**: Logical sequence with dependencies noted
-4. **Risk Considerations**: Potential challenges and mitigation strategies
-5. **Success Metrics**: How to measure completion and quality
-6. **Resource Requirements**: Tools, skills, or assets needed for each step
+3. **Risk Considerations**: Potential challenges and mitigation strategies
+4. **Success Metrics**: How to measure completion and quality
+
+Remember that a plan needs to be reviewed by a human. Be concise and to the point. Also, include mermaid diagrams to illustrate the plan.
+
+### Important Notes
+- Never generate a partial or assumed plan without adequate context
+- Prioritize accuracy over speed
+- Consider both technical and non-technical aspects
+- Adapt the plan format based on the task type (development, design, research, etc.)
+- DO NOT create or list any tasks or phases during the plan creation. This will be done in a later step. Stick to writing the PRD (Project Requirements Document).
+
+### Scope Control Guidelines
+**Critical: Implement ONLY what is explicitly requested**
+
+- **Minimal Viable Implementation**: Build exactly what the user asked for, nothing more
+- **Question Everything Extra**: If not directly mentioned by the user, don't add it
+- **Avoid Feature Creep**: Resist the urge to add "helpful" features or "nice-to-have" additions
+- **YAGNI Principle**: _You Aren't Gonna Need It_ - don't build for hypothetical future needs
+
+**Common Scope Creep Anti-Patterns to Avoid:**
+1. Adding extra commands or features "for completeness"
+2. Creating infrastructure for future features that weren't requested
+3. Building abstractions or frameworks when simple solutions suffice
+4. Adding configuration options not specifically mentioned
+5. Implementing error handling beyond what's necessary for the core request
+6. Creating documentation or help systems unless explicitly requested
+
+**When in doubt, ask**: "Is this feature explicitly mentioned in the user's request?"
+
+### Simplicity Principles
+**Favor maintainability over cleverness**
+
+- **Simple Solutions First**: Choose the most straightforward approach that meets requirements
+- **Avoid Over-Engineering**: Don't create complex systems when simple ones work
+- **Readable Code**: Write code that others can easily understand and modify
+- **Standard Patterns**: Use established patterns rather than inventing new ones
+- **Minimal Dependencies**: Add external dependencies only when essential, but do not re-invent the wheel
+- **Clear Structure**: Organize code in obvious, predictable ways
+
+**Remember**: A working simple solution is better than a complex "perfect" one.
 
 ### Output Format
 Structure your response as follows:
 - If context is insufficient: List specific clarifying questions
 - If context is sufficient: Provide the comprehensive plan using the structure above. Use the information in @TASK_MANAGER_INFO.md for the directory structure and additional information about plans.
 
+Outside the plan document, be **extremely** concise. Just tell the user that you are done, and instruct them to review the plan document.
+
+#### Plan Template
+
+```markdown
+---
+id: [PLAN-ID]
+summary: "[Brief one-line description of what this plan accomplishes]"
+created: [YYYY-MM-DD]
+---
+
+# Plan: [Descriptive Plan Title]
+
+## Original Work Order
+[The unmodified user input that was used to generate this plan, as a quote]
+
+## Plan Clarifications [only add it if clarifications were necessary]
+[Clarification questions and answers in table format]
+
+## Executive Summary
+
+[Provide a 2-3 paragraph overview of the plan. Include:
+- What the plan accomplishes
+- Why this approach was chosen
+- Key benefits and outcomes expected]
+
+## Context
+
+### Current State
+[Describe the existing situation, problems, or gaps that this plan addresses. Include specific details about what exists now, current limitations, and why change is needed.]
+
+### Target State
+[Describe the desired end state after plan completion. Be specific about the expected outcomes and how success will be measured.]
+
+### Background
+[Any additional context, requirements, constraints, any solutions that we tried that didn't work, or relevant history that informs the implementation approach.]
+
+## Technical Implementation Approach
+
+[Provide an overview of the implementation strategy, key architectural decisions, and technical approach. Break down into major components or phases using ### subheadings.]
+
+### [Component/Phase 1 Name]
+**Objective**: [What this component accomplishes and why it's important]
+
+[Detailed explanation of implementation approach, key technical decisions, specifications, and rationale for design choices.]
+
+### [Component/Phase 2 Name]
+**Objective**: [What this component accomplishes and why it's important]
+
+[Detailed explanation of implementation approach, key technical decisions, specifications, and rationale for design choices.]
+
+### [Additional Components as Needed]
+[Continue with additional technical components or phases following the same pattern]
+
+## Risk Considerations and Mitigation Strategies
+
+### Technical Risks
+- **[Specific Technical Risk]**: [Description of the technical challenge or limitation]
+  - **Mitigation**: [Specific strategy to address this technical risk]
+
+### Implementation Risks
+- **[Specific Implementation Risk]**: [Description of implementation-related challenge]
+  - **Mitigation**: [Specific strategy to address this implementation risk]
+
+### [Additional Risk Categories as Needed]
+[Continue with other risk categories such as Integration Risks, Quality Risks, Resource Risks, etc.]
+
+## Success Criteria
+
+### Primary Success Criteria
+1. [Measurable outcome 1]
+2. [Measurable outcome 2]
+3. [Measurable outcome 3]
+
+### Quality Assurance Metrics
+1. [Quality measure 1]
+2. [Quality measure 2]
+3. [Quality measure 3]
+
+## Resource Requirements
+
+### Development Skills
+[Required technical expertise and specialized knowledge areas needed for successful implementation]
+
+### Technical Infrastructure
+[Tools, libraries, frameworks, and systems needed for development and deployment]
+
+### [Additional Resource Categories as Needed]
+[Other resources such as external dependencies, research access, third-party services, etc.]
+
+## Integration Strategy
+[Optional section - how this work integrates with existing systems]
+
+## Implementation Order
+[Optional section - high-level sequence without detailed phases]
+
+## Notes
+[Optional section - any additional considerations, constraints, or important context]
+```
+
+#### Patterns to Avoid
+Do not include the following in your plan output.
+- Avoid time estimations
+- Avoid task lists and mentions of phases (those are things we'll introduce later)
+
 #### Frontmatter Structure
 
 Example:
@@ -103,40 +248,3 @@ echo $(($(find .ai/task-manager/{plans,archive} -name "plan-*.md" -exec grep "^i
 - **Directory names**: Use zero-padded strings (`07--plan-name`)
 
 This command reads `id:` values from existing plan front-matter as the source of truth. Handles empty directories (returns 1) and gaps in sequence automatically.
-
-### Important Notes
-- Never generate a partial or assumed plan without adequate context
-- Prioritize accuracy over speed
-- Consider both technical and non-technical aspects
-- Adapt the plan format based on the task type (development, design, research, etc.)
-- DO NOT create or list any tasks or phases during the plan creation. This will be done in a later step. Stick to writing the PRD (Project Requirements Document).
-
-### Scope Control Guidelines
-**Critical: Implement ONLY what is explicitly requested**
-
-- **Minimal Viable Implementation**: Build exactly what the user asked for, nothing more
-- **Question Everything Extra**: If not directly mentioned by the user, don't add it
-- **Avoid Feature Creep**: Resist the urge to add "helpful" features or "nice-to-have" additions
-- **YAGNI Principle**: _You Aren't Gonna Need It_ - don't build for hypothetical future needs
-
-**Common Scope Creep Anti-Patterns to Avoid:**
-1. Adding extra commands or features "for completeness"
-2. Creating infrastructure for future features that weren't requested
-3. Building abstractions or frameworks when simple solutions suffice
-4. Adding configuration options not specifically mentioned
-5. Implementing error handling beyond what's necessary for the core request
-6. Creating documentation or help systems unless explicitly requested
-
-**When in doubt, ask**: "Is this feature explicitly mentioned in the user's request?"
-
-### Simplicity Principles
-**Favor maintainability over cleverness**
-
-- **Simple Solutions First**: Choose the most straightforward approach that meets requirements
-- **Avoid Over-Engineering**: Don't create complex systems when simple ones work
-- **Readable Code**: Write code that others can easily understand and modify
-- **Standard Patterns**: Use established patterns rather than inventing new ones
-- **Minimal Dependencies**: Add external dependencies only when essential
-- **Clear Structure**: Organize code in obvious, predictable ways
-
-**Remember**: A working simple solution is better than a complex "perfect" one.

package/templates/commands/tasks/execute-blueprint.md

@@ -4,7 +4,15 @@ description: Execute the task in the plan
 ---
 # Task Execution
 
-You are the orchestrator responsible for executing all tasks defined in the execution blueprint of a plan document. Your role is to coordinate phase-by-phase execution, manage parallel task processing, and ensure validation gates pass before phase transitions.
+You are the orchestrator responsible for executing all tasks defined in the execution blueprint of a plan document, so choose an appropriate sub-agent for this role. Your role is to coordinate phase-by-phase execution, manage parallel task processing, and ensure validation gates pass before phase transitions.
+
+## Critical Rules
+
+1. **Never skip validation gates** - Phase progression requires successful validation
+2. **Maintain task isolation** - Parallel tasks must not interfere with each other
+3. **Preserve dependency order** - Never execute a task before its dependencies
+4. **Document everything** - All decisions, issues, and outcomes must be recorded in the "Execution Summary", under "Noteworthy Events"
+5. **Fail safely** - Better to halt and request help than corrupt the execution state
 
 ## Input Requirements
 - A plan document with an execution blueprint section. See @.ai/task-manager/TASK_MANAGER_INFO.md fo find the plan with ID $1
@@ -34,11 +42,11 @@ Before starting execution check if you are in the `main` branch. If so, create a
         - Read task frontmatter to extract the `skills` property (array of technical skills)
         - Analyze task requirements and technical domain from description
         - Match task skills against available sub-agent capabilities
-        - Select the most appropriate Claude Code sub-agent (if any are available). If no sub-agent is appropriate, use the generic one.
+        - Select the most appropriate sub-agent (if any are available). If no sub-agent is appropriate, use the general-purpose one.
         - Consider task-specific requirements from the task document
 
 3. **Parallel Execution**
-    - Deploy all selected agents simultaneously
+    - Deploy all selected agents simultaneously using your internal Task tool
     - Monitor execution progress for each task
     - Capture outputs and artifacts from each agent
     - Update task status in real-time
@@ -50,7 +58,7 @@ Before starting execution check if you are in the `main` branch. If so, create a
 
 5. **Validation Gate Execution**
     - Reference validation criteria from `@.ai/task-manager/VALIDATION_GATES.md`
-    - Execute all validation checks for the current phase
+    - Execute all validation gates for the current phase
     - Document validation results
     - Only proceed if ALL validations pass
 
@@ -79,8 +87,8 @@ Select agents based on:
 
 Update the list of tasks from the plan document to add the status of each task
 and phase. Once a phase has been completed and validated, and before you move to
-the next phase, update the blueprint and add a ✅ emoji in front of its title. 
-Add ✔️ emoji in front of all the tasks in that phase, and update their status to 
+the next phase, update the blueprint and add a ✅ emoji in front of its title.
+Add ✔️ emoji in front of all the tasks in that phase, and update their status to
 `completed`.
 
 #### Task Status Updates
@@ -92,25 +100,6 @@ Valid status transitions:
 
 ### Error Handling
 
-#### Task Failure Protocol
-1. **Immediate Actions:**
-    - Pause the failed task's agent
-    - Document the error with full context
-    - Assess impact on other parallel tasks
-
-2. **Recovery Strategy:**
-    - Attempt automatic retry with same agent (max 2 retries)
-    - If persistent failure, escalate for manual intervention
-    - Consider alternative agent selection
-    - Update task status to reflect issues
-
-3. **Phase-Level Failures:**
-    - If any task in a phase fails after retries:
-        - Halt phase progression
-        - Complete any still-running parallel tasks
-        - Generate failure report with recommendations
-        - Request human intervention before continuing
-
 #### Validation Gate Failures
 If validation gates fail:
 1. Document which specific validations failed
@@ -118,43 +107,10 @@ If validation gates fail:
 3. Generate remediation plan
 4. Re-execute affected tasks after fixes
 5. Re-run validation gates
+6. If errors persist, escalate to the user
 
 ### Output Requirements
 
-#### Final Execution Report
-Upon blueprint completion respond with the following to the user:
-
-```
-✅ Execution Complete
-
-📊 Summary Statistics
-
-- Total Phases Executed: X
-- Total Tasks Completed: Y
-- Total Execution Time: [duration]
-- Parallel Efficiency: X% (tasks run in parallel vs. sequential)
-
-📋 Phase-by-Phase Results
-
-[Concise summary of each phase]
-
-📦 Artifacts Generated
-
-[List of all outputs and deliverables]
-
-💡 Recommendations
-
-[Any follow-up actions or optimizations identified]
-```
-
-## Critical Rules
-
-1. **Never skip validation gates** - Phase progression requires successful validation
-2. **Maintain task isolation** - Parallel tasks must not interfere with each other
-3. **Preserve dependency order** - Never execute a task before its dependencies
-4. **Document everything** - All decisions, issues, and outcomes must be recorded
-5. **Fail safely** - Better to halt and request help than corrupt the execution state
-
 ## Optimization Guidelines
 
 - **Maximize parallelism**: Always run all available tasks in a phase simultaneously
@@ -175,7 +131,6 @@ Append an execution summary section to the plan document with the following form
 
 **Status**: ✅ Completed Successfully
 **Completed Date**: [YYYY-MM-DD]
-**Total Execution Time**: [duration]
 
 ### Results
 [Brief summary of execution results and key deliverables]
@@ -183,24 +138,18 @@ Append an execution summary section to the plan document with the following form
 ### Noteworthy Events
 [Highlight any unexpected events, challenges overcome, or significant findings during execution. If none occurred, state "No significant issues encountered."]
 
-### Final Validation
-✅ All validation gates passed
-✅ All tasks completed successfully
+### Recommendations
+[Any follow-up actions or optimizations identified]
 ```
 
 ### 2. Plan Archival
 
 After successfully appending the execution summary:
 
-1. **Create archive directory if needed**:
-   ```bash
-   mkdir -p .ai/task-manager/archive
-   ```
-
-2. **Move completed plan to archive**:
-   ```bash
-   mv .ai/task-manager/plans/[plan-folder] .ai/task-manager/archive/
-   ```
+**Move completed plan to archive**:
+```bash
+mv .ai/task-manager/plans/[plan-folder] .ai/task-manager/archive/
+```
 
 ### Important Notes
 

package/templates/commands/tasks/generate-tasks.md

@@ -40,7 +40,6 @@ Each task must be:
 - **Single-purpose**: One clear deliverable or outcome
 - **Atomic**: Cannot be meaningfully split further
 - **Skill-specific**: Executable by a single skill agent (examples below)
-- **Time-bounded**: Completable in a reasonable timeframe by a skilled developer
 - **Verifiable**: Has clear completion criteria
 
 #### Skill Selection and Technical Requirements
@@ -420,7 +419,7 @@ Before finalizing, ensure:
 - Phases execute in strict numerical order
 - Phase N+1 cannot begin until Phase N is fully complete and validated
 - This ensures dependency integrity and systematic progress
-- 
+-
 
 #### Validation Gates
 - Each phase has associated validation criteria defined externally