New Project Bootstrap

Also ask for the project name and a one-sentence description.

Record the project type, subtype, name, and description for DECISIONS.md.

Rounds 2-4: Stack, Scope, Preferences

Read the relevant section from references/interview-trees.md based on the chosen project type. Ask questions from:

• Round 2: Stack & Framework choices
• Round 3: Scope & Features (MVP definition)
• Round 4: Preferences & Constraints (deployment, team, timeline, design)

After each answer, record the decision and rationale for DECISIONS.md.

1B: Research

After the interview, research the chosen stack. Read the relevant section from references/stack-profiles.md for research prompts.

Context7 research: For each major dependency in the chosen stack:

1. Call resolve-library-id to find the library
2. Call query-docs with the specific query from stack-profiles.md
3. Note key patterns, conventions, and best practices

Web research: Run the WebSearch prompts from stack-profiles.md (substitute {{YEAR}} with the current year). Focus on:

• Production best practices for the chosen stack
• Common pitfalls and how to avoid them
• Recommended project structure

Compile research findings — these inform documentation and scaffold decisions.

Phase 2: Document

Read references/doc-templates.md for all templates.

Create 7 files in docs/ plus update the CLAUDE.md files. Draft each document using information from Phase 1 (interview answers + research findings). Fill in all template placeholders with project-specific content.

Document creation order:

1. docs/PROJECT.md — Project overview, problem statement, target users, key features
2. docs/STACK.md — Technology table, framework details, infrastructure, dev tools
3. docs/ARCHITECTURE.md — System overview, directory structure, modules, data flow, design patterns
4. docs/CONVENTIONS.md — Code style, git workflow, component patterns, testing, error handling
5. docs/DECISIONS.md — Pre-populate with all decisions captured during Phase 1 interview
6. docs/ROADMAP.md — Vision, 3 phases with task checklists, future considerations
7. docs/TEAM.md — Team roster (filled in Phase 4), communication patterns, PR workflow

CLAUDE.md updates:

Update the root CLAUDE.md with:

• Project summary (1-2 sentences)
• Stack summary (key technologies)
• Convention pointers (reference docs/CONVENTIONS.md)
• Available skills list
• Quick reference commands (dev server, test, build, lint)

Update .claude/CLAUDE.md with:

• Agent coordination info
• Doc references (paths to all docs/ files)
• Available skills and when to use them
• Team workflow notes

For each document, draft the full content in one pass, then review for consistency with other docs. Use the section-by-section approach from doc-coauthoring when a section needs user input — but most content should be derivable from Phase 1 answers.

Phase 3: Build

3A: Scaffold

1. Run scripts/init-project.sh --name "{{PROJECT_NAME}}" to create the universal skeleton
2. Read the relevant stack profile from references/stack-profiles.md for init commands
3. Execute the stack-specific init commands (e.g., npx create-next-app, cargo init)
4. Install core packages from the stack profile
5. Install optional packages based on features chosen in Phase 1
6. Create configuration files (linter, formatter, tsconfig, etc.)
7. Create .env.example with all required environment variables documented
8. Update .gitignore with stack-specific entries from the stack profile
9. Create initial git commit: git add -A && git commit -m "chore: initial project scaffold"

If the project directory already has files (e.g., from the boilerplate), integrate the scaffold around existing files rather than overwriting them.

3B: Generate Agents

Read references/agent-blueprints.md for templates.

Always create these universal agents:

• code-reviewer.md — Opus, plan mode, read-only tools, PR review specialist
• project-lead.md — Opus, default mode, full tools, project coordinator

Then create 3-5 type-specific agents based on the project type. Use the selection guide in agent-blueprints.md to determine which specialists to create.

Write each agent to .claude/agents/{{agent-name}}.md with:

• YAML frontmatter (name, model, description, mode, tools)
• System prompt referencing specific docs/ files by path
• Responsibilities section tailored to this project
• Workflow section with branch/PR conventions
• Constraints section with guardrails

All agents must be instructed on the GitHub issue-driven workflow (using the gh-cli skill for all GitHub operations):

1. Claim a GitHub issue (gh issue edit N --add-assignee @me)
2. Create a branch from the issue (gh issue develop N --branch type/issue-N-description)
3. Work in plan mode — submit plan to team lead for approval before implementing
4. Implement changes following project conventions
5. Write/update tests
6. Push and create a PR linking to the issue (gh pr create --title "type: description" --body "Closes #N")
7. Code reviewer reviews the PR (gh pr review)
8. Address review feedback, then merge (gh pr merge --squash --delete-branch)

All type-specific agents must use mode: plan (require plan approval). Only the project-lead uses default mode. When a teammate finishes planning, the team lead reviews and approves or rejects with feedback before the teammate can implement.

3C: Generate Rules

Read references/rules-blueprints.md for templates.

Always create these universal rules:

• .claude/rules/shared/git-workflow.md — Branch naming, commit format, PR process
• .claude/rules/shared/code-style.md — Formatting, naming, file organization
• .claude/rules/shared/documentation.md — When to update docs, comment style

Then create framework-specific rules based on the chosen stack. Use the selection guide in rules-blueprints.md. Write rules to .claude/rules/{{layer}}/{{rule-name}}.md with appropriate globs frontmatter for path scoping.

Organize rules by layer:

• shared/ — Apply everywhere
• frontend/ — Frontend-specific
• backend/ — Backend-specific
• testing/ — Test file conventions

3D: Generate Hooks

Read references/hooks-blueprints.md for templates.

Set up context rot mitigation hooks that prevent degradation during long-running team sessions:

1. Create .claude/hooks/ directory
2. Create .claude/hooks/session-start.js from the SessionStart hook template
3. Create .claude/hooks/pre-compact.js from the PreCompact hook template
4. Create or merge into .claude/settings.json with:
   • CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70 environment variable
   • Hook config pointing to both hook scripts
5. Add the Context Recovery block from hooks-blueprints.md to .claude/CLAUDE.md
6. Verify hooks execute without errors: node .claude/hooks/session-start.js <<< '{"source":"startup"}' and node .claude/hooks/pre-compact.js <<< '{}'

If .claude/settings.json already exists, merge the new keys into the existing file rather than overwriting it. If .claude/settings.local.json exists, do not modify it — it contains user-specific overrides.

Phase 4: Launch

4A: Create Team

Use TeamCreate to create a development team for the project.

4B: Create GitHub Issues from Roadmap

Read docs/ROADMAP.md Phase 1 items. For each task:

1. Create a GitHub issue using gh issue create --title "type: description" --labels "phase-1,area" --body "..." with acceptance criteria in the body
2. Also create a local task with TaskCreate that references the GitHub issue number
3. Set appropriate dependencies between tasks with TaskUpdate

This ensures every piece of work is tracked as a GitHub issue — the source of truth for project progress.

4C: Spawn Team Members

Spawn team members from the agent definitions created in Phase 3B. All type-specific agents must be spawned with plan mode required so the team lead must approve their implementation plans before they write code.

1. Spawn the code-reviewer agent first (needed for PR reviews)
2. Spawn the project-lead agent (default mode — coordinates and approves plans)
3. Spawn type-specific agents with mode: plan as needed for Phase 1 tasks

Brief each team member with:

• Project name and description
• Their role and key responsibilities
• Paths to relevant docs/ files they should read
• The GitHub issue-driven workflow: claim issue → branch → plan (get approval) → implement → PR → review → merge
• That they must use gh CLI for all GitHub operations (issues, PRs, reviews)
• Subagent delegation pattern: Always spawn Task subagents for implementation work — keep your own context clean for coordination, planning, and communication. See docs/TEAM.md for full details.
• Context management: Hooks are configured for automatic context recovery (70% autocompact threshold, SessionStart hook restores state after compaction). If responses degrade, run /compact proactively.

4D: Assign Work and Wait

Use TaskUpdate to assign initial tasks to appropriate team members based on their specialization. Tell teammates which GitHub issue to claim.

Important: Wait for teammates to complete their tasks before proceeding. Do not start implementing tasks yourself — use delegate mode to focus on coordination. The project-lead should:

• Monitor teammate progress
• Review and approve/reject teammate plans when they submit them
• Ensure code-reviewer reviews every PR before merge
• Only proceed to the next phase when all current phase tasks are complete
• Reassign work if a teammate gets stuck

Phase 5: Shutdown

Gracefully shut down the team after all work is complete. TeamDelete will fail if teammates are still active — the shutdown handshake ensures it succeeds.

5A: Shutdown Teammates

For each teammate:

1. Send a shutdown_request via SendMessage with type: "shutdown_request"
2. Wait for the teammate to respond with shutdown_response and approve: true
3. If a teammate rejects, check why — they may have unfinished work. Resolve the blocker, then retry.

Shut down implementer agents first, then the code-reviewer, then the project-lead last.

5B: Clean Up Team

After all teammates have acknowledged shutdown:

1. Call TeamDelete to remove the team and its task directory
2. This cleans up ~/.claude/teams/{{team-name}}/ and ~/.claude/tasks/{{team-name}}/

5C: Final Updates

1. Update docs/ROADMAP.md — check off completed tasks, note any deferred work
2. Create a summary commit: git add -A && git commit -m "chore: complete project bootstrap"
3. Report a summary to the user: what was built, how many issues created, team composition, and next steps

Reference Files

Integration with Existing Skills

• gh-cli — Used by ALL agents for GitHub operations (issues, PRs, reviews, branches). Core to the issue-driven development workflow. Every agent system prompt should reference this skill.
• doc-coauthoring — Available for future doc revisions. Reference in generated CLAUDE.md.
• frontend-design — Add to skills list for frontend-architect agent on web projects.
• web-artifacts-builder — Available for frontend agents doing React/Tailwind/shadcn prototyping.
• skill-creator — Reference in generated CLAUDE.md for creating project-specific skills later.

Error Handling

• If a stack init command fails, check the error, try to resolve (missing dependency, wrong Node version), and retry once. If still failing, inform the user and continue with manual setup.
• If Context7 returns no results for a library, fall back to WebSearch for documentation.
• If the project directory has existing files that conflict with scaffold, ask the user how to proceed rather than overwriting.