x-implement-task

Global Output Policy

• Language: English ONLY.
• Tone: Technical, Direct, and Concise.
• Efficiency: Remove all conversational fillers and greetings to save tokens.

🔒 EXECUTION INTEGRITY (Rule 24) — Every Skill(...) block is a MANDATORY TOOL CALL. TDD cycles (x-drive-tdd), atomic commits (x-commit-changes), CI watch (x-watch-pr-ci), and PR creation (x-create-pr) MUST be invoked as real tool calls, not inlined. See .claude/rules/24-execution-integrity.md.

Triggers

/x-implement-task STORY-ID          — implement a story by ID (v1 or v2 schema auto-detected)
/x-implement-task TASK-XXXX-YYYY-NNN  — implement a specific task (v2 task-file-first mode)
/x-implement-task feature-description  — implement a feature from description
/x-implement-task STORY-ID --worktree  — standalone worktree mode (ADR-0004 Mode 2)

Parameters

Parameter	Type	Default	Description
STORY-ID or TASK-ID or description	positional	(required)	Story ID, TASK-XXXX-YYYY-NNN, or feature description
--worktree	boolean	false	Create dedicated worktree (standalone Mode 2). Ignored inside existing worktree (Rule 14 §3).
--no-ci-watch	boolean	false	Skip Step 4.5 CI-Watch. Required for CI/automation.

Output Contract

Schema dispatch:

planningSchemaVersion	Execution Mode	Input artifacts
"1.0" (or absent)	v1 — Double-Loop TDD via story section 8	story file, plan-story-*.md, tests-story-*.md
"2.0"	v2 — task-file-first	task-TASK-*.md + plan-task-TASK-*.md + task-implementation-map-*.md

Emits structured result to caller:

{"status":"DONE","taskId":"TASK-XXXX-YYYY-NNN","commitSha":"abc123","cycleCount":N,"coverageDelta":{"lineBefore":95.1,"lineAfter":95.3},"wallclockMs":12340}

Task Tracking (Rule 25)

Six phases (Rule 25 REGRA-001, EPIC-0055). Each phase opens with x-internal-verify-phase-gates --mode pre + TaskCreate, closes with TaskUpdate(completed) + POST/WAVE/FINAL gate. Phase 2 dispatches 3 × N TaskCreate calls (Red/Green/Refactor per cycle) in Batch A, then updates sequentially in the execution loop. See references/tdd-cycle-protocol.md for the canonical TDD cycle tracking protocol.

Phase 0 — Setup (Steps 0 and 0.5)

<!-- TELEMETRY: phase.start --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-implement-task Phase-0-Setup

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode pre --skill x-implement-task --phase Phase-0-Setup")

Open phase tracker (close with TaskUpdate(id: phase0TaskId, status: "completed") after Step 0.5):

TaskCreate(subject: "{TASK_ID} › Step 0 - Precheck", activeForm: "Checking plan reuse and staleness")

Resolve paths, check staleness (Step 0), detect worktree context (Step 0.5):

Skill(skill: "x-manage-worktrees", model: "haiku", args: "detect-context")

See references/full-protocol.md §Step 0 and §Step 0.5 for full three-way mode decision (REUSE / CREATE / LEGACY).

Persist interactiveMode to execution-state.json (EPIC-0068 — consumed by Stop hook enforce-continuous-flow.sh):

Skill(skill: "x-internal-update-status", args: "--file ai/epics/epic-XXXX/execution-state.json --type task --id <TASK-ID> --field interactiveMode --value <interactive|non-interactive>")

Value: "interactive" when --interactive passed or CLAUDE_LEGACY_INTERACTIVE=1; otherwise "non-interactive" (Rule 20 default, EPIC-0061).

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode post --skill x-implement-task --phase Phase-0-Setup")

TaskUpdate(id: phase0TaskId, status: "completed")

<!-- TELEMETRY: phase.end --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-implement-task Phase-0-Setup ok

Phase 1 — Prepare and Understand (Step 1)

<!-- TELEMETRY: phase.start --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-implement-task Phase-1-Prepare

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode pre --skill x-implement-task --phase Phase-1-Prepare")

Open phase tracker (close with TaskUpdate(id: phase1TaskId, status: "completed") after Step 1):

TaskCreate(subject: "{TASK_ID} › Step 1 - Prepare", activeForm: "Loading knowledge packs and building TDD plan")

Dispatch a preparation subagent (Rule 13 Pattern 2 — SUBAGENT-GENERAL) that reads KPs and produces the TDD implementation plan. See references/full-protocol.md §Step 1.

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode post --skill x-implement-task --phase Phase-1-Prepare")

TaskUpdate(id: phase1TaskId, status: "completed")

<!-- TELEMETRY: phase.end --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-implement-task Phase-1-Prepare ok

Phase 2 — TDD Cycles (Step 2)

See references/tdd-cycle-protocol.md for the canonical TDD cycle tracking protocol with Batch A/B dispatch and wave gate.

<!-- TELEMETRY: phase.start --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-implement-task Phase-2-TDD

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode pre --skill x-implement-task --phase Phase-2-TDD")

Open phase tracker (close with TaskUpdate(id: phase2TaskId, status: "completed") after wave gate):

TaskCreate(subject: "{TASK_ID} › Step 2 - TDD Cycles", activeForm: "Running TDD Red-Green-Refactor cycles")

Batch A — emit all TDD cycle task trackers in ONE assistant message (Red/Green/Refactor per UT-N):

TaskCreate(subject: "{TASK_ID} › Step 2 › Cycle 1 › Red", activeForm: "RED cycle 1")
TaskCreate(subject: "{TASK_ID} › Step 2 › Cycle 1 › Green", activeForm: "GREEN cycle 1")
TaskCreate(subject: "{TASK_ID} › Step 2 › Cycle 1 › Refactor", activeForm: "REFACTOR cycle 1")
[... repeat for Cycle 2..N in the same message ...]

Store returned IDs: tddCycleTaskIds[N] = {red: id, green: id, refactor: id}.

Per-cycle execution (sequential):

For each cycle N = 1..M:

TaskUpdate(id: tddCycleTaskIds[N].red, status: "in_progress")
[RED: write failing test → run → MUST fail]
Skill(skill: "x-commit-changes", model: "haiku", args: "--type test --scope {scope} --subject \"add failing test UT-N (RED)\"")
TaskUpdate(id: tddCycleTaskIds[N].red, status: "completed")

TaskUpdate(id: tddCycleTaskIds[N].green, status: "in_progress")
[GREEN: minimum code → all tests MUST pass]
Skill(skill: "x-commit-changes", model: "haiku", args: "--type feat --scope {scope} --subject \"implement UT-N (GREEN)\"")
TaskUpdate(id: tddCycleTaskIds[N].green, status: "completed")

TaskUpdate(id: tddCycleTaskIds[N].refactor, status: "in_progress")
[REFACTOR: improve design → tests MUST stay GREEN]
Skill(skill: "x-commit-changes", model: "haiku", args: "--type refactor --scope {scope} --subject \"improve UT-N\"")
TaskUpdate(id: tddCycleTaskIds[N].refactor, status: "completed")

Wave gate — all TDD cycle tasks completed:

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode wave --skill x-implement-task --phase Phase-2-TDD --expected-tasks {all-tdd-task-ids}")

TaskUpdate(id: phase2TaskId, status: "completed")

<!-- TELEMETRY: phase.end --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-implement-task Phase-2-TDD ok

Phase 3 — Validate and Status Transition (Steps 3 and 3.5)

<!-- TELEMETRY: phase.start --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-implement-task Phase-3-Validate

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode pre --skill x-implement-task --phase Phase-3-Validate")

Open phase tracker (close with TaskUpdate(id: phase3TaskId, status: "completed") after Step 3.5):

TaskCreate(subject: "{TASK_ID} › Step 3 - Validate", activeForm: "Validating coverage and acceptance criteria")

Run all AT-N acceptance tests; coverage check (line ≥ 95%, branch ≥ 90%). See references/full-protocol.md §Step 3.

v2 only — Status transition (Step 3.5):

TaskCreate(subject: "{TASK_ID} › Step 3.5 - Status sync", activeForm: "Syncing task status to Concluida")

Write **Status:** Concluída to task file and map row via TaskMapRowUpdaterCli. See references/full-protocol.md §Phase 3.5.

TaskUpdate(id: step35TaskId, status: "completed")

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode post --skill x-implement-task --phase Phase-3-Validate")

TaskUpdate(id: phase3TaskId, status: "completed")

<!-- TELEMETRY: phase.end --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-implement-task Phase-3-Validate ok

Phase 4 — Commit and CI Watch (Steps 4 and 4.5)

<!-- TELEMETRY: phase.start --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-implement-task Phase-4-Commit

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode pre --skill x-implement-task --phase Phase-4-Commit")

Open phase tracker (close with TaskUpdate(id: phase4TaskId, status: "completed") after Step 4.5):

TaskCreate(subject: "{TASK_ID} › Step 4 - Commit", activeForm: "Creating TDD atomic commit")

Invoke atomic commit via x-commit-changes. See references/full-protocol.md §Step 4.

Skill(skill: "x-commit-changes", model: "haiku", args: "--type feat --scope {scope} --subject \"implement {task-description}\"")

CI Watch (Step 4.5, conditional — v2 + --worktree standalone only; see decision table in references/full-protocol.md §Step 4.5):

TaskCreate(subject: "{TASK_ID} › Step 4.5 - CI Watch", activeForm: "Polling CI checks after PR creation")

MANDATORY TOOL CALL — NON-NEGOTIABLE (Rule 24 + Rule 45): Invoke the x-watch-pr-ci skill via the Skill tool — silent omission fails Camada 3 audit (EIE_EVIDENCE_MISSING):

Skill(skill: "x-watch-pr-ci", args: "--pr-number {N} --poll-interval-seconds 60 --timeout-minutes 30 --require-copilot-review=false")

TaskUpdate(id: step45TaskId, status: "completed")

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode post --skill x-implement-task --phase Phase-4-Commit")

TaskUpdate(id: phase4TaskId, status: "completed")

<!-- TELEMETRY: phase.end --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-implement-task Phase-4-Commit ok

Phase 5 — Cleanup (Step 5)

<!-- TELEMETRY: phase.start --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-implement-task Phase-5-Cleanup

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode pre --skill x-implement-task --phase Phase-5-Cleanup")

Open phase tracker (close with TaskUpdate(id: phase5TaskId, status: "completed") at final gate):

TaskCreate(subject: "{TASK_ID} › Step 5 - Cleanup", activeForm: "Cleaning up worktree")

Mode-aware cleanup (REUSE: no-op; CREATE: remove worktree; LEGACY: checkout develop). See references/full-protocol.md §Step 5.

Skill(skill: "x-manage-worktrees", model: "haiku", args: "remove --id {task-id}")

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode final --skill x-implement-task --phase Phase-5-Cleanup")

TaskUpdate(id: phase5TaskId, status: "completed")

<!-- TELEMETRY: phase.end --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-implement-task Phase-5-Cleanup ok

Error Envelope

Code	Condition
TASK_ARTIFACT_NOT_FOUND	task / plan / map file missing (v2)
UNMET_DEPENDENCY	declared Depends on TASK-ID not DONE
SCHEMA_VIOLATION	task file fails ERROR-level schema validation
OUTPUT_CONTRACT_VIOLATION	declared output failed post-exec verification (v2 Phase 3)
RED_NOT_OBSERVED	RED phase test didn't fail as expected
REFACTOR_BROKE_TESTS	refactor made previously-green tests fail
STATUS_SYNC_FAILED	Phase 3.5 (v2) failed to update **Status:** header or map row
Coverage below threshold	Add missing test scenarios; no bypass

Full Protocol

Complete step-by-step instructions for each phase (Step 0 plan-reuse + staleness check, Step 0.5 worktree three-way mode decision, Step 1 subagent KP loading, Step 2 Double-Loop TDD + TPP ordering, Step 3 coverage + AC validation, Step 3.5 status transition, Step 4 atomic commit conventions, Step 4.5 CI-Watch decision table, Step 5 mode-aware cleanup), v2 extensions (Phase 0c schema detection, Phase 0d–0e pre-execution gates, Phase 5 status report), CI-Watch state-file schema, and all knowledge pack references in references/full-protocol.md. Canonical TDD cycle tracking protocol (Batch A/B dispatch, wave gate, cycle IDs) in references/tdd-cycle-protocol.md.