Set Up New Repository

Create a new project with spec-driven development structure from scratch.

Invoked by: /blueprint:setup-repo or /blueprint:setup-repo [tech stack description]

Principles

•Ask questions, allow skip: The user has the knowledge - ask for it, but never block.
•Parse input first: Extract what user already provided before asking.
•Early exit always available: User can say "proceed" at any point.
•Unit tests from the start: Every project gets a testing setup.
•Conservative dependencies: Only add packages if explicitly requested or de facto standard.

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.

CLAUDE.md / AGENTS.md Handling

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

bash

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:

code

- Agent instructions: CLAUDE.md ← [default | existing | symlink target]

Process

FIRST ACTION: Enter plan mode by calling the EnterPlanMode tool. This enables proper interactive questioning.

Step 1: Parse Input

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:

•"[Name]: [description]" or "[Name] - [description]" → Name + description
•"team knows [X]" / "familiar with [X]" → Rationale for that technology
•"[tech] + [tech] + [tech]" → Stack components

Step 2: Gather Missing Information (Single Batch)

Present all remaining questions in a single prompt:

code

"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:

•Node.js → Vitest, Express (if framework not specified)
•Bun → Bun test runner, Hono
•Python → pytest, FastAPI
•Go → built-in testing, standard library

Rationale shortcuts:

•"team knows" / "team preference" → "Team familiarity with [technology]"
•"industry standard" → "De facto industry standard"
•No rationale → Use "Team preference" as default

Step 3: Preview Before Creating

Show what will be created (text format):

code

"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:

json

{
  "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:

•"Create now" → Proceed to Create Structure
•"Change" → Ask "What needs to change?" (plain text)
•"Other" → Treat as modification request

Skip AskUserQuestion if user already said "create now" or "proceed" during questions.

Create Structure

Tool Preferences:

•File writing: Use Claude's Write tool
•Directory operations: Use Bash for mkdir -p and git init

code

[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.

File Templates

Source of truth: _templates/TEMPLATES.md

ADR Template (inline for non-interactive execution)

markdown

---
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)

product.md Template

markdown

---
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

boundaries.md Template

markdown

# 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

Other Templates

File	Section in TEMPLATES.md
`tech-stack.md`	`<!-- SECTION: tech-stack -->`
`CLAUDE.md`	`<!-- SECTION: claude-md -->`
`anti-patterns.md`	`<!-- SECTION: bad-patterns -->`

Applying Templates

•Product spec: Fill what user provided, mark missing sections with .
•Tech stack: Fill from choices. Mark inferred values: .
•Boundaries: Use sensible defaults + any user-specified rules.
•
ADRs:
- •If user gave rationale → Use it
- •If user said "team preference" → Use "Team familiarity and industry standard"
- •If user skipped → Use "Team preference" as default
•CLAUDE.md / AGENTS.md: Use full template from _templates/TEMPLATES.md (section: ). Include Pre-Edit Checklist. See "CLAUDE.md / AGENTS.md Handling" above for which file to create.

Default Boundaries (if not specified)

markdown

## 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)

After Creation

•Initialize git repository if not already done
•Set up testing with language-appropriate runner
•Create initial commit with spec structure

•Report:

code

"Blueprint structure created:
- [N] ADRs (M from your input, K inferred)
- Testing: [framework]
- Commands: [list]

Run /blueprint:onboard to add more detail anytime."

•
Suggest next steps:
- •/blueprint:require - Add requirements
- •/blueprint:decide - Record additional tech decisions
- •/blueprint:good-pattern - Capture good patterns

Examples

Minimal input:

code

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:

code

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]

Error Recovery

If user indicates a mistake after creation:

•Acknowledge: "I can update or remove the created files"
•Clarify: "What needs to change?"
•Execute: Update or delete as needed
•Confirm: "Files have been [updated/removed]"