From blueprint-mode
Set up a new repository with spec-driven development structure from scratch. Use when creating a new project and the user wants to establish specs, ADRs, and patterns from the beginning.
npx claudepluginhub rickardp/blueprint-mode --plugin blueprint-modeThis skill is limited to using the following tools:
Create a new project with spec-driven development structure from scratch.
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Create a new project with spec-driven development structure from scratch.
Invoked by: /blueprint:setup-repo or /blueprint:setup-repo [tech stack description]
TOOL USAGE: You MUST invoke the AskUserQuestion tool for all structured questions.
When you see JSON examples in this skill, they are parameters for the AskUserQuestion tool - invoke it, don't output the JSON as text or rephrase as plain text questions.
When setting up a new project, check if the directory already has agent instruction files. CRITICAL: Check for symlinks FIRST.
Step 1: Check for symlinks FIRST
ls -la CLAUDE.md AGENTS.md 2>/dev/null
Look for -> in the output which indicates a symlink (e.g., CLAUDE.md -> AGENTS.md).
Step 2: Determine action (priority order)
| Priority | Scenario | Action |
|---|---|---|
| 1 | Symlink exists | Update the TARGET file only. NEVER delete either file. |
| 2 | Neither exists | Create CLAUDE.md (default) |
| 3 | Only CLAUDE.md exists | Update CLAUDE.md |
| 4 | Only AGENTS.md exists | Update AGENTS.md |
| 5 | Both exist independently | Update both with same content |
⚠️ CRITICAL: If a symlink exists, NEVER delete or recreate either file - use Edit on the target.
Step 3: Include in preview Show which file will be created/updated in the preview:
- Agent instructions: CLAUDE.md ← [default | existing | symlink target]
FIRST ACTION: Enter plan mode by calling the EnterPlanMode tool. This enables proper interactive questioning.
Before asking ANY questions, extract ALL information from input.
Use the parsing rules from _templates/TEMPLATES.md (Flexible Information Gathering section).
| Input | Extracts | Questions Needed |
|---|---|---|
/blueprint:setup-repo | Nothing | All questions |
/blueprint:setup-repo Node.js API | Runtime, implied description | Name only |
/blueprint:setup-repo Node + Express + Postgres | Runtime, framework, database | Name, description |
/blueprint:setup-repo MyApp: Node API with Express and PostgreSQL | Name, description, full stack | None (show preview) |
/blueprint:setup-repo TaskAPI - team knows Node and Postgres | Name, runtime, database, rationale | Show preview, create |
Key signals to extract:
Present all remaining questions in a single prompt:
"Setting up a new project. Tell me what you know (answer any, or 'create now'):
**Basics:**
1. Project name?
2. What does it do? (1-2 sentences)
**Tech Stack:**
3. Runtime, framework, database? (e.g., 'Node + Express + Postgres')
**Optional:**
4. Any reasons for these choices? (helps ADRs - or just say 'team preference')
5. Commands to run before commits? [default: lint, test, typecheck]
_(Say 'create now' anytime - I'll infer defaults for anything not specified)_"
Inference Rules (apply automatically):
| If provided | Infer |
|---|---|
| Runtime only | Framework: common default for runtime |
| Framework only | Runtime: framework's native runtime |
| Database mentioned | Database driver for runtime |
| No testing mentioned | Standard test framework for runtime |
Runtime defaults:
Rationale shortcuts:
Show what will be created (text format):
"Creating project with:
- Name: TaskAPI ← provided
- Description: REST API for task management ← provided
- Runtime: Node.js ← provided
- Framework: Express ← inferred (Node default)
- Database: PostgreSQL ← provided
- Testing: Vitest ← inferred (Node default)
- Rationale: Team familiarity ← provided"
Then confirm with AskUserQuestion:
{
"questions": [{
"question": "Ready to create the project with these settings?",
"header": "Create",
"options": [
{"label": "Create now", "description": "Generate project structure"},
{"label": "Change", "description": "I need to modify something"}
],
"multiSelect": false
}]
}
Response handling:
Skip AskUserQuestion if user already said "create now" or "proceed" during questions.
Tool Preferences:
mkdir -p and git init[project-name]/
├── docs/
│ ├── specs/
│ │ ├── product.md # Vision, users, success metrics
│ │ ├── features/ # Feature specifications (empty, discovered via globbing)
│ │ ├── non-functional/ # NFRs by category (empty, discovered via globbing)
│ │ ├── tech-stack.md # Technology decisions
│ │ └── boundaries.md # Agent guardrails
│ └── adrs/
│ ├── 001-runtime-choice.md # Why this runtime
│ ├── 002-framework-choice.md # Why this framework (if applicable)
│ └── 003-database-choice.md # Why this database (if applicable)
├── patterns/
│ ├── good/
│ │ └── .gitkeep
│ └── bad/
│ └── anti-patterns.md
├── tests/
│ └── example.test.[ext] # Initial test file
├── CLAUDE.md (or AGENTS.md) # Agent instructions - see detection above
└── [standard project files]
Note: ADRs are discovered via globbing docs/adrs/*.md. No index file needed.
Source of truth: _templates/TEMPLATES.md
---
status: Active
date: YYYY-MM-DD
---
# ADR-NNN: [Choice] as [CATEGORY]
## Context
[What problem are we solving?]
## Options Considered
### Option 1: [Alternative]
- Pro: [advantage]
- Con: [disadvantage]
## Decision
We chose **[CHOICE]** because [primary motivation].
## Consequences
**Positive:**
- [benefit]
**Negative:**
- [tradeoff]
## Related
- Tech stack: [docs/specs/tech-stack.md](../specs/tech-stack.md)
---
last_updated: YYYY-MM-DD
---
# [PROJECT_NAME]
## Vision
[1-2 sentence description]
## Users
### [User Type 1]
- [What they need]
## Success Metrics
- [Metric 1]
## Features
See `docs/specs/features/` for detailed specifications.
## Quality Standards
- Run `[lint command]` before committing
- Run `[test command]` for verification
# Agent Boundaries
## Always Do
- Run quality commands before commits
- Follow existing code patterns
- Read ADRs before implementing features
## Ask First
### Architecture
- Adding new services or packages
### Breaking Changes
- Removing/renaming API fields
- Changing database schemas
### Blueprint
- Adding or editing ADRs in docs/adrs/
- Adding or editing specs in docs/specs/
- Modifying boundaries.md
## Never Do
### Security
- Commit secrets or credentials
- Disable authentication
### Code
- Commit with type errors
### Documentation
- Create ad-hoc README/markdown files outside the docs/ structure without prior agreement
- Add excessive comments (code should be self-documenting)
- Write long or boilerplate-heavy file header comments instead of concise summaries
| File | Section in TEMPLATES.md |
|---|---|
tech-stack.md | <!-- SECTION: tech-stack --> |
CLAUDE.md | <!-- SECTION: claude-md --> |
anti-patterns.md | <!-- SECTION: bad-patterns --> |
<!-- TODO -->.<!-- Auto-inferred -->._templates/TEMPLATES.md (section: <!-- SECTION: claude-md -->). Include Pre-Edit Checklist. See "CLAUDE.md / AGENTS.md Handling" above for which file to create.## Never Do
- Commit secrets, API keys, or credentials
- Delete data without explicit confirmation
- Push directly to main/master
- Disable security features
## Ask First
- Major dependency additions
- Database schema changes
- Authentication changes
- Adding or editing Blueprint docs (ADRs, specs, boundaries)
"Blueprint structure created:
- [N] ADRs (M from your input, K inferred)
- Testing: [framework]
- Commands: [list]
Run /blueprint:onboard to add more detail anytime."
/blueprint:require - Add requirements/blueprint:decide - Record additional tech decisions/blueprint:good-pattern - Capture good patternsMinimal input:
User: /blueprint:setup-repo
Assistant: "Setting up a new project. Tell me what you know (answer any, or 'create now'):
**Basics:**
1. Project name?
2. What does it do?
**Tech Stack:**
3. Runtime, framework, database?
_(Say 'create now' anytime - I'll infer defaults for anything not specified)_"
User: TaskAPI - REST API for tasks, Node + Postgres, team knows these
Assistant: "Creating project with:
- Name: TaskAPI ← provided
- Description: REST API for tasks ← provided
- Runtime: Node.js ← provided
- Framework: Express ← inferred
- Database: PostgreSQL ← provided
- Testing: Vitest ← inferred
- Rationale: Team familiarity ← provided"
[Uses AskUserQuestion with "Create now" / "Change" options]
User: [Selects "Create now"]
Assistant: [Creates structure]
Rich input:
User: /blueprint:setup-repo TaskAPI: Node.js REST API with Express, PostgreSQL, and JWT auth. Team knows these well.
Assistant: "Creating project with:
- Name: TaskAPI ← provided
- Description: Node.js REST API ← provided
- Runtime: Node.js ← provided
- Framework: Express ← provided
- Database: PostgreSQL ← provided
- Auth: JWT ← provided
- Rationale: Team familiarity ← provided"
[Uses AskUserQuestion with "Create now" / "Change" options]
User: [Selects "Create now"]
Assistant: [Creates structure immediately]
If user indicates a mistake after creation: