blueprint:setup-repo

What this skill does

# Set Up New Repository

Create a new project with Blueprint intent-capture structure from scratch.

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

## Principles

1. **Ask questions, allow skip**: The user has the knowledge - ask for it, but never block.
2. **Parse input first**: Extract what user already provided before asking.
3. **Early exit always available**: User can say "proceed" at any point.
4. **Unit tests from the start**: Every project gets a testing setup.
5. **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:
```
- 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:**

```
"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):**

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

```
[project-name]/
├── docs/                              # CODE / ARCHITECTURE TREE
│   ├── 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/                          # Pattern examples and anti-patterns (any subject)
│   ├── 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]
```

**The design tree (`design/`) and `DESIGN.md` are NOT created by this skill.** Design intent capture is opt-in via `/blueprint:onboard-design`. If the user mentions UI, frontend, dashboard, or a UI framework, mention `/blueprint:onboard-design` in the After Creation report — but do NOT scaffold design artifacts here.

**When generating CLAUDE.md / AGENTS.md from the `<!-- SECTION: claude-md -->` template:** OMIT the "Important adjacent design context" and "Design / UX tree" tables. They only apply once `DESIGN.md` exists or `/blueprint:onboard-design` has been run. Including them here would point agents at non-existent paths. `/blueprint:onboard-design` adds the rows post-hoc.

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