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 — Comprehensive skill catalog
• INDEX.md — Complete skill catalog

References

• INDEX.md — Complete skill catalog
• AGENTS.md — Framework overview
• PLAYBOOK.md — Operational workflows
• FRAMEWORK.md — Architecture patterns