Skip to main content
command CX Codex

speckit.check-integration — Claude Code command for tasks.md review

speckit.check-integration reads tasks.md and flags tasks that overlap with code you already have, so you can reuse it instead of writing a second version.

MIT ★ 372 updated 2026-09-10

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add giuseppe-trisciuoglio/developer-kit
/plugin install github-spec-kit@developer-kit
Open on GitHub

What speckit.check-integration does

It reads tasks.md, plan.md and spec.md, then compares every task against what the repository already contains: similar modules, helpers you can reuse, libraries already installed. Findings show up in the chat as a Markdown report. No file gets touched.

The first step runs .specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks from the repo root and parses the paths it returns. From there the command maps the codebase layer by layer: config, models, services, endpoints, components, tests. Each task gets labelled on whether an implementation already exists, whether it can extend something instead of adding a parallel one, whether the dependency is present, whether the approach fits the architecture. Tools available are Read, Glob, Grep and Bash.

The useful slot is after /speckit.tasks and before /speckit.implement. Without tasks.md it stops right away and asks you to generate the task list first. If .specify/scripts/bash/check-prerequisites.sh is missing from the project, setup fails and nothing gets analysed. An optional argument narrows the check to criteria you pass in.

What it helps with

  • spot tasks in tasks.md that repeat code you already have
  • decide which existing helpers and services a task should reuse
  • check whether a task pulls a new library when an installed one covers it
  • compare the task list with the project's architecture before editing anything
  • get a duplication-risk report ahead of /speckit.implement

Example prompts for the agent

  • Run /speckit.check-integration and tell me which tasks duplicate existing modules.
  • Check /speckit.check-integration before /speckit.implement so I know what to reuse.
  • Run /speckit.check-integration with criteria limited to the data layer.

How to install speckit.check-integration

1Plugin marketplace

/plugin marketplace add giuseppe-trisciuoglio/developer-kit
/plugin install github-spec-kit@developer-kit

2Manually: put the files in place

.claude/commands/speckit.check-integration.md

Call it with /speckit.check-integration. For all projects use ~/.claude/commands/

Questions about speckit.check-integration

How do I install speckit.check-integration in Claude Code?

From the marketplace: /plugin marketplace add giuseppe-trisciuoglio/developer-kit, then /plugin install github-spec-kit@developer-kit. The command file lands at .claude/commands/speckit.check-integration.md.

What does speckit.check-integration do?

It checks each task in tasks.md against the codebase and reports existing implementations, integration options, dependency status and architectural fit. It modifies nothing.

What has to exist before it runs?

A generated tasks.md and the .specify/scripts/bash/check-prerequisites.sh script in the repository, with the command started from the project root. If the task file is absent it aborts and tells you to run /speckit.tasks first.

Source text

speckit.check-integration.md · MIT
---
description: 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.
argument-hint: "[optional-criteria]"
allowed-tools: Read, Glob, Grep, Bash
---

# 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-purpose` agent with appropriate domain expertise
- Or use specialized agent if available for the specific task type

## User Input

```text
$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**:

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**:

| 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`)

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

```bash
/speckit.check-integration example-input
```

© Giuseppe Trisciuoglio · MIT · giuseppe-trisciuoglio/developer-kit

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set191

The whole set →
aws-cloudformation-bedrock aws-cloudformation-bedrock provides AWS CloudFormation patterns for Amazon Bedrock resources. Generates infrastructure for Bedrock agents, knowledge bases, S3 data sources, and guardrails. CX Codex +1 ★ 372repo stars python-software-architect-expert python-software-architect-expert reviews Python project structure through Clean Architecture, DDD, and SOLID principles. Use it to examine module boundaries or get guidance on architecture decisions. CX Codex ★ 372repo stars aws-architecture-review-expert aws-architecture-review-expert audits CloudFormation templates and AWS architecture against Well-Architected Framework pillars, security standards, and cost risks. CX Codex ★ 372repo stars devkit.generate-document The devkit.generate-document command examines a codebase and drafts structured technical or business documents. Choose a document type, language, and objective. CX Codex +1 ★ 372repo stars devkit.react.code-review devkit.react.code-review audits React 19 and Tailwind CSS codebases against modern patterns, Server Components, and hook conventions prior to merging pull requests. CX Codex +1 ★ 372repo stars aws-cloudformation-cloudfront aws-cloudformation-cloudfront is a Claude Code skill that builds CloudFormation templates for CloudFront distributions, including origins, cache rules, custom domains, WAF, security headers, and logging. CX Codex +1 ★ 372repo stars aws-cloudformation-cloudwatch aws-cloudformation-cloudwatch — a skill that walks through CloudFormation templates for CloudWatch: alarms, dashboards, log groups and metric filters. Useful once monitoring has to live in code. CX Codex +1 ★ 372repo stars python-refactor-expert python-refactor-expert — a subagent for Claude Code refactors Python files without changing runtime behavior. It cleans up architecture, extracts settings, and applies type hints. CX Codex ★ 372repo stars

Project sponsors

Companies that keep this analytics open