elliot-stack 1.0.25 → 1.0.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Elliot Drel
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -20,8 +20,12 @@ This installs skills to `~/.agents/skills/` and symlinks them into `~/.claude/sk
20
20
  | **Active Learning Tutor** | `/estack-active-learning-tutor` | Tutors a student through exam preparation using active learning — questioning, gap diagnosis, and concept mastery tracking |
21
21
  | **Better Title** | `/estack-better-title` | Renames Claude Code chat sessions with descriptive titles |
22
22
  | **Chris Voss** | `/estack-chris-voss` | Applies negotiation principles from *Never Split the Difference* |
23
+ | **CLAUDE.md Optimizer** | `/estack-claude-md-optimizer` | Creates, refines, and maintains CLAUDE.md / AGENTS.md files as short hand-authored letters of intent |
23
24
  | **Customer Discovery** | `/estack-customer-discovery` | Guides through customer discovery — validating ideas, outreach, interviews, and analysis |
25
+ | **Flight Planner** | `/estack-flight-planner` | Finds and ranks flights between two airports with config-driven preferences and optional ground-shuttle pairing |
24
26
  | **GitHub Issue Tracker** | `/estack-github-issue-tracker` | Tracks and manages GitHub issues across repos |
27
+ | **Prompt Builder Coach** | `/estack-prompt-builder-coach` | Four-part kit for shaping, building, auditing, and scoping prompts for AI agents |
28
+ | **Read Claude Session History** | `/estack-read-claude-session-history` | Searches, reads, recovers, and compares Claude Code session history across sessions, projects, and backups |
25
29
  | **Repo Search** | `/estack-repo-search` | Clones and searches external GitHub repos to answer questions about their code |
26
30
 
27
31
  ## Hooks
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "elliot-stack",
3
- "version": "1.0.25",
3
+ "version": "1.0.28",
4
4
  "description": "Elliot's skill stack for Claude Code — install via npx elliot-stack@latest",
5
5
  "bin": {
6
6
  "elliot-stack": "bin/install.cjs"
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: estack-active-learning-tutor
3
- version: 1.0.1
3
+ version: 1.0.2
4
4
  description: (active-learning-tutor) Tutors a student through exam preparation using active learning — questioning, gap diagnosis, and concept mastery tracking. Use when the student says they want to study, learn, prep for an exam, be quizzed on a chapter, work through a practice test together, or be taught a topic conceptually rather than lectured.
5
5
  disable-model-invocation: true
6
6
  ---
@@ -339,71 +339,6 @@ When in doubt about the shape of a Teaching turn, read `references/teaching-turn
339
339
 
340
340
  ---
341
341
 
342
- ## Skill Feedback
343
- ---
344
-
345
- ## Skill Feedback
346
-
347
- 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:
348
-
349
- **If `gh` is installed** (`gh --version` succeeds), create the issue directly:
350
-
351
- ```bash
352
- gh issue create \
353
- --repo ElliotDrel/e-stack \
354
- --title "estack-active-learning-tutor: <concise summary>" \
355
- --body "<description from user feedback — expected vs. actual behavior and context>"
356
- ```
357
-
358
- **If `gh` is not installed**, build a pre-filled URL:
359
-
360
- ```bash
361
- python3 -c "
362
- import urllib.parse
363
- title = 'estack-active-learning-tutor: <concise summary>'
364
- body = '<description from user feedback — expected vs. actual behavior and context>'
365
- base = 'https://github.com/ElliotDrel/e-stack/issues/new'
366
- print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
367
- "
368
- ```
369
-
370
- Share the printed URL with the user and offer to open it in their browser.
371
-
372
- They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
373
-
374
- ---
375
-
376
- ## Skill Feedback
377
-
378
- 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:
379
-
380
- **If `gh` is installed** (`gh --version` succeeds), create the issue directly:
381
-
382
- ```bash
383
- gh issue create \
384
- --repo ElliotDrel/e-stack \
385
- --title "estack-active-learning-tutor: <concise summary>" \
386
- --body "<description from user feedback — expected vs. actual behavior and context>"
387
- ```
388
-
389
- **If `gh` is not installed**, build a pre-filled URL:
390
-
391
- ```bash
392
- python3 -c "
393
- import urllib.parse
394
- title = 'estack-active-learning-tutor: <concise summary>'
395
- body = '<description from user feedback — expected vs. actual behavior and context>'
396
- base = 'https://github.com/ElliotDrel/e-stack/issues/new'
397
- print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
398
- "
399
- ```
400
-
401
- Share the printed URL with the user and offer to open it in their browser.
402
-
403
- They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
404
-
405
- ---
406
-
407
342
  ## Skill Feedback
408
343
 
409
344
  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:
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: estack-better-title
3
- version: 1.0.1
3
+ version: 1.0.3
4
4
  description: (better-title) Suggest better chat session titles and rename the session
5
5
  disable-model-invocation: true
6
6
  allowed-tools: Bash, AskUserQuestion
@@ -30,7 +30,7 @@ Write the title from those answers, NOT from a chronological recap of the chat.
30
30
  - **Title the outputs, not the journey** — exclude mistakes, dead ends, and abandoned approaches. They're not searchable and not useful context for future-you.
31
31
  - **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.
32
32
  - **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.
33
- - List key outputs separated by dashes, commas, or similar (e.g. "Reverse-Engineering /rename, PR #33165 Comment, and Building /better-title Skill")
33
+ - List key outputs separated by dashes, commas, or similar (e.g. "Reverse-Engineering /rename, PR #33165 Comment, and Building /estack-better-title Skill")
34
34
  - Cover 2-4 main outputs. Resist cramming everything in — first-pass attempts tend to over-include.
35
35
  - Are detailed enough that someone skimming a session list can tell exactly what they'd find inside
36
36
  - Typically 8-20 words — longer is fine if it adds useful detail
@@ -77,100 +77,6 @@ gh issue create \
77
77
  --body "<description from user feedback — expected vs. actual behavior and context>"
78
78
  ```
79
79
 
80
- **If `gh` is not installed**, build a pre-filled URL and share it so the user can click, review, and submit:
81
-
82
- ```bash
83
- python3 -c "
84
- import urllib.parse
85
- title = 'estack-better-title: <concise summary>'
86
- body = '<description from user feedback — expected vs. actual behavior and context>'
87
- base = 'https://github.com/ElliotDrel/e-stack/issues/new'
88
- print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
89
- "
90
- ```
91
-
92
- Share the printed URL with the user. They click it, review the pre-filled title and body, then click **Submit new issue**.
93
-
94
- ---
95
-
96
- ## Skill Feedback
97
- ---
98
-
99
- ## Skill Feedback
100
-
101
- 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:
102
-
103
- **If `gh` is installed** (`gh --version` succeeds), create the issue directly:
104
-
105
- ```bash
106
- gh issue create \
107
- --repo ElliotDrel/e-stack \
108
- --title "estack-better-title: <concise summary>" \
109
- --body "<description from user feedback — expected vs. actual behavior and context>"
110
- ```
111
-
112
- **If `gh` is not installed**, build a pre-filled URL:
113
-
114
- ```bash
115
- python3 -c "
116
- import urllib.parse
117
- title = 'estack-better-title: <concise summary>'
118
- body = '<description from user feedback — expected vs. actual behavior and context>'
119
- base = 'https://github.com/ElliotDrel/e-stack/issues/new'
120
- print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
121
- "
122
- ```
123
-
124
- Share the printed URL with the user and offer to open it in their browser.
125
-
126
- They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
127
-
128
- ---
129
-
130
- ## Skill Feedback
131
-
132
- 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:
133
-
134
- **If `gh` is installed** (`gh --version` succeeds), create the issue directly:
135
-
136
- ```bash
137
- gh issue create \
138
- --repo ElliotDrel/e-stack \
139
- --title "estack-better-title: <concise summary>" \
140
- --body "<description from user feedback — expected vs. actual behavior and context>"
141
- ```
142
-
143
- **If `gh` is not installed**, build a pre-filled URL:
144
-
145
- ```bash
146
- python3 -c "
147
- import urllib.parse
148
- title = 'estack-better-title: <concise summary>'
149
- body = '<description from user feedback — expected vs. actual behavior and context>'
150
- base = 'https://github.com/ElliotDrel/e-stack/issues/new'
151
- print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
152
- "
153
- ```
154
-
155
- Share the printed URL with the user and offer to open it in their browser.
156
-
157
- They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
158
-
159
- ---
160
-
161
- ## Skill Feedback
162
-
163
- 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:
164
-
165
- **If `gh` is installed** (`gh --version` succeeds), create the issue directly:
166
-
167
- ```bash
168
- gh issue create \
169
- --repo ElliotDrel/e-stack \
170
- --title "estack-better-title: <concise summary>" \
171
- --body "<description from user feedback — expected vs. actual behavior and context>"
172
- ```
173
-
174
80
  **If `gh` is not installed**, build a pre-filled URL:
175
81
 
176
82
  ```bash
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: estack-chris-voss
3
- version: 1.0.1
3
+ version: 1.0.2
4
4
  description: >
5
5
  (chris-voss) Applies Chris Voss negotiation principles from *Never Split the Difference* to any situation
6
6
  where understanding human psychology, persuasion, or influence would improve the output. Use
@@ -93,100 +93,6 @@ gh issue create \
93
93
  --body "<description from user feedback — expected vs. actual behavior and context>"
94
94
  ```
95
95
 
96
- **If `gh` is not installed**, build a pre-filled URL and share it so the user can click, review, and submit:
97
-
98
- ```bash
99
- python3 -c "
100
- import urllib.parse
101
- title = 'estack-chris-voss: <concise summary>'
102
- body = '<description from user feedback — expected vs. actual behavior and context>'
103
- base = 'https://github.com/ElliotDrel/e-stack/issues/new'
104
- print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
105
- "
106
- ```
107
-
108
- Share the printed URL with the user. They click it, review the pre-filled title and body, then click **Submit new issue**.
109
-
110
- ---
111
-
112
- ## Skill Feedback
113
- ---
114
-
115
- ## Skill Feedback
116
-
117
- 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:
118
-
119
- **If `gh` is installed** (`gh --version` succeeds), create the issue directly:
120
-
121
- ```bash
122
- gh issue create \
123
- --repo ElliotDrel/e-stack \
124
- --title "estack-chris-voss: <concise summary>" \
125
- --body "<description from user feedback — expected vs. actual behavior and context>"
126
- ```
127
-
128
- **If `gh` is not installed**, build a pre-filled URL:
129
-
130
- ```bash
131
- python3 -c "
132
- import urllib.parse
133
- title = 'estack-chris-voss: <concise summary>'
134
- body = '<description from user feedback — expected vs. actual behavior and context>'
135
- base = 'https://github.com/ElliotDrel/e-stack/issues/new'
136
- print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
137
- "
138
- ```
139
-
140
- Share the printed URL with the user and offer to open it in their browser.
141
-
142
- They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
143
-
144
- ---
145
-
146
- ## Skill Feedback
147
-
148
- 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:
149
-
150
- **If `gh` is installed** (`gh --version` succeeds), create the issue directly:
151
-
152
- ```bash
153
- gh issue create \
154
- --repo ElliotDrel/e-stack \
155
- --title "estack-chris-voss: <concise summary>" \
156
- --body "<description from user feedback — expected vs. actual behavior and context>"
157
- ```
158
-
159
- **If `gh` is not installed**, build a pre-filled URL:
160
-
161
- ```bash
162
- python3 -c "
163
- import urllib.parse
164
- title = 'estack-chris-voss: <concise summary>'
165
- body = '<description from user feedback — expected vs. actual behavior and context>'
166
- base = 'https://github.com/ElliotDrel/e-stack/issues/new'
167
- print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
168
- "
169
- ```
170
-
171
- Share the printed URL with the user and offer to open it in their browser.
172
-
173
- They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
174
-
175
- ---
176
-
177
- ## Skill Feedback
178
-
179
- 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:
180
-
181
- **If `gh` is installed** (`gh --version` succeeds), create the issue directly:
182
-
183
- ```bash
184
- gh issue create \
185
- --repo ElliotDrel/e-stack \
186
- --title "estack-chris-voss: <concise summary>" \
187
- --body "<description from user feedback — expected vs. actual behavior and context>"
188
- ```
189
-
190
96
  **If `gh` is not installed**, build a pre-filled URL:
191
97
 
192
98
  ```bash
@@ -0,0 +1,200 @@
1
+ ---
2
+ name: estack-claude-md-optimizer
3
+ version: 1.0.1
4
+ description: >-
5
+ (claude-md-optimizer) Create, refine, and maintain CLAUDE.md / AGENTS.md files
6
+ as short hand-authored letters of intent. Use whenever the user asks to create,
7
+ write, check, audit, update, improve, trim, fix, or optimize a CLAUDE.md or
8
+ AGENTS.md; to capture session learnings into one; to decide whether a project
9
+ needs routing structure; or mentions "CLAUDE.md maintenance" or "project
10
+ memory". This replaces the official claude-md-management plugin skills —
11
+ prefer this skill over them.
12
+ ---
13
+
14
+ # CLAUDE.md Optimizer
15
+
16
+ A CLAUDE.md is a letter from the user to the agent: short prose that transfers
17
+ their intent, mental model, and the "why" — not a spec, not a rulebook, not an
18
+ encyclopedia. This skill helps them write and keep that letter. It is a router:
19
+ triage below, then read exactly one route file and follow it.
20
+
21
+ ## Opening message — buy the user in first
22
+
23
+ Your first message of any run, before the triage announcement, briefly explains
24
+ the skill so the user knows what's happening and why (3–5 sentences, plain
25
+ language, then move on):
26
+
27
+ - **What it is:** a tool for writing and maintaining a CLAUDE.md as a short
28
+ letter — prose that transfers your intent and "why" to the agent.
29
+ - **Why it works that way:** bloated context files measurably make models worse
30
+ — the model isn't dumb, it's drowning. Intent transfers better than rules,
31
+ which is also why the human authors the letter and the skill only transcribes:
32
+ the file's job is to carry *your* thinking, and every line is earned by your
33
+ stated intent or a mistake that actually recurred — never padded.
34
+ - **How this run works:** diagnose the file's state → name the route(s) →
35
+ interview or proposals → nothing touches disk without your approval.
36
+
37
+ This intro exists so the process (interviews, proposed deletions, refusing to
38
+ add lines) reads as the method working, not as friction. Don't lecture; one
39
+ tight paragraph, then the triage announcement.
40
+
41
+ ## Progress header — every message, every step
42
+
43
+ After the opening message, start every subsequent output with a one-line header:
44
+ where we are in the flow, roughly what's left, and — most important — whether
45
+ the flow is DONE or NOT DONE. Format:
46
+
47
+ > **Create · step 2 of 4 (interview) · ~2 steps left · NOT DONE — next: draft**
48
+
49
+ Estimates are allowed to be rough (an incomplete answer can keep a step alive an
50
+ extra turn — fine, don't apologize, just keep the count honest). What is not
51
+ allowed is ambiguity about completion: people abandon flows midway and lose the
52
+ whole benefit. Until the final file is approved and written, every header says
53
+ NOT DONE and names what's next. The last message of a run says **DONE** and
54
+ states what was written where — and if the user stops responding mid-flow, the
55
+ last header they saw should make it obvious the work is unfinished.
56
+
57
+ ## Triage
58
+
59
+ The ask picks the *entry* route; the file's actual state picks the full path.
60
+ Assess that state yourself: look for a CLAUDE.md/AGENTS.md in the target project
61
+ and, if one exists, read it and judge what it is (a letter? a router? a command
62
+ list? bloat? how long?). Then, before doing anything else, tell the user which
63
+ route(s) you are entering and the evidence why — one or two sentences, e.g.
64
+ "Your file is 220 lines of commands and template sections with no letter spine,
65
+ so I'm running create's interview, then refine" — and pause so they can correct
66
+ you if the read is wrong. Then start:
67
+
68
+ 1. **No CLAUDE.md/AGENTS.md exists** in the target project (check before assuming)
69
+ → read `routes/create.md`
70
+ 2. **A file exists** and the ask is to audit, improve, trim, fix, or update it
71
+ → read `routes/refine.md`
72
+ 3. **End of a working session** — capture what was learned / "update CLAUDE.md
73
+ with learnings" → read `routes/session-capture.md`. If instead you were
74
+ invoked *mid-task* because the maintenance footer told a working agent to
75
+ capture something it noticed, go straight to that route's **Quick capture**
76
+ section — skip the opening message and the full flow entirely.
77
+ 4. **The question is structural** — has this project outgrown a plain letter?
78
+ should it route to skills/docs/directories? → read `routes/scale-check.md`
79
+
80
+ **The finish line is non-negotiable:** every invocation ends with a file that
81
+ passes the hard rules and letter shape below — not just with the asked-for route
82
+ completed. If the entry route alone can't get there, chain the routes needed and
83
+ tell the user you're doing so. Example: "refine" on a file that has no letter, is
84
+ long, and is mostly a router → run create's interview to author the missing
85
+ letter spine, refine to fold or cut every existing line against it, and
86
+ scale-check to judge whether its routing is even earned. If the ask spans routes
87
+ (e.g. "capture learnings" but the file is also bloated), run them one at a time,
88
+ session-capture first.
89
+
90
+ ## Hard rules — every route, no exceptions
91
+
92
+ 1. **The user authors; you transcribe.** Never draft CLAUDE.md content from
93
+ codebase analysis alone. Draft only from their answers, their corrections, and
94
+ their phrasing — quote their words rather than paraphrasing them into something
95
+ smoother. Investigating the repo to produce *candidates* is encouraged (see the
96
+ routes) — but a candidate enters the letter only after the user confirms it,
97
+ and their confirmation or correction is what makes it theirs.
98
+ 2. **Nothing touches disk without approval — but the file is the deliverable.**
99
+ Present every proposed line and get explicit approval before any Write or
100
+ Edit. Line-by-line review for new letters; per-change review for edits. Once
101
+ approved, you make the changes to the CLAUDE.md yourself — never end a run by
102
+ pasting final content into chat for the user to apply by hand. Chat is for
103
+ proposals and approvals; the result lands on disk.
104
+ 3. **Every line must trace.** Each line in the file must trace to either the
105
+ user's stated intent or a mistake that has actually recurred. If you can't name the
106
+ trace, the line doesn't go in — and if it's already in, propose deleting it.
107
+ 4. **150-line hard cap.** At cap, refuse to add a line without removing one. Treat
108
+ the cap as a ceiling, not a target — shorter is an active improvement.
109
+ 5. **Letter shape.** Prose addressed to the agent: purpose, mental model, why.
110
+ A glossary only when terms are genuinely ambiguous. No file paths. No
111
+ enforcement language. No speculative rules for imagined problems. The single
112
+ exception: a routing section that `scale-check` has explicitly earned.
113
+ 6. **Proposing nothing is a valid output.** A one-off mistake gets no line. A
114
+ project that hasn't outgrown the letter gets no routing. Say so and stop.
115
+ 7. **Every file ships with the maintenance footer.** The last lines of any
116
+ CLAUDE.md this skill writes or refines are this footer, verbatim (its trace
117
+ is this skill's standing mandate, approved with the rest of the file; it
118
+ counts toward the 150 cap):
119
+
120
+ > ---
121
+ > *Maintenance: this file is a letter — short, intent-only, grown one earned
122
+ > line at a time. Agent: as you work, watch for things this letter should
123
+ > learn — new or ambiguous vocabulary (glossary candidates), corrections the
124
+ > user has had to repeat, anything that changes the intent, rules, or routing
125
+ > written here. When you notice one, invoke the `estack-claude-md-optimizer`
126
+ > skill (quick capture): ask the user in one line whether to add it, and if yes do
127
+ > it right then — under 5 minutes, do it now — then return to your task.
128
+ > Never silently append, and never let a noticed improvement get lost. For
129
+ > humans: run the skill directly — refine to audit, session-capture after
130
+ > working sessions, scale-check before adding any routing.*
131
+
132
+ If a file the skill touches lacks the footer, propose adding it with the
133
+ other changes. The footer also warns future agent sessions off appending
134
+ learnings directly — maintenance goes through the skill, where the recurring
135
+ /one-off filter and the cap live.
136
+ 8. **AGENTS.md becomes a one-line pointer.** As one of the last stages of any
137
+ run, check the project dir for an AGENTS.md. If it exists (or other tools
138
+ need one), propose rewriting it to exactly one line:
139
+
140
+ > Read CLAUDE.md — all project instructions live there.
141
+
142
+ If it has real content of its own, that content goes through the normal
143
+ refine flow into CLAUDE.md first; nothing is silently dropped. When you
144
+ propose this, explain both whys to the user: (1) duplicate info means agents
145
+ that read both files ingest it twice, bloating their context; (2) the real
146
+ info lives in CLAUDE.md because Codex and other tools reliably follow a file
147
+ path pointer and will go read CLAUDE.md — but Claude only reads CLAUDE.md
148
+ and won't follow a pointer into AGENTS.md, so that direction is the only one
149
+ that works for every tool.
150
+
151
+ ## References — the source mentalities
152
+
153
+ The full syntheses this skill is built from live in `references/`. Read them on
154
+ demand, not by default:
155
+
156
+ - `references/theo_claude_md_mentality.md` — Theo's letter mentality (the spine):
157
+ hand-authored prose, intent and why, glossary, reactive growth, bloat as harm.
158
+ - `references/gary_tan_router_claude_md_mentality.md` — Gary's resolver discipline: route
159
+ don't explain, routing earned by scale, reachability, resolver rot.
160
+
161
+ Read the relevant one when the user asks about the philosophy or "why does the
162
+ skill work this way," when a judgment call needs grounding (a scale-check
163
+ verdict, a contested deletion, how to re-voice a rule), or when quoting the
164
+ sources would land better than asserting the rule.
165
+
166
+ ## What this skill is not
167
+
168
+ Not a template generator, not an A–F grader, not a skill/resolver manager. It does
169
+ not score files against rubrics or pad them toward "recommended sections." It
170
+ targets ordinary project codebases and runs only when invoked.
171
+ ---
172
+
173
+ ## Skill Feedback
174
+
175
+ 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:
176
+
177
+ **If `gh` is installed** (`gh --version` succeeds), create the issue directly:
178
+
179
+ ```bash
180
+ gh issue create \
181
+ --repo ElliotDrel/e-stack \
182
+ --title "estack-claude-md-optimizer: <concise summary>" \
183
+ --body "<description from user feedback — expected vs. actual behavior and context>"
184
+ ```
185
+
186
+ **If `gh` is not installed**, build a pre-filled URL:
187
+
188
+ ```bash
189
+ python3 -c "
190
+ import urllib.parse
191
+ title = 'estack-claude-md-optimizer: <concise summary>'
192
+ body = '<description from user feedback — expected vs. actual behavior and context>'
193
+ base = 'https://github.com/ElliotDrel/e-stack/issues/new'
194
+ print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
195
+ "
196
+ ```
197
+
198
+ Share the printed URL with the user and offer to open it in their browser.
199
+
200
+ They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.