edercnj/x-implement-task

🔒 EXECUTION INTEGRITY (Rule 24) — Every Skill(...) block is a MANDATORY TOOL CALL. 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 src/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. | | --orchestrated | boolean | false | Set to true when dispatched from x-implement-story. Alters behavior: (1) No task branch creation — all work is committed directly to the current story branch; (2) No push per task — the story orchestrator issues a single push at the end of the full lifecycle; (3) No per-task PR — x-create-pr is NOT called; (4) CI-Watch (Step 4.5) is skipped — the parent story orchestrator owns CI polling; (5) worktree cleanup (Phase 5) is skipped — the parent story orchestrator owns worktree lifecycle. Never set this flag manually in standalone invocations. | | --target-branch | string | develop | Base branch for task PRs. Propagated from x-implement-story. | | --context-path <path> | string | — | Explicit base directory for plan artifacts and execution-state.json (e.g. .aikittools/bugs/bug-000001/). When provided, takes precedence over path derived from task ID. Used when dispatched from x-internal-implement-story for bug tasks. |

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}

⚠️ Mandatory Execution Summary

Read before executing. Every phase below is either MANDATORY or clearly marked CONDITIONAL/OPTIONAL. Silent omission of any MANDATORY phase is a PROTOCOL_VIOLATION.

| Phase | Name | Status | Bypass flag | |-------|------|--------|-------------| | 0 | Setup & Worktree Detect | MANDATORY | — | | 1 | Prepare: Load KPs + Build TDD Plan | MANDATORY | — | | 2 | TDD Cycles (Red/Green/Refactor × N) | MANDATORY | — | | 3 | Validate Coverage + AC + Status Sync | MANDATORY | — | | 4 | Atomic Commit | MANDATORY | — | | 4.5 | CI Watch (after PR) | CONDITIONAL — v2 standalone only | --no-ci-watch | | 5 | Cleanup Worktree | CONDITIONAL — only in CREATE mode | — |

Phase 2 MUST execute at minimum 1 full Red/Green/Refactor cycle (Cycle 1 ALWAYS degenerate). Phase 3 MUST assert line ≥ 95% and branch ≥ 90% coverage.

Task Tracking (Rule 25)

Six phases (Rule 25 REGRA-001). 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)

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")

--orchestrated mode — Branch policy (MANDATORY):

When --orchestrated=true, skip all worktree and branch creation steps. Work directly on the current branch (the story branch). Do NOT invoke x-manage-worktrees create, do NOT run git checkout -b, and do NOT create a task-level branch. The parent x-implement-story orchestrator owns the story branch; all task commits accumulate on it.

IF --orchestrated:
  LOG: "[x-implement-task --orchestrated] Operating on story branch — no task branch created."
  SKIP worktree creation / git checkout -b calls
  PROCEED to Step 0 (plan-reuse check) with current branch as working branch
ELSE:
  Normal Mode 1/2/3 worktree detection (see full-protocol.md §Step 0.5)

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 (consumed by Stop hook enforce-continuous-flow.sh (planned — not yet implemented)). When --context-path is provided, use {context_path}/execution-state.json; otherwise derive base dir from task ID feature prefix (.aikittools/features/feature-XXXX/):

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

Value: "interactive" when --interactive passed; otherwise "non-interactive" (Rule 20 default).

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")

Phase 1 — Prepare and Understand (Step 1)

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")

Resolve canonical implementation packs via x-internal-select-context-packs (primary source of truth) before dispatch. Build implementCapabilities from task/story evidence (task file, plan-task, task map row, interfaces, and active NFR constraints) and keep only context-relevant domains — do not preload broad capability sets by default:

Skill(skill: "x-internal-select-context-packs",
      args: "--phase implement --capabilities <implementCapabilities>")
Skill(skill: "x-internal-select-knowledge",
      args: "--kind technical --phase implement --capabilities <implementCapabilities>")

Load policy for selector output (union both selectors' buckets): read all required; read only scope-relevant recommended; include optional only when the task explicitly requires optional controls or exploratory assets.

Architecture Decisions Loading (MANDATORY when at least one decisions file exists):

Before dispatching the preparation subagent, check for the canonical architecture decisions file:

ARCH_BACKEND_FILE="docs/architecture/architecture-decisions-backend.md"
HAS_ARCH_DECISIONS=false
[ -f "$ARCH_BACKEND_FILE" ] && HAS_ARCH_DECISIONS=true

When HAS_ARCH_DECISIONS=true:

1. Read docs/architecture/architecture-decisions-backend.md.
2. Extract the "Patterns e Knowledge Obrigatórios" sections and load every listed file.
3. Pass the loaded content to the preparation subagent prompt as ARCHITECTURE_DECISIONS_CONTEXT.
4. The subagent MUST use the pattern excerpts from this file rather than inventing conventions — anti-alucinação.

When HAS_ARCH_DECISIONS=false: proceed normally; log INFO: docs/architecture/architecture-decisions-backend.md not found.

Dispatch a preparation subagent (Rule 13 Pattern 2 — SUBAGENT-GENERAL) that reads KPs and produces the TDD implementation plan. For Java projects, dispatch the java-developer named subagent:

Agent(
  subagent_type: "java-developer",
  description: "Load KPs and build TDD implementation plan for {TASK_ID}",
  prompt: "FIRST ACTION: TaskCreate(subject: \"{TASK_ID} › Step 1 - Prepare\", activeForm: \"Loading KPs\"). Read all `required` and only scope-relevant `recommended` assets returned by `x-internal-select-context-packs` for phase `implement` and capabilities `<implementCapabilities>` (selector output is canonical; avoid unrelated assets). Read all plan artifacts from .aikittools/features/. Produce a TDD implementation plan covering: layer order, AT-N acceptance tests, UT-N unit tests in TPP order. LAST ACTION: TaskUpdate(status: \"completed\")."
)

See references/full-protocol.md §Step 1 for full subagent prompt and KP loading details.

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")

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.

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")

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

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 the task file and the matching map row natively (rewrite the **Status:** header line / status cell — no external CLI). 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")

Phase 3.7 — Specialist Exit Gate (v2 only, CONDITIONAL)

Exit gate: before committing, run specialist reviews declared in expects-reviews from the task file. This ensures each task is reviewed by the right specialist before the code-review aggregation task. Skip when task-type == code-review or when expects-reviews is empty.

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

Open phase tracker:

TaskCreate(subject: "{TASK_ID} › Step 3.7 - Specialist Exit Gate", activeForm: "Running expects-reviews specialists")

Exit gate resolution:

IF planningSchemaVersion == "2.0" AND task-type != "code-review":
  PARSE expects-reviews from task-TASK-*.md frontmatter (field: expects-reviews)

  IF expects-reviews is empty or null:
    LOG: "[EXIT-GATE] No expects-reviews declared — skipping specialist exit gate."
    TaskUpdate(id: step37TaskId, status: "completed")
    PROCEED to Phase 4

  ELSE:
    LOG: "[EXIT-GATE] Running specialists: {expects-reviews}"
    Skill(skill: "x-review-specialist",
          args: "--story-id <parent-story-id> --scope {expects-reviews-as-csv} --task-exit-gate --task-id {TASK_ID}")
    
    IF x-review-specialist decision == "NO-GO":
      LOG: "[EXIT-GATE] Task exit gate FAILED — NO-GO from specialists: {expects-reviews}"
      ABORT with TASK_EXIT_GATE_FAILED
    ELSE:
      LOG: "[EXIT-GATE] Task exit gate PASSED — verdict: {decision}"
      TaskUpdate(id: step37TaskId, status: "completed")
      PROCEED to Phase 4

ELSE (v1 schema OR task-type == code-review):
  SKIP Phase 3.7
  PROCEED to Phase 4

| Condition | Action | |-----------|--------| | TASK_EXIT_GATE_FAILED | Abort task; specialist findings written to .aikittools/.../reviews/exit-gate-{TASK_ID}.md | | All specialist EXIT-GATE verdicts are GO/GO-WITH-RESERVATIONS | Continue to Phase 4 commit |

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

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

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}\"")

--orchestrated mode — No PR, No Push, No CI Watch:

When --orchestrated=true, skip Step 4.5 entirely (no x-create-pr, no x-watch-pr-ci, no git push). The commit above is the final action for this task. The parent x-implement-story orchestrator will issue the single push after ALL tasks (including the code-review task) have been completed and the story push gate has passed.

IF --orchestrated:
  LOG: "[x-implement-task --orchestrated] Task commit staged. No push/PR — story orchestrator owns push lifecycle."
  SKIP Step 4.5 (x-create-pr, x-watch-pr-ci, git push)
  PROCEED to Phase 5 gate (worktree cleanup is also skipped in orchestrated mode)

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")

Phase 5 — Cleanup (Step 5)

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")

--orchestrated mode — No worktree cleanup:

When --orchestrated=true, skip all worktree removal operations. The parent x-implement-story orchestrator is the worktree creator and is responsible for removal at story close (Phase 3.5).

IF --orchestrated:
  LOG: "[x-implement-task --orchestrated] Skipping worktree cleanup — story orchestrator owns worktree lifecycle."
  PROCEED to final gate (no-op cleanup)
ELSE:
  Mode-aware cleanup (REUSE: no-op; CREATE: remove worktree; LEGACY: checkout develop)

Mode-aware cleanup for standalone mode (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")

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 |

Knowledge Pack References

Read src/skills/x-internal-select-context-packs/SKILL.md Read src/knowledge/shared/architecture-decisions/task-hierarchy/knowledge.md Read src/knowledge/shared/governance-baselines/tool-call-grammar/knowledge.md

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.

Decision Record

ADR-0014 — Task Hierarchy and Phase Gates: Defines Red/Green/Refactor TDD cycle as the canonical task unit with mandatory phase gates.

Optional: Version Bump After Task

After a successful task completion (when status=DONE), you may optionally bump the application version following Semantic Versioning. Individual tasks typically correspond to a patch increment:

Skill(skill: "x-increment-version", args: "--type patch")

This step is NOT mandatory — invoke it only when the project has explicit version management and the task represents a shippable unit. For tasks within a story, prefer bumping at story-level via /x-implement-story instead. See /x-increment-version for stack detection and commit conventions.