cosmtrek Self-Improvement Loop
A cross-agent self-improvement system. Works with Claude Code, Codex, Cursor, and any agent that reads SKILL.md.
Core loop: Capture → Promote → Prune → Review.
Three-Tier Architecture
NOTES.md Tier 0 raw observations, quick captures
LESSONS.md Tier 1 validated patterns, domain-specific playbook
AGENTS.md Tier 2 hard rules, always loaded, ≤100 lines
Promotion direction: NOTES → LESSONS → AGENTS. Each tier is more selective, more abstract, and higher priority.
Setup
File layout:
project-root/
├── AGENTS.md # Tier 2: always loaded
└── .agents/self-improve/
├── LESSONS.md # Tier 1: read on demand
└── NOTES.md # Tier 0: staging area
The .agents/self-improve/ directory is owned by this skill. On first
invocation, create it if missing, plus any missing files inside it with
a one-line heading. No fingerprint is needed for these files — the path
itself is the ownership marker.
Throughout this document, NOTES.md and LESSONS.md refer to their
fixed paths inside .agents/self-improve/.
Each tier has its own structural scope. The skill only reads and writes content that matches its tier's format:
- NOTES.md — entries matching the Phase 1 capture format
(
### [observe|promote] ...with a<!-- captured: YYYY-MM-DD -->footer). - LESSONS.md — bullet points (
- ...) under##section headings (Code Style, Testing, API, etc.).
Anything that does not match these shapes — prose, comments, headings outside the skill's format — is never parsed, moved, or deleted.
AGENTS.md
AGENTS.md lives at the project root and is never owned as a whole by this skill. The skill only touches a single fingerprinted block:
## Self-Improve
<!-- managed-by: self-improve -->
See `.agents/self-improve/LESSONS.md` for domain-specific patterns.
- <promoted rule 1>
- <promoted rule 2>
Rules for this block:
- Identified by block fingerprint, not heading text. A project's own
## Self-Improveheading without the fingerprint is out of scope — never touched. - The only place Phase 2 writes promoted rules and Phase 3 prunes them.
- Created on first promotion with a separate user confirmation. If AGENTS.md does not exist, Phase 2 also asks before creating it.
- Everything else in AGENTS.md is project-owned and read-only. If a promotion candidate overlaps with a project-owned rule outside the block, see the merge procedure in Phase 2.
Mirror files (CLAUDE.md, .cursorrules, copilot-instructions.md, …)
are never written to. AGENTS.md is the single source of truth.
Phase 1: Capture → NOTES.md
Trigger: /self-improve capture.
- One sentence: what happened
- One sentence: root cause (ask "why", not "what")
- Decide: record or dismiss?
- dismiss — one-off, not a pattern. Tell user why, do not write to NOTES.md, stop here.
- record — continue to step 4.
- Tag the entry:
[promote]— clear pattern, recommend moving to LESSONS.md in Phase 2[observe]— might be a pattern, keep for now
- Append to
NOTES.mdwith date stamp
Entry format:
### [observe] Database calls must be awaited
- **Symptom**: Missing await in userService.ts caused silent failure
- **Root cause**: No lint rule enforcing consumption of async return values
- **Scope**: `src/services/**`
<!-- captured: YYYY-MM-DD -->
Constraints:
- Max 5 lines per entry
- Write behavioral directives ("must X", "never Y"), not narratives
- Record glob scope when determinable
Phase 2: Promote
Trigger: /self-improve promote.
Promotion moves entries between tiers. Do not leave breadcrumbs like
[promoted → ...] in the source file — git log is the audit trail.
Two promotion paths, evaluated independently.
NOTES.md → LESSONS.md
- Read
NOTES.md - Gather candidates:
[promote]-tagged entries, plus[observe]entries with 2+ similar occurrences - Abstract: from specific incidents to general principle
- Present candidates to user, ask for each:
| Action | When |
|---|---|
Promote to LESSONS.md |
Pattern confirmed, domain-specific |
| Stay in notes | Needs more observation |
| Dismiss | Turned out to be noise |
- On confirm: append to the correct section in
LESSONS.md(Code Style, Testing, API, …), creating the section if it does not yet exist, and delete the entry from NOTES.md.
LESSONS.md → AGENTS.md
- Read
LESSONS.md - Find lessons that apply across the whole project
- Compression test: can it be stated in one line? If yes → candidate
- Present candidates to user:
| Action | When |
|---|---|
| Promote to AGENTS.md | Universal, high-impact, one-liner |
| Stay in lessons | Domain-specific or needs context |
| Extract to a skill | Complex enough to be a standalone workflow |
| Merge into existing rule | Says the same thing as an existing rule |
- On confirm: append the rule to the
## Self-Improveblock in AGENTS.md and delete the entry from LESSONS.md.
Merge procedure
When a candidate overlaps with an existing rule, the destination action depends on where the duplicate lives.
- Duplicate in skill-managed space (LESSONS.md, or the
## Self-Improveblock in AGENTS.md). Show both wordings side-by-side and ask the user: keep existing, replace with candidate, or combine. Apply the choice to the destination, then delete the source entry (move semantics). - Duplicate in project-owned AGENTS.md content. Tell the user the rule already exists outside the skill's managed area and recommend they update the project-owned rule themselves. Never auto-edit project-owned content. Keep the source entry in place — the skill cannot verify the destination was updated, so deleting it would risk silent loss. Offer an explicit dismiss action if the user wants to drop the source anyway.
Phase 3: Prune
Trigger: /self-improve prune.
Prune each tier independently.
AGENTS.md (Tier 2)
Scope: the ## Self-Improve block only. Never touch content outside it,
even if a rule elsewhere looks redundant or stale. Hard constraint:
≤100 lines inside the block.
| Check | Condition | Action |
|---|---|---|
| Redundant | Removing it would not cause mistakes | Delete from block |
| Over-detailed | Needs examples to understand | Demote to LESSONS.md |
| Duplicate | Another block rule says the same thing | Merge in place |
LESSONS.md (Tier 1)
No hard line limit, but each section must earn its place.
| Check | Condition | Action |
|---|---|---|
| Obsolete | Codebase has changed, no longer applies | Delete |
| Section bloat | One section dominates | Split into a skill |
NOTES.md (Tier 0)
Aggressive cleanup — this is a staging area, not an archive.
| Check | Condition | Action |
|---|---|---|
| Stale observe | > 14 days, no second occurrence | Dismiss |
Present the pruning plan, wait for user confirmation, execute, and report line counts before vs after for all three files.
Phase 4: Review
Trigger: /self-improve review.
- Scan the current session for:
- Corrections the user made
- Dead ends that required backtracking
- Repeated attempts before success
- Run Phase 1 (Capture) on each finding → NOTES.md
- If NOTES.md has ≥ 2 similar
[observe]entries, suggest Promote - Output summary: N new notes captured, M ready for promotion
Constraints
- NOTES.md entries: ≤ 5 lines each
- AGENTS.md: ≤ 100 lines inside the
## Self-Improveblock (project-owned content elsewhere is out of scope and uncounted) - Every entry must have a date:
<!-- captured: YYYY-MM-DD --> - Date stamps use the harness-provided current date (e.g., Claude Code's
currentDatecontext). If unavailable, ask the user for today's date before writing. Never guess or fabricate. - All file modifications require user confirmation
- Write behavioral directives, not narratives
- When promoting to AGENTS.md, compress to one line; if impossible, it belongs in LESSONS.md