菜单
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".
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/gannonh/kata-skills --skill kata-new-project命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| 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"} |
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>
MANDATORY FIRST STEP — Execute these checks before ANY user interaction:
Abort if project exists:
[ -f .planning/PROJECT.md ] && echo "ERROR: Project already initialized. Use /kata-track-progress" && exit 1
Initialize git repo in THIS directory (required even if inside a parent repo):
[ -d .git ] || [ -f .git ];
git init -b main
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.
If existing code detected and .planning/codebase/ doesn't exist:
Check the results from setup step:
CODE_FILES is non-empty OR HAS_PACKAGE is "yes"HAS_CODEBASE_MAP is NOT "yes"Use AskUserQuestion:
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.
Display stage banner:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Kata ► QUESTIONING ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Open the conversation:
Use AskUserQuestion:
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:
Consult questioning.md for techniques:
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:
If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally.
Loop until "Create PROJECT.md" selected.
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:
.planning/codebase/ARCHITECTURE.md and STACK.md## 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
)"
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:
gh repo create --source=. --private --pushgh repo create --source=. --public --pushgh 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":
github.enabled: false in config.json (override user's earlier selection)gh repo create --source=. --public to enable later, then update .planning/config.json."If HAS_GITHUB_REMOTE=true:
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""quality""budget"GitHub Tracking conditional logic:
If GitHub Tracking = Yes:
github.enabled based on final state (true if remote exists or was created, false if skipped)github.issue_mode based on Issue Creation choice:
"auto""ask""never"gh CLI."If GitHub Tracking = No:
github.enabled: falsegithub.issue_mode: "never"Worktree conditional logic:
If PR Workflow = Yes AND Worktrees = Yes:
"worktree": { "enabled": true } to config.jsonIf PR Workflow = Yes AND Worktrees = No:
"worktree": { "enabled": false } to config.jsonIf PR Workflow = No:
If commit_docs = No:
commit_docs: false in config.json.planning/ to .gitignore (create if needed)If commit_docs = Yes:
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.
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 claudeAll skills, git commands, and file edits run from
main/going forward.
───────────────────────────────────────────────────────────────
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/intel/ scaffolded with empty v2 schema (index.json, conventions.json, summary.md)/kata-add-milestoneAtomic commits: PROJECT.md and config.json are committed. If context is lost, artifacts persist.
</success_criteria>