project-bootstrap

Project Bootstrap

Performs initial project analysis when the AI coding protocols are first vendored into a project. Scans the codebase to detect the technology stack, architectural patterns, and key conventions, then generates an initial project-overview skill and an adapted blueprint.

When to Activate

• Right after make ai installation into a new project
• When the agent first encounters an .ai/ directory without project-specific skills
• When explicitly asked to bootstrap or initialize AI protocols for the project

Core Concepts

• Idempotent — checks for existing project skills before generating; never overwrites previous work
• Detection over assumption — scans actual project files rather than guessing based on directory names
• Minimal initial output — generates one project-overview skill and one blueprint; the skill-generator skill handles ongoing growth
• Blueprint-aware — generates tool-specific configuration (CLAUDE.md or .cursor/​rules/) referencing relevant skills

Detailed Guidance

Guard Clause

Before running any analysis, check:

1. Does .ai/​skills/​project/ exist and contain at least one SKILL.md file?
2. If yes → skip bootstrap. Inform the user that project-specific skills already exist and suggest using skill-generator for new additions.
3. If no → proceed with bootstrap.

Phase 1: Project Scan

Scan these files and directories to build a project profile:

Phase 2: Pattern Detection

From the scan results, classify:

• Language(s): Primary and secondary
• Framework: Web framework, CLI framework, library, etc.
• Architecture: Monorepo, MVC, hexagonal/​ports-and-adapters, serverless, microservices
• Testing setup: Runner, assertion style, coverage tool
• Code quality: Linter, formatter, static analysis
• Key directories: Where source, tests, config, and infrastructure live

Phase 3: Generate Project Overview Skill

Create .ai/​skills/​project/​project-overview/​SKILL.md with:

---
name: project-overview
version: 1.0.0
description: Project stack, conventions, and key file paths for {project-name}.
triggers: [project, overview, stack, conventions]
---

# Project Overview: {project-name}

## Stack
- **Language:** {detected}
- **Framework:** {detected}
- **Testing:** {detected}
- **Linting/​Formatting:** {detected}
- **Architecture:** {detected}

## Key Directories
- `src/` — {purpose}
- `tests/` — {purpose}
- ...

## Conventions
- {detected conventions from config files and code patterns}

## Relevant Skills
- {list of generic skills from .ai/​skills/ that match this stack}

Phase 4: Generate Blueprint

Generate a tool-specific blueprint based on the detected stack:

For Claude Code — suggest content for CLAUDE.md in the project root:

Follow the engineering standards vendored in ./​.ai/​skills/​.
See ./​.ai/​blueprints/​claude-cli.md for the operational protocol.

Project-specific conventions are in ./​.ai/​skills/​project/​.

For Cursor — generate rules in .cursor/​rules/ (NOT .cursorrules, which is deprecated):

• Create .cursor/​rules/​ai-protocols.mdc referencing vendored skills
• Include project-specific stack info from the generated overview

What NOT to Do

• Don't generate skills for standard language features — that's what the generic skills cover
• Don't guess at conventions that aren't evidenced by config files or code
• Don't generate multiple project skills — start with one overview, let skill-generator handle the rest
• Don't modify any existing files outside .ai/​skills/​project/ without user confirmation

Examples

Scenario: Bootstrap on a Next.js project with TypeScript, Vitest, and ESLint.

Detected profile:

• Language: TypeScript
• Framework: Next.js 14 (App Router)
• Testing: Vitest + Testing Library
• Linting: ESLint + Prettier
• Architecture: App Router with src/​app/, src/​components/, src/​lib/

Generated .ai/​skills/​project/​project-overview/​SKILL.md:

---
name: project-overview
version: 1.0.0
description: Next.js 14 App Router project with TypeScript, Vitest, and ESLint.
triggers: [project, overview, stack, conventions]
---

# Project Overview: my-nextjs-app

## Stack
- **Language:** TypeScript 5.x (strict mode)
- **Framework:** Next.js 14 (App Router)
- **Testing:** Vitest + @testing-library/​react
- **Linting/​Formatting:** ESLint (next/​core-web-vitals) + Prettier
- **Architecture:** App Router — src/​app/ for routes, src/​components/ for UI, src/​lib/ for utilities

## Key Directories
- `src/​app/` — Next.js App Router pages and layouts
- `src/​components/` — Reusable React components
- `src/​lib/` — Shared utilities and helpers
- `tests/` — Vitest test files

## Relevant Skills
- `typescript-standard` — TypeScript conventions and TDD patterns
- `recursive-exploration` — Codebase navigation
- `code-review` — Review protocol

Guidelines

1. Always check for existing project skills before generating — never overwrite
2. Base all detections on actual files, not assumptions
3. Generate exactly one project-overview skill and one blueprint suggestion
4. Reference only generic skills that match the detected stack
5. Place all generated skills in .ai/​skills/​project/
6. For Cursor, use .cursor/​rules/ (not .cursorrules)
7. Don't modify files outside .ai/​skills/​project/ without user confirmation

Integration

• Related: skill-generator (handles ongoing skill creation after bootstrap)
• Related: recursive-exploration (used during the scanning phase)
• Outputs: project-overview skill, blueprint suggestions

Skill Metadata

• Created: 2025-07-01
• Last Updated: 2025-07-01
• Author: didacrios
• Version: 1.0.0