From 107ab6d5af1a8fba1738da92cdfd07e8b38cd65b Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 6 Mar 2026 17:48:33 +0000 Subject: [PATCH 1/2] docs: align execute-task with execute-blueprint refinements Bring the single-task executor up to par with execute-blueprint for scripting/orchestration contexts: add needs-clarification status gate, valid status transitions reference, post-task lint validation, post- execution test checks, structured machine-parseable output block, and noteworthy events documentation guidance. https://claude.ai/code/session_01MbvXrSawdTqfxeevbqbsqV --- .../assistant/commands/tasks/execute-task.md | 113 +++++++++++++++--- 1 file changed, 99 insertions(+), 14 deletions(-) diff --git a/templates/assistant/commands/tasks/execute-task.md b/templates/assistant/commands/tasks/execute-task.md index 2c19c973..4e4d96d4 100644 --- a/templates/assistant/commands/tasks/execute-task.md +++ b/templates/assistant/commands/tasks/execute-task.md @@ -49,22 +49,24 @@ if [ -z "$root" ]; then fi ``` -Use your internal Todo task tool to track the execution of all parts of the task, and the final update of noteworthy items during execution. Example: +Use your internal Todo task tool to track the execution of all parts of the task. Example: -- [ ] Validate task: file, status, and dependencies. -- [ ] Select the most appropriate sub-agent. +- [ ] Validate task: file, status (including needs-clarification), and dependencies. - [ ] Set task status to in-progress. -- [ ] Delegate task implementation to the sub-agent. +- [ ] Execute the task. +- [ ] Run post-task validation (lint check). +- [ ] Run post-execution checks (tests for affected code). - [ ] Update task status to completed or failed. -- [ ] Update the task file with noteworthy events during execution. +- [ ] Document noteworthy events (if any). +- [ ] Emit structured output for orchestrator. ## Critical Rules 1. **Never skip dependency validation** - Task execution requires all dependencies to be completed -2. **Validate task status** - Never execute tasks that are already completed or in-progress +2. **Validate task status** - Never execute tasks that are already completed, in-progress, or needs-clarification 3. **Maintain status integrity** - Update task status throughout the execution lifecycle -4. **Use appropriate agents** - Match task skills to available sub-agents -5. **Document execution** - Record all outcomes and issues encountered +4. **Document execution** - Record all outcomes and issues encountered +5. **Provide structured output** - Always emit the structured result block for orchestrator parsing ## Input Requirements - Plan ID: $1 (required) @@ -162,6 +164,11 @@ case "$current_status" in echo "Wait for current execution to complete or check for stale processes" exit 1 ;; + "needs-clarification") + echo "Error: Task ${task_id} is marked as 'needs-clarification'" + echo "Resolve clarification questions in the task file before execution" + exit 1 + ;; "pending"|"failed"|"") echo "Task status allows execution - proceeding..." ;; @@ -171,6 +178,17 @@ case "$current_status" in esac ``` +#### Valid Status Transitions + +Reference for orchestrators and execution flow: + +- `pending` → `in-progress` (execution starts) +- `in-progress` → `completed` (successful execution) +- `in-progress` → `failed` (execution error) +- `failed` → `in-progress` (retry attempt) +- `pending` → `needs-clarification` (set externally by orchestrator or reviewer) +- `needs-clarification` → `pending` (clarification resolved, set externally) + ### 4. Dependency Validation Use the dependency checking script to validate all dependencies: @@ -268,15 +286,80 @@ awk ' mv "$temp_file" "$task_file" -echo "✓ Task ${task_id} completed successfully" -echo "" -echo "You can now execute dependent tasks or continue with the full blueprint execution." +echo "✓ Task ${task_id} status updated to completed" +``` + +### 9. Post-Task Validation + +After updating status to completed, run validation to catch issues early. + +**Lint Check** (if configured): + +Verify that the code changes introduced by this task pass linting. If a linter is configured for the project, run it now. If linting fails: +1. Attempt to auto-fix with the project's lint fix command +2. If auto-fix succeeds, continue +3. If auto-fix fails, revert task status to `failed`, document the lint errors in the task file under "Noteworthy Events", and exit with error + +**Note**: Do NOT create commits. The external orchestrator is responsible for commit management. + +### 10. Post-Execution Checks + +Perform targeted validation for the completed task: + +- [ ] Verify the task file frontmatter shows `status: "completed"` +- [ ] If the task's acceptance criteria reference tests, run the relevant test suite and verify affected tests pass +- [ ] If linting was not already validated in Post-Task Validation, run it now + +**Important**: Unlike execute-blueprint, do NOT check "all tasks completed" or run documentation validation. These are plan-level concerns managed by the orchestrator. + +If any check fails, revert the task status to `failed` using the POST_ERROR_DETECTION hook procedure, document the failure, and exit with a non-zero status. + +### 11. Noteworthy Events Documentation + +After task execution (whether successful or failed), append a "Noteworthy Events" section to the task file body if any of the following occurred: + +- **Unexpected decisions**: Deviations from the implementation notes or acceptance criteria approach +- **Dependency issues**: Problems with input artifacts from prerequisite tasks +- **Environment issues**: Build tool problems, missing dependencies, version conflicts +- **Scope observations**: Discovery that the task is larger/smaller than expected, or that it overlaps with another task +- **Test findings**: Tests that revealed unexpected behavior or required modification + +Append to the end of the task file: + +```markdown +## Noteworthy Events +- [YYYY-MM-DD] [Event description with sufficient context for the orchestrator] ``` +If no noteworthy events occurred, do not add the section. + ## Error Handling Read and execute $root/.ai/task-manager/config/hooks/POST_ERROR_DETECTION.md +On any error, ensure you still emit the structured output block (see Output Requirements) with `Status: failed` and `Exit Code: 1`. + +## Output Requirements + +**CRITICAL - Structured Output for Orchestrator Coordination:** + +Always end your output with a standardized summary in this exact format: + +``` +--- +Task Execution Result: +- Plan ID: [plan-id] +- Task ID: [task-id] +- Task Name: [task filename without extension] +- Status: [completed|failed] +- Exit Code: [0 for success, 1 for failure] +- Lint Check: [passed|failed|skipped] +- Test Check: [passed|failed|skipped] +- Noteworthy Events: [brief summary or "None"] +``` + +This structured output enables automated orchestration pipelines to parse results and determine next steps. It MUST be included regardless of success or failure. + ## Usage Examples ```bash @@ -292,11 +375,13 @@ Read and execute $root/.ai/task-manager/config/hooks/POST_ERROR_DETECTION.md ## Integration Notes -This command integrates with the existing task management system by: +This command is designed for scripting contexts where an external orchestrator manages task sequencing, commits, feature branches, and plan archival. It integrates with the task management system by: - Using established plan and task location patterns - Leveraging the dependency checking script for validation -- Following status management conventions +- Following status management conventions (see Valid Status Transitions) +- Providing structured machine-parseable output for orchestrator pipelines +- Running post-task validation (lint, tests) to catch issues before the orchestrator proceeds - Maintaining compatibility with execute-blueprint workflows - Preserving task isolation and dependency order -The command complements execute-blueprint by providing granular task control while maintaining the same validation and execution standards. +The command complements execute-blueprint by providing granular single-task control while maintaining the same validation standards. From 66ed16367af90d6d395a4491b3cdf46c8278c655 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 6 Mar 2026 18:14:18 +0000 Subject: [PATCH 2/2] docs: address PR feedback on execute-task command Remove post-task validation and post-execution checks (orchestrator's responsibility). Simplify structured output to Plan ID, Task ID, and Exit Code. Remove prescriptive noteworthy events examples. Add linting and test execution to integration notes as orchestrator responsibilities. https://claude.ai/code/session_01MbvXrSawdTqfxeevbqbsqV --- .../assistant/commands/tasks/execute-task.md | 47 ++----------------- 1 file changed, 4 insertions(+), 43 deletions(-) diff --git a/templates/assistant/commands/tasks/execute-task.md b/templates/assistant/commands/tasks/execute-task.md index 4e4d96d4..ecb81a69 100644 --- a/templates/assistant/commands/tasks/execute-task.md +++ b/templates/assistant/commands/tasks/execute-task.md @@ -54,8 +54,6 @@ 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. -- [ ] Run post-task validation (lint check). -- [ ] Run post-execution checks (tests for affected code). - [ ] Update task status to completed or failed. - [ ] Document noteworthy events (if any). - [ ] Emit structured output for orchestrator. @@ -289,40 +287,9 @@ mv "$temp_file" "$task_file" echo "✓ Task ${task_id} status updated to completed" ``` -### 9. Post-Task Validation +### 9. Noteworthy Events Documentation -After updating status to completed, run validation to catch issues early. - -**Lint Check** (if configured): - -Verify that the code changes introduced by this task pass linting. If a linter is configured for the project, run it now. If linting fails: -1. Attempt to auto-fix with the project's lint fix command -2. If auto-fix succeeds, continue -3. If auto-fix fails, revert task status to `failed`, document the lint errors in the task file under "Noteworthy Events", and exit with error - -**Note**: Do NOT create commits. The external orchestrator is responsible for commit management. - -### 10. Post-Execution Checks - -Perform targeted validation for the completed task: - -- [ ] Verify the task file frontmatter shows `status: "completed"` -- [ ] If the task's acceptance criteria reference tests, run the relevant test suite and verify affected tests pass -- [ ] If linting was not already validated in Post-Task Validation, run it now - -**Important**: Unlike execute-blueprint, do NOT check "all tasks completed" or run documentation validation. These are plan-level concerns managed by the orchestrator. - -If any check fails, revert the task status to `failed` using the POST_ERROR_DETECTION hook procedure, document the failure, and exit with a non-zero status. - -### 11. Noteworthy Events Documentation - -After task execution (whether successful or failed), append a "Noteworthy Events" section to the task file body if any of the following occurred: - -- **Unexpected decisions**: Deviations from the implementation notes or acceptance criteria approach -- **Dependency issues**: Problems with input artifacts from prerequisite tasks -- **Environment issues**: Build tool problems, missing dependencies, version conflicts -- **Scope observations**: Discovery that the task is larger/smaller than expected, or that it overlaps with another task -- **Test findings**: Tests that revealed unexpected behavior or required modification +After task execution (whether successful or failed), append a "Noteworthy Events" section to the task file body if anything noteworthy occurred during execution. Append to the end of the task file: @@ -337,7 +304,7 @@ If no noteworthy events occurred, do not add the section. Read and execute $root/.ai/task-manager/config/hooks/POST_ERROR_DETECTION.md -On any error, ensure you still emit the structured output block (see Output Requirements) with `Status: failed` and `Exit Code: 1`. +On any error, ensure you still emit the structured output block (see Output Requirements) with `Exit Code: 1`. ## Output Requirements @@ -350,12 +317,7 @@ Always end your output with a standardized summary in this exact format: Task Execution Result: - Plan ID: [plan-id] - Task ID: [task-id] -- Task Name: [task filename without extension] -- Status: [completed|failed] - Exit Code: [0 for success, 1 for failure] -- Lint Check: [passed|failed|skipped] -- Test Check: [passed|failed|skipped] -- Noteworthy Events: [brief summary or "None"] ``` This structured output enables automated orchestration pipelines to parse results and determine next steps. It MUST be included regardless of success or failure. @@ -375,12 +337,11 @@ This structured output enables automated orchestration pipelines to parse result ## Integration Notes -This command is designed for scripting contexts where an external orchestrator manages task sequencing, commits, feature branches, and plan archival. It integrates with the task management system by: +This command is designed for scripting contexts where an external orchestrator manages task sequencing, commits, feature branches, linting, test execution, and plan archival. It integrates with the task management system by: - Using established plan and task location patterns - Leveraging the dependency checking script for validation - Following status management conventions (see Valid Status Transitions) - Providing structured machine-parseable output for orchestrator pipelines -- Running post-task validation (lint, tests) to catch issues before the orchestrator proceeds - Maintaining compatibility with execute-blueprint workflows - Preserving task isolation and dependency order