claude-code-autoconfig 1.0.101 → 1.0.103

package/.claude/commands/autoconfig-update.md

@@ -1,146 +1,146 @@
-<!-- @description Manages and installs updates to Claude Code configuration. -->
-
-<!-- @applied
--->
-
-# Autoconfig Update
-
-Check for and install pending updates to your Claude Code configuration.
-
-**Style guideline**: Work silently through Steps 1-3. Do not narrate internal steps, implementation details, or progress messages (e.g., "Let me check...", "The @applied block is empty..."). The first output the user sees should be the formatted summary in Step 4 (or the "up to date" message).
-
-## Step 1: Pull Latest Updates
-
-Run this command via Bash to pull new update files from the latest package:
-
-```bash
-npx claude-code-autoconfig@latest --pull-updates
-```
-
-This copies any new update `.md` files into `.claude/updates/` and refreshes this command file (preserving the `@applied` block above).
-
-After the command completes, check `.claude/updates/` directory. If it doesn't exist or is empty, output:
-
-```
-No new updates available. You're up to date.
-```
-
-Then stop — do not continue to further steps.
-
-## Step 2: Parse Update Files
-
-Read all `.md` files in `.claude/updates/` matching the pattern `NNN-*.md` (e.g., `001-debug-methodology.md`).
-
-For each file, extract metadata from the HTML comment headers at the top:
-
-| Header | Pattern | Required |
-|--------|---------|----------|
-| `@title` | `<!-- @title (.+?) -->` | Yes |
-| `@type` | `<!-- @type (.+?) -->` | Yes |
-| `@description` | `<!-- @description (.+?) -->` | Yes |
-| `@files` | `<!-- @files (.+?) -->` | Yes |
-
-Extract the numeric ID from the filename prefix (e.g., `001` from `001-debug-methodology.md`).
-
-Skip any files that are malformed (missing required headers) with a warning.
-
-## Step 3: Filter Already Applied
-
-Parse the `<!-- @applied -->` block in THIS file (`.claude/commands/autoconfig-update.md`) to get the list of already-applied update IDs. Extract the three-digit ID from the start of each line.
-
-Filter out any updates whose ID appears in the applied list. If no pending updates remain, output:
-
-```
-All updates are already installed. You're up to date.
-```
-
-Then stop.
-
-## Step 4: Display Summary
-
-**Important**: Do NOT narrate your internal steps (e.g., "The @applied block is empty" or "Let me check..."). Go straight to the formatted output below. The user doesn't need to see implementation details.
-
-Output the pending updates using this exact format. Use `═` horizontal dividers only (no vertical borders — they render poorly in Claude Code). Render the dividers and header in **yellow** (ANSI `\x1b[33m`) to visually match the CLI's yellow "READY TO UPDATE" box and distinguish this from regular Claude output:
-
-```
-════════════════════════════════════════════
-  Updates available ({count})
-════════════════════════════════════════════
-
-  001 ─ Debug Methodology
-  002 ─ Some other feature
-
-════════════════════════════════════════════
-  [1] Install all    [2] Review each
-════════════════════════════════════════════
-```
-
-Replace `{count}` with the number of pending updates. List each update with its ID and title. Wait for the user to respond with 1 or 2.
-
-## Step 5a: Install All (User picked 1)
-
-For each pending update (in ID order):
-1. Read the update `.md` file body (everything below the metadata comments)
-2. Follow the instructions in the body to apply the update
-3. After successful application, append to the `@applied` block in THIS file:
-   ```
-   {id} - {title}
-   ```
-
-After all updates are applied, go to Step 6.
-
-## Step 5b: Review Each (User picked 2)
-
-For each pending update (in ID order), display using horizontal dividers only (no vertical borders — they render poorly in Claude Code):
-
-```
-════════════════════════════════════════════
-  UPDATE {n} of {total}              {type}
-════════════════════════════════════════════
-
-  {title}
-
-  {description}
-
-  Files:  {comma-separated list of files touched}
-
-════════════════════════════════════════════
-  [y] Install    [s] Skip    [a] Install all remaining
-════════════════════════════════════════════
-```
-
-**Rendering rules:**
-- Use `═` horizontal dividers only — no `║ ╔ ╗ ╠ ╣ ╚ ╝` vertical/corner characters
-- Content lines are free-flowing (no padding or alignment needed)
-- `{n}` is the position in the pending list (1, 2, 3...), `{total}` is count of pending
-
-**User actions:**
-- `y` → Apply this update (follow body instructions), append to `@applied`, show next
-- `s` → Skip this update (do NOT add to `@applied` — it will appear again next run)
-- `a` → Apply this update AND all remaining updates without further prompts
-
-After all updates are reviewed, go to Step 6.
-
-## Step 6: Summary and Cleanup
-
-Show a summary of what happened:
-
-```
-✅ Installed: 001, 003
-⏭️  Skipped:  002
-
-Run /autoconfig-update again anytime to install skipped updates.
-```
-
-If all were installed:
-```
-✅ All updates installed.
-```
-
-Then delete the `.claude/updates/` directory (it's ephemeral — updates are tracked in the @applied block above).
-
-If the user installed any updates that modified `.claude/commands/autoconfig.md`, suggest:
-
-```
-Run /sync-claude-md to apply these changes to your current project's CLAUDE.md.
-```
+<!-- @description Manages and installs updates to Claude Code configuration. -->
+
+<!-- @applied
+-->
+
+# Autoconfig Update
+
+Check for and install pending updates to your Claude Code configuration.
+
+**Style guideline**: Work silently through Steps 1-3. Do not narrate internal steps, implementation details, or progress messages (e.g., "Let me check...", "The @applied block is empty..."). The first output the user sees should be the formatted summary in Step 4 (or the "up to date" message).
+
+## Step 1: Pull Latest Updates
+
+Run this command via Bash to pull new update files from the latest package:
+
+```bash
+npx claude-code-autoconfig@latest --pull-updates
+```
+
+This copies any new update `.md` files into `.claude/updates/` and refreshes this command file (preserving the `@applied` block above).
+
+After the command completes, check `.claude/updates/` directory. If it doesn't exist or is empty, output:
+
+```
+No new updates available. You're up to date.
+```
+
+Then stop — do not continue to further steps.
+
+## Step 2: Parse Update Files
+
+Read all `.md` files in `.claude/updates/` matching the pattern `NNN-*.md` (e.g., `001-debug-methodology.md`).
+
+For each file, extract metadata from the HTML comment headers at the top:
+
+| Header | Pattern | Required |
+|--------|---------|----------|
+| `@title` | `<!-- @title (.+?) -->` | Yes |
+| `@type` | `<!-- @type (.+?) -->` | Yes |
+| `@description` | `<!-- @description (.+?) -->` | Yes |
+| `@files` | `<!-- @files (.+?) -->` | Yes |
+
+Extract the numeric ID from the filename prefix (e.g., `001` from `001-debug-methodology.md`).
+
+Skip any files that are malformed (missing required headers) with a warning.
+
+## Step 3: Filter Already Applied
+
+Parse the `<!-- @applied -->` block in THIS file (`.claude/commands/autoconfig-update.md`) to get the list of already-applied update IDs. Extract the three-digit ID from the start of each line.
+
+Filter out any updates whose ID appears in the applied list. If no pending updates remain, output:
+
+```
+All updates are already installed. You're up to date.
+```
+
+Then stop.
+
+## Step 4: Display Summary
+
+**Important**: Do NOT narrate your internal steps (e.g., "The @applied block is empty" or "Let me check..."). Go straight to the formatted output below. The user doesn't need to see implementation details.
+
+Output the pending updates using this exact format. Use `═` horizontal dividers only (no vertical borders — they render poorly in Claude Code). Render the dividers and header in **yellow** (ANSI `\x1b[33m`) to visually match the CLI's yellow "READY TO UPDATE" box and distinguish this from regular Claude output:
+
+```
+════════════════════════════════════════════
+  Updates available ({count})
+════════════════════════════════════════════
+
+  001 ─ Debug Methodology
+  002 ─ Some other feature
+
+════════════════════════════════════════════
+  [1] Install all    [2] Review each
+════════════════════════════════════════════
+```
+
+Replace `{count}` with the number of pending updates. List each update with its ID and title. Wait for the user to respond with 1 or 2.
+
+## Step 5a: Install All (User picked 1)
+
+For each pending update (in ID order):
+1. Read the update `.md` file body (everything below the metadata comments)
+2. Follow the instructions in the body to apply the update
+3. After successful application, append to the `@applied` block in THIS file:
+   ```
+   {id} - {title}
+   ```
+
+After all updates are applied, go to Step 6.
+
+## Step 5b: Review Each (User picked 2)
+
+For each pending update (in ID order), display using horizontal dividers only (no vertical borders — they render poorly in Claude Code):
+
+```
+════════════════════════════════════════════
+  UPDATE {n} of {total}              {type}
+════════════════════════════════════════════
+
+  {title}
+
+  {description}
+
+  Files:  {comma-separated list of files touched}
+
+════════════════════════════════════════════
+  [y] Install    [s] Skip    [a] Install all remaining
+════════════════════════════════════════════
+```
+
+**Rendering rules:**
+- Use `═` horizontal dividers only — no `║ ╔ ╗ ╠ ╣ ╚ ╝` vertical/corner characters
+- Content lines are free-flowing (no padding or alignment needed)
+- `{n}` is the position in the pending list (1, 2, 3...), `{total}` is count of pending
+
+**User actions:**
+- `y` → Apply this update (follow body instructions), append to `@applied`, show next
+- `s` → Skip this update (do NOT add to `@applied` — it will appear again next run)
+- `a` → Apply this update AND all remaining updates without further prompts
+
+After all updates are reviewed, go to Step 6.
+
+## Step 6: Summary and Cleanup
+
+Show a summary of what happened:
+
+```
+✅ Installed: 001, 003
+⏭️  Skipped:  002
+
+Run /autoconfig-update again anytime to install skipped updates.
+```
+
+If all were installed:
+```
+✅ All updates installed.
+```
+
+Then delete the `.claude/updates/` directory (it's ephemeral — updates are tracked in the @applied block above).
+
+If the user installed any updates that modified `.claude/commands/autoconfig.md`, suggest:
+
+```
+Run /sync-claude-md to apply these changes to your current project's CLAUDE.md.
+```

package/.claude/commands/autoconfig.md

@@ -114,7 +114,7 @@ Replace `{TIMESTAMP}` with the current UTC time in format `YYYY-MM-DD HH:MM:SS`
 
 **Always include:**
 - **Project name + one-liner**: What is this thing?
-- **Tech stack**: Runtime, framework, database, key services (so Claude uses correct patterns)
+- **Tech stack**: One to two lines max. Only mention choices Claude wouldn't guess from config files alone (e.g., "Firebase Auth via WEB_OAUTH" is worth including; "React 18 with TypeScript" is not — Claude sees that in `package.json`). Do NOT list individual dependencies, testing libraries, or build tools that appear in `package.json`/`requirements.txt` — Claude reads those files directly.
 - **Commands**: How to run, test, build, deploy — Claude needs these to execute tasks
 - **Non-obvious conventions**: Multi-schema databases, monorepo structure, unusual patterns Claude wouldn't infer
 
@@ -135,13 +135,15 @@ Place this section near the top (after Tech Stack, before Commands) since versio
 
 **Include if relevant:**
 - **Deployment flow**: If non-standard or involves multiple steps
-- **Key architectural decisions**: Only if Claude would make wrong assumptions without them
+- **Key architectural decisions**: Only when the project has non-standard module boundaries (e.g., Chrome extension background/content split, microservice routing, multi-entrypoint builds). For standard single-entrypoint apps (Next.js, Express, Django), skip it — Claude can infer the architecture from the file structure.
 
 **Skip these — Claude can discover them:**
 - Detailed project structure trees (Claude can run `ls` or `tree`)
 - Exhaustive route/endpoint lists (Claude can grep)
 - File-by-file descriptions (Claude can read files)
 - Database model lists (Claude can read schema files)
+- Individual dependency names or versions (Claude reads `package.json`/`requirements.txt` directly)
+- Standard framework patterns (e.g., "uses app router" for Next.js — Claude sees `app/` directory)
 
 **Keep it tight.** A 30-line CLAUDE.md that hits the essentials beats a 200-line doc Claude has to parse every session.
 
@@ -295,7 +297,9 @@ Claude Code has a persistent auto memory file (`MEMORY.md`) that loads into the
 
 The file lives at `~/.claude/projects/{encoded-project-path}/memory/MEMORY.md` where the project path is encoded by replacing path separators with dashes and removing colons (e.g., `C:\CODE\my-project` becomes `C--CODE-my-project`).
 
-**Write this content** (append if file already exists, create if it doesn't):
+**Before writing, read MEMORY.md first.** If a `## Debugging` section (or similar heading like `## Debugging — Evidence Before Solutions`) already exists, **skip this step entirely** — never duplicate or overwrite user-curated memory content.
+
+**Only if no debugging section exists**, write this content (append if file already exists, create if it doesn't):
 
 ```markdown
 ## Debugging — Evidence Before Solutions
@@ -305,7 +309,7 @@ NEVER guess the root cause and jump to coding a fix. Ask yourself: is the cause
 3. Only then propose and implement a fix
 ```
 
-**Important**: Use the Write tool (or Edit to append). Do not skip this step — it ensures Claude investigates root causes before making changes in every future session.
+**Important**: Use the Write tool (or Edit to append). Do not skip this step on first-time setup — it ensures Claude investigates root causes before making changes in every future session. But never overwrite existing user content in MEMORY.md.
 
 ## Step 8: Update the Docs
 

package/.claude/commands/sync-claude-md.md

@@ -56,9 +56,15 @@ CLAUDE.md uses markers to identify auto-generated content:
 Compare detected state with current CLAUDE.md and update:
 
 1. **Project name** — if changed
-2. **Tech stack** — new frameworks, languages, databases
+2. **Tech stack** — One to two lines max. Only mention choices Claude wouldn't guess from config files alone. Do NOT list individual dependencies, testing libraries, or build tools that appear in `package.json`/`requirements.txt` — Claude reads those directly.
 3. **Commands** — new/changed npm scripts, build commands
 4. **Conventions** — if project structure changed
+5. **Architecture** — Only include when the project has non-standard module boundaries (e.g., Chrome extension background/content split, microservice routing, multi-entrypoint builds). For standard single-entrypoint apps, skip it.
+
+**Skip these — Claude can discover them:**
+- Detailed project structure trees, route/endpoint lists, file-by-file descriptions
+- Database model lists, individual dependency names or versions
+- Standard framework patterns (e.g., "uses app router" for Next.js)
 
 **Always include within markers:**
 - The `## Retro` section pointer
@@ -72,4 +78,5 @@ Show the user what changed in CLAUDE.md before finishing.
 
 - **Respect markers**: Only regenerate content between AUTO-GENERATED markers
 - **Be conservative**: Only update sections that actually changed
-- **Keep it tight**: CLAUDE.md should stay concise
+- **Keep it tight**: A 30-line CLAUDE.md that hits the essentials beats a 200-line doc Claude has to parse every session
+- **No boilerplate**: If Claude can infer it from scanning `package.json` or config files, don't put it in CLAUDE.md

package/.claude/updates/001-debug-methodology.md

@@ -17,13 +17,13 @@ The file lives at `~/.claude/projects/{encoded-project-path}/memory/MEMORY.md` w
 
 ```markdown
 ## Debugging — Evidence Before Solutions
-NEVER guess the root cause and jump to coding a fix. Ask yourself: is the cause deterministic and verifiable from the error alone?
-- **Deterministic means**: stack trace, compile error, or type error — NOT "I read the code and I think I see the issue." Reading code paths and reasoning about what "should" happen is a GUESS, not evidence.
-- If deterministic: fix it directly.
-- If NOT deterministic (this includes most runtime bugs):
-  1. Add logging / check actual data first
-  2. Confirm root cause with evidence
-  3. Only then propose and implement a fix
+
+**Never guess.** Before writing any fix, ask: do I have a stack trace, compile error, or type error that points directly to the problem?
+
+- **Yes** → Fix it directly.
+- **No** → Stop. Add logging first, get real runtime data, confirm the cause, *then* fix.
+
+"I read the code and I think I see the issue" is a guess, not evidence.
 
 **Circuit breaker — going in circles**: If the user reports your fix didn't solve the problem, STOP coding immediately. Add logging. No second guesses. Making another code change for the same symptom without new runtime evidence is going in circles.
 ```

package/bin/cli.js

@@ -342,9 +342,15 @@ if (fs.existsSync(commandsSrc)) {
   process.exit(1);
 }
 
-// Copy docs (interactive documentation)
+// Copy docs (only .html files — skip internal planning docs)
 if (fs.existsSync(docsSrc)) {
-  copyDir(docsSrc, path.join(claudeDest, 'docs'));
+  const docsDestDir = path.join(claudeDest, 'docs');
+  fs.mkdirSync(docsDestDir, { recursive: true });
+  for (const file of fs.readdirSync(docsSrc)) {
+    if (file.endsWith('.html')) {
+      fs.copyFileSync(path.join(docsSrc, file), path.join(docsDestDir, file));
+    }
+  }
 }
 
 // Copy agents if exists
@@ -393,6 +399,34 @@ const isUpgrade = (() => {
   return false;
 })();
 
+// On fresh install, pre-mark all bundled updates as applied.
+// The /autoconfig command already handles their content (e.g., debug methodology in MEMORY.md),
+// so they shouldn't appear as "new" when the user later upgrades.
+if (!isUpgrade) {
+  const userCmdPath = path.join(claudeDest, 'commands', 'autoconfig-update.md');
+  const packageUpdatesDir = path.join(packageDir, '.claude', 'updates');
+  if (fs.existsSync(userCmdPath) && fs.existsSync(packageUpdatesDir)) {
+    const updateFiles = fs.readdirSync(packageUpdatesDir)
+      .filter(f => f.endsWith('.md') && /^\d{3}-/.test(f))
+      .sort();
+    if (updateFiles.length > 0) {
+      const appliedLines = updateFiles.map(file => {
+        const id = file.match(/^(\d{3})-/)[1];
+        const content = fs.readFileSync(path.join(packageUpdatesDir, file), 'utf8');
+        const titleMatch = content.match(/<!-- @title (.+?) -->/);
+        const title = titleMatch ? titleMatch[1] : file.replace(/^\d{3}-/, '').replace(/\.md$/, '');
+        return `${id} - ${title}`;
+      });
+      const cmdContent = fs.readFileSync(userCmdPath, 'utf8');
+      const updated = cmdContent.replace(
+        /<!-- @applied\r?\n-->/,
+        `<!-- @applied\n${appliedLines.join('\n')}\n-->`
+      );
+      fs.writeFileSync(userCmdPath, updated);
+    }
+  }
+}
+
 const launchCommand = isUpgrade ? '/autoconfig-update' : '/autoconfig';
 
 // Step 4: Show "READY" message

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-autoconfig",
-  "version": "1.0.101",
+  "version": "1.0.103",
   "description": "Intelligent, self-configuring setup for Claude Code. One command analyzes your project, configures Claude, and shows you what it did.",
   "author": "ADAC 1001 <info@adac1001.com>",
   "license": "MIT",
@@ -36,7 +36,7 @@
     "!.claude/settings.local.json",
     "!.claude/commands/publish.md",
     "!.claude/commands/gls.md",
-    "!.claude/docs/multi-stack-parity-plan.md",
+    "!.claude/plans",
     "CLAUDE.md"
   ],
   "engines": {