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

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:

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:

Architectural Alignment:

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

Risk Matrix

Codebase Integration Summary

By Category:

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