13KB
Project Bootstrap
Version: 1.0.0 Status: ACTIVE
Purpose
Bootstrap the AI operating system inside an unfamiliar or newly initialized project.
This skill allows an agent to inspect the repository, determine how the project actually works, create a concise project profile, identify important workflows, and propose project-specific skills only where real repository evidence justifies them.
The goal is:
GENERIC AI-OS
↓
INSPECT PROJECT
↓
UNDERSTAND PROJECT
↓
CAPTURE PROJECT CONTEXT
↓
IDENTIFY REUSABLE PROJECT WORKFLOWS
↓
CREATE PROJECT-SPECIFIC SKILLS OVER TIME
1. Trigger Conditions
Use when:
- the AI-OS is first copied into an existing project
- an agent enters an unfamiliar repository
- repository architecture has changed substantially
- project instructions are missing or stale
- a project needs an initial agent profile
- the user asks the agent system to learn the repository
Do not rerun the entire bootstrap process for every task.
2. Bootstrap Principle
Do not attempt to understand every file.
Identify the project's:
STRUCTURE
TECHNOLOGY
BUILD
TEST
RUNTIME
DATA
DEPLOYMENT
SECURITY
CONVENTIONS
HIGH-VALUE WORKFLOWS
Stop when enough information exists for reliable normal work.
3. Read Existing Instructions
First inspect:
AGENTS.md
CLAUDE.md
README*
CONTRIBUTING*
docs/
project-specific instruction files
Existing human-authored project instructions take priority over inferred conventions.
4. Identify Repository Type
Determine whether the repository contains:
APPLICATION
LIBRARY
SERVICE
SCRIPT COLLECTION
INFRASTRUCTURE
DATA PIPELINE
DOCUMENTATION
MULTI-PROJECT MONOREPO
A repository may contain more than one.
5. Identify Languages
Determine languages from evidence such as:
file extensions
project manifests
build files
source directories
Record only languages materially used by the project.
Do not treat incidental generated files as primary technologies.
6. Identify Frameworks
Inspect:
project files
dependency manifests
imports
configuration
startup files
Examples:
ASP Classic
ASP.NET
ASP.NET MVC
PHP
Node.js
PowerShell
Python
Java
C/C++
Record versions when reliably discoverable.
7. Identify Runtime Environment
Discover:
operating system
web server
application server
container runtime
required services
environment assumptions
Examples:
Windows + IIS
Linux + Nginx
Docker
Windows Scheduled Task
Do not infer production environment solely from developer tooling.
8. Identify Project Structure
Map only important directories.
Example:
/src
/tests
/scripts
/config
/docs
/database
/deploy
For legacy projects the structure may be unconventional.
Describe what exists rather than forcing a standard architecture.
9. Identify Entry Points
Find:
application startup
routes
main scripts
services
scheduled jobs
public endpoints
command-line entry points
This helps agents understand how behavior enters the system.
10. Identify Build Process
Find commands required to:
restore dependencies
compile
package
generate assets
Capture actual commands from:
scripts
CI files
project files
README
package manifests
Do not invent standard commands without checking.
11. Identify Test Process
Find:
test frameworks
test directories
commands
integration tests
smoke tests
Record:
FAST TEST
FULL TEST
SPECIAL ENVIRONMENT REQUIREMENTS
when possible.
12. Identify Data Stores
Discover:
database engine
connection architecture
schema location
migration method
data files
queues
caches
Do not record credentials or secrets.
13. Identify Data Access Pattern
Examples:
ADODB
ADO.NET
Entity Framework
raw SQL
stored procedures
ODBC
file-based data
Look for repeated conventions.
14. Identify External Integrations
Find meaningful integrations:
payment providers
APIs
SMTP
SFTP
file shares
cloud services
directory services
webhooks
Record only what is evidenced.
15. Identify Authentication and Authorization
Discover:
authentication mechanism
authorization approach
roles
identity source
protected entry points
Examples:
Windows Authentication
forms authentication
OAuth
JWT
session-based authorization
Do not expose secrets.
16. Identify Deployment
Inspect:
deployment scripts
CI/CD
Docker files
server configuration
README
runbooks
Determine:
TARGET
DEPLOYMENT METHOD
VERIFICATION
ROLLBACK
when available.
17. Identify Coding Conventions
Look for repeated patterns in:
naming
directory structure
controllers
services
error handling
logging
configuration
database access
testing
Use several examples before declaring a convention.
One file is not always a convention.
18. Identify Architectural Patterns
Possible examples:
MVC
layered architecture
service/repository
event-driven
script pipeline
monolith
microservice
Describe what the repository actually implements.
Do not label architecture based solely on directory names.
19. Identify Existing Reusable Workflows
Search for recurring work such as:
adding controller
adding endpoint
database import
deployment
creating report
adding customer/client
testing release
data conversion
configuration change
These are future project-skill candidates.
20. Do Not Create Skills Immediately
Bootstrap should primarily:
OBSERVE
not:
GENERATE MANY SKILLS
For each potential skill ask:
Is there repeated evidence?
Is the workflow stable?
Would another agent use this?
If evidence is insufficient, put it in:
.ai/state/LEARNINGS.md
as a candidate.
21. Project Profile
Create or maintain:
.ai/PROJECT.md
unless the repository already has a clearly better project-context location.
This file should remain concise.
22. Suggested .ai/PROJECT.md Structure
# Project Profile
## Purpose
## Technology
## Architecture
## Important Directories
## Entry Points
## Database / Data
## Authentication
## External Integrations
## Build
## Tests
## Deployment
## Important Conventions
## Known Constraints
## High-Value Workflows
## Project-Specific Skills
Do not duplicate complete README or architecture documentation.
Link to existing docs when possible.
23. Source-of-Truth Rule
If existing documentation already owns a fact:
REFERENCE IT
rather than duplicating it extensively.
Example:
Deployment:
See docs/deployment.md.
The project profile is a map, not necessarily the full encyclopedia.
24. Fact Confidence
When project facts are inferred rather than explicitly documented, mark them appropriately.
Example:
Observed convention:
Most controllers inherit the same request-validation helper.
Confidence:
Medium — found in 4 of 5 reviewed controllers.
Do not turn weak inference into permanent project law.
25. Detect Conflicts
If repository behavior conflicts with documentation:
DO NOT SILENTLY CHOOSE
Record the inconsistency.
Example:
README says SQL Server 2019.
Deployment configuration references SQL Server 2022.
Determine which source is authoritative or surface the conflict.
26. Project Constraints
Capture durable constraints such as:
must support Windows Server 2016
must remain ASP Classic
no React
database must remain Microsoft Access
must run without administrator privileges
only when evidenced by project instructions or user direction.
27. Build Verification
If practical, run the documented build process.
Record:
COMMAND
RESULT
REQUIREMENTS
If build fails because of environment limitations, state that.
Do not “fix” unrelated build failures during bootstrap unless asked.
28. Test Verification
Run a lightweight test or documented suite when practical.
This verifies that:
documented test process
matches:
actual test process
29. Deployment Verification
Do not deploy merely because bootstrap discovers deployment instructions.
Bootstrap should understand deployment.
Actual production deployment requires the normal task workflow and appropriate authority.
30. Security Boundary
Bootstrap may inspect security architecture.
It must not:
disable authentication
rotate credentials
change permissions
modify firewall
change production security
unless separately requested.
Discovery is not permission to change.
31. Project Skill Candidate Detection
For each repeated workflow, record:
NAME
TRIGGER
OBSERVED EXAMPLES
LIKELY PROCEDURE
CONFIDENCE
Example:
Candidate:
classic-asp-controller
Observed:
six controllers use the same initialization,
validation, service, and response pattern.
Confidence:
High
Then Skill Extractor may promote it.
32. Project Automation Candidates
Look for deterministic repeated operations.
Examples:
build
deployment preflight
file transformation
schema verification
test-data generation
database import validation
Ask:
Should this be code instead of prompt guidance?
Favor scripts when deterministic automation is possible.
33. Bootstrap Output
Produce:
PROJECT PROFILE
KEY COMMANDS
IMPORTANT CONSTRAINTS
ARCHITECTURE SUMMARY
VERIFICATION METHODS
KNOWN UNKNOWNS
SKILL CANDIDATES
AUTOMATION CANDIDATES
Do not overwhelm the user with every inspected detail.
34. Suggested First Bootstrap Sequence
1. Read instructions.
2. Inspect repository root.
3. Identify project files/manifests.
4. Identify source entry points.
5. Identify architecture.
6. Identify data layer.
7. Identify tests.
8. Identify build.
9. Identify deployment.
10. Identify authentication/security.
11. Review several representative implementations.
12. Create/update .ai/PROJECT.md.
13. Record skill candidates.
14. Run system audit on any AI-OS changes.
35. Incremental Bootstrap
Large repositories should be learned incrementally.
Example:
CORE APPLICATION
↓
DATA LAYER
↓
DEPLOYMENT
↓
SPECIALIZED SUBSYSTEMS AS NEEDED
Do not consume huge context merely to say the repository has been “fully learned.”
36. Refresh Mode
Use a lighter version when project profile already exists.
Check whether these changed:
framework version
architecture
build
tests
deployment
database
security
important directories
Update only stale areas.
37. Staleness Triggers
Consider refreshing bootstrap information after:
major framework upgrade
deployment redesign
database change
repository restructure
new service architecture
new test framework
major authentication change
38. Relationship to AGENTS.md
Bootstrap may recommend a short project routing rule when evidence shows a universally important project workflow.
Example:
For production deployments, use the project's IIS deployment skill.
Do not add all discovered project facts to AGENTS.md.
39. Relationship to Skill Extractor
Bootstrap discovers:
POSSIBLE SKILLS
Skill Extractor determines:
WHETHER THEY SHOULD EXIST
Skill Builder determines:
HOW TO BUILD THEM
Workflow:
PROJECT BOOTSTRAP
↓
CANDIDATE
↓
SKILL EXTRACTOR
↓
SKILL BUILDER
40. Relationship to System Audit
Any AI-OS files created during bootstrap should be audited.
Especially:
.ai/PROJECT.md
new skills
new root routing rules
41. Anti-Patterns
Avoid:
READ EVERY FILE
Avoid:
CREATE 30 SKILLS ON DAY ONE
Avoid:
ASSUME COMMON FRAMEWORK CONVENTIONS
Avoid:
COPY README INTO PROJECT.md
Avoid:
CHANGE THE PROJECT WHILE TRYING TO UNDERSTAND IT
Bootstrap is primarily discovery.
42. Completion
Bootstrap is complete when an agent can reliably answer:
What is this project?
How is it structured?
How do I build it?
How do I test it?
How does it store data?
How is it deployed?
What security model does it use?
What conventions should I follow?
Where should I look before creating something new?
It does not need complete knowledge of every subsystem.
43. Changelog
1.0.0
Initial active version.
Introduced:
- repository-first bootstrap
- project technology discovery
- architecture discovery
- build/test/deployment discovery
- security/data/integration discovery
.ai/PROJECT.md- project skill candidate detection
- automation candidate detection
- incremental and refresh bootstrap modes