
github-spec-kit
GitHub specification integration and verification
- version
- 4.0.1
- GitHub stars
- 372
Install
/plugin install github-spec-kit@developer-kitRun it inside Claude Code after adding the marketplace with /plugin marketplace add giuseppe-trisciuoglio/developer-kit.
Contents
Discovered from sourceCommands 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
| Argument | Description |
|---|---|
$ARGUMENTS | Combined arguments passed to the command |
Execution Steps
Execution Instructions
Agent Selection: To execute this task, use the following approach:
- Primary: Use
general-purposeagent 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:
| File | Lines | Similarity | Description |
|---|---|---|---|
| [path] | [range] | [HIGH/MED/LOW] | [What it does] |
Integration Opportunities:
- [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:
| Dependency | Status | Current Use | Note |
|---|---|---|---|
| [package] | [INSTALLED/NEW] | [where used] | [recommendation] |
Architectural Alignment:
- Current pattern: [Description]
- Task approach: [Description]
- Compatibility: [ALIGNED/PARTIAL/MISALIGNED]
- Recommendation: [If needed]
Risk Matrix
| Task ID | Risk Level | Type | Impact | Mitigation |
|---|---|---|---|---|
| T001 | π΄ CRITICAL | Duplication | High | Rewrite task to extend existing component |
| T015 | π‘ MEDIUM | Integration | Medium | Reference existing pattern in task description |
| T023 | π’ LOW | Awareness | Low | Consider using existing utility |
Codebase Integration Summary
By Category:
| Category | Tasks | Integration Opportunities | Duplication Risks | Status |
|---|---|---|---|---|
| Setup | X | X opportunities | X risks | [icon + status] |
| Data Models | X | X opportunities | X risks | [icon + status] |
| Services | X | X opportunities | X risks | [icon + status] |
| API Endpoints | X | X opportunities | X risks | [icon + status] |
| UI Components | X | X opportunities | X risks | [icon + status] |
| Tests | X | X opportunities | X 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)
- Task [ID]: [Specific recommendation]
- Issue: [Description]
- Existing code: [Reference]
- Suggested fix: [How to revise task]
Medium Priority (Consider during implementation)
- Task [ID]: [Specific recommendation]
- Integration opportunity: [Description]
- Benefit: [Why it matters]
Low Priority (Optional improvements)
- 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:
- Review and update tasks.md manually based on recommendations
- Re-run
/speckit.check-integrationto verify fixes - Proceed to
/speckit.implementwhen clear
If MEDIUM issues found:
- You may proceed to
/speckit.implementbut 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
| Argument | Description |
|---|---|
$ARGUMENTS | Combined arguments passed to the command |
Execution Steps
Execution Instructions
Agent Selection: To execute this task, use the following approach:
- Primary: Use
general-purposeagent 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:
- Minimal Summary: One sentence (max two) highlighting the primary optimization gain or risk reminder.
- Phase Execution Matrix: Present the table from Step 11 exactly once; this is the focal artifact.
- 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
| Argument | Description |
|---|---|
$ARGUMENTS | Combined arguments passed to the command |
Execution Steps
Execution Instructions
Agent Selection: To execute this task, use the following approach:
- Primary: Use
general-purposeagent 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