/validate-space

Validate that a project space has all required structure, boilerplate docs, and stays consistent with its planning docs in ideas/.

Usage

bash

/validate-space leaf-nextjs-convex    # Validate specific space
/validate-space coordinatr            # Another project
/validate-space                       # Prompt for project name

Validation Checklist

Required Files (Every Space)

File	Purpose	Check
CLAUDE.md	AI instructions for codebase	Must exist
README.md	Entry point for developers	Must exist
package.json (JS/TS)	Project config	Stack-dependent

Required Directory Structure

Directory	Purpose	Check
docs/	Documentation root	Must exist
docs/specs/	Protocol/feature specs	Must exist
docs/adrs/	Architecture Decision Records	Must exist

Required Overview Docs (in docs/)

File	Purpose
architecture-overview.md	System architecture
api-overview.md	API documentation
data-model.md	Data structures
deployment.md	Deployment guide
security.md	Security considerations
testing-overview.md	Testing strategy
ui-guide.md	UI patterns and components

Templates available at

shared/templates/docs/

CLAUDE.md Requirements

Overview section with stack description
Project structure section
Commands section (dev, build, deploy)
Environment variables section (if applicable)
Link to ideas/ planning docs

Consistency Checks

Check	Description
Version sync	package.json versions match docs (e.g., "Next.js 16" in CLAUDE.md matches `"next": "16.x"` )
Stack accuracy	Listed technologies actually exist in dependencies
Structure accuracy	Documented directories actually exist
Ideas link	Referenced ideas/[project]/ exists and has matching info

Cross-Reference with ideas/

Check	Description
README.md	Stack listed in ideas/ matches spaces/
project-brief.md	Technical decisions match actual implementation
Issues	Current phase/status is accurate

Execution Flow

1. Locate Project

bash

ls spaces/[project-name]/

Error if not found.

2. Check Required Files

Read: spaces/[project]/CLAUDE.md
Read: spaces/[project]/README.md
Read: spaces/[project]/package.json (if JS/TS)

3. Validate CLAUDE.md Sections

Check for required sections:

Overview / Stack
Project Structure
Commands
Environment Variables (if .env.example exists)

4. Check Version Consistency

Extract versions from:

CLAUDE.md stack description
ideas/[project]/README.md
ideas/[project]/project-brief.md
package.json dependencies

Flag any mismatches.

5. Verify Directory Structure

Check required directories exist:

bash

ls -la spaces/[project]/docs/
ls -la spaces/[project]/docs/specs/
ls -la spaces/[project]/docs/adrs/

Check overview docs present:

bash

ls spaces/[project]/docs/*.md
# Should have: architecture-overview.md, api-overview.md, data-model.md,
#              deployment.md, security.md, testing-overview.md, ui-guide.md

Compare documented structure in CLAUDE.md against actual:

bash

ls -la spaces/[project]/
ls -la spaces/[project]/src/ (if documented)

6. Cross-Reference ideas/

bash

Read: ideas/[project]/README.md
Read: ideas/[project]/project-brief.md

Check stack/version consistency.

Validation Report

markdown

# Space Validation: [Project Name]

## Status
- Space location: spaces/[project]/
- Ideas location: ideas/[project]/ (exists/missing)

## Required Files
✅ CLAUDE.md - Present
✅ README.md - Present
✅ package.json - Present

## Required Directories
✅ docs/ - Present
✅ docs/specs/ - Present
✅ docs/adrs/ - Present

## Overview Docs (in docs/)
✅ architecture-overview.md - Present
✅ api-overview.md - Present
✅ data-model.md - Present
✅ deployment.md - Present
✅ security.md - Present
✅ testing-overview.md - Present
✅ ui-guide.md - Present

## CLAUDE.md Sections
✅ Overview/Stack - Complete
✅ Project Structure - Complete
⚠️  Commands - Missing deploy command
✅ Environment Variables - Complete

## Version Consistency
✅ Next.js: 16.1.3 (package.json) matches "Next.js 16" (docs)
❌ React: 19.0.0 (package.json) but docs say "React 18"

## Ideas Cross-Reference
✅ ideas/leaf-nextjs-convex/ exists
✅ Stack matches between spaces/ and ideas/
⚠️  project-brief.md says "Next.js 15" - outdated

## Issues Found
1. React version mismatch in documentation
2. project-brief.md has outdated version

## Recommendations
1. Update React version in CLAUDE.md
2. Update project-brief.md to say Next.js 16
3. Fill in overview doc templates with project-specific content

Fixing Missing Structure

If docs/ structure is missing, create it:

bash

mkdir -p spaces/[project]/docs/specs
mkdir -p spaces/[project]/docs/adrs
cp shared/templates/docs/*.md spaces/[project]/docs/

When to Use

After initial project scaffolding
Before starting implementation work
After upgrading dependencies
Monthly maintenance checks
When onboarding to existing project

Integration

/validate-space → Fix issues → /validate-space again → /implement

Stack-Specific Checks

Next.js Projects

Check for
```
next.config.js
```
or
```
next.config.ts
```
Verify
```
src/app/
```
structure for App Router
Check for
```
public/
```
directory

Convex Projects

Check for
```
convex/
```
directory
Verify
```
convex/schema.ts
```
exists
Check for
```
convex/_generated/
```

General JS/TS

Verify
```
tsconfig.json
```
if TypeScript
Check for
```
.env.example
```
if env vars documented
Verify
```
.gitignore
```
exists

validate-space

NPX Install

Tags

SKILL.md Content

/validate-space

Usage

Validation Checklist

Required Files (Every Space)

Required Directory Structure

Required Overview Docs (in docs/)

CLAUDE.md Requirements

Consistency Checks

Cross-Reference with ideas/

Execution Flow

1. Locate Project

2. Check Required Files

3. Validate CLAUDE.md Sections

4. Check Version Consistency

5. Verify Directory Structure

6. Cross-Reference ideas/

Validation Report

Fixing Missing Structure

When to Use

Integration

Stack-Specific Checks

Next.js Projects

Convex Projects

General JS/TS