validate-space

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

Usage

/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

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:

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

Check overview docs present:

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:

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

6. Cross-Reference ideas/

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

Check stack/version consistency.

Validation Report

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

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