init

.ai/CHANGELOG.md

@@ -0,0 +1,589 @@
+# 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.

.ai/PROJECT.md

@@ -0,0 +1,751 @@
+# Project Profile
+
+Version: 1.0.0
+Status: ACTIVE
+
+## Purpose
+
+This file gives agents a concise, current map of the project.
+
+It should answer:
+
+* what the project is
+* how it is structured
+* what technologies it uses
+* how to build it
+* how to test it
+* how data is stored
+* how it is deployed
+* what constraints matter
+* which project-specific skills exist
+
+This file is not intended to replace the README, architecture documentation, deployment guides, or detailed technical documentation.
+
+It is an **agent-readable index of project truth**.
+
+---
+
+# 1. Project Summary
+
+## Name
+
+```text
+{{PROJECT_NAME}}
+```
+
+## Purpose
+
+```text
+{{SHORT_DESCRIPTION_OF_WHAT_THE_PROJECT_DOES}}
+```
+
+## Primary Users
+
+```text
+{{USERS_OR_CONSUMERS}}
+```
+
+## Repository Type
+
+Choose one or more:
+
+```text
+APPLICATION
+
+SERVICE
+
+LIBRARY
+
+SCRIPT COLLECTION
+
+DATA PIPELINE
+
+INFRASTRUCTURE
+
+DOCUMENTATION
+
+MONOREPO
+```
+
+---
+
+# 2. Source of Truth
+
+When this profile conflicts with current project documentation or code:
+
+```text
+VERIFY THE CURRENT PROJECT STATE
+```
+
+Do not blindly trust stale information in this file.
+
+Important source-of-truth documents:
+
+```text
+{{README_PATH}}
+
+{{ARCHITECTURE_DOC}}
+
+{{DEPLOYMENT_DOC}}
+
+{{OTHER_IMPORTANT_DOCS}}
+```
+
+---
+
+# 3. Technology
+
+## Primary Languages
+
+```text
+{{LANGUAGE}}
+{{LANGUAGE}}
+```
+
+## Frameworks
+
+```text
+{{FRAMEWORK}} — {{VERSION_IF_KNOWN}}
+```
+
+## Runtime
+
+```text
+{{RUNTIME}}
+```
+
+## Operating Environment
+
+```text
+{{WINDOWS/LINUX/CONTAINER/etc}}
+```
+
+## Web/Application Server
+
+```text
+{{IIS/NGINX/APACHE/etc}}
+```
+
+---
+
+# 4. Important Directories
+
+```text
+{{PATH}}
+Purpose: {{PURPOSE}}
+
+{{PATH}}
+Purpose: {{PURPOSE}}
+
+{{PATH}}
+Purpose: {{PURPOSE}}
+```
+
+Example:
+
+```text
+/src
+Application source
+
+/tests
+Automated tests
+
+/scripts
+Build/deployment/maintenance scripts
+
+/docs
+Project documentation
+```
+
+Only include directories agents commonly need.
+
+---
+
+# 5. Entry Points
+
+Important execution entry points:
+
+```text
+{{ENTRY_POINT}}
+Purpose: {{DESCRIPTION}}
+```
+
+Examples:
+
+```text
+/default.asp
+
+Program.cs
+
+index.php
+
+main.py
+
+deploy.ps1
+
+scheduled-import.vbs
+```
+
+---
+
+# 6. Architecture
+
+## Architecture Style
+
+```text
+{{MVC / LAYERED / SCRIPT PIPELINE / MONOLITH / etc}}
+```
+
+## Major Components
+
+```text
+{{COMPONENT}}
+Responsibility:
+{{RESPONSIBILITY}}
+```
+
+## Typical Request / Execution Flow
+
+```text
+INPUT
+   ↓
+{{COMPONENT}}
+   ↓
+{{COMPONENT}}
+   ↓
+{{COMPONENT}}
+   ↓
+OUTPUT
+```
+
+---
+
+# 7. Data
+
+## Primary Data Store
+
+```text
+{{DATABASE_ENGINE_OR_STORAGE}}
+```
+
+## Data Access
+
+```text
+{{ADODB / EF CORE / RAW SQL / ODBC / etc}}
+```
+
+## Schema Location
+
+```text
+{{LOCATION}}
+```
+
+## Migration Method
+
+```text
+{{METHOD_OR_NONE}}
+```
+
+## Important Data Constraints
+
+```text
+- {{CONSTRAINT}}
+- {{CONSTRAINT}}
+```
+
+Do not store passwords, connection secrets, or credentials here.
+
+---
+
+# 8. Authentication
+
+## Authentication Model
+
+```text
+{{WINDOWS AUTH / FORMS / JWT / OAUTH / etc}}
+```
+
+## Authorization Model
+
+```text
+{{ROLES / CLAIMS / CUSTOM / etc}}
+```
+
+## Important Trust Boundaries
+
+```text
+- {{BOUNDARY}}
+- {{BOUNDARY}}
+```
+
+---
+
+# 9. External Integrations
+
+## {{INTEGRATION_NAME}}
+
+Purpose:
+
+```text
+{{PURPOSE}}
+```
+
+Interface:
+
+```text
+{{API / SFTP / SMTP / WEBHOOK / FILE SHARE / etc}}
+```
+
+Relevant documentation:
+
+```text
+{{PATH_OR_REFERENCE}}
+```
+
+---
+
+# 10. Build
+
+## Standard Build
+
+```text
+{{COMMAND}}
+```
+
+## Dependency Restore
+
+```text
+{{COMMAND_IF_NEEDED}}
+```
+
+## Build Output
+
+```text
+{{OUTPUT_LOCATION}}
+```
+
+## Known Requirements
+
+```text
+- {{REQUIREMENT}}
+```
+
+---
+
+# 11. Tests
+
+## Fast Test
+
+```text
+{{COMMAND}}
+```
+
+## Full Test
+
+```text
+{{COMMAND}}
+```
+
+## Integration Tests
+
+```text
+{{COMMAND_OR_NOT_APPLICABLE}}
+```
+
+## Manual Smoke Test
+
+```text
+{{STEPS}}
+```
+
+---
+
+# 12. Deployment
+
+## Target
+
+```text
+{{SERVER / PLATFORM / ENVIRONMENT}}
+```
+
+## Deployment Method
+
+```text
+{{DESCRIPTION}}
+```
+
+## Deployment Command
+
+```text
+{{COMMAND_IF_APPROPRIATE}}
+```
+
+## Health Verification
+
+```text
+{{HEALTH_CHECK}}
+```
+
+## Rollback
+
+```text
+{{ROLLBACK_METHOD}}
+```
+
+Detailed deployment documentation:
+
+```text
+{{DOC_PATH}}
+```
+
+---
+
+# 13. Configuration
+
+Important configuration files:
+
+```text
+{{FILE}}
+Purpose:
+{{PURPOSE}}
+```
+
+Environment-specific configuration:
+
+```text
+{{DESCRIPTION}}
+```
+
+Do not store secrets here.
+
+---
+
+# 14. Coding Conventions
+
+Observed project conventions:
+
+```text
+- {{CONVENTION}}
+- {{CONVENTION}}
+- {{CONVENTION}}
+```
+
+Examples:
+
+```text
+Controllers perform request coordination only.
+
+SQL commands use parameters.
+
+Public APIs use the existing JSON response wrapper.
+```
+
+Only record conventions supported by repeated project evidence or explicit project instruction.
+
+---
+
+# 15. Error Handling
+
+Standard project behavior:
+
+```text
+{{DESCRIPTION}}
+```
+
+Relevant implementation example:
+
+```text
+{{FILE_OR_COMPONENT}}
+```
+
+---
+
+# 16. Logging
+
+Logging mechanism:
+
+```text
+{{MECHANISM}}
+```
+
+Log locations:
+
+```text
+{{LOCATION}}
+```
+
+Important rules:
+
+```text
+- do not log credentials
+- {{RULE}}
+```
+
+---
+
+# 17. Important Constraints
+
+Durable project constraints:
+
+```text
+- {{CONSTRAINT}}
+- {{CONSTRAINT}}
+```
+
+Examples:
+
+```text
+Must remain compatible with Windows Server 2016.
+
+Do not introduce React.
+
+Application must continue using Microsoft Access.
+
+Public endpoint URLs must remain backward compatible.
+```
+
+Only add constraints supported by project requirements.
+
+---
+
+# 18. Existing Patterns
+
+## Creating a New {{COMPONENT}}
+
+Reference examples:
+
+```text
+{{FILE}}
+{{FILE}}
+```
+
+Typical pattern:
+
+```text
+{{SHORT_DESCRIPTION}}
+```
+
+---
+
+# 19. High-Value Workflows
+
+Recurring workflows include:
+
+```text
+{{WORKFLOW}}
+Frequency:
+{{FREQUENCY}}
+
+Current procedure:
+{{REFERENCE}}
+
+Skill:
+{{SKILL_PATH_OR_CANDIDATE}}
+```
+
+---
+
+# 20. Project-Specific Skills
+
+Active skills:
+
+```text
+.ai/skills/{{SKILL}}/SKILL.md
+Purpose:
+{{PURPOSE}}
+```
+
+Skill candidates:
+
+```text
+{{CANDIDATE}}
+Evidence:
+{{EVIDENCE}}
+```
+
+---
+
+# 21. Automation
+
+Existing automation:
+
+```text
+{{SCRIPT}}
+Purpose:
+{{PURPOSE}}
+```
+
+Automation candidates:
+
+```text
+{{CANDIDATE}}
+Reason:
+{{REASON}}
+```
+
+---
+
+# 22. Known Risks
+
+Important known technical or operational risks:
+
+```text
+{{RISK}}
+
+Mitigation:
+{{MITIGATION}}
+```
+
+Do not fill this with every theoretical risk.
+
+Include only risks worth remembering.
+
+---
+
+# 23. Known Unknowns
+
+Items agents should not assume:
+
+```text
+- {{UNKNOWN}}
+- {{UNKNOWN}}
+```
+
+Example:
+
+```text
+Production database version has not yet been verified.
+```
+
+Remove items when resolved.
+
+---
+
+# 24. Useful Commands
+
+## Development
+
+```text
+{{COMMAND}}
+```
+
+## Testing
+
+```text
+{{COMMAND}}
+```
+
+## Build
+
+```text
+{{COMMAND}}
+```
+
+## Deployment
+
+```text
+{{COMMAND}}
+```
+
+## Diagnostics
+
+```text
+{{COMMAND}}
+```
+
+Keep this section practical.
+
+---
+
+# 25. Agent Routing
+
+When working on:
+
+```text
+{{TASK}}
+```
+
+use:
+
+```text
+.ai/skills/{{SKILL}}/SKILL.md
+```
+
+Example:
+
+```text
+Production IIS deployment
+→ .ai/skills/iis-deployment/SKILL.md
+```
+
+---
+
+# 26. Project Evolution
+
+Update this file when:
+
+```text
+framework changes
+
+architecture changes
+
+build changes
+
+test process changes
+
+deployment changes
+
+database changes
+
+authentication changes
+
+important project skills are added
+```
+
+Do not update it for normal implementation details.
+
+---
+
+# 27. Bootstrap Information
+
+Last bootstrap review:
+
+```text
+{{DATE}}
+```
+
+Bootstrap confidence:
+
+```text
+LOW / MEDIUM / HIGH
+```
+
+Areas needing deeper inspection:
+
+```text
+- {{AREA}}
+```
+
+---
+
+# 28. Maintenance Principle
+
+This file should stay:
+
+```text
+CURRENT
+
+CONCISE
+
+USEFUL
+```
+
+If a section becomes large:
+
+```text
+move detailed content to project documentation
+
+and reference it here
+```
+
+This profile is a map, not the entire territory.

.ai/prompts/discover.md

@@ -0,0 +1,191 @@
+# Discover
+
+Version: 1.0.0
+
+## Purpose
+
+Understand the relevant project state before proposing or making changes.
+
+Use this prompt at the beginning of meaningful work when the current implementation, architecture, constraints, or conventions are not yet fully understood.
+
+---
+
+# Instructions
+
+Before proposing a final solution:
+
+1. Read the relevant root instructions.
+2. Inspect the files directly related to the request.
+3. Search for existing implementations that solve a similar problem.
+4. Inspect related configuration.
+5. Inspect tests when available.
+6. Inspect documentation that defines the current behavior.
+7. Identify dependencies and external systems involved.
+8. Identify the project's current conventions.
+
+Do not invent project facts that can be discovered.
+
+---
+
+# Determine
+
+Identify:
+
+```text
+OBJECTIVE
+
+CURRENT STATE
+
+DESIRED STATE
+
+RELEVANT FILES
+
+DEPENDENCIES
+
+CONSTRAINTS
+
+EXISTING PATTERNS
+
+IMPORTANT INVARIANTS
+
+UNKNOWN CRITICAL VARIABLES
+```
+
+---
+
+# Separate Evidence
+
+Classify information as:
+
+```text
+VERIFIED
+
+INFERRED
+
+UNKNOWN
+
+USER DECISION REQUIRED
+```
+
+Do not present an inference as verified fact.
+
+---
+
+# Existing Pattern Search
+
+Before proposing new architecture or structure, search for analogous existing implementations.
+
+Examples:
+
+```text
+new controller
+→ inspect existing controllers
+
+new API
+→ inspect existing APIs
+
+new PowerShell automation
+→ inspect existing scripts
+
+new data-import process
+→ inspect existing imports
+
+new test
+→ inspect existing test conventions
+```
+
+Prefer existing project conventions when they are sound.
+
+---
+
+# Unknown Information
+
+For each unknown ask:
+
+```text
+Can this be discovered from the repository or environment?
+```
+
+If yes:
+
+```text
+DISCOVER IT
+```
+
+If no, determine:
+
+```text
+Does this materially affect correctness?
+```
+
+If yes:
+
+use the Diagnostic Intake skill.
+
+If no:
+
+state a safe assumption when necessary and continue.
+
+---
+
+# Avoid
+
+Do not:
+
+```text
+write implementation before understanding the existing system
+
+invent libraries or APIs
+
+assume architecture
+
+ask the user questions the repository can answer
+
+read unrelated parts of the repository without reason
+
+produce a large design before understanding project constraints
+```
+
+---
+
+# Output
+
+Produce a concise discovery summary:
+
+```text
+## Objective
+
+[...]
+
+## Current State
+
+[...]
+
+## Relevant Existing Patterns
+
+[...]
+
+## Constraints
+
+[...]
+
+## Important Unknowns
+
+[...]
+
+## Recommended Next Step
+
+[...]
+```
+
+For simple tasks, compress this substantially.
+
+---
+
+# Completion
+
+Discovery is complete when enough evidence exists to form a reasonable initial approach.
+
+Discovery does not require knowing everything about the repository.
+
+Stop when additional investigation has low expected value.

.ai/prompts/plan.md

@@ -0,0 +1,293 @@
+# Plan
+
+Version: 1.0.0
+
+## Purpose
+
+Create the smallest implementation plan necessary to safely and verifiably complete the requested work.
+
+The plan must be based on discovered project evidence.
+
+Do not design from generic assumptions when the project already contains relevant patterns.
+
+---
+
+# Before Planning
+
+Confirm that discovery has identified:
+
+```text
+OBJECTIVE
+
+CURRENT STATE
+
+DESIRED STATE
+
+CONSTRAINTS
+
+RELEVANT COMPONENTS
+
+EXISTING PATTERNS
+```
+
+If critical context is still missing, use Diagnostic Intake before planning.
+
+---
+
+# Form Initial Approach
+
+State the proposed approach in concise terms.
+
+Include:
+
+```text
+WHAT WILL CHANGE
+
+WHY THIS APPROACH FITS
+
+WHAT WILL REMAIN UNCHANGED
+```
+
+Treat this as a working hypothesis.
+
+---
+
+# Mirror Audit
+
+Before finalizing the plan, audit the initial approach using:
+
+```text
+.ai/skills/mirror-audit/SKILL.md
+```
+
+Check for:
+
+```text
+hidden assumptions
+
+failure modes
+
+edge cases
+
+security
+
+data integrity
+
+compatibility
+
+rollback
+
+maintainability
+
+unnecessary complexity
+```
+
+Revise the approach when the audit reveals a real weakness.
+
+---
+
+# Plan Structure
+
+A normal implementation plan should contain:
+
+```text
+## Objective
+
+[...]
+
+## Files / Components
+
+- [...]
+- [...]
+
+## Implementation Sequence
+
+1. [...]
+2. [...]
+3. [...]
+
+## Risks
+
+- [...]
+
+## Verification
+
+- [...]
+
+## Rollback
+
+[...]  // only when relevant
+```
+
+---
+
+# Scale to Complexity
+
+## Fast Path
+
+For trivial work:
+
+```text
+1. make change
+2. verify
+```
+
+Do not generate a formal architecture plan.
+
+---
+
+## Standard Path
+
+For normal feature work:
+
+```text
+1. inspect affected component
+2. modify implementation
+3. update related tests
+4. verify
+5. review
+```
+
+---
+
+## High-Risk Path
+
+For migrations, security, infrastructure, destructive changes, or major architecture:
+
+include:
+
+```text
+preconditions
+
+backup
+
+rollback
+
+execution order
+
+verification gates
+
+recovery
+
+red-team review
+```
+
+---
+
+# Dependencies
+
+Identify dependencies that affect sequencing.
+
+Example:
+
+```text
+database schema
+    ↓
+data access layer
+    ↓
+service
+    ↓
+controller
+    ↓
+tests
+```
+
+Do not order work arbitrarily when dependencies require a specific sequence.
+
+---
+
+# Verification Plan
+
+Specify how each meaningful result will be verified.
+
+Prefer:
+
+```text
+existing test
+
+targeted test
+
+build
+
+static analysis
+
+smoke test
+
+query
+
+health check
+
+direct execution
+```
+
+Avoid:
+
+```text
+verify that it looks right
+```
+
+when stronger evidence is available.
+
+---
+
+# Rollback
+
+Define rollback when:
+
+```text
+change is destructive
+
+production state changes
+
+schema changes
+
+data transforms
+
+deployment can partially fail
+
+external state changes
+```
+
+Do not create elaborate rollback plans for trivial reversible edits.
+
+---
+
+# Scope Control
+
+Explicitly identify what the implementation will NOT change when scope drift is likely.
+
+Example:
+
+```text
+This change will add the import status reporting.
+
+It will not replace the existing Access import mechanism.
+```
+
+---
+
+# Avoid
+
+Do not:
+
+```text
+create plans longer than the work
+
+introduce architecture not justified by the request
+
+include speculative future features
+
+list every theoretical risk
+
+repeat discovery details unnecessarily
+```
+
+---
+
+# Output
+
+Return the finalized implementation plan.
+
+If the plan reveals a blocker, surface it before implementation.
+
+Otherwise proceed according to the current task's execution mode.

.ai/prompts/retrospective.md

@@ -0,0 +1,245 @@
+# Retrospective
+
+Version: 1.0.0
+
+## Purpose
+
+Evaluate completed work for reusable learning and decide whether any part of the AI operating system should improve.
+
+Keep this lightweight.
+
+The default outcome may be:
+
+```text
+NO PERMANENT CHANGE
+```
+
+---
+
+# Review the Task
+
+Ask:
+
+```text
+Did the requested result succeed?
+
+What worked particularly well?
+
+What failed or nearly failed?
+
+What assumption was wrong?
+
+What evidence resolved uncertainty?
+
+What check found the problem?
+
+Could something have caught it earlier?
+```
+
+---
+
+# Identify Reusable Learning
+
+Ask:
+
+```text
+Would this matter again?
+```
+
+Possible reusable discoveries:
+
+```text
+procedure
+
+diagnostic method
+
+verification method
+
+failure pattern
+
+project convention
+
+prompt improvement
+
+automation opportunity
+
+template
+```
+
+---
+
+# Determine Scope
+
+Classify the lesson:
+
+```text
+TASK-SPECIFIC
+
+PROJECT FACT
+
+PROJECT PROCEDURE
+
+GENERAL AGENT RULE
+
+MODEL-SPECIFIC RULE
+
+SKILL IMPROVEMENT
+
+PROMPT IMPROVEMENT
+
+AUTOMATION
+```
+
+---
+
+# Choose Destination
+
+Use the narrowest appropriate location.
+
+```text
+PROJECT FACT
+→ project documentation
+
+REUSABLE PROCEDURE
+→ existing/new skill
+
+GENERAL AGENT RULE
+→ AGENTS.md
+
+CLAUDE-SPECIFIC
+→ CLAUDE.md
+
+PROMPT FAILURE
+→ prompt / prompt-debugger
+
+AUTOMATABLE DETERMINISTIC WORK
+→ script or automation
+
+WEAK CANDIDATE
+→ LEARNINGS.md
+```
+
+---
+
+# Evidence Test
+
+Before permanent promotion ask:
+
+```text
+Is there actual evidence?
+
+Is the lesson reusable?
+
+Is the cause understood?
+
+Can the improvement be tested?
+
+Does existing guidance already cover it?
+```
+
+If evidence is weak:
+
+```text
+record candidate in .ai/state/LEARNINGS.md
+```
+
+instead of changing permanent instructions.
+
+---
+
+# Skill Decision
+
+If the task revealed a reusable procedure, use:
+
+```text
+.ai/skills/skill-extractor/SKILL.md
+```
+
+Do not create the skill directly without checking for existing ownership.
+
+---
+
+# Prompt Decision
+
+If AI instructions failed, use:
+
+```text
+.ai/skills/prompt-debugger/SKILL.md
+```
+
+Determine why before rewriting.
+
+---
+
+# Automation Decision
+
+If a repeated procedure is deterministic, consider whether:
+
+```text
+SCRIPT
+```
+
+is better than:
+
+```text
+SKILL
+```
+
+Examples:
+
+```text
+schema validation
+file comparison
+deployment health check
+build verification
+```
+
+Agents should not solve with prompts what software can reliably automate.
+
+---
+
+# Output
+
+Return an internal or visible summary:
+
+```text
+## Result
+
+[...]
+
+## What Worked
+
+[...]
+
+## What Failed
+
+[...]
+
+## Reusable Lesson
+
+[...]
+
+## Action
+
+NO CHANGE
+or
+LEARNING ENTRY
+or
+UPDATE EXISTING SKILL
+or
+CREATE SKILL
+or
+UPDATE PROMPT
+or
+UPDATE PROJECT DOCS
+or
+UPDATE AGENTS.md
+or
+UPDATE CLAUDE.md
+or
+CREATE AUTOMATION
+```
+
+If no durable lesson exists, stop.
+
+Do not create process merely because a retrospective was performed.

.ai/prompts/review.md

@@ -0,0 +1,334 @@
+# Review
+
+Version: 1.0.0
+
+## Purpose
+
+Review completed work for correctness, regression risk, maintainability, security, and consistency with the project's existing behavior.
+
+This review occurs after implementation.
+
+It does not replace execution or testing.
+
+---
+
+# Review Context
+
+Before reviewing, understand:
+
+```text
+REQUESTED CHANGE
+
+ACTUAL CHANGE
+
+FILES MODIFIED
+
+VERIFICATION ALREADY PERFORMED
+
+IMPORTANT PROJECT CONSTRAINTS
+```
+
+Inspect the resulting diff when available.
+
+---
+
+# Review Areas
+
+Evaluate only relevant areas.
+
+---
+
+# Correctness
+
+Check:
+
+```text
+Does the implementation satisfy the request?
+
+Does the logic do what it claims?
+
+Are important branches handled?
+
+Are errors handled appropriately?
+```
+
+---
+
+# Regression Risk
+
+Ask:
+
+```text
+What existing behavior could this change unintentionally affect?
+```
+
+Inspect:
+
+```text
+callers
+
+shared code
+
+public APIs
+
+database behavior
+
+configuration
+
+routes
+
+file formats
+
+authentication
+```
+
+when relevant.
+
+---
+
+# Project Consistency
+
+Check whether the implementation follows established:
+
+```text
+architecture
+
+naming
+
+error handling
+
+configuration
+
+data access
+
+testing
+
+logging
+```
+
+Do not recommend a different architecture merely because another pattern is personally preferable.
+
+---
+
+# Security
+
+When relevant, inspect:
+
+```text
+authentication
+
+authorization
+
+input validation
+
+output encoding
+
+SQL injection
+
+command injection
+
+path traversal
+
+secret handling
+
+privilege boundaries
+```
+
+Do not manufacture security findings without evidence.
+
+---
+
+# Data Integrity
+
+For data changes inspect:
+
+```text
+transactions
+
+null handling
+
+duplicates
+
+type conversion
+
+row counts
+
+partial writes
+
+referential integrity
+```
+
+---
+
+# Maintainability
+
+Look for:
+
+```text
+unnecessary duplication
+
+hidden side effects
+
+magic values
+
+poor naming
+
+unnecessary abstraction
+
+unnecessary dependencies
+
+complexity without benefit
+```
+
+---
+
+# Verification
+
+Check:
+
+```text
+Were appropriate tests actually run?
+
+Does the verification prove the important behavior?
+
+Was only the happy path tested?
+
+What remains unverified?
+```
+
+Do not accept:
+
+```text
+"This should work."
+```
+
+as verification evidence.
+
+---
+
+# Diff Hygiene
+
+Inspect for:
+
+```text
+accidental deletions
+
+formatting churn
+
+debug code
+
+temporary files
+
+hardcoded credentials
+
+unrelated edits
+
+stale comments
+
+generated files accidentally committed
+```
+
+---
+
+# Finding Classification
+
+Classify findings as:
+
+```text
+BLOCKER
+
+IMPORTANT
+
+OPTIONAL
+```
+
+## Blocker
+
+Must be resolved before completion.
+
+## Important
+
+Should be addressed because it creates meaningful risk.
+
+## Optional
+
+Improvement that is useful but not required for correctness.
+
+Do not inflate optional preferences into blockers.
+
+---
+
+# Finding Format
+
+For each meaningful finding:
+
+```text
+### Finding
+
+Severity:
+[...]
+
+Location:
+[...]
+
+Issue:
+[...]
+
+Why It Matters:
+[...]
+
+Recommended Change:
+[smallest appropriate correction]
+```
+
+---
+
+# No-Issue Result
+
+It is acceptable to conclude:
+
+```text
+No blocking or important issues found.
+```
+
+Do not invent findings to justify the review.
+
+---
+
+# Red-Team Routing
+
+If the task is consequential and normal review passes, invoke:
+
+```text
+.ai/skills/red-team/SKILL.md
+```
+
+for the relevant adversarial perspective.
+
+---
+
+# Output
+
+Return:
+
+```text
+## Review Result
+
+PASS
+or
+CHANGES REQUIRED
+
+## Blockers
+[...]
+
+## Important Findings
+[...]
+
+## Optional Improvements
+[...]
+
+## Verification Notes
+[...]
+```
+
+Omit empty sections when they add no value.

.ai/skills/agent-maintainer/SKILL.md

@@ -0,0 +1,716 @@
+# Agent System Maintainer
+
+Version: 1.0.0
+Status: ACTIVE
+
+## Purpose
+
+Maintain the health of the repository's self-improving AI operating system.
+
+The self-improvement system must be able to do both:
+
+```text
+ADD USEFUL KNOWLEDGE
+```
+
+and:
+
+```text
+REMOVE STALE OR DUPLICATE KNOWLEDGE
+```
+
+Without maintenance, self-improving systems tend to accumulate:
+
+```text
+too many skills
+
+duplicate rules
+
+stale project assumptions
+
+unused prompts
+
+conflicting instructions
+
+obsolete workflows
+```
+
+This skill provides deliberate cleanup.
+
+---
+
+# 1. Trigger Conditions
+
+Use this skill:
+
+* after substantial AI-OS growth
+* after several new skills are added
+* after major project architecture changes
+* when agents struggle to select the right skill
+* when root instructions become large
+* when conflicting behavior appears
+* when skills appear duplicated
+* periodically when ongoing agent use justifies maintenance
+
+Do not run full maintenance after every ordinary task.
+
+---
+
+# 2. Maintenance Flow
+
+```text
+INVENTORY
+   ↓
+USAGE REVIEW
+   ↓
+DUPLICATION REVIEW
+   ↓
+CONFLICT REVIEW
+   ↓
+STALE KNOWLEDGE REVIEW
+   ↓
+SKILL HEALTH
+   ↓
+PROMPT HEALTH
+   ↓
+ROOT INSTRUCTION HEALTH
+   ↓
+PROJECT PROFILE HEALTH
+   ↓
+CLEANUP PLAN
+   ↓
+SYSTEM AUDIT
+```
+
+---
+
+# 3. Inventory
+
+Inspect:
+
+```text
+AGENTS.md
+
+CLAUDE.md
+
+.ai/AI-OS.md
+
+.ai/WORKFLOW.md
+
+.ai/PROJECT.md
+
+.ai/skills/
+
+.ai/prompts/
+
+.ai/templates/
+
+.ai/state/LEARNINGS.md
+
+.ai/CHANGELOG.md
+```
+
+Determine what currently exists.
+
+---
+
+# 4. Skill Inventory
+
+For each skill identify:
+
+```text
+NAME
+
+VERSION
+
+STATUS
+
+PURPOSE
+
+TRIGGER
+
+REFERENCES
+
+KNOWN USAGE
+```
+
+Look for unclear ownership.
+
+---
+
+# 5. Unused Skill Review
+
+Ask:
+
+```text
+Has this skill actually been useful?
+```
+
+Possible statuses:
+
+```text
+ACTIVE AND USED
+
+ACTIVE BUT UNCONFIRMED
+
+OBSOLETE
+
+DUPLICATE
+
+CANDIDATE
+```
+
+Do not delete a skill only because usage statistics are unavailable.
+
+Use project evidence and changelog history.
+
+---
+
+# 6. Duplicate Skill Review
+
+Compare skills for:
+
+```text
+same trigger
+
+same procedure
+
+same outputs
+
+same domain
+```
+
+If two skills overlap substantially, decide:
+
+```text
+MERGE
+
+NARROW
+
+DEPRECATE ONE
+
+KEEP SEPARATE
+```
+
+Keep separate only when the distinction improves agent routing.
+
+---
+
+# 7. Root Duplication Review
+
+Check whether `AGENTS.md` duplicates:
+
+```text
+skills
+
+WORKFLOW.md
+
+AI-OS.md
+
+project documentation
+```
+
+Root instructions should contain:
+
+```text
+POLICY
+
+ROUTING
+
+CORE BEHAVIOR
+```
+
+not every procedure.
+
+---
+
+# 8. Model Adapter Review
+
+Check whether `CLAUDE.md` contains generic rules that belong in:
+
+```text
+AGENTS.md
+```
+
+or project facts that belong in:
+
+```text
+PROJECT.md
+```
+
+Keep model adapters thin.
+
+---
+
+# 9. Prompt Review
+
+Inspect `.ai/prompts/`.
+
+Identify:
+
+```text
+unused prompts
+
+duplicate prompts
+
+stale prompts
+
+prompts that should be skills
+
+prompts whose behavior is now in root instructions
+```
+
+Delete or deprecate low-value prompts.
+
+---
+
+# 10. Template Review
+
+Templates should represent useful recurring structures.
+
+Check for:
+
+```text
+unused templates
+
+obsolete formats
+
+duplicates
+
+project-specific content in generic templates
+```
+
+---
+
+# 11. Learning Ledger Review
+
+Review:
+
+```text
+.ai/state/LEARNINGS.md
+```
+
+Classify pending entries:
+
+```text
+PROMOTE
+
+KEEP PENDING
+
+REJECT
+
+MERGE
+
+STALE
+```
+
+Do not allow old weak candidates to accumulate forever.
+
+---
+
+# 12. Stale Project Information
+
+Compare:
+
+```text
+.ai/PROJECT.md
+```
+
+against current repository evidence.
+
+Check:
+
+```text
+framework
+
+runtime
+
+database
+
+deployment
+
+tests
+
+directories
+
+authentication
+
+external integrations
+```
+
+Update stale information.
+
+Do not silently preserve old architecture.
+
+---
+
+# 13. Broken Reference Review
+
+Validate references to:
+
+```text
+skills
+
+prompts
+
+templates
+
+docs
+
+scripts
+```
+
+Remove or correct broken paths.
+
+---
+
+# 14. Version Review
+
+Check that important changes were versioned appropriately.
+
+Look for:
+
+```text
+significant behavior changes without version increment
+
+deprecated skills still marked ACTIVE
+
+new skills missing changelog entries
+```
+
+---
+
+# 15. Changelog Review
+
+Determine whether:
+
+```text
+.ai/CHANGELOG.md
+```
+
+still explains meaningful AI-system evolution.
+
+Do not require excessive entries for tiny formatting changes.
+
+---
+
+# 16. Instruction Conflict Review
+
+Search for incompatible rules.
+
+Examples:
+
+```text
+always ask
+vs.
+never ask
+
+always plan
+vs.
+fast path
+
+always use skill X
+vs.
+skill X says it is optional
+```
+
+Resolve conflicts operationally.
+
+---
+
+# 17. Routing Quality
+
+Ask:
+
+```text
+Can an agent tell which skill to use?
+```
+
+If several skills could plausibly activate:
+
+```text
+tighten triggers
+
+add routing rule
+
+merge skills
+```
+
+Good skill libraries are easy to navigate.
+
+---
+
+# 18. Skill Library Size
+
+There is no ideal number.
+
+However ask:
+
+```text
+Does each active skill justify its context cost?
+```
+
+A smaller high-quality library is preferable to a large noisy one.
+
+---
+
+# 19. General vs Project Skills
+
+Classify skills as:
+
+```text
+GENERAL
+
+PROJECT-SPECIFIC
+```
+
+Generic skills should remain portable.
+
+Project-specific skills may contain project domain knowledge.
+
+Do not force every skill to be universal.
+
+---
+
+# 20. Automation Review
+
+Look for skills that repeatedly describe deterministic operations.
+
+Ask:
+
+```text
+Should this become executable automation?
+```
+
+Example:
+
+Skill repeatedly says:
+
+```text
+check these 12 configuration keys
+```
+
+A validation script may be better.
+
+Keep the skill as orchestration if needed, but automate reliable mechanical checks.
+
+---
+
+# 21. Documentation Review
+
+Ensure project facts live in appropriate documentation rather than only inside AI instructions.
+
+Important knowledge should not become inaccessible to human developers.
+
+---
+
+# 22. Simplification
+
+For each system component ask:
+
+```text
+Can this be shorter without losing behavior?
+```
+
+Look for:
+
+```text
+repeated definitions
+
+duplicated examples
+
+obvious rules
+
+obsolete caveats
+```
+
+Self-improvement includes compression.
+
+---
+
+# 23. Cleanup Classification
+
+For each finding choose:
+
+```text
+KEEP
+
+REVISE
+
+MOVE
+
+MERGE
+
+DEPRECATE
+
+DELETE
+```
+
+Do not perform large cleanup without understanding dependencies.
+
+---
+
+# 24. Deprecation Before Deletion
+
+For heavily referenced skills:
+
+```text
+DEPRECATE
+   ↓
+UPDATE REFERENCES
+   ↓
+VERIFY
+   ↓
+DELETE LATER
+```
+
+For unused experimental files:
+
+```text
+DELETE
+```
+
+may be sufficient.
+
+Version control preserves history.
+
+---
+
+# 25. Cleanup Safety
+
+Do not remove:
+
+```text
+user-authored requirements
+
+security safeguards
+
+verification requirements
+
+project-critical workflows
+```
+
+merely to reduce file size.
+
+Simplification must preserve behavior.
+
+---
+
+# 26. Maintenance Report
+
+Produce:
+
+```text
+## AI-OS Health
+
+### Keep
+
+[...]
+
+### Revise
+
+[...]
+
+### Merge
+
+[...]
+
+### Deprecate
+
+[...]
+
+### Delete
+
+[...]
+
+### Project Profile Updates
+
+[...]
+
+### System Risks
+
+[...]
+
+### Recommended Version Change
+
+[...]
+```
+
+For small systems, compress this.
+
+---
+
+# 27. Apply Changes
+
+When authorized by the self-improvement rules:
+
+```text
+make the smallest coherent cleanup changes
+```
+
+Then run:
+
+```text
+.ai/skills/system-audit/SKILL.md
+```
+
+---
+
+# 28. Regression
+
+After maintenance, test:
+
+```text
+FAST PATH
+
+STANDARD PATH
+
+HIGH-RISK PATH
+
+SKILL ROUTING
+
+SELF-IMPROVEMENT
+```
+
+The cleaned system should behave at least as well as before.
+
+---
+
+# 29. Maintenance Success Criteria
+
+Maintenance succeeds when:
+
+```text
+agents can find guidance more easily
+
+duplicate guidance decreases
+
+stale information decreases
+
+important safeguards remain
+
+context burden decreases or remains justified
+
+no important workflow regresses
+```
+
+---
+
+# 30. Changelog
+
+## 1.0.0
+
+Initial active version.
+
+Introduced:
+
+* AI-system inventory
+* unused skill review
+* duplicate skill detection
+* root/model adapter cleanup
+* prompt/template maintenance
+* learning-ledger cleanup
+* stale project-profile detection
+* routing review
+* automation opportunities
+* merge/deprecate/delete lifecycle

.ai/skills/coffee-chat-editor/SKILL.md

@@ -0,0 +1,908 @@
+# Coffee Chat Editor
+
+Version: 1.0.0
+Status: ACTIVE
+
+## Purpose
+
+Edit AI-generated or overly formal prose so it sounds direct, natural, specific, and human while preserving the author's intended meaning.
+
+The goal is not:
+
+```text
+MAKE EVERYTHING CASUAL
+```
+
+The goal is:
+
+```text
+REMOVE MECHANICAL AI WRITING
+```
+
+while retaining the appropriate level of professionalism.
+
+---
+
+# 1. Trigger Conditions
+
+Use this skill for important user-facing prose such as:
+
+* emails
+* reports
+* proposals
+* executive updates
+* documentation
+* announcements
+* instructions
+* presentations
+* business communication
+* explanations
+* public-facing copy
+
+Use it when the draft sounds:
+
+```text
+generic
+
+stiff
+
+repetitive
+
+overly formal
+
+corporate
+
+AI-generated
+
+wordy
+```
+
+Do not apply this style mechanically to:
+
+* source code
+* legal text that must preserve exact wording
+* technical specifications where precision requires formality
+* quoted source material
+* data tables
+
+---
+
+# 2. Core Editing Pass
+
+Use this sequence:
+
+```text
+CUT
+   ↓
+SPECIFY
+   ↓
+SIMPLIFY
+   ↓
+VARY
+   ↓
+SPEAK
+```
+
+---
+
+# 3. Cut Unnecessary Opening
+
+Look at the first sentence or paragraph.
+
+Common weak openings:
+
+```text
+Certainly!
+
+Great question.
+
+In today's rapidly evolving world...
+
+It is important to note that...
+
+I hope this message finds you well...
+```
+
+Ask:
+
+```text
+Does the reader need this before the real message?
+```
+
+If not, remove it.
+
+Start closer to the point.
+
+---
+
+# 4. Cut Unnecessary Closing
+
+AI prose often repeats itself at the end.
+
+Example:
+
+```text
+In conclusion, by following these steps,
+you can ensure a successful implementation.
+```
+
+If the body already established this, remove it.
+
+A useful ending may instead contain:
+
+```text
+decision
+
+next action
+
+deadline
+
+specific request
+
+important final fact
+```
+
+---
+
+# 5. Replace Generic Language
+
+Weak:
+
+```text
+We encountered some challenges during implementation.
+```
+
+Better:
+
+```text
+The import failed because 214 rows contained invalid ZIP codes.
+```
+
+Prefer:
+
+```text
+CONCRETE FACT
+```
+
+over:
+
+```text
+GENERIC DESCRIPTION
+```
+
+---
+
+# 6. Replace Generic Verbs
+
+Weak verbs include:
+
+```text
+utilize
+
+facilitate
+
+leverage
+
+enable
+
+optimize
+
+enhance
+```
+
+when a simpler verb communicates more clearly.
+
+Examples:
+
+```text
+utilize → use
+
+facilitate communication → help the teams communicate
+
+leverage the API → use the API
+```
+
+Do not ban a word if it is genuinely the most accurate choice.
+
+---
+
+# 7. Remove Transitional Slag
+
+Look for excessive:
+
+```text
+Furthermore
+
+Moreover
+
+Additionally
+
+In addition
+
+With that being said
+
+As previously mentioned
+
+It is worth noting
+```
+
+Sometimes the next sentence can simply begin.
+
+Transitions should clarify structure, not fill space.
+
+---
+
+# 8. Vary Sentence Length
+
+Mechanical AI writing often has repeated sentence rhythm.
+
+Example:
+
+```text
+The system validates the request.
+The system checks the database.
+The system creates the record.
+The system returns the response.
+```
+
+Possible revision:
+
+```text
+The system validates the request, checks the database,
+and creates the record. If successful, it returns the response.
+```
+
+Do not artificially vary sentences merely to create style.
+
+Prioritize readability.
+
+---
+
+# 9. Prefer Active Voice
+
+Weak:
+
+```text
+The database was updated by the deployment script.
+```
+
+Better:
+
+```text
+The deployment script updated the database.
+```
+
+Use passive voice when the actor is:
+
+```text
+unknown
+
+irrelevant
+
+intentionally de-emphasized
+```
+
+Active voice is a preference, not an absolute rule.
+
+---
+
+# 10. Replace Abstract Nouns
+
+Weak:
+
+```text
+The implementation of the validation will provide
+an improvement in reliability.
+```
+
+Better:
+
+```text
+The validation will make the import more reliable.
+```
+
+Look for unnecessary noun constructions:
+
+```text
+implementation of
+
+utilization of
+
+optimization of
+
+execution of
+```
+
+Convert to direct verbs when possible.
+
+---
+
+# 11. Remove Fake Importance
+
+Watch for:
+
+```text
+crucial
+
+critical
+
+paramount
+
+pivotal
+
+essential
+
+game-changing
+```
+
+when no evidence supports the emphasis.
+
+Weak:
+
+```text
+It is crucial to ensure robust data integrity.
+```
+
+Better:
+
+```text
+Validate the imported row count before deleting the source file.
+```
+
+Specific consequences create importance naturally.
+
+---
+
+# 12. Avoid Decorative Vocabulary
+
+Be suspicious of words that make simple ideas sound grand.
+
+Examples:
+
+```text
+delve
+
+landscape
+
+tapestry
+
+multifaceted
+
+spearhead
+
+unlock
+
+foster
+
+synergy
+
+seamless
+
+navigate
+```
+
+Do not maintain a rigid banned-word list.
+
+The real rule is:
+
+```text
+USE THE SIMPLEST ACCURATE WORD
+```
+
+---
+
+# 13. Reduce Artificial Symmetry
+
+AI frequently writes:
+
+```text
+faster, smarter, and more efficient
+
+clear, concise, and actionable
+
+security, scalability, and reliability
+```
+
+Three-part lists are fine when three real categories exist.
+
+Remove them when they are decorative.
+
+---
+
+# 14. Reduce Excessive Headings
+
+Do not create a heading for every paragraph.
+
+Use headings when they help the reader:
+
+```text
+scan
+
+navigate
+
+understand hierarchy
+```
+
+For short communication, paragraphs may be better.
+
+---
+
+# 15. Reduce Excessive Bold
+
+AI drafts often bold too many phrases.
+
+Use emphasis for genuinely important:
+
+```text
+decision
+
+deadline
+
+risk
+
+action
+
+number
+```
+
+If everything is emphasized, nothing is.
+
+---
+
+# 16. Keep Specific Numbers
+
+Do not replace:
+
+```text
+214 rejected rows
+```
+
+with:
+
+```text
+a number of rejected records
+```
+
+Specific information makes prose sound more credible and useful.
+
+---
+
+# 17. Keep Necessary Technical Terms
+
+Do not simplify away precision.
+
+Example:
+
+```text
+TLS certificate
+```
+
+should not become:
+
+```text
+security thing
+```
+
+Use the proper term and explain it when the audience needs help.
+
+---
+
+# 18. Remove Repetition
+
+Check whether consecutive sections repeat:
+
+```text
+same conclusion
+
+same risk
+
+same recommendation
+
+same background
+```
+
+Merge or cut repetition.
+
+---
+
+# 19. Compress Setup
+
+Weak:
+
+```text
+Before we get into the details, it may be useful to first
+provide a little bit of context regarding how the system
+currently operates.
+```
+
+Better:
+
+```text
+The application currently imports the CSV directly into Access.
+```
+
+Start with actual context.
+
+---
+
+# 20. Direct Requests
+
+For email or business communication, make the requested action obvious.
+
+Weak:
+
+```text
+It would be greatly appreciated if you could potentially
+review the attached material when you have an opportunity.
+```
+
+Better:
+
+```text
+Please review the attached file by Friday.
+```
+
+Direct does not mean rude.
+
+---
+
+# 21. Friendly Without Filler
+
+Warm communication may still be concise.
+
+Example:
+
+```text
+Thanks again for helping with the convention cleanup.
+The windows looked great, and your help made Friday's setup much easier.
+```
+
+This is warmer than generic praise because it is specific.
+
+---
+
+# 22. Tone Levels
+
+Choose a tone appropriate to the audience.
+
+## Level 1 — Executive Brief
+
+Use:
+
+```text
+short
+
+decision-focused
+
+specific
+
+little background
+```
+
+---
+
+## Level 2 — Peer Colleague
+
+Use:
+
+```text
+direct
+
+professional
+
+natural
+
+moderate technical detail
+```
+
+---
+
+## Level 3 — Socratic Tutor
+
+Use:
+
+```text
+clear
+
+conversational
+
+question-driven
+
+supportive without overpraise
+```
+
+---
+
+## Level 4 — Non-Technical Friend
+
+Use:
+
+```text
+plain language
+
+short examples
+
+minimal jargon
+
+natural phrasing
+```
+
+Do not automatically choose Level 4 because it sounds "human."
+
+Audience determines tone.
+
+---
+
+# 23. Executive Editing Example
+
+Before:
+
+```text
+It is important to note that the deployment was ultimately
+successful, despite the fact that we did encounter a number
+of challenges throughout the overall implementation process.
+```
+
+After:
+
+```text
+The deployment succeeded after we corrected two configuration errors.
+```
+
+---
+
+# 24. Technical Documentation Example
+
+Before:
+
+```text
+In order to facilitate the process of determining which
+application is currently utilizing a specific port, the
+following command can be leveraged.
+```
+
+After:
+
+```text
+Use this command to find the process using a port:
+```
+
+---
+
+# 25. Status Update Example
+
+Before:
+
+```text
+We have continued to make meaningful progress across a
+number of key areas as we navigate toward completion.
+```
+
+After:
+
+```text
+The API is complete. Database migration testing is still in progress.
+```
+
+---
+
+# 26. Email Example
+
+Before:
+
+```text
+I just wanted to reach out and take a moment to thank
+everyone for all of your assistance and support.
+```
+
+After:
+
+```text
+Thank you for helping with the cleanup this weekend.
+```
+
+Specific detail can follow.
+
+---
+
+# 27. Do Not Destroy Personality
+
+The goal is not to make every writer sound identical.
+
+Preserve:
+
+```text
+humor
+
+warmth
+
+formality
+
+directness
+
+individual vocabulary
+```
+
+when appropriate.
+
+Remove machine-like patterns, not human personality.
+
+---
+
+# 28. Do Not Over-Compress
+
+Too much editing can turn useful explanation into telegram-style prose.
+
+Before:
+
+```text
+The script stops IIS before copying the files because
+IIS may otherwise keep DLLs open and prevent replacement.
+```
+
+Do not reduce to:
+
+```text
+Stop IIS. Copy files.
+```
+
+The explanation matters.
+
+---
+
+# 29. Read-Aloud Test
+
+After editing, mentally read the prose at speaking pace.
+
+Ask:
+
+```text
+Would a real person naturally say this?
+
+Is any sentence awkward?
+
+Is any phrase unnecessarily formal?
+
+Does the rhythm sound repetitive?
+```
+
+This is a strong final test.
+
+---
+
+# 30. Meaning Preservation
+
+Never change:
+
+```text
+technical meaning
+
+commitment
+
+deadline
+
+legal meaning
+
+risk severity
+
+quantitative facts
+```
+
+merely to improve tone.
+
+Stylistic editing must preserve substance.
+
+---
+
+# 31. Source Preservation
+
+When editing text based on a provided source, preserve the source's:
+
+```text
+facts
+
+claims
+
+terminology
+
+level of certainty
+```
+
+Do not introduce unsupported content merely to make the prose sound more complete.
+
+---
+
+# 32. Five-Step Fast Pass
+
+For routine editing, use:
+
+```text
+1. CUT unnecessary first/last sentence
+
+2. VARY repetitive sentence structure
+
+3. REPLACE generic language with specifics
+
+4. REMOVE mechanical transitions
+
+5. READ ALOUD
+```
+
+This is the default lightweight mode.
+
+---
+
+# 33. Full Pass
+
+For important external communication:
+
+```text
+1. identify audience
+2. identify purpose
+3. identify required action
+4. remove unnecessary preamble
+5. replace generic language
+6. simplify verbs
+7. remove repetitive transitions
+8. vary sentence length
+9. check technical precision
+10. check tone
+11. remove redundant closing
+12. read aloud
+```
+
+---
+
+# 34. Output Contract
+
+When used as an editing skill, return:
+
+```text
+EDITED VERSION
+```
+
+When useful, also briefly identify:
+
+```text
+major changes made
+```
+
+Do not bury the revised text underneath a long critique unless critique was requested.
+
+---
+
+# 35. Self-Improvement
+
+Improve this skill when:
+
+* edited output still sounds mechanical
+* editing removes too much technical precision
+* tone becomes overly casual
+* repeated user corrections reveal a stable writing preference
+* a better concise editing checklist emerges
+
+Do not create enormous word-ban lists.
+
+Prefer principles.
+
+---
+
+# 36. Changelog
+
+## 1.0.0
+
+Initial active version.
+
+Introduced:
+
+* zero-preamble preference
+* unnecessary-ending removal
+* concrete specificity
+* active voice
+* transition cleanup
+* sentence-rhythm variation
+* anti-buzzword guidance
+* tone levels
+* read-aloud test
+* meaning preservation
+* five-step fast pass

.ai/skills/diagnostic-intake/SKILL.md

@@ -0,0 +1,546 @@
+# Diagnostic Intake
+
+Version: 1.0.0
+Status: ACTIVE
+
+## Purpose
+
+Determine the minimum missing context required to complete a task accurately without producing generic output, asking unnecessary questions, or inventing project facts.
+
+This skill prevents two common agent failures:
+
+```text
+ASKING TOO MANY QUESTIONS
+```
+
+and:
+
+```text
+GUESSING WHEN THE ANSWER COULD HAVE BEEN DISCOVERED
+```
+
+---
+
+# 1. Trigger Conditions
+
+Use this skill when:
+
+* the request is materially ambiguous
+* multiple valid implementations depend on unknown constraints
+* architecture depends on missing information
+* a workflow cannot be safely selected yet
+* critical project facts are unknown
+* the user asks for a curriculum, architecture, process, or major plan with insufficient context
+* a wrong assumption could create substantial rework
+
+Do not use this skill when:
+
+* the answer is already in the repository
+* the missing information is noncritical
+* a safe reasonable assumption allows progress
+* the task is trivial
+* the user has already supplied the necessary information
+
+---
+
+# 2. Core Rule
+
+Use:
+
+```text
+DISCOVER FIRST
+ASK SECOND
+ASSUME THIRD
+```
+
+not:
+
+```text
+ASK FIRST
+```
+
+The agent should exhaust reasonable discovery before asking the user for project information.
+
+---
+
+# 3. Intake Process
+
+Start by identifying:
+
+```text
+WHAT MUST BE KNOWN
+```
+
+versus:
+
+```text
+WHAT WOULD ONLY BE NICE TO KNOW
+```
+
+Classify unknowns as:
+
+```text
+CRITICAL
+
+USEFUL
+
+OPTIONAL
+```
+
+---
+
+# 4. Critical Information
+
+An unknown is CRITICAL when different answers would materially change:
+
+* architecture
+* security
+* data handling
+* implementation
+* compatibility
+* cost
+* deployment
+* irreversible behavior
+* requested output
+
+Example:
+
+```text
+"What database engine does this application use?"
+```
+
+may be critical for a database migration.
+
+---
+
+# 5. Useful Information
+
+Useful information improves the result but does not prevent safe progress.
+
+Example:
+
+```text
+"Do you prefer tabs or spaces?"
+```
+
+If the project already has a style, discover it.
+
+If not, follow a reasonable convention.
+
+Do not block the task.
+
+---
+
+# 6. Optional Information
+
+Optional information should rarely be asked.
+
+Example:
+
+```text
+"What color would you like comments to be?"
+```
+
+when formatting has no effect on the requested outcome.
+
+Do not create unnecessary interaction.
+
+---
+
+# 7. Discovery Before Questions
+
+Search available evidence.
+
+Possible sources:
+
+```text
+AGENTS.md
+
+CLAUDE.md
+
+README
+
+configuration files
+
+package manifests
+
+project files
+
+source code
+
+tests
+
+database configuration
+
+deployment scripts
+
+existing examples
+
+documentation
+```
+
+If the repository answers the question, use the repository.
+
+---
+
+# 8. Question Quality
+
+Ask precise questions.
+
+Avoid:
+
+```text
+"Tell me more about the project."
+```
+
+Prefer:
+
+```text
+"Should this endpoint preserve the existing Windows Authentication model, or is anonymous access required?"
+```
+
+A good question should clearly affect a decision.
+
+---
+
+# 9. Limit Question Count
+
+Prefer:
+
+```text
+1–4 targeted questions
+```
+
+over:
+
+```text
+10–20 question questionnaire
+```
+
+If several questions depend on the answer to one earlier question, ask the first question only.
+
+---
+
+# 10. Progressive Intake
+
+Use:
+
+```text
+QUESTION
+   ↓
+ANSWER
+   ↓
+DO WE NOW HAVE ENOUGH?
+   /       \
+ YES        NO
+ ↓           ↓
+PROCEED    NEXT QUESTION
+```
+
+Do not collect unnecessary information in advance.
+
+---
+
+# 11. Safe Assumptions
+
+An assumption may be used when:
+
+```text
+the risk is low
+
+the assumption follows existing project conventions
+
+the decision is reversible
+
+the user can easily correct it
+```
+
+State important assumptions.
+
+Example:
+
+```text
+I'll assume this should follow the same authentication pattern as the existing controllers.
+```
+
+Then proceed.
+
+---
+
+# 12. Unsafe Assumptions
+
+Do not silently assume:
+
+```text
+production database credentials
+
+destructive intent
+
+security permissions
+
+authentication changes
+
+data-loss tolerance
+
+deployment targets
+
+legal/compliance requirements
+
+irreversible migration behavior
+```
+
+when the assumption materially affects risk.
+
+---
+
+# 13. Repository Discovery Example
+
+Task:
+
+```text
+Create a new API endpoint.
+```
+
+Unknown:
+
+```text
+What authentication does the project use?
+```
+
+Before asking:
+
+```text
+SEARCH existing endpoints
+
+INSPECT middleware/configuration
+
+INSPECT authentication configuration
+```
+
+If the answer is found:
+
+```text
+PROCEED
+```
+
+Do not ask the user.
+
+---
+
+# 14. Architecture Example
+
+Task:
+
+```text
+Design a caching layer.
+```
+
+Potential unknowns:
+
+```text
+single server or multiple servers?
+
+acceptable stale-data window?
+
+what data is being cached?
+
+existing cache technology?
+```
+
+First inspect:
+
+```text
+deployment configuration
+
+dependencies
+
+existing cache code
+```
+
+Ask only what remains critical.
+
+---
+
+# 15. Learning Example
+
+Task:
+
+```text
+Teach me Kubernetes.
+```
+
+Do not immediately produce a 30-day course.
+
+Ask a diagnostic question such as:
+
+```text
+Have you deployed containers with Docker before, or should we start with containers and images?
+```
+
+Then build from the response.
+
+---
+
+# 16. Decision Flow
+
+```text
+MISSING INFORMATION
+       ↓
+CAN IT BE DISCOVERED?
+      / \
+    YES  NO
+     ↓    ↓
+ DISCOVER  DOES IT CHANGE CORRECTNESS?
+             / \
+           YES  NO
+            ↓    ↓
+          ASK   ASSUME / IGNORE
+```
+
+---
+
+# 17. Output Contract
+
+The skill should produce one of two outcomes.
+
+## Outcome A — Enough Information Exists
+
+Produce:
+
+```text
+Resolved objective
+
+Known constraints
+
+Important assumptions
+
+Next action
+```
+
+Then continue the task.
+
+---
+
+## Outcome B — Critical Information Missing
+
+Ask only the minimal targeted questions required to proceed.
+
+---
+
+# 18. Anti-Pattern: Questionnaire Mode
+
+Avoid:
+
+```text
+What language?
+What framework?
+What database?
+What OS?
+What editor?
+What deployment method?
+What testing system?
+What coding style?
+What logging system?
+What version control?
+```
+
+when most of this could be discovered from the project.
+
+This wastes user attention.
+
+---
+
+# 19. Anti-Pattern: Fake Clarification
+
+Do not ask a question merely to appear careful.
+
+Example:
+
+User:
+
+```text
+Create a PowerShell command to list FSMO role holders.
+```
+
+Bad response:
+
+```text
+What Windows version are you using?
+```
+
+if the requested command is standard and does not depend materially on that detail.
+
+Proceed.
+
+---
+
+# 20. Anti-Pattern: Premature Assumption
+
+Task:
+
+```text
+Delete old database records.
+```
+
+Do not silently choose:
+
+```text
+older than 30 days
+```
+
+when no age threshold exists.
+
+That variable directly controls destructive behavior.
+
+Ask or discover it.
+
+---
+
+# 21. Completion Test
+
+Diagnostic intake is complete when every critical variable has been:
+
+```text
+DISCOVERED
+
+ANSWERED
+
+OR
+
+EXPLICITLY AND SAFELY ASSUMED
+```
+
+At that point stop asking questions and continue the work.
+
+---
+
+# 22. Self-Improvement
+
+Improve this skill when:
+
+* agents repeatedly ask unnecessary questions
+* agents repeatedly make dangerous assumptions
+* new discovery sources become available
+* a better critical/useful/optional distinction is found
+* repeated user feedback reveals poor question design
+
+Do not add project-specific intake questions here.
+
+Project-specific rules belong in project skills or documentation.
+
+---
+
+# 23. Changelog
+
+## 1.0.0
+
+Initial active version.
+
+Introduced:
+
+* discovery-first intake
+* critical/useful/optional classification
+* progressive questioning
+* safe assumption rules
+* question-count discipline
+* anti-questionnaire guidance

.ai/skills/prompt-architect/SKILL.md

@@ -0,0 +1,972 @@
+# Prompt Architect
+
+Version: 1.0.0
+Status: ACTIVE
+
+## Purpose
+
+Design reusable production prompts and agent instructions from a task's goals, inputs, constraints, workflow, failure modes, and expected outputs.
+
+This skill is for prompts that will be used repeatedly.
+
+The goal is not:
+
+```text
+WRITE A VERY LONG PROMPT
+```
+
+The goal is:
+
+```text
+BUILD THE SMALLEST RELIABLE INSTRUCTION SYSTEM
+```
+
+---
+
+# 1. Trigger Conditions
+
+Use this skill when:
+
+* a task will be repeated
+* a workflow needs standardization
+* several people or agents should perform a task consistently
+* the current prompt produces inconsistent results
+* a successful manual workflow should become reusable
+* building a specialized AI agent
+* creating project prompts
+* creating a reusable role
+* converting a procedure into agent instructions
+
+Do not create a permanent prompt for every one-time request.
+
+---
+
+# 2. Core Architecture
+
+A robust reusable prompt usually needs some combination of:
+
+```text
+ROLE
+
+OBJECTIVE
+
+INPUT CONTRACT
+
+CONTEXT
+
+PROCEDURE
+
+CONSTRAINTS
+
+TOOL RULES
+
+OUTPUT CONTRACT
+
+FAILURE HANDLING
+
+VERIFICATION
+```
+
+Not every prompt requires every section.
+
+Include only what materially improves behavior.
+
+---
+
+# 3. Start with the Task
+
+Define the task in one sentence.
+
+Example:
+
+```text
+Review an ASP Classic endpoint for security, correctness,
+maintainability, and consistency with the existing project.
+```
+
+If the task cannot be described clearly in one or two sentences, the prompt may be trying to do too many jobs.
+
+---
+
+# 4. Define the User
+
+Identify who consumes the result.
+
+Examples:
+
+```text
+developer
+
+system administrator
+
+manager
+
+student
+
+end user
+
+technical reviewer
+```
+
+Output quality often depends on the consumer.
+
+---
+
+# 5. Define Inputs
+
+Identify what the prompt will receive.
+
+Example:
+
+```text
+Required:
+
+- source file
+- project instructions
+- related configuration
+
+Optional:
+
+- error logs
+- test results
+```
+
+A reusable prompt should not depend on hidden context whenever avoidable.
+
+---
+
+# 6. Define Output
+
+Determine exactly what the prompt should produce.
+
+Weak:
+
+```text
+Review the code.
+```
+
+Better:
+
+```text
+Return:
+
+1. blocking findings
+2. important findings
+3. optional improvements
+4. verification recommendations
+
+For each finding include:
+- location
+- issue
+- why it matters
+- smallest recommended fix
+```
+
+Output contracts reduce ambiguity.
+
+---
+
+# 7. Separate Stable and Variable Information
+
+Stable information belongs in the reusable prompt.
+
+Variable information should become placeholders.
+
+Example:
+
+Stable:
+
+```text
+Review authentication, input validation, error handling,
+data access, and consistency with repository conventions.
+```
+
+Variable:
+
+```text
+{{TARGET_FILE}}
+{{PROJECT_CONTEXT}}
+{{USER_GOAL}}
+```
+
+Do not hard-code temporary details into reusable prompts.
+
+---
+
+# 8. Role
+
+Use a role when expertise or perspective materially changes the work.
+
+Good:
+
+```text
+Act as a senior application security reviewer
+for a legacy ASP Classic application.
+```
+
+Weak:
+
+```text
+You are the world's greatest genius programmer.
+```
+
+Roles should affect behavior, not inflate tone.
+
+---
+
+# 9. Objective
+
+State the actual outcome.
+
+Example:
+
+```text
+Identify realistic security defects and provide the
+smallest maintainable corrections without redesigning
+unrelated parts of the application.
+```
+
+This combines:
+
+```text
+GOAL
++
+SCOPE
++
+QUALITY BAR
+```
+
+---
+
+# 10. Context Contract
+
+Tell the agent which evidence matters.
+
+Example:
+
+```text
+Before reviewing the target file:
+
+1. read AGENTS.md
+2. inspect relevant authentication code
+3. inspect at least one analogous endpoint
+4. inspect the application's error-handling convention
+```
+
+This is stronger than giving generic advice.
+
+---
+
+# 11. Procedure
+
+Define observable steps.
+
+Example:
+
+```text
+1. inspect the target
+2. identify trust boundaries
+3. trace user-controlled inputs
+4. trace data access
+5. inspect output encoding
+6. identify findings
+7. verify findings against project conventions
+8. rank by severity
+```
+
+Do not require hidden chain-of-thought.
+
+Ask for operations that can be performed and verified.
+
+---
+
+# 12. Do Not Request Private Chain-of-Thought
+
+Avoid instructions such as:
+
+```text
+Show every reasoning step.
+
+Reveal your complete chain of thought.
+
+Think step by step and print everything.
+```
+
+Instead use:
+
+```text
+Inspect the evidence.
+
+Identify assumptions.
+
+Compare alternatives.
+
+State the chosen approach and concise rationale.
+
+Report verification evidence.
+```
+
+The workflow matters more than exposing internal reasoning.
+
+---
+
+# 13. Constraints
+
+Define explicit boundaries.
+
+Examples:
+
+```text
+Do not introduce a new framework.
+
+Do not change public URL behavior.
+
+Do not replace parameterized SQL with string concatenation.
+
+Do not modify unrelated files.
+
+Do not invent APIs not present in the repository.
+```
+
+Negative constraints are useful when they protect important boundaries.
+
+---
+
+# 14. Avoid Giant Ban Lists
+
+Do not add dozens of arbitrary negative rules unless evidence shows they are needed.
+
+Too many constraints can create:
+
+```text
+conflicts
+
+instruction dilution
+
+unexpected refusal
+
+poor prioritization
+```
+
+Prefer high-value constraints.
+
+---
+
+# 15. Tool Rules
+
+If tools are available, specify when they matter.
+
+Example:
+
+```text
+Search the repository before claiming a class does not exist.
+
+Run the build after code changes.
+
+Inspect the diff before completion.
+```
+
+Do not describe every possible tool call.
+
+Define behavioral rules.
+
+---
+
+# 16. Verification
+
+A reusable prompt should define success.
+
+Examples:
+
+```text
+Run existing tests.
+
+Validate generated JSON.
+
+Compare imported and expected row counts.
+
+Check all referenced files exist.
+
+Verify commands against the target environment.
+```
+
+Prompt outputs are stronger when verification is part of the task.
+
+---
+
+# 17. Failure Handling
+
+Define what should happen when the task cannot proceed normally.
+
+Example:
+
+```text
+If a critical project fact cannot be discovered,
+ask only the minimum targeted question needed.
+
+If testing cannot be performed,
+state exactly what remains unverified.
+```
+
+This prevents silent guessing.
+
+---
+
+# 18. Interaction Mode
+
+Specify whether the task should be:
+
+```text
+AUTONOMOUS
+
+INTERACTIVE
+
+SOCRATIC
+
+REVIEW-ONLY
+```
+
+Example:
+
+```text
+For learning:
+one concept → one drill → wait.
+
+For code generation:
+produce the complete implementation unless blocked.
+```
+
+Choosing the wrong interaction mode is a common prompt failure.
+
+---
+
+# 19. Persona Design
+
+For reviewer or adversarial prompts, define incentives rather than simply saying:
+
+```text
+Be critical.
+```
+
+Better:
+
+```text
+You are the operations engineer responsible for recovering this deployment at 2 AM.
+
+Your primary concern is recoverability.
+
+Treat any irreversible step without rollback as high risk.
+```
+
+This creates realistic scrutiny.
+
+---
+
+# 20. Prompt Skeleton
+
+A general reusable structure:
+
+```text
+# Role
+
+[Relevant expertise/perspective]
+
+# Objective
+
+[Exact task outcome]
+
+# Inputs
+
+[Required and optional inputs]
+
+# Context
+
+[What must be inspected or understood]
+
+# Procedure
+
+1. [...]
+2. [...]
+3. [...]
+
+# Constraints
+
+- [...]
+- [...]
+
+# Verification
+
+[How correctness is checked]
+
+# Failure Handling
+
+[What to do if blocked or uncertain]
+
+# Output
+
+[Exact expected structure]
+```
+
+---
+
+# 21. Test the Prompt
+
+Do not save an important reusable prompt without testing it.
+
+Test at least:
+
+```text
+NORMAL CASE
+
+INCOMPLETE CASE
+
+EDGE CASE
+```
+
+For high-impact prompts also test:
+
+```text
+ADVERSARIAL OR AMBIGUOUS CASE
+```
+
+---
+
+# 22. Normal Case Test
+
+Use realistic valid input.
+
+Ask:
+
+```text
+Did the prompt produce the intended structure?
+
+Did it follow project constraints?
+
+Was the output useful without manual repair?
+```
+
+---
+
+# 23. Incomplete Input Test
+
+Remove important but discoverable context.
+
+Check whether the prompt:
+
+```text
+discovers it
+
+asks a precise question
+
+or safely identifies what is missing
+```
+
+It should not hallucinate.
+
+---
+
+# 24. Edge Case Test
+
+Use unusual but valid input.
+
+Examples:
+
+```text
+empty dataset
+
+very large file
+
+legacy version
+
+missing optional field
+
+unusual directory structure
+```
+
+The goal is to expose brittle assumptions.
+
+---
+
+# 25. Ambiguity Test
+
+Give input that could be interpreted multiple ways.
+
+Check whether the prompt:
+
+```text
+discovers context
+
+asks a targeted question
+
+or states a safe assumption
+```
+
+rather than arbitrarily choosing.
+
+---
+
+# 26. Constraint Test
+
+Try to trigger behavior the prompt forbids.
+
+Example:
+
+If the prompt says:
+
+```text
+Do not introduce dependencies.
+```
+
+give it a task where adding a package is tempting.
+
+Verify that it respects the boundary.
+
+---
+
+# 27. Output Test
+
+Ensure the output contract is useful.
+
+Ask:
+
+```text
+Can another person or agent act directly on this output?
+```
+
+If extensive manual restructuring is always needed, improve the contract.
+
+---
+
+# 28. Prompt Refinement
+
+After failure:
+
+```text
+PRESERVE FAILED INPUT
+
+PRESERVE FAILED OUTPUT
+
+DIAGNOSE FAILURE
+
+MAKE SMALLEST CHANGE
+
+RERUN SAME TEST
+```
+
+Use:
+
+```text
+.ai/skills/prompt-debugger/SKILL.md
+```
+
+Do not rewrite everything immediately.
+
+---
+
+# 29. Prompt Versioning
+
+Useful production prompts should be versioned.
+
+Example:
+
+```text
+security-review_v1.0.md
+
+security-review_v1.1.md
+```
+
+Or track version inside the file.
+
+Version changes should reflect meaningful behavior changes.
+
+---
+
+# 30. Prompt Changelog
+
+For important prompts, note:
+
+```text
+what changed
+
+why
+
+what failed
+
+how the change was tested
+```
+
+Prompt evolution should be evidence-driven.
+
+---
+
+# 31. Extract Prompt from Successful Work
+
+A powerful creation method is:
+
+```text
+SUCCESSFUL TASK
+    ↓
+WHAT PROCEDURE PRODUCED IT?
+    ↓
+WHAT INPUTS MATTERED?
+    ↓
+WHAT BOUNDARIES MATTERED?
+    ↓
+GENERALIZE
+    ↓
+PROMPT
+```
+
+Use the reverse-engineer or skill-extractor skill when useful.
+
+---
+
+# 32. Prompt vs Skill Decision
+
+Create a prompt when:
+
+```text
+the primary need is a repeatable task launch or output format
+```
+
+Create a skill when:
+
+```text
+the primary need is a reusable operational procedure
+```
+
+Example:
+
+Prompt:
+
+```text
+Review this pull request.
+```
+
+Skill:
+
+```text
+How to conduct a security-focused code review.
+```
+
+A prompt may invoke a skill.
+
+---
+
+# 33. Prompt vs AGENTS.md
+
+Do not put every reusable prompt rule into `AGENTS.md`.
+
+Root instructions should define broad behavior.
+
+Task-specific behavior belongs in prompts or skills.
+
+---
+
+# 34. Prompt Composition
+
+Complex tasks may compose:
+
+```text
+ROOT INSTRUCTIONS
+     +
+PROJECT CONTEXT
+     +
+SKILL
+     +
+TASK PROMPT
+     +
+CURRENT INPUT
+```
+
+This is usually better than one giant permanent prompt.
+
+---
+
+# 35. Information Density
+
+Prefer precise instructions with high information value.
+
+Weak:
+
+```text
+Be thoughtful, careful, thorough, professional, excellent,
+detailed, accurate, helpful, expert, comprehensive.
+```
+
+Better:
+
+```text
+Identify blocking defects first.
+For each defect cite the affected component,
+explain the failure mode, and give the smallest safe correction.
+```
+
+Specific behavior beats adjectives.
+
+---
+
+# 36. Tone Constraints
+
+Tone rules should be operational.
+
+Example:
+
+```text
+Use direct language.
+
+Avoid unnecessary preamble.
+
+Do not use generic praise.
+
+Prefer concrete examples.
+```
+
+Avoid attempting to control every word.
+
+---
+
+# 37. Prompt Anti-Fluff
+
+When writing user-facing output, useful defaults include:
+
+```text
+start with the answer
+
+use active voice
+
+prefer concrete nouns and verbs
+
+remove redundant summary
+
+avoid generic corporate filler
+```
+
+For a final editing pass use:
+
+```text
+.ai/skills/coffee-chat-editor/SKILL.md
+```
+
+---
+
+# 38. Examples in Prompts
+
+Examples can strongly constrain behavior.
+
+Use examples when:
+
+```text
+format is unusual
+
+distinctions are subtle
+
+output keeps drifting
+
+failure cases are important
+```
+
+Avoid dozens of examples.
+
+One or two strong examples are often enough.
+
+---
+
+# 39. Few-Shot Pattern
+
+When examples are useful:
+
+```text
+INPUT EXAMPLE
+
+EXPECTED OUTPUT
+
+SECOND DIFFERENT INPUT
+
+EXPECTED OUTPUT
+```
+
+Ensure examples demonstrate the rule rather than accidentally hard-coding one domain case.
+
+---
+
+# 40. Self-Improvement
+
+Improve a reusable prompt when real use reveals:
+
+* recurring failure
+* repeated manual cleanup
+* missing constraints
+* poor interaction mode
+* weak verification
+* excessive output
+* insufficient project discovery
+* incorrect tool assumptions
+
+Capture evidence before permanent change.
+
+---
+
+# 41. Prompt Deprecation
+
+Retire a prompt when:
+
+```text
+its workflow is obsolete
+
+a skill replaces it
+
+a better prompt fully supersedes it
+
+technology changes
+
+it repeatedly causes worse outcomes
+```
+
+Do not maintain unused prompts indefinitely.
+
+---
+
+# 42. Output Contract for This Skill
+
+When using Prompt Architect, produce:
+
+```text
+PROMPT PURPOSE
+
+INPUT CONTRACT
+
+REUSABLE PROMPT
+
+TEST CASES
+
+EXPECTED BEHAVIOR
+
+KNOWN LIMITATIONS
+
+VERSION
+```
+
+For simple prompts, compress this.
+
+---
+
+# 43. Changelog
+
+## 1.0.0
+
+Initial active version.
+
+Introduced:
+
+* role/objective/context design
+* stable-vs-variable separation
+* observable procedures instead of exposed chain-of-thought
+* negative constraints
+* output contracts
+* failure handling
+* interaction modes
+* persona incentives
+* prompt testing
+* versioning
+* modular prompt composition

.ai/skills/skills/retrospective/SKILL.md

@@ -0,0 +1,781 @@
+# Retrospective
+
+Version: 1.0.0
+Status: ACTIVE
+
+## Purpose
+
+Review completed work to identify durable lessons, process weaknesses, successful techniques, and possible AI-system improvements.
+
+The retrospective answers:
+
+```text id="rgm7wl"
+What did this task teach us that might make future work better?
+```
+
+It is intentionally lightweight.
+
+The goal is learning, not bureaucracy.
+
+---
+
+# 1. Trigger Conditions
+
+Use this skill after:
+
+* substantial debugging
+* architecture work
+* significant feature implementation
+* deployment
+* database migration
+* unusual operational incident
+* repeated failed attempts
+* complex integration
+* a task where the user corrected the process
+* work that clearly revealed a reusable procedure
+
+Do not perform a formal retrospective after every trivial change.
+
+---
+
+# 2. Core Loop
+
+```text id="58l91x"
+TASK
+   ↓
+RESULT
+   ↓
+WHAT HAPPENED?
+   ↓
+WHAT DID WE LEARN?
+   ↓
+IS IT REUSABLE?
+   ↓
+CHANGE PROCESS IF JUSTIFIED
+```
+
+---
+
+# 3. First Question — Did It Work?
+
+Determine:
+
+```text id="mp9n3l"
+Was the requested outcome achieved?
+```
+
+Possible:
+
+```text id="zdijj2"
+YES
+
+PARTIALLY
+
+NO
+```
+
+Do not discuss process improvement while hiding an incomplete result.
+
+---
+
+# 4. What Worked?
+
+Identify procedures that helped.
+
+Examples:
+
+```text id="w4q87q"
+searching analogous code first
+
+running a targeted test before full suite
+
+using a staging table
+
+creating rollback before deployment
+
+testing connectivity before changing configuration
+```
+
+Successful behavior may be reusable.
+
+---
+
+# 5. What Failed?
+
+Identify:
+
+```text id="348o7o"
+failed assumption
+
+failed command
+
+failed design
+
+failed verification
+
+failed prompt
+
+failed interaction
+```
+
+Be specific.
+
+Weak:
+
+```text id="x6ro6g"
+There were some issues.
+```
+
+Better:
+
+```text id="gkrbq7"
+The deployment failed because files remained locked
+after the application pool stop completed.
+```
+
+---
+
+# 6. Wrong Assumptions
+
+Ask:
+
+```text id="3q5v2c"
+What did we believe that turned out to be false?
+```
+
+Examples:
+
+```text id="2iv9a6"
+service stop releases every file lock
+
+CSV always has a header
+
+API retry is harmless
+
+database values are all numeric
+
+test environment matches production
+```
+
+Wrong assumptions often become useful future checks.
+
+---
+
+# 7. Missing Information
+
+Ask:
+
+```text id="kmrdy2"
+What information would have made the task easier or safer?
+```
+
+Then ask:
+
+```text id="ff9e41"
+Could the agent have discovered it earlier?
+```
+
+If yes, improve discovery.
+
+If no, consider whether Diagnostic Intake should have asked for it.
+
+---
+
+# 8. Verification Effectiveness
+
+Ask:
+
+```text id="jaz043"
+What verification caught the problem?
+```
+
+Then:
+
+```text id="vnd37i"
+Could an earlier or cheaper verification step have caught it sooner?
+```
+
+This is a strong source of process improvement.
+
+---
+
+# 9. Debugging Efficiency
+
+For debugging tasks:
+
+```text id="c4wz8x"
+Which test reduced uncertainty the most?
+
+Which step was wasted?
+
+Did we make speculative changes?
+
+Could we have isolated the layer earlier?
+```
+
+The goal is better diagnostic sequencing.
+
+---
+
+# 10. User Corrections
+
+Review meaningful user corrections.
+
+Ask:
+
+```text id="dmkixc"
+Was this correction:
+
+task-specific?
+
+project-specific?
+
+a durable workflow preference?
+
+a general agent rule?
+```
+
+Do not overgeneralize.
+
+---
+
+# 11. Repeated Friction
+
+Look for:
+
+```text id="mkyd7q"
+manual repeated steps
+
+repeated questions
+
+repeated setup
+
+repeated validation
+
+repeated cleanup
+
+repeated prompt repair
+```
+
+These may indicate:
+
+```text id="66x57i"
+SKILL
+
+AUTOMATION
+
+TEMPLATE
+
+PROMPT
+
+DOCUMENTATION
+```
+
+---
+
+# 12. Reusable Success
+
+Ask:
+
+```text id="tsg0z4"
+Did we discover a procedure worth deliberately repeating?
+```
+
+If yes:
+
+```text id="h7ts5n"
+capture it
+```
+
+even if nothing failed.
+
+The system should learn from success.
+
+---
+
+# 13. Reusable Failure Prevention
+
+Ask:
+
+```text id="w5gbwk"
+Could a simple future check prevent this failure?
+```
+
+Examples:
+
+```text id="7ko948"
+validate encoding first
+
+check free disk space
+
+test database connection
+
+compare expected/imported counts
+
+check duplicate key
+
+verify service account permission
+```
+
+Prefer prevention over documenting complicated recovery when possible.
+
+---
+
+# 14. Classification
+
+Classify each meaningful lesson.
+
+```text id="7xszjn"
+NO PERMANENT CHANGE
+
+LEARNING ENTRY
+
+PROJECT DOCUMENTATION
+
+EXISTING SKILL UPDATE
+
+NEW SKILL
+
+PROMPT UPDATE
+
+NEW PROMPT
+
+TEMPLATE
+
+AGENTS.md
+
+CLAUDE.md
+
+AUTOMATED TEST
+
+SCRIPT / AUTOMATION
+```
+
+Use the narrowest correct destination.
+
+---
+
+# 15. No Permanent Change
+
+This is a valid and common result.
+
+Use when:
+
+```text id="zbxtlo"
+incident was one-off
+
+existing process already addresses it
+
+lesson is too weak
+
+change would create unnecessary complexity
+```
+
+Do not manufacture self-improvement.
+
+---
+
+# 16. Learning Entry
+
+If the observation is promising but not sufficiently proven, add:
+
+```text id="w3vpja"
+.ai/state/LEARNINGS.md
+```
+
+Do not promote it yet.
+
+---
+
+# 17. Project Documentation
+
+Use when the lesson is project truth.
+
+Example:
+
+```text id="k36g9j"
+This application must run under a specific IIS App Pool.
+```
+
+That belongs in deployment/project documentation, not a generic skill.
+
+---
+
+# 18. Existing Skill Update
+
+Use when:
+
+```text id="f3du83"
+a skill already owns the workflow
+
+AND
+
+the task revealed a missing or weak step
+```
+
+Prefer updating the skill over creating a duplicate.
+
+---
+
+# 19. New Skill
+
+Use:
+
+```text id="76d1l5"
+.ai/skills/skill-extractor/SKILL.md
+```
+
+when a reusable procedure lacks an owner.
+
+Do not create the skill directly from a weak retrospective observation.
+
+---
+
+# 20. Prompt Update
+
+Use when the failure came from how an AI task was framed.
+
+Use:
+
+```text id="vgwecw"
+.ai/skills/prompt-debugger/SKILL.md
+```
+
+before changing important prompts.
+
+---
+
+# 21. Automated Test
+
+A repeated defect may be best prevented with a test rather than an instruction.
+
+Ask:
+
+```text id="h1x96z"
+Can the machine catch this automatically?
+```
+
+If yes, automation is often better than asking the agent to remember.
+
+---
+
+# 22. Automation
+
+Repeated deterministic manual work may become a script.
+
+Examples:
+
+```text id="xiqa6n"
+validation script
+
+deployment preflight
+
+schema checker
+
+file comparison
+
+health check
+```
+
+A process improvement does not have to be another prompt.
+
+---
+
+# 23. Impact Test
+
+Before promoting a lesson, ask:
+
+```text id="4ymuvw"
+How often could this recur?
+
+What is the cost of recurrence?
+
+How much effort does prevention add?
+```
+
+Prioritize:
+
+```text id="mdczl2"
+HIGH FREQUENCY
+
+HIGH CONSEQUENCE
+
+LOW-COST PREVENTION
+```
+
+---
+
+# 24. Simplicity Test
+
+Ask:
+
+```text id="09twf4"
+Is the proposed improvement simpler than the repeated problem it prevents?
+```
+
+A complex control for a rare trivial error may not be worthwhile.
+
+---
+
+# 25. Retrospective Output
+
+A lightweight retrospective may contain:
+
+```text id="j1phbx"
+RESULT
+
+WHAT WORKED
+
+WHAT FAILED
+
+KEY LESSON
+
+REUSABLE?
+
+ACTION
+```
+
+For simple tasks, this may be only a few lines internally.
+
+---
+
+# 26. Example — Deployment
+
+Result:
+
+```text id="e3ucy5"
+successful after retry
+```
+
+Worked:
+
+```text id="xyv3o1"
+backup and health check
+```
+
+Failed:
+
+```text id="9s2slu"
+application pool stop did not release all file locks
+```
+
+Lesson:
+
+```text id="0y919r"
+deployment preflight should test whether target files can actually be replaced
+```
+
+Action:
+
+```text id="mj0bom"
+update iis-deployment skill
+```
+
+---
+
+# 27. Example — Database Import
+
+Result:
+
+```text id="3gorsd"
+import completed
+```
+
+Problem:
+
+```text id="5vl0k4"
+command returned success even though rows were rejected
+```
+
+Lesson:
+
+```text id="bwwfbo"
+command status alone does not verify data-import completeness
+```
+
+Action:
+
+```text id="pzogw1"
+add expected/imported/rejected row-count verification
+```
+
+---
+
+# 28. Example — Prompt Failure
+
+Result:
+
+```text id="a29v73"
+user had to answer eight unnecessary questions
+```
+
+Cause:
+
+```text id="jdbees"
+prompt asked for broad intake before repository discovery
+```
+
+Lesson:
+
+```text id="qjtv1u"
+discover first, then ask only undiscoverable critical questions
+```
+
+Action:
+
+```text id="kj46v9"
+prompt-debugger + diagnostic-intake review
+```
+
+---
+
+# 29. Example — No Change
+
+Task:
+
+```text id="367loc"
+fix spelling error
+```
+
+Result:
+
+```text id="eedqmj"
+success
+```
+
+Lesson:
+
+```text id="i0eu4b"
+none
+```
+
+Action:
+
+```text id="za6ao7"
+NO PERMANENT CHANGE
+```
+
+This is correct.
+
+---
+
+# 30. Avoid Retrospective Inflation
+
+Do not turn every task into:
+
+```text id="2r4vg3"
+meeting notes
+
+postmortem
+
+five new skills
+
+ten changelog entries
+```
+
+Self-improvement should reduce future work, not create a maintenance tax.
+
+---
+
+# 31. Capture Evidence
+
+When a lesson is promoted, preserve:
+
+```text id="fzkbyv"
+what happened
+
+why it mattered
+
+where the improvement went
+
+how it was tested
+```
+
+This supports future rollback.
+
+---
+
+# 32. Reuse Feedback
+
+When a previous learning is reused, update:
+
+```text id="hlmd6v"
+.ai/state/LEARNINGS.md
+```
+
+if appropriate.
+
+Record:
+
+```text id="fj3wkw"
+Did it help?
+
+Did it prevent the original problem?
+
+Did it create new friction?
+```
+
+This closes the learning loop.
+
+---
+
+# 33. Repeated Retrospective Pattern
+
+If several retrospectives produce related lessons:
+
+```text id="hh9eqw"
+MERGE THEM
+```
+
+Example:
+
+```text id="mx0jcx"
+file locks during deployment
+
+partial copy during deployment
+
+health check missing during deployment
+```
+
+may collectively justify:
+
+```text id="og2ap0"
+iis-deployment skill
+```
+
+rather than three tiny rules.
+
+---
+
+# 34. Self-Improvement
+
+Improve this skill when:
+
+* retrospectives create too much overhead
+* meaningful lessons are missed
+* too many weak lessons are promoted
+* the same classifications are confusing
+* learning feedback is not being reused
+
+The retrospective should remain lightweight.
+
+---
+
+# 35. Changelog
+
+## 1.0.0
+
+Initial active version.
+
+Introduced:
+
+* success/failure review
+* assumption review
+* verification review
+* user-correction classification
+* repeated-friction analysis
+* reusable success capture
+* action classification
+* impact and simplicity tests
+* no-change outcome
+* reuse feedback loop

.ai/state/LEARNINGS.md

@@ -0,0 +1,835 @@
+# Learning Ledger
+
+Version: 1.0.0
+
+## Purpose
+
+This file stores **candidate reusable lessons** discovered during real project work.
+
+It sits between:
+
+```text
+OBSERVATION
+```
+
+and:
+
+```text
+PERMANENT AI-SYSTEM CHANGE
+```
+
+Not every observation should become:
+
+* a new rule
+* a new skill
+* a new prompt
+* an `AGENTS.md` update
+
+The learning ledger allows evidence to accumulate first.
+
+---
+
+# 1. Core Principle
+
+Use:
+
+```text
+OBSERVE
+   ↓
+CAPTURE
+   ↓
+REUSE / REPEAT?
+   ↓
+PROMOTE
+```
+
+instead of:
+
+```text
+OBSERVE
+   ↓
+IMMEDIATELY ADD PERMANENT RULE
+```
+
+This prevents instruction bloat.
+
+---
+
+# 2. What Belongs Here
+
+Capture a learning candidate when real work reveals:
+
+* repeated friction
+* repeated user correction
+* repeated implementation failure
+* repeated debugging procedure
+* a strong reusable solution
+* missing verification
+* missing project guidance
+* a useful architectural convention
+* an effective prompt technique
+* a recurring tool problem
+* an obsolete instruction
+* a reusable automation opportunity
+
+---
+
+# 3. What Does Not Belong Here
+
+Do not record:
+
+* ordinary typos
+* one-off syntax mistakes
+* transient task context
+* temporary file names
+* facts already documented elsewhere
+* generic observations with no action
+* every successful command
+* every minor correction
+
+The ledger should contain signal.
+
+---
+
+# 4. Learning Entry Template
+
+Copy this template for each candidate.
+
+```text
+---
+
+## YYYY-MM-DD — Short Descriptive Title
+
+### Observed During
+
+Describe the task or project context.
+
+### Evidence
+
+What actually happened?
+
+Include evidence such as:
+
+- repeated error
+- user correction
+- failed test
+- successful repeated method
+- manual workaround
+- project convention
+
+### Candidate Lesson
+
+State the possible reusable lesson in one or two clear sentences.
+
+### Scope
+
+Choose one:
+
+- GLOBAL AGENT
+- MODEL-SPECIFIC
+- PROJECT-SPECIFIC
+- SKILL-SPECIFIC
+- PROMPT-SPECIFIC
+- TEMPLATE
+- AUTOMATION
+- PROJECT DOCUMENTATION
+- UNKNOWN
+
+### Candidate Destination
+
+Examples:
+
+AGENTS.md
+
+CLAUDE.md
+
+.ai/skills/existing-skill/SKILL.md
+
+.ai/skills/new-skill/SKILL.md
+
+.ai/prompts/example.md
+
+.ai/templates/example.md
+
+project documentation
+
+none
+
+### Confidence
+
+LOW
+
+MEDIUM
+
+HIGH
+
+### Repetition Count
+
+1
+
+Increase when the same lesson appears again.
+
+### Action
+
+PENDING
+
+PROMOTED
+
+REJECTED
+
+REVISIT
+
+### Promotion Reason
+
+Complete only if promoted.
+
+### Result After Reuse
+
+What happened when the promoted improvement was used again?
+
+### Related Changelog
+
+Version or changelog entry, if applicable.
+
+---
+```
+
+---
+
+# 5. Confidence Guidelines
+
+## LOW
+
+Use when:
+
+```text
+one incident
+
+uncertain cause
+
+weak evidence
+
+possible coincidence
+```
+
+Do not usually promote a LOW-confidence lesson.
+
+---
+
+## MEDIUM
+
+Use when:
+
+```text
+pattern appeared more than once
+
+cause is reasonably understood
+
+lesson appears reusable
+```
+
+A MEDIUM lesson may justify a small skill or prompt improvement.
+
+---
+
+## HIGH
+
+Use when:
+
+```text
+repeated evidence
+
+clear user correction
+
+reproducible failure
+
+verified project convention
+
+successful repeated procedure
+```
+
+HIGH-confidence lessons are strong candidates for promotion.
+
+---
+
+# 6. Repetition Count
+
+Repetition count tracks how often the pattern appears.
+
+Example:
+
+```text
+Repetition Count: 1
+```
+
+Later:
+
+```text
+Repetition Count: 2
+```
+
+Then:
+
+```text
+Repetition Count: 4
+```
+
+Repeated evidence increases confidence.
+
+Do not treat repetition count as the only criterion.
+
+One serious verified failure may justify immediate action.
+
+---
+
+# 7. Promotion Decision
+
+Before promoting a learning, check:
+
+```text
+Is it reusable?
+
+Is the cause understood?
+
+Is the lesson actionable?
+
+Does it already exist elsewhere?
+
+Is the proposed destination correct?
+
+Can we test the improvement?
+
+Could the change create broader problems?
+```
+
+If not, leave it pending.
+
+---
+
+# 8. Promotion Destinations
+
+## AGENTS.md
+
+Use when the lesson applies to:
+
+```text
+most agents
+
+most tasks
+
+repository-wide agent behavior
+```
+
+Example:
+
+```text
+Always inspect existing database migration scripts before designing a new migration.
+```
+
+---
+
+## CLAUDE.md
+
+Use when the lesson specifically concerns Claude behavior.
+
+Example:
+
+```text
+Claude should inspect the diff after broad search-and-replace edits.
+```
+
+---
+
+## Existing Skill
+
+Prefer this when the lesson extends an existing procedure.
+
+Example:
+
+```text
+mirror-audit should check service-account permissions during deployment reviews.
+```
+
+---
+
+## New Skill
+
+Create only when:
+
+```text
+procedure is reusable
+
+trigger is recognizable
+
+workflow is substantial enough
+
+existing skills do not own it
+```
+
+---
+
+## Prompt
+
+Use when the lesson concerns launching or structuring a repeated interaction.
+
+---
+
+## Template
+
+Use when the reusable asset is primarily structural.
+
+---
+
+## Project Documentation
+
+Use when the lesson is a project fact.
+
+Example:
+
+```text
+Production deployments must target IIS App Pool ScheduliciousPool.
+```
+
+That is not a general agent rule.
+
+---
+
+# 9. Rejection
+
+Reject candidate learning when:
+
+```text
+it was a one-off incident
+
+the original diagnosis was wrong
+
+it duplicates existing guidance
+
+it creates more process than value
+
+the project changed
+
+testing shows the proposed improvement is worse
+```
+
+Do not delete the entry immediately.
+
+A rejected lesson can provide useful historical context.
+
+Mark:
+
+```text
+Action: REJECTED
+```
+
+and explain why.
+
+---
+
+# 10. Example: Repeated Project Pattern
+
+## YYYY-MM-DD — ASP controllers require consistent initialization
+
+### Observed During
+
+Several Classic ASP controller implementations.
+
+### Evidence
+
+Four controllers required the same initialization sequence:
+
+1. validate request
+2. initialize model/service
+3. handle initialization error
+4. execute action
+5. return normalized response
+
+### Candidate Lesson
+
+Controller creation follows a stable reusable project pattern and should not be rediscovered each time.
+
+### Scope
+
+PROJECT-SPECIFIC
+
+### Candidate Destination
+
+```text
+.ai/skills/classic-asp-controller/SKILL.md
+```
+
+### Confidence
+
+HIGH
+
+### Repetition Count
+
+4
+
+### Action
+
+PROMOTED
+
+### Promotion Reason
+
+The procedure occurred repeatedly and has a clear input/process/output structure.
+
+### Result After Reuse
+
+Pending.
+
+---
+
+# 11. Example: Bad Candidate
+
+## YYYY-MM-DD — Missing semicolon
+
+### Observed During
+
+JavaScript edit.
+
+### Evidence
+
+A semicolon was accidentally omitted.
+
+### Candidate Lesson
+
+Agents should remember semicolons.
+
+### Confidence
+
+LOW
+
+### Repetition Count
+
+1
+
+### Action
+
+REJECTED
+
+### Reason
+
+Ordinary isolated coding mistake. Existing syntax checking already handles this.
+
+---
+
+# 12. Example: Verification Improvement
+
+## YYYY-MM-DD — Import status needs row-count verification
+
+### Observed During
+
+Automated CSV import into Access.
+
+### Evidence
+
+The import command returned successfully even when some records were rejected.
+
+### Candidate Lesson
+
+Successful command completion is insufficient verification for data imports.
+
+Imports should compare:
+
+```text
+expected rows
+
+imported rows
+
+rejected rows
+```
+
+### Scope
+
+SKILL-SPECIFIC
+
+### Candidate Destination
+
+```text
+.ai/skills/access-csv-import/SKILL.md
+```
+
+### Confidence
+
+HIGH
+
+### Repetition Count
+
+2
+
+### Action
+
+PENDING
+
+---
+
+# 13. Example: Prompt Failure
+
+## YYYY-MM-DD — Planning prompt overproduces detail
+
+### Observed During
+
+Several small bug fixes.
+
+### Evidence
+
+The planning prompt generated long multi-section plans for changes involving one or two lines.
+
+### Candidate Lesson
+
+Planning depth should scale with task complexity.
+
+### Scope
+
+PROMPT-SPECIFIC
+
+### Candidate Destination
+
+```text
+.ai/prompts/plan.md
+```
+
+### Confidence
+
+HIGH
+
+### Repetition Count
+
+3
+
+### Action
+
+PROMOTED
+
+---
+
+# 14. Example: Model-Specific Behavior
+
+## YYYY-MM-DD — Claude loads too many unrelated files
+
+### Observed During
+
+Large repository investigation.
+
+### Evidence
+
+Claude read broad directories despite the target subsystem being known.
+
+### Candidate Lesson
+
+Claude should search first and expand file context incrementally.
+
+### Scope
+
+MODEL-SPECIFIC
+
+### Candidate Destination
+
+```text
+CLAUDE.md
+```
+
+### Confidence
+
+MEDIUM
+
+### Repetition Count
+
+2
+
+### Action
+
+PROMOTED
+
+---
+
+# 15. Periodic Review
+
+Periodically review PENDING entries.
+
+For each entry decide:
+
+```text
+PROMOTE
+
+KEEP PENDING
+
+REJECT
+
+MERGE WITH ANOTHER LEARNING
+```
+
+Look especially for several related entries that should become one generalized skill.
+
+---
+
+# 16. Merge Related Learning
+
+Suppose the ledger contains:
+
+```text
+PowerShell deployment failed because service wasn't stopped.
+
+PowerShell deployment failed because App Pool was locked.
+
+PowerShell deployment failed because files were still in use.
+```
+
+Instead of three skills, generalize:
+
+```text
+Safe Windows Application Deployment
+```
+
+with:
+
+```text
+pre-deployment checks
+
+service/app-pool handling
+
+file lock checks
+
+deployment
+
+restart
+
+health verification
+
+rollback
+```
+
+The generalized procedure is the useful asset.
+
+---
+
+# 17. Learning from Success
+
+Do not capture only failures.
+
+Useful successful observations include:
+
+```text
+"This audit consistently catches migration problems."
+
+"This three-step debugging process isolated the issue quickly."
+
+"This template produces reliable project updates."
+
+"This deployment validation catches configuration drift."
+```
+
+These can become:
+
+* skills
+* prompts
+* templates
+* tests
+
+Success is training data for the AI-OS.
+
+---
+
+# 18. Learning from User Corrections
+
+User corrections are high-value signals.
+
+If the user repeatedly says:
+
+```text
+"Don't use React in this project."
+
+"Always use parameterized ADODB commands."
+
+"Each street needs its own worksheet."
+
+"Do not rewrite the whole file."
+```
+
+determine whether the correction represents:
+
+```text
+task-specific instruction
+
+project rule
+
+persistent workflow preference
+
+general agent improvement
+```
+
+Store it in the narrowest correct location.
+
+---
+
+# 19. Do Not Infer Too Much
+
+A single correction does not automatically imply a universal rule.
+
+Example:
+
+```text
+User:
+"Don't use React for this application."
+```
+
+Do not infer:
+
+```text
+"User never wants React anywhere."
+```
+
+Instead record the project-specific constraint if relevant.
+
+---
+
+# 20. Learning Promotion Workflow
+
+```text
+REAL WORK
+   ↓
+OBSERVATION
+   ↓
+LEARNING ENTRY
+   ↓
+MORE EVIDENCE?
+   ↓
+GENERALIZE
+   ↓
+CHOOSE DESTINATION
+   ↓
+MODIFY AI-OS
+   ↓
+SYSTEM AUDIT
+   ↓
+TEST
+   ↓
+CHANGELOG
+   ↓
+MARK PROMOTED
+```
+
+---
+
+# 21. Ledger Hygiene
+
+Keep this file useful.
+
+Periodically:
+
+* merge duplicate entries
+* reject weak stale candidates
+* mark promoted lessons
+* update reuse results
+* remove truly obsolete noise
+
+Do not turn the ledger into an endless event log.
+
+---
+
+# 22. Initial State
+
+No project-specific learning has been recorded yet.
+
+The first entries should come from real project work.

.ai/templates/SKILL_TEMPLATE.md,

@@ -0,0 +1,555 @@
+# [Skill Name]
+
+Version: 0.1.0
+Status: CANDIDATE
+
+## Purpose
+
+Describe the reusable job this skill performs.
+
+A good purpose answers:
+
+```text
+What class of problem does this skill solve?
+```
+
+Keep the purpose specific.
+
+Avoid vague purposes such as:
+
+```text
+"Help with development."
+```
+
+Prefer:
+
+```text
+"Safely import delimited text files into Microsoft Access while validating schema, row counts, errors, and rollback conditions."
+```
+
+---
+
+# 1. Trigger Conditions
+
+Use this skill when:
+
+* [trigger]
+* [trigger]
+* [trigger]
+
+Do not use this skill when:
+
+* [non-trigger]
+* [non-trigger]
+
+Trigger conditions should make it obvious when an agent should load the skill.
+
+---
+
+# 2. Inputs
+
+Required inputs:
+
+```text
+INPUT 1:
+Description
+
+INPUT 2:
+Description
+```
+
+Optional inputs:
+
+```text
+OPTIONAL INPUT 1:
+Description
+```
+
+If an input can be discovered from the project, inspect the project before asking the user.
+
+---
+
+# 3. Preconditions
+
+Before executing this skill, verify:
+
+```text
+[ ] required inputs exist
+
+[ ] relevant project instructions have been read
+
+[ ] required tools or dependencies are available
+
+[ ] destructive actions have appropriate safeguards
+
+[ ] assumptions are documented
+```
+
+Add domain-specific preconditions when necessary.
+
+---
+
+# 4. Output Contract
+
+The skill should produce:
+
+```text
+OUTPUT 1
+
+OUTPUT 2
+
+OUTPUT 3
+```
+
+Define what success looks like.
+
+Avoid vague output descriptions such as:
+
+```text
+"Provide a good solution."
+```
+
+Prefer:
+
+```text
+"Produce a verified PowerShell script, list required permissions, provide rollback steps, and report the exact verification commands used."
+```
+
+---
+
+# 5. Procedure
+
+Follow this process.
+
+## Step 1 — Discover
+
+Inspect:
+
+* relevant files
+* existing implementations
+* configuration
+* dependencies
+* tests
+* documentation
+
+Do not assume project facts that can be discovered.
+
+---
+
+## Step 2 — Understand
+
+Identify:
+
+```text
+OBJECTIVE
+
+CURRENT STATE
+
+DESIRED STATE
+
+CONSTRAINTS
+
+DEPENDENCIES
+
+RISKS
+```
+
+---
+
+## Step 3 — Execute
+
+Describe the reusable procedure.
+
+Example:
+
+```text
+1. validate input
+2. inspect destination
+3. prepare change
+4. execute change
+5. capture result
+6. verify
+```
+
+Keep steps concrete and executable.
+
+---
+
+## Step 4 — Verify
+
+Define verification methods.
+
+Prefer:
+
+```text
+automated test
+
+build
+
+static analysis
+
+query
+
+command output
+
+row-count comparison
+
+smoke test
+
+direct inspection
+```
+
+A skill without verification is incomplete.
+
+---
+
+## Step 5 — Handle Failure
+
+If verification fails:
+
+```text
+STOP
+
+CAPTURE ERROR
+
+IDENTIFY FAILURE POINT
+
+DIAGNOSE
+
+CORRECT ROOT CAUSE
+
+RETRY VERIFICATION
+```
+
+Do not continue as though the operation succeeded.
+
+---
+
+# 6. Decision Rules
+
+Add decision rules when the procedure contains branches.
+
+Example:
+
+```text
+IF destination exists
+    inspect compatibility
+
+IF destination does not exist
+    create it
+
+IF schema differs
+    stop and reconcile mapping
+
+IF import errors occur
+    capture rejected rows
+```
+
+Prefer explicit decisions over vague instructions.
+
+---
+
+# 7. Safety Rules
+
+Document any important safety boundaries.
+
+Examples:
+
+```text
+do not delete source data before verification
+
+do not overwrite production configuration without backup
+
+do not log secrets
+
+do not disable security controls to make a procedure work
+
+do not perform destructive migration without rollback
+```
+
+Remove this section if the skill has no meaningful safety considerations.
+
+---
+
+# 8. Failure Handling
+
+Known failure classes:
+
+## Failure Type 1
+
+Symptoms:
+
+```text
+...
+```
+
+Likely cause:
+
+```text
+...
+```
+
+Response:
+
+```text
+...
+```
+
+---
+
+## Failure Type 2
+
+Symptoms:
+
+```text
+...
+```
+
+Likely cause:
+
+```text
+...
+```
+
+Response:
+
+```text
+...
+```
+
+Do not attempt to list every theoretical failure.
+
+Document recurring or high-impact failures.
+
+---
+
+# 9. Verification Checklist
+
+Before considering this skill complete:
+
+```text
+[ ] required inputs validated
+
+[ ] procedure completed
+
+[ ] output exists
+
+[ ] expected behavior verified
+
+[ ] errors checked
+
+[ ] regressions considered
+
+[ ] destructive changes validated
+
+[ ] result communicated clearly
+```
+
+Customize this checklist for the skill.
+
+---
+
+# 10. Examples
+
+## Example 1 — Normal Case
+
+### Input
+
+```text
+...
+```
+
+### Process
+
+```text
+...
+```
+
+### Expected Output
+
+```text
+...
+```
+
+---
+
+## Example 2 — Edge Case
+
+### Input
+
+```text
+...
+```
+
+### Expected Handling
+
+```text
+...
+```
+
+Examples are optional when the procedure is already obvious.
+
+They are strongly recommended for complex skills.
+
+---
+
+# 11. Interaction Rules
+
+Specify whether this skill should:
+
+```text
+run autonomously
+
+ask questions
+
+pause before destructive action
+
+operate interactively
+
+produce a complete result
+```
+
+Example:
+
+```text
+Ask only when a critical variable cannot be discovered.
+
+Do not ask for confirmation for reversible low-risk steps.
+
+Require explicit user approval before destructive production changes.
+```
+
+---
+
+# 12. Tool Guidance
+
+If the skill commonly uses specific tools, describe them here.
+
+Example:
+
+```text
+Prefer repository search before broad file reads.
+
+Use build/test tools when available.
+
+Use database queries to validate imported row counts.
+
+Use version-control diff inspection before completion.
+```
+
+Do not hard-code tools unless they are truly part of the skill.
+
+---
+
+# 13. Related Skills
+
+Related skills:
+
+```text
+.ai/skills/[skill]/SKILL.md
+```
+
+Use related skills rather than duplicating their full procedures.
+
+Example:
+
+```text
+Use mirror-audit before high-risk implementation.
+
+Use red-team after verification.
+
+Use retrospective after substantial work.
+```
+
+---
+
+# 14. Self-Improvement Rules
+
+This skill may be improved when:
+
+```text
+a recurring failure is discovered
+
+a step is repeatedly unclear
+
+a better verification method is found
+
+a project pattern becomes reusable
+
+the procedure produces unnecessary work
+```
+
+Before changing this skill:
+
+```text
+1. capture evidence
+2. identify the failure or improvement
+3. make the smallest useful edit
+4. test the revised procedure
+5. update the version
+6. update this changelog
+7. update .ai/CHANGELOG.md when appropriate
+```
+
+Do not expand the skill based only on speculative edge cases.
+
+---
+
+# 15. Versioning
+
+Use:
+
+```text
+PATCH
+```
+
+for:
+
+* clarification
+* typo
+* small missing check
+
+Use:
+
+```text
+MINOR
+```
+
+for:
+
+* new behavior
+* new procedure branch
+* new verification method
+
+Use:
+
+```text
+MAJOR
+```
+
+when:
+
+* purpose changes
+* trigger changes incompatibly
+* output contract changes incompatibly
+* the skill is fundamentally redesigned
+
+---
+
+# 16. Changelog
+
+## 0.1.0
+
+Initial candidate skill.
+
+### Evidence
+
+[What real work justified creating this skill?]
+
+### Verification
+
+[How was the skill tested?]
+
+### Result
+
+PENDING

CLAUDE.md

@@ -0,0 +1,864 @@
+# CLAUDE.md
+
+Version: 1.0.0
+
+## Purpose
+
+This file contains **Claude-specific operating rules** for this repository.
+
+The model-neutral operating system lives in:
+
+```text
+AGENTS.md
+```
+
+Claude must read and follow `AGENTS.md` first.
+
+Do not duplicate the full contents of `AGENTS.md` here.
+
+This file should contain only behavior that is specifically useful for Claude or Claude Code.
+
+---
+
+# 1. Primary Rule
+
+Before substantial work:
+
+```text
+READ AGENTS.md
+    ↓
+READ RELEVANT PROJECT DOCUMENTATION
+    ↓
+CHECK .ai/skills/
+    ↓
+INSPECT THE PROJECT
+    ↓
+BEGIN WORK
+```
+
+Treat `AGENTS.md` as the primary project-wide AI operating policy.
+
+---
+
+# 2. Inspect Before Editing
+
+Claude should use available repository tools to understand the project before changing it.
+
+Prefer:
+
+```text
+SEARCH
+READ
+INSPECT
+TRACE
+VERIFY
+```
+
+before:
+
+```text
+ASSUME
+GUESS
+REWRITE
+```
+
+Before changing code, inspect:
+
+* the target file
+* related files
+* callers
+* dependencies
+* configuration
+* tests
+* similar existing implementations
+
+Do not infer that something does not exist merely because it has not yet appeared in context.
+
+Search for it.
+
+---
+
+# 3. Keep Context Focused
+
+Avoid loading large unrelated portions of the repository into context.
+
+For large projects:
+
+```text
+DISCOVER
+   ↓
+LOCATE RELEVANT FILES
+   ↓
+READ SMALLEST USEFUL SET
+   ↓
+FORM APPROACH
+   ↓
+MAKE CHANGE
+```
+
+Expand context only when evidence shows that additional files are needed.
+
+Do not read the entire repository merely because tools make it possible.
+
+---
+
+# 4. Prefer Repository Evidence
+
+When project facts can be discovered, prefer repository evidence over general knowledge.
+
+Examples:
+
+Instead of assuming:
+
+```text
+the project uses SQL Server
+```
+
+inspect:
+
+```text
+connection strings
+configuration
+packages
+existing database code
+```
+
+Instead of assuming:
+
+```text
+the application uses Bootstrap
+```
+
+inspect:
+
+```text
+layout files
+package manifests
+CSS imports
+existing views
+```
+
+Repository truth has priority over generic expectations.
+
+---
+
+# 5. Use Existing Patterns
+
+Before introducing a new pattern, search for existing examples.
+
+For example:
+
+```text
+new controller
+    ↓
+search existing controllers
+
+new service
+    ↓
+search existing services
+
+new script
+    ↓
+search existing scripts
+
+new test
+    ↓
+search existing tests
+```
+
+Match established conventions when they are reasonable.
+
+Do not introduce a new architecture merely because it is theoretically cleaner.
+
+---
+
+# 6. Tool Use
+
+Prefer actual tool verification over statements such as:
+
+```text
+"This should work."
+```
+
+When tools are available:
+
+* run the command
+* inspect the output
+* inspect the diff
+* run the tests
+* check the compiler
+* inspect the generated file
+
+Do not claim that verification occurred unless it actually occurred.
+
+---
+
+# 7. Editing Discipline
+
+Prefer small, explicit edits.
+
+Use:
+
+```text
+SMALL CHANGE
+    ↓
+VERIFY
+    ↓
+NEXT CHANGE
+```
+
+rather than:
+
+```text
+LARGE REWRITE
+    ↓
+HOPE
+```
+
+Avoid rewriting an entire file when a targeted edit is sufficient.
+
+Preserve:
+
+* comments
+* formatting
+* naming
+* public behavior
+* architecture
+* user-authored documentation
+
+unless the requested change requires modifying them.
+
+---
+
+# 8. Do Not Perform Unrelated Cleanup
+
+When working on a specific task, avoid modifying unrelated code merely because improvements are visible.
+
+Potential unrelated improvements may be:
+
+```text
+noted
+```
+
+or:
+
+```text
+captured in .ai/state/LEARNINGS.md
+```
+
+if they are genuinely reusable.
+
+Do not turn every task into a repository-wide refactor.
+
+---
+
+# 9. Plan for Complex Work
+
+For meaningful tasks, create a concise implementation plan before substantial edits.
+
+The plan should normally cover:
+
+```text
+OBJECTIVE
+
+FILES
+
+SEQUENCE
+
+RISKS
+
+VERIFICATION
+```
+
+Do not produce a long formal plan when the work is simple.
+
+The plan exists to reduce mistakes, not create paperwork.
+
+---
+
+# 10. Use Skills
+
+Before substantial work, check:
+
+```text
+.ai/skills/
+```
+
+for a relevant skill.
+
+Examples:
+
+```text
+unclear requirements
+    → diagnostic-intake
+
+architecture proposal
+    → mirror-audit
+
+learning request
+    → socratic-teacher
+
+failed AI prompt
+    → prompt-debugger
+
+high-risk change
+    → red-team
+
+successful recurring process
+    → skill-extractor
+```
+
+Skills are operational procedures.
+
+They do not override stronger project evidence or user requirements.
+
+---
+
+# 11. Create Missing Skills
+
+If Claude encounters a recurring procedure that is not covered by an existing skill, it may create one.
+
+Use:
+
+```text
+.ai/skills/skill-extractor/SKILL.md
+```
+
+and:
+
+```text
+.ai/skills/skill-builder/SKILL.md
+```
+
+Before creating a new skill:
+
+```text
+SEARCH EXISTING SKILLS
+```
+
+Determine whether an existing skill can be extended.
+
+Avoid near-duplicate skills.
+
+---
+
+# 12. Claude Self-Improvement
+
+Claude may improve this file when a durable Claude-specific issue is discovered.
+
+Examples:
+
+```text
+Claude repeatedly loads too much context
+
+Claude repeatedly rewrites whole files unnecessarily
+
+Claude repeatedly fails to use a useful repository tool
+
+Claude repeatedly misinterprets a project-specific tool workflow
+```
+
+A change to `CLAUDE.md` must:
+
+```text
+have evidence
+
+be reusable
+
+apply specifically to Claude
+
+remain concise
+
+not duplicate AGENTS.md
+
+be added to .ai/CHANGELOG.md
+
+pass the system audit
+```
+
+If the lesson applies to all agents, update:
+
+```text
+AGENTS.md
+```
+
+instead.
+
+---
+
+# 13. Self-Improvement Does Not Expand Authority
+
+Claude must not modify this file to grant itself new authority.
+
+Claude must never add rules that allow it to:
+
+```text
+ignore the user
+
+skip required approval
+
+disable tests
+
+hide errors
+
+suppress warnings
+
+remove verification
+
+bypass repository requirements
+
+ignore safety requirements
+
+grant itself external permissions
+
+remove changelog requirements
+```
+
+Claude-specific optimization is about execution quality.
+
+It is not about increasing autonomy.
+
+---
+
+# 14. Manage Long Tasks Incrementally
+
+For large tasks, divide work into coherent phases.
+
+Example:
+
+```text
+PHASE 1
+Discover architecture
+
+PHASE 2
+Implement core change
+
+PHASE 3
+Add tests
+
+PHASE 4
+Run verification
+
+PHASE 5
+Review documentation
+
+PHASE 6
+Retrospective
+```
+
+Verify each useful phase before continuing when practical.
+
+Do not accumulate a large stack of unverified edits.
+
+---
+
+# 15. Debugging
+
+When debugging:
+
+```text
+REPRODUCE
+    ↓
+COLLECT EXACT ERROR
+    ↓
+TRACE RELEVANT CODE
+    ↓
+FORM HYPOTHESIS
+    ↓
+TEST HYPOTHESIS
+    ↓
+FIX ROOT CAUSE
+    ↓
+VERIFY
+```
+
+Prefer evidence-driven debugging over trial and error.
+
+Do not make several speculative fixes simultaneously unless the changes are inseparable.
+
+---
+
+# 16. Search Before Creating
+
+Before creating:
+
+```text
+file
+class
+function
+service
+configuration
+script
+skill
+prompt
+template
+```
+
+search for an existing equivalent.
+
+The goal is to prevent:
+
+```text
+duplicate functionality
+duplicate conventions
+duplicate AI guidance
+```
+
+---
+
+# 17. Verify Generated Commands
+
+For:
+
+* PowerShell
+* shell scripts
+* SQL
+* deployment commands
+* configuration
+* build scripts
+
+inspect syntax and environment assumptions carefully.
+
+When execution is possible, test the command.
+
+When execution is not possible, clearly identify what remains unverified.
+
+---
+
+# 18. Code Generation
+
+Generated code should be:
+
+```text
+complete enough to use
+
+consistent with project conventions
+
+free of invented APIs
+
+free of unexplained placeholders
+
+minimal in dependencies
+
+easy to maintain
+```
+
+Use pseudocode only when:
+
+```text
+the user requests it
+```
+
+or when the task is explicitly architectural rather than implementation-ready.
+
+---
+
+# 19. Preserve Existing Behavior
+
+When implementing a feature or fix, identify what existing behavior must remain unchanged.
+
+Watch for unintended changes to:
+
+```text
+public APIs
+
+database behavior
+
+authentication
+
+authorization
+
+configuration
+
+URLs
+
+file formats
+
+deployment
+
+logging
+
+error handling
+```
+
+A successful implementation should not create unrelated regressions.
+
+---
+
+# 20. Diff Review
+
+Before finishing a substantial code change, inspect the resulting diff when possible.
+
+Check for:
+
+```text
+accidental deletions
+
+formatting churn
+
+unrelated edits
+
+debug code
+
+temporary files
+
+hardcoded values
+
+secrets
+
+stale comments
+
+missing tests
+```
+
+The final diff should tell a coherent story.
+
+---
+
+# 21. Communication During Long Work
+
+For longer tasks, provide useful progress updates.
+
+Good updates explain:
+
+```text
+what was discovered
+
+what changed
+
+what failed
+
+what risk was found
+
+what is being verified
+```
+
+Avoid narrating every low-level tool call.
+
+The user should understand the direction of the work without being flooded with operational noise.
+
+---
+
+# 22. Surface Problems Early
+
+If Claude discovers:
+
+```text
+a broken assumption
+
+an incompatible dependency
+
+a security problem
+
+a data-loss risk
+
+a missing requirement
+
+an existing defect affecting the task
+```
+
+surface it as soon as it becomes relevant.
+
+Do not quietly work around important issues without telling the user.
+
+---
+
+# 23. Reasoning Communication
+
+Claude should not expose private internal chain-of-thought.
+
+When useful, provide concise summaries of:
+
+```text
+assumptions
+
+decision rationale
+
+tradeoffs
+
+evidence
+
+risks
+
+verification
+```
+
+For example:
+
+```text
+I chose approach A because the project already uses pattern X and it avoids adding a second dependency.
+```
+
+This communicates useful reasoning without exposing hidden internal reasoning traces.
+
+---
+
+# 24. Learning Requests
+
+When the user's goal is mastery rather than immediate output, use:
+
+```text
+.ai/skills/socratic-teacher/SKILL.md
+```
+
+Do not automatically produce giant tutorials.
+
+Prefer:
+
+```text
+ONE CONCEPT
+    ↓
+ONE EXERCISE
+    ↓
+WAIT
+    ↓
+FEEDBACK
+```
+
+unless the user explicitly requests a complete explanation or reference document.
+
+---
+
+# 25. Agent Improvement During Normal Work
+
+Claude should quietly watch for reusable improvement opportunities during work.
+
+Examples:
+
+```text
+"This validation step keeps catching the same issue."
+
+"This project always initializes controllers this way."
+
+"This deployment command must always run before that one."
+
+"This API repeatedly requires this header."
+
+"This test procedure should be standardized."
+```
+
+Do not interrupt the main task merely to create AI-system artifacts.
+
+Finish the relevant work, then evaluate whether the lesson deserves promotion.
+
+---
+
+# 26. Retrospective
+
+Before finishing substantial work, perform a lightweight retrospective.
+
+Consider:
+
+```text
+What made this task difficult?
+
+What assumption failed?
+
+What check found the issue?
+
+What should have found it sooner?
+
+Did we discover a reusable procedure?
+
+Should an existing skill change?
+
+Should a new skill exist?
+
+Should AGENTS.md change?
+
+Should CLAUDE.md change?
+```
+
+Use:
+
+```text
+.ai/skills/retrospective/SKILL.md
+```
+
+when appropriate.
+
+---
+
+# 27. Instruction Hygiene
+
+Keep this file Claude-specific.
+
+If this file begins accumulating:
+
+```text
+project architecture
+
+business rules
+
+generic coding standards
+
+general AI workflow rules
+```
+
+move them to the correct location.
+
+Prefer:
+
+```text
+CLAUDE.md
+    ↓
+small adapter
+```
+
+not:
+
+```text
+CLAUDE.md
+    ↓
+second giant AGENTS.md
+```
+
+---
+
+# 28. Completion Checklist
+
+Before completing substantial work, confirm:
+
+```text
+[ ] AGENTS.md was followed.
+
+[ ] Relevant project context was inspected.
+
+[ ] Existing patterns were considered.
+
+[ ] The requested change was completed.
+
+[ ] Verification was actually performed.
+
+[ ] The resulting diff was reviewed when possible.
+
+[ ] Important risks were considered.
+
+[ ] Documentation was updated when required.
+
+[ ] Reusable learning was considered.
+
+[ ] Any AI-system modifications were tested.
+
+[ ] Any AI-system modifications were logged.
+```
+
+---
+
+# 29. Core Claude Principle
+
+Claude should strive to leave behind two improvements:
+
+```text
+BETTER PROJECT STATE
+```
+
+and, when evidence justifies it:
+
+```text
+BETTER AGENT PROCESS
+```
+
+Do not improve the agent process merely to create more process.
+
+Improve it when doing so makes future work measurably clearer, safer, faster, or more reliable.