kata-new-project

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
• .planning/intel/ — empty v2 intel scaffolding (index.json, conventions.json, summary.md)

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

<execution_context>

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

</execution_context>

Phase 1: Setup

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

1. Abort if project exists:

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

   if [ -d .git ] || [ -f .git ]; then
       echo "Git repo exists in current directory"
   else
       git init -b main
       echo "Initialized new git repo"
   fi
   

3. Detect existing code (brownfield detection):

   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:

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.

Scaffold empty intel for greenfield progressive capture:

# Scaffold empty intel for greenfield progressive capture
node "scripts/scaffold-intel.cjs" 2>/dev/null || echo "Warning: Intel scaffolding skipped"

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

For greenfield projects:

Initialize requirements as hypotheses:

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

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

## Key Decisions

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

Last updated footer:

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

Do not compress. Capture everything gathered.

Commit PROJECT.md:

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

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

Phase 5: Workflow Preferences

6 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: "Model Quality",
    question: "Which AI models for planning agents?",
    multiSelect: false,
    options: [
      { label: "Balanced (Recommended)", description: "Opus for planning, Sonnet for execution — good quality/cost ratio" },
      { label: "Quality", description: "Opus for research/planning — higher cost, deeper analysis" },
      { label: "Budget", description: "Sonnet/Haiku where possible — fastest, lowest cost" }
    ]
  },
  {
    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 PR Workflow = Yes, ask about worktrees:
{
  header: "Git Worktrees",
  question: "Use git worktrees for plan isolation? (each plan agent gets its own branch and working directory)",
  multiSelect: false,
  options: [
    { label: "Yes (Recommended)", description: "Each plan gets an isolated worktree and branch" },
    { label: "No", description: "Plans share the working directory (standard git workflow)" }
  ]
}
# If PR Workflow = No, skip this question entirely (worktrees require PR workflow).

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

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

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

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

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

Map user selections to values:

• "Balanced (Recommended)" → "balanced"
• "Quality" → "quality"
• "Budget" → "budget"

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.issue_mode 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.issue_mode: "never"

Worktree conditional logic:

If PR Workflow = Yes AND Worktrees = Yes:

• Add "worktree": { "enabled": true } to config.json

If PR Workflow = Yes AND Worktrees = No:

• Add "worktree": { "enabled": false } to config.json

If PR Workflow = No:

• Do NOT add worktree key to config.json (absence = disabled)

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

Commit config.json:

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

Mode: [chosen mode]
Depth: [chosen depth]
EOF
)"

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

If Worktrees = Yes (after config.json is written):

Call setup-worktrees.sh to convert to bare repo + worktree layout:

WORKTREE_OUTPUT=$(bash "scripts/setup-worktrees.sh" 2>&1) || WORKTREE_FAILED=true
echo "$WORKTREE_OUTPUT"

If setup failed (WORKTREE_FAILED=true), diagnose and retry (up to 2 retries):

Read the error output and fix the underlying issue:

Error message contains	Fix
"uncommitted changes"	git add -A && git commit -m "chore: commit pending changes before worktree setup"
"Not a git repository"	git init && git add -A && git commit -m "chore: initial commit"
"pr_workflow must be true"	node scripts/kata-lib.cjs set-config "pr_workflow" "true"

After applying the fix, retry:

WORKTREE_OUTPUT=$(bash "scripts/setup-worktrees.sh" 2>&1) || WORKTREE_FAILED=true
echo "$WORKTREE_OUTPUT"

If setup still fails after retries, revert and warn the user:

node scripts/kata-lib.cjs set-config "worktree.enabled" "false"

Display the error output and tell the user worktree setup failed, their preference was reverted to false, and they can enable it later via /kata-configure-settings.

After successful worktree setup, cd into the main worktree:

cd main

All subsequent operations (GitHub Actions scaffold, validation, commits, push) happen inside main/. This is the working directory for the project from now on.

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

mkdir -p .github/workflows

Write the workflow file:

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:

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 6: Done

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

Check if uncommitted changes exist and commit them:

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

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"
[ -f .planning/intel/index.json ] || MISSING="${MISSING}\n- .planning/intel/index.json"
[ -f .planning/intel/conventions.json ] || MISSING="${MISSING}\n- .planning/intel/conventions.json"
[ -f .planning/intel/summary.md ] || MISSING="${MISSING}\n- .planning/intel/summary.md"
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
Intel	.planning/intel/

Ready for milestone planning ✓

Configure build commands, test commands, and version files:

/kata-configure-settings

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)

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

If worktree.enabled = true:

Worktrees are active. main/ is now your project root.

Before continuing, restart Claude Code from inside main/:

cd main
claude

All skills, git commands, and file edits run from main/ going forward.

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

▶ Next Up

Define your first milestone

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

/clear first → fresh context window

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

• .planning/PROJECT.md
• .planning/config.json
• .planning/intel/index.json
• .planning/intel/conventions.json
• .planning/intel/summary.md

<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
• .planning/intel/ scaffolded with empty v2 schema (index.json, conventions.json, summary.md)
• Self-validation passed (all artifacts exist, including intel files)
• 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>