mk:bootstrap

End-to-end project orchestrator for new projects from scratch. Research -> design -> plan -> scaffold -> implement -> docs.

CLI boundary: npx mewkit init = project infrastructure (.claude/). mk:bootstrap = application code + full pipeline. Zero overlap. Never touch .claude/.

What This Skill Does

Orchestrates the complete journey from idea to running code for a brand-new project. Handles research, design, planning, file scaffolding, implementation via mk:cook, and documentation generation. Supports 4 execution modes ranging from fully-interactive (--full) to fully-automated (--fast).

When to Use

Explicit invocation only — never auto-activates.

mk:bootstrap [requirements]
mk:bootstrap [requirements] --full
mk:bootstrap [requirements] --fast
mk:bootstrap [requirements] --parallel

Do NOT invoke when:

• Project already has source code — use mk:plan-creator + mk:cook directly
• You only need kit setup — use CLI (npx mewkit init)
• You need autonomous multi-hour builds of specified products — use mk:autobuild
• You need single-task feature work on existing projects — use mk:cook

Example Prompt

Bootstrap a new full-stack SaaS application with a React frontend, Express API, PostgreSQL database, and JWT authentication. Include user registration, role-based access control, and a dashboard with real-time metrics.

Core Capabilities

• Research — parallel subagent research on validation, competition, tech stack, design patterns
• Design — UI/UX design via ui-ux-designer subagent, design guidelines document
• Planning — structured plan via mk:plan-creator with architecture, modules, file structure
• Scaffolding — progressive file generation following naming conventions and dependency order
• Implementation — via mk:cook with TDD cycle, review, fix-first resolution
• Documentation — via mk:docs-init generating docs/ directory and README
• Validation — post-scaffold validation catching missing files and placeholder leaks

Arguments

Argument	Type	Description
requirements	string	Required. Natural language description of what to build
--full	flag	Maximum user control, gates at every step
--fast	flag	No user gates, maximum speed, auto-commit
--parallel	flag	Parallel implementation for independent components
(default)	-	Auto mode: balanced, design gate only

Modes

Mode	Flag	Research	Design	Plan Flag	Cook Flag	Git
Auto	(default)	Parallel researchers	UI/UX if frontend	--auto	--auto	Auto init
Full	--full	Parallel researchers, gate	UI/UX if frontend, gate	--hard	(interactive)	Ask user
Fast	--fast	6 parallel batch, no gate	Skip	--fast	--auto	Auto init + commit
Parallel	--parallel	Parallel researchers, no gate	UI/UX if frontend, gate	--parallel	--parallel	Auto init

Workflow

Pre-workflow. Bootstrap IS the full workflow for new projects:

mk:bootstrap -> [research -> design -> plan -> scaffold -> cook -> docs] -> done

For subsequent features on the same project: use mk:plan-creator -> mk:cook directly.

Routing

Parse first flag from arguments:

• --full -> load references/workflow-full.md
• --fast -> load references/workflow-fast.md
• --parallel -> load references/workflow-parallel.md
• default -> load references/workflow-auto.md

Each workflow file defines the exact steps for that mode. After plan + scaffold, all modes load references/shared-phases.md for implementation -> docs -> final report.

Planning BEFORE Scaffolding

Plan first, scaffold second. The plan tells us WHAT to scaffold — planning is NOT optional.

1. Plan — invoke mk:plan-creator with mode-matched flag. Plan defines: architecture, modules, file structure, acceptance criteria.
2. Scaffold — generate files following the plan's architecture + references/scaffolding-principles.md. Detect stack via scripts/detect-stack.sh. Validate with scripts/validate-bootstrap.sh.

Optional: invoke mk:plan-ceo-review on the plan (Full mode only).

Scaffolding Principles

Directory Structure

1. Separate concerns by directory: src/, tests/, docs/
2. Mirror test structure to source: src/auth/ -> tests/auth/
3. Flat until necessary: don't nest until 5+ files exist at a level
4. Convention over configuration: follow the stack's standard layout

File Generation

1. Config files first: package.json/go.mod before any source
2. Entry point second: main.ts/index.ts/main.go
3. One module at a time: complete auth/ before moving to users/
4. Every file must compile: no placeholder imports
5. No empty files: every file has meaningful content

Progressive Generation

Step 1: Print proposed directory tree -> user confirms
Step 2: Generate config files (package.json, tsconfig, etc.)
Step 3: Generate entry point + core module
Step 4: Generate remaining modules (one at a time)
Step 5: Generate test scaffolds matching source structure
Step 6: Generate docs (README.md + code-standards.md only)

Between steps: verify no compilation errors before proceeding.

What NOT to Generate

• .claude/ directory (CLI handles this)
• .env files with real secrets (generate .env.example only)
• Lock files (npm install generates these)
• Build output directories (dist/, build/)
• IDE-specific config (.vscode/, .idea/) unless user requests

Minimum Viable Scaffold

project/
  src/
    [entry-point]           <- main.ts, index.ts, main.go, etc.
  tests/
    [entry-point.test]      <- matching test file
  [package-manifest]        <- package.json, go.mod, Cargo.toml
  [compiler-config]         <- tsconfig.json, etc. (if applicable)
  .gitignore
  README.md

Extend from this minimum based on config.json features (docker, CI, database).

Naming Convention Enforcement

• TypeScript/Node: kebab-case files, camelCase functions, PascalCase classes
• Vue: PascalCase components, kebab-case files, use prefix for composables
• NestJS: feature.service.ts, feature.controller.ts, feature.module.ts
• Go/Rust: snake_case files
• Unknown stack: ask user for naming conventions before generating

Mode Details

Auto (default)

Balanced mode. Research + design gate. Good for most projects.

1. Git init (auto)
2. Research: 2-3 parallel researcher subagents
3. Tech stack: auto-detect or auto-select from research
4. Design: ui-ux-designer if frontend, gate: user approves
5. Plan: mk:plan-creator --auto
6. Scaffold: guided by plan, auto-confirm
7. Shared phases: cook -> docs -> final report

Full (--full)

Maximum user control. Gates at every major step. For critical projects.

1. Git init: ask user
2. Clarify requirements: one question at a time, 100% clarity
3. Research: 2-4 parallel researchers, gate: user approves summary
4. Tech stack + design: gate for each
5. Plan: mk:plan-creator --hard with Gate 1 approval. Optional: mk:plan-ceo-review
6. Scaffold: user confirms tree, progressive generation
7. Shared phases: cook (interactive) -> docs -> final report

Fast (--fast)

No user gates. Maximum speed. For prototypes and hackathons.

1. Git init (auto)
2. Combined research + stack: 6 parallel researchers, no gate
3. Plan: mk:plan-creator --fast, auto-creates without approval
4. Scaffold: progressive, no user confirmation
5. Shared phases: cook (auto) -> docs -> final report
6. Auto-commit: git add -A && git commit -m "feat: bootstrap [project-name]"

Parallel (--parallel)

Design gate only. Parallel implementation for independent components. For large projects.

1. Git init (auto)
2. Research: 2 parallel researchers, no gate
3. Tech stack + design: gate for both
4. Plan: mk:plan-creator --parallel with file ownership matrix, dependency graph
5. Scaffold: guided by plan, progressive
6. Shared phases: cook (parallel, multiple developer agents), docs, final report

Shared Phases (MANDATORY — all modes)

After plan + scaffold, all modes execute these phases:

Phase A: Implementation

Activate mk:cook with mode-matched flag. Handles TDD, implementation, review, fix-first.

Phase B: Documentation

Activate mk:docs-init to generate docs/ directory and README.

Phase C: Final Report

Print summary and ask about commit.

BOOTSTRAP COMPLETE
Project: [name]
Stack: [detected/selected stack]
Files generated: [count]
Plan: [plan path]
Docs: [list of docs/ files]

Next steps:
- Review generated code and docs
- Use mk:plan-creator to plan next feature
- Use mk:document-release after shipping to keep docs in sync

Stack Detection

scripts/detect-stack.sh auto-detects project stack from existing project files. Supports 30+ stacks across mobile, systems, Go, Ruby, Java/Kotlin, PHP, Python, and Node.js ecosystems.

Validation

scripts/validate-bootstrap.sh runs post-scaffold checks:

• Basic structure exists (src/, tests/)
• Source files are not empty
• No placeholder tokens remain ([TODO], [PROJECT_NAME], [PLACEHOLDER])

Exits BOOTSTRAP_VALID (0) or BOOTSTRAP_INCOMPLETE (1) with error details.

Gotchas

• Duplicating CLI init: generating .claude/ files that npx mewkit init already provides — NEVER touch .claude/; bootstrap owns src/ and tests/ only
• Over-scaffolding: generating 20+ files for a simple project — ask user about scope first; match generated files to actual needs
• Context overflow on large stacks: generating NestJS monorepo in one shot — progressive generation: structure first, then one module at a time; verify compilation between steps
• Wrong naming conventions: CamelCase files in TypeScript project — always check agent-conduct.md B1 for detected stack; ask user if stack is unknown
• Placeholder leak: [PROJECT_NAME] or [TODO] left in generated files — validate-bootstrap.sh catches these; fix before declaring BOOTSTRAP_VALID
• Stale scaffold patterns: generating patterns from outdated framework versions — use mk:docs-finder to check current framework docs before generating
• Broken imports after generation: files reference modules that don't exist yet — generate in dependency order; entry point last (it imports everything)
• Skipping research on "simple" projects: hidden complexity — always run research unless --fast mode
• Running full pipeline on tiny scripts: bootstrapping a 50-line utility with full process — detect project size; if <5 files expected, use --fast mode automatically

Tools

Tool	Path	Purpose
Stack detector	scripts/detect-stack.sh	Auto-detect project stack from existing files
Validator	scripts/validate-bootstrap.sh	Post-scaffold structural integrity check
Config template	config.example.json	Project config with stack, features, conventions

Common Use Cases

• Creating a new SaaS application from scratch
• Bootstrapping a microservice with Express/Fastify/NestJS
• Scaffolding a full-stack Next.js + TypeScript project
• Building a CLI tool prototype quickly (--fast)
• Large multi-module project with parallel team workflow (--parallel)
• Critical production project with stakeholder sign-offs (--full)

Pro Tips

• Always plan before scaffolding — the plan defines WHAT to generate
• Use --fast for prototypes (<5 files expected), --auto for most projects, --full for critical ones
• Progressive generation prevents context overflow on large projects
• Run validate-bootstrap.sh after every scaffold — catches placeholder leaks immediately
• Generate in dependency order: config -> core -> modules -> entry point
• The minimum viable scaffold (5 files) is the starting point — extend based on config.json features