Getting Started

Getting Started

This page walks through everything you need to reproduce the project: installing Spec Kit, scaffolding a project, driving the Spec-Driven Development loop, and running the generated site locally.

Prerequisites

• Node.js 20+ (the site was built and validated on Node 24) and npm
• Python with uv to install the Spec Kit CLI
• A Spec Kit-compatible AI coding agent (for example, GitHub Copilot in VS Code)

1. Install Spec Kit

Install the specify CLI from the Spec Kit repository:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.11.1

Verify the command is available:

specify --help

2. Initialize a project

Create a new Spec Kit project:

specify init spec-podcast-site

Initialization creates the .specify/ workspace: prompt files, templates, the memory folder that holds the constitution, and the integration hooks used by the rest of the workflow.

3. Establish the constitution

Before writing any feature, capture the non-negotiable rules in .specify/memory/constitution.md. For this project the constitution requires:

• Static output that can be hosted without a custom server
• Source-controlled content and configuration
• Accessibility by default
• Deterministic, lightweight delivery
• Minimal dependencies and tooling

See Project Constitution for the full text and the reasoning behind each principle.

4. Run the Spec-Driven Development loop

With the constitution in place, drive the feature through the SDD commands. Each command is documented in detail on the Spec-Driven Development page.

/speckit.specify   ->  specs/<feature>/spec.md
/speckit.clarify   ->  refined spec, open questions resolved
/speckit.plan      ->  plan.md, research.md, data-model.md, contracts/, quickstart.md
/speckit.tasks     ->  tasks.md (dependency-ordered, grouped by user story)
/speckit.implement ->  application code, validated against the plan

5. Run the site locally

Once the implementation tasks are complete, install dependencies and start the development server:

npm install
npm run dev

The development server runs at http://localhost:3000.

6. Validate

The same checks the workflow uses are available as npm scripts:

npm run type-check   # TypeScript, no emit
npm run lint         # ESLint flat config
npm run build        # static export to out/
npm run test:e2e     # responsive navigation and content contract
npm run test:a11y    # axe accessibility scan of all four pages

npm run build emits a fully static bundle to out/ with one index.html per route. See Testing and Validation for what each check guarantees.

Project layout at a glance

app/                 # App Router routes: /, /episodes, /about, /faq
src/components/       # shared UI components
src/content/          # typed, source-controlled content (podcast, episodes, faq)
src/styles/           # design tokens and responsive CSS
public/assets/        # static artwork
tests/                # Playwright content, accessibility, responsive suites
specs/                # the SDD artifacts that drove the build
.specify/             # Spec Kit workspace, templates, and the constitution

For a deeper tour, continue to Architecture.