feat: add PRE_TASK_EXECUTION hook (#16)

e0ipso · web-flow · commit e86a386e2838 · 2026-03-27T07:17:29.000+01:00
## Summary - Adds `PRE_TASK_EXECUTION.md` hook template (ships empty) for pre-flight validation before individual task dispatch - Wires the hook into `execute-blueprint.md` and `full-workflow.md` as a new step between agent selection and parallel execution - Documents the hook across six Jekyll docs pages and updates AGENTS.md Closes #15 ## Test plan - [x] `npm test` passes (189 tests) - [x] `npm start init --assistants claude` installs `PRE_TASK_EXECUTION.md` to `.ai/task-manager/config/hooks/` - [x] `execute-blueprint.md` references the hook between steps 2 and 4 - [x] Hook count updated from "eight" to "nine" in all docs
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
@@ -5,8 +5,6 @@ ARG TZ=Europe/Madrid
 ENV TZ="$TZ"
 
 ARG CLAUDE_CODE_VERSION=latest
-ARG GEMINI_VERSION=latest
-ARG CODEX_VERSION=latest
 
 # Install basic development tools and iptables/ipset
 RUN apt-get update && apt-get install -y --no-install-recommends \
@@ -49,8 +47,7 @@ RUN mkdir -p /worktrees \
   && chown -R $USERNAME /worktrees
 
 # Pre-create directories that will be needed for bind mounts
-RUN mkdir -p /home/$USERNAME/.claude/debug /home/$USERNAME/.gemini /home/$USERNAME/.codex \
-  && chown -R $USERNAME:$USERNAME /home/$USERNAME/.claude /home/$USERNAME/.gemini /home/$USERNAME/.codex
+RUN mkdir -p /home/$USERNAME/.claude/debug && chown -R $USERNAME:$USERNAME /home/$USERNAME/.claude
 
 # Set `DEVCONTAINER` environment variable to help with orientation
 ENV DEVCONTAINER=true
@@ -91,7 +88,5 @@ RUN sh -c "$(wget -O- https://github.com/deluan/zsh-in-docker/releases/download/
   -a "export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
   -x
 
-# Install Claude & Gemini
+# Install Claude
 RUN npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION:-latest}
-RUN npm install -g @google/gemini-cli@${GEMINI_VERSION:-latest}
-RUN npm install -g @openai/codex@${CODEX_VERSION:-latest}
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -6,7 +6,6 @@
       "BASE_IMAGE": "node:22",
       "TZ": "${localEnv:TZ:Europe/Madrid}",
       "CLAUDE_CODE_VERSION": "latest",
-      "GEMINI_VERSION": "latest",
       "GIT_DELTA_VERSION": "0.18.2",
       "ZSH_IN_DOCKER_VERSION": "1.2.0"
     }
@@ -56,14 +55,10 @@
     "source=claude-code-bashhistory-${devcontainerId},target=/commandhistory,type=volume",
     "source=${localWorkspaceFolder}/../worktrees,target=/worktrees,type=bind,consistency=cached",
     "source=${localEnv:HOME}/.claude/CLAUDE.md,target=/home/node/.claude/CLAUDE.md,type=bind,consistency=cached",
-    "source=${localEnv:HOME}/.gemini/GEMINI.md,target=/home/node/.gemini/GEMINI.md,type=bind,consistency=cached",
-    "source=${localEnv:HOME}/.codex/AGENTS.md,target=/home/node/.codex/AGENTS.md,type=bind,consistency=cached",
     "source=${localEnv:HOME}/.claude.json,target=/home/node/.claude.json,type=bind,consistency=cached",
     "source=${localEnv:HOME}/.claude/settings.json,target=/home/node/.claude/settings.json,type=bind,consistency=cached",
     "source=${localEnv:HOME}/.claude/skills,target=/home/node/.claude/skills,type=bind,consistency=cached",
     "source=${localEnv:HOME}/.claude/hooks,target=/home/node/.claude/hooks,type=bind,consistency=cached",
-    "source=${localEnv:HOME}/.codex/config.toml,target=/home/node/.codex/config.toml,type=bind,consistency=cached",
-    "source=${localEnv:HOME}/.codex/prompts,target=/home/node/.codex/prompts,type=bind,consistency=cached",
     "source=${localEnv:HOME}/.config/gh/hosts.yml,target=/home/node/.config/gh/hosts.yml,type=bind,consistency=cached",
     "source=${localEnv:HOME}/.gitconfig,target=/home/node/.gitconfig,type=bind,consistency=cached",
     "source=${localEnv:SSH_AUTH_SOCK},target=/ssh-agent,type=bind"
@@ -76,7 +71,7 @@
   },
   "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=delegated",
   "workspaceFolder": "/workspace",
-  "postCreateCommand": "sudo chown -R node:node /home/node/.claude /home/node/.gemini /home/node/.codex || true",
-  "postStartCommand": "npm update -g @anthropic-ai/claude-code && npm update -g @google/gemini-cli && npm update -g @openai/codex",
+  "postCreateCommand": "sudo chown -R node:node /home/node/.claude || true",
+  "postStartCommand": "npm update -g @anthropic-ai/claude-code",
   "waitFor": "postStartCommand"
 }
diff --git a/AGENTS.md b/AGENTS.md
@@ -292,7 +292,7 @@ project/
 │   ├── config/
 │   │   ├── TASK_MANAGER.md        # Project context
 │   │   ├── scripts/               # ID generation (get-next-plan-id.cjs, etc)
-│   │   ├── hooks/                 # Validation scripts (PRE_PLAN.md, POST_PLAN.md, etc)
+│   │   ├── hooks/                 # Lifecycle hooks (PRE_PLAN, POST_PLAN, PRE_PHASE, POST_PHASE, PRE_TASK_ASSIGNMENT, PRE_TASK_EXECUTION, POST_TASK_GENERATION_ALL, POST_EXECUTION, POST_ERROR_DETECTION)
 │   │   └── templates/             # Customizable (PLAN_TEMPLATE.md, TASK_TEMPLATE.md)
 └── .<assistant>/...               # See Assistant-Specific Differences table below
 ```
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -233,12 +233,13 @@ AI Task Manager is built for customization through three extension points:
 
 ### 1. Hooks System
 
-Eight lifecycle hooks inject custom logic:
+Nine lifecycle hooks inject custom logic:
 
 ```
 PRE_PLAN → Planning guidance
 PRE_PHASE → Phase preparation
 PRE_TASK_ASSIGNMENT → Agent selection
+PRE_TASK_EXECUTION → Task pre-flight validation
 POST_PLAN → Plan validation
 POST_TASK_GENERATION_ALL → Task refinement
 POST_PHASE → Quality gates
diff --git a/docs/comparison.md b/docs/comparison.md
@@ -317,7 +317,7 @@ All formats are automatically generated from a single source during initializati
 ### Can I customize the workflow?
 
 **Yes, extensively.** Customize:
-- **Hooks**: Eight lifecycle hooks for validation gates and custom logic
+- **Hooks**: Nine lifecycle hooks for validation gates and custom logic
 - **Templates**: Five templates for plans, tasks, blueprints, and summaries
 - **Configuration**: TASK_MANAGER.md and POST_PHASE.md for project context
 
diff --git a/docs/customization-extension.md b/docs/customization-extension.md
@@ -30,14 +30,15 @@ In this section:
 ## Customization Points
 
 ### Hooks System
-Eight lifecycle hooks inject custom logic at key points in the workflow. All hooks are Markdown files in `.ai/task-manager/config/hooks/`:
+Nine lifecycle hooks inject custom logic at key points in the workflow. All hooks are Markdown files in `.ai/task-manager/config/hooks/`:
 
 - **PRE_PLAN**: Pre-planning guidance
 - **PRE_PHASE**: Phase preparation logic
 - **POST_PHASE**: Validation gates after each phase
 - **POST_PLAN**: Plan validation
 - **POST_TASK_GENERATION_ALL**: Task complexity analysis and blueprint generation
 - **PRE_TASK_ASSIGNMENT**: Agent selection based on skills
+- **PRE_TASK_EXECUTION**: Pre-flight validation before each task dispatch
 - **POST_ERROR_DETECTION**: Error handling procedures
 - **POST_EXECUTION**: Final validation before execution summary and archival
 
diff --git a/docs/customization.md b/docs/customization.md
@@ -116,7 +116,17 @@ The hook system injects custom logic at seven key points in the workflow lifecyc
 - Map skills to specific agent configurations
 - Add fallback strategies for unmatched skills
 
-#### 7. POST_ERROR_DETECTION Hook
+#### 7. PRE_TASK_EXECUTION Hook
+
+**File**: `PRE_TASK_EXECUTION.md`
+**Purpose**: Pre-flight validation before each individual task is dispatched to an agent. Ships empty — add your own checks.
+
+**Common Customizations**:
+- Add project-specific pre-flight checks (e.g., verify required services are running)
+- Configure which checks are hard failures vs warnings
+- Add environment validation (e.g., required env vars are set)
+
+#### 8. POST_ERROR_DETECTION Hook
 
 **File**: `POST_ERROR_DETECTION.md`
 **Purpose**: Error handling procedures for task execution failures
diff --git a/docs/features.md b/docs/features.md
@@ -20,7 +20,7 @@ AI Task Manager provides comprehensive tools for structured AI-assisted developm
 - **Template Customization**: Modify plan and task templates to include project-specific sections, acceptance criteria, and workflow steps
 
 ### Extensibility Framework
-- **Hook System**: Eight lifecycle hooks for injecting custom logic at key workflow points (PRE_PLAN, PRE_PHASE, POST_PHASE, POST_PLAN, POST_TASK_GENERATION_ALL, PRE_TASK_ASSIGNMENT, POST_ERROR_DETECTION, POST_EXECUTION)
+- **Hook System**: Nine lifecycle hooks for injecting custom logic at key workflow points (PRE_PLAN, PRE_PHASE, POST_PHASE, POST_PLAN, POST_TASK_GENERATION_ALL, PRE_TASK_ASSIGNMENT, PRE_TASK_EXECUTION, POST_ERROR_DETECTION, POST_EXECUTION)
 - **Custom Validation Gates**: Add project-specific quality checks, security scans, performance tests, or documentation requirements
 - **Integration Points**: Connect with existing CI/CD pipelines, testing frameworks, or development tools
 - **Workflow Patterns**: Create and share reusable workflow patterns for common project types
diff --git a/docs/installation.md b/docs/installation.md
@@ -91,6 +91,7 @@ project-root/
 │       │   │   ├── POST_PLAN.md
 │       │   │   ├── POST_TASK_GENERATION_ALL.md
 │       │   │   ├── PRE_TASK_ASSIGNMENT.md
+│       │   │   ├── PRE_TASK_EXECUTION.md
 │       │   │   ├── POST_ERROR_DETECTION.md
 │       │   │   └── POST_EXECUTION.md
 │       │   ├── templates/         # Customizable templates
diff --git a/templates/ai-task-manager/config/hooks/POST_ERROR_DETECTION.md b/templates/ai-task-manager/config/hooks/POST_ERROR_DETECTION.md
@@ -1,7 +1,5 @@
 # POST_ERROR_DETECTION Hook
 
-This hook provides error handling procedures for task execution failures and validation gate failures.
-
 ## Task Execution Error Handling
 
 If task execution fails:
@@ -45,4 +43,4 @@ 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
+6. If errors persist, escalate to the user
diff --git a/templates/ai-task-manager/config/hooks/POST_PLAN.md b/templates/ai-task-manager/config/hooks/POST_PLAN.md
@@ -1,3 +1,5 @@
 # POST_PLAN Hook
 
-This hook provides validation and update procedures to execute after plan creation, ensuring comprehensive context analysis and proper plan document structuring with dependency visualization.
+Ensure the plan includes a _Self Validation_ section describing the steps the LLM will take to validate that the plan was completed successfully.
+
+Also, answer the question _Does this plan need to update the documentation, or the AGENTS.md_.
diff --git a/templates/ai-task-manager/config/hooks/PRE_PHASE.md b/templates/ai-task-manager/config/hooks/PRE_PHASE.md
@@ -1,7 +1,5 @@
 # PRE_PHASE Hook
 
-This hook contains the phase preparation logic that should be executed before starting any phase execution.
-
 ## Phase Pre-Execution
 
 ### Feature Branch Creation
@@ -40,4 +38,4 @@ node $root/config/scripts/create-feature-branch.cjs $1
         done
         ```
     - Confirm no tasks are marked "needs-clarification"
-    - If any phases are marked as completed, verify they are actually completed and continue from the next phase.
+    - If any phases are marked as completed, verify they are actually completed and continue from the next phase.
diff --git a/templates/ai-task-manager/config/hooks/PRE_PLAN.md b/templates/ai-task-manager/config/hooks/PRE_PLAN.md
@@ -1,7 +1,5 @@
 # PRE_PLAN Hook
 
-This hook provides pre-planning guidance to ensure scope control, simplicity principles, and proper validation requirements are established before comprehensive plan creation.
-
 ## Scope Control Guidelines
 
 **Critical: Implement ONLY what is explicitly requested**
diff --git a/templates/ai-task-manager/config/hooks/PRE_TASK_ASSIGNMENT.md b/templates/ai-task-manager/config/hooks/PRE_TASK_ASSIGNMENT.md
@@ -1,7 +1,5 @@
 # PRE_TASK_ASSIGNMENT Hook
 
-This hook executes before task assignment to determine the most appropriate agent for each task based on skill requirements and available sub-agents.
-
 ## Agent Selection and Task Assignment
 
 - For each task in the current phase:
diff --git a/templates/ai-task-manager/config/hooks/PRE_TASK_EXECUTION.md b/templates/ai-task-manager/config/hooks/PRE_TASK_EXECUTION.md
@@ -0,0 +1 @@
+# PRE_TASK_EXECUTION Hook
diff --git a/templates/assistant/commands/tasks/execute-blueprint.md b/templates/assistant/commands/tasks/execute-blueprint.md
@@ -142,6 +142,9 @@ Read and execute $root/.ai/task-manager/config/hooks/PRE_TASK_ASSIGNMENT.md
 
 3. **Parallel Execution**
     - Deploy all selected agents simultaneously using your internal Task tool
+    - **Each agent MUST perform these steps in order:**
+      1. Read and execute `$root/.ai/task-manager/config/hooks/PRE_TASK_EXECUTION.md` before starting any implementation work
+      2. Execute the task according to its requirements
     - Monitor execution progress for each task
     - Capture outputs and artifacts from each agent
     - Update task status in real-time
diff --git a/templates/assistant/commands/tasks/execute-task.md b/templates/assistant/commands/tasks/execute-task.md
@@ -53,7 +53,7 @@ Use your internal Todo task tool to track the execution of all parts of the task
 
 - [ ] Validate task: file, status (including needs-clarification), and dependencies.
 - [ ] Set task status to in-progress.
-- [ ] Execute the task.
+- [ ] Execute the task (agent runs PRE_TASK_EXECUTION hook, then implements).
 - [ ] Update task status to completed or failed.
 - [ ] Document noteworthy events (if any).
 - [ ] Emit structured output for orchestrator.
@@ -253,10 +253,13 @@ Deploy the task using the Task tool with full context:
 - Required skills: `$task_skills`
 - Agent selection: Based on skills analysis or general-purpose agent
 
-Read the complete task file and execute according to its requirements. The task includes:
-- Objective and acceptance criteria
-- Technical requirements and implementation notes
-- Input dependencies and expected output artifacts
+**The agent MUST perform these steps in order:**
+
+1. **Pre-flight validation**: Read and execute `$root/.ai/task-manager/config/hooks/PRE_TASK_EXECUTION.md` before starting any implementation work.
+2. **Execute the task**: Read the complete task file and implement according to its requirements, including:
+   - Objective and acceptance criteria
+   - Technical requirements and implementation notes
+   - Input dependencies and expected output artifacts
 
 ### 8. Post-Execution Status Management
 
diff --git a/templates/assistant/commands/tasks/full-workflow.md b/templates/assistant/commands/tasks/full-workflow.md
@@ -83,6 +83,9 @@ Use your internal Todo task tool to track the workflow execution:
 
 Execute the following plan creation process:
 
+For this step, think hard to create detailed, actionable plans based on the user input while
+ensuring you have all necessary context before proceeding. Use the plan-creator sub-agent for this if it is available.
+
 Use tools for the planning. You are encouraged to write your own specialized tools to research, analyze, and debug
 any work order from the user. You are not restricted to the stack of the current project to create your own
 specialized tools.
@@ -747,6 +750,9 @@ Read and execute $root/.ai/task-manager/config/hooks/PRE_TASK_ASSIGNMENT.md
 
 3. **Parallel Execution**
     - Deploy all selected agents simultaneously using your internal Task tool
+    - **Each agent MUST perform these steps in order:**
+      1. Read and execute `$root/.ai/task-manager/config/hooks/PRE_TASK_EXECUTION.md` before starting any implementation work
+      2. Execute the task according to its requirements
     - Monitor execution progress for each task
     - Capture outputs and artifacts from each agent
     - Update task status in real-time
