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".
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"}
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.
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:
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:Publishtonpmon:push:branches:-mainjobs:publish:runs-on:ubuntu-latestpermissions:contents:writesteps:-name:Checkoutuses:actions/checkout@v4-name:SetupNode.jsuses:actions/setup-node@v4with:node-version:'20'registry-url:'https://registry.npmjs.org'-name:Getpackageinfoid:packagerun:|
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=$(npmview"$PACKAGE_NAME"version2>/dev/null||
[ ]
[ ]
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 filesif 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:
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)
