@e0ipso/ai-task-manager 1.36.1 → 1.38.0

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

@@ -1,348 +0,0 @@
----
-argument-hint: "[planId]"
-description: Generate tasks to implement the plan with the provided ID.
----
-
-# Comprehensive Task List Creation
-
----
-
-## Find the AI Task Manager root
-
-```bash
-if [ ! -f /tmp/find-ai-task-manager-root.js ]; then
-  cat << 'EOF' > /tmp/find-ai-task-manager-root.js
-const fs = require('fs');
-const path = require('path');
-
-const findRoot = (currentDir) => {
-  const taskManagerPath = path.join(currentDir, '.ai/task-manager');
-  const metadataPath = path.join(taskManagerPath, '.init-metadata.json');
-
-  try {
-    if (fs.existsSync(metadataPath) && JSON.parse(fs.readFileSync(metadataPath, 'utf8')).version) {
-      console.log(path.resolve(taskManagerPath));
-      process.exit(0);
-    }
-  } catch (e) {
-    // Continue searching
-  }
-
-  const parentDir = path.dirname(currentDir);
-  if (parentDir.length < currentDir.length) {
-    findRoot(parentDir);
-  } else {
-    process.exit(1);
-  }
-};
-
-findRoot(process.cwd());
-EOF
-fi
-
-root=$(node /tmp/find-ai-task-manager-root.js)
-
-if [ -z "$root" ]; then
-    echo "Error: Could not find task manager root directory (.ai/task-manager)"
-    exit 1
-fi
-```
-
-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 `$root/.ai/task-manager/config/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 $root/.ai/task-manager/config/hooks/POST_TASK_GENERATION_ALL.md
-
-### Input
-
-- A plan document. Extract it with the following command.
-
-```bash
-# Extract validation results directly from script
-plan_file=$(node $root/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.
-
-### 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 $root/.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 $root/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 $root/.ai/task-manager/config/hooks/POST_TASK_GENERATION_ALL.md
-
-### Output Requirements
-
-**Output Behavior:**
-
-Provide a concise completion message with task count and location:
-- Example: "Task generation complete. Created [count] tasks in `$root/.ai/task-manager/plans/[plan-id]--[name]/tasks/`"
-
-**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.

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

@@ -1,172 +0,0 @@
-<!-- Based on refine-plan.md — keep in sync with changes to the original. -->
----
-argument-hint: "[planId]"
-description: Review and refine a plan without user interaction, resolving ambiguities autonomously.
----
-# Plan Review and Refinement (Autonomous Mode)
-
-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, resolve any missing information
-autonomously, and update the plan with the refinements. Use the plan-creator sub-agent for this if it is available.
-
-**AUTONOMOUS MODE**: This command runs without user interaction. You must resolve all ambiguities by inspecting the
-codebase, documentation, and project context. Do NOT ask the user any questions or wait for user input at any point.
-
----
-
-Use tools for the plan refinement. You are encouraged to write your own specialized tools to research, analyze, and
-debug any plan refinement. You are not restricted to the stack of the current project to create your own specialized
-tools.
-
-## Find the AI Task Manager root
-
-```bash
-if [ ! -f /tmp/find-ai-task-manager-root.js ]; then
-  cat << 'EOF' > /tmp/find-ai-task-manager-root.js
-const fs = require('fs');
-const path = require('path');
-
-const findRoot = (currentDir) => {
-  const taskManagerPath = path.join(currentDir, '.ai/task-manager');
-  const metadataPath = path.join(taskManagerPath, '.init-metadata.json');
-
-  try {
-    if (fs.existsSync(metadataPath) && JSON.parse(fs.readFileSync(metadataPath, 'utf8')).version) {
-      console.log(path.resolve(taskManagerPath));
-      process.exit(0);
-    }
-  } catch (e) {
-    // Continue searching
-  }
-
-  const parentDir = path.dirname(currentDir);
-  if (parentDir.length < currentDir.length) {
-    findRoot(parentDir);
-  } else {
-    process.exit(1);
-  }
-};
-
-findRoot(process.cwd());
-EOF
-fi
-
-root=$(node /tmp/find-ai-task-manager-root.js)
-
-if [ -z "$root" ]; then
-    echo "Error: Could not find task manager root directory (.ai/task-manager)"
-    exit 1
-fi
-```
-
-Include `$root/.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:
-
-```bash
-# Extract validation results directly from script
-plan_file=$(node $root/config/scripts/validate-plan-blueprint.cjs $1 planFile)
-```
-
-## Process Checklist
-
-Use your internal Todo tool to track the entire refinement workflow:
-
-- [ ] Load `$root/.ai/task-manager/config/hooks/PRE_PLAN.md`
-- [ ] Stage 1: Baseline Review
-- [ ] Stage 2: Autonomous Clarification
-- [ ] 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 "Autonomous Clarification Algorithm" to resolve gaps via codebase inspection
-- [ ] Apply refinements using `$root/.ai/task-manager/config/templates/PLAN_TEMPLATE.md` as the structural baseline
-- [ ] Update the "Plan Clarifications" table with findings and assumptions
-- [ ] Update the plan file (stored in `plan_file`) with the refinements from steps above
-- [ ] Re-run `$root/.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: Autonomous Clarification
-
-- Use the "Autonomous Clarification Algorithm" below to resolve gaps without user input
-- Record findings in the "Plan Clarifications" section using the existing format (table with question/answer pairs), marking the source as "auto-resolved" or "assumption"
-- For truly unresolvable questions, record them as unresolved with mitigation notes so downstream assistants know the risk
-
-### Autonomous Clarification Algorithm
-
-Think harder before flagging gaps—only document concrete uncertainties you can cite.
-
-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. For each gap, attempt to resolve it by:
-    - Inspecting the codebase, configuration files, and documentation
-    - Analyzing existing patterns and conventions in the project
-    - Reviewing assistant documents (CLAUDE.md, GEMINI.md, AGENTS.md) and README files
-    - Making reasonable assumptions based on common practices and project context
-4. Record all resolutions and assumptions in the Plan Clarifications table with clear rationale. Mark each entry's source as either "auto-resolved" (confirmed via codebase) or "assumption" (best-effort guess).
-5. If no gaps remain (or all have been resolved/documented), proceed directly to Stage 3.
-
-CRITICAL: Do NOT ask the user any questions. Do NOT wait for user input. Resolve all ambiguity through codebase analysis and documented assumptions.
-
-```mermaid
-flowchart TD
-    A[Inspect current plan] --> B{Need more clarification?}
-    B -- No --> C[End · proceed with refinement]
-    B -- Yes --> D[Attempt to resolve via codebase inspection]
-    D --> E{Resolved?}
-    E -- Yes --> F[Record as auto-resolved]
-    E -- No --> G[Record assumption with rationale]
-    F --> B
-    G --> 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 `$root/.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 `$root/.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]
-```

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

@@ -1,163 +0,0 @@
----
-argument-hint: "[planId]"
-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.
-
----
-
-Use tools for the plan refinement. You are encouraged to write your own specialized tools to research, analyze, and
-debug any plan refinement. You are not restricted to the stack of the current project to create your own specialized
-tools.
-
-## Find the AI Task Manager root
-
-```bash
-if [ ! -f /tmp/find-ai-task-manager-root.js ]; then
-  cat << 'EOF' > /tmp/find-ai-task-manager-root.js
-const fs = require('fs');
-const path = require('path');
-
-const findRoot = (currentDir) => {
-  const taskManagerPath = path.join(currentDir, '.ai/task-manager');
-  const metadataPath = path.join(taskManagerPath, '.init-metadata.json');
-
-  try {
-    if (fs.existsSync(metadataPath) && JSON.parse(fs.readFileSync(metadataPath, 'utf8')).version) {
-      console.log(path.resolve(taskManagerPath));
-      process.exit(0);
-    }
-  } catch (e) {
-    // Continue searching
-  }
-
-  const parentDir = path.dirname(currentDir);
-  if (parentDir.length < currentDir.length) {
-    findRoot(parentDir);
-  } else {
-    process.exit(1);
-  }
-};
-
-findRoot(process.cwd());
-EOF
-fi
-
-root=$(node /tmp/find-ai-task-manager-root.js)
-
-if [ -z "$root" ]; then
-    echo "Error: Could not find task manager root directory (.ai/task-manager)"
-    exit 1
-fi
-```
-
-Include `$root/.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:
-
-```bash
-# Extract validation results directly from script
-plan_file=$(node $root/config/scripts/validate-plan-blueprint.cjs $1 planFile)
-```
-
-## Process Checklist
-
-Use your internal Todo tool to track the entire refinement workflow:
-
-- [ ] Load `$root/.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 `$root/.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 (stored in `plan_file`) with the refinements from steps above
-- [ ] Re-run `$root/.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. **STOP AND ASK**: Present the clarification packet to the user. **You must halt execution here and await user input.** Do not simulate the user's response. Do not proceed to Stage 3 until you have received explicit answers.
-
-```mermaid
-flowchart TD
-    A[Inspect current plan] --> B{Need more clarification?}
-    B -- No --> C[End · proceed with refinement]
-    B -- Yes --> D[Construct Question Packet]
-    D --> E[STOP · Ask User]
-    E --> F[Receive Input]
-    F --> 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 `$root/.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 `$root/.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]
-```