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

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

Arguments

Examples

Basic Usage

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

Auto-Detect Spec from Branch

/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:

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 "

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:

     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