# Speckit Brownfield Validate

> Verify bootstrap output matches actual project structure and conventions

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

---


# Validate Bootstrap

Verify that the spec-kit configuration generated by `/speckit.brownfield.bootstrap` accurately reflects the actual project structure, conventions, and architecture. Reports mismatches and suggests corrections.

## User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty). The user may specify a focus area (e.g., "only constitution", "only templates") or request verbose output.

## Prerequisites

1. Verify a spec-kit project exists by checking for `.specify/` directory
2. Verify git is available and the project is a git repository
3. Verify at least one bootstrap artifact exists (constitution, customized templates, or AGENTS.md)

## Outline

1. **Validate constitution**: Check `.specify/memory/constitution.md` against the actual codebase:

   | Check | How |
   |-------|-----|
   | **Language references** | Verify mentioned languages actually exist in the codebase |
   | **Directory references** | Verify all referenced paths (`client/`, `server/`, etc.) exist |
   | **Framework references** | Verify mentioned frameworks are in dependency files |
   | **Naming conventions** | Sample 20 files and check if naming rules match reality |
   | **Test location** | Verify test directories mentioned in constitution exist |
   | **Branch pattern** | Check if branch naming rules match actual branches in `git branch -a` |

2. **Validate templates**: Check customized spec/plan/tasks templates:

   | Check | How |
   |-------|-----|
   | **Module references** | Verify template sections reference actual modules/directories |
   | **Test commands** | Verify test commands in tasks template actually work |
   | **Build commands** | Verify build commands reference real scripts from package files |
   | **Section relevance** | Flag template sections that reference non-existent project aspects |

3. **Validate AGENTS.md** (if exists): Check agent configuration:

   | Check | How |
   |-------|-----|
   | **Directory ownership** | Verify each agent's directories exist |
   | **No overlaps** | Check that no directory is owned by multiple agents |
   | **No orphans** | Check that all source directories are covered by at least one agent |

4. **Detect drift**: Check if the project has changed since bootstrap:
   - New directories or modules added since constitution was generated
   - Dependencies added or removed since bootstrap
   - New branch patterns that don't match constitution rules

5. **Output validation report**:

   ```markdown
   # Validation Report

   ## Constitution
   | Rule | Status | Detail |
   |------|--------|--------|
   | Primary language: TypeScript | ✅ Pass | 68% of source files |
   | Frontend in `client/` | ✅ Pass | Directory exists, contains React code |
   | Backend in `server/` | ✅ Pass | Directory exists, contains FastAPI code |
   | Test location: `__tests__/` | ⚠️ Drift | Also found tests in `tests/` (not mentioned) |
   | Branch pattern: `feat/*` | ✅ Pass | 8/10 recent branches match |

   ## Templates
   | Template | Status | Detail |
   |----------|--------|--------|
   | Spec template | ✅ Pass | All custom sections map to real project aspects |
   | Plan template | ⚠️ Drift | References `shared/` module — directory renamed to `common/` |
   | Tasks template | ✅ Pass | Test commands verified |

   ## Summary
   - **Checks passed**: 9/11
   - **Drift detected**: 2 items
   - **Action needed**: Update plan template (`shared/` → `common/`), add `tests/` to constitution
   ```

## Rules

- **Read-only** — this command never modifies any files
- **Evidence-based** — every pass/fail must cite specific files or directories as evidence
- **Actionable output** — for every failure or drift, suggest the specific fix
- **Non-blocking** — drift warnings don't mean the configuration is broken, just that it could be improved
- **Respect .gitignore** — never scan ignored directories when validating