# 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text project files dependency manifests imports configuration startup files ``` Examples: ```text 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: ```text operating system web server application server container runtime required services environment assumptions ``` Examples: ```text 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: ```text /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: ```text 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: ```text restore dependencies compile package generate assets ``` Capture actual commands from: ```text scripts CI files project files README package manifests ``` Do not invent standard commands without checking. --- # 11. Identify Test Process Find: ```text test frameworks test directories commands integration tests smoke tests ``` Record: ```text FAST TEST FULL TEST SPECIAL ENVIRONMENT REQUIREMENTS ``` when possible. --- # 12. Identify Data Stores Discover: ```text database engine connection architecture schema location migration method data files queues caches ``` Do not record credentials or secrets. --- # 13. Identify Data Access Pattern Examples: ```text ADODB ADO.NET Entity Framework raw SQL stored procedures ODBC file-based data ``` Look for repeated conventions. --- # 14. Identify External Integrations Find meaningful integrations: ```text payment providers APIs SMTP SFTP file shares cloud services directory services webhooks ``` Record only what is evidenced. --- # 15. Identify Authentication and Authorization Discover: ```text authentication mechanism authorization approach roles identity source protected entry points ``` Examples: ```text Windows Authentication forms authentication OAuth JWT session-based authorization ``` Do not expose secrets. --- # 16. Identify Deployment Inspect: ```text deployment scripts CI/CD Docker files server configuration README runbooks ``` Determine: ```text TARGET DEPLOYMENT METHOD VERIFICATION ROLLBACK ``` when available. --- # 17. Identify Coding Conventions Look for repeated patterns in: ```text 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: ```text 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: ```text 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: ```text OBSERVE ``` not: ```text GENERATE MANY SKILLS ``` For each potential skill ask: ```text Is there repeated evidence? Is the workflow stable? Would another agent use this? ``` If evidence is insufficient, put it in: ```text .ai/state/LEARNINGS.md ``` as a candidate. --- # 21. Project Profile Create or maintain: ```text .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 ```text # 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: ```text REFERENCE IT ``` rather than duplicating it extensively. Example: ```text 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: ```text 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: ```text DO NOT SILENTLY CHOOSE ``` Record the inconsistency. Example: ```text 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: ```text 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: ```text 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: ```text documented test process ``` matches: ```text 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: ```text 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: ```text NAME TRIGGER OBSERVED EXAMPLES LIKELY PROCEDURE CONFIDENCE ``` Example: ```text 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: ```text build deployment preflight file transformation schema verification test-data generation database import validation ``` Ask: ```text Should this be code instead of prompt guidance? ``` Favor scripts when deterministic automation is possible. --- # 33. Bootstrap Output Produce: ```text 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 ```text 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: ```text 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: ```text framework version architecture build tests deployment database security important directories ``` Update only stale areas. --- # 37. Staleness Triggers Consider refreshing bootstrap information after: ```text 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: ```text 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: ```text POSSIBLE SKILLS ``` Skill Extractor determines: ```text WHETHER THEY SHOULD EXIST ``` Skill Builder determines: ```text HOW TO BUILD THEM ``` Workflow: ```text PROJECT BOOTSTRAP ↓ CANDIDATE ↓ SKILL EXTRACTOR ↓ SKILL BUILDER ``` --- # 40. Relationship to System Audit Any AI-OS files created during bootstrap should be audited. Especially: ```text .ai/PROJECT.md new skills new root routing rules ``` --- # 41. Anti-Patterns Avoid: ```text READ EVERY FILE ``` Avoid: ```text CREATE 30 SKILLS ON DAY ONE ``` Avoid: ```text ASSUME COMMON FRAMEWORK CONVENTIONS ``` Avoid: ```text COPY README INTO PROJECT.md ``` Avoid: ```text CHANGE THE PROJECT WHILE TRYING TO UNDERSTAND IT ``` Bootstrap is primarily discovery. --- # 42. Completion Bootstrap is complete when an agent can reliably answer: ```text 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