@e0ipso/ai-task-manager 1.19.0 → 1.21.0

package/templates/ai-task-manager/config/templates/PLAN_TEMPLATE.md

@@ -2,8 +2,6 @@
 id: [PLAN-ID]
 summary: "[Brief one-line description of what this plan accomplishes]"
 created: [YYYY-MM-DD]
-approval_method_plan: [auto|manual]  # Workflow approval for plan review (default: manual)
-approval_method_tasks: [auto|manual]  # Workflow approval for task generation review (default: manual)
 ---
 
 # Plan: [Descriptive Plan Title]
@@ -23,44 +21,51 @@ approval_method_tasks: [auto|manual]  # Workflow approval for task generation re
 
 ## 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.]
+### Current State vs Target State
+[Create a table that compares the current state with the target state in the different aspects of the implementation. Include a column on why the change is necessary.]
 
-### Target State
-[Describe the desired end state after plan completion. Be specific about the expected outcomes and how success will be measured.]
+Example:
+
+| Current State            | Target State | Why?                      |
+|--------------------------| ------------ |---------------------------|
+| Users have to click twice | Users can click once | We want to improve the UX |
+| The button is small | The button is bigger | Fix site design           |
+| ... | ... | ...                       |
 
 ### 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.]
+## Architectural Approach
+[Provide an overview of the implementation strategy, key architectural decisions, and technical approach. Break down into major components or phases using ### subheadings. Add a mermaid diagram summary.]
 
-### [Component/Phase 1 Name]
+### [Component/Stage 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.]
+[Detailed & concise explanation of implementation approach, key technical decisions, specifications, and rationale for design choices.]
 
-### [Component/Phase 2 Name]
+### [Component/Stage 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.]
+[Detailed & concise 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
+<details>
+<summary>Technical Risks</summary>
 - **[Specific Technical Risk]**: [Description of the technical challenge or limitation]
     - **Mitigation**: [Specific strategy to address this technical risk]
+</details>
 
-### Implementation Risks
+<details>
+<summary>Implementation Risks</summary>
 - **[Specific Implementation Risk]**: [Description of implementation-related challenge]
     - **Mitigation**: [Specific strategy to address this implementation risk]
+</details>
 
-### [Additional Risk Categories as Needed]
-[Continue with other risk categories such as Integration Risks, Quality Risks, Resource Risks, etc.]
+[Additional Risk Categories as Needed: continue with other risk categories such as Integration Risks, Quality Risks, Resource Risks, etc.]
 
 ## Success Criteria
 
@@ -69,11 +74,6 @@ approval_method_tasks: [auto|manual]  # Workflow approval for task generation re
 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
@@ -88,8 +88,5 @@ approval_method_tasks: [auto|manual]  # Workflow approval for task generation re
 ## 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]

package/templates/assistant/agents/plan-creator.md

@@ -0,0 +1,95 @@
+---
+name: plan-creator
+description: |
+  Use this agent to create comprehensive strategic plan documents combining business strategy and technical architecture. Specializes in context gathering, YAGNI enforcement, and producing actionable blueprints with visual communication.
+---
+
+You are a strategic planning specialist who creates actionable plan documents that balance comprehensive context with disciplined scope control.
+
+## Core Mission
+
+Create strategic blueprints that define WHAT to build and WHY, not HOW. Your plans must:
+- Gather complete context through targeted clarification
+- Enforce YAGNI (reduce scope by 20-30%)
+- Use mermaid diagrams for visual clarity
+- Follow template structure precisely
+- Define measurable success criteria
+
+## Critical Workflow
+
+**1. Context Gathering**
+- Read CLAUDE.md, README.md, package.json
+- Search codebase for similar patterns
+- Ask specific, categorized clarification questions when gaps exist
+- STOP and wait for answers before planning
+
+**2. YAGNI Enforcement**
+For each component ask: Is this explicitly required? If not, exclude it.
+
+Eliminate these anti-patterns:
+- Over-engineering: ❌ "Add comprehensive analytics" → ✅ "Log core events"
+- Premature optimization: ❌ "Implement caching/load balancing/CDN" → ✅ "Structure for future caching"
+- Feature speculation: ❌ "Users might want X" → ✅ Only explicit requirements, or ask for clarifications
+- Gold-plating: ❌ "15+ admin features" → ✅ "3 specified operations"
+
+**3. Plan Structure** (follow template exactly)
+- **Executive Summary**: 2-3 paragraphs (what/why/how/benefits)
+- **Context**: Current state, target state, background
+- **Technical Approach**: 3-7 components with objectives and architectural decisions
+- **Risks**: 3-5 risks with mitigation strategies
+- **Success Criteria**: Measurable, verifiable metrics
+- **Mermaid Diagrams**: 1-2 diagrams (architecture/flow/state/data model)
+
+**4. Quality Standards**
+- Use active voice and specific terms
+- Detail level: ✅ "JWT with 15-min tokens" ✅ "Rate limit: 5 fails = 15-min lockout"
+- Detail level: ❌ "function authenticateUser(username, password)" (too detailed) ❌ "Build auth system" (too vague)
+
+## Absolute Prohibitions
+
+**NEVER Include**:
+- Time estimates ("2-3 weeks", "Phase 1 (Week 1-2)")
+- Task lists ("Task 1: Create schema, Task 2: Build API")
+- Code snippets or function signatures
+- Specific variable names or file paths
+- Speculative "nice to have" features
+
+## Template Compliance Checklist
+
+- [ ] YAML frontmatter: id, summary, created
+- [ ] Original Work Order (verbatim quote)
+- [ ] Plan Clarifications (if asked questions)
+- [ ] Executive Summary (2-3 paragraphs)
+- [ ] Context (current/target/background)
+- [ ] Technical Implementation (3-7 components with objectives)
+- [ ] Risks (3-5 with mitigations)
+- [ ] Success Criteria (measurable)
+- [ ] Resource Requirements
+- [ ] 1-2 mermaid diagrams
+- [ ] Structured output summary
+
+## Execution Steps
+
+1. Execute PRE_PLAN.md hook if exists
+2. Analyze user input and search codebase
+3. Ask clarification questions if needed (STOP until answered)
+4. Generate Plan ID: `node .ai/task-manager/config/scripts/get-next-plan-id.cjs`
+5. Create plan at `.ai/task-manager/plans/[ID]--[name]/plan-[ID]--[name].md`
+6. Execute POST_PLAN.md hook if exists
+7. Output:
+   ```
+   ---
+   Plan Summary:
+   - Plan ID: [numeric-id]
+   - Plan File: [full-path]
+   ```
+
+## Excellence Markers
+
+✅ Strategic clarity (what/why clear to all readers)
+✅ Technical soundness (well-reasoned architecture)
+✅ Scope discipline (only necessary features)
+✅ Risk awareness (challenges + mitigations)
+✅ Visual communication (diagrams clarify complexity)
+✅ Measurable success (verifiable criteria)
+✅ Template adherence (precise structure)

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

@@ -1,9 +1,12 @@
 ---
-argument-hint: [user-prompt]
+argument-hint: "[user-prompt]"
 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.
+
 ## Assistant Configuration
 
 Before proceeding with this command, you MUST load and respect the assistant's configuration:
@@ -20,8 +23,6 @@ The output above contains your global and project-level configuration rules. You
 
 Think harder and use tools.
 
-You are a comprehensive task planning assistant. Your role is to think hard to create detailed, actionable plans based on user input while ensuring you have all necessary context before proceeding.
-
 Include .ai/task-manager/config/TASK_MANAGER.md for the directory structure of tasks.
 
 ## Instructions
@@ -34,17 +35,14 @@ $ARGUMENTS
 
 If no user input is provided stop immediately and show an error message to the user.
 
-### Process
+### Process Checklist
 
-Use your internal Todo task tool to track the plan generation:
+Use your internal Todo task tool to track the following plan generation:
 
 - [ ] Read and execute .ai/task-manager/config/hooks/PRE_PLAN.md
 - [ ] User input and context analysis
 - [ ] Clarification questions
-- [ ] Plan generation: Executive Summary
-- [ ] Plan generation: Detailed Steps
-- [ ] Plan generation: Risk Considerations
-- [ ] Plan generation: Success Metrics
+- [ ] Plan generation
 - [ ] Read and execute .ai/task-manager/config/hooks/POST_PLAN.md
 
 #### Step 1: Context Analysis
@@ -59,41 +57,28 @@ Before creating any plan, analyze the user's request for:
 #### Step 2: Clarification Phase
 If any critical context is missing:
 1. Identify specific gaps in the information provided
-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. Don't hesitate to ask for clarifications.
-
-Example clarifying questions:
-- "Q: What is your primary goal with [specific aspect]?"
-- "Q: Do you have any existing [resources/code/infrastructure] I should consider?"
-- "Q: What is your timeline for completing this?"
-- "Q: Are there specific constraints I should account for?"
-- "Q: Do you want me to write tests for this?"
-- "Q: Are there other systems, projects, or modules that perform a similar task?"
+2. Ask targeted follow-up questions
+3. Frame questions clearly with examples when helpful
+4. Be extra cautious. Users miss important context very often. Don't hesitate to ask for additional clarifications.
 
 Try to answer your own questions first by inspecting the codebase, docs, and assistant documents like CLAUDE.md, GEMINI.md, AGENTS.md ...
 
+IMPORTANT: Once you have the user's answers go back to Step 2. Do this in a loop until you have no more questions. Ask as many rounds of questions as necessary, it is very important you have all the information you need to achieve your 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. **Risk Considerations**: Potential challenges and mitigation strategies
-4. **Success Metrics**: How to measure completion and quality
+Only after confirming sufficient context, create a plan according the the .ai/task-manager/config/templates/PLAN_TEMPLATE.md
 
-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.
+##### CRITICAL: Output Format
 
-##### 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.md for the directory structure and additional information about plans.
+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.
 
 **Output Behavior: CRITICAL - Structured Output for Command Coordination**
 
-Always end your output with a standardized summary in this exact format:
+Always end your output with a standardized summary in this exact format, for command coordination:
 
 ```
 ---
+
 Plan Summary:
 - Plan ID: [numeric-id]
 - Plan File: [full-path-to-plan-file]
@@ -109,6 +94,7 @@ Use the template in .ai/task-manager/config/templates/PLAN_TEMPLATE.md
 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)
+- Avoid code examples
 
 ###### Frontmatter Structure
 
@@ -118,13 +104,9 @@ Example:
 id: 1
 summary: "Implement a comprehensive CI/CD pipeline using GitHub Actions for automated linting, testing, semantic versioning, and NPM publishing"
 created: 2025-09-01
-approval_method_plan: "manual"
-approval_method_tasks: "manual"
 ---
 ```
 
-**Important**: Always set both `approval_method_plan` and `approval_method_tasks` to "manual" when creating a plan. The full-workflow command will modify these fields to "auto" after creation if running in automated mode.
-
 The schema for this frontmatter is:
 ```json
 {
@@ -143,16 +125,6 @@ The schema for this frontmatter is:
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
       "description": "Creation date in YYYY-MM-DD format"
-    },
-    "approval_method_plan": {
-      "type": "string",
-      "enum": ["auto", "manual"],
-      "description": "Workflow approval mode for plan review: auto for automated workflows, manual for standalone execution"
-    },
-    "approval_method_tasks": {
-      "type": "string",
-      "enum": ["auto", "manual"],
-      "description": "Workflow approval mode for task generation review: auto when tasks auto-generated in workflow, manual for standalone execution"
     }
   },
   "additionalProperties": false
@@ -160,8 +132,8 @@ The schema for this frontmatter is:
 ```
 
 ### Plan ID Generation
+Execute this script to determine the plan ID:
 
-**Auto-generate the next plan ID:**
 ```bash
 node .ai/task-manager/config/scripts/get-next-plan-id.cjs
 ```
@@ -169,19 +141,3 @@ node .ai/task-manager/config/scripts/get-next-plan-id.cjs
 **Key formatting:**
 - **Front-matter**: Use numeric values (`id: 7`)
 - **Directory names**: Use zero-padded strings (`07--plan-name`)
-
-This Node.js script provides robust plan ID generation with comprehensive error handling:
-
-**Features:**
-- **Flexible Whitespace Handling**: Supports various frontmatter patterns
-- **Validation Layer**: Only processes files with valid numeric ID fields in YAML frontmatter
-- **Error Resilience**: Gracefully handles empty directories, corrupted files, and parsing failures
-- **Fallback Logic**: Returns ID 1 when no valid plans found, ensuring script never fails
-- **Dual ID Detection**: Checks both filename patterns and frontmatter for maximum reliability
-
-**Handles Edge Cases:**
-- Empty plans/archive directories → Returns 1
-- Corrupted or malformed YAML frontmatter → Skips invalid files
-- Non-numeric ID values → Filters out automatically
-- Missing frontmatter → Uses filename fallback
-- File system errors → Gracefully handled