elliot-stack 1.0.28 → 1.0.29

package/README.md

@@ -20,7 +20,7 @@ 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 |
+| **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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elliot-stack",
-  "version": "1.0.28",
+  "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-claude-md-optimizer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: estack-claude-md-optimizer
-version: 1.0.1
+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,
@@ -18,33 +18,82 @@ 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 — buy the user in first
+## Opening message — welcome and teach first
 
-Your first message of any run, before the triage announcement, briefly explains
-the skill so the user knows what's happening and why (3–5 sentences, plain
-language, then move on):
+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.
 
-- **What it is:** a tool for writing and maintaining a CLAUDE.md as a short
-  letter — prose that transfers your intent and "why" to the agent.
-- **Why it works that way:** bloated context files measurably make models worse
-  — the model isn't dumb, it's drowning. Intent transfers better than rules,
-  which is also why the human authors the letter and the skill only transcribes:
-  the file's job is to carry *your* thinking, and every line is earned by your
-  stated intent or a mistake that actually recurred — never padded.
-- **How this run works:** diagnose the file's state → name the route(s) →
-  interview or proposals → nothing touches disk without your approval.
+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):
 
-This intro exists so the process (interviews, proposed deletions, refusing to
-add lines) reads as the method working, not as friction. Don't lecture; one
-tight paragraph, then the triage announcement.
+---
+
+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 header:
-where we are in the flow, roughly what's left, and — most important — whether
-the flow is DONE or NOT DONE. Format:
+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**
+```
+┌──────────────────────────────────────────────────────────────
+│ 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
@@ -148,6 +197,31 @@ session-capture first.
    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