---
name: kata-new-project
description: Initialize a new project with deep context gathering and project.md. Triggers include "new project", "start project", "initialize project", "create project", "begin project", "setup project".
metadata:
  version: "1.6.1"
---
<objective>

Initialize a new project with deep context gathering and workflow configuration.

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

**After this command:** Run `/kata-add-milestone` to define your first milestone.

</objective>

<execution_context>

@./references/questioning.md
@./references/ui-brand.md
@./references/project-template.md

</execution_context>

<process>

## Phase 1: Setup

**MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**

1. **Abort if project exists:**
   ```bash
   [ -f .planning/PROJECT.md ] && echo "ERROR: Project already initialized. Use /kata-track-progress" && exit 1
   ```

2. **Initialize git repo in THIS directory** (required even if inside a parent repo):
   ```bash
   if [ -d .git ] || [ -f .git ]; then
       echo "Git repo exists in current directory"
   else
       git init
       echo "Initialized new git repo"
   fi
   ```

3. **Detect existing code (brownfield detection):**
   ```bash
   CODE_FILES=$(find . -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.swift" -o -name "*.java" 2>/dev/null | grep -v node_modules | grep -v .git | head -20)
   HAS_PACKAGE=$([ -f package.json ] || [ -f requirements.txt ] || [ -f Cargo.toml ] || [ -f go.mod ] || [ -f Package.swift ] && echo "yes")
   HAS_CODEBASE_MAP=$([ -d .planning/codebase ] && echo "yes")
   ```

   **You MUST run all bash commands above using the Bash tool before proceeding.**

## Phase 2: Brownfield Offer

**If existing code detected and .planning/codebase/ doesn't exist:**

Check the results from setup step:
- If `CODE_FILES` is non-empty OR `HAS_PACKAGE` is "yes"
- AND `HAS_CODEBASE_MAP` is NOT "yes"

Use AskUserQuestion:
- header: "Existing Code"
- question: "I detected existing code in this directory. Would you like to map the codebase first?"
- options:
  - "Map codebase first" — Run /kata-map-codebase to understand existing architecture (Recommended)
  - "Skip mapping" — Proceed with project initialization

**If "Map codebase first":**
```
Run `/kata-map-codebase` first, then return to `/kata-new-project`
```
Exit command.

**If "Skip mapping":** Continue to Phase 3.

**If no existing code detected OR codebase already mapped:** Continue to Phase 3.

## Phase 3: Deep Questioning

**Display stage banner:**


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata ► QUESTIONING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


**Open the conversation:**

Use AskUserQuestion:

- header: "Getting Started"
- question: "How would you like to begin?"
- options:
  - "I know what I want to build" — Jump into describing your project
  - "Brainstorm first" — Run explorer/challenger brainstorm session to explore ideas

**If "Brainstorm first":**

Display "Launching brainstorm session..." and run `/kata-brainstorm`. After brainstorm completes, continue to questioning below.

**If "I know what I want to build":** Continue to questioning below.

**Questioning:**

Ask inline (freeform, NOT AskUserQuestion):

"What do you want to build?"

Wait for their response. This gives you the context needed to ask intelligent follow-up questions.

**Follow the thread:**

Based on what they said, ask follow-up questions that dig into their response. Use AskUserQuestion with options that probe what they mentioned — interpretations, clarifications, concrete examples.

Keep following threads. Each answer opens new threads to explore. Ask about:
- What excited them
- What problem sparked this
- What they mean by vague terms
- What it would actually look like
- What's already decided

Consult `questioning.md` for techniques:
- Challenge vagueness
- Make abstract concrete
- Surface assumptions
- Find edges
- Reveal motivation

**Check context (background, not out loud):**

As you go, mentally check the context checklist from `questioning.md`. If gaps remain, weave questions naturally. Don't suddenly switch to checklist mode.

**Decision gate:**

When you could write a clear PROJECT.md, use AskUserQuestion:

- header: "Ready?"
- question: "I think I understand what you're after. Ready to create PROJECT.md?"
- options:
  - "Create PROJECT.md" — Let's move forward
  - "Keep exploring" — I want to share more / ask me more

If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally.

Loop until "Create PROJECT.md" selected.

## Phase 4: Write PROJECT.md

**First, create all project directories in a single command:**

```bash
mkdir -p .planning/phases/pending .planning/phases/active .planning/phases/completed
touch .planning/phases/pending/.gitkeep .planning/phases/active/.gitkeep .planning/phases/completed/.gitkeep
```

This creates `.planning/`, `.planning/phases/`, the three state subdirectories, and `.gitkeep` files so git tracks them. Run this BEFORE writing any files.

Synthesize all context into `.planning/PROJECT.md` using the template from `@./references/project-template.md`.

**For greenfield projects:**

Initialize requirements as hypotheses:

```markdown
## Requirements

### Validated

(None yet — ship to validate)

### Active

- [ ] [Requirement 1]
- [ ] [Requirement 2]
- [ ] [Requirement 3]

### Out of Scope

- [Exclusion 1] — [why]
- [Exclusion 2] — [why]
```

All Active requirements are hypotheses until shipped and validated.

**For brownfield projects (codebase map exists):**

Infer Validated requirements from existing code:

1. Read `.planning/codebase/ARCHITECTURE.md` and `STACK.md`
2. Identify what the codebase already does
3. These become the initial Validated set

```markdown
## Requirements

### Validated

- ✓ [Existing capability 1] — existing
- ✓ [Existing capability 2] — existing
- ✓ [Existing capability 3] — existing

### Active

- [ ] [New requirement 1]
- [ ] [New requirement 2]

### Out of Scope

- [Exclusion 1] — [why]
```

**Key Decisions:**

Initialize with any decisions made during questioning:

```markdown
## Key Decisions

| Decision                  | Rationale | Outcome   |
| ------------------------- | --------- | --------- |
| [Choice from questioning] | [Why]     | — Pending |
```

**Last updated footer:**

```markdown
---
*Last updated: [date] after initialization*
```

Do not compress. Capture everything gathered.

**Commit PROJECT.md:**

```bash
git add .planning/PROJECT.md .planning/phases/pending/.gitkeep .planning/phases/active/.gitkeep .planning/phases/completed/.gitkeep
git commit -m "$(cat <<'EOF'
docs: initialize project

[One-liner from PROJECT.md What This Is section]
EOF
)"
```

## Phase 5: Workflow Preferences

**5 questions:**

```
questions: [
  {
    header: "Mode",
    question: "How do you want to work?",
    multiSelect: false,
    options: [
      { label: "YOLO (Recommended)", description: "Auto-approve, just execute" },
      { label: "Interactive", description: "Confirm at each step" }
    ]
  },
  {
    header: "Depth",
    question: "How thorough should planning be?",
    multiSelect: false,
    options: [
      { label: "Quick", description: "Ship fast (3-5 phases, 1-3 plans each)" },
      { label: "Standard", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
      { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" }
    ]
  },
  {
    header: "Git Tracking",
    question: "Commit planning docs to git?",
    multiSelect: false,
    options: [
      { label: "Yes (Recommended)", description: "Planning docs tracked in version control" },
      { label: "No", description: "Keep .planning/ local-only (add to .gitignore)" }
    ]
  },
  {
    header: "PR Workflow",
    question: "Use PR-based release workflow?",
    multiSelect: false,
    options: [
      { label: "Yes (Recommended)", description: "Protect main, create PRs, tag via GitHub Release" },
      { label: "No", description: "Commit directly to main, create tags locally" }
    ]
  },
  {
    header: "GitHub Tracking",
    question: "Enable GitHub Milestone/Issue tracking?",
    multiSelect: false,
    options: [
      { label: "Yes (Recommended)", description: "Create GitHub Milestones for Kata milestones, optionally create Issues for phases" },
      { label: "No", description: "Keep planning local to .planning/ directory only" }
    ]
  }
]

# If GitHub Tracking = Yes, ask follow-up:
{
  header: "Issue Creation",
  question: "When should GitHub Issues be created for phases?",
  multiSelect: false,
  options: [
    { label: "Auto", description: "Create Issues automatically for each phase (no prompting)" },
    { label: "Ask per milestone", description: "Prompt once per milestone, decision applies to all phases" },
    { label: "Never", description: "Only create Milestones, no phase-level Issues" }
  ]
}
```

**GitHub Repository Check (conditional):**

**If GitHub Tracking = Yes:**

After confirming GitHub preferences, check for existing remote:

```bash
# Check if gh CLI is authenticated
GH_AUTH=$(gh auth status &>/dev/null && echo "true" || echo "false")

# Check for GitHub remote
HAS_GITHUB_REMOTE=$(git remote -v 2>/dev/null | grep -q 'github\.com' && echo "true" || echo "false")
```

**If `HAS_GITHUB_REMOTE=false` and user selected GitHub Tracking = Yes:**

Use AskUserQuestion:
- header: "GitHub Repository"
- question: "GitHub tracking enabled, but no GitHub repository is linked. Create one now?"
- options:
  - "Create private repo (Recommended)" — Run `gh repo create --source=. --private --push`
  - "Create public repo" — Run `gh repo create --source=. --public --push`
  - "Skip for now" — Disable GitHub tracking (can enable later with `gh repo create`)

**If "Create private repo":**
```bash
if [ "$GH_AUTH" = "true" ]; then
  gh repo create --source=. --private --push && echo "GitHub repository created" || echo "Warning: Failed to create repository"
else
  echo "Warning: GitHub CLI not authenticated. Run 'gh auth login' first, then 'gh repo create --source=. --private --push'"
fi
```
Continue with `github.enabled: true`.

**If "Create public repo":**
```bash
if [ "$GH_AUTH" = "true" ]; then
  gh repo create --source=. --public --push && echo "GitHub repository created" || echo "Warning: Failed to create repository"
else
  echo "Warning: GitHub CLI not authenticated. Run 'gh auth login' first, then 'gh repo create --source=. --public --push'"
fi
```
Continue with `github.enabled: true`.

**If "Skip for now":**
- Set `github.enabled: false` in config.json (override user's earlier selection)
- Display note: "GitHub tracking disabled — no repository configured. Run `gh repo create --source=. --public` to enable later, then update `.planning/config.json`."

**If `HAS_GITHUB_REMOTE=true`:**
- Proceed normally with user's GitHub preferences
- No additional prompts needed

Create `.planning/config.json` with settings (workflow and display defaults are hardcoded, not user-selected):

```json
{
  "mode": "yolo|interactive",
  "depth": "quick|standard|comprehensive",
  "commit_docs": true|false,
  "pr_workflow": true|false,
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true
  },
  "github": {
    "enabled": true|false,
    "issueMode": "auto|ask|never"
  }
}
```

Note: `model_profile` is intentionally absent from initial config. Its absence triggers check-or-ask in `/kata-plan-phase` on first invocation.

**GitHub Tracking conditional logic:**

**If GitHub Tracking = Yes:**
- Ask the Issue Creation follow-up question
- Check for GitHub remote (see GitHub Repository Check above)
- Set `github.enabled` based on final state (true if remote exists or was created, false if skipped)
- Set `github.issueMode` based on Issue Creation choice:
  - "Auto" → `"auto"`
  - "Ask per milestone" → `"ask"`
  - "Never" → `"never"`
- Display note based on outcome:
  - If remote exists/created: "GitHub integration enabled. Milestones will be created via `gh` CLI."
  - If skipped: "GitHub tracking disabled — no repository configured."

**If GitHub Tracking = No:**
- Skip the Issue Creation question
- Skip the GitHub Repository Check
- Set `github.enabled: false`
- Set `github.issueMode: "never"`

**If commit_docs = No:**
- Set `commit_docs: false` in config.json
- Add `.planning/` to `.gitignore` (create if needed)

**If commit_docs = Yes:**
- No additional gitignore entries needed

**Scaffold preferences.json:**

```bash
echo '{}' > .planning/preferences.json
```

**Commit config.json and preferences.json:**

```bash
git add .planning/config.json .planning/preferences.json
git commit -m "$(cat <<'EOF'
chore: add project config

Mode: [chosen mode]
Depth: [chosen depth]
Preferences: scaffolded (empty)
EOF
)"
```

**Note:** Run `/kata-configure-settings` anytime to update these preferences.

**If pr_workflow = Yes:**

Ask about GitHub Actions release workflow:

```
AskUserQuestion([
  {
    header: "GitHub Actions",
    question: "Scaffold a GitHub Actions workflow to auto-publish on release?",
    multiSelect: false,
    options: [
      { label: "Yes (Recommended)", description: "Create .github/workflows/release.yml for npm publish" },
      { label: "No", description: "I'll set up CI/CD myself" }
    ]
  }
])
```

**If "Yes":**

Create `.github/workflows/release.yml`:

**Branch Protection Recommendation:**

After scaffolding, display:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ⚠ RECOMMENDED: Enable GitHub Branch Protection
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Since you've enabled PR workflow, we strongly recommend
protecting your main branch to prevent accidental direct pushes.

Go to: https://github.com/{owner}/{repo}/settings/branches

Enable these settings for `main`:
  ✓ Require a pull request before merging
  ✓ Do not allow bypassing the above settings
  ✗ Allow force pushes (uncheck this)

This ensures ALL changes go through PRs — even in emergencies,
you can temporarily disable protection from GitHub settings.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

```bash
mkdir -p .github/workflows
```

Write the workflow file:

```yaml
name: Publish to npm

on:
  push:
    branches:
      - main

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'

      - name: Get package info
        id: package
        run: |
          LOCAL_VERSION=$(node -p "require('./package.json').version")
          PACKAGE_NAME=$(node -p "require('./package.json').name")
          echo "local_version=$LOCAL_VERSION" >> $GITHUB_OUTPUT
          echo "package_name=$PACKAGE_NAME" >> $GITHUB_OUTPUT

          # Get published version (returns empty if not published)
          PUBLISHED_VERSION=$(npm view "$PACKAGE_NAME" version 2>/dev/null || echo "")
          echo "published_version=$PUBLISHED_VERSION" >> $GITHUB_OUTPUT

          echo "Local version: $LOCAL_VERSION"
          echo "Published version: $PUBLISHED_VERSION"

      - name: Check if should publish
        id: check
        run: |
          LOCAL="${{ steps.package.outputs.local_version }}"
          PUBLISHED="${{ steps.package.outputs.published_version }}"

          if [ -z "$PUBLISHED" ]; then
            echo "Package not yet published, will publish"
            echo "should_publish=true" >> $GITHUB_OUTPUT
          elif [ "$LOCAL" != "$PUBLISHED" ]; then
            echo "Version changed ($PUBLISHED -> $LOCAL), will publish"
            echo "should_publish=true" >> $GITHUB_OUTPUT
          else
            echo "Version unchanged ($LOCAL), skipping publish"
            echo "should_publish=false" >> $GITHUB_OUTPUT
          fi

      - name: Publish to npm
        if: steps.check.outputs.should_publish == 'true'
        run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

      - name: Create GitHub Release
        if: steps.check.outputs.should_publish == 'true'
        uses: softprops/action-gh-release@v2
        with:
          tag_name: v${{ steps.package.outputs.local_version }}
          name: v${{ steps.package.outputs.local_version }}
          generate_release_notes: true
          make_latest: true
```

Commit the workflow:

```bash
git add .github/workflows/release.yml
git commit -m "$(cat <<'EOF'
ci: add npm publish workflow

Publishes to npm and creates GitHub Release when:
- Push to main
- package.json version differs from published version

Requires NPM_TOKEN secret in repository settings.
EOF
)"
```

Display setup instructions:

```
✓ Created .github/workflows/release.yml

## Setup Required

Add NPM_TOKEN secret to your GitHub repository:
1. Go to repo Settings → Secrets and variables → Actions
2. Click "New repository secret"
3. Name: NPM_TOKEN
4. Value: Your npm access token (from npmjs.com → Access Tokens)

The workflow will auto-publish when you merge PRs that bump package.json version.
```

## Phase 5.5: Resolve Model Profile

Read model profile for agent spawning:

```bash
MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
```

Default to "balanced" if not set.

**Model lookup table:**

| Agent                     | quality | balanced | budget |
| ------------------------- | ------- | -------- | ------ |
| kata-project-researcher   | opus    | sonnet   | haiku  |
| kata-research-synthesizer | sonnet  | sonnet   | haiku  |
| kata-roadmapper           | opus    | sonnet   | sonnet |

Store resolved models for use in Task calls if milestone research/roadmapping is needed later.

## Phase 6: Done

**Commit PROJECT.md and config.json (if not already committed):**

Check if uncommitted changes exist and commit them:

```bash
# Check for uncommitted planning files
if git status --porcelain .planning/PROJECT.md .planning/config.json 2>/dev/null | grep -q '.'; then
  git add .planning/PROJECT.md .planning/config.json
  git commit -m "$(cat <<'EOF'
docs: initialize project

Project context and workflow configuration.
EOF
)"
fi
```

**Self-validation — verify all required artifacts exist before displaying completion:**

```bash
MISSING=""
[ ! -f .planning/PROJECT.md ] && MISSING="${MISSING}\n- .planning/PROJECT.md"
[ ! -f .planning/config.json ] && MISSING="${MISSING}\n- .planning/config.json"
[ ! -f .planning/preferences.json ] && MISSING="${MISSING}\n- .planning/preferences.json"
[ ! -f .planning/phases/pending/.gitkeep ] && MISSING="${MISSING}\n- .planning/phases/pending/.gitkeep"
[ ! -f .planning/phases/active/.gitkeep ] && MISSING="${MISSING}\n- .planning/phases/active/.gitkeep"
[ ! -f .planning/phases/completed/.gitkeep ] && MISSING="${MISSING}\n- .planning/phases/completed/.gitkeep"
if [ -n "$MISSING" ]; then
  echo "MISSING ARTIFACTS:${MISSING}"
else
  echo "ALL ARTIFACTS PRESENT"
fi
```

**If anything is missing:** Create the missing artifacts now. Do NOT proceed to the completion banner until all artifacts exist.

**Display completion banner:**


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata ► PROJECT INITIALIZED ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**[Project Name]**

| Artifact    | Location                     |
| ----------- | ---------------------------- |
| Project     | `.planning/PROJECT.md`       |
| Config      | `.planning/config.json`      |
| Preferences | `.planning/preferences.json` |

Ready for milestone planning ✓

**If pr_workflow = Yes, append:**

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ⚠ RECOMMENDED: Enable Branch Protection
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PR workflow is enabled. Protect your main branch:

  https://github.com/{owner}/{repo}/settings/branches

Settings for `main`:
  ✓ Require a pull request before merging
  ✓ Do not allow bypassing the above settings
  ✗ Allow force pushes (uncheck)
```

───────────────────────────────────────────────────────────────

## ▶ Next Up

**Define your first milestone**

`/kata-add-milestone` — research, requirements, and roadmap

<sub>`/clear` first → fresh context window</sub>

───────────────────────────────────────────────────────────────


</process>

<output>

- `.planning/PROJECT.md`
- `.planning/config.json`
- `.planning/preferences.json`

</output>

<success_criteria>

- [ ] .planning/ directory created
- [ ] .planning/phases/pending/, active/, completed/ directories created
- [ ] Git repo initialized
- [ ] Brownfield detection completed
- [ ] Deep questioning completed (threads followed, not rushed)
- [ ] PROJECT.md captures full context → **committed**
- [ ] config.json has mode, depth, commit_docs, pr_workflow, github → **committed**
- [ ] preferences.json scaffolded as `{}` → **committed**
- [ ] Self-validation passed (all artifacts exist)
- [ ] User knows next step is `/kata-add-milestone`

**Atomic commits:** PROJECT.md and config.json are committed. If context is lost, artifacts persist.

</success_criteria>