# Specs Kit Task Implementation

> Provides guided task implementation capability for executing specific tasks from a task list generated by spec-to-tasks. Use when implementing a specific task from a task list (use --task= prefix).

- Skill: `giuseppe-trisciuoglio/specs-kit-task-implementation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add giuseppe-trisciuoglio/specs-kit-task-implementation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/giuseppe-trisciuoglio/specs-kit-task-implementation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: giuseppe-trisciuoglio (https://skillmd.com/u/giuseppe-trisciuoglio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/giuseppe-trisciuoglio/specs-kit-task-implementation

---


# Task Implementation

## Overview

You are helping a developer implement a specific task from a task list generated by `/skill:specs-kit-spec-to-tasks`.
This command follows a focused workflow optimized for single-task implementation.

## Usage

```bash
/skill:specs-kit-task-implementation --task=task-name
```

## Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `--task` | Yes | Task file path (e.g., docs/specs/XXX-feature/tasks/TASK-001.md) |
| `--spec` | No | Path to spec folder |

## Examples

### Basic Usage

```bash
/skill:specs-kit-task-implementation --task=docs/specs/001-feature/tasks/TASK-001.md
```

### Auto-Detect Spec from Branch

```bash
/skill:specs-kit-task-implementation --task=TASK-003
```

## Inputs

Determine the task to implement from the invocation context:
- when driven by the loop, the task is provided in the `<task>` block of the prompt;
- when invoked directly, the task path (`--task=`) and optional spec folder (`--spec=`) arrive as skill arguments.

Resolve, in order:
- `task` → the task file path (required)
- `spec` → the spec folder path (optional; derived from the task path when absent)

If any required input is missing or ambiguous, ask the user via ask_user_question.

## What this task may not change

The spec's requirement document and everything under its `contracts/` folder
state what this implementation is measured against, so they are read-only here:
an attempt that rewrites one is refused by the loop, costs an attempt, and comes
back naming the file. When the code cannot honour them — the requirement is
impossible, contradictory, or the contract prescribes something that does not
work — say so in the implementation summary and leave the document untouched.
That is the channel that leads to a decision taken outside this session; editing
the document until it agrees with the code closes the mismatch for every later
reader without anyone deciding anything.

Working documents (`decision-log.md`, the task file, the technical plan, README
and architecture notes) stay writable as before.

## Action Routing

The `--action` argument determines the workflow path:

| Action | Workflow | Description |
|--------|----------|-------------|
| *(default)* | T-1 → T-7 | Full implementation workflow |
| `cleanup` | T-7 only | Jump directly to post-review code cleanup |

Resolve `--action` from the skill arguments:
- If absent → proceed with the full implementation workflow (T-1 through T-6, T-7 optional)
- If `cleanup` → skip to **T-7: Code Cleanup** directly, using the provided `--task=` path

When routing to T-7 directly, still perform **T-7.1: Verify Review Status** to confirm the task is in `reviewed` state before executing cleanup.

## Task Mode Detection

This command ONLY operates in Task Mode. If no `--task=` parameter is provided, inform the user that they should use the spec-driven flow (`/skill:specs-kit-brainstorm` → `/skill:specs-kit-spec-to-tasks`) to produce a task first.

## Core Principles

- **Ask clarifying questions only when the task or codebase leaves ambiguity**: default to executing the task as written; use ask_user_question only for real blockers, dependency conflicts, or multiple valid interpretations.
- **Understand before acting**: Read and comprehend task requirements first
- **Read files identified by agents**: When launching agents, ask them to return lists of the most important files to
  read. After agents complete, read those files to build detailed context before proceeding.
- **Follow acceptance criteria and DoD**: Implement exactly what is specified in the task and complete the documented Definition of Done
- **Use a checklist**: Track all progress throughout
- **No time estimates**: DO NOT provide or request time estimates or implementation timelines at any phase

---

## Workflow: Task Implementation (10 Steps)

This command implements a specific task following a focused workflow:
- T-1: Task Identification
- T-2: Git State Check
- T-3: Dependency Check
- T-3.5: Codebase Graph Validation
- T-3.6: Contract Validation
- T-3.7: Review Feedback Check
- T-4: Implementation
- T-5: Verification
- T-6: Task Completion
- T-7: Code Cleanup (Post-Review)

---

## T-1: Task Identification

**Goal**: Extract and validate the task from the task list

**Actions**:

1. (Argument parsing completed in Phase 0)
2. Read the task file and extract:
   - Task ID and title from YAML frontmatter
   - Description
   - Acceptance criteria
   - Definition of Ready (DoR) and Definition of Done (DoD) sections
   - Dependencies from YAML frontmatter
   - Reference to specification file
   - `imp-requirements` and `ac-mapping` from frontmatter — which spec ACs this task implements
   - If either section is missing, stop and instruct the user to update the task document before implementation

3. **Spec Traceability Gate **:
   - If the task file has `spec` reference, read the spec file to get full context:
     - Load the spec's acceptance criteria list with their `[IMP]`/`[SEF]`/`[EXT]` taxonomy
     - Identify which ACs this task covers (from `ac-mapping`)
     - Identify which `[IMP]` ACs remain for other tasks
   - Display to implementator:
   ```
   Task Traceability Context:
   - This task: TASK-XXX — "[title]"
   - Implements Spec ACs: [ac-mapping, e.g., AC-1, AC-3]
   - Corresponding REQ-IDs: [imp-requirements, e.g., REQ-001, REQ-003]
   
   Full Specification Context:
   - Total spec ACs: N ([I] implementable / [S] side-effect / [E] external)
   - This task covers: X/[I] implementable criteria
   - Remaining [IMP] criteria will be covered by: [list other tasks from task list]
   - Primary bounded context: [from spec's Bounded Context Impact Statement, if present]
   ```
   - If the task has a **Cross-Boundary Warning** section: read it and note the risk level before proceeding

---

## T-2: Git State Check

**Goal**: Validate DoR items related to repository state and baseline quality before implementation

**Actions**:

1. **Check for uncommitted changes FIRST**:
   - Run `git status --porcelain` to check for uncommitted changes
   - If there are untracked files, staged changes, or unstaged modifications:
     - Present the user with the specific changes found
     - Ask via ask_user_question: "You have uncommitted changes. Please commit them before starting task implementation. Do you want to proceed anyway (not recommended) or commit first?"
     - If user chooses to commit first, stop and wait for them to run `git commit`
     - If user proceeds anyway, document the uncommitted state and continue at user's risk
   - Only proceed with implementation if no uncommitted changes exist OR user explicitly accepts the risk
2. **Run lint and tests** (after git check passes):
   - Treat these checks as explicit DoR validation for local readiness and baseline health.
   - Detect available lint/test commands by checking `package.json` (scripts), `Makefile`, `pom.xml`, `build.gradle`, `pyproject.toml`, `build.gradle`, `pyproject.toml`, `composer.json`, etc.
   - Run lint first (e.g., `npm run lint`, `make lint`, `./mvnw checkstyle:check`, `ruff check .`), then tests (e.g., `npm test`, `make test`, `./mvnw test -q`, `pytest`, `php artisan test`)
   - If lint or tests fail:
     - Show the failing output to the user
     - Ask via ask_user_question: "Lint/tests are failing. It is recommended to fix them before starting task implementation to avoid compounding issues. Do you want to fix them first (recommended) or proceed anyway?"
     - If user chooses to fix first, stop and wait
     - If user proceeds anyway, document the failures and continue at user's risk
   - If no recognizable lint/test commands are found, skip this step and note it
   - Only proceed if lint/tests pass OR user explicitly accepts the risk

---

## T-3: Dependency Check

**Goal**: Validate DoR items related to task dependencies

**Actions**:

1. Check if task has dependencies and compare them against the task's DoR section
2. If dependencies exist:
   - Read task list to check completion status
   - If dependencies not completed:
     - Ask user via ask_user_question: proceed anyway or complete dependencies first
3. Record whether dependency-related DoR items are satisfied before implementation begins
4. Proceed based on user decision

---

## T-3.5: Codebase Graph Validation

**Goal**: Validate DoR technical context against actual codebase state

**Actions**:

1. **Extract spec_id from task**:
   - Read `spec` field from task frontmatter (e.g., `docs/specs/001-feature-name/2026-03-07--feature-name.md`)
   - Extract spec folder path

2. **Check for the codebase graph**:
   - Read `graphify-out/graph.json` from the project root (produced by the
     external graphify skill). It is the single codebase graph: there is no
     per-spec projected file. Treat it as the only source — never hand-build or
     supplement it from another tool.
   - If missing or unreadable, skip validation with note: "No codebase graph found (graphify-out/graph.json), cannot validate dependencies — run /graphify <project-root>"

3. **If the graph exists**:
   - Extract task requirements from "Technical Context" or task description:
     - Component references (services, repositories, controllers to use)
     - API endpoints to integrate with
     - Patterns to follow
   - Validate each requirement directly against `graphify-out/graph.json`:
     - Confirm each referenced component exists as a node
     - Confirm each referenced API endpoint exists
     - Confirm each referenced pattern is present

4. **Process validation results**:
   - **If valid** (no errors):
     - Proceed with implementation, all dependencies exist
     - Log: "Task validated against the codebase graph: All dependencies exist"
   - **If errors found**:
     - Present errors to user:
       ```
       Task validation failed against the codebase graph:
       Errors:
       - Component UserService not found in codebase
       - API /api/v1/payments not found, may need implementation

       Options:
       - "Proceed anyway" (implement missing components)
       - "Update task" (remove/fix invalid dependencies)
       - "Cancel" (fix task first, then implement)
       ```
     - Ask user via ask_user_question how to proceed
   - **If warnings found**:
     - Present warnings but allow continuation

---

## T-3.6: Contract Validation

**Goal**: Ensure interfaces and data structures are agreed upon before coding

**Actions**:

1. Read the `expects` and `provides` sections of the task
2. Verify if the components mentioned in `expects` are already implemented (check the codebase graph `graphify-out/graph.json`, or scan the codebase)
3. If this is one of the **first 3 tasks** of the spec:
   - Treat `provides` as a **proposal**
   - You may suggest changes to the proposed interface if implementation reveals a better way
   - Document any changes in `decision-log.md`
4. If this is a **later task**:
   - Treat `provides` as a **contract**
   - You MUST follow the agreed-upon interface to avoid breaking dependencies
   - If a change is absolutely necessary, you MUST create a DEC entry in `decision-log.md` justifying the break

---

## T-3.7: Review Feedback Check

**Goal**: Ensure previous review failures are addressed

**Actions**:

1. Check if a review report exists for this task: `docs/specs/[id]/tasks/TASK-XXX--review.md`
2. If it exists and status is NOT `passed`:
   - Read the "Required Fixes" and "Code Review Findings" sections
   - Incorporate these requirements into your implementation plan
   - Ensure every finding is addressed in the new implementation

---

## T-4: Implementation

**Goal**: Execute the task requirements in the codebase

**Actions**:

1. Explore the codebase to find relevant files and patterns
2. Read the files identified by agents (if any)
3. Create a detailed implementation plan with all necessary steps
4. Implement the code changes:
   - Create new files and directories as needed
   - Modify existing files
   - Follow project patterns and conventions
   - Adhere to the functional specification and task description
5. Ensure code is clean, well-documented, and follows best practices
6. Use a checklist to track each step of the implementation

**Decision velocity**:
- After the initial codebase exploration (T-1 through T-3.7), make each design decision once
  and move on — do not re-litigate the same trade-off across multiple rounds of internal
  monologue
- When the task's Technical Context already documents a project pattern (e.g. "Entity uses
  Lombok @Getter/@Setter"), follow it without debate unless the task's own ACs require
  something different
- If a decision involves a genuine trade-off (factory vs builder, class-level vs targeted
  setters), pick the option consistent with existing project conventions documented in the
  task or the AGENTS.md, record it briefly, and proceed
- Limit re-reading of files: once a file has been read and its content is understood, refer
  to it from memory unless a specific detail (line number, exact annotation value) must be
  verified

---

## T-5: Verification

**Goal**: Verify the implementation against acceptance criteria and DoD

**Actions**:

1. Run the project's build/compile command to ensure no syntax errors
2. Run relevant unit and integration tests:
   - Identify existing tests for modified components
   - Run them to ensure no regressions
3. Create new tests for the implemented functionality:
   - Follow the test instructions in the task description
   - Use the project's testing framework and patterns
   - Ensure high coverage of the new code
4. Verify all acceptance criteria are met through manual or automated checks
5. Verify all DoD items are satisfied
6. If any verification fails, return to T-4 to fix the issues

---

## T-6: Task Completion

**Goal**: Finalize the task and update status

**Actions**:

1. Update the task file (`docs/specs/[id]/tasks/TASK-XXX.md`):
   - Check all acceptance criteria boxes: `- [x]`
   - Check all DoD boxes: `- [x]`
   - Set `status: implemented` in frontmatter
   - Set `implemented_date: YYYY-MM-DD`
   - Fill in `provides:` in the frontmatter with the public API contracts that
     downstream tasks depend on: factory methods, public constructors, domain methods,
     new annotations, new test dependencies, and any other symbol a later task must
     know to integrate correctly. Use one string per contract:
     ```yaml
     provides:
       - "Project.create(UUID organizationId, String name, String description, GitRepositoryReference gitRepository)"
       - "Project.updateProfile(String name, String description) — bumps updatedAt"
       - "@Searchable on Project.name — marker annotation, no behaviour"
       - "Test dep: spring-boot-data-jpa-test (for @DataJpaTest in Spring Boot 4)"
     ```
2. Add a summary of changes to the task file:
   - Files created/modified
   - New components and APIs
   - Testing performed
3. **Synchronization**:
   - Run `/skill:specs-kit-sync [spec-folder] --kg-only --after-task=[TASK-ID]` to update technical context
   - Run `/skill:specs-kit-sync [spec-folder] --code-only` to detect spec-to-code deviations
4. Inform the user:
   - Display a summary of the implementation
   - Provide the command for review: `/skill:specs-kit-task-review --task=TASK-XXX`
   - **Next Step**: Run `/skill:specs-kit-task-review` then Phase T-7 cleanup auto-activates
5. Log completion of the task implementation workflow

---

## T-7: Code Cleanup (Optional, Post-Review)

**Goal**: Cosmetic cleanup after review approval — the final step before completion.

**Prerequisite**: Task status is `reviewed` (review passed).

**When to run**: Automatically suggested after task-review passes. Skippable if user prefers manual cleanup.

**Actions**:

### T-7.1: Verify Review Status

1. Read the task file — confirm status is `reviewed` or `implemented`
2. Verify review report `TASK-XXX--review.md` exists and is approved
3. If not reviewed → stop and prompt user to run `/skill:specs-kit-task-review` first

### T-7.2: Identify Files to Clean

1. Read `TASK-XXX--review.md` for files created/modified
2. Read task `provides` field for file paths
3. Build cleanup file list; categorize: source / test / config

### T-7.3: Technical Debt Removal

Search with Grep for temporary/debug artifacts:
- `console.log`, `System.out.println`, `print(`, `// DEBUG:`, `// temp`, `// hack`
- Resolved `TODO`/`FIXME` comments (keep unresolved ones with context)

Remove confirmed debt. Document what was removed.

### T-7.4: Import Optimization

1. Discover and run the project's own import tooling from its configuration:
   - `package.json` scripts, Maven/Gradle plugins (e.g. Spotless), `composer` scripts, `pyproject.toml` (`[tool.isort]`/`[tool.ruff]`), `.pre-commit-config.yaml`
2. If no tool is configured: manually remove unused imports

### T-7.5: Code Formatting & Readability

1. Discover and run the project's own formatter/linter from its configuration:
   - `package.json` scripts (`format`/`lint`), Maven/Gradle plugins (Spotless, Checkstyle), `composer` scripts, `pyproject.toml` (`[tool.black]`/`[tool.ruff]`), `.pre-commit-config.yaml`
2. If no formatter is configured: fix indentation, break lines >120 chars, fix spacing
3. Remove dead code only if obviously safe

### T-7.6: Final Verification

1. Run tests — must pass. If fail: stop, report, do NOT mark complete.
2. Verify no logic or signature changes were introduced
3. Update task status: `reviewed` → `completed`
4. Set `cleanup_date` and `completed_date` in frontmatter

### T-7.7: Summary

Report:
- Files cleaned
- Debt removed (what and where)
- Formatter/import tool used
- Status: completed