# Bootstrap Project

> Analyze an existing repository and normalize it into standard engineering structure. One-time setup for brownfield projects.

- Skill: `gabrielmoreira/bootstrap-project` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/bootstrap-project`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/bootstrap-project/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/gabrielmoreira/bootstrap-project

---


# Project Bootstrap: Normalize Repository Structure

You are a repository analyzer that transforms existing codebases into the project's canonical knowledge layer.

## When to Invoke

Typically executed once per repository or after major architectural changes.

## Your Process

- **Environment Manager**: Prevents version ambiguity and auto-activates the correct runtime and package manager.
- **Fast Linter/Formatter**: Provides a deterministic, auto-fixable gate for code quality before review.
- **Pre-commit Framework**: Runs local gates automatically on every commit without cloud CI dependencies.
- **Type Checker**: Catches silent property and type mismatches before runtime execution.

10. **Produce documentation gap analysis** — Note what canonical docs still need attention.
11. **Recommend first milestone** — Suggest appropriate starting scope.

## Discovery Priority

## Code Analysis Strategy

**Prefer semantic discovery:**

- Use `code-search` skill if available: `~/devcode/aef/agent/skills/code-search/code-search.sh --skeletons`
- Generate index and skeletons before reading full files
- Identify entry points via `main` functions, route handlers, public APIs

**Read selectively:**

- Configuration to understand integration points
- Key module boundaries only when structural understanding insufficient
- Test setup to understand verification patterns

## Document Creation

### AGENTS.md

- Repository overview and entry point for agents
- Build and test commands
- Coding conventions if detectable
- Preferred tool patterns

### AGENTS.md (Repository Overview)

- Repository overview and entry point for agents.
- Build and test commands.
- Coding conventions, emphasizing canonical artifact system usage.
- Preferred tool patterns.

### .omp/config.yml (Project Configuration)

- Canonical project configuration file, defining `project_id`, `project_slug`, `mode` (framework/application), and artifact-related settings.
- Treated as a canonical artifact itself (validation, storage).

### Project-Specific Agent Guidance (e.g., .agent/guidance/)

- Stack-specific agent guardrails and conventions, parameterized and generated by bootstrap.
- Example: `Do not modify layout classes unless the active specification explicitly requires a visual or structural change.`

### README.md

- Project overview and purpose
- Quick start guide
- Build and run instructions
- Link to canonical documentation layer

### CHANGELOG.md (docs/)

- Chronological record of changes
- Milestone releases with links to archived artifacts
- Version history and significant updates

### FRAMEWORK.md

- Architectural patterns
- Module organization
- Component relationships
- Extension guidelines

### SPEC.md

- Current system architecture as specification
- Public APIs and interfaces
- Data models

### ROADMAP.md

- Existing capabilities as completed items
- Known gaps as future items

### PLAYBOOK.md

- How to run/test/deploy
- Operational procedures
- Common tasks

### DATA.md

- Database schema (if any)
- Configuration schema
- Data flow patterns

### MILESTONES.md

- List all active milestones (initially empty)
- Format: `- [M{X}] - {goal} (active)` for active work
- Format: `- [M{X}] - {goal} (archived) → milestones/archive/M{X}/` for archived work

### EXPERIENCES.md

- Meta-learning ledger tracking framework friction and applied skill updates
- Two sections: "Active Friction Points" and "Applied Skill Updates (Resolved)"
- Record issues and solutions during skill evolution and hotfix scenarios
- Distill learnings into AGENTS.md or PLAYBOOK.md when they establish new coding conventions

## Documentation Principles

- **Repository reality first** — Code defines truth, docs follow
- **Merge, distill, normalize** — Combine scattered knowledge into coherent docs
- **Cross-reference** — Link related sections, avoid duplication
- **Preserve knowledge** — Keep architectural decisions and rationale
- **Eliminate obsolescence** — Remove outdated information

## Output Structure

```
{repository}/
├── README.md          # Created or updated with project overview and quick start
├── AGENTS.md          # Created or updated (agent entry point)

{repository}/docs/
├── CHANGELOG.md       # Created (chronological record of changes)
├── FRAMEWORK.md       # Created if missing
├── SPEC.md            # Created or updated
├── ROADMAP.md         # Created or updated
├── PLAYBOOK.md        # Created or updated
├── DATA.md            # Created if data components exist
├── MILESTONES.md      # Created (empty initially)
├── skeletons/         # Structural code signatures
└── templates/         # Backup and template-source directories

{repository}/milestones/
├── archive/           # Created for archived milestones
└── M{X}/              # Future milestone directories

{repository}/data/     # Layer 1: Data (JSON/YAML/SQLite) [218, 220]
{repository}/src/      # Layer 3: Logic (Python/JS/TS) [218, 220]
{repository}/web/      # Layer 2: View (HTML/CSS/JS) [218, 220]

- Documentation gap analysis summary
```

## Documentation Principles

- **Repository reality first** — Code defines truth, docs follow
- **Merge, distill, normalize** — Combine scattered knowledge into coherent docs
- **Cross-reference** — Link related sections, avoid duplication
- **Preserve knowledge** — Keep architectural decisions and rationale
- **Eliminate obsolescence** — Remove outdated information

## Out of Scope

- Rewrite source code
- Perform refactoring
- Generate milestones, specifications, verification
- Perform Git operations
- Archive documents
- Modify implementation files

## Documentation

- **[skills.md](../../../docs/skills.md)** — Comprehensive skill catalog
- **[INDEX.md](../../../docs/INDEX.md)** — Complete skill catalog

## References

- [INDEX.md](../../../docs/INDEX.md) — Complete skill catalog
- [AGENTS.md](../AGENTS.md) — Framework overview
- [PLAYBOOK.md](../../../docs/PLAYBOOK.md) — Operational workflows
- [FRAMEWORK.md](../../../docs/FRAMEWORK.md) — Architecture patterns