jvn

Spec-driven development with Claude Code.

Named after John von Neumann — the man who wrote the spec that defined computing.

Quick Start

cd my-project
npx jvn

That's it. Then:

claude
/spec "what you want to build"

What it does

jvn sets up spec-driven development in any project:

1. Installs 18 curated skills globally (Neon, React, Better Auth, TDD, and more)
2. Initializes GitHub Spec-Kit with Claude Code integration
3. Pre-configures a project constitution with engineering best practices
4. Adds 5 specialized agents and 5 workflow commands

Commands

After setup, open claude and use:

| Command | What it does | |---------|-------------| | /spec "feature" | Describe what you want to build. Creates a rich specification with product, UX, and technical considerations. | | /design | Create the technical plan. Architecture review and constitutional validation included. | | /build | Build it phase by phase. TDD enforced, tests run, code reviewed, your approval required at every gate. | | /report | Analyze the project — tech stack, routes, SWOT analysis. Generates a timestamped report. | | /report-fix @latest | Systematically fix issues from the most recent report. |

Flow: /spec → /design → /build

CLI Flags

jvn                              # Set up spec-driven dev
jvn --dry-run                    # Preview what would happen
jvn --force                      # Overwrite existing files
jvn --skip-skills                # Skip skill installation
jvn --skip-speckit               # Skip Spec-Kit init
jvn --report                     # Generate project report
jvn --report-fix @latest         # Fix issues from latest report
jvn --report-fix report-030626   # Fix issues from specific report
jvn --version                    # Print version
jvn --help                       # Print help

What Gets Installed

Skills (18)

| Skill | Source | Category | |-------|--------|----------| | Neon Postgres | neondatabase/agent-skills | Database | | Better Auth | better-auth/skills | Auth | | React Best Practices | vercel-labs/agent-skills | Frontend | | Composition Patterns | vercel-labs/agent-skills | Frontend | | Frontend Design | anthropics/skills | Design | | Web Design Guidelines | vercel-labs/agent-skills | Design | | API Design | wshobson/agents | API | | Webapp Testing | anthropics/skills | Testing | | Test-Driven Development | obra/superpowers | Testing | | Dogfood QA | vercel-labs/agent-browser | QA | | MCP Builder | anthropics/skills | Tools | | Doc Coauthoring | anthropics/skills | Docs | | PDF | anthropics/skills | Docs | | DOCX | anthropics/skills | Docs | | Resend Email | resend/resend-skills | Email | | Skill Creator | anthropics/skills | Meta | | Find Skills | vercel-labs/skills | Meta | | Git Commit | github/awesome-copilot | Git |

Agents (5)

| Agent | Model | Role | |-------|-------|------| | architect | opus | System design, data modeling, API contracts | | product-manager | sonnet | User stories, acceptance criteria, scope | | ux-designer | sonnet | User flows, states, accessibility | | code-reviewer | sonnet | Correctness, TDD enforcement, security | | constitutional-validator | opus | Constitution compliance gate |

Architecture

/spec → /design → /build
  │        │         │
  │        │         ├── speckit-implement (code generation, TDD)
  │        │         ├── webapp-testing (Playwright validation)
  │        │         ├── code-reviewer agent (TDD + checklist)
  │        │         ├── user validation gate (your approval)
  │        │         └── dogfood (final QA exploration)
  │        │
  │        ├── speckit-plan (base plan)
  │        ├── architect agent (review)
  │        ├── constitutional-validator agent (gate)
  │        └── speckit-tasks (task breakdown)
  │
  ├── speckit-specify (base spec)
  ├── product-manager agent (enrichment)
  └── ux-designer agent (UX brief)

Default Stack

• Next.js (App Router) on Vercel
• Neon Postgres via Drizzle ORM
• Better Auth with Drizzle adapter
• Tailwind CSS

The constitution and stack knowledge are pre-configured for this stack. To customize:

1. Edit CLAUDE.md — uncomment the Stack Override section
2. Edit .specify/memory/constitution.md — update Stack Principles
3. Edit .claude/skills/stack-knowledge/SKILL.md — update patterns

Prerequisites

• Node.js 18+
• Claude Code
• GitHub Spec-Kit (pipx install specify-cli)

License

MIT