/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