Run `/kata-map-codebase` first, then return to `/kata-new-project`

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

undefined

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

**Key Decisions:**

Initialize with any decisions made during questioning:

```markdown

**Last updated footer:**

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

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

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: "Execution",
    question: "Run plans in parallel?",
    multiSelect: false,
    options: [
      { label: "Parallel (Recommended)", description: "Independent plans run simultaneously" },
      { label: "Sequential", description: "One plan at a time" }
    ]
  },
  {
    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" }
    ]
  }
]

**GitHub Repository Check (conditional):**

**If GitHub Tracking = Yes:**

After confirming GitHub preferences, check for existing remote:

```bash

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

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

questions: [
  {
    header: "Research",
    question: "Research before planning each phase? (adds tokens/time)",
    multiSelect: false,
    options: [
      { label: "Yes (Recommended)", description: "Investigate domain, find patterns, surface gotchas" },
      { label: "No", description: "Plan directly from requirements" }
    ]
  },
  {
    header: "Plan Check",
    question: "Verify plans will achieve their goals? (adds tokens/time)",
    multiSelect: false,
    options: [
      { label: "Yes (Recommended)", description: "Catch gaps before execution starts" },
      { label: "No", description: "Execute plans without verification" }
    ]
  },
  {
    header: "Verifier",
    question: "Verify work satisfies requirements after each phase? (adds tokens/time)",
    multiSelect: false,
    options: [
      { label: "Yes (Recommended)", description: "Confirm deliverables match phase goals" },
      { label: "No", description: "Trust execution, skip verification" }
    ]
  },
  {
    header: "Model Profile",
    question: "Which AI models for planning agents?",
    multiSelect: false,
    options: [
      { label: "Balanced (Recommended)", description: "Sonnet for most agents — good quality/cost ratio" },
      { label: "Quality", description: "Opus for research/roadmap — higher cost, deeper analysis" },
      { label: "Budget", description: "Haiku where possible — fastest, lowest cost" }
    ]
  },
  {
    header: "Statusline",
    question: "Enable Kata statusline? (shows model, context usage, update status)",
    multiSelect: false,
    options: [
      { label: "Yes (Recommended)", description: "Display live session info in Claude Code statusline" },
      { label: "No", description: "Use default Claude Code statusline" }
    ]
  }
]

{
  "mode": "yolo|interactive",
  "depth": "quick|standard|comprehensive",
  "parallelization": true|false,
  "commit_docs": true|false,
  "pr_workflow": true|false,
  "model_profile": "quality|balanced|budget",
  "display": {
    "statusline": true|false
  },
  "workflow": {
    "research": true|false,
    "plan_check": true|false,
    "verifier": true|false
  },
  "github": {
    "enabled": true|false,
    "issueMode": "auto|ask|never"
  }
}

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

Mode: [chosen mode]
Depth: [chosen depth]
Parallelization: [enabled/disabled]
Workflow agents: research=[on/off], plan_check=[on/off], verifier=[on/off]
EOF
)"

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" }
    ]
  }
])

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ⚠ 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.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

mkdir -p .github/workflows

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

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

✓ Created .github/workflows/release.yml

**If statusline = Yes:**

Update `.claude/settings.json` with statusline configuration:

```bash

The statusline hook will be automatically installed on next session start by Kata's SessionStart hook.

**If statusline = No:**

No changes to `.claude/settings.json`.

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

undefined

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

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