# AI System Changelog This file tracks durable changes to the repository's AI operating system. The goal is to make agent self-improvement: * visible * auditable * reversible * testable Do not use this file for ordinary application code changes. Use it for changes to: ```text AGENTS.md CLAUDE.md .ai/AI-OS.md .ai/WORKFLOW.md .ai/skills/ .ai/prompts/ .ai/templates/ .ai/state/ ``` when those changes alter reusable agent behavior. --- # Versioning Use semantic-style versioning where practical. ```text MAJOR.MINOR.PATCH ``` Examples: ```text 1.0.0 1.0.1 1.1.0 2.0.0 ``` --- # PATCH Use PATCH for: * wording clarification * typo correction * small missing validation * stronger constraint wording * broken file reference * minor procedure correction Example: ```text 1.0.0 → 1.0.1 ``` --- # MINOR Use MINOR for: * new skill * new prompt * new template * meaningful workflow improvement * new verification procedure * new reusable rule Example: ```text 1.0.1 → 1.1.0 ``` --- # MAJOR Use MAJOR when changing: * agent authority * instruction priority * self-modification governance * default execution lifecycle * approval requirements * security boundaries * verification philosophy Example: ```text 1.4.2 → 2.0.0 ``` Major changes should normally be surfaced to the user unless directly requested. --- # Entry Format Use this structure: ```text ## [Version] — [Date] ### Changed - file/path - short description ### Reason Why was the change necessary? ### Evidence What real task, failure, correction, or repeated pattern justified it? ### Expected Improvement What future behavior should improve? ### Verification How was the new behavior tested? ### Result PASS / PARTIAL / FAILED / REVERTED ### Rollback What should be reverted if the change performs worse? ``` --- # Initial Release ## 1.0.0 ### Added * `AGENTS.md` * `CLAUDE.md` * `.ai/AI-OS.md` * `.ai/WORKFLOW.md` * `.ai/CHANGELOG.md` * `.ai/state/LEARNINGS.md` * `.ai/templates/SKILL_TEMPLATE.md` Initial general-purpose skills: * `diagnostic-intake` * `mirror-audit` * `socratic-teacher` * `prompt-architect` * `prompt-debugger` * `reverse-engineer` * `red-team` * `coffee-chat-editor` * `skill-extractor` * `skill-builder` * `retrospective` * `system-audit` Initial reusable prompts: * `discover.md` * `plan.md` * `review.md` * `retrospective.md` ### Reason Establish a reusable, self-improving agent operating system based on: * discovery before action * audit before commitment * verification before completion * adversarial review for consequential work * reusable learning extraction * controlled self-modification ### Expected Improvement Agents should become better at: * understanding unfamiliar projects * avoiding premature implementation * detecting hidden assumptions * verifying generated work * learning reusable procedures * improving their own instructions without uncontrolled prompt growth ### Verification Initial system should be tested using: ```text .ai/skills/system-audit/SKILL.md ``` after all baseline files are installed. ### Result PENDING INITIAL DEPLOYMENT --- # Changelog Rules ## 1. Log Durable Changes Log changes that affect future agent behavior. Examples: ```text new project deployment skill new security review rule improved prompt failure handling new requirement to run a specific project test ``` --- ## 2. Do Not Log Temporary Task Context Do not add entries such as: ```text "Changed variable name during today's task." "Opened controller.asp." "Ran unit test." ``` Those belong in normal project history or the task conversation. --- ## 3. Link Changes to Evidence Avoid changelog entries such as: ```text Improved prompt. ``` Prefer: ```text Updated prompt-debugger skill after three tasks showed that failed prompts were being expanded rather than diagnosed. Added explicit instruction-overload detection and same-input retesting. ``` The changelog should explain why the system evolved. --- ## 4. Record Failed Improvements Failed self-improvements are useful history. Example: ```text ## 1.2.1 ### Changed Added mandatory architecture planning for all code changes. ### Evidence Several larger changes benefited from planning. ### Verification Tested against three small bug fixes. ### Result FAILED The rule created unnecessary overhead for trivial tasks. ### Rollback Reverted mandatory planning and replaced it with Fast / Standard / High-Risk workflow selection. ``` This helps future agents avoid repeating the same experiment. --- # Reversion Policy If a new AI-system change: ```text increases failures creates instruction conflicts causes excessive clarification adds unnecessary process reduces verification quality breaks unrelated workflows ``` then: ```text REVERT ↓ LOG FAILURE ↓ CAPTURE LESSON ``` Do not preserve a bad self-improvement simply because it was versioned. --- # Cross-File Versioning Individual skills may have their own versions. Example: ```text .ai/skills/red-team/SKILL.md Version: 1.2.0 ``` The top-level AI-OS may still be: ```text AI-OS Version: 1.4.0 ``` The root changelog records meaningful cross-system changes. Individual skill changelogs record detailed changes to that skill. --- # Example PATCH Entry ## 1.0.1 — YYYY-MM-DD ### Changed `CLAUDE.md` Added requirement to inspect the resulting diff before finishing substantial edits. ### Reason Claude completed several tasks with correct functionality but left unrelated formatting changes. ### Evidence Repeated formatting churn appeared during three unrelated project tasks. ### Expected Improvement Reduce accidental unrelated modifications. ### Verification Tested on: 1. targeted bug fix 2. documentation edit 3. unrelated code generation task ### Result PASS ### Rollback Remove the new diff-review rule from `CLAUDE.md`. --- # Example MINOR Entry ## 1.1.0 — YYYY-MM-DD ### Added ```text .ai/skills/classic-asp-controller/SKILL.md ``` ### Reason Controller creation repeatedly required the same: * request validation * service initialization * error handling * response pattern ### Evidence The procedure occurred in four controller implementations. ### Expected Improvement Reduce duplicated discovery and inconsistent controller structure. ### Verification Tested against: 1. existing controller reconstruction 2. new test controller ### Result PASS --- # Example Prompt Improvement Entry ## 1.1.1 — YYYY-MM-DD ### Changed ```text .ai/prompts/plan.md ``` ### Reason The planning prompt produced long implementation documents for trivial changes. ### Evidence Three small fixes generated plans longer than the actual change. ### Expected Improvement Plans should scale with task complexity. ### Verification Tested on: * typo fix * moderate feature * database migration ### Result PASS --- # Example Skill Revision ## 1.2.0 — YYYY-MM-DD ### Changed ```text .ai/skills/red-team/SKILL.md ``` ### Added Explicit distinction between: ```text BLOCKER IMPORTANT RISK ACCEPTABLE TRADEOFF SPECULATIVE CONCERN ``` ### Reason Red-team reviews were generating too many low-value objections. ### Evidence Repeated reviews treated minor hypothetical concerns as release blockers. ### Expected Improvement Increase review signal and reduce adversarial noise. ### Verification Re-ran the skill against two previously reviewed designs. ### Result PASS --- # Example Major Change ## 2.0.0 — YYYY-MM-DD ### Changed Default AI workflow changed from: ```text Discover → Plan → Implement → Verify ``` to: ```text Discover → Initial Approach → Mirror Audit → Plan → Implement → Verify ``` ### Reason Agents repeatedly committed to the first plausible architecture without evaluating hidden assumptions. ### Evidence Multiple architecture tasks required substantial correction after implementation began. ### Expected Improvement Catch design errors before implementation cost is incurred. ### Verification Tested on several architecture and migration scenarios. ### Result PASS ### User Review REQUIRED / APPROVED --- # Changelog Quality Test A useful changelog entry should allow a future agent to understand: ```text WHAT CHANGED? WHY? WHAT EVIDENCE EXISTED? WHAT WAS EXPECTED TO IMPROVE? DID IT WORK? HOW CAN IT BE UNDONE? ``` If those questions cannot be answered, the entry is incomplete.