# Speck Scan

> Extracts code-side facts at project, epic, or story scope. Use for brownfield work or a fresh reality check.

- Skill: `telum-ai/speck-scan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add telum-ai/speck-scan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/telum-ai/speck-scan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: telum-ai (https://skillmd.com/u/telum-ai)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/telum-ai/speck-scan

---


The user input can be provided directly by the agent or as a command argument — you **MUST** consider it before proceeding with the prompt (if not empty).

User input:

$ARGUMENTS

---

## Purpose

`/speck-scan` extracts code-side facts from an existing codebase and produces a scan artifact that downstream Speck commands consume. One level-aware engine serves project, epic, and story scope.

| Scope | Output artifact | Used by |
|-------|------------------|---------|
| `--level project` | `project-landscape-overview.md` at project root | `/project-specify`, `/project-architecture`, `/project-plan`, `/speck-recheck` |
| `--level epic` | `epic-codebase-scan-<topic>.md` in epic dir | `/epic-specify`, `/epic-plan` |
| `--level story` | `codebase-scan-<topic>.md` in story dir | `/story-specify`, `/story-plan`, `/speck-audit` |

## When to Run

| Trigger | --level | What to do |
|---------|---------|------------|
| Brownfield project init | `project` | Full landscape (tech stack, structure, patterns, conventions) |
| Adding a new epic that touches existing code | `epic` | Topic-scoped scan of affected modules |
| Adding a new story that extends existing code | `story` | Narrow scan of file(s) being modified |
| `/speck-recheck` needs fresh code-side reality | inferred | Re-scan at appropriate level |

## Level Detection (when not specified)

1. If user is in `specs/projects/<id>/epics/<eid>/stories/<sid>/` → default `--level story`
2. If user is in `specs/projects/<id>/epics/<eid>/` → default `--level epic`
3. If user is in `specs/projects/<id>/` or higher → default `--level project`

## Execution by Level

### level project

Produces `project-landscape-overview.md`. Captures:
- Top-level structure (apps, packages, libraries)
- Tech stack (language, framework, build, test, lint, deploy tooling)
- Architectural patterns observed (monolith / microservices / monorepo / etc.)
- External dependencies (databases, third-party services, AI providers, auth)
- Codebase health signals (test coverage, type coverage, lint warnings, recent activity)
- Module boundaries + ownership patterns
- Existing design system / UI primitives (if any) — note for `/project-design-system`
- Recommended epic candidates (functional areas that could become epics)

Output template: `.speck/templates/project/project-landscape-overview-template.md` (use existing template).

### level epic

Produces `epic-codebase-scan-<topic>.md` in `epics/E###-<name>/`. Captures:
- Files and modules in the epic's scope
- Existing patterns relevant to this epic (data flow, error handling, etc.)
- Existing tests covering this area
- Dependencies on other epics' code
- Known issues / debt in this area

### level story

Produces `codebase-scan-<topic>.md` in `stories/S###-<name>/`. Captures:
- Specific files this story will touch
- Existing functions/classes/components to refactor vs extend
- Existing tests covering these surfaces
- Coupling to other surfaces

## Execution Steps

### 1. Detect level (per Level Detection rules above) or use --level arg

### 2. Locate paths

Find `specs/projects/<id>/` (and epic/story dirs as relevant).

### 3. Subagent parallel scan

```
├── [Parallel] speck-explorer: List top-level structure (or scoped)
├── [Parallel] speck-explorer: Detect tech stack (package.json, Cargo.toml, requirements.txt, etc.)
├── [Parallel] speck-scanner: Identify architectural patterns
├── [Parallel] speck-scanner: List external dependencies + integrations
├── [Parallel] speck-scanner: Test coverage + health signals
└── [Wait] → Synthesize into scan artifact
```

### 4. Write the scan artifact

Use the level-appropriate template. Write to the level-appropriate path.

### 5. Apply SHA stamp

```
.speck/scripts/stamp-truth.sh <output-path>
```

### 6. Report

```
🔍 /speck-scan complete

Level: <project | epic | story>
Output: <path>
Summary: <1 sentence>

Next:
- For project: run /project-specify (or /project-clarify if specifying)
- For epic: run /epic-specify (or /epic-plan if specifying)
- For story: run /story-specify (or /story-plan if specifying)
```

## Compatibility aliases

`/project-scan`, `/epic-scan`, and `/story-scan` remain thin user-invoked shims that route here.

## Behavior Rules

- NEVER scan more broadly than the level requires (story scan is narrow)
- ALWAYS use SHA stamp on output
- ALWAYS reference output from downstream commands' "Information Sources" section

## Context: $ARGUMENTS