16KB
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:
GOALS
PRIORITIES
FINAL DECISIONS
RISK ACCEPTANCE
The agent provides:
DISCOVERY
ANALYSIS
EXECUTION
VERIFICATION
CRITIQUE
DOCUMENTATION
REUSABLE LEARNING
The preferred operating loop is:
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.
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:
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:
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:
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:
.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:
.ai/skills/
Each skill has its own directory.
Example:
.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:
.ai/prompts/
Examples:
discover.md
plan.md
review.md
retrospective.md
Prompts differ from skills.
A prompt is usually:
"Do this task in this format."
A skill is:
"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:
.ai/templates/
Examples:
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:
.ai/state/LEARNINGS.md
This is intentionally separate from permanent instructions.
The learning ledger acts as:
OBSERVATION
↓
POSSIBLE LESSON
↓
EVALUATION
↓
PERMANENT RULE?
not:
OBSERVATION
↓
IMMEDIATELY MODIFY AGENTS.md
This protects the system from instruction growth based on weak evidence.
10. Changelog
AI-system modifications are recorded in:
.ai/CHANGELOG.md
The changelog should make it possible to answer:
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:
OBSERVE
↓
CAPTURE
↓
CLASSIFY
↓
GENERALIZE
↓
MODIFY
↓
TEST
↓
LOG
↓
REUSE
↓
RE-EVALUATE
12. Observe
Agents should notice recurring patterns during real work.
Examples:
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:
.ai/state/LEARNINGS.md
Capture:
CONTEXT
EVIDENCE
POSSIBLE LESSON
CONFIDENCE
POSSIBLE DESTINATION
The entry may later be:
PROMOTED
REJECTED
REVISED
REVISITED
14. Classify
Determine what type of information was learned.
Project Fact
Example:
"This application uses SQL Server 2022."
Destination:
project documentation
not AGENTS.md.
General Agent Rule
Example:
"Always inspect existing migration scripts before creating a new migration process."
Possible destination:
AGENTS.md
Model-Specific Rule
Example:
"Claude should avoid loading generated vendor directories into context."
Destination:
CLAUDE.md
Reusable Procedure
Example:
"How to safely perform an Access database CSV import."
Destination:
.ai/skills/access-csv-import/SKILL.md
Task Launcher
Example:
"Start a release readiness review."
Destination:
.ai/prompts/release-review.md
Reusable Structure
Example:
"Architecture review document layout."
Destination:
.ai/templates/
15. Generalize
Before promoting an observation, remove accidental details.
Example observation:
"The import of Territory223.csv failed because
the Access driver expected the text qualifier setting."
Possible reusable lesson:
"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:
small rule
over:
large rewrite
Prefer:
existing skill extension
over:
new duplicate skill
Prefer:
skill
over:
500 additional lines in AGENTS.md
17. Test
Every durable self-improvement should be exercised.
Use:
.ai/skills/system-audit/SKILL.md
At minimum test:
the behavior the new rule should improve
and:
one unrelated behavior
This detects unintended regression.
18. Log
After a successful self-improvement:
update:
.ai/CHANGELOG.md
and, when applicable:
.ai/state/LEARNINGS.md
Mark the learning:
PROMOTED
and record the resulting destination.
19. Reuse
A new rule or skill only proves its value when it works again.
When reused, note:
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:
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:
ADDING
and:
REMOVING
guidance.
21. Optimization Targets
Self-improvement should optimize for:
CORRECTNESS
CLARITY
REPEATABILITY
MAINTAINABILITY
VERIFICATION
LOWER FAILURE RATE
LOWER COGNITIVE OVERHEAD
FASTER DISCOVERY
It should not optimize for:
MORE AUTONOMY
MORE FILES
MORE PROMPTS
MORE RULES
LONGER INSTRUCTIONS
MORE COMPLEXITY
22. Instruction Budget
Root instructions are limited attention resources.
Prefer:
SHORT ROOT RULE
↓
SPECIALIZED SKILL
↓
PROJECT DOCUMENTATION
Example:
AGENTS.md:
Use the database migration skill for schema migrations.
Skill:
.ai/skills/database-migration/SKILL.md
Project documentation:
docs/database-schema.md
Do not embed all three layers in the root instructions.
23. Skill Lifecycle
Every skill conceptually progresses through:
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:
.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:
.ai/templates/SKILL_TEMPLATE.md
or:
.ai/skills/skill-builder/SKILL.md
26. Tested Skill
A skill becomes tested after it succeeds in:
ORIGINAL SCENARIO
and preferably:
SECOND DIFFERENT SCENARIO
This helps ensure the procedure was actually generalized.
27. Active Skill
An active skill:
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:
edge cases appear
tests reveal weaknesses
project tooling changes
the procedure can be simplified
Use semantic-style versioning where practical.
Example:
1.0.0
1.0.1
1.1.0
2.0.0
29. Deprecated Skill
Deprecate a skill when:
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:
DRAFT
↓
TEST
↓
USE
↓
FAILURE REVIEW
↓
REFINE
↓
VERSION
When a prompt fails, use:
.ai/skills/prompt-debugger/SKILL.md
Do not blindly add more instructions.
31. Root File Governance
The most sensitive AI-system files are:
AGENTS.md
CLAUDE.md
.ai/AI-OS.md
.ai/WORKFLOW.md
Changes to these files should be made conservatively.
Ask:
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:
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:
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:
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:
.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:
All API endpoints in this project must include
a standard authorization and error-handling wrapper.
First:
.ai/state/LEARNINGS.md
records the pattern.
If repeated:
.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:
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:
FAILURE
↓
ROOT CAUSE
↓
COULD PROCESS HAVE CAUGHT THIS?
↓
YES
↓
PROCESS IMPROVEMENT CANDIDATE
Possible improvements:
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:
SUCCESSFUL PROCEDURE
↓
EXTRACT STRUCTURE
↓
GENERALIZE
↓
TEST
↓
SKILL
Use:
.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:
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:
.ai/state/LEARNINGS.md
Promote strong recurring lessons.
Reject weak ones.
After Project Changes
Re-check:
tooling
versions
architecture
deployment
testing
security assumptions
agent skills
After Model Changes
If agent behavior changes unexpectedly:
run:
.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:
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:
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.