claude-code-autoconfig 1.0.102 → 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/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.102",
+  "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": {