# AI Operating System Version: 1.0.0 ## Purpose This directory contains the reusable operating system used by AI agents working in this repository. The system is intentionally **self-improving**. Agents may add and refine: * skills * prompts * templates * workflow rules * verification procedures * project-specific agent guidance * model-specific adapters when real work reveals a durable improvement. The AI-OS should become more useful over time without becoming larger merely for the sake of growth. --- # 1. Core Philosophy The human owns: ```text GOALS PRIORITIES FINAL DECISIONS RISK ACCEPTANCE ``` The agent provides: ```text DISCOVERY ANALYSIS EXECUTION VERIFICATION CRITIQUE DOCUMENTATION REUSABLE LEARNING ``` The preferred operating loop is: ```text DISCOVER ↓ ATTEMPT ↓ AUDIT ↓ PLAN ↓ IMPLEMENT ↓ VERIFY ↓ CHALLENGE ↓ REFINE ↓ LEARN ``` The AI should not be treated as an unquestioned authority. The agent should produce work that can be inspected, tested, challenged, and improved. --- # 2. AI-OS Architecture The system is divided into layers. ```text PROJECT ROOT │ ├── AGENTS.md ├── CLAUDE.md │ └── .ai/ ├── AI-OS.md ├── WORKFLOW.md ├── CHANGELOG.md │ ├── state/ │ └── LEARNINGS.md │ ├── prompts/ │ ├── templates/ │ └── skills/ ``` Each layer has a specific responsibility. --- # 3. Root Agent Instructions ## `AGENTS.md` This is the primary model-neutral instruction file. It defines: ```text how agents work how agents verify work how agents use skills how agents improve themselves how agent-system changes are governed ``` All compatible agents should follow `AGENTS.md`. --- # 4. Model Adapters Examples: ```text CLAUDE.md CODEX.md GEMINI.md COPILOT.md ``` Model adapters contain only rules specific to that model or environment. They should not duplicate `AGENTS.md`. Their purpose is adaptation. Example: ```text AGENTS.md ↓ generic rule: "Inspect project evidence before editing." CLAUDE.md ↓ Claude-specific implementation: "Use repository search and focused file reads before editing." ``` --- # 5. Workflow Definition The detailed lifecycle lives in: ```text .ai/WORKFLOW.md ``` That file defines: * fast path * standard path * high-risk path * debugging loop * learning loop * prompt failure loop * self-improvement loop `AGENTS.md` provides policy. `WORKFLOW.md` provides operational flow. --- # 6. Skills Reusable procedures live in: ```text .ai/skills/ ``` Each skill has its own directory. Example: ```text .ai/skills/ ├── diagnostic-intake/ │ └── SKILL.md ├── mirror-audit/ │ └── SKILL.md ├── red-team/ │ └── SKILL.md └── skill-extractor/ └── SKILL.md ``` A skill should solve one coherent class of problem. A skill is preferable to adding a long procedure directly to `AGENTS.md`. --- # 7. Prompts Reusable task launchers and prompt fragments live in: ```text .ai/prompts/ ``` Examples: ```text discover.md plan.md review.md retrospective.md ``` Prompts differ from skills. A prompt is usually: ```text "Do this task in this format." ``` A skill is: ```text "When this class of task occurs, follow this reusable procedure." ``` Skills may use prompts. Prompts should not become substitutes for workflow logic. --- # 8. Templates Reusable file structures live in: ```text .ai/templates/ ``` Examples: ```text SKILL_TEMPLATE.md ARCHITECTURE_REVIEW_TEMPLATE.md POSTMORTEM_TEMPLATE.md PROJECT_BOOTSTRAP_TEMPLATE.md ``` Templates reduce repeated formatting work. They should contain structure rather than project-specific facts. --- # 9. State Reusable candidate learning is recorded in: ```text .ai/state/LEARNINGS.md ``` This is intentionally separate from permanent instructions. The learning ledger acts as: ```text OBSERVATION ↓ POSSIBLE LESSON ↓ EVALUATION ↓ PERMANENT RULE? ``` not: ```text OBSERVATION ↓ IMMEDIATELY MODIFY AGENTS.md ``` This protects the system from instruction growth based on weak evidence. --- # 10. Changelog AI-system modifications are recorded in: ```text .ai/CHANGELOG.md ``` The changelog should make it possible to answer: ```text What changed? Why? What evidence justified it? What behavior was expected to improve? How was it tested? Can we revert it? ``` Treat agent instructions like code. Changes should be traceable. --- # 11. Self-Improvement Loop The self-improvement cycle is: ```text OBSERVE ↓ CAPTURE ↓ CLASSIFY ↓ GENERALIZE ↓ MODIFY ↓ TEST ↓ LOG ↓ REUSE ↓ RE-EVALUATE ``` --- # 12. Observe Agents should notice recurring patterns during real work. Examples: ```text repeated user corrections repeated test failures repeated prompt failures repeated debugging steps repeated manual procedures recurring architectural conventions successful recurring review techniques missing validation steps ``` Observation alone does not justify permanent modification. --- # 13. Capture Potential durable learning should be added to: ```text .ai/state/LEARNINGS.md ``` Capture: ```text CONTEXT EVIDENCE POSSIBLE LESSON CONFIDENCE POSSIBLE DESTINATION ``` The entry may later be: ```text PROMOTED REJECTED REVISED REVISITED ``` --- # 14. Classify Determine what type of information was learned. ## Project Fact Example: ```text "This application uses SQL Server 2022." ``` Destination: ```text project documentation ``` not `AGENTS.md`. --- ## General Agent Rule Example: ```text "Always inspect existing migration scripts before creating a new migration process." ``` Possible destination: ```text AGENTS.md ``` --- ## Model-Specific Rule Example: ```text "Claude should avoid loading generated vendor directories into context." ``` Destination: ```text CLAUDE.md ``` --- ## Reusable Procedure Example: ```text "How to safely perform an Access database CSV import." ``` Destination: ```text .ai/skills/access-csv-import/SKILL.md ``` --- ## Task Launcher Example: ```text "Start a release readiness review." ``` Destination: ```text .ai/prompts/release-review.md ``` --- ## Reusable Structure Example: ```text "Architecture review document layout." ``` Destination: ```text .ai/templates/ ``` --- # 15. Generalize Before promoting an observation, remove accidental details. Example observation: ```text "The import of Territory223.csv failed because the Access driver expected the text qualifier setting." ``` Possible reusable lesson: ```text "When automating CSV imports into Access, inspect delimiter, text qualifier, encoding, headers, and destination field types before import." ``` The lesson is more general than the incident. --- # 16. Modify Make the smallest change that captures the reusable improvement. Prefer: ```text small rule ``` over: ```text large rewrite ``` Prefer: ```text existing skill extension ``` over: ```text new duplicate skill ``` Prefer: ```text skill ``` over: ```text 500 additional lines in AGENTS.md ``` --- # 17. Test Every durable self-improvement should be exercised. Use: ```text .ai/skills/system-audit/SKILL.md ``` At minimum test: ```text the behavior the new rule should improve ``` and: ```text one unrelated behavior ``` This detects unintended regression. --- # 18. Log After a successful self-improvement: update: ```text .ai/CHANGELOG.md ``` and, when applicable: ```text .ai/state/LEARNINGS.md ``` Mark the learning: ```text PROMOTED ``` and record the resulting destination. --- # 19. Reuse A new rule or skill only proves its value when it works again. When reused, note: ```text Did it reduce effort? Did it prevent the original mistake? Did it create new friction? Was the trigger correct? Was the procedure too broad? ``` This feedback may lead to another revision. --- # 20. Re-Evaluate Self-improvements are not sacred. Remove or revise guidance when: ```text it no longer matches the project technology changes the instruction creates worse output another skill replaces it it duplicates another rule the original problem no longer exists ``` The AI-OS should evolve by both: ```text ADDING ``` and: ```text REMOVING ``` guidance. --- # 21. Optimization Targets Self-improvement should optimize for: ```text CORRECTNESS CLARITY REPEATABILITY MAINTAINABILITY VERIFICATION LOWER FAILURE RATE LOWER COGNITIVE OVERHEAD FASTER DISCOVERY ``` It should not optimize for: ```text MORE AUTONOMY MORE FILES MORE PROMPTS MORE RULES LONGER INSTRUCTIONS MORE COMPLEXITY ``` --- # 22. Instruction Budget Root instructions are limited attention resources. Prefer: ```text SHORT ROOT RULE ↓ SPECIALIZED SKILL ↓ PROJECT DOCUMENTATION ``` Example: `AGENTS.md`: ```text Use the database migration skill for schema migrations. ``` Skill: ```text .ai/skills/database-migration/SKILL.md ``` Project documentation: ```text docs/database-schema.md ``` Do not embed all three layers in the root instructions. --- # 23. Skill Lifecycle Every skill conceptually progresses through: ```text CANDIDATE ↓ DRAFT ↓ TESTED ↓ ACTIVE ↓ REVISED ↓ DEPRECATED ``` --- # 24. Candidate Skill A candidate exists when a reusable procedure has been observed but not proven. Store the evidence in: ```text .ai/state/LEARNINGS.md ``` Do not necessarily create the skill yet. --- # 25. Draft Skill A draft skill exists when the procedure appears useful enough to formalize. Build it using: ```text .ai/templates/SKILL_TEMPLATE.md ``` or: ```text .ai/skills/skill-builder/SKILL.md ``` --- # 26. Tested Skill A skill becomes tested after it succeeds in: ```text ORIGINAL SCENARIO ``` and preferably: ```text SECOND DIFFERENT SCENARIO ``` This helps ensure the procedure was actually generalized. --- # 27. Active Skill An active skill: ```text has clear triggers has clear outputs has verification has been useful in real work ``` Agents may use it automatically when its trigger matches the task. --- # 28. Revised Skill Skills should evolve when: ```text edge cases appear tests reveal weaknesses project tooling changes the procedure can be simplified ``` Use semantic-style versioning where practical. Example: ```text 1.0.0 1.0.1 1.1.0 2.0.0 ``` --- # 29. Deprecated Skill Deprecate a skill when: ```text technology is no longer used another skill replaces it its trigger is obsolete tests show it creates worse results the knowledge belongs somewhere else ``` Remove obsolete active guidance instead of allowing dead instructions to accumulate. --- # 30. Prompt Lifecycle Prompts should also evolve. A reusable prompt should go through: ```text DRAFT ↓ TEST ↓ USE ↓ FAILURE REVIEW ↓ REFINE ↓ VERSION ``` When a prompt fails, use: ```text .ai/skills/prompt-debugger/SKILL.md ``` Do not blindly add more instructions. --- # 31. Root File Governance The most sensitive AI-system files are: ```text AGENTS.md CLAUDE.md .ai/AI-OS.md .ai/WORKFLOW.md ``` Changes to these files should be made conservatively. Ask: ```text Does this truly need to affect many tasks? ``` If not, the change probably belongs in a skill. --- # 32. Major Change Boundary The agent may autonomously make routine improvements. However, changes that affect: ```text agent authority self-modification permissions approval requirements security policy verification requirements instruction priority the fundamental workflow ``` should be treated as major changes. Major changes should be clearly surfaced to the user unless directly requested. --- # 33. Self-Modification Safety The AI-OS must never evolve toward: ```text less verification less transparency hidden changes greater unauthorized access weaker security less user control suppressed failures untracked modification ``` A proposed self-improvement that does any of these should fail the system audit. --- # 34. Continuous Improvement Metrics When possible, evaluate whether a process improvement reduces: ```text clarification rounds prompt retries failed tests implementation mistakes manual repeated steps duplicate instructions time rediscovering project information ``` Not every improvement needs numeric measurement. Strong qualitative evidence is acceptable. --- # 35. Project-Specific Skill Growth The initial AI-OS contains general skills. As the project evolves, agents may create domain-specific skills such as: ```text .ai/skills/classic-asp-controller/ .ai/skills/iis-deployment/ .ai/skills/access-database-import/ .ai/skills/sql-server-schema-change/ .ai/skills/powershell-server-setup/ .ai/skills/security-header-audit/ .ai/skills/api-endpoint-design/ ``` The project should teach the agent what skills it actually needs. Do not create dozens of speculative skills before they are needed. --- # 36. Knowledge Promotion Example Suppose an agent repeatedly discovers: ```text All API endpoints in this project must include a standard authorization and error-handling wrapper. ``` First: ```text .ai/state/LEARNINGS.md ``` records the pattern. If repeated: ```text .ai/skills/api-endpoint/SKILL.md ``` may be created. If every agent working in the repository must know to use that skill: `AGENTS.md` may receive a short rule: ```text When adding an API endpoint, use the api-endpoint skill. ``` The detailed procedure stays in the skill. --- # 37. Failure-Driven Improvement Failures are valuable inputs to the AI-OS. When something fails: ```text FAILURE ↓ ROOT CAUSE ↓ COULD PROCESS HAVE CAUGHT THIS? ↓ YES ↓ PROCESS IMPROVEMENT CANDIDATE ``` Possible improvements: ```text new test new validation step new skill rule better diagnostic prompt better project documentation better bootstrap discovery ``` Do not automatically create a new instruction for every bug. The lesson must be reusable. --- # 38. Success-Driven Improvement Successful work can also generate skills. If a task was solved efficiently because of a strong reusable method: ```text SUCCESSFUL PROCEDURE ↓ EXTRACT STRUCTURE ↓ GENERALIZE ↓ TEST ↓ SKILL ``` Use: ```text .ai/skills/skill-extractor/SKILL.md ``` This allows the system to learn from success instead of only from failure. --- # 39. Project Bootstrap When this AI-OS is first introduced into an existing repository, the agent should eventually build a project-specific understanding of: ```text languages frameworks directory layout architecture database testing build commands deployment security boundaries coding conventions operational constraints ``` These facts should normally live in project documentation or a project-context file rather than bloating `AGENTS.md`. A future skill may automate this bootstrap process. --- # 40. Maintenance AI-system maintenance occurs at several levels. ## Per Task Consider reusable learning. ## Periodically Review: ```text .ai/state/LEARNINGS.md ``` Promote strong recurring lessons. Reject weak ones. --- ## After Project Changes Re-check: ```text tooling versions architecture deployment testing security assumptions agent skills ``` --- ## After Model Changes If agent behavior changes unexpectedly: run: ```text .ai/skills/system-audit/SKILL.md ``` and test important root rules. --- # 41. Minimum Permanent Memory Principle Not every useful observation deserves permanent storage. Permanent guidance should represent: ```text STABLE REUSABLE ACTIONABLE VERIFIABLE ``` knowledge. Temporary task context belongs in the task. Project truth belongs in project documentation. Reusable procedure belongs in a skill. General agent behavior belongs in root instructions. This separation keeps the AI-OS useful. --- # 42. The Goal The AI-OS should create a compounding loop: ```text PROJECT WORK ↓ EXPERIENCE ↓ REUSABLE LEARNING ↓ BETTER PROCESS ↓ BETTER PROJECT WORK ↓ MORE EXPERIENCE ``` The system becomes better because it learns from actual work. It should never become more complicated merely because it has permission to modify itself.