New Project

---
description: Initialize a new project with deep questioning → optional research → requirements → roadmap. Writes .planning/ scaffold (PROJECT.md, config.json, REQUIREMENTS.md, ROADMAP.md, STATE.md) and commits atomically.
argument-hint: "[--auto] [@idea.md]"
---

# /new-project

## Objective

Initialize a project through a unified flow: **questioning → research (optional) → requirements → roadmap**. This is the most leveraged moment in any project — deep questioning here means better plans, better execution, better outcomes.

**Creates:**
- `.planning/PROJECT.md` — project context
- `.planning/config.json` — workflow preferences
- `.planning/research/` — domain research (optional)
- `.planning/REQUIREMENTS.md` — scoped requirements with REQ-IDs
- `.planning/ROADMAP.md` — phase structure
- `.planning/STATE.md` — project memory

After this command: run the planning command for Phase 1.

## Supporting files

Read these before running:
- Questioning techniques: `~/.claude/planning-references/questioning.md`
- UI/brand tone (banners, section dividers): `~/.claude/planning-references/ui-brand.md`
- Templates you will fill in:
  - `~/.claude/planning-templates/project.md`
  - `~/.claude/planning-templates/requirements.md`
  - `~/.claude/planning-templates/roadmap.md`
  - `~/.claude/planning-templates/state.md`
  - `~/.claude/planning-templates/research/{STACK,FEATURES,ARCHITECTURE,PITFALLS,SUMMARY}.md`

## Arguments

- `$ARGUMENTS` — may contain `--auto` flag and/or an `@file` reference.
- **Auto mode** (`--auto` present): skip deep questioning, skip approval gates, expect an idea document (`@file` or pasted text) to synthesize from.
  - If no idea document is supplied with `--auto`, print this error and stop:
    ```
    Error: --auto requires an idea document.

    Usage:
      /new-project --auto @your-idea.md
      /new-project --auto [paste or write your idea here]
    ```

## Process

### 1. Preflight

```bash
# Detect state
HAS_GIT=$( [ -d .git ] && echo true || echo false )
PROJECT_EXISTS=$( [ -f .planning/PROJECT.md ] && echo true || echo false )
HAS_CODEBASE_MAP=$( [ -d .planning/codebase ] && echo true || echo false )
HAS_CODE=$(find . -maxdepth 3 \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.py' -o -name '*.go' -o -name '*.rs' -o -name '*.java' -o -name '*.swift' \) 2>/dev/null | grep -v node_modules | grep -v .git | head -1)
HAS_PKG=$( { [ -f package.json ] || [ -f requirements.txt ] || [ -f Cargo.toml ] || [ -f go.mod ] || [ -f pyproject.toml ] || [ -f pom.xml ]; } && echo true || echo false )
[ -n "$HAS_CODE" ] || [ "$HAS_PKG" = "true" ] && IS_BROWNFIELD=true || IS_BROWNFIELD=false
TODAY=$(date +%F)
echo "project_exists=$PROJECT_EXISTS has_git=$HAS_GIT has_codebase_map=$HAS_CODEBASE_MAP is_brownfield=$IS_BROWNFIELD today=$TODAY"

• If PROJECT_EXISTS=true: stop. Tell the user the project is already initialized and suggest editing .planning/PROJECT.md directly.
• If HAS_GIT=false: git init.

2. Brownfield offer (skip in auto mode)

If IS_BROWNFIELD=true AND HAS_CODEBASE_MAP=false:

Existing code detected but no codebase map at .planning/codebase/.

Options:
1. Map the codebase first (recommended) — run /clear then /map-codebase, then return to /new-project
2. Skip mapping — continue without codebase context

If user picks "map first": exit this command. Otherwise continue.

3. Deep questioning (skip in auto mode)

Display stage banner:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ► QUESTIONING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Open freeform: "What do you want to build?"

Then follow threads based on the response. Use techniques from ~/.claude/planning-references/questioning.md:

• Challenge vagueness — "what do you mean by X?"
• Make abstract concrete — "can you give me an example?"
• Surface assumptions — "what would have to be true for this to work?"
• Find edges — "when shouldn't this happen?"
• Reveal motivation — "why this, why now?"

Mentally track the context checklist (problem, user, success, constraints, key decisions). Weave in questions naturally rather than interrogating.

Gate: when you can write a clean PROJECT.md, ask inline:

Ready to create PROJECT.md, or keep exploring?

Loop until the user says "go".

4. Write PROJECT.md

Read the template at ~/.claude/planning-templates/project.md and fill it in with everything you've gathered.

Greenfield: Requirements → Active = hypotheses; Validated = (None yet — ship to validate). Brownfield (codebase map exists): read .planning/codebase/ARCHITECTURE.md and STACK.md, treat existing capabilities as Validated; new asks go into Active.

Footer line:

---
*Last updated: <TODAY> after initialization*

Commit:

mkdir -p .planning
git add .planning/PROJECT.md
git commit -m "docs: initialize project"  # only if HAS_GIT=true

5. Workflow config

Ask 4 config questions (skip in auto mode — use defaults + YOLO).

Question	Options
Mode — how do you want to work?	yolo (auto-approve, ship fast) / interactive (confirm each step)
Depth — how thorough should planning be?	quick (3-5 phases) / standard (5-8) / comprehensive (8-12)
Parallelization — run independent plans concurrently?	true / false
Git tracking — commit planning docs?	true / false

Then 3 workflow-agent questions:

Agent	Default	What it does
Researcher — research each phase before planning?	yes	surfaces domain patterns + gotchas
Plan checker — verify plans will achieve their goals?	yes	catches gaps before execution
Verifier — verify work satisfies requirements after each phase?	yes	confirms deliverables

Write .planning/config.json:

{
  "mode": "yolo|interactive",
  "depth": "quick|standard|comprehensive",
  "parallelization": true,
  "commit_docs": true,
  "workflow": {
    "research": true,