| name | bootstrapping-projects |
| description | Bootstraps a new project or initializes an existing directory with standard structures, documentation, planning files, version control setups, and framework-agnostic AI agent rules. Use when starting a new codebase or adding initial structure (git, docs, planning) to an existing project. Don't use if the project is already fully initialized with git, planning, and documentation frameworks. |
Bootstrapping Projects
Overview
Automates the setup of folders, files, planning trackers, version control, and AI guidelines for new or ongoing codebases. This skill uses a combination of a deterministic Python script to create base structures and adaptive LLM logic to write personalized context.
Bootstrapping Workflow
graph TD
A[Start Bootstrapping] --> B[Analyze Current Directory & Context]
B --> C{Files/Signals Found?}
C -- Yes (Detect Tech Stack) --> D[Run bootstrap.py with Stack Args]
C -- No (Ask or Infer) --> E[Run bootstrap.py with Generic/Selected Stack]
D --> F[Create Base Directories & Standard Files]
E --> F
F --> G[LLM Populates Custom Files]
G --> G1[README.md & Docs]
G --> G2[PLAN.md & Milestones]
G --> G3[Agnostic AGENTS.md Rules]
G1 --> H[Verify & Present Project Tree]
G2 --> H
G3 --> H
H --> I[Ready for Implementation]
Best Practices
- Clarify Before Action (Ambiguity Gate): If the tech stack, project scope, database preference, or deployment target is unclear, do not proceed with default assumptions. You must prompt the user with concise options first.
- Analyze Before Action: Always inspect the target directory first. Never blindly overwrite existing files. If existing files conflict with bootstrapping templates, ask the user whether to augment, bypass, or replace them.
- Combined Bootstrapping: Use the helper Python script (
scripts/bootstrap.py) to create empty directories and write boilerplate gitignores. Let the LLM fill in high-context files (PLAN.md, README.md, AGENTS.md).
- Agnostic Agent Rules: Ensure generated agent instructions (e.g.,
AGENTS.md) are standard and agnostic to specific IDE extensions or agent frameworks (e.g., compatible with Claude Code, Roo, Cursor, Kilo, etc.).
- Plan-First Strategy: Always start with a
PLAN.md containing verifiable, realistic milestones before writing any application source code.
- Strict Git Boundaries: Always initialize a Git repository (
git init) and a comprehensive .gitignore configured specifically for the target stack.
Process
1. Analyze and Infer
- Directory Assessment: Scan the target directory for pre-existing configurations (e.g.,
package.json, pyproject.toml, go.mod, etc.) or files.
- Ambiguity Assessment: Evaluate if there is ambiguity regarding the core tech stack/language, frameworks (e.g., React vs. Next.js vs. Vue, or FastAPI vs. Django), or core architectural requirements (e.g., database, auth, hosting).
- Active Prompting: If any of the above are ambiguous or unspecified, you must use the questioning tool or prompt the user with highly specific, concise multiple-choice options before executing any scripting or file creation.
2. Run the Bootstrap Script
Run the automated python script to generate the physical directory tree and default files:
python3 skills/bootstrapping-projects/scripts/bootstrap.py --stack [detected-stack]
(Valid stacks: generic, python, typescript, go, rust)
3. Customize and Hydrate
The script creates placeholder templates. Your job as the LLM is to overwrite them with project-specific detail:
- README.md: Formulate a professional overview of the project, including quickstart instructions and architectural layouts.
- PLAN.md: Establish phase-based goals and success criteria for the project's development.
- AGENTS.md: Customize general coding practices, formatting rules, and testing strategies for the selected tech stack.
4. Verification
Run a directory tree listing (excluding node_modules/venv/etc.) to confirm structure matches expectation:
git status && ls -la
Common Pitfalls
- The Guessing Trap: Proceeding with standard templates or stacks when the user's intent is ambiguous, leading to throwaway work, misconfigured directories, and out-of-sync plans.
- Overwriting Work: Destroying existing user code during the setup of a pre-existing directory without asking the user for conflict resolution instructions first.
- Template Bloat: Creating folder structures (e.g., deeply nested
domain/application/infrastructure directories) before a single line of actual feature code is written. Keep it minimal first.
- Generic Gitignore: Forgetting to configure stack-specific exclusions, leading to commit pollution (e.g., committing
node_modules or .venv).
