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
| 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
/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:
| 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:
-
(Argument parsing completed in Phase 0)
-
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-requirementsandac-mappingfrom frontmatter — which spec ACs this task implements- If either section is missing, stop and instruct the user to update the task document before implementation
-
**Spec Traceability Gate **:
- If the task file has
specreference, 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
- Load the spec's acceptance criteria list with their
- 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
- If the task file has
T-2: Git State Check
Goal: Validate DoR items related to repository state and baseline quality before implementation
Actions:
- Check for uncommitted changes FIRST:
- Run
git status --porcelainto 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
- Run
- 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:
- Check if task has dependencies and compare them against the task's DoR section
- 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
- Record whether dependency-related DoR items are satisfied before implementation begins
- Proceed based on user decision
T-3.5: Codebase Graph Validation
Goal: Validate DoR technical context against actual codebase state
Actions:
-
Extract spec_id from task:
- Read
specfield from task frontmatter (e.g.,docs/specs/001-feature-name/2026-03-07--feature-name.md) - Extract spec folder path
- Read
-
Check for the codebase graph:
- Read
graphify-out/graph.jsonfrom 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 "
- Read
-
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
- Extract task requirements from "Technical Context" or task description:
-
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
- Present errors to user:
- If warnings found:
- Present warnings but allow continuation
- If valid (no errors):
T-3.6: Contract Validation
Goal: Ensure interfaces and data structures are agreed upon before coding
Actions:
- Read the
expectsandprovidessections of the task - Verify if the components mentioned in
expectsare already implemented (check the codebase graphgraphify-out/graph.json, or scan the codebase) - If this is one of the first 3 tasks of the spec:
- Treat
providesas a proposal - You may suggest changes to the proposed interface if implementation reveals a better way
- Document any changes in
decision-log.md
- Treat
- If this is a later task:
- Treat
providesas 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.mdjustifying the break
- Treat
T-3.7: Review Feedback Check
Goal: Ensure previous review failures are addressed
Actions:
- Check if a review report exists for this task:
docs/specs/[id]/tasks/TASK-XXX--review.md - 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:
- Explore the codebase to find relevant files and patterns
- Read the files identified by agents (if any)
- Create a detailed implementation plan with all necessary steps
- 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
- Ensure code is clean, well-documented, and follows best practices
- 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:
- Run the project's build/compile command to ensure no syntax errors
- Run relevant unit and integration tests:
- Identify existing tests for modified components
- Run only the tests that cover what you touched: the modules, packages or files you changed. Do not run the whole suite — the gate that follows this phase runs the same scope for you, and the full suite runs at the checkpoint of a task that passed its review. A full suite run inside the phase pays for itself two more times before the task is done.
- Run them to ensure no regressions
- 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
- Verify all acceptance criteria are met through manual or automated checks
- Verify all DoD items are satisfied
- If any verification fails, return to T-4 to fix the issues
T-6: Task Completion
Goal: Finalize the task and update status
Actions:
- Update the task file (
docs/specs/[id]/tasks/TASK-XXX.md):- Check all acceptance criteria boxes:
- [x] - Check all DoD boxes:
- [x] - Set
status: implementedin 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)"
- Check all acceptance criteria boxes:
- Add a summary of changes to the task file:
- Files created/modified
- New components and APIs
- Testing performed
- 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-onlyto detect spec-to-code deviations
- Run
- 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-reviewthen Phase T-7 cleanup auto-activates
- 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
- Read the task file — confirm status is
reviewedorimplemented - Verify review report
TASK-XXX--review.mdexists and is approved - If not reviewed → stop and prompt user to run
/skill:specs-kit-task-reviewfirst
T-7.2: Identify Files to Clean
- Read
TASK-XXX--review.mdfor files created/modified - Read task
providesfield for file paths - 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/FIXMEcomments (keep unresolved ones with context)
Remove confirmed debt. Document what was removed.
T-7.4: Import Optimization
- Discover and run the project's own import tooling from its configuration:
package.jsonscripts, Maven/Gradle plugins (e.g. Spotless),composerscripts,pyproject.toml([tool.isort]/[tool.ruff]),.pre-commit-config.yaml
- If no tool is configured: manually remove unused imports
T-7.5: Code Formatting & Readability
- Discover and run the project's own formatter/linter from its configuration:
package.jsonscripts (format/lint), Maven/Gradle plugins (Spotless, Checkstyle),composerscripts,pyproject.toml([tool.black]/[tool.ruff]),.pre-commit-config.yaml
- If no formatter is configured: fix indentation, break lines >120 chars, fix spacing
- Remove dead code only if obviously safe
T-7.6: Final Verification
- Run tests — must pass. If fail: stop, report, do NOT mark complete.
- Verify no logic or signature changes were introduced
- Update task status:
reviewed→completed - Set
cleanup_dateandcompleted_datein frontmatter
T-7.7: Summary
Report:
- Files cleaned
- Debt removed (what and where)
- Formatter/import tool used
- Status: completed