speckit-implement

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Overview

This skill bridges SpecKit planning with Linear/Beads execution tracking.

Architecture: Linear is the source of truth. Beads is a local cache. See Linear Workflow Guide.

Modes:

• •No arguments: Auto-select first ready task
• •With selector: Implement specific task (number, Task ID T###, or Linear ID FLO-###)

CRITICAL: Spec Context Loading (MANDATORY)

You MUST load ALL spec artifacts into context BEFORE implementing any task.

This is NON-NEGOTIABLE. Implementation without full spec context leads to:

• •Deviations from agreed design
• •Missing requirements
• •Inconsistent architecture decisions
• •Wasted rework

Required Artifacts (Load All)

Loading Protocol

At the START of every implementation session:

# 1. Identify feature directory
FEATURE_DIR=$(./specify/scripts/bash/check-prerequisites.sh --json | jq -r '.feature_dir')

# 2. Load ALL spec artifacts (use Read tool for each)
Read: $FEATURE_DIR/spec.md
Read: $FEATURE_DIR/plan.md
Read: $FEATURE_DIR/tasks.md
Read: $FEATURE_DIR/research.md       # if exists
Read: $FEATURE_DIR/data-model.md     # if exists
Read: $FEATURE_DIR/contracts/*.md    # if exists
Read: .specify/memory/constitution.md

After context compaction: Re-read ALL artifacts immediately. The summary may lose critical details.

During implementation: Reference spec.md and plan.md continuously. Every decision must align with the documented design.

Memory Integration

Before Starting

Search for relevant implementation patterns:

./scripts/memory-search "implementation patterns for {component type}"

Query patterns:

• •For plugins: "plugin implementation patterns"
• •For schemas: "Pydantic schema patterns"
• •For tests: "testing patterns for {feature}"

After Completion

Save key decisions for future sessions:

./scripts/memory-save --decisions "{key decisions made}" --issues "{LinearIDs}"

What to save:

• •Implementation patterns that worked well
• •Gotchas and edge cases discovered
• •Architecture decisions made during implementation

Constitution Alignment

This skill enforces project principles from .specify/memory/constitution.md:

• •TDD: Tests first, implementation second
• •SOLID: Single responsibility, clean interfaces
• •Atomic Commits: 300-600 LOC per commit, focused changes

Outline

1. •

   Setup & Sync

   • •Run .specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks from repo root
   • •Parse JSON output for FEATURE_DIR
   • •Verify .linear-mapping.json exists in FEATURE_DIR (run /speckit.taskstolinear if missing)
   • •If Beads CLI available (bd), sync from Linear: bd linear sync --pull
2. •

   Find Ready Tasks

   • •Load $FEATURE_DIR/.linear-mapping.json for task-to-Linear mappings
   • •For each task in mapping, query Linear via mcp__plugin_linear_linear__get_issue for current status
   • •Build ready list: issues with status typebacklog
   • •Display ready tasks with: number, Task ID, Linear identifier, title
3. •

   Task Selection

   • •Parse $ARGUMENTS for selector (first token):
     • •Empty: auto-select first ready task
     • •Number (1, 2, 3): position in displayed ready list
     • •Task ID (T001, T042): match by task ID in mapping
     • •Linear ID (FLO-33, FLO-108): match by Linear identifier
   • •Verify task not blocked: query with includeRelations: true, check blockedBy is empty
   • •ERROR if blocked and show which issues block it
4. •

   Claim Task

   • •Query team statuses via mcp__plugin_linear_linear__list_issue_statuses (team: "floe")
   • •You MUST update Linear via mcp__plugin_linear_linear__update_issue:
     • •id: Linear issue ID
     • •state: "In Progress"
     • •assignee: "me"
   • •Display confirmation with Linear URL
5. •

   Load Context (CRITICAL - See "Spec Context Loading" above)

   • •Load ALL spec artifacts per the CRITICAL section above:
     • •$FEATURE_DIR/spec.md - Full feature specification
     • •$FEATURE_DIR/plan.md - Architecture and design decisions
     • •$FEATURE_DIR/tasks.md - Parse task line for phase, user story, description
     • •$FEATURE_DIR/research.md - Technology research (if exists)
     • •$FEATURE_DIR/data-model.md - Schema design (if exists)
     • •$FEATURE_DIR/contracts/*.md - Contract definitions (if exists)
     • •.specify/memory/constitution.md - Project principles
   • •This is NON-NEGOTIABLE - do NOT proceed without full context
   • •Display: phase, user story, task description, Linear URL
   • •Use Explore subagents to ensure you deeply understand the codebase and target architecture
   • •Validate any ambiguity with the AskUserQuestions tool
6. •

   Implementation

   • •Follow constitution principles: TDD (tests first), SOLID, atomic commits (300-600 LOC)
   • •Implement per task description from tasks.md
   • •Use project's existing patterns and tooling
   • •Reference spec.md and plan.md for context

   Cleanup (REQUIRED for refactors): When changing existing code, you MUST clean up:

   • •Remove replaced code - don't leave old implementations behind
   • •Remove orphaned tests - tests for removed code should be deleted
   • •Remove unused imports - ruff check --select F401 on changed files
   • •Update __all__ exports - remove exports that no longer exist

   Quick cleanup check:

   bash

   # Find unused imports in changed files
   git diff HEAD~1 --name-only -- '*.py' | xargs -I{} uv run ruff check {} --select F401,F811
   

   Principle: Leave the codebase cleaner than you found it.

7. •

   Integration Check (Per-Task) Before closing a task, verify deliverables are integrated into the system:

   For new modules/classes:

   • • Imported by at least one other file in src/ (not just tests)
   • • Has a path to an entry point (CLI command, plugin registry, or package __all__)

   For plugin implementations:

   • • Entry point registered in pyproject.toml under [project.entry-points]
   • • Plugin discoverable via PluginRegistry.get_plugins()

   For new schemas:

   • • Added to CompiledArtifacts or exported from package
   • • Has a consumer that imports it

   Quick integration check:

   bash

   # Verify new files are imported somewhere in src/
   for f in $(git diff HEAD~1 --name-only --diff-filter=A -- '*.py' | grep '/src/'); do
     basename="${f##*/}"
     module="${basename%.py}"
     grep -r "from.*import.*$module\|import.*$module" $(dirname $f)/.. --include="*.py" | grep -v test | head -1
   done
   

   If new code isn't reachable: Wire it up before closing the task. Add a wiring commit if needed.

8. •

   Validation

   • •Run checks appropriate to what was implemented:
     • •Python: uv run mypy --strict, uv run ruff check, uv run pytest <relevant tests>
     • •Helm: helm lint, helm template | kubectl apply --dry-run=client -f -
     • •General: verify code imports, builds, integrates with existing code
   • •Block closure if validation fails - fix issues first
9. •

   Close Task

   • •Ask user confirmation via AskUserQuestion tool
   • •Query statuses again, find status with type completed (usually "Done")
   • •You MUST update Linear status via mcp__plugin_linear_linear__update_issue
   • •MANDATORY: Create Linear comment via mcp__plugin_linear_linear__create_comment:
     code

     **Completed**: {TaskID}
     **Summary**: {what was implemented}
     **Commit**: {commit hash or "See latest commit"}
     **Files Changed**: {key files}
     ---
     *Closed via /speckit.implement*
     

   • •Commit changes with message: {type}(scope): {title} ({TaskID}, {LinearID})
   • •Example: feat(plugin-api): add PluginMetadata ABC (T001, FLO-33)
10. •

    Continue or Complete

• •Query Linear for remaining ready tasks (status type unstarted or backlog)
• •If more tasks: ask user "Continue to next task?" via AskUserQuestion
• •If yes: loop back to step 2
• •If no or none remaining: display session summary and Linear project URL

1. •Save Session Decisions (end of session):
   • •If implementation involved significant decisions, save them for future reference:
     bash

     ./scripts/memory-save --decisions "{key decisions made}" --issues "{LinearIDs}"
     

   • •This enables future sessions to recover context and maintain consistency
   • •If agent-memory unavailable, decisions are captured in Linear comments (step 8)

Tool Patterns

Linear MCP tools (never hardcode status names - always query first):

Status type mapping:

• •unstarted: "Todo" (ready to work)
• •backlog: "Backlog" (ready to work)
• •started: "In Progress" (claimed)
• •completed: "Done" (finished)
• •canceled: "Canceled" (abandoned)

Key Rules

1. •

   Never hardcode status names - Teams can customize "In Progress" to anything. Always query list_issue_statuses and match by type field.

2. •

   Always create Linear comment on closure - The bd close --reason stores in Beads only. Team members viewing Linear need the comment for context.

3. •

   Include both IDs in commit message - Format: {type}(scope): {title} ({TaskID}, {LinearID}) enables traceability from git history.

4. •

   Block closure on validation failure - Never mark a task "Done" if tests fail or code doesn't build.

5. •

   Verify not blocked before claiming - Query with includeRelations: true to check blockedBy array.

Error Handling

Handoff

After completing this skill:

• •Review tests: Run /speckit.test-review to validate test quality
• •Continue implementing: Run /speckit.implement again for next task
• •Batch implementation: Run /speckit.implement-epic for automatic continuation

References

• •Linear Workflow Guide - Architecture, traceability, detailed patterns
• •speckit.tasks - Generate tasks.md
• •speckit.taskstolinear - Create Linear issues from tasks
• •.specify/memory/constitution.md - Project principles (TDD, SOLID, atomic commits)
• •Memory Scripts - ./scripts/memory-{search,save,add} for knowledge graph integration