Self Improve

Self-Improve

Review the current conversation, or the project's past sessions when asked, to extract durable lessons and route each one to the right knowledge layer.

Step 1: Detect Context

Available destinations:

• Project AGENTS.md — the instruction file in the project root, plus any nested ones in subdirectories. At each level use AGENTS.override.md when one is present, otherwise AGENTS.md: an override replaces that directory's AGENTS.md rather than adding to it, so a lesson written to a shadowed file never loads. A nested file scopes its guidance to that subtree, so a lesson scoped to one subtree belongs in the nearest enclosing file, with the root reserved for project-wide rules.
• Auto memory — one writable memory target resolved for the canonical project root. Prefer a synced Claude Code project-memory source, then a memory-update target explicitly named by the active harness. If neither resolves, skip this destination.
• Skills — Project skills at .agents/skills/ (walked from project root down to cwd) and user-installed skills at ~/.agents/skills/ (resolve symlinks)

Resolve the canonical project root as the Git top-level containing the working directory, or the physical working directory outside a repository. Resolve Auto memory in this order:

1. Synced Claude Code source memory — Read ~/.turbo/config.json. When codex.sharedClaudeAutoMemory is exactly true, treat shared-memory setup as complete for every project and use this branch. Resolve autoMemoryDirectory from Claude Code's managed settings, then project-local .claude/settings.local.json, then the user <Claude config home>/settings.json; exclude checked-in .claude/settings.json, where Claude Code ignores this security-sensitive field. Use the expanded override when set. Otherwise locate the resource directory under ~/.codex/memories/extensions/external_agent_import/resources/ whose scope.json matches the canonical project root, take its directory name as the exact Claude project key, and use projects/<project key>/memory/ under CLAUDE_CONFIG_DIR when set or ~/.claude/. Treat false, a missing or invalid key, and an unreadable ~/.turbo/config.json as not opted in and continue to the harness target.
2. Harness memory update target — Otherwise use a project-specific memory file or additive note intake that the active harness instructions explicitly name for memory updates.
3. No target — Otherwise skip Auto memory and route lessons through the remaining destinations.

Treat imported extension resources and the harness's consolidated memory files as read-only. For the resolved target, list the directory when applicable and read its index before routing lessons.

Discover the project instruction files (the root file and any nested ones in subdirectories, resolved through the override rule above) and read them. When those files or the resolved Auto memory target point at a knowledge base the repo maintains, read its index too; it is a documentation source for Step 3 rather than a routing destination. List all skill directories with the description frontmatter of each SKILL.md, but do not read the bodies yet — Step 2 needs to run first so you know what to look for.

Skill Ownership Detection

Classify every skill this session touched:

• Skills that live in the project are user/project skills
• If ~/.turbo/repo/ exists, list directories in ~/.turbo/repo/codex/skills/; any skill in ~/.agents/skills/ with a matching directory there is a turbo skill
• For every other skill in ~/.agents/skills/, read ~/.agents/.skill-lock.json. Its top-level skills object is keyed by skill name, and a skill listed there was installed from a source that replaces it wholesale on its next update. Match on the resolved path rather than the name alone, against the entry's skillPath, so a local fork that replaced the installed copy is not mistaken for it. A skill that matches is package-managed. The signal runs one way: absence from the file leaves ownership genuinely open, so carry an unlisted skill into Step 4 as ownership-unresolved

Verification rule (mandatory before routing in Step 4): For every candidate skill that is about to be routed as turbo, confirm with a fresh test -d ~/.turbo/repo/codex/skills/<name> check that the skill actually lives in the turbo repo. Do not rely on remembered listings from earlier in the session, filename hits in grep output, or assumptions based on where a SKILL.md was read from. A miss here mislabels a user/project skill as turbo, triggers the contribution flow unnecessarily, and can introduce session-specific content into a shared skill — so the check is not optional.

Exception: If the current project IS the turbo repo (i.e., the working directory contains this skill collection), route turbo skill lessons through the Existing user/project skill destination in Step 4 — edits go directly to codex/skills/<name>/ in the project, with no installed-copy indirection and no contribution flow.

Step 2: Gather Session Evidence and Scan for Lessons

Recover Pre-Compaction Evidence

Skip when the conversation is visible in full from the user's own first message.

When it starts from a summary of earlier work instead, recover the compacted turns from the on-disk rollout file. Spawn a single sub-agent (inherited model defaults). The sub-agent's prompt must include:

1. The absolute path of the project root
2. A distinctive phrase from the visible conversation, for confirming which rollout file belongs to this session
3. An instruction to read references/transcript-miner.md for rollout file location, extraction, and output format

Treat the returned items as raw evidence for the scan below.

Sweep Past Sessions

Run when asked to distill sessions beyond the current one. Skip otherwise.

Propose a cutoff first. When Step 1 resolved a harness memory update target, take its newest modification time, state it, then use request_user_input to confirm sweeping from it or sweeping the whole history; when that gate cannot reach the user, sweep from the proposed cutoff and say so in the report. A memory file's timestamp records a write rather than a completed sweep, so it bounds the work without settling what a previous run covered. When Step 1 resolved the synced Claude Code source, take its newest modification time and state that Claude Code writes also advance it, so it may omit unswept Codex sessions; use request_user_input with whole Codex history as the recommended option and that timestamp as the bounded option. When that gate cannot reach the user, sweep the whole Codex history and say so in the report. When no memory location is available, sweep the whole history without asking.

Spawn a single sub-agent (inherited model defaults). The sub-agent's prompt must include:

1. The absolute path of the project root
2. The confirmed cutoff as an ISO-8601 timestamp, or that there is none
3. An instruction to read references/transcript-miner.md and follow its sweep process

Treat the returned items as raw evidence for the scan below.

Identify Session Skills

Before scanning for lessons, identify which skills were loaded during this session:

• Scan the conversation for Turbo skill invocations and SKILL.md reads from ~/.agents/skills/
• Build a list of session skills, marking each as turbo, user/project, package-managed, or ownership-unresolved (using the detection from Step 1)
• This list informs routing in Step 4: when a lesson clearly arose from a specific skill's workflow, that skill is the natural routing target

Scan for Lessons

Scan the full conversation with this priority:

1. Corrections — Where the user interrupted, said "no", "actually", "stop", "not like that", redirected, or manually fixed something Codex did wrong. Highest-value lessons.
2. Repeated guidance — Instructions the user gave more than once. Across separate sessions this counts even where each instance reads as ordinary steering on its own.
3. Skill-shaped knowledge — Domain expertise that was needed repeatedly, tool/API integration details that had to be looked up, decision frameworks that emerged for evaluating options, content templates or writing conventions that were refined, and multi-step workflows where ordering mattered (as reusable domain knowledge, not the workflow itself — see #4).
4. New workflows — Did this session establish a novel multi-step procedure, coordination pattern, or automation that worked? A successful workflow that would need to be repeated is a prime skill candidate — even if it ran fine this time. Distinct from #3: this captures the procedure itself as a repeatable artifact, not knowledge about how to do it. Flag it.
5. Preferences — Formatting, naming, style, or tool choices the user expressed.
6. Failure modes — Approaches that failed, with what worked instead. For tool or script call failures, trace back to the information source that led to the error and route the fix there (e.g., clarify a reference file, update skill instructions, add missing documentation).
7. Domain knowledge — Facts or conventions Codex needed but did not have.
8. Improvement opportunities — Out-of-scope improvements noticed during work: code that could be refactored, missing tests, performance issues, readability concerns, or feature ideas that were intentionally skipped to stay focused. Skipped findings count here: when code simplification or code review identified a genuine improvement or issue but it was skipped for this session, route it as a project improvement so it isn't lost.
9. Trusted reviewer feedback — Human PR review comments that reveal project conventions, patterns, or corrections. Trusted reviewers are repo collaborators with admin or maintain roles (determine via gh api repos/{owner}/{repo}/collaborators --jq '.[] | select(.role_name == "admin" or .role_name == "maintain") | .login'). Their feedback takes precedence over other reviewers and AI bots when there are contradictions.

After scanning, read the SKILL.md of every skill a candidate lesson could touch: the session skills, plus any skill whose description from Step 1 covers a lesson's domain. This gives Step 3 and Step 4 the context for filtering and routing.

Step 3: Filter

Keep only lessons that are:

• Stable — likely to remain true across future sessions
• Non-obvious — Codex would not already know this
• Actionable — can be expressed as a rule or instruction
• Not already covered — no rule in the files read in Steps 1 and 2, in the references/ and other supporting files of the skills read in Step 2, or in the project's own knowledge stores already covers it, even as a special case. A lesson drawn from one incident is covered when an existing general rule, followed, would have prevented that incident; a workflow is covered only when an existing skill already encodes its steps. Search those sources for each candidate's keywords, then judge coverage by meaning, since a general rule rarely shares an incident's wording. When the covering rule was in context during the incident and still read past, because its wording, scope, or placement let the incident through, keep the lesson as a revision of that rule in place, adding no new rule; otherwise discard it. A lesson covered only in an unrelated subtree's AGENTS.md still counts as uncovered for the subtree it actually applies to.
• Still a concern — the issue is not already fixed by changes made in this session. If a bug was found and fixed, or a missing feature was added, future sessions will see the corrected code — they don't need a reminder about the old problem. Exception: successful workflows and procedures are not "resolved" — they're skill candidates precisely because they worked and will need to be repeated. When sweeping past sessions, judge this against the current state of the code and docs rather than against this session's changes.

Discard anything session-specific, speculative, one-off, or already resolved by code changes in this session (but not successful workflows — see exception above). If no lessons survive filtering, tell the user and stop.