vt-d-1-bootstrap¶

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

Plugin: vt-product-dev
Category: Development Workflow
Command: /vt-d-1-bootstrap

Phase 1: Bootstrap - Project Scaffolding¶

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

Workflow Position¶

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

Invocation¶

# Interactive mode
/vt-d-1-bootstrap

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

Execution Instructions¶

Step 0.5: Project Registration Check¶

Run the shared registration check — single source of truth. Do NOT inline the logic here (duplicating it re-introduces the cross-copy drift SPEC-150 removed):

bash ~/.claude/skills/vt-c-project-register/scripts/check_registration.sh

Act on the emitted status line (stdout); any line other than UNREGISTERED … means continue silently (keeps the gate soft even if the vocabulary grows): - REGISTERED, TOOLKIT_REPO, NOT_GIT, or DEGRADED … → continue silently. - UNREGISTERED skips=N escalate=<bool> → offer registration (soft gate — never block): - Ask (AskUserQuestion): "This project isn't registered in the toolkit, so its learnings won't reach the intake pipeline. Register now?" - If escalate=true, strengthen the wording: note that learnings have not been reaching the toolkit across N sessions. - Register now → invoke /vt-c-project-register. - Skip for now → run bash ~/.claude/skills/vt-c-project-register/scripts/check_registration.sh --record-skip, then continue.

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

Before Starting¶

Load and execute the full bootstrap skill from skills/vt-d-bootstrap/SKILL.md
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 spec-driven development:

→ /vt-d-spec-from-requirements

This creates:
- specs/[N]-feature/spec.md       → Requirements specification
  (the constitution lives at .specify/memory/constitution.md — author it once)
- specs/[N]-feature/plan.md       → Implementation plan (from /vt-d-2-plan)

Benefits:
• Spec-aware planning in /vt-d-2-plan
• Validation against spec in /vt-d-4-review
• Constitution compliance in /vt-d-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-d-3-build reminds you to update docs after each feature
• /vt-d-4-review checks documentation completeness
• /vt-d-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-d-spec-from-requirements → Create a spec
  2. /vt-d-2-plan "Your feature"  → Spec-aware planning

Option B: Quick start (smaller projects)
  → /vt-d-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-d-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-t-claudemd-evolve to refine the generated CLAUDE.md with project-specific patterns as you learn them.

Spec-Driven Development (Recommended)¶

After bootstrap completes, set up spec-driven development for production applications.

What it is¶

Spec-driven development enforces that code satisfies a written specification: - Constitution (.specify/memory/constitution.md) defines project principles, constraints, and non-negotiables - Spec captures detailed requirements that code must satisfy - Plan breaks implementation down into validated steps

Setting it up¶

/vt-d-spec-from-requirements   # Create a spec from informal requirements
/vt-d-activate                 # Load the spec for development
/vt-d-2-plan "Your feature"    # Spec-aware planning

The constitution lives at .specify/memory/constitution.md; author it once and it guides every phase.

What it creates¶

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

Benefits Throughout Workflow¶

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