GitHub specification integration and verification

version
4.0.1
GitHub stars
372

Install

/plugin install github-spec-kit@developer-kit

Run it inside Claude Code after adding the marketplace with /plugin marketplace add giuseppe-trisciuoglio/developer-kit.

Contents

Discovered from source

Commands 3

Check Task Integration with Codebase

Overview

Validates that tasks.md considers existing codebase implementations and integration opportunities before execution. Use when you need to check task alignment with the current codebase.

Usage

/speckit.check-integration $ARGUMENTS

Arguments

ArgumentDescription
$ARGUMENTSCombined arguments passed to the command

Execution Steps

Execution Instructions

Agent Selection: To execute this task, use the following approach:

  • Primary: Use general-purpose agent with appropriate domain expertise
  • Or use specialized agent if available for the specific task type

User Input

$ARGUMENTS

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

Outline

Goal: Analyze tasks.md to verify each task considers existing codebase implementations, integration opportunities, and architectural compatibility. This is a READ-ONLY analysis command that reports findings without modifying any files.

When to run: After /speckit.tasks generates tasks.md but BEFORE /speckit.implement executes them.

Critical Principle: This command NEVER modifies code, tasks, or any files. It only analyzes and reports.

1. Setup & Prerequisites

Run .specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks from repo root and parse JSON for:

  • FEATURE_DIR (absolute path)
  • TASKS file path
  • AVAILABLE_DOCS list

For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").

Abort if tasks.md is missing with error: "No tasks.md found. Run /speckit.tasks first."

2. Load Context

Required files:

  • tasks.md: Complete task list with file paths and descriptions
  • plan.md: Tech stack, architecture, dependencies
  • spec.md: Feature requirements and scope

Optional files (load if present):

  • data-model.md: Entity definitions
  • contracts/: API specifications
  • research.md: Technical decisions

Codebase scan:

  • Identify project root structure (src/, lib/, components/, etc.)
  • List existing dependencies from package.json/requirements.txt/etc.
  • Map existing modules, services, utilities, components
  • Identify configuration files (database, API, environment)

3. Build Codebase Inventory

Create internal mapping of existing implementations:

Infrastructure & Configuration:

  • Database setup, migrations, ORM configurations
  • API framework initialization (Express, FastAPI, etc.)
  • Authentication/authorization systems
  • Logging, monitoring, error handling utilities
  • Environment configuration patterns

Data Layer:

  • Existing models/entities with fields and relationships
  • Database access patterns (repositories, DAOs)
  • Data validation utilities
  • Schema management approaches

Service Layer:

  • Business logic services
  • Integration services (external APIs, third-party)
  • Utility services (email, notifications, file handling)
  • Caching mechanisms

API Layer:

  • Existing endpoints and route patterns
  • Request/response handlers
  • Middleware (auth, validation, error handling)
  • API versioning approach

UI Components (if applicable):

  • Component library and design system
  • Layout components
  • Shared utilities (hooks, contexts)
  • State management patterns

Testing Infrastructure:

  • Test frameworks and utilities
  • Mock/fixture patterns
  • Test database setup
  • CI/CD test integration

4. Analyze Each Task

For every task in tasks.md, perform this structured analysis:

A. Existing Implementation Detection

Scan for:

  • Similar functionality already implemented
  • Overlapping components/modules
  • Duplicate data models or entities
  • Redundant API endpoints
  • Existing utilities that solve the same problem

Output for each finding:

EXISTING: [File path]
Lines: [Line range]
Description: [What it does]
Similarity: [HIGH/MEDIUM/LOW]
Reason: [Why it's relevant to this task]
B. Integration Opportunity Analysis

Check if task can:

  • Extend existing components rather than create new ones
  • Reuse existing utilities/helpers
  • Integrate with established patterns
  • Leverage installed dependencies
  • Follow existing architectural patterns

Output for each opportunity:

INTEGRATION: [Approach]
With: [Existing component/pattern]
Benefit: [Why integration is better than from-scratch]
Risk: [Potential conflicts or limitations]
C. Dependency & Library Check

Verify:

  • Required libraries already installed
  • Similar functionality in existing dependencies
  • Configuration already present
  • Patterns already established in codebase

Output:

DEPENDENCY: [Package/library name]
Status: [INSTALLED/NOT_INSTALLED]
Usage: [Where used in codebase]
Alternative: [If similar functionality exists]
D. Architectural Compatibility

Assess:

  • Task aligns with existing architecture
  • File structure matches project conventions
  • Naming conventions consistency
  • Design patterns compatibility

Output:

COMPATIBILITY: [ALIGNED/PARTIAL/MISALIGNED]
Architecture: [Current pattern in codebase]
Task Approach: [What task proposes]
Concern: [If any conflicts detected]

5. Task-Level Evaluation

For each task, answer these questions:

Integration Assessment:

  • CONSIDERS - Task explicitly mentions existing code to integrate with
  • PARTIAL - Task could integrate but doesn't mention existing code
  • IGNORES - Task proposes from-scratch solution when integration possible
  • NEW - Task is genuinely new, no existing code applies

Codebase Awareness:

  • AWARE - Task references existing patterns/utilities/components
  • UNAWARE - Task doesn't consider relevant existing implementations

Duplication Risk:

  • NONE - No overlap with existing code
  • LOW - Minor overlap, integration not critical
  • MEDIUM - Significant overlap, integration recommended
  • HIGH - Major overlap, integration mandatory
  • CRITICAL - Duplicates existing functionality, task should be rewritten

6. Generate Analysis Report

Output a structured Markdown report (DO NOT write to file, display only):

Task Integration Analysis Report

Feature: [Feature name from tasks.md] Analysis Date: [Current date] Tasks Analyzed: [Total count]


Executive Summary

Overall Status: [READY/NEEDS_REVIEW/CRITICAL_ISSUES]

Key Findings:

  • Tasks with high integration opportunities: X
  • Tasks with duplication risk: X
  • Tasks ignoring existing code: X
  • New dependencies needed: X
  • Existing dependencies reusable: X

Recommendation: [Proceed/Review tasks/Rewrite specific tasks]


Detailed Task Analysis

For each task with findings (skip tasks with all-clear status):

Task [ID]: [Task Name]

Description: [Brief task description]

Files Referenced: [List from tasks.md]

Integration Assessment: [CONSIDERS/PARTIAL/IGNORES/NEW]

Codebase Awareness: [AWARE/UNAWARE]

Duplication Risk: [NONE/LOW/MEDIUM/HIGH/CRITICAL]


Existing Implementations Found:

FileLinesSimilarityDescription
[path][range][HIGH/MED/LOW][What it does]

Integration Opportunities:

  1. [Opportunity description]
    • With: [Existing component]
    • Benefit: [Why better]
    • Approach: [How to integrate]
    • Effort: [Estimated complexity]

Missing Considerations:

  • Task should mention [specific existing code]
  • Task should integrate with [pattern/utility]
  • Task should reuse [dependency/library]
  • Task should follow [architectural pattern]

Dependencies Status:

DependencyStatusCurrent UseNote
[package][INSTALLED/NEW][where used][recommendation]

Architectural Alignment:

  • Current pattern: [Description]
  • Task approach: [Description]
  • Compatibility: [ALIGNED/PARTIAL/MISALIGNED]
  • Recommendation: [If needed]

Risk Matrix

Task IDRisk LevelTypeImpactMitigation
T001πŸ”΄ CRITICALDuplicationHighRewrite task to extend existing component
T015🟑 MEDIUMIntegrationMediumReference existing pattern in task description
T023🟒 LOWAwarenessLowConsider using existing utility

Codebase Integration Summary

By Category:

CategoryTasksIntegration OpportunitiesDuplication RisksStatus
SetupXX opportunitiesX risks[icon + status]
Data ModelsXX opportunitiesX risks[icon + status]
ServicesXX opportunitiesX risks[icon + status]
API EndpointsXX opportunitiesX risks[icon + status]
UI ComponentsXX opportunitiesX risks[icon + status]
TestsXX opportunitiesX risks[icon + status]

Dependencies Analysis

Already Installed (can be reused):

  • [Package]: Used in [files], supports [tasks]
  • [Package]: Used in [files], supports [tasks]

Need Installation (genuinely new):

  • [Package]: Required for [tasks], purpose: [reason]

Potentially Redundant (alternatives exist):

  • [Package proposed]: Alternative: [existing package], used in [files]

Architectural Patterns

Existing Patterns (should be followed):

  • Data access: [Pattern], used in [files]
  • API structure: [Pattern], used in [files]
  • Error handling: [Pattern], used in [files]
  • Configuration: [Pattern], used in [files]

Pattern Alignment by Task Phase:

  • Setup Phase: [Aligned/Issues]
  • Data Models Phase: [Aligned/Issues]
  • Services Phase: [Aligned/Issues]
  • API Phase: [Aligned/Issues]

Recommendations

High Priority (Address before /speckit.implement)
  1. Task [ID]: [Specific recommendation]
    • Issue: [Description]
    • Existing code: [Reference]
    • Suggested fix: [How to revise task]
Medium Priority (Consider during implementation)
  1. Task [ID]: [Specific recommendation]
    • Integration opportunity: [Description]
    • Benefit: [Why it matters]
Low Priority (Optional improvements)
  1. Task [ID]: [Specific recommendation]

Integration Checklist

Use this to verify tasks have been updated appropriately:

  • All CRITICAL duplication risks addressed
  • HIGH-risk integration opportunities incorporated
  • Existing utilities/patterns referenced in relevant tasks
  • New dependencies justified (no existing alternatives)
  • Architectural patterns acknowledged
  • File paths align with existing structure
  • Naming conventions consistent with codebase

Next Steps

If CRITICAL issues found:

  1. Review and update tasks.md manually based on recommendations
  2. Re-run /speckit.check-integration to verify fixes
  3. Proceed to /speckit.implement when clear

If MEDIUM issues found:

  • You may proceed to /speckit.implement but review recommendations
  • Consider integration opportunities during implementation
  • Flag for post-implementation refactoring if needed

If LOW/NONE issues:

  • βœ… Tasks are integration-aware
  • βœ… Safe to proceed with /speckit.implement

Analysis Principles

What This Command Does

βœ… DOES:

  • Read codebase to find existing implementations
  • Identify integration opportunities
  • Detect potential duplication
  • Check dependency status
  • Verify architectural alignment
  • Report findings with specific file/line references
  • Provide concrete recommendations

❌ DOES NOT:

  • Modify any files (strictly read-only)
  • Rewrite tasks automatically
  • Change codebase
  • Execute tasks
  • Make assumptions without evidence
  • Hallucinate implementations

Analysis Quality Standards

Evidence-Based:

  • Every finding MUST cite specific files/lines
  • No speculation about "probably exists"
  • If uncertain, mark as "Needs Manual Verification"

Actionable:

  • Each recommendation includes specific next steps
  • Reference exact files/components to integrate with
  • Provide integration approach suggestions

Risk-Calibrated:

  • CRITICAL: Blocks implementation, must fix
  • HIGH: Strongly recommend addressing
  • MEDIUM: Consider during implementation
  • LOW: Optional improvement

Context-Aware:

  • Consider project size and maturity
  • Respect existing architectural decisions
  • Balance purity vs pragmatism
  • Account for technical debt tradeoffs

Efficiency Guidelines

Progressive Scanning:

  • Load files on-demand (don't dump everything)
  • Focus on high-signal areas first
  • Skip obviously unrelated code

Token Management:

  • Summarize large files (don't quote entire contents)
  • Reference by path + line range, not full code blocks
  • Group similar findings

Report Sizing:

  • Limit to 50 most important findings
  • Summarize remainder in overflow section
  • Prioritize by risk level

Validation

Before outputting report, verify:

  • Every finding cites specific file/line evidence
  • Risk levels assigned consistently
  • Recommendations are specific and actionable
  • No modifications made to any files
  • Report is concise yet complete (token-efficient)
  • Integration opportunities clearly explained
  • Duplication risks quantified with specifics
  • Dependencies checked against actual project files

Context

$ARGUMENTS


Examples

/speckit.check-integration example-input

Task Workflow Optimization for tasks.md

Overview

Provides task workflow optimization by analyzing dependencies, parallelization opportunities, and subagent delegation strategy for tasks.md. Use when you need to improve task execution efficiency.

Usage

/speckit.optimize $ARGUMENTS

Arguments

ArgumentDescription
$ARGUMENTSCombined arguments passed to the command

Execution Steps

Execution Instructions

Agent Selection: To execute this task, use the following approach:

  • Primary: Use general-purpose agent with appropriate domain expertise
  • Or use specialized agent if available for the specific task type

User Input

$ARGUMENTS

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

Outline

Goal: Analyze tasks.md to optimize the implementation workflow by identifying parallelization opportunities, task dependencies, resource requirements, and generating an optimized execution plan with subagent delegation strategy. This command prepares tasks.md for efficient execution via /speckit.implement.

When to run: After /speckit.check-integration completes, BEFORE /speckit.implement executes tasks.

Critical Principle: This command NEVER modifies tasks.md or code files. It only analyzes and reports optimization recommendations. Output is a READ-ONLY optimization report.

1. Setup & Prerequisites

Run .specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks from repo root and parse JSON for:

  • FEATURE_DIR (absolute path)
  • TASKS file path
  • AVAILABLE_DOCS list

For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").

Abort if tasks.md is missing with error: "No tasks.md found. Run /speckit.tasks first."

2. Load Optimization Context

Required files:

  • tasks.md: Complete task list with phases, IDs, descriptions, and parallelization markers [P]
  • plan.md: Tech stack, architecture, team structure
  • spec.md: Feature requirements and complexity assessment

Optional files (load if present):

  • data-model.md: Data dependencies between tasks
  • contracts/: API contract dependencies
  • research.md: Technical constraints and decisions

Codebase scan:

  • Identify project structure and complexity
  • Map existing test patterns (unit, integration, e2e)
  • Assess resource requirements (memory, CPU, external services)
  • List available subagent types from available configuration

3. Parse Tasks Structure

Extract task information:

For each task in tasks.md:
- Task ID: Extract [ID] (e.g., T001, T126)
- Parallelization marker: Extract [P] if present
- Phase: Which phase/group task belongs to
- Description: Full task description
- Dependencies: Infer from description or explicit phase ordering
- Complexity: Assess as LOW/MEDIUM/HIGH/CRITICAL based on:
  * Lines of code expected
  * Test coverage required
  * External dependencies (databases, APIs)
  * Integration points

4. Dependency Analysis

Build dependency graph:

Task β†’ Task Dependencies Analysis:

CRITICAL (blocking):
- Phase 1 β†’ Phase 2 (Phase 2 blocked until Phase 1 complete)
- Phase 2 β†’ Phase 3+ (Phase 3+ blocked until Phase 2 complete)
- Within-phase: Tasks without [P] marker may have implicit dependencies

IMPLICIT DEPENDENCIES:
- T002 (pom.xml) β†’ T018 (configuration properties)
- Configuration tasks β†’ Infrastructure implementation
- Domain models β†’ Repository implementations
- Service implementations β†’ Test infrastructure

Output:

DEPENDENCY ANALYSIS

Blocking Dependencies (Sequential):
- Phase 1 β†’ Phase 2: [BLOCKING] Phase 1 must complete before Phase 2 starts
- Phase 2 β†’ User Stories: [BLOCKING] Foundational layer required for all user story work

Critical Internal Dependencies:
- [Task A] β†’ [Task B]: [Reason] (Must complete A before starting B)
- [Task X] β†’ [Task Y/Z]: [Reason] (Task X blocks multiple dependents)

Independent Task Groups (Can parallelize):
- Group [N]: Tasks [ID, ID, ID] - All marked [P], no internal dependencies
  * Estimated parallel execution time: [minutes]
  * Resource requirement: [CPU/Memory profile]

5. Parallelization Opportunities

Identify parallelizable task groups:

PARALLELIZATION STRATEGY

Within-Phase Parallelization:
- [P] marked tasks: Can run simultaneously (different files, no dependencies)
- Grouped by agent type for efficient team allocation

Potential Parallelization:
- Tasks that could be parallelized with refactoring
- Risks: List any hidden dependencies or integration points
- Recommendation: Whether to parallelize or keep sequential

Sequential Requirements:
- Tasks that MUST run serially (blocking relationships)
- Reasons: Dependency chains, shared state, integration points

6. Subagent Assignment Strategy

Analyze workload distribution:

SUBAGENT DELEGATION ANALYSIS

Task Distribution by Complexity:
- CRITICAL tasks: [Count] (needs expert/experienced subagent)
- HIGH tasks: [Count] (needs intermediate subagent)
- MEDIUM tasks: [Count] (can distribute across team)
- LOW tasks: [Count] (can batch or auto-run)

Required Subagent Types:
- spring-boot-backend-development-expert: [Task IDs] - [Time estimate]
- spring-boot-test-expert: [Task IDs] - [Time estimate]
- [Other specialists]: [Task IDs] - [Time estimate]

Resource Constraints:
- Concurrent subagents available: [N]
- Time per subagent batch: [minutes]
- Memory per subagent: [MB estimate]

7. Execution Phases & Timeline

Generate optimized execution plan:

OPTIMIZED EXECUTION PLAN

Phase 1: Setup (Shared Infrastructure)
β”œβ”€ Batch 1.1 [PARALLEL] (5-10 min):
β”‚  β”œβ”€ Agent: spring-boot-backend-development-expert
β”‚  β”‚  └─ T001: Create DDD aggregate structure
β”‚  β”‚     β€’ Resource: MEDIUM
β”‚  β”‚     β€’ Depends on: None
β”‚  β”‚     β€’ Blocks: T002, T003, T126
β”‚  β”‚
β”‚  β”œβ”€ Agent: spring-boot-test-expert
β”‚  β”‚  └─ T004: Setup Testcontainers
β”‚  β”‚     β€’ Resource: MEDIUM
β”‚  β”‚     β€’ Depends on: None
β”‚  β”‚     β€’ Blocks: All test tasks
β”‚
β”œβ”€ Batch 1.2 [PARALLEL] (10-15 min):
β”‚  β”œβ”€ Agent: spring-boot-backend-development-expert
β”‚  β”‚  β”œβ”€ T002: Add dependencies to pom.xml
β”‚  β”‚  β”‚  β€’ Resource: MEDIUM
β”‚  β”‚  β”‚  β€’ Depends on: T001
β”‚  β”‚  β”‚  β€’ Blocks: T003, Configuration
β”‚  β”‚  β”œβ”€ T003: Configure application.yml
β”‚  β”‚  β”‚  β€’ Resource: MEDIUM
β”‚  β”‚  β”‚  β€’ Depends on: T001, T002
β”‚  β”‚  β”‚  β€’ Blocks: Runtime configuration tasks
β”‚  β”‚  └─ T126: Create CodeContextProperties
β”‚  β”‚     β€’ Resource: MEDIUM
β”‚  β”‚     β€’ Depends on: T001, T003
β”‚  β”‚     β€’ Blocks: T127, T128
β”‚  β”‚
β”‚  └─ Agent: spring-boot-backend-development-expert
β”‚     β”œβ”€ T127: ThreadPoolConfiguration service
β”‚     β”‚  β€’ Resource: HIGH
β”‚     β”‚  β€’ Depends on: T126
β”‚     β”‚  β€’ Blocks: T128
β”‚     β”œβ”€ T128: Async task execution config
β”‚     β”‚  β€’ Resource: HIGH
β”‚     β”‚  β€’ Depends on: T127
β”‚     β”‚  β€’ Blocks: Async operations
β”‚     β”œβ”€ T156: BatchEmbeddingConfiguration
β”‚     β”‚  β€’ Resource: HIGH
β”‚     β”‚  β€’ Depends on: T003
β”‚     β”‚  β€’ Blocks: T157, T158, T159
β”‚     β”œβ”€ T157: Adaptive batch sizing service
β”‚     β”‚  β€’ Resource: HIGH
β”‚     β”‚  β€’ Depends on: T156
β”‚     β”‚  β€’ Blocks: T159
β”‚     β”œβ”€ T158: Batch monitoring & metrics
β”‚     β”‚  β€’ Resource: MEDIUM
β”‚     β”‚  β€’ Depends on: T156
β”‚     β”‚  β€’ Blocks: None
β”‚     └─ T159: Batch optimization tests
β”‚        β€’ Resource: HIGH
β”‚        β€’ Depends on: T156, T157, T158
β”‚        β€’ Blocks: None

Phase 1 Validation Checkpoint:
β”œβ”€ Execute: mvn clean compile
β”œβ”€ Execute: mvn clean test-compile
β”œβ”€ Execute: mvn test
└─ Status: [READY/BLOCKED]

Estimated Total Duration Phase 1:
- Sequential path (critical path): [X] minutes
- With optimal parallelization: [Y] minutes (Z% reduction)
- Wall-clock time (assuming N concurrent subagents): [W] minutes

8. Resource Estimation

Calculate resource requirements:

RESOURCE REQUIREMENTS ANALYSIS

Memory Usage Profile:
- Setup Phase: [MB]
- Per parallel subagent: [MB]
- Testing infrastructure: [MB]
- Total peak: [MB]

CPU Requirements:
- Compilation tasks: MEDIUM (can share)
- Test execution: HIGH (parallel benefit significant)
- Code generation: MEDIUM

External Dependencies:
- Docker/Testcontainers: [Yes/No] β†’ Startup time [minutes]
- Database services: [Services listed] β†’ Availability window [minutes]
- API mock servers: [Services listed] β†’ Setup time [minutes]

Network Bandwidth:
- Dependency download: [MB]
- Docker image pulls: [MB]
- Artifact uploads: [MB]

9. Risk Assessment

Identify optimization risks:

RISK ASSESSMENT

High-Risk Dependencies:
- [Risk]: Task A depends on Task B completing and compiling
  * Mitigation: Run immediate validation after B completes
  * Impact if fails: Cascading failure to all dependent tasks

Integration Points:
- [Point]: Configuration tasks must synchronize state
  * Mitigation: Validate configuration after each phase batch
  * Impact if fails: Runtime errors in downstream phases

Parallelization Risks:
- [Risk]: Tasks T002 and T003 both modify configuration
  * Mitigation: Enforce sequential ordering (already done with [P] marker)
  * Impact if fails: Configuration conflicts, merge issues

10. Optimization Recommendations

Generate specific recommendations:

OPTIMIZATION RECOMMENDATIONS

Priority 1: Critical Path Optimization
1. **Parallelize Setup Phase Batches**
   - Current: [X] minutes (assuming sequential)
   - Optimized: [Y] minutes (batches: B1.1 β†’ B1.2)
   - Savings: [Z]% with [N] concurrent subagents
   - Implementation: Assign T002/T003/T126 to Batch 1.2 (after T001)

2. **Pre-compile Dependency Resolution**
   - Recommendation: Run `mvn dependency:resolve` once
   - Benefit: Avoid repeated downloads in parallel builds
   - Timing: Before starting any compilation tasks

Priority 2: Subagent Utilization
1. **Dedicate Specialists by Phase**
   - Phase 1.1: 1x backend-expert (T001), 1x test-expert (T004)
   - Phase 1.2: 1x backend-expert (T002-T159 cohort)
   - Benefit: Specialized focus, reduced context-switching

2. **Batch Similar Tasks**
   - Group T126/T127/T128: Configuration & threading (coherent scope)
   - Group T156/T157/T158/T159: Batch optimization (coherent scope)
   - Benefit: Reduced cognitive load, better error handling

Priority 3: Checkpoint Strategy
1. **Insert Compilation Checkpoints**
   - After T001: Run `mvn clean compile` (validate structure)
   - After T002/T003: Run `mvn clean compile` (validate config)
   - After T004: Run `mvn test-compile` (validate test setup)
   - Benefit: Catch errors early before downstream tasks start

2. **Test Validation Sequence**
   - Phase 1 complete β†’ Run `mvn test` immediately
   - Blocks: All user story work until Phase 1 tests pass
   - Benefit: Prevent cascading test failures

Priority 4: Error Recovery
1. **Graceful Failure Handling**
   - If Phase 1.1 fails: Halt all Phase 1.2+ tasks
   - If Phase 1 compilation fails: Stop parallel execution, investigate sequentially
   - Recovery: Re-run failed task batch after fix

2. **Subagent Reassignment**
   - If subagent crashes: Reassign task to backup subagent
   - Track completion: Mark task [X] only after validation passes
   - Retry policy: 2 attempts per task before manual escalation

11. Execution Phase Table

Generate an aggregated phase view (no time column) that groups tasks by phase, highlights the responsible subagent, and captures the validation check for each phase:

PHASE EXECUTION MATRIX
══════════════════════════════════════════════════════════════════════════════

 Phase β”‚ Execution Mode β”‚ Subagent            β”‚ Tasks (Grouped)                     β”‚ Check Action
───────┼────────────────┼─────────────────────┼──────────────────────────────────────┼──────────────────────────────
 1.1   β”‚ Parallel       β”‚ Backend Expert      β”‚ [T001] DDD Structure                β”‚ mvn clean compile
       β”‚                β”‚                     β”‚ [T004] Testcontainers Setup         β”‚
───────┼────────────────┼─────────────────────┼──────────────────────────────────────┼──────────────────────────────
 1.2A  β”‚ Parallel       β”‚ Backend Expert      β”‚ [T002] Dependencies                 β”‚ mvn clean compile
       β”‚                β”‚                     β”‚ [T003] app.yml                      β”‚
       β”‚                β”‚                     β”‚ [T126] Properties                   β”‚
───────┼────────────────┼─────────────────────┼──────────────────────────────────────┼──────────────────────────────
 1.2B  β”‚ Parallel       β”‚ Backend Expert      β”‚ [T127] ThreadPool Config            β”‚ mvn clean test-compile
       β”‚                β”‚                     β”‚ [T128] Async Execution              β”‚
       β”‚                β”‚                     β”‚ [T158] Batch Monitoring             β”‚
       β”‚                β”‚                     β”‚ [T159] Optimization Tests           β”‚
───────┼────────────────┼─────────────────────┼──────────────────────────────────────┼──────────────────────────────
 1.3   β”‚ Sequential     β”‚ Test Expert         β”‚ [T160] Contract Validation          β”‚ mvn test
       β”‚                β”‚                     β”‚ [T161] Performance Smoke            β”‚
───────┼────────────────┼─────────────────────┼──────────────────────────────────────┼──────────────────────────────
 Done  β”‚ β€”              β”‚ Lead Agent          β”‚ Phase 1 sign-off                    β”‚ βœ… READY

LEGEND:
[Tnnn] = Task ID
Parallel = may run alongside other phases; Sequential = must run one after another
Every phase includes an explicit validation command
Check Action uses mvn/gradle/cli commands or equivalent verification step

12. Output to User

Produce a concise optimization report that leads with the phase table:

  1. Minimal Summary: One sentence (max two) highlighting the primary optimization gain or risk reminder.
  2. Phase Execution Matrix: Present the table from Step 11 exactly once; this is the focal artifact.
  3. Supporting Sections (only if needed): Keep Dependency Analysis, Parallelization Opportunities, Subagent Strategy, Resource Estimation, Risk Assessment, Recommendations, and Next Steps succinctβ€”use bullets and avoid repetition. Skip sections that add no new signal.

Ensure the report keeps the table front-and-center and avoids reintroducing time-based columns.

RECOMMENDED NEXT STEPS

1. βœ… VALIDATE THIS PLAN
   - Review the phase matrix above for feasibility
   - Confirm subagent availability: [N] concurrent agents
   - Confirm resource availability: [MB] peak memory
   - Estimate actual duration: [minutes] (add 20% buffer)

2. πŸ“‹ PREPARE EXECUTION
   - Ensure tasks.md is up-to-date with all task IDs, [P] markers
   - Verify pom.xml, application.yml, test configuration exist
   - Have CI/CD integration ready for compilation checkpoints

3. ⚑ EXECUTE WITH OPTIMIZATION
   - Use `/speckit.implement` with --optimize flag to follow this plan
   - Monitor Phase 1.1 completion before starting Phase 1.2
   - Watch compilation checkpoints - halt if any fail
   - Validate tests pass at end of Phase 1

4. πŸ“Š TRACK PROGRESS
   - Record actual vs estimated effort for each phase
   - Document any blockers or task failures
   - Use data for refining future optimizations

5. πŸš€ PROCEED TO NEXT PHASE
   - After Phase 1 validation passes: Proceed to Phase 2
   - Use same optimization strategy for subsequent phases
   - Adjust subagent assignments based on Phase 1 learnings

Optimization Principles

What This Command Does

βœ… DOES:

  • Analyze task.md for dependencies and parallelization
  • Calculate resource requirements
  • Identify optimal subagent allocation strategy
  • Build a phase-oriented execution plan with batching guidance
  • Provide checkpoint/validation strategy
  • Quantify optimization benefits (time savings, resource efficiency)
  • Recommend risk mitigation approaches

❌ DOES NOT:

  • Modify tasks.md or any files (READ-ONLY)
  • Execute tasks or modify code
  • Make final execution decisions (user validates)
  • Guarantee timing (provides estimates only)
  • Automate subagent assignment (recommends strategy)

Analysis Quality Standards

Evidence-Based:

  • Every timeline estimate based on task complexity assessment
  • Dependency analysis grounded in task descriptions
  • Resource calculations from typical Spring Boot patterns

Actionable:

  • Specific subagent type recommendations
  • Concrete batching strategy with timing
  • Checkpoint strategy with validation steps

Risk-Calibrated:

  • Identify critical path dependencies
  • Highlight parallelization risks
  • Provide mitigation strategies

Token Efficiency

Progressive analysis:

  • Load tasks on-demand
  • Analyze phase-by-phase
  • Summarize large dependency graphs
  • Focus on high-impact optimizations

Compact reporting:

  • Use tables for timeline visualization
  • Group related findings
  • Provide executive summary
  • Link to detailed analysis

Validation

Before outputting report, verify:

  • All task IDs from tasks.md extracted correctly
  • Dependency analysis covers all blocking relationships
  • Timeline accounts for compilation/validation checkpoints
  • Subagent allocation realistic (not over-subscribing)
  • Resource estimates reasonable for Spring Boot stack
  • Risk assessment identifies critical paths
  • Recommendations are specific and implementable
  • Report is concise yet complete (token-efficient)

Context

$ARGUMENTS


Examples

/speckit.optimize example-input

Verify Feature Implementation - Comprehensive Validation

Overview

Validates implementation completion by checking tasks, logic, tests, and code quality against specifications. Use when you need to verify that all tasks are properly completed.

Usage

/speckit.verify $ARGUMENTS

Arguments

ArgumentDescription
$ARGUMENTSCombined arguments passed to the command

Execution Steps

Execution Instructions

Agent Selection: To execute this task, use the following approach:

  • Primary: Use general-purpose agent with appropriate domain expertise
  • Or use specialized agent if available for the specific task type

User Input

$ARGUMENTS

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

Outline

Goal: Perform comprehensive verification of the implemented feature against specifications, ensuring all requirements are met, tests pass, and code quality standards are satisfied. This command runs AFTER /speckit.implement completes.

Critical Principle: This is a READ-ONLY analysis command. The ONLY file that may be written is verification-report.md in the feature directory. No other modifications are permitted.

1. Setup & Prerequisites

Run .specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks from repo root and parse JSON for:

  • FEATURE_DIR (absolute path)
  • AVAILABLE_DOCS list
  • Repository root

For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").

Abort if implementation appears incomplete with guidance to run /speckit.implement first.

2. Load Verification Context

Load artifacts in order (progressive, on-demand):

Required:

  • tasks.md: Verify all tasks marked completed [X]
  • spec.md: Requirements, user stories, acceptance criteria
  • plan.md: Tech stack, architecture, file structure

Optional (load if present):

  • data-model.md: Entity definitions and relationships
  • contracts/: API specifications
  • research.md: Technical decisions and constraints
  • quickstart.md: Integration scenarios
  • checklists/: Quality validation items

Codebase:

  • Implementation files referenced in tasks.md
  • Test files (unit, integration, e2e)
  • Configuration files
  • Documentation updates

3. Task Completion Verification

Check tasks.md:

For each task in tasks.md:

  • Task is marked [X] or [x] (completed)
  • No tasks remain with [ ] (incomplete)
  • All file paths mentioned exist in codebase
  • Implementation addresses task description

Output:

TASK COMPLETION STATUS
Total tasks: X
Completed: X [X%]
Incomplete: X [X%]
Status: [PASS/FAIL]

If incomplete tasks found:

INCOMPLETE TASKS:
- [Task ID]: [Description] β†’ [Reason not completed]

Verification FAILS if any task incomplete unless justified (explicitly marked as deferred/optional in tasks.md).

4. Requirements Coverage Analysis

Map implementation to specification:

For each requirement in spec.md:

A. Functional Requirements
  • Implementation code exists
  • Code logic matches requirement description
  • All acceptance criteria satisfied
  • Edge cases handled
B. Non-Functional Requirements
  • Performance targets met (if specified)
  • Security measures implemented
  • Accessibility requirements satisfied
  • Scalability considerations addressed
C. User Stories
  • All user actions supported
  • Success criteria demonstrable
  • Error scenarios handled gracefully

Output format:

REQUIREMENT: [ID or description]
Status: [COVERED/PARTIAL/MISSING]
Implementation: [File paths]
Evidence: [Specific code references]
Acceptance Criteria Met: X/Y
Issues: [If any]

5. Architecture & Design Compliance

Verify against plan.md:

A. Tech Stack Compliance
  • All specified libraries/frameworks used correctly
  • No unauthorized dependencies introduced
  • Version constraints respected
B. Project Structure
  • Files in expected locations per plan.md
  • Directory structure follows specification
  • Naming conventions consistent
C. Architectural Patterns
  • Separation of concerns maintained
  • Design patterns correctly applied
  • Component boundaries respected
  • Integration points match contracts

Output:

ARCHITECTURE COMPLIANCE
Tech Stack: [COMPLIANT/VIOLATIONS]
- [Package]: [Expected version] β†’ [Actual version] [Status]

Structure: [COMPLIANT/VIOLATIONS]
- [Expected pattern] β†’ [Actual implementation] [Status]

Design Patterns: [COMPLIANT/VIOLATIONS]
- [Pattern]: [Assessment]

6. Data Model Validation

If data-model.md exists:

For each entity:

  • Entity class/model exists
  • All fields present with correct types
  • Relationships implemented correctly
  • Validations in place
  • State transitions (if any) handled

Check:

  • Foreign key constraints
  • Cascade behaviors
  • Index definitions
  • Migration files (if applicable)

Output:

DATA MODEL VERIFICATION
Entity: [Name]
- Fields: [X/Y present, types correct]
- Relationships: [X/Y implemented]
- Validations: [List]
- Status: [PASS/FAIL]

7. Contract Compliance

If contracts/ exists:

For each contract file:

A. API Endpoints
  • Route/path matches contract
  • HTTP methods correct
  • Request schema validation implemented
  • Response schema matches contract
  • Status codes per specification
B. Error Handling
  • All error cases from contract covered
  • Error response format matches contract
  • Appropriate HTTP status codes used
C. Business Logic
  • Implements contract behavior precisely
  • Edge cases from contract handled
  • Validation rules enforced

Output:

CONTRACT: [Filename]
Endpoint: [Method] [Path]
- Route: [MATCH/MISMATCH]
- Request Schema: [VALID/INVALID]
- Response Schema: [VALID/INVALID]
- Error Handling: [COMPLETE/INCOMPLETE]
- Logic Compliance: [PASS/FAIL]
Status: [PASS/FAIL]

8. Test Execution & Coverage

Run test suites:

A. Execute Tests
# Run all test commands from plan.md or infer from project type
npm test              # or pytest, cargo test, etc.
npm run test:coverage # or equivalent
B. Analyze Results
  • All tests pass (100% success rate)
  • No skipped tests (unless explicitly documented)
  • No test warnings or errors
  • Coverage meets threshold (from plan.md or β‰₯90% default)
C. Test Quality
  • Tests cover positive scenarios
  • Tests cover negative/error scenarios
  • Tests cover edge cases and boundaries
  • Tests validate business logic
  • Integration tests verify component interactions
  • E2E tests (if specified) validate user flows

Output:

TEST EXECUTION RESULTS
Total Tests: X
Passed: X [100%/less]
Failed: X
Skipped: X
Duration: Xs

COVERAGE METRICS
Lines: X%
Branches: X%
Functions: X%
Statements: X%
Threshold: Y% [MET/NOT MET]

TEST QUALITY
Positive Scenarios: [COVERED/GAPS]
Negative Scenarios: [COVERED/GAPS]
Edge Cases: [COVERED/GAPS]
Integration: [COVERED/GAPS]

If tests fail:

FAILED TESTS:
[Test suite] β†’ [Test name]
Error: [Message]
File: [Path:Line]
Expected: [Value]
Actual: [Value]

9. Code Quality Assessment

Static Analysis:

A. Linting

Run project linter (ESLint, Pylint, Clippy, etc.):

  • Zero errors
  • Zero warnings (or all justified)
  • Style guide compliance
B. Type Checking

If TypeScript/typed language:

  • No type errors
  • Strict mode compliance
  • No 'any' types (unless justified)
C. Formatting
  • Code formatted consistently
  • Follows project style guide
  • No formatting inconsistencies

Output:

CODE QUALITY SCAN
Linter: [Tool name]
- Errors: X
- Warnings: X
- Status: [PASS/FAIL]

Type Checker:
- Errors: X
- Status: [PASS/FAIL]

Formatter:
- Violations: X
- Status: [PASS/FAIL]

10. Security & Performance Audit

Security Checks:

  • No hardcoded secrets/credentials
  • Input validation on all user inputs
  • SQL injection prevention (parameterized queries)
  • XSS prevention (output encoding)
  • CSRF protection (if web app)
  • Authentication/authorization correct
  • Dependency vulnerabilities scan

Performance Checks:

  • No obvious performance anti-patterns
  • Database queries optimized (indexes, N+1 prevention)
  • No memory leaks
  • Resource cleanup (connections, files)
  • Efficient algorithms (no O(nΒ²) where O(n) possible)

Output:

SECURITY AUDIT
- Hardcoded Secrets: [NONE/FOUND]
- Input Validation: [COMPLETE/GAPS]
- Injection Prevention: [PROTECTED/VULNERABLE]
- Auth/Authz: [CORRECT/ISSUES]
- Dependencies: [SECURE/VULNERABILITIES]
Status: [PASS/FAIL]

PERFORMANCE AUDIT
- Algorithm Efficiency: [OPTIMAL/CONCERNS]
- Database Queries: [OPTIMIZED/ISSUES]
- Resource Management: [PROPER/LEAKS]
Status: [PASS/FAIL]

11. Documentation Verification

Check documentation quality:

  • README updated with new feature (if significant)
  • API documentation matches implementation
  • Complex code has inline comments
  • Public APIs have docstrings/JSDoc
  • quickstart.md reflects current state (if exists)
  • Migration guides (if breaking changes)

Output:

DOCUMENTATION REVIEW
README: [UPDATED/OUTDATED/N/A]
API Docs: [ACCURATE/OUTDATED/MISSING]
Code Comments: [ADEQUATE/SPARSE]
Public APIs: [DOCUMENTED/UNDOCUMENTED]
Status: [PASS/FAIL]

12. Constitution Compliance

If .specify/memory/constitution.md exists:

Check implementation against project principles:

  • Follows mandated practices
  • Respects constraints
  • Adheres to quality standards
  • Meets governance requirements

Output:

CONSTITUTION COMPLIANCE
Principle: [Name]
- Status: [COMPLIANT/VIOLATION]
- Evidence: [Description]

Overall: [COMPLIANT/VIOLATIONS]

13. Checklist Validation

If FEATURE_DIR/checklists/ exists:

For each checklist file:

  • Count total items
  • Count completed [X] or [x] items
  • Count incomplete [ ] items
  • Calculate completion percentage

Output:

CHECKLIST STATUS
| Checklist | Total | Completed | Incomplete | %    | Status |
|-----------|-------|-----------|------------|------|--------|
| ux.md     | 12    | 12        | 0          | 100% | βœ“ PASS |
| api.md    | 15    | 14        | 1          | 93%  | βœ— FAIL |

Overall: [PASS if all 100% / FAIL if any incomplete]

14. Generate Verification Report

Create structured report at FEATURE_DIR/verification-report.md:

# Feature Verification Report

**Feature**: [Name from spec.md]
**Verification Date**: [ISO date]
**Verification Status**: [PASS/FAIL]

---

## Executive Summary

[Overall pass/fail with key metrics]

**Quick Stats**:

- Tasks Completed: X/Y (Z%)
- Requirements Covered: X/Y (Z%)
- Tests Passed: X/Y (Z%)
- Code Quality: [PASS/FAIL]
- Overall Status: [PASS/FAIL]

---

## Task Completion

[Results from step 3]

---

## Requirements Coverage

[Results from step 4]

**Coverage Summary**:

- Functional Requirements: X/Y covered
- Non-Functional Requirements: X/Y covered
- User Stories: X/Y implemented
- Acceptance Criteria: X/Y met

---

## Architecture Compliance

[Results from step 5]

---

## Data Model Validation

[Results from step 6 if applicable]

---

## Contract Compliance

[Results from step 7 if applicable]

---

## Test Results

[Results from step 8]

---

## Code Quality

[Results from step 9]

---

## Security & Performance

[Results from step 10]

---

## Documentation

[Results from step 11]

---

## Constitution Compliance

[Results from step 12 if applicable]

---

## Checklist Status

[Results from step 13 if applicable]

---

## Issues Found

[If FAIL, list all issues with severity]

### Critical Issues

[Must fix before merge]

### High Priority

[Should fix before merge]

### Medium Priority

[Can fix post-merge if needed]

### Low Priority

[Optional improvements]

---

## Remediation Steps

[If FAIL, provide specific actions]

1. **[Issue category]**:
    - File: [Path]
    - Problem: [Description]
    - Fix: [Specific steps]
    - Verification: [How to confirm fixed]

---

## Sign-Off

- [ ] All critical issues resolved
- [ ] All high priority issues resolved
- [ ] Tests pass at 100%
- [ ] Code quality meets standards
- [ ] Documentation updated
- [ ] Ready for review/merge

---

## Next Steps

[If PASS]: Feature ready for [code review/staging/production]
[If FAIL]: Fix issues listed above and re-run `/speckit.verify`

---

## Metrics

| Metric | Target | Actual | Status |
|--------|--------|--------|--------|
| Task Completion | 100% | X% | [βœ“/βœ—] |
| Requirements Coverage | 100% | X% | [βœ“/βœ—] |
| Test Pass Rate | 100% | X% | [βœ“/βœ—] |
| Test Coverage | β‰₯90% | X% | [βœ“/βœ—] |
| Code Quality | 0 errors | X errors | [βœ“/βœ—] |
| Security Issues | 0 | X | [βœ“/βœ—] |

15. Output to User

If PASS:

βœ… VERIFICATION PASSED

Feature implementation successfully verified!

Summary:
- All tasks completed
- All requirements covered
- All tests passing (X% coverage)
- Code quality standards met
- No security issues found

Report: [path to verification-report.md]

Suggested commit message:
feat: complete [feature name] implementation

Next steps:
- Create pull request for review
- Deploy to staging environment
- Update project documentation

If FAIL:

❌ VERIFICATION FAILED

Implementation has issues requiring attention.

Critical Issues: X
High Priority: X
Medium Priority: X

Top Issues:
1. [Issue summary]
2. [Issue summary]
3. [Issue summary]

Full details: [path to verification-report.md]

Next steps:
1. Review verification report
2. Fix critical and high priority issues
3. Re-run `/speckit.verify`

Do NOT proceed to merge until verification passes.

Verification Principles

Strictness Levels

CRITICAL (Must Pass):

  • All tasks completed
  • All requirements covered
  • All tests passing
  • No security vulnerabilities
  • No contract violations

HIGH (Should Pass):

  • Code quality standards
  • Documentation completeness
  • Performance optimization
  • Constitution compliance

MEDIUM (Nice to Pass):

  • Code comments
  • Optimization opportunities
  • Style improvements

LOW (Optional):

  • Minor refactoring suggestions
  • Additional test scenarios

Pass/Fail Criteria

PASS requires:

  • 100% task completion (or justified deferrals)
  • 100% requirements covered
  • 100% test pass rate
  • β‰₯90% test coverage (or plan.md threshold)
  • 0 critical security issues
  • 0 linting errors (warnings acceptable if justified)
  • Contract compliance (if applicable)
  • Architecture compliance

FAIL if any:

  • Incomplete tasks without justification
  • Uncovered requirements
  • Failing tests
  • Coverage below threshold
  • Critical security issues
  • Linting errors
  • Contract violations
  • Architecture violations

Evidence Requirements

Every finding must include:

  • Specific file path and line numbers
  • Concrete evidence (code snippets, test output)
  • Expected vs actual comparison
  • Remediation guidance

No speculation allowed:

  • Don't assume code exists if not found
  • Don't guess at intent
  • Don't hallucinate test results
  • Quote actual output/errors

Token Efficiency

Progressive analysis:

  • Load files on-demand
  • Analyze in phases
  • Stop on critical failures (optional)
  • Summarize verbose output

Compact reporting:

  • Use tables for metrics
  • Group similar issues
  • Link to full details
  • Prioritize actionable items

Context

$ARGUMENTS

Notes

  • This command is READ-ONLY except for writing verification-report.md
  • Verification should be deterministic (same code β†’ same result)
  • Re-run after fixes until PASS achieved
  • Can be run multiple times safely
  • Integrates with CI/CD pipelines
  • Provides audit trail of verification

Examples

/speckit.verify example-input

Sponsors

Details

Marketplace
giuseppe-trisciuoglio/developer-kit
Source
plugins/github-spec-kit
Category
Community

More from giuseppe-trisciuoglio/developer-kit

All 11