Skip to content

vt-c-1-bootstrap

Phase 1 - Scaffold your project with best-practice structure, configurations, and documentation. Creates CI/CD, docs folders, and toolkit integration.

Plugin: core-standards
Category: Development Workflow
Command: /vt-c-1-bootstrap

Phase 1: Bootstrap - Project Scaffolding

Create your project structure with industry best practices, tooling, and toolkit integration.

Workflow Position

/vt-c-0-start  →  [ /vt-c-1-bootstrap ]  →  /vt-c-2-plan  →  /vt-c-3-build  →  /vt-c-4-review  →  /vt-c-5-finalize  →  /vt-c-6-operate
              ▲ YOU ARE HERE

Invocation

# Interactive mode
/vt-c-1-bootstrap

# With arguments
/vt-c-1-bootstrap typescript-api my-service
/vt-c-1-bootstrap rails-api my-app

Execution Instructions

Step 0.5: Project Registration Check

  1. Read TOOLKIT_ROOT/intake/projects.yaml (resolve TOOLKIT_ROOT from this skill's base directory)
  2. Check if the current working directory appears in the projects list
  3. If NOT registered and the project has a CLAUDE.md or .design-state.yaml:
  4. Ask: "This project is not registered in the toolkit. Register now to enable cross-project scanning and journal aggregation?"
  5. Options: Register now (invoke /vt-c-project-register) | Skip for now
  6. If registered: continue silently

This command invokes the bootstrap skill. Follow all instructions from the bootstrap skill, then add the workflow context below.

Before Starting

  1. Load and execute the full bootstrap skill from skills/vt-c-bootstrap/SKILL.md
  2. Follow all its steps for project creation

After Bootstrap Completes

Add this workflow-specific guidance:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase 1 Complete: Project Bootstrapped
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Created:
✓ Project structure (src/, tests/, docs/)
✓ CI/CD workflows (.github/workflows/)
✓ CLAUDE.md with project instructions
✓ Git hooks (branch-based workflow enforcement)
✓ Toolkit integration folders:
  - docs/solutions/     → For compound-docs
  - docs/vt-c-journal/       → For session-journal
  - docs/runbooks/      → For incident response
  - docs/adr/           → For Architecture Decision Records
  - docs/test-plan.md   → For manual/acceptance test tracking

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
RECOMMENDED: Set up Spec-Driven Development
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

For production applications, we recommend SpecKit:

→ /vt-c-specify-and-validate

This creates:
- .specify/memory/constitution.md → Project principles & constraints
- specs/[N]-feature/spec.md       → Requirements specification
- specs/[N]-feature/plan.md       → Implementation plan

Benefits:
• Spec-aware planning in /vt-c-2-plan
• Validation against spec in /vt-c-4-review
• Constitution compliance in /vt-c-5-finalize
• Drift detection between code and spec

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OPTIONAL: User Documentation Site
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If this project will have end-user documentation (user manuals, API
guides, feature docs), we can scaffold a documentation site now.

→ Reply "yes" to create a docs/user-manual/ MkDocs site

This creates:
- docs/user-manual/mkdocs.yml     → Docs site configuration
- docs/user-manual/docs/index.md  → Home page
- docs/user-manual/docs/getting-started.md → Getting started stub
- docs/user-manual/docs/features/ → Feature documentation (updated per specs)

Benefits:
• Documentation is tracked as a deliverable in each specs
• /vt-c-3-build reminds you to update docs after each feature
• /vt-c-4-review checks documentation completeness
• /vt-c-5-finalize builds the docs site and verifies no broken links

If user accepts, create:
docs/user-manual/ ├── mkdocs.yml # MkDocs Material config (project name from PRD/CLAUDE.md) ├── docs/ │ ├── index.md # "Welcome to [Project Name]" with brief overview │ ├── getting-started.md # Setup/onboarding stub for end users │ └── features/ # One page per major feature (added per specs) │ └── .gitkeep 
The mkdocs.yml should use MkDocs Material with the same deep orange theme as the toolkit.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OPTIONAL: Issue Tracking with Beads
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

For projects that benefit from persistent, cross-session issue tracking
with dependency awareness, we can initialize Beads (a git-backed
distributed issue tracker).

→ Reply "yes" to initialize Beads issue tracking

This creates:
- .beads/issues.jsonl    → Git-tracked issue database (source of truth)
- .beads/beads.db        → Local SQLite cache (gitignored)
- Git hooks for automatic sync on commit/merge

Benefits:
• Issues persist across sessions (no more lost TodoWrite items)
• `bd ready` finds unblocked work automatically
• `bd prime` injects compact context (~1-2k tokens) at session start
• Dependency tracking: blocks, related, parent-child, discovered-from
• Hash-based IDs prevent collision in multi-agent/multi-branch work

Requires: Beads CLI (`bd`) installed. See Beads Integration guide.

If user accepts:
1. Run `bd init --quiet` in project root
2. Run `bd hooks install` to add git hooks
3. Add to .gitignore: `.beads/beads.db`, `.beads/bd.sock`, `.beads/*.log`
4. The .beads/issues.jsonl and .beads/deletions.jsonl are git-tracked

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NEXT STEPS:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Option A (Recommended): Spec-driven development
  1. /vt-c-specify-and-validate  → Create constitution & specs
  2. /vt-c-2-plan "Your feature" → Spec-aware planning

Option B: Quick start (smaller projects)
  → /vt-c-2-plan "Your feature" → Direct planning

The plan phase will:
- Research best practices
- Design architecture
- Create implementation plan
- Identify potential risks

If User Has Existing PRD

Reference the PRD in the planning suggestion:

Found: PRD.md

Suggested next step:
/vt-c-2-plan "Implement [main feature from PRD]"

Project Types Reference

Type Stack Use For
typescript-api Node.js, Express, TypeScript, Prisma REST APIs
typescript-cli Node.js, TypeScript, Commander CLI tools
rails-api Ruby, Rails, PostgreSQL Rails API-only
rails-full Ruby, Rails, Hotwire, PostgreSQL Full-stack Rails
react-app React, TypeScript, Vite SPAs
nextjs-app Next.js, TypeScript, Tailwind Full-stack React

What Gets Created

See the full bootstrap skill for complete details. Key items:

  • .github/workflows/ci.yml - CI pipeline
  • .github/workflows/deploy.yml - Deployment workflow
  • CLAUDE.md - Project-specific AI instructions
  • .git/hooks/pre-commit - Branch workflow enforcement (blocks commits to main/master)
  • docs/solutions/patterns/critical-patterns.md - For continuous learning
  • docs/test-plan.md - Test plan for manual/acceptance test tracking
  • Environment templates and configs

After bootstrap, consider running /vt-c-claudemd-evolve to refine the generated CLAUDE.md with project-specific patterns as you learn them.

After bootstrap completes, set up spec-driven development:

What is SpecKit?

SpecKit enforces spec-driven development where: - Constitution defines project principles, constraints, and non-negotiables - Spec captures detailed requirements that code must satisfy - Plan breaks down implementation into validated steps

Setting Up SpecKit

# Option 1: Use toolkit command (recommended)
/vt-c-specify-and-validate

# Option 2: Manual setup with SpecKit CLI
# Install: uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify init . --ai claude

What SpecKit Creates

.specify/
└── memory/
    └── constitution.md   # Project principles & constraints
specs/
└── [N]-feature/
    ├── spec.md           # Requirements specification
    └── plan.md           # Implementation plan

Benefits Throughout Workflow

Phase Without SpecKit With SpecKit
/vt-c-2-plan General planning Constrained by constitution
/vt-c-3-build General guidance Validates against spec
/vt-c-4-review Quality review + Spec compliance check
/vt-c-5-finalize Standard checks + Constitution validation