@e0ipso/ai-task-manager 1.21.0 → 1.22.0

package/README.md

@@ -49,10 +49,11 @@ Comprehensive guides covering:
 
 **Manual Workflow (Full Control):**
 1. **📝 Create a plan** → `/tasks:create-plan Create user authentication system`
-2. **📋 Generate tasks** → `/tasks:generate-tasks 1`
-3. **🚀 Execute blueprint** → `/tasks:execute-blueprint 1`
-4. **📊 Monitor progress** → `npx @e0ipso/ai-task-manager status`
-5. **🗂️ Manage plans** → `npx @e0ipso/ai-task-manager plan show 1`
+2. **🔍 Refine the plan** → `/tasks:refine-plan 1` (have a second assistant review the plan, ask clarifying questions, and update the document before tasks are created)
+3. **📋 Generate tasks** → `/tasks:generate-tasks 1`
+4. **🚀 Execute blueprint** → `/tasks:execute-blueprint 1`
+5. **📊 Monitor progress** → `npx @e0ipso/ai-task-manager status`
+6. **🗂️ Manage plans** → `npx @e0ipso/ai-task-manager plan show 1`
 
 ## 🤖 Supported Assistants
 

package/package.json

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

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

@@ -5,7 +5,8 @@ description: Create a comprehensive plan to accomplish the request from the user
 # Comprehensive Plan Creation
 
 You are a strategic planning specialist who creates actionable plan documents that balance comprehensive context with 
-disciplined scope control. Your role is to think hard to create detailed, actionable plans based on user input while ensuring you have all necessary context before proceeding. Use the plan-creator sub-agent for this if it is available.
+disciplined scope control. Your role is to think hard to create detailed, actionable plans based on user input while 
+ensuring you have all necessary context before proceeding. Use the plan-creator sub-agent for this if it is available.
 
 ## Assistant Configuration
 

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

@@ -57,309 +57,23 @@ BLUEPRINT_EXISTS=$(node .ai/task-manager/config/scripts/validate-plan-blueprint.
 
 If either `$TASK_COUNT` is 0 or `$BLUEPRINT_EXISTS` is "no":
    - Display notification to user: "⚠️ Tasks or execution blueprint not found. Generating tasks automatically..."
-   - Execute the following task generation process inline:
+   - Execute the embedded task generation process below
 
    ## Embedded Task Generation
 
-   Think harder and use tools.
+   Follow ALL instructions from `generate-tasks.md` exactly for plan ID $1.
 
-   You are a comprehensive task planning assistant. Your role is to create detailed, actionable plans based on user input while ensuring you have all necessary context before proceeding.
-
-   Include /TASK_MANAGER.md for the directory structure of tasks.
-
-   ## Instructions
-
-   You will think hard to analyze the provided plan document and decompose it into atomic, actionable tasks with clear dependencies and groupings.
-
-   Use your internal Todo task tool to track the following process:
-
-   - [ ] Read and process plan $1
-   - [ ] Use the Task Generation Process to create tasks according to the Task Creation Guidelines
-   - [ ] Read and run the .ai/task-manager/config/hooks/POST_TASK_GENERATION_ALL.md
-
-   ### Input
-   - A plan document. See .ai/task-manager/config/TASK_MANAGER.md fo find the plan with ID $1
-   - The plan contains high-level objectives and implementation steps
-
-   ### Input Error Handling
-   If the plan does not exist. Stop immediately and show an error to the user.
-
-   ### Task Creation Guidelines
-
-   #### Task Minimization Principles
-   **Core Constraint:** Create only the minimum number of tasks necessary to satisfy the plan requirements. Target a 20-30% reduction from comprehensive task lists by questioning the necessity of each component.
-
-   **Minimization Rules:**
-   - **Direct Implementation Only**: Create tasks for explicitly stated requirements, not "nice-to-have" features
-   - **DRY Task Principle**: Each task should have a unique, non-overlapping purpose
-   - **Question Everything**: For each task, ask "Is this absolutely necessary to meet the plan objectives?"
-   - **Avoid Gold-plating**: Resist the urge to add comprehensive features not explicitly required
-
-   **Antipatterns to Avoid:**
-   - Creating separate tasks for "error handling" when it can be included in the main implementation
-   - Breaking simple operations into multiple tasks (e.g., separate "validate input" and "process input" tasks)
-   - Adding tasks for "future extensibility" or "best practices" not mentioned in the plan
-   - Creating comprehensive test suites for trivial functionality
-
-   #### Task Granularity
-   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)
-   - **Verifiable**: Has clear completion criteria
-
-   #### Skill Selection and Technical Requirements
-
-   **Core Principle**: Each task should require 1-2 specific technical skills that can be handled by specialized agents. Skills should be automatically inferred from the task's technical requirements and objectives.
-
-   **Skill Selection Criteria**:
-   1. **Technical Specificity**: Choose skills that directly match the technical work required
-   2. **Agent Specialization**: Select skills that allow a single skilled agent to complete the task
-   3. **Minimal Overlap**: Avoid combining unrelated skill domains in a single task
-   4. **Creative Inference**: Derive skills from task objectives and implementation context
-
-   **Inspirational Skill Examples** (use kebab-case format):
-   - Frontend: `react-components`, `css`, `js`, `vue-components`, `html`
-   - Backend: `api-endpoints`, `database`, `authentication`, `server-config`
-   - Testing: `jest`, `playwright`, `unit-testing`, `e2e-testing`
-   - DevOps: `docker`, `github-actions`, `deployment`, `ci-cd`
-   - Languages: `typescript`, `python`, `php`, `bash`, `sql`
-   - Frameworks: `nextjs`, `express`, `drupal-backend`, `wordpress-plugins`
-
-   **Automatic Skill Inference Examples**:
-   - "Create user login form" → `["react-components", "authentication"]`
-   - "Build REST API for orders" → `["api-endpoints", "database"]`
-   - "Add Docker deployment" → `["docker", "deployment"]`
-   - "Write Jest tests for utils" → `["jest"]`
-
-   **Assignment Guidelines**:
-   - **1 skill**: Focused, single-domain tasks
-   - **2 skills**: Tasks requiring complementary domains
-   - **Split if 3+**: Indicates task should be broken down
-
-   ```
-   # Examples
-   skills: ["css"]  # Pure styling
-   skills: ["api-endpoints", "database"]  # API with persistence
-   skills: ["react-components", "jest"]  # Implementation + testing
-   ```
-
-   #### Meaningful Test Strategy Guidelines
-
-   **IMPORTANT** Make sure to copy this _Meaningful Test Strategy Guidelines_ section into all the tasks focused on testing, and **also** keep them in mind when generating tasks.
-
-   Your critical mantra for test generation is: "write a few tests, mostly integration".
-
-   **Definition of "Meaningful Tests":**
-   Tests that verify custom business logic, critical paths, and edge cases specific to the application. Focus on testing YOUR code, not the framework or library functionality.
-
-   **When TO Write Tests:**
-   - Custom business logic and algorithms
-   - Critical user workflows and data transformations
-   - Edge cases and error conditions for core functionality
-   - Integration points between different system components
-   - Complex validation logic or calculations
-
-   **When NOT to Write Tests:**
-   - Third-party library functionality (already tested upstream)
-   - Framework features (React hooks, Express middleware, etc.)
-   - Simple CRUD operations without custom logic
-   - Getter/setter methods or basic property access
-   - Configuration files or static data
-   - Obvious functionality that would break immediately if incorrect
-
-   **Test Task Creation Rules:**
-   - Combine related test scenarios into single tasks (e.g., "Test user authentication flow" not separate tasks for login, logout, validation)
-   - Focus on integration and critical path testing over unit test coverage
-   - Avoid creating separate tasks for testing each CRUD operation individually
-   - Question whether simple functions need dedicated test tasks
-
-   ### Task Generation Process
-
-   #### Step 1: Task Decomposition
-   1. Read through the entire plan
-   2. Identify all concrete deliverables **explicitly stated** in the plan
-   3. Apply minimization principles: question necessity of each potential task
-   4. Break each deliverable into atomic tasks (only if genuinely needed)
-   5. Ensure no task requires multiple skill sets
-   6. Verify each task has clear inputs and outputs
-   7. **Minimize test tasks**: Combine related testing scenarios, avoid testing framework functionality
-   8. Be very detailed with the "Implementation Notes". This should contain enough detail for a non-thinking LLM model to successfully complete the task. Put these instructions in a collapsible field `<details>`.
-
-   #### Step 2: Dependency Analysis
-   For each task, identify:
-   - **Hard dependencies**: Tasks that MUST complete before this can start
-   - **Soft dependencies**: Tasks that SHOULD complete for optimal execution
-   - **No circular dependencies**: Validate the dependency graph is acyclic
-
-   Dependency Rule: Task B depends on Task A if:
-   - B requires output or artifacts from A
-   - B modifies code created by A
-   - B tests functionality implemented in A
-
-   #### Step 3: Task Generation
-
-   ##### Frontmatter Structure
-
-   Example:
-   ```yaml
-   ---
-   id: 1
-   group: "user-authentication"
-   dependencies: []  # List of task IDs, e.g., [2, 3]
-   status: "pending"  # pending | in-progress | completed | needs-clarification
-   created: "2024-01-15"
-   skills: ["react-components", "authentication"]  # Technical skills required for this task
-   # Optional: Include complexity scores for high-complexity tasks or decomposition tracking
-   # complexity_score: 4.2  # Composite complexity score (only if >4 or decomposed)
-   # complexity_notes: "Decomposed from original task due to high technical depth"
-   ---
-   ```
-
-   The schema for this frontmatter is:
-   ```json
-   {
-     "type": "object",
-     "required": ["id", "group", "dependencies", "status", "created", "skills"],
-     "properties": {
-       "id": {
-         "type": ["number"],
-         "description": "Unique identifier for the task. An integer."
-       },
-       "group": {
-         "type": "string",
-         "description": "Group or category the task belongs to"
-       },
-       "dependencies": {
-         "type": "array",
-         "description": "List of task IDs this task depends on",
-         "items": {
-           "type": ["number"]
-         }
-       },
-       "status": {
-         "type": "string",
-         "enum": ["pending", "in-progress", "completed", "needs-clarification"],
-         "description": "Current status of the task"
-       },
-       "created": {
-         "type": "string",
-         "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
-         "description": "Creation date in YYYY-MM-DD format"
-       },
-       "skills": {
-         "type": "array",
-         "description": "Technical skills required for this task (1-2 skills recommended)",
-         "items": {
-           "type": "string",
-           "pattern": "^[a-z][a-z0-9-]*$"
-         },
-         "minItems": 1,
-         "uniqueItems": true
-       },
-       "complexity_score": {
-         "type": "number",
-         "minimum": 1,
-         "maximum": 10,
-         "description": "Optional: Composite complexity score (include only if >4 or for decomposed tasks)"
-       },
-       "complexity_notes": {
-         "type": "string",
-         "description": "Optional: Rationale for complexity score or decomposition decisions"
-       }
-     },
-     "additionalProperties": false
-   }
-   ```
-
-   ##### Task Body Structure
-
-   Use the task template in .ai/task-manager/config/templates/TASK_TEMPLATE.md
-
-   ##### Task ID Generation
-
-   When creating tasks, you need to determine the next available task ID for the specified plan. Use this bash command to automatically generate the correct ID:
-
-   ```bash
-   node .ai/task-manager/config/scripts/get-next-task-id.cjs $1
-   ```
-
-   ### Validation Checklist
-   Before finalizing, ensure:
-
-   **Core Task Requirements:**
-   - [ ] Each task has 1-2 appropriate technical skills assigned
-   - [ ] Skills are automatically inferred from task objectives and technical requirements
-   - [ ] All dependencies form an acyclic graph
-   - [ ] Task IDs are unique and sequential
-   - [ ] Groups are consistent and meaningful
-   - [ ] Every **explicitly stated** task from the plan is covered
-   - [ ] No redundant or overlapping tasks
-
-   **Complexity Analysis & Controls:**
-   - [ ] **Complexity Analysis Complete**: All tasks assessed using 5-dimension scoring
-   - [ ] **Decomposition Applied**: Tasks with composite score ≥6 have been decomposed or justified
-   - [ ] **Final Task Complexity**: All final tasks have composite score ≤5 (target ≤4)
-   - [ ] **Iteration Limits Respected**: No task exceeded 3 decomposition rounds
-   - [ ] **Minimum Viability**: No tasks decomposed below complexity threshold of 3
-   - [ ] **Quality Gates Passed**: All decomposed tasks meet enhanced quality criteria
-   - [ ] **Dependency Integrity**: No circular dependencies or orphaned tasks exist
-   - [ ] **Error Handling Complete**: All edge cases resolved or escalated appropriately
-
-   **Complexity Documentation Requirements:**
-   - [ ] **Complexity Scores Documented**: Individual dimension scores recorded for complex tasks
-   - [ ] **Decomposition History**: Iteration tracking included in `complexity_notes` for decomposed tasks
-   - [ ] **Validation Status**: All tasks marked with appropriate validation outcomes
-   - [ ] **Escalation Documentation**: High-complexity tasks have clear escalation notes
-   - [ ] **Consistency Validated**: Complexity scores align with task descriptions and skills
-
-   **Scope & Quality Control:**
-   - [ ] **Minimization Applied**: Each task is absolutely necessary (20-30% reduction target)
-   - [ ] **Test Tasks are Meaningful**: Focus on business logic, not framework functionality
-   - [ ] **No Gold-plating**: Only plan requirements are addressed
-   - [ ] **Total Task Count**: Represents minimum viable implementation
-   - [ ] **Scope Preservation**: Decomposed tasks collectively match original requirements
-
-   **System Reliability:**
-   - [ ] **Error Conditions Resolved**: No unresolved error states remain
-   - [ ] **Manual Intervention Flagged**: Complex edge cases properly escalated
-   - [ ] **Quality Checkpoints**: All validation gates completed successfully
-   - [ ] **Dependency Graph Validated**: Full dependency analysis confirms acyclic, logical relationships
-
-   ### Error Handling
-   If the plan lacks sufficient detail:
-   - Note areas needing clarification
-   - Create placeholder tasks marked with `status: "needs-clarification"`
-   - Document assumptions made
-
-   #### Step 4: POST_TASK_GENERATION_ALL hook
-
-   Read and run the .ai/task-manager/config/hooks/POST_TASK_GENERATION_ALL.md
-
-   ### Output Requirements
-
-   **Output Behavior:**
-
-   Provide a concise completion message with task count:
-   - Example: "Tasks generated for plan [id]: [count] tasks created"
-
-   **CRITICAL - Structured Output for Command Coordination:**
-
-   Always end your output with a standardized summary in this exact format:
-
-   ```
-   ---
-   Task Generation Summary:
-   - Plan ID: [numeric-id]
-   - Tasks: [count]
-   - Status: Ready for execution
-   ```
-
-   This structured output enables automated workflow coordination and must be included even when running standalone.
+   This includes:
+   - Reading and processing the plan document
+   - Applying task minimization principles (20-30% reduction target)
+   - Creating atomic tasks with 1-2 skills each
+   - Generating proper task files with frontmatter and body structure
+   - Running all validation checklists
+   - Executing the POST_TASK_GENERATION_ALL hook
 
    ## Resume Blueprint Execution
 
-   After task generation completes, continue with the execution process below.
+   After task generation completes, continue with execution below.
 
 Otherwise, if tasks exist, proceed directly to execution.
 

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

@@ -23,7 +23,7 @@ Think harder and use tools.
 
 You are a comprehensive task planning assistant. Your role is to create detailed, actionable plans based on user input while ensuring you have all necessary context before proceeding.
 
-Include /TASK_MANAGER.md for the directory structure of tasks.
+Include `.ai/task-manager/config/TASK_MANAGER.md` for the directory structure of tasks.
 
 ## Instructions
 
@@ -36,8 +36,13 @@ Use your internal Todo task tool to track the following process:
 - [ ] Read and run the .ai/task-manager/config/hooks/POST_TASK_GENERATION_ALL.md
 
 ### Input
-- A plan document. See .ai/task-manager/config/TASK_MANAGER.md fo find the plan with ID $1
-- The plan contains high-level objectives and implementation steps
+
+- A plan document. Extract it with the following command.
+
+```bash
+# Extract validation results directly from script
+PLAN_FILE=$(node .ai/task-manager/config/scripts/validate-plan-blueprint.cjs $1 planFile)
+```
 
 ### Input Error Handling
 If the plan does not exist. Stop immediately and show an error to the user.

package/templates/assistant/commands/tasks/refine-plan.md

@@ -0,0 +1,130 @@
+---
+argument-hint: "[plan-ID]"
+description: Review the plan with the provided ID, gather clarifications, and refine it.
+---
+# Plan Review and Refinement
+
+You are a strategic planning specialist who specializes in interrogating existing plans, uncovering blind spots, and 
+refining the document so that task generators receive the clearest possible instructions. Treat the current plan as the 
+work product of another assistant: your responsibility is to pressure test it, request any missing information from the 
+user, and update the plan with the refinements. Use the plan-creator sub-agent for this if it is available.
+
+## Assistant Configuration
+
+Before proceeding with this command, you MUST load and respect the assistant's configuration:
+
+**Run the following scripts:**
+```bash
+ASSISTANT=$(node .ai/task-manager/config/scripts/detect-assistant.cjs)
+node .ai/task-manager/config/scripts/read-assistant-config.cjs "$ASSISTANT"
+```
+
+The output above contains your global and project-level configuration rules. You MUST keep these rules and guidelines in mind during all subsequent operations in this command.
+
+---
+
+Think harder and use tools.
+
+Include `.ai/task-manager/config/TASK_MANAGER.md` to understand the plan directory structure and naming conventions.
+
+## Inputs
+- **Plan ID**: `$1` (required)
+- **Optional refinement notes**: Either provided as additional command arguments or in the conversation. Treat them as constraints that must be reflected in the refined plan.
+
+If the plan ID is missing, immediately stop and show an error explaining correct usage.
+
+### Plan Discovery and Validation
+
+Obtain the plan using the plan ID using the following script:
+
+```bash
+# Extract validation results directly from script
+PLAN_FILE=$(node .ai/task-manager/config/scripts/validate-plan-blueprint.cjs $1 planFile)
+```
+
+## Process Checklist
+
+Use your internal Todo tool to track the entire refinement workflow:
+
+- [ ] Load `.ai/task-manager/config/hooks/PRE_PLAN.md`
+- [ ] Stage 1: Baseline Review
+- [ ] Stage 2: Clarification Loop
+- [ ] Stage 3: Refinement Implementation
+- [ ] Review the existing plan end-to-end (frontmatter, clarifications, architecture, risks, etc.)
+- [ ] Surface strengths, contradictions, and potential risks, without updating the plan
+- [ ] Use the "Total Clarification Algorithm" to get the missing clarification from the user
+- [ ] Apply refinements using `.ai/task-manager/config/templates/PLAN_TEMPLATE.md` as the structural baseline
+- [ ] Update the "Plan Clarifications" table with the latest Q&A
+- [ ] Update the plan file ($PLAN_FILE) with the refinements from steps above
+- [ ] Re-run `.ai/task-manager/config/hooks/POST_PLAN.md`
+
+## Stage 1: Baseline Review
+
+1. Capture key metadata (plan title, summary, creation date, related initiatives).
+2. Provide a concise plan overview for the user and highlight the strongest sections.
+
+## Stage 2: Clarification Loop
+
+- Use the "Total Clarification Algorithm" to get the missing clarification from the user
+- After receiving answers, append them to the "Plan Clarifications" section in the plan Markdown using the existing format (table with question/answer pairs).
+- If the user cannot answer, record the unresolved questions along with mitigation notes so downstream assistants know the risk.
+
+### Total Clarification Algorithm
+
+Think harder before interrupting the user—only trigger this loop when you can cite concrete uncertainties.
+
+1. Ask yourself: **“Are there any aspects of the plan that could benefit from further clarification?”** Identify gaps using these lenses:
+    - **Context gaps**: missing background, assumptions, competing priorities.
+    - **Technical gaps**: underspecified architecture, unclear interfaces, missing diagrams.
+    - **Risk gaps**: untracked risks, missing mitigations, hand-wavy success metrics.
+    - **Scope issues**: gold-plating, ambiguous boundaries, requirements that contradict YAGNI.
+2. Document each gap with `{section, issue, severity, proposed fix}` so you can reference it when refining the plan.
+3. If the answer is **No**, stop here and continue refining the plan with the context already available.
+4. If the answer is **Yes**:
+    - Build a clarification packet grouped by theme.
+    - Prefill each question with the most plausible answer so the user can confirm/deny quickly.
+    - Always include an **“Other / open-ended”** option to capture nuances you did not anticipate.
+5. Send the packet, capture the responses (including open-ended notes), update the Plan Clarifications table, then jump back to Step 1 to ensure no new gaps remain.
+
+```mermaid
+flowchart TD
+    A[Inspect current plan] --> B{Need more clarification?}
+    B -- No --> C[End · proceed with refinement]
+    B -- Yes --> D[Collect question set\n• targeted prompts\n• prefilled answers\n• open-ended field]
+    D --> B
+```
+
+## Stage 3: Refinement Implementation
+
+Once you have sufficient context (or have documented the missing context), refine the plan directly in-place:
+
+1. **Maintain Identity**: Keep the existing `id` and directory. Do not create a new plan ID.
+2. **Structure Compliance**: Ensure the plan still follows `.ai/task-manager/config/templates/PLAN_TEMPLATE.md`. Add missing sections if necessary.
+3. **Content Updates**:
+   - Refresh the executive summary to reflect clarifications and new insights.
+   - Update architectural sections, diagrams, and risk mitigations to resolve the identified gaps.
+   - Trim any scope creep that is not explicitly required.
+   - Clearly reference clarifications in the relevant plan sections (e.g., italicized notes that point back to the Q&A table).
+4. **Net-New Sections**: If the plan needs a new subsection (e.g., Decision Log, Data Contracts), add it under `Notes` with a clearly labeled section so it remains discoverable.
+5. **Change Log**: Append a bullet list in the `Notes` section that briefly states what changed in this refinement session (e.g., `- 2025-03-16: Clarified auth flow tokens and updated architecture diagram`).
+6. **Validation Hooks**: Execute `.ai/task-manager/config/hooks/POST_PLAN.md` to ensure the refined plan still meets quality bars.
+
+## Output Requirements
+
+1. Present a concise "Refinement Report" to the user containing:
+   - Snapshot of the updated plan summary (title, summary line, plan path).
+   - Key clarifications added (with links to sections if applicable).
+   - Major improvements and remaining open questions (if any).
+2. Ensure the plan file on disk is fully updated before finishing.
+
+## Structured Output (MANDATORY)
+
+Always end with the standardized summary so orchestrators can chain commands:
+
+```
+---
+
+Plan Refinement Summary:
+- Plan ID: [numeric-id]
+- Plan File: [full-path-to-plan-file]
+```