arn-code-execute-task

Arness Execute Task

Execute a single task from the task list by spawning a arn-code-task-executor agent. Optionally run a arn-code-task-reviewer to validate the implementation before marking the task complete.

Pipeline position (this is an alternative entry point, not in the main pipeline):

arn-code-taskify -> arn-code-execute-task (single task) -> [optional] arn-code-review-implementation

Use cases:

• Re-running a failed task after manual intervention
• Testing a single phase independently
• Implementing one task without the full pipeline
• Retrying a task that was escalated during arn-code-execute-plan

Prerequisites

If no ## Arness section exists in the project's CLAUDE.md, inform the user: "Arness is not configured for this project yet. Run /arn-implementing to get started — it will set everything up automatically." Do not proceed without it. Task list must exist (run /arn-code-taskify first).

Workflow

Step 1: Load Configuration

1. Read the project's CLAUDE.md and extract the ## Arness section to find:

   • Plans directory -- base path where project plans are saved
   • Code patterns -- path to the directory containing stored pattern documentation
   • Template path -- path to the report template set (JSON templates)
   • Template version -- plugin version the templates were copied from (if present)
   • Template updates -- user preference: ask, auto, or manual (if present)
   • Specs directory -- path to the directory containing specification files (if present)

   Template version check: If Template version and Template updates fields are present, run the template version check procedure documented in arn-code-save-plan Step 1 (Template Version Check) before proceeding. If ## Arness does not contain these fields, treat as legacy and skip.

---

Step 2: Identify the Task

• If user provided a task ID or number: verify it exists in TaskList
• If user provided a description: search TaskList for a matching task
• If no task specified: show all available tasks (pending, unblocked) and ask user to choose
• Show the selected task: ID, description, status, dependencies
• If task is blocked: warn user that dependencies haven't completed, ask if they want to proceed anyway

---

Step 3: Choose Review Option

Ask (using AskUserQuestion):

"Run with review gate after execution?"

Options:

1. Yes, review after execution (Recommended) -- Spawn reviewer to validate
2. No, execute only -- Skip review, mark complete after executor finishes

If review chosen, also ask:

Ask (using AskUserQuestion):

"How should Arness handle critical review findings?"

Options:

1. Resume executor with feedback (Recommended) -- Resumes the original agent with its full implementation context
2. Dispatch fresh executor with review report -- Spawns a new executor with the review report as context

Store the choice for the execution session.

---

Step 4: Execute the Task

1. Ask the user for PROJECT_NAME if not provided in the trigger message

2. Verify the project directory exists:

   <plans-dir>/<PROJECT_NAME>/
   ├── INTRODUCTION.md
   ├── TASKS.md
   ├── PROGRESS_TRACKER.json
   ├── plans/PHASE_*.md
   └── reports/
   

   If PROGRESS_TRACKER.json is missing, warn that progress tracking will not be available. Execution can still proceed.

3. Mark task as in_progress via TaskUpdate

4. Check if the project has ### Visual Testing configured in the ## Arness section of CLAUDE.md. If found, extract: capture script path, compare script path, baseline directory, diff threshold.

   Note: Extract only the top-level fields (implicit Layer 1). Do NOT parse #### Layer N: subsections — multi-layer visual validation runs during /arn-code-review-implementation, not per-task.

5. Spawn arn-code-task-executor via the Task tool with full context:

   • Task ID and full task description
   • Project name: <PROJECT_NAME>
   • Project folder path: <plans-dir>/<PROJECT_NAME>/
   • Phase plan file path (extracted from the task description)
   • INTRODUCTION.md path: <project-folder>/INTRODUCTION.md
   • Code patterns directory path: <code-patterns-dir>/
   • Specs directory path: <specs-dir>/ (if relevant to the task)
   • Report template path: <template-path>/
   • Visual testing config (if configured): capture script path, compare script path, baseline directory, diff threshold

6. Record the agent ID returned by the Task tool (needed for resume mode)

7. Wait for executor to complete

---

Step 5: Review (if requested)

1. Read the executor's output to extract:
   • Report file path(s)
   • List of files created and modified
   • Visual capture directory path (if reported)
2. Spawn arn-code-task-reviewer via the Task tool with:
   • Task ID and full task description
   • Project name and folder path
   • INTRODUCTION.md path
   • Code patterns directory path
   • Report template path (for TASK_REVIEW_REPORT_TEMPLATE.json)
   • Implementation/testing report path(s) from executor
   • List of files created/modified by executor
   • Visual testing config (if configured in Step 4): compare script path, baseline directory, diff threshold
   • Note: Only Layer 1 visual config is passed to the reviewer. Multi-layer visual validation runs during /arn-code-review-implementation.
   • Visual capture directory (if reported by executor)
3. Handle verdict:
   • pass -- mark task as completed via TaskUpdate
   • pass-with-warnings -- append warnings to implementation report (reviewFindings section), mark task as completed via TaskUpdate
   • needs-fixes -- apply chosen feedback mode:
     • Resume mode: resume the original executor agent (using its agent ID from Step 4.6, via the resume parameter of the Task tool) with review feedback, then re-run reviewer
     • Fresh dispatch mode: spawn a new executor with the review report + original context, then re-run reviewer
     • Maximum 2 review cycles, then escalate to user with full findings
4. After marking the task as completed (pass or pass-with-warnings), update PROGRESS_TRACKER.json:
   • Read <plans-dir>/<PROJECT_NAME>/PROGRESS_TRACKER.json
   • Find the phase entry whose implementation.taskId or testing.taskId matches this task
   • Set the matching status to "completed" and completedAt to current ISO 8601 timestamp
   • Set review.verdict to the reviewer's verdict and review.reviewCycles to the number of review cycles
   • If all phases now have implementation.status = "completed" (and testing.status = "completed" or "none"), set overallStatus to "completed"; otherwise set overallStatus to "in_progress" (if not already)
   • Update lastUpdated and write to disk
   • If no review was requested: same update but leave review.verdict and review.reviewCycles at their initial values
   • If PROGRESS_TRACKER.json does not exist, skip this step silently

---

Step 6: Report Result

Show: what was implemented, tests run, review verdict, reports generated.

• If review passed: "Task N is complete. Progress tracker updated: Phase N implementation/testing completed. Overall: X of Y phases complete."
• If no review: "Task N execution complete (no review performed). Progress tracker updated."
• If escalated: present findings and ask user for guidance.

Offer next step: "Would you like to run /arn-code-review-implementation to validate the full project, or continue with another task?"

If the review verdict is pass or pass-with-warnings: also offer "Or run /arn-code-simplify to review the implementation for simplification opportunities before full review."

If deferred visual testing layers exist in CLAUDE.md (any #### Layer N: subsection with **Status:** deferred) and this task is the last task in a phase, suggest: "Deferred visual testing layers detected. Consider running /arn-spark-visual-readiness to check if they can be activated now that this phase is complete."

---

Error Handling

• ## Arness config missing in CLAUDE.md -- suggest running /arn-implementing to get started
• No tasks in TaskList -- suggest running /arn-code-taskify to convert TASKS.md into tasks
• Task not found -- show available tasks and ask user to select one
• Task is blocked by incomplete dependencies -- warn user, let them decide whether to proceed anyway
• Project directory missing -- suggest running /arn-code-save-plan to create the project structure
• Executor fails -- read agent output, report to user, offer retry
• Executor reports 3-attempt test failure -- present failure details, ask: retry with more context, skip, or abort
• Reviewer fails -- report to user, offer to skip review or retry
• Review cycle exceeds 2 retries -- escalate to user with full review findings, ask: retry with more context, skip review, or abort
• Resume fails (API error or agent ID no longer valid) -- fall back to fresh dispatch mode, inform user