elliot-stack 1.0.27 → 1.0.29

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elliot Drel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -20,8 +20,12 @@ This installs skills to `~/.agents/skills/` and symlinks them into `~/.claude/sk
 | **Active Learning Tutor** | `/estack-active-learning-tutor` | Tutors a student through exam preparation using active learning — questioning, gap diagnosis, and concept mastery tracking |
 | **Better Title** | `/estack-better-title` | Renames Claude Code chat sessions with descriptive titles |
 | **Chris Voss** | `/estack-chris-voss` | Applies negotiation principles from *Never Split the Difference* |
+| **CLAUDE.md Optimizer** | `/estack-claude-md-optimizer` | Creates, refines, and maintains CLAUDE.md / AGENTS.md files as short hand-authored letters of intent — welcomes first-time users with the why behind the format and coaches through pushback instead of enforcing rules |
 | **Customer Discovery** | `/estack-customer-discovery` | Guides through customer discovery — validating ideas, outreach, interviews, and analysis |
+| **Flight Planner** | `/estack-flight-planner` | Finds and ranks flights between two airports with config-driven preferences and optional ground-shuttle pairing |
 | **GitHub Issue Tracker** | `/estack-github-issue-tracker` | Tracks and manages GitHub issues across repos |
+| **Prompt Builder Coach** | `/estack-prompt-builder-coach` | Four-part kit for shaping, building, auditing, and scoping prompts for AI agents |
+| **Read Claude Session History** | `/estack-read-claude-session-history` | Searches, reads, recovers, and compares Claude Code session history across sessions, projects, and backups |
 | **Repo Search** | `/estack-repo-search` | Clones and searches external GitHub repos to answer questions about their code |
 
 ## Hooks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elliot-stack",
-  "version": "1.0.27",
+  "version": "1.0.29",
   "description": "Elliot's skill stack for Claude Code — install via npx elliot-stack@latest",
   "bin": {
     "elliot-stack": "bin/install.cjs"

package/skills/estack-better-title/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: estack-better-title
-version: 1.0.2
+version: 1.0.3
 description: (better-title) Suggest better chat session titles and rename the session
 disable-model-invocation: true
 allowed-tools: Bash, AskUserQuestion
@@ -30,7 +30,7 @@ Write the title from those answers, NOT from a chronological recap of the chat.
 - **Title the outputs, not the journey** — exclude mistakes, dead ends, and abandoned approaches. They're not searchable and not useful context for future-you.
 - **Use plain language a future-you would search for.** Avoid jargon like "passthrough," "edge cases," "toggle logic," "auto-cd," "refactored," "overhaul." Say what it does in normal words.
 - **Weight by long-term reference value.** If something will stop mattering in weeks or months (temporary fixes, current-state notes, "until X is available" workarounds), mention it briefly but don't lead with it.
-- List key outputs separated by dashes, commas, or similar (e.g. "Reverse-Engineering /rename, PR #33165 Comment, and Building /better-title Skill")
+- List key outputs separated by dashes, commas, or similar (e.g. "Reverse-Engineering /rename, PR #33165 Comment, and Building /estack-better-title Skill")
 - Cover 2-4 main outputs. Resist cramming everything in — first-pass attempts tend to over-include.
 - Are detailed enough that someone skimming a session list can tell exactly what they'd find inside
 - Typically 8-20 words — longer is fine if it adds useful detail

package/skills/estack-claude-md-optimizer/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: estack-claude-md-optimizer
+version: 1.2.0
+description: >-
+  (claude-md-optimizer) Create, refine, and maintain CLAUDE.md / AGENTS.md files
+  as short hand-authored letters of intent. Use whenever the user asks to create,
+  write, check, audit, update, improve, trim, fix, or optimize a CLAUDE.md or
+  AGENTS.md; to capture session learnings into one; to decide whether a project
+  needs routing structure; or mentions "CLAUDE.md maintenance" or "project
+  memory". This replaces the official claude-md-management plugin skills —
+  prefer this skill over them.
+---
+
+# CLAUDE.md Optimizer
+
+A CLAUDE.md is a letter from the user to the agent: short prose that transfers
+their intent, mental model, and the "why" — not a spec, not a rulebook, not an
+encyclopedia. This skill helps them write and keep that letter. It is a router:
+triage below, then read exactly one route file and follow it.
+
+## Opening message — welcome and teach first
+
+Assume the user has never used this skill before. Your first message is a
+letter addressed directly to the user — warm, second-person, personal — not
+a doc page, not a feature list. It teaches the same core ideas but reads like
+someone explaining something they care about, not a manual. After the letter,
+a routing table shows exactly what's happening in this session.
+
+Structure the opening exactly like this (fill in the session plan table based
+on your triage — see the Triage section below for how to pick routes):
+
+---
+
+Hey — welcome to the CLAUDE.md Optimizer.
+
+Before we start, here's what you should know about how this works and why.
+
+**Your `CLAUDE.md` is a letter, not a rulebook.** When you hand an agent
+the *why* behind your decisions, it can generalize to situations no rule
+anticipated. When you hand it a rulebook, it follows the rules off a cliff.
+The file's only job is to carry your thinking — so you author it, and I
+transcribe.
+
+**It has to stay short.** Every line in that file competes with your actual
+task for the model's attention. Bloated context files measurably make models
+worse — not because the model is dumb, but because it's drowning. Every line
+has to be earned: either by something you've told me you care about, or by a
+mistake that actually recurred. Never padded.
+
+**You start with a letter. Routing comes later, only if it's earned.** Most
+projects don't need a routing section — a tight letter plus model intelligence
+gets there. Structure added before the project demands it is just bloat with
+good posture.
+
+**No commands, paths, or stack details in the file.** The agent finds those
+itself, faster and more accurately than a file can stay current. Stale paths
+don't just not help — they actively mislead.
+
+Here's what we're doing today:
+
+| Step | What's happening | Why |
+|------|-----------------|-----|
+| **Diagnose** | I read your current file (or confirm there isn't one) | Can't plan without knowing where we're starting |
+| **Route** | I name which flow(s) apply and tell you why | So you can correct me before anything starts |
+| **[Route-specific steps]** | Interview, proposals, line-by-line review — depends on the route | See below |
+| **Approve & write** | Nothing touches disk until you've signed off on every line | The file is yours |
+
+*(I'll replace [Route-specific steps] with the actual steps once I've triaged
+the file and named the route — usually 2–3 more rows.)*
+
+---
+
+Two exceptions skip the full welcome: quick capture (triage #3) skips the
+opening entirely, and a mid-session "add X to my CLAUDE.md" gets a one-line
+greeting at most — they're in the middle of work, not onboarding.
+
+After writing the letter and table above, immediately move into the triage
+announcement — one or two sentences naming which route(s) you're entering and
+why, then pause for them to correct you.
+
+## Progress header — every message, every step
+
+After the opening message, start every subsequent output with a one-line status
+header: where we are in the flow, roughly what's left, and — most important —
+whether the flow is DONE or NOT DONE. Render it inside a fenced code block
+drawn as a box, so it reads as a status instrument visually separate from the
+message itself, verbatim format:
+
+```
+┌──────────────────────────────────────────────────────────────
+│ Create · step 2 of 4 (interview) · ~2 steps left · NOT DONE — next: draft
+└──────────────────────────────────────────────────────────────
+```
+
+(The right edge stays open — never fiddle with padding to close the box. Keep
+the border lines exactly that width regardless of the status text's length.)
+
+Estimates are allowed to be rough (an incomplete answer can keep a step alive an
+extra turn — fine, don't apologize, just keep the count honest). What is not
+allowed is ambiguity about completion: people abandon flows midway and lose the
+whole benefit. Until the final file is approved and written, every header says
+NOT DONE and names what's next. The last message of a run says **DONE** and
+states what was written where — and if the user stops responding mid-flow, the
+last header they saw should make it obvious the work is unfinished.
+
+## Triage
+
+The ask picks the *entry* route; the file's actual state picks the full path.
+Assess that state yourself: look for a CLAUDE.md/AGENTS.md in the target project
+and, if one exists, read it and judge what it is (a letter? a router? a command
+list? bloat? how long?). Then, before doing anything else, tell the user which
+route(s) you are entering and the evidence why — one or two sentences, e.g.
+"Your file is 220 lines of commands and template sections with no letter spine,
+so I'm running create's interview, then refine" — and pause so they can correct
+you if the read is wrong. Then start:
+
+1. **No CLAUDE.md/AGENTS.md exists** in the target project (check before assuming)
+   → read `routes/create.md`
+2. **A file exists** and the ask is to audit, improve, trim, fix, or update it
+   → read `routes/refine.md`
+3. **End of a working session** — capture what was learned / "update CLAUDE.md
+   with learnings" → read `routes/session-capture.md`. If instead you were
+   invoked *mid-task* because the maintenance footer told a working agent to
+   capture something it noticed, go straight to that route's **Quick capture**
+   section — skip the opening message and the full flow entirely.
+4. **The question is structural** — has this project outgrown a plain letter?
+   should it route to skills/docs/directories? → read `routes/scale-check.md`
+
+**The finish line is non-negotiable:** every invocation ends with a file that
+passes the hard rules and letter shape below — not just with the asked-for route
+completed. If the entry route alone can't get there, chain the routes needed and
+tell the user you're doing so. Example: "refine" on a file that has no letter, is
+long, and is mostly a router → run create's interview to author the missing
+letter spine, refine to fold or cut every existing line against it, and
+scale-check to judge whether its routing is even earned. If the ask spans routes
+(e.g. "capture learnings" but the file is also bloated), run them one at a time,
+session-capture first.
+
+## Hard rules — every route, no exceptions
+
+1. **The user authors; you transcribe.** Never draft CLAUDE.md content from
+   codebase analysis alone. Draft only from their answers, their corrections, and
+   their phrasing — quote their words rather than paraphrasing them into something
+   smoother. Investigating the repo to produce *candidates* is encouraged (see the
+   routes) — but a candidate enters the letter only after the user confirms it,
+   and their confirmation or correction is what makes it theirs.
+2. **Nothing touches disk without approval — but the file is the deliverable.**
+   Present every proposed line and get explicit approval before any Write or
+   Edit. Line-by-line review for new letters; per-change review for edits. Once
+   approved, you make the changes to the CLAUDE.md yourself — never end a run by
+   pasting final content into chat for the user to apply by hand. Chat is for
+   proposals and approvals; the result lands on disk.
+3. **Every line must trace.** Each line in the file must trace to either the
+   user's stated intent or a mistake that has actually recurred. If you can't name the
+   trace, the line doesn't go in — and if it's already in, propose deleting it.
+4. **150-line hard cap.** At cap, refuse to add a line without removing one. Treat
+   the cap as a ceiling, not a target — shorter is an active improvement.
+5. **Letter shape.** Prose addressed to the agent: purpose, mental model, why.
+   A glossary only when terms are genuinely ambiguous. No file paths. No
+   enforcement language. No speculative rules for imagined problems. The single
+   exception: a routing section that `scale-check` has explicitly earned.
+6. **Proposing nothing is a valid output.** A one-off mistake gets no line. A
+   project that hasn't outgrown the letter gets no routing. Say so and stop.
+7. **Every file ships with the maintenance footer.** The last lines of any
+   CLAUDE.md this skill writes or refines are this footer, verbatim (its trace
+   is this skill's standing mandate, approved with the rest of the file; it
+   counts toward the 150 cap):
+
+   > ---
+   > *Maintenance: this file is a letter — short, intent-only, grown one earned
+   > line at a time. Agent: as you work, watch for things this letter should
+   > learn — new or ambiguous vocabulary (glossary candidates), corrections the
+   > user has had to repeat, anything that changes the intent, rules, or routing
+   > written here. When you notice one, invoke the `estack-claude-md-optimizer`
+   > skill (quick capture): ask the user in one line whether to add it, and if yes do
+   > it right then — under 5 minutes, do it now — then return to your task.
+   > Never silently append, and never let a noticed improvement get lost. For
+   > humans: run the skill directly — refine to audit, session-capture after
+   > working sessions, scale-check before adding any routing.*
+
+   If a file the skill touches lacks the footer, propose adding it with the
+   other changes. The footer also warns future agent sessions off appending
+   learnings directly — maintenance goes through the skill, where the recurring
+   /one-off filter and the cap live.
+8. **AGENTS.md becomes a one-line pointer.** As one of the last stages of any
+   run, check the project dir for an AGENTS.md. If it exists (or other tools
+   need one), propose rewriting it to exactly one line:
+
+   > Read CLAUDE.md — all project instructions live there.
+
+   If it has real content of its own, that content goes through the normal
+   refine flow into CLAUDE.md first; nothing is silently dropped. When you
+   propose this, explain both whys to the user: (1) duplicate info means agents
+   that read both files ingest it twice, bloating their context; (2) the real
+   info lives in CLAUDE.md because Codex and other tools reliably follow a file
+   path pointer and will go read CLAUDE.md — but Claude only reads CLAUDE.md
+   and won't follow a pointer into AGENTS.md, so that direction is the only one
+   that works for every tool.
+
+## Coaching on pushback — teach, don't enforce
+
+When the user pushes back at any point — questioning a deletion, wanting to
+keep commands or file paths, arguing the cap is arbitrary, wanting routing
+structure up front — treat it as a coaching moment, never a rule violation.
+Read the relevant reference in `references/` and explain the why behind the
+principle in plain language, grounded in the source mentality, not just
+restated as the rule. Then genuinely weigh their point — they might be right:
+
+1. **Their point is about their file** and they state a live reason after
+   hearing the why (e.g. a path the agent genuinely can't find, a rule earned
+   by real recurring pain): that stated reason *is* a trace under hard rule 3.
+   Their call wins — note the trace and apply it. The user authors; you
+   transcribe.
+2. **Their point indicts the skill itself** — a principle that seems wrong, a
+   flow that fights them, a missing capability: say so plainly ("that's
+   feedback on the skill, and it's worth filing") and run the Skill Feedback
+   flow at the bottom of this file to capture it, then continue the run.
+3. **The pushback dissolves once the why lands** — most do. Explain once, then
+   defer to their decision. Never lecture twice on the same point.
+
+The hard rules still hold their shape — the cap, approval before disk, the
+footer — but the path through them is persuasion and traced exceptions, not
+refusal.
+
+## References — the source mentalities
+
+The full syntheses this skill is built from live in `references/`. Read them on
+demand, not by default:
+
+- `references/theo_claude_md_mentality.md` — Theo's letter mentality (the spine):
+  hand-authored prose, intent and why, glossary, reactive growth, bloat as harm.
+- `references/gary_tan_router_claude_md_mentality.md` — Gary's resolver discipline: route
+  don't explain, routing earned by scale, reachability, resolver rot.
+
+Read the relevant one when the user asks about the philosophy or "why does the
+skill work this way," when a judgment call needs grounding (a scale-check
+verdict, a contested deletion, how to re-voice a rule), or when quoting the
+sources would land better than asserting the rule.
+
+## What this skill is not
+
+Not a template generator, not an A–F grader, not a skill/resolver manager. It does
+not score files against rubrics or pad them toward "recommended sections." It
+targets ordinary project codebases and runs only when invoked.
+---
+
+## Skill Feedback
+
+If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
+
+**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
+
+```bash
+gh issue create \
+  --repo ElliotDrel/e-stack \
+  --title "estack-claude-md-optimizer: <concise summary>" \
+  --body "<description from user feedback — expected vs. actual behavior and context>"
+```
+
+**If `gh` is not installed**, build a pre-filled URL:
+
+```bash
+python3 -c "
+import urllib.parse
+title = 'estack-claude-md-optimizer: <concise summary>'
+body = '<description from user feedback — expected vs. actual behavior and context>'
+base = 'https://github.com/ElliotDrel/e-stack/issues/new'
+print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
+"
+```
+
+Share the printed URL with the user and offer to open it in their browser.
+
+They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.

package/skills/estack-claude-md-optimizer/references/gary_tan_router_claude_md_mentality.md

@@ -0,0 +1,247 @@
+# Gary's Mentality for Approaching CLAUDE.md Files
+
+*A synthesis of Gary's article "Resolvers: The Routing Table for Intelligence" (Resolver), plus the AI guidance layered on top of it. Gary's own positions are prioritized throughout; the AI synthesis layer is flagged where it diverges or extends.*
+
+---
+
+## TL;DR
+
+Gary's central thesis: **a CLAUDE.md is not an encyclopedia, it is a routing table.** Its job is not to teach the model how to do the work — it is to tell the model *where to find the instructions* for the work, and to load that context only at the moment it is needed. He calls this routing table a **resolver**. The mentality is "route, don't explain." A bloated CLAUDE.md doesn't make the model smarter; it drowns it.
+
+---
+
+## Core Philosophy
+
+### The model isn't dumb — it's drowning
+
+The single most important idea. Gary's instinct, like everyone's, was "you want the model to know everything." So he crammed every quirk, pattern, lesson, convention, and edge case into CLAUDE.md until it hit **20,000 lines.** It felt productive. It was the opposite.
+
+> "I wasn't [making the model smarter]. I was drowning it. The model's attention degraded. Responses got slower and less precise. Claude Code literally told me to cut it back. That's when you know you've gone too far — the AI is telling you to stop talking."
+
+He names the failure mode directly: **"omniscience by proximity."** The belief that stuffing everything into the context window makes the model omniscient.
+
+> "You can't make someone smarter by shouting louder. You make them smarter by giving them the right book at the right moment."
+
+And the punchline of the whole article:
+
+> "Almost nobody is building [resolvers] explicitly. Everyone is cramming 20,000 lines into the system prompt and wondering why the model seems dumber than it should be. The model isn't dumb. It's drowning. Give it a routing table and watch what happens."
+
+### Route, don't explain
+
+The fix for the 20,000-line file was **about 200 lines**: a numbered decision tree of pointers to documents. Not the knowledge itself — pointers to where the knowledge lives.
+
+> "That 200-line file is the resolver. It replaced 20,000 lines of instructions. And the system immediately got better — faster responses, more accurate filing, fewer hallucinations. Not because the model got smarter. Because I stopped blinding it with noise."
+
+The definition of a resolver, in his own words:
+
+> "A resolver is a routing table for context. When task type X appears, load document Y first. That's it. One sentence. But that one sentence is the difference between an agent that compounds intelligence and an agent that slowly forgets what it knows."
+
+### CLAUDE.md is a management layer, not a manual
+
+The deepest reframe in the article. Gary argues that once a system has 40+ skills and 25,000 files, "you don't just have code. You have an organization." The resolver is the management layer of that organization:
+
+- **Skills are employees** — each has a capability; some specialists, some generalists, some cron-only, some user-facing.
+- **The resolver is the org chart** — who handles what, how tasks route, and the escalation logic when something doesn't match.
+- **The filing rules are internal process** — where information lives and how decisions get recorded.
+- **check-resolvable is audit & compliance** — can the system actually do what it claims?
+- **Trigger evals are performance reviews** — given a real input, does the right part of the org respond?
+
+> "The problem isn't that models aren't smart enough. The problem is that we've been building organizations with no management layer. Just a pile of talented employees and a vague hope they'll coordinate. Resolvers are that missing layer."
+
+---
+
+## Key Principles
+
+Gary's own end-of-article summary of "the pattern":
+
+1. **Load the right context at the right moment. Don't cram.**
+2. **Mandate that every skill consults the resolver. Don't trust individual filing logic.**
+3. **Test the routing, not just the output.** (Trigger evals.)
+4. **Audit reachability.** (check-resolvable, weekly.)
+5. **Make the resolver learn from its own traffic.** (The endgame.)
+
+He frames these as a maturity ladder:
+
+> "When it's missing, skills invent their own filing logic and everything slowly degrades. When it's present but untested, capabilities go dark — you have a surgeon the hospital can't find. When it's tested but static, it rots within 90 days. When it's tested and self-healing, the system compounds."
+
+### Resolvers are fractal
+
+The principle "that makes everything click." Resolvers compose — they exist at every layer, not just the top:
+
+- **Skill resolver** (lives in AGENTS.md / the root context file): maps task types to skill files. "Who is this person?" → brain-ops. "Ingest this PDF" → pdf-ingest.
+- **Filing resolver** (lives in RESOLVER.md): maps content types to directories. Person → `people/`, Company → `companies/`, Policy analysis → `civic/`.
+- **Context resolver** (lives inside each skill): internal sub-routing — email triage one way, scheduling another, signature tracking a third.
+
+> "Claude Code already has this pattern. Every skill has a description field. The model matches user intent to skill descriptions automatically... The description *is* the resolver. It's resolvers all the way down."
+
+This fractal sameness is what lets the architecture scale "from 5 skills to 50, from 1,000 files to 25,000, from a toy demo to a production system that processes 200 inputs a day."
+
+---
+
+## What Gary Does (Recommended Practices)
+
+### Keeps the root file short — pointers, not prose
+A numbered decision tree the model walks:
+- Is it a person? → `/people/` directory
+- A company? → `/companies/` directory
+- A policy analysis? → `/civic/` directory
+
+20,000 lines of knowledge remains accessible *on demand* without polluting the context window. ~200 lines at the top; everything else lives in linked documents loaded only when relevant.
+
+### Mandates that every skill consult the resolver
+After catching a misfiling (see anti-patterns), he didn't patch skills one by one — he created a shared filing-rules document and a hard mandate. His actual two-line mandate, placed at the top of every brain-writing skill, verbatim:
+
+> *"Before creating any new brain page, read `brain/RESOLVER.md` and `skills/_brain-filing-rules.md`. File by primary subject, not by source format or skill name."*
+
+"One rule. Ten skills fixed." Result: **zero misfilings since.**
+
+### Maintains a disambiguation / filing-rules document
+A secondary doc (`_brain-filing-rules.md`) that catalogs edge cases and *past mistakes* so the same error can't recur a different way: Sources vs. originals. People vs. companies (when someone IS a company). Civic vs. sources (the misfiling that started it all).
+
+> "Every mistake, documented, so the same mistake can't happen a different way."
+
+### Tests the routing with trigger evals
+A suite of ~50 sample inputs with expected outputs. His actual examples:
+
+```
+Input: "check my signatures"      → Expected: executive-assistant (signature section)
+Input: "who is Pedro Franceschi"  → Expected: brain-ops → gbrain search
+Input: "save this article to brain" → Expected: idea-ingest + RESOLVER.md
+```
+
+Two failure modes he names:
+- **False negative** — skill should fire but doesn't (trigger description wrong/missing).
+- **False positive** — wrong skill fires (two triggers overlap).
+
+Both are fixable by editing markdown, no code changes. "The resolver is a document, and documents are cheap to fix." He is emphatic this is non-negotiable:
+
+> "If you can't prove the right skill fires for the right input, you don't have a system. You have a collection of skills and a prayer."
+
+### Audits reachability with a meta-skill (`check-resolvable`)
+A skill that walks the entire chain — AGENTS.md → skill file → code — to find dead links: skills that exist but have *no path* from the resolver at all. First run found **6 unreachable skills out of 40+ — 15% of capabilities were "dark."** Fixed in an hour by adding triggers. Now runs weekly.
+
+> "It's the resolver equivalent of a linter — it tells you what's broken before a user discovers it the hard way."
+
+### Plans for a self-healing resolver (the endgame)
+Forward-looking, not fully built. The idea (raised by a YC CTO in office hours): a reinforcement-learning loop that observes every task dispatch — which skill fired, which didn't, which had no match, which matched wrong — and periodically rewrites the resolver from observed evidence. "Not a human maintaining a table. The table maintaining itself." He notes Claude Code's AutoDream memory-consolidation system is a primitive version of this.
+
+> "A resolver that learns from its own traffic. That's the endgame for agent governance."
+
+---
+
+## What Gary Avoids (Anti-Patterns)
+
+### The 20,000-line CLAUDE.md
+The originating sin. Cramming every lesson and edge case into one file degrades attention, slows responses, and reduces precision. Signal you've gone too far: **the AI itself tells you to cut it back.**
+
+### Hardcoded filing logic inside skills
+The misfiling that revealed everything: he asked his agent to ingest Will Manidis's essay "No New Deal for OpenAI" — a sharp policy analysis. The agent filed it in `sources/` (meant for raw data dumps, CSVs, API exports, scrapes) instead of `civic/` (policy, political actors, institutional dynamics).
+
+Root cause: the idea-ingest skill had `brain/sources/` hardcoded as default. It never consulted the resolver.
+
+> "It had its own half-assed filing logic baked into the skill itself. When no explicit path was given, it fell back to `sources/` the way a lazy intern throws everything in the 'misc' folder."
+
+The audit that followed: **only 3 of 13 brain-writing skills referenced the resolver.** The other 10 had hardcoded paths — each "a potential misfiling waiting to happen." Fixing them individually is "whack-a-mole. You fix one, another drifts."
+
+### The slow, silent drift (not dramatic failure)
+The thing that actually kills agent systems:
+
+> "Not a dramatic failure. Not a hallucination that produces nonsense. A slow, silent drift where information goes to the wrong place, connections don't form, and the knowledge base gradually becomes a junk drawer with 14,700 files in it instead of a structured intelligence layer."
+
+### The invisible skill (capability that exists but can't be reached)
+His OpenClaw signature-tracking system "worked perfectly... Completely invisible." The resolver had no trigger for signatures, so "check my signatures" got a shrug.
+
+> "It's like having a surgeon on staff but not listing them in the hospital directory."
+
+Why this is *worse* than a missing skill:
+
+> "A missing skill is honest — the system says 'I can't do that' and you know to build it. A skill that exists but isn't reachable creates the illusion of capability. You think the system handles signatures. It doesn't. And you don't find out until the moment it matters."
+
+### Context rot — letting the resolver decay
+Resolvers decay even when built correctly. His timeline:
+- **Day 1** — perfect. Every skill registered, every trigger accurate.
+- **Day 30** — three new skills exist that nobody added (built by sub-agents at 3 AM).
+- **Day 60** — trigger descriptions don't match how users actually phrase things. Skill handles "track this flight"; user says "is my flight delayed?" — doesn't fire.
+- **Day 90** — the resolver is "a historical document. An artifact of what the system *used to* be able to do."
+
+The tell that you've drifted: invoking skills by direct instruction ("read skills/flight-tracker/SKILL.md") because the resolver lacks the right triggers.
+
+> "The system worked because I knew which skill to call. That's not a system. That's a person with a filing cabinet."
+
+### Filing by source format or skill name instead of by subject
+A recurring rule. Route by *primary subject*, never by how the data arrived or which skill produced it. (A policy analysis is `civic/` even though it was "imported," and even though the ingest skill defaults elsewhere.)
+
+---
+
+## Notable Quotes (verbatim, with context)
+
+- On the core failure: *"I wasn't [making it smarter]. I was drowning it."* — the thesis of the whole piece.
+- On the cure: *"You make them smarter by giving them the right book at the right moment."*
+- On the definition: *"A resolver is a routing table for context. When task type X appears, load document Y first."*
+- On the economics: *"The resolver is a document, and documents are cheap to fix."* — why routing problems are markdown edits, not retraining.
+- On testing: *"If you can't prove the right skill fires for the right input, you don't have a system. You have a collection of skills and a prayer."*
+- On hidden capability: *"It's like having a surgeon on staff but not listing them in the hospital directory."*
+- On reachability: *"Six. Out of 40+. Fifteen percent of the system's capabilities were dark."*
+- On drift: *"That's not a system. That's a person with a filing cabinet."*
+- On the real problem: *"The problem isn't that models aren't smart enough... we've been building organizations with no management layer."*
+- The closing call: *"The model isn't dumb. It's drowning. Give it a routing table and watch what happens."*
+
+---
+
+## Practical Takeaways (how to actually structure your CLAUDE.md)
+
+Distilled from Gary's pattern and the AI synthesis at the end of the source. Where these are the AI synthesis layer extending Gary, it's noted.
+
+1. **Aim for ~200 lines, not 20,000.** The root file triages and points; it does not teach. Think triage nurse / org chart.
+
+2. **Open with a hard mandate.** Forbid the model from inventing filing logic or guessing how to execute a complex task. Make it read the routing table and load the required doc *first*. *(AI synthesis example mandate, consistent with Gary's two-line brain mandate):*
+   > *"Before executing a task, creating a file, or running a skill, you MUST read this routing table and follow its paths. Do not rely on default behaviors or assumptions. File by primary subject as defined below, not by source format."*
+
+3. **Use a numbered decision tree of conditional pointers**, e.g.:
+   - If Task A → read `path/to/specific-skill.md`
+   - If Content B → save to `/specific-directory/`
+   - If Subject C → consult `_rules/subject-c-guidelines.md`
+
+4. **Separate two kinds of routing** (the fractal idea):
+   - **Task routing** (intent → skill file).
+   - **Filing routing** (content type → directory, by *subject* not format).
+
+5. **Isolate disambiguation into its own file** (`_filing-rules.md`). Catalog past mistakes and define boundary cases explicitly (Source vs. Original; when a Person is filed under Companies; Civic vs. Sources).
+
+6. **Test the routing.** Maintain a small eval suite of real-phrasing inputs → expected skill. Watch for false negatives (should-fire-but-doesn't) and false positives (wrong skill fires).
+
+7. **Audit reachability on a schedule.** Periodically verify every skill/path is reachable from the resolver and that trigger phrases match how you actually ask ("is my flight delayed?" not just "track this flight"). Treat dead links like a linter would.
+
+8. **Treat the resolver as living infrastructure.** It rots within ~90 days if untouched. Register new skills as they're born; update triggers to match real usage. The endgame is a resolver that rewrites itself from observed traffic.
+
+### A clean target shape (from the AI synthesis at the end of the source)
+
+```markdown
+# MASTER SYSTEM RESOLVER
+**CRITICAL MANDATE:** Do not invent filing logic. Do not guess how to execute a
+complex task. Before taking action, match the user's intent to the routing table
+below and read the required context document FIRST.
+
+## 1. Task Routing (Agents & Skills)
+* Signatures & Documents   -> Read `skills/executive-assistant/signatures.md`
+* Meeting Transcripts      -> Read `skills/ingest/meetings.md`
+* General Search / "Who is..." -> Read `skills/brain-ops/search.md`
+
+## 2. Filing Routing (Knowledge Base)  — route by SUBJECT, not file format
+* Is it a Person?            -> `/people/`
+* Is it a Company/Entity?    -> `/companies/`
+* Is it Policy/Political?    -> `/civic/`
+* Is it a Raw Data Dump?     -> `/sources/`
+
+## 3. Disambiguation & Rules
+If unsure where to route, or if categories overlap, you MUST read
+`_brain-filing-rules.md` to resolve the conflict before proceeding.
+```
+
+---
+
+## Source Attribution & Provenance Notes
+
+- **Primary source:** Gary's article *"Resolvers: The Routing Table for Intelligence"* (Resolver), a follow-up to his earlier *"Thin Harness, Fat Skills."* All quotes above are verbatim from that article unless flagged.
+- **Gary's own positions** (prioritized here): the 20,000-line confession, the resolver definition, the Manidis/`civic` misfiling, the 3-of-13 audit, the invisible signature skill, trigger evals, `check-resolvable` (6/40 dark), the 90-day context-rot timeline, the self-healing/RLM endgame, the "resolvers are fractal" and "management layer" reframes, and the open-source tools he ships these patterns in (GBrain — `gbrain init` scaffolds RESOLVER.md + decision tree + disambiguation rules + check-resolvable; GStack — the markdown coding-skill layer; OpenClaw/Hermes — the thin harness).
+- **AI synthesis layer** (the `assistant:` section at the end of the source): restates Gary's philosophy as a "route, don't explain" guideline and supplies the example mandate text and the "MASTER SYSTEM RESOLVER" template above. These are faithful extensions of Gary's points, not new claims — used here only as practical scaffolding.

package/skills/estack-claude-md-optimizer/references/theo_claude_md_mentality.md

@@ -0,0 +1,113 @@
+# Theo's Mentality for agent.md / CLAUDE.md Files
+
+A synthesis of Theo's (t3.gg) approach to writing, structuring, and maintaining context files for AI coding agents — `AGENTS.md`, `CLAUDE.md`, `agent.md` — based on his video **"How I Build with AI (Updated)"** ([youtube.com/watch?v=xJaMTo2YgO8](https://www.youtube.com/watch?v=xJaMTo2YgO8)).
+
+Context: He developed this view while building **Lakebed** (codename "span"), a from-scratch full-stack TypeScript framework/cloud, mostly solo, over ~5 days and 100+ agent threads. He used GPT-5.5 ("55") primarily, via the Codex app and T3 Code, and tested Cursor, Claude Code, and open code along the way. This document focuses narrowly on his agent-context-file philosophy, not the full workflow.
+
+---
+
+## Core Philosophy
+
+**The single most important thing in agentic coding is that the AI understands what you want and how you build — not what files to touch or how to implement.** The agent.md exists to transfer *your way of thinking* ("your psychosis," in his words) into the model so it stops making the same wrong assumptions. It is a steering document, not a specification or a rulebook.
+
+He frames it as a spectrum of ways to get the model aligned with you:
+1. Write a 5,000-line global agent.md describing everything you like and do.
+2. Be a famous influencer and just tell the model "I'm Theo, build the way I like" (works *sometimes*).
+3. **The easiest and best:** read the model's outputs and steer it conversationally; only when you see it making the *same mistake repeatedly* do you encode that correction into the agent.md.
+
+His big shift: he used to use a "big bloated useless agents MD." With GPT-5.5 in that bloated default state, "55 sucks." Once he condensed the file and made it about steering rather than rules, "it becomes the coolest way to work I've ever built with." The agent.md was one of the strongest things that let him build Lakebed so fast.
+
+---
+
+## Key Principles
+
+1. **Write it like a letter from you to the agent.** He wrote the Lakebed AGENTS.md "almost like a letter from me to the agent to tell it how we're thinking, what we're building, and why we're doing this." The goal: reduce bad assumptions, weird questions, and work that drifts outside his intended constraints.
+
+2. **Convey intent and "why," not file paths or implementation.** His Lakebed agent.md has **no file paths, no technical decisions, no enforcements.** Telling the model *what* to do and *why* beats telling it *how*. This mirrors how he prompts: high-level goal first, not implementation detail.
+
+3. **Encode corrections, not anticipations.** Don't pre-write rules for problems you imagine. When you "notice it making the same mistakes over and over again, go into the agent MD and try to give the model your psychosis." The file grows reactively from observed failures, not speculatively.
+
+4. **A glossary of terms is high-value.** This is his one concrete, strongly-endorsed structural element. On Lakebed the word "you/me/we/developers/agents" was genuinely ambiguous (he was both the builder and a user; agents built Lakebed and also used Lakebed). So he defined terms explicitly: *you* = the agent making changes; *me/we/us* = the humans building Lakebed; *developers* = end users building on Lakebed; *agents* = what those developers use. Purpose: "make it easier for the model to know what I'm referring to."
+
+5. **Keep it simple — and when simple fails, fix the obstacle, don't add complexity.** A recurring theme: "if it doesn't work, that doesn't mean make it more complex. It means fix the things that prevent it from being simple." If plain-language prompting isn't landing, the fix is a *small* agent.md/CLAUDE.md tweak so prompts can stay simple — not more verbose prompts and not a heavier rules file.
+
+6. **Write it by hand, yourself.** He emphasized twice: "my agents did not write this file. I wrote this file." The point of the document is to transfer *his* mental model, so the human has to author it.
+
+7. **Reinforce behavior through artifacts in the codebase, not just the agent.md.** Once the model behaves the way you want — via the agent.md, via well-formatted HTML plans it can copy, or via the existing code — "everything else almost stops mattering." The agent.md is one of several steering surfaces; consistency across them compounds.
+
+---
+
+## What Theo Does
+
+- Writes a short, prose, intent-driven AGENTS.md addressed *to* the agent, explaining the project's purpose, his mental model, and the constraints he wants respected.
+- Includes a **glossary** when terminology is ambiguous in the domain.
+- Keeps a couple of small general rules at the bottom — and is candid that he "might even delete them because I haven't found them to be super useful."
+- Authors and edits the file manually.
+- Updates it reactively, only after repeated observed mistakes, with the minimal addition needed to fix the recurring problem.
+- Uses it to keep prompts short — most of his actual prompts end up two sentences or less because the agent.md already carries the shared context.
+
+---
+
+## What Theo Avoids (Anti-Patterns)
+
+- **Bloated agent.md files.** The "big bloated useless agents MD" actively made GPT-5.5 worse. Size is a liability, not thoroughness.
+- **File paths in the agent.md (and in prompts).** "I trust the model to find the right file. I am more likely to recommend the wrong file than the model is half the time." A wrong path actively confuses the model into forcing changes in the wrong place.
+- **Technical decisions / hard enforcements baked into the file.** His Lakebed file has none.
+- **Over-engineered workflow scaffolding around the file.** When chat asked what skills/frameworks/"superpowers plugin" he used to get the model to behave: "No, you're all coping. You don't need all of that. I have almost zero skills installed. Just talk to the model. They're smart enough now." He keeps even his "grill me" prompt as a Whisper Flow text-expansion binding rather than an installed skill.
+- **Letting the agent write its own context file.** It defeats the purpose of transferring *your* thinking.
+- **Speculative rules.** Don't add detail "unless it needs the details." Be sparse; figure out what the model *doesn't* understand and fix only that.
+- **Adding complexity as a response to failure.** The instinct to get more specific/oversp­ecific is the wrong move; condense and steer instead.
+
+---
+
+## Notable Quotes (verbatim)
+
+> "The most important thing when you're building with AI is that the AI understands what you want and how you build."
+— His stated thesis for the whole topic; the agent.md is one tool for achieving it.
+
+> "If you notice it making the same mistakes over and over again, go into the agent MD and try to give the model your psychosis. That's what I've done. And I think that's one of the strongest things I did that made it possible for me to make this project so quickly."
+— On when and why to edit the file.
+
+> "You'll notice that in this Lakebed Agents MD, there are no file paths. There are no technical decisions or enforcements. There's a couple small general rules at the bottom that I might even delete because I haven't found them to be super useful."
+— Describing the actual contents of his file.
+
+> "I wrote this one almost like a letter from me to the agent to tell it how we're thinking, what we're building, and why we're doing this so that it's less likely to have bad assumptions or ask weird questions or work outside of the technical constraints that I want it to work within."
+— The format and intent.
+
+> "I noticed almost immediately after writing this — by hand, by the way, my agents did not write this file, I wrote this file — ... I didn't really have to do much to get the agent to build how I wanted it to. Once it had the context of how I was thinking about this, it started behaving way, way better."
+— On authoring it himself and the payoff.
+
+> "A glossary of terms and language to help the model understand what you're saying can be very, very helpful."
+— On the one structural element he explicitly recommends.
+
+> "Generally speaking, you should try to keep things simple. And if it doesn't work, that doesn't mean make it more complex. It means fix the things that prevent it from being simple. ... You should make slight changes to your agents MD and to your claude MD so that you can keep your prompt simple."
+— The simplicity principle applied directly to context files.
+
+> "Copying the prompts I used to use with the big bloated useless agents MD, 55 sucks. When you take the time to condense and steer it the way you want it to work, it becomes the coolest way to work I've ever built with."
+— Bloat vs. condensed, with a concrete before/after.
+
+> "No, you're all coping. You don't need all of that. I have almost zero skills installed. Just talk to the model. They're smart enough now."
+— Pushing back on skills/plugins/frameworks as a substitute for plain steering.
+
+> "Once you get the agent to behave how you want — if there is enough proof of that behavior in your codebase, whether that is HTML plans, whether that is your agents MD steering it certain ways, whether it's the code itself — once you get the model to behave how you want it to, everything else almost stops mattering."
+— The agent.md as one of several reinforcing steering surfaces.
+
+> "I trust the model to find the right file. I am more likely to recommend the wrong file than the model is half the time."
+— Why no file paths.
+
+---
+
+## Practical Takeaways
+
+1. **Default to no agent.md, then earn it.** Start by just talking to the model. Add to the file only when a mistake recurs.
+2. **Write prose, addressed to the agent, about purpose and mindset** — not specs, not paths, not enforcement.
+3. **Add a glossary** the moment your domain has ambiguous or overloaded terms.
+4. **Keep it short.** Bloat measurably degrades model behavior. Condensing is an active improvement, not just tidiness.
+5. **Author it by hand.** The file's job is to transmit your thinking; don't outsource that to the agent.
+6. **Use the agent.md to shrink your prompts.** If you're writing long, over-specified prompts, that's a signal to make a small context-file change — not to write longer prompts.
+7. **Don't reach for skills/plugins/frameworks first.** Treat them as last resorts; modern models respond to plain conversational steering plus a lean context file.
+8. **Stay reactive and minimal.** Don't anticipate; fix what you actually observe, with the smallest change that works. Be willing to delete rules that aren't pulling weight.
+
+---
+
+*Source: Theo (t3.gg), "How I Build with AI (Updated)," https://www.youtube.com/watch?v=xJaMTo2YgO8. All quotes transcribed from the video's auto-transcript; minor verbal artifacts and censored profanity have been smoothed for readability without changing meaning.*

package/skills/estack-claude-md-optimizer/routes/create.md

@@ -0,0 +1,84 @@
+# Route: Create — bootstrap the initial letter
+
+You are here because no CLAUDE.md or AGENTS.md exists in the target project.
+Verify that first (project root and obvious parents). If one exists, switch to
+`refine.md` instead — unless refine sent you here because the existing file has
+no letter spine; in that case run the interview below and hand the drafted
+letter back to refine's flow.
+
+The goal is a short letter from the user to the agent. They author it through an
+interview; you transcribe and shape, in their phrasing. You never substitute
+codebase analysis for their answers.
+
+## Step 1 — Investigate quietly, then interview freehand-first
+
+Before asking anything, investigate the repo yourself: README, docs, notes,
+recent git history, the existing CLAUDE.md if refine sent you here. Form your
+own candidate answers for each interview area — intent, constraints, ambiguous
+terms, boundaries. **Do not show these yet.**
+
+Open the interview by telling the user the plan, so they answer freely instead
+of dictating what's already written down: *"Answer freehand — don't worry about
+repeating things that are already in the repo or the old file; I've scanned
+those and will show you what I found after your answers, to build on or
+correct."*
+
+Ask at most a handful of questions, batched 2–3 at a time, covering four areas:
+
+1. **Intent** — What is this project, and why does it exist? What does done or
+   good look like to you?
+2. **Mental model** — How do you think about building it? What do you care about
+   most, and what constraints matter (taste, priorities, trade-offs you've
+   already decided)?
+3. **Glossary candidates** — Are any words in this domain ambiguous or overloaded?
+   (Terms that mean something specific here, names that collide, "you/we/users"
+   confusion.)
+4. **Hard boundaries** — What is off-limits without your explicit permission?
+
+This is not project discovery. Do not ask about stack, file structure, build
+commands, or architecture — the agent can find those itself, and wrong paths
+mislead more than they help. Only include such details if the user raises them
+unprompted.
+
+If an answer is thin, ask one focused follow-up, then move on. Total questions
+should stay in single digits.
+
+## Step 1.5 — Surface what you found
+
+After the freehand answers, show your investigation candidates, grouped by the
+same four areas — only the ones they *didn't* already cover: "Here's what I found
+in the repo that you didn't mention — build on it, correct it, or cut it." If
+refine sent you here, this is also where the valuable lines from the old file
+resurface as candidates (real intent buried in rules, gotchas earned by past
+pain) so the user never has to re-dictate what was already written. Each candidate
+they confirm becomes draftable; its trace is their confirmation. Anything they
+don't confirm stays out.
+
+## Step 2 — Draft
+
+Synthesize their answers into a draft letter:
+
+- Prose, addressed to the agent ("This project is… What I care about is… Don't…").
+- Their phrasing — lift their actual words and rhythms from the interview. If you
+  smooth something, keep their vocabulary.
+- A glossary section only if step 1 surfaced genuinely ambiguous terms.
+- No file paths, no enforcement language, no rules for problems they haven't hit.
+- Short. A new letter has earned almost nothing yet — most letters start well
+  under 40 lines and grow reactively from observed mistakes. Never pad toward
+  the 150 cap.
+
+Every line must trace to something the user said. If you find yourself writing a
+line they didn't give you, cut it or ask.
+
+## Step 3 — Line-by-line approval
+
+Present the full draft first so the user sees the shape. Then walk it line by line
+(or paragraph by paragraph for flowing prose): for each, they approve, reword,
+or cut. Apply their rewording verbatim — do not "improve" it back.
+
+## Step 4 — Write
+
+Only after every line is approved, write the file to the project root as
+`CLAUDE.md` (or `AGENTS.md` if the user prefers — ask once). Confirm the final line
+count. Remind them, once, that the letter grows reactively: when the agent makes
+the same mistake twice, that's when the next line gets earned.

package/skills/estack-claude-md-optimizer/routes/refine.md

@@ -0,0 +1,69 @@
+# Route: Refine — audit an existing file letter-style
+
+You are here because a CLAUDE.md/AGENTS.md exists and the user wants it audited or
+improved. The audit is letter-style: does each line transfer intent they actually
+hold, or is it noise? No rubrics, no grades, no template sections.
+
+## Step 0 — Is this even a letter?
+
+Read the whole file first and judge its shape. If it has no prose-intent spine —
+it's a command list, template sections, a routing table, or rule soup — line
+edits can't fix it, because there is no letter to refine. Say so, then:
+
+1. Run the interview from `routes/create.md` to author the missing letter spine
+   (the user's answers, their phrasing — the existing file is not a substitute,
+   but it IS a hint source: mine it for genuinely valuable content — real intent
+   buried in rules, gotchas earned by past pain — and surface those as
+   candidates in create's Step 1.5 so the user confirms rather than re-dictates).
+2. Return here and classify every existing line against that new spine: most
+   become DELETE or RE-VOICE (folded into the letter); KEEP only what traces.
+3. Any existing routing section must pass the bar in `routes/scale-check.md`
+   or be proposed for deletion with the rest.
+
+The pass is not done until the final file is a letter that passes the hard
+rules — that is the finish line for every route, whatever was asked.
+
+## Step 1 — Read and classify every line
+
+Read the whole file. Tag each line (or tight group of lines) with exactly one:
+
+- **KEEP** — traces to intent or a known recurring mistake, current, voiced as
+  intent. Leave it alone.
+- **DELETE** — propose removal. Triggers: generic advice any model already knows;
+  restates what the code shows; speculative rule for a problem never observed;
+  stale (references things that no longer exist, commands that no longer work);
+  one-off fix that never recurred; duplicate; a rule whose "why" nobody can state.
+- **RE-VOICE** — the underlying intent is real but it's written as enforcement
+  ("ALWAYS/NEVER do X") or as a bare mechanic. Rewrite as intent with its why
+  ("I care about X because Y") — usually shorter, always more transferable.
+- **ASK** — you can't tell whether it traces. Don't guess; queue a question.
+
+File paths get special suspicion: the model finds files better than stale paths
+do. Propose deleting paths unless the user states a live reason to keep one.
+
+## Step 2 — Ask the queued questions
+
+Batch the ASK items (2–5 at a time): "This line says X — what's the why? Is it
+still true? Has the mistake it guards against actually recurred?" A line whose
+why the user can't state becomes a DELETE proposal — Theo deletes rules that
+aren't pulling weight, and so does this skill.
+
+## Step 3 — Propose the edit set, deletions first
+
+Deletions are mandatory in every refine pass — if you found none, you didn't
+audit, you skimmed. Present in this order:
+
+1. **Deletions** — quoted line + one-line reason each.
+2. **Re-voicings** — before → after, one-line why.
+3. **Additions** — rare, only for a recurring mistake the user names during this
+   audit, in their phrasing. Never additions to "round out" the file.
+
+Show the net line count: before → after. It should usually go down. If the file
+is over 150 lines, the pass is not done until it's under; if an addition would
+cross 150, pair it with a removal or drop it.
+
+## Step 4 — Approve and apply
+
+Walk the edit set change by change. Apply only what the user approves, with their
+rewordings verbatim. Edit the file, then report the final shape: line count,
+what was cut, what survived.

package/skills/estack-claude-md-optimizer/routes/scale-check.md

@@ -0,0 +1,56 @@
+# Route: Scale check — has this project outgrown a pure letter?
+
+You are here to judge whether a project has genuinely outgrown a plain letter
+and earned a routing section — Gary's resolver idea, applied only when scale
+demands it. The default verdict is **not yet**. A short letter plus model
+intelligence covers most projects; routing structure added early is bloat
+wearing a uniform.
+
+## Step 1 — Gather the scale signals
+
+Look at the project (this part IS codebase analysis — allowed here because you
+are assessing structure, not authoring letter content):
+
+- Project-level skills: count entries in `.claude/skills/`.
+- Subagents: count entries in `.claude/agents/`.
+- Domain subdirectories with their own conventions or their own CLAUDE.md files.
+- Standing docs the agent repeatedly needs (filing rules, domain references).
+- **Observed misrouting** — the strongest signal, and it comes from the user, not
+  the file tree: the agent repeatedly picking the wrong skill, wrong directory,
+  or wrong doc; or the user invoking things by explicit path because intent alone
+  doesn't land. Ask them directly whether they've seen this.
+
+## Step 2 — Verdict
+
+**Not yet** (the common case): a handful of skills, no repeated misrouting, the
+letter is doing its job. Say so, name the signals you'd want to see before
+revisiting (e.g. "if you catch the agent filing X into Y twice, come back"),
+and stop. Do not propose routing "to be safe."
+
+**Earned**: multiple independent signals — meaningful skill/subagent count AND
+repeated misrouting the user has actually observed, or several domains with
+conventions the agent keeps missing. Be explicit about which signals tipped it.
+
+## Step 3 — If earned, propose a lean routing section
+
+The letter stays the spine; routing is a section appended to it, never a
+replacement and never a rewrite of the prose.
+
+- A short numbered list of conditional pointers: "task/content type → read/file
+  here." Route, don't explain — pointers carry no instruction content themselves.
+- Route by primary subject, not by source format or which tool produced the thing.
+- Only include routes for *observed* traffic: tasks and content types that have
+  actually occurred. No speculative rows.
+- It counts against the 150-line cap like everything else. A routing section is
+  typically 10–20 lines; if it wants to be more, the project needs its own
+  routing doc the section points to, not a longer section.
+
+Present the draft section with the trace for each row (which observed signal
+earned it). Line-by-line approval, then apply.
+
+## Step 4 — Note the decay
+
+Routing rots as skills change (~90 days untouched and it's a historical
+document). When a routing section ships, tell the user once: re-run this scale
+check when skills are added or when they catch themselves invoking things by
+explicit path again.

package/skills/estack-claude-md-optimizer/routes/session-capture.md

@@ -0,0 +1,70 @@
+# Route: Session capture — earn a line from a real session
+
+## Quick capture — mid-task, triggered by the maintenance footer
+
+If you are here because a working agent (you, mid-task) noticed something the
+letter should learn — new or ambiguous vocab, a repeated correction, drifted
+intent or routing — do NOT run the full flow below. The capture must not derail
+the task at hand, and must not be lost either:
+
+1. One line to the user: what you noticed + the proposed minimal change, in
+   their words. No opening message, no progress headers.
+2. Approved? Apply immediately — cap check, footer intact. If it takes less
+   than 5 minutes, do it now; deferring is how improvements get forgotten.
+3. Declined, or the user is heads-down? Note it (a TODO, a scratch line —
+   anywhere durable) and re-raise it at session end through the full flow.
+4. Return to the interrupted task immediately. The capture is a pit stop,
+   not a detour.
+
+Everything below is the full end-of-session flow.
+
+---
+
+You are here at the end of a working session, asked to capture learnings into
+the CLAUDE.md. The letter grows reactively: only a *recurring* mistake earns a
+line. One-off mistakes earn nothing — and "nothing to add" is the most common
+correct outcome of this route. Say it plainly when it's true.
+
+## Step 1 — Mine the session for corrections
+
+Scan this session for moments where the user corrected the agent: redirected an
+assumption, rejected an approach, repeated an instruction, expressed frustration,
+or re-explained intent the agent should have had. Each correction is a candidate.
+Discoveries that aren't corrections (a command that worked, a quirk found) are
+NOT candidates — that's the official plugin's instinct, not this skill's. The
+letter carries intent, not session notes.
+
+## Step 2 — Filter: recurring or one-off?
+
+A candidate is **recurring** only if at least one holds:
+
+- The user corrected the same thing more than once *this* session.
+- The existing CLAUDE.md already gestures at it and the agent still got it wrong
+  (the line isn't landing — a rewording problem, not an addition problem).
+- The user confirms it's a repeat from earlier sessions. When unsure, ask exactly
+  that: "Has the agent gotten this wrong before, or was today the first time?"
+
+Everything else is one-off. List one-offs in a sentence ("watching, not writing:
+X, Y") so the user knows they were seen, and propose nothing for them.
+
+## Step 3 — Propose the minimal fix
+
+For each recurring mistake (usually zero or one per session):
+
+- First check whether a **deletion or rewording** of an existing line fixes it
+  better than an addition — a line that misled the agent should be cut, not
+  counter-weighted with a second line.
+- If an addition is right, it is the *smallest* line that transfers the intent:
+  usually one sentence, voiced as why, built from the user's own correction words
+  in the session. Not a rule, not an enforcement, no file paths.
+- Check the cap: if the file is at 150 lines, pair the addition with a proposed
+  removal or don't propose it.
+
+Present as: the mistake (with where it happened), why it qualifies as recurring,
+the proposed change as a diff, and the trace ("your words: '…'").
+
+## Step 4 — Approve and apply
+
+The user approves, rewords, or rejects each proposal; apply only approved changes,
+their rewording verbatim. If nothing qualified, end with: "No recurring mistake
+this session — the letter stands."

package/skills/estack-flight-planner/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: estack-flight-planner
-version: 1.0.2
+version: 1.0.3
 description: (flight-planner) Find and rank flights between any two airports with config-driven preferences (budget, airlines, nonstop, time-of-day) and optional ground-shuttle pairing. Uses SerpAPI Google Flights (or WebSearch fallback). Saves preferences to `~/.flight-planner/config.json` and logs every search.
 disable-model-invocation: true
 ---
@@ -312,7 +312,7 @@ If the user doesn't have a SerpAPI key and asks for help getting one:
 2. Walk them to https://serpapi.com/users/sign_up — sign up with email.
 3. After signup, the API key is at https://serpapi.com/manage-api-key.
 4. To set it permanently, walk them through either:
-   - Saving it in their flight-planner config (`serpapi_key` field), or
+   - Saving it in their `~/.flight-planner/config.json` (`serpapi_key` field), or
    - Setting `SERPAPI_KEY` as an environment variable in their shell profile.
 5. If they don't want a key: confirm they want the WebSearch fallback. Set `serpapi_key: null` in config. Tell them: "I'll use WebSearch each run. Results won't be as complete and prices may be approximations."
 

package/skills/estack-flight-planner/scripts/fetch_flights.py

@@ -35,7 +35,7 @@ BASE_PARAMS = {
 
 
 def default_output_dir() -> Path:
-    base = Path(tempfile.gettempdir()) / "flight-planner"
+    base = Path(tempfile.gettempdir()) / "estack-flight-planner"
     base.mkdir(parents=True, exist_ok=True)
     return base
 

package/skills/estack-flight-planner/scripts/filter_flights.py

@@ -13,10 +13,10 @@ price distribution. The skill uses this to propose specific relaxations when
 hard filters return zero results.
 
 Usage:
-    python filter_flights.py --json-dir /tmp/flight-planner/ --max-price 200 --from IND --to EWR
-    python filter_flights.py --json-dir /tmp/flight-planner/ --max-price 200 \\
+    python filter_flights.py --json-dir /tmp/estack-flight-planner/ --max-price 200 --from IND --to EWR
+    python filter_flights.py --json-dir /tmp/estack-flight-planner/ --max-price 200 \\
         --soft-filters max-price,time-priority
-    python filter_flights.py --json-dir /tmp/flight-planner/ --cluster-analysis
+    python filter_flights.py --json-dir /tmp/estack-flight-planner/ --cluster-analysis
 
 All filter args (--max-price, --time-priority, --from, --to, --airlines, --nonstop)
 are required for normal filter mode (no defaults — caller passes config values).
@@ -192,7 +192,7 @@ def cluster_analysis(flights, max_price, bands, origins, dests, airlines, nonsto
 
 def main() -> int:
     p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    default_dir = Path(tempfile.gettempdir()) / "flight-planner"
+    default_dir = Path(tempfile.gettempdir()) / "estack-flight-planner"
     p.add_argument("--json-dir", default=str(default_dir))
     p.add_argument("--max-price", type=int, default=None,
                    help="Max price in USD. Omit for no price filter.")

package/skills/estack-github-issue-tracker/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: estack-github-issue-tracker
-version: 1.0.2
+version: 1.0.3
 description: >
   (github-issue-tracker) GitHub issue tracker management. Checks all open issues the user is involved in,
   finds related/duplicate issues, reports what changed, and recommends next steps.

package/skills/estack-github-issue-tracker/bin/tracker-tools.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * tracker-tools.cjs — Data service layer for github-issue-tracker skill.
+ * tracker-tools.cjs — Data service layer for estack-github-issue-tracker skill.
  *
  * Commands:
  *   startup --tracker <path>              Auth, parse tracker + config, create temp dir, discover issues

package/skills/estack-read-claude-session-history/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: estack-read-claude-session-history
-version: 1.0.2
+version: 1.0.3
 description: (read-claude-session-history) Invoke for ANY task involving Claude Code session history, transcripts, or .jsonl files — this is the only way to read, parse, or search them; do not attempt to use Bash or Read on .jsonl directly. Use for: recovering context after /compact ("what were we doing before compact"), advisor response retrieval ("what did the advisor say"), subagent output collection ("get all subagent finals"), cross-project session search by keyword, session listing and triage, UUID and title lookup, resume-command generation, file-edit and tool-call forensics, session diff between two sessions or subagents, weekly work journal, day timeline of activity blocks and idle gaps, engagement/attention-time accounting (active vs elapsed time, break detection, parallel-chat-safe totals), recovering from .claude-backups after data loss, session count queries, and reading the last agent message before a crash or interrupt. Trigger phrases: "session history", "before compact", "what did claude do", "what did I work on", "search my sessions", "find that session", "what did the advisor say", "what did the agent edit", "from the backup", "list my sessions", "subagent outputs", "session journal", "resume previous", "which files did claude touch", "go back and look", "what did I do yesterday", "where did my day go", "timeline of my day", "how much time on", "how long did that actually take", "how much did I actually work", "active time", "time I spent".
 ---
 
@@ -13,7 +13,7 @@ Sessions are stored as `.jsonl` files. Reading them raw is hopeless: 1,000–5,0
 ## Quick start
 
 ```bash
-PY="C:\Users\2supe\.claude\skills\read-claude-session-history\scripts\read_transcript.py"
+PY="$HOME/.claude/skills/estack-read-claude-session-history/scripts/read_transcript.py"
 
 # What was the last thing the agent said in this session?
 python "$PY" --file <current-session.jsonl> --mode last

package/skills/estack-read-claude-session-history/references/recipes.md

@@ -4,7 +4,7 @@ Multi-step workflows. For per-mode flag reference, see `modes.md`. For schema, s
 
 In all examples, `$PY` refers to:
 ```
-C:\Users\2supe\.claude\skills\read-claude-session-history\scripts\read_transcript.py
+~/.claude/skills/estack-read-claude-session-history/scripts/read_transcript.py
 ```
 
 ---