spec-first-project-setup

Spec-first project setup

Bootstrap the doc structure, design directory, and Claude Code configuration that the global engineering rules depend on. Creates the skeleton — the user fills in the values.

Companion skills

This skill scaffolds the artifacts that four sibling skills depend on. The intended workflow once setup is done:

Skill	Stage	Reads
/design-explore	Discover or challenge design direction	All design docs (treats them as living, can challenge)
/design-agent	Generate production design variants	All design docs (treats them as locked spec)
/code-agent	Implement features	CLAUDE.md, REPO-CONVENTIONS.md, COMPONENT-SPECS.md ([FEATURE]-IDEAS.md recommended per feature)
/visual-qa	Verify rendered code against spec	DESIGN-TOKENS.md, DESIGN-LANGUAGE.md, DESIGN-TAXONOMY.md

Each companion skill runs a "spec preflight" check on first invocation and tells the user to run /spec-first-project-setup if its required artifacts are missing.

When to use

• Starting a new project from scratch.
• Adding spec structure to an existing project that has none.
• User asks to "set up docs", "scaffold specs", or "create project structure".

What it creates

docs/
├── BRIEF-AND-DIRECTION.md
├── DESIGN-LANGUAGE.md
├── DESIGN-TOKENS.md
├── COMPONENT-SPECS.md
├── DESIGN-TAXONOMY.md
├── REPO-CONVENTIONS.md       # Routing, parsing, state management, analytics patterns
├── [FEATURE]-IDEAS.md        # One per feature/page
└── mocks/                    # API response fixtures (optional)
    └── [endpoint-name].json
design/
└── .gitkeep
CLAUDE.md                      # Project-level Claude Code configuration
.claude/
└── rules/                     # Project-specific rules (if applicable)
    └── design-code-sync.md    # Only for projects with design artifacts

Templates

All file templates live in assets/templates/. Each "Create" step below copies a template into place, substituting placeholders (project name, feature name, design tool, file paths). Templates use [BRACKETS] for substitutions and <!-- HTML comments --> for guidance the user fills in later.