claude-setup 1.0.0 → 1.1.2

package/README.md

@@ -2,31 +2,41 @@
 
 Setup layer for Claude Code. Reads your project, writes command files, Claude Code does the rest.
 
-## Install
+**The CLI has zero intelligence.** All reasoning is delegated to Claude Code via the command files. The CLI reads files. Claude Code decides.
+
+## Install & Quick Start
 
 ```bash
 npx claude-setup init
 ```
 
+Then open Claude Code and run `/stack-init`.
+
 ## Commands
 
 | Command | What it does |
 |---------|-------------|
-| `npx claude-setup init` | Full project setup — new or existing |
-| `npx claude-setup add` | Add a multi-file capability |
-| `npx claude-setup sync` | Update setup after project changes |
-| `npx claude-setup status` | Show current setup |
-| `npx claude-setup doctor` | Validate environment |
-| `npx claude-setup remove` | Remove a capability cleanly |
+| `npx claude-setup init` | Full project setup — new or existing. Detects empty projects automatically. |
+| `npx claude-setup add` | Add a multi-file capability (MCP + hooks + skills together) |
+| `npx claude-setup sync` | Update setup after project changes (uses diff, not full re-scan) |
+| `npx claude-setup status` | Show current setup state — OS, servers, hooks, staleness |
+| `npx claude-setup doctor` | Validate environment — OS/MCP format, hook quoting, env vars, stale skills |
+| `npx claude-setup remove` | Remove a capability cleanly with dangling reference detection |
+
+### Flags
+
+```bash
+npx claude-setup init --dry-run    # Preview without writing
+npx claude-setup sync --dry-run    # Show changes without writing
+npx claude-setup doctor --verbose  # Include passing checks in output
+```
 
 ## How it works
 
-1. **CLI collects** — reads project files (configs, source samples) with strict cost controls
+1. **CLI collects** — reads project files (configs, source samples) with strict token cost controls
 2. **CLI writes command files** — assembles markdown instructions into `.claude/commands/`
 3. **Claude Code executes** — you run `/stack-init` (or `/stack-sync`, etc.) in Claude Code
 
-The CLI has zero intelligence. All reasoning is delegated to Claude Code via the command files.
-
 ## Three project states
 
 - **Empty project** — Claude Code asks 3 discovery questions, then sets up a tailored environment
@@ -36,16 +46,74 @@ The CLI has zero intelligence. All reasoning is delegated to Claude Code via the
 ## What it creates
 
 - `CLAUDE.md` — project-specific context for Claude Code
-- `.mcp.json` — MCP server connections (only if evidenced by project files)
-- `.claude/settings.json` — hooks (only if warranted)
-- `.claude/skills/` — reusable patterns (only if recurring)
+- `.mcp.json` — MCP server connections (only if evidenced by project files, OS-correct format)
+- `.claude/settings.json` — hooks (only if warranted, OS-correct shell format)
+- `.claude/skills/` — reusable patterns (only if recurring, with `applies-when` frontmatter)
 - `.claude/commands/` — project-specific slash commands
 - `.github/workflows/` — CI workflows (only if `.github/` exists)
 
-## Cost controls
+## Token cost controls
+
+Every byte injected into command files costs tokens. The CLI enforces:
+
+| Control | Default |
+|---------|---------|
+| Init token budget | 12,000 |
+| Sync token budget | 6,000 |
+| Add token budget | 3,000 |
+| Remove token budget | 2,000 |
+| Max source files sampled | 15 |
+| Max file size | 80KB |
+| Max depth | 6 levels |
+
+### File-specific truncation
+
+| File | Strategy |
+|------|----------|
+| `package-lock.json` | Extract `{ name, version, lockfileVersion }` only |
+| `Dockerfile` | First 50 lines |
+| `docker-compose.yml` | First 100 lines if > 8KB |
+| `pom.xml`, `build.gradle*` | First 80 lines |
+| `setup.py` | First 60 lines |
+| `*.config.{js,ts,mjs}` | First 100 lines |
+
+## Configuration
+
+Create `.claude-setup.json` in your project root to customize:
+
+```json
+{
+  "maxSourceFiles": 15,
+  "maxDepth": 6,
+  "maxFileSizeKB": 80,
+  "tokenBudget": {
+    "init": 12000,
+    "sync": 6000,
+    "add": 3000,
+    "remove": 2000
+  },
+  "digestMode": true,
+  "extraBlockedDirs": ["my-custom-dir"],
+  "sourceDirs": ["src", "lib"]
+}
+```
+
+## Digest mode
+
+When `digestMode` is enabled (default), the CLI extracts compact signal instead of dumping raw file content:
+
+- **Config files found** — just names, not content
+- **Dependencies** — extracted from any package manifest
+- **Scripts** — available commands/tasks
+- **Env vars** — names from `.env.example`
+- **Directory tree** — compact structure (3 levels deep)
+- **Source signatures** — imports, exports, declarations (not full content)
+
+## OS detection
+
+The CLI detects your OS and ensures command files tell Claude Code to use the correct format:
+
+- **Windows**: `{ "command": "cmd", "args": ["/c", "npx", "<package>"] }`
+- **macOS/Linux**: `{ "command": "npx", "args": ["<package>"] }`
 
-Every byte in a command file costs tokens. The CLI enforces:
-- Source file sampling (max 10 files, smallest first)
-- Hard truncation per file (150/400 line thresholds)
-- Token budget cap (20,000 tokens max per command file)
-- Universal blocklist (node_modules, dist, binaries, etc.)
+`doctor` checks for mismatches and reports them as critical issues.

package/dist/builder.js

@@ -1,17 +1,16 @@
 import { readFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
+import { loadConfig } from "./config.js";
+import { detectOS } from "./os.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, "..", "templates");
-const TOKEN_SOFT_WARN = 8_000;
-const TOKEN_HARD_CAP = 20_000;
 function estimateTokens(content) {
     return Math.ceil(content.length / 4);
 }
 function loadTemplate(name) {
     return readFileSync(join(TEMPLATES_DIR, name), "utf8");
 }
-// Simple {{VARIABLE}} replacement
 function replaceVars(template, vars) {
     let result = template;
     for (const [key, value] of Object.entries(vars)) {
@@ -19,56 +18,60 @@ function replaceVars(template, vars) {
     }
     return result;
 }
-// Conditional blocks: {{#if VAR}}...{{else}}...{{/if}} and {{#if VAR}}...{{/if}}
 function processConditionals(template, flags) {
-    // Handle {{#if VAR}}...{{else}}...{{/if}}
     let result = template;
-    const ifElseRegex = /\{\{#if\s+(\w+)\}\}\n?([\s\S]*?)\{\{else\}\}\n?([\s\S]*?)\{\{\/if\}\}/g;
-    result = result.replace(ifElseRegex, (_match, key, ifBlock, elseBlock) => {
-        return flags[key] ? ifBlock : elseBlock;
-    });
-    // Handle {{#if VAR}}...{{/if}} (no else)
-    const ifRegex = /\{\{#if\s+(\w+)\}\}\n?([\s\S]*?)\{\{\/if\}\}/g;
-    result = result.replace(ifRegex, (_match, key, block) => {
-        return flags[key] ? block : "";
-    });
+    // {{#if VAR}}...{{else}}...{{/if}}
+    result = result.replace(/\{\{#if\s+(\w+)\}\}\n?([\s\S]*?)\{\{else\}\}\n?([\s\S]*?)\{\{\/if\}\}/g, (_m, key, ifBlock, elseBlock) => flags[key] ? ifBlock : elseBlock);
+    // {{#if VAR}}...{{/if}}
+    result = result.replace(/\{\{#if\s+(\w+)\}\}\n?([\s\S]*?)\{\{\/if\}\}/g, (_m, key, block) => flags[key] ? block : "");
     return result;
 }
-function formatConfigFiles(configs) {
-    if (Object.keys(configs).length === 0)
-        return "(no config files found)";
-    return Object.entries(configs)
-        .map(([path, content]) => {
-        return `#### ${path}\n\`\`\`\n${content}\n\`\`\``;
-    })
-        .join("\n\n");
+function formatList(items) {
+    return items.length === 0 ? "none" : items.join(", ");
+}
+function getVersion() {
+    try {
+        return JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf8")).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
 }
-function formatSourceFiles(source) {
+// --- Project context formatter ---
+// This is the key optimization: instead of dumping raw files, we format
+// the digest compactly. Full file content only when truly needed.
+function formatProjectContext(collected) {
+    const lines = [];
+    // Digest (compact signal extraction)
+    const digest = collected.configs["__digest__"];
+    if (digest) {
+        lines.push(digest);
+    }
+    // Additional config files that kept full content (docker-compose, etc.)
+    for (const [name, content] of Object.entries(collected.configs)) {
+        if (name === "__digest__" || name === ".env")
+            continue;
+        lines.push(`\n### ${name}\n\`\`\`\n${content}\n\`\`\``);
+    }
+    return lines.join("\n") || "(no config files found)";
+}
+function formatSourceContext(source) {
     if (source.length === 0)
-        return "(no source files sampled)";
+        return "";
     return source
-        .map(({ path, content }) => {
-        return `#### ${path}\n\`\`\`\n${content}\n\`\`\``;
-    })
+        .map(({ path, content }) => `### ${path}\n\`\`\`\n${content}\n\`\`\``)
         .join("\n\n");
 }
-function formatSkippedFiles(skipped) {
-    return skipped.map(({ path, reason }) => `- ${path} — ${reason}`).join("\n");
-}
-function formatList(items) {
-    if (items.length === 0)
-        return "none";
-    return items.join(", ");
-}
+// --- Template variable building ---
 function buildVars(collected, state) {
-    const version = getVersion();
-    const date = new Date().toISOString().split("T")[0];
+    const skippedList = collected.skipped.length > 0
+        ? collected.skipped.map(s => `- ${s.path} — ${s.reason}`).join("\n")
+        : "";
     return {
-        VERSION: version,
-        DATE: date,
-        CONFIG_FILES: formatConfigFiles(collected.configs),
-        SOURCE_FILES: formatSourceFiles(collected.source),
-        SKIPPED_LIST: formatSkippedFiles(collected.skipped),
+        VERSION: getVersion(),
+        DATE: new Date().toISOString().split("T")[0],
+        PROJECT_CONTEXT: formatProjectContext(collected),
+        SOURCE_CONTEXT: formatSourceContext(collected.source),
         CLAUDE_MD_CONTENT: state.claudeMd.content
             ? `\`\`\`\n${state.claudeMd.content}\n\`\`\``
             : "",
@@ -82,160 +85,245 @@ function buildVars(collected, state) {
         COMMANDS_LIST: formatList(state.commands),
         WORKFLOWS_LIST: formatList(state.workflows),
         HAS_GITHUB_DIR: state.hasGithubDir ? "yes" : "no",
+        SKIPPED_LIST: skippedList,
+        DETECTED_OS: detectOS(),
     };
 }
-function buildFlags(collected, state) {
+function buildFlags(_collected, state) {
     return {
-        HAS_SKIPPED: collected.skipped.length > 0,
+        HAS_SOURCE: _collected.source.length > 0,
+        HAS_SKIPPED: _collected.skipped.length > 0,
         HAS_CLAUDE_MD: state.claudeMd.exists,
         HAS_MCP_JSON: state.mcpJson.exists,
         HAS_SETTINGS: state.settings.exists,
         HAS_GITHUB_DIR: state.hasGithubDir,
     };
 }
-function getVersion() {
-    try {
-        const pkgPath = join(__dirname, "..", "package.json");
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-        return pkg.version ?? "0.0.0";
-    }
-    catch {
-        return "0.0.0";
-    }
-}
-function fitToTokenBudget(content, sources) {
-    if (estimateTokens(content) <= TOKEN_HARD_CAP)
+// --- Token budget enforcement ---
+function fitToTokenBudget(content, sources, hardCap) {
+    if (estimateTokens(content) <= hardCap)
         return content;
-    // Progressively remove source files, largest first
+    // Remove source files largest-first until under budget
     const sorted = [...sources].sort((a, b) => b.content.length - a.content.length);
     for (const remove of sorted) {
-        const sourceBlock = `#### ${remove.path}\n\`\`\`\n${remove.content}\n\`\`\``;
-        content = content.replace(sourceBlock, `[${remove.path} — removed to fit token budget]`);
-        if (estimateTokens(content) <= TOKEN_HARD_CAP)
+        const block = `### ${remove.path}\n\`\`\`\n${remove.content}\n\`\`\``;
+        content = content.replace(block, `[${remove.path} — trimmed]`);
+        if (estimateTokens(content) <= hardCap)
             break;
     }
     return content;
 }
-function applyTemplate(templateName, collected, state, extraVars = {}) {
+function applyTemplate(templateName, collected, state, extraVars = {}, budgetKey = "init") {
+    const config = loadConfig();
+    const budget = config.tokenBudget[budgetKey];
     const template = loadTemplate(templateName);
     const vars = { ...buildVars(collected, state), ...extraVars };
     const flags = buildFlags(collected, state);
     let content = replaceVars(template, vars);
     content = processConditionals(content, flags);
     const tokens = estimateTokens(content);
-    if (tokens > TOKEN_SOFT_WARN) {
-        console.warn(`⚠️  Command file is ${tokens} tokens (soft limit: ${TOKEN_SOFT_WARN})`);
+    if (tokens > budget) {
+        content = fitToTokenBudget(content, collected.source, budget);
+        const finalTokens = estimateTokens(content);
+        if (finalTokens > budget) {
+            console.warn(`⚠️  ${templateName}: ${finalTokens} tokens (budget: ${budget})`);
+        }
     }
-    content = fitToTokenBudget(content, collected.source);
     return content;
 }
+// --- Public API ---
 export function buildInitCommand(collected, state) {
-    return applyTemplate("init.md", collected, state);
+    return applyTemplate("init.md", collected, state, {}, "init");
 }
 export function buildEmptyProjectCommand() {
     const template = loadTemplate("init-empty.md");
-    const version = getVersion();
-    const date = new Date().toISOString().split("T")[0];
-    return replaceVars(template, { VERSION: version, DATE: date });
+    return replaceVars(template, { VERSION: getVersion(), DATE: new Date().toISOString().split("T")[0] });
 }
 export function buildAddCommand(input, collected, state) {
-    return applyTemplate("add.md", collected, state, { USER_INPUT: input });
+    return applyTemplate("add.md", collected, state, { USER_INPUT: input }, "add");
 }
 export function buildSyncCommand(diff, collected, state) {
-    const lastRun = state.manifest?.runs.at(-1);
+    // Compact diff format — paths + one-line summary, not full content
     const addedStr = diff.added.length > 0
-        ? diff.added.map(f => `#### ${f.path}\n\`\`\`\n${f.content}\n\`\`\``).join("\n\n")
+        ? diff.added.map(f => `- **${f.path}** (new) — ${f.content.split("\n").length} lines`).join("\n")
         : "(none)";
     const modifiedStr = diff.changed.length > 0
-        ? diff.changed.map(f => `#### ${f.path}\n\`\`\`\n${f.current}\n\`\`\``).join("\n\n")
+        ? diff.changed.map(f => `- **${f.path}** (modified)`).join("\n")
         : "(none)";
     const deletedStr = diff.deleted.length > 0
         ? diff.deleted.map(f => `- ${f}`).join("\n")
         : "(none)";
+    const lastRun = state.manifest?.runs.at(-1);
     return applyTemplate("sync.md", collected, state, {
         LAST_RUN_DATE: lastRun?.at ?? "unknown",
         ADDED_FILES: addedStr,
         MODIFIED_FILES: modifiedStr,
         DELETED_FILES: deletedStr,
-    });
+    }, "sync");
 }
 export function buildRemoveCommand(input, state) {
-    // Remove uses a minimal collected set — no project files needed
     const emptyCollected = { configs: {}, source: [], skipped: [] };
-    return applyTemplate("remove.md", emptyCollected, state, { USER_INPUT: input });
+    return applyTemplate("remove.md", emptyCollected, state, { USER_INPUT: input }, "remove");
 }
 export function buildAtomicSteps(collected, state) {
-    const fullContent = buildInitCommand(collected, state);
-    const vars = buildVars(collected, state);
-    const flags = buildFlags(collected, state);
     const version = getVersion();
     const date = new Date().toISOString().split("T")[0];
-    const preamble = `<!-- Generated by claude-setup ${version} on ${date} — DO NOT hand-edit -->\n`;
-    const idempotentCheck = `\nBefore writing: check if what you are about to write already exists in the target file\n(current content provided below). If yes: print "SKIPPED — already up to date" and stop.\nWrite only what is genuinely missing.\n\n`;
-    // Each step gets project context + specific instructions for its target
+    const vars = buildVars(collected, state);
+    const os = detectOS();
+    const header = `<!-- claude-setup ${version} ${date} -->\n`;
+    const preamble = `Before writing: check if what you are about to write already exists in the target file (current content provided below if it exists). If already up to date: print "SKIPPED — already up to date" and stop. Write only what is genuinely missing.\n\nRead /stack-0-context for full project info.\n\n`;
+    // Shared context block — written once, referenced by all steps
+    const sharedContext = header +
+        `## Project\n\n${vars.PROJECT_CONTEXT}\n\n` +
+        `{{#if HAS_SOURCE}}## Source samples\n\n${vars.SOURCE_CONTEXT}\n{{/if}}`;
+    const sharedContextProcessed = processConditionals(sharedContext, buildFlags(collected, state));
     const steps = [
+        {
+            filename: "stack-0-context.md",
+            content: sharedContextProcessed,
+        },
+        // --- Step 1: CLAUDE.md ---
         {
             filename: "stack-1-claude-md.md",
-            content: preamble + idempotentCheck +
-                `## Project context\n\n${vars.CONFIG_FILES}\n\n${vars.SOURCE_FILES}\n\n` +
+            content: header + preamble +
                 `## Target: CLAUDE.md\n\n` +
                 (state.claudeMd.exists
-                    ? `### Current CLAUDE.md — EXISTS — append only, never rewrite, never remove\n${vars.CLAUDE_MD_CONTENT}\n\n`
-                    : `CLAUDE.md does not exist. Create it.\n\n`) +
-                `Write or update CLAUDE.md for THIS specific project.\nMake it specific: reference actual file paths, actual patterns, actual conventions from the source above.\nNo generic boilerplate. Every line must trace back to something in the project files.\n` +
-                (state.claudeMd.exists ? `\nAppend only — never rewrite or remove existing content.` : ""),
+                    ? `### Current content — APPEND ONLY, never rewrite, never remove:\n${vars.CLAUDE_MD_CONTENT}\n\n`
+                    : `Does not exist — create it.\n\n`) +
+                `### What to write\n` +
+                `CLAUDE.md is the most valuable artifact. Make it specific to THIS project:\n` +
+                `- **Purpose**: one sentence describing what this project does\n` +
+                `- **Runtime**: language, framework, key dependencies from /stack-0-context\n` +
+                `- **Key dirs**: reference actual directory paths from the project tree\n` +
+                `- **Run/test/build commands**: extract from scripts in /stack-0-context\n` +
+                `- **Non-obvious conventions**: patterns you see in the source samples\n\n` +
+                `### Rules\n` +
+                `- Every line must reference something you actually saw in /stack-0-context\n` +
+                `- No generic boilerplate. Two different projects must produce two different CLAUDE.md files\n` +
+                `- If it exists above: read it fully, add only what is genuinely missing\n\n` +
+                `### Output\n` +
+                `Created/Updated: ✅ CLAUDE.md — [one clause: what you wrote and why]\n` +
+                `Skipped: ⏭ CLAUDE.md — [why not needed]\n`,
         },
+        // --- Step 2: .mcp.json ---
         {
             filename: "stack-2-mcp.md",
-            content: preamble + idempotentCheck +
-                `## Project context\n\n${vars.CONFIG_FILES}\n\n` +
+            content: header + preamble +
                 `## Target: .mcp.json\n\n` +
                 (state.mcpJson.exists
-                    ? `### Current .mcp.json — EXISTS — merge only, never remove existing entries\n${vars.MCP_JSON_CONTENT}\n\n`
-                    : `.mcp.json does not exist. Create only if you find evidence of external services in the config files above.\n\n`) +
-                `Only add MCP servers for services evidenced in the project files. No evidence = no server.\n` +
-                (state.mcpJson.exists ? `Merge only — never remove existing entries. Produce valid JSON.` : ""),
+                    ? `### Current content — MERGE ONLY, never remove existing entries:\n${vars.MCP_JSON_CONTENT}\n\n`
+                    : `Does not exist.\n\n`) +
+                `### When to create/update\n` +
+                `Add an MCP server ONLY if you find evidence in /stack-0-context:\n` +
+                `- Import statement referencing an external service\n` +
+                `- docker-compose service (database, cache, queue)\n` +
+                `- Env var name in .env.example matching a known service pattern\n` +
+                `- Explicit dependency on an MCP-compatible package\n\n` +
+                `No evidence = no server. Do not invent services.\n\n` +
+                `### OS-correct format (detected: ${os})\n` +
+                (os === "Windows"
+                    ? `Use: \`{ "command": "cmd", "args": ["/c", "npx", "<package>"] }\`\n`
+                    : `Use: \`{ "command": "npx", "args": ["<package>"] }\`\n`) +
+                `\n### Rules\n` +
+                `- All env var refs use \`\${VARNAME}\` syntax\n` +
+                `- Produce valid JSON only\n` +
+                `- If creating: document every new env var in .env.example\n\n` +
+                `### Output\n` +
+                `Created/Updated: ✅ .mcp.json — [what server and evidence source]\n` +
+                `Skipped: ⏭ .mcp.json — checked [files], found [nothing], no action\n`,
         },
+        // --- Step 3: .claude/settings.json ---
         {
             filename: "stack-3-settings.md",
-            content: preamble + idempotentCheck +
-                `## Project context\n\n${vars.CONFIG_FILES}\n\n` +
+            content: header + preamble +
                 `## Target: .claude/settings.json\n\n` +
                 (state.settings.exists
-                    ? `### Current settings.json — EXISTS — merge only, never remove existing hooks\n${vars.SETTINGS_CONTENT}\n\n`
-                    : `.claude/settings.json does not exist. Create only if hooks are genuinely warranted for this project.\n\n`) +
-                `Every hook adds overhead on every Claude Code action. Only add if clearly earned for THIS project.\n` +
-                (state.settings.exists ? `Merge only — never remove existing hooks. Never modify existing values.` : ""),
+                    ? `### Current content — MERGE ONLY, never remove existing hooks:\n${vars.SETTINGS_CONTENT}\n\n`
+                    : `Does not exist.\n\n`) +
+                `### When to create/update\n` +
+                `Add a hook ONLY if it runs on a pattern that repeats every session AND the cost is justified.\n` +
+                `Every hook adds overhead on every Claude Code action. Only add if clearly earned.\n\n` +
+                `### OS-correct hook format (detected: ${os})\n` +
+                (os === "Windows"
+                    ? `Use: \`{ "command": "cmd", "args": ["/c", "<command>"] }\`\n`
+                    : `Use: \`{ "command": "bash", "args": ["-c", "<command>"] }\`\n` +
+                        `**Bash quoting rule**: never use bare \`"\` inside \`-c "..."\` — use \`\\x22\` instead.\n` +
+                        `Replace \`'\` with \`\\x27\`, \`$\` in character classes with \`\\x24\`.\n`) +
+                `\n### Rules\n` +
+                `- If it exists above: audit quoting of existing hooks first, fix broken ones\n` +
+                `- Only add hooks for patterns that genuinely recur for this project type\n` +
+                `- Produce valid JSON only\n\n` +
+                `### Output\n` +
+                `Created/Updated: ✅ settings.json — [hook name and justification]\n` +
+                `Skipped: ⏭ settings.json — [why no hooks warranted]\n`,
         },
+        // --- Step 4: .claude/skills/ ---
         {
             filename: "stack-4-skills.md",
-            content: preamble + idempotentCheck +
-                `## Project context\n\n${vars.CONFIG_FILES}\n\n${vars.SOURCE_FILES}\n\n` +
-                `## Target: .claude/skills/\n\n` +
-                `Skills installed: ${vars.SKILLS_LIST}\n\n` +
-                `Only create skills for patterns that recur across this codebase and benefit from automatic loading.\n` +
-                `Use applies-when frontmatter so skills load only when relevant.\n` +
-                `If a similar skill already exists: extend it. Do not create a parallel one.\n` +
-                `Empty is fine — not every project needs skills.`,
+            content: header + preamble +
+                `## Target: .claude/skills/\n` +
+                `Installed: ${vars.SKILLS_LIST}\n\n` +
+                `### When to create\n` +
+                `Create a skill ONLY if:\n` +
+                `- A recurring multi-step project-specific pattern exists in /stack-0-context\n` +
+                `- It is NOT something Claude already knows (standard patterns don't need skills)\n` +
+                `- It will save time across multiple Claude Code sessions\n\n` +
+                `### Rules\n` +
+                `- Use \`applies-when:\` frontmatter so skills load only when relevant, not every message\n` +
+                `- If a similar skill already exists above: extend it, don't create a parallel one\n` +
+                `- Empty is valid — no skills is better than useless skills\n\n` +
+                `### Output\n` +
+                `Created: ✅ .claude/skills/[name] — [what pattern it captures]\n` +
+                `Skipped: ⏭ skills — checked [patterns], found [nothing project-specific]\n`,
         },
+        // --- Step 5: .claude/commands/ ---
         {
             filename: "stack-5-commands.md",
-            content: preamble + idempotentCheck +
-                `## Project context\n\n${vars.CONFIG_FILES}\n\n` +
-                `## Target: .claude/commands/ (not stack-*.md files)\n\n` +
-                `Commands installed: ${vars.COMMANDS_LIST}\n\n` +
-                `Only create commands that will actually be useful for this kind of project.\n` +
-                `Do not duplicate existing commands. Do not create stack-*.md files.`,
+            content: header + preamble +
+                `## Target: .claude/commands/ (excluding stack-*.md — those are setup artifacts)\n` +
+                `Installed: ${vars.COMMANDS_LIST}\n\n` +
+                `### When to create\n` +
+                `Create a command ONLY for project-specific multi-step workflows a developer repeats:\n` +
+                `- Deploy sequences\n` +
+                `- Database migration + seed\n` +
+                `- Release workflows\n` +
+                `- Environment setup for a new contributor\n\n` +
+                `Do NOT create commands for things expressible as a single shell alias.\n` +
+                `Look at the scripts in /stack-0-context for evidence of multi-step workflows.\n\n` +
+                `### Rules\n` +
+                `- If existing commands cover the same workflow: skip\n` +
+                `- Commands should be specific to this project, not generic\n\n` +
+                `### Output\n` +
+                `Created: ✅ .claude/commands/[name].md — [what workflow and why useful]\n` +
+                `Skipped: ⏭ commands — [why no project-specific workflows found]\n`,
         },
+        // --- Step 6: .github/workflows/ ---
         {
             filename: "stack-6-workflows.md",
-            content: preamble + idempotentCheck +
-                `## Target: .github/workflows/\n\n` +
+            content: header +
+                `## Target: .github/workflows/\n` +
                 `.github/ exists: ${vars.HAS_GITHUB_DIR}\n` +
-                `Workflows installed: ${vars.WORKFLOWS_LIST}\n\n` +
+                `Installed: ${vars.WORKFLOWS_LIST}\n\n` +
                 (state.hasGithubDir
-                    ? `Only create workflows warranted by the project. If workflows already exist: do not touch them.`
-                    : `.github/ does not exist. Only create workflows if the project clearly warrants them.`),
+                    ? (`### What to do\n` +
+                        `Check /stack-0-context for CI evidence: tests dir, Dockerfile, CI-related scripts.\n` +
+                        `If evidence found, print EXACTLY:\n\n` +
+                        `\`\`\`\n` +
+                        `⚙️  CI/CD GATE — action required\n\n` +
+                        `Evidence found:\n` +
+                        `  [list each piece of evidence]\n\n` +
+                        `Two questions before I proceed:\n` +
+                        `  1. Set up CI/CD? (yes / no / later)\n` +
+                        `  2. Connected to a remote GitHub repo? (yes / no)\n\n` +
+                        `I will not write .github/workflows/ until you answer.\n` +
+                        `\`\`\`\n\n` +
+                        `### Rules\n` +
+                        `- NEVER create or modify workflows without explicit developer confirmation\n` +
+                        `- If existing workflows exist: do not touch them\n` +
+                        `- Secrets must use \`\${{ secrets.VARNAME }}\` syntax only\n`)
+                    : (`### .github/ does not exist\n` +
+                        `Do not create workflows. Print:\n` +
+                        `Skipped: ⏭ .github/workflows/ — .github/ directory does not exist\n`)),
         },
     ];
     return steps;
@@ -243,17 +331,17 @@ export function buildAtomicSteps(collected, state) {
 export function buildOrchestratorCommand(steps) {
     const version = getVersion();
     const date = new Date().toISOString().split("T")[0];
-    const stepList = steps
+    // Skip step 0 (context) in the run list — it's referenced by other steps
+    const runSteps = steps.filter(s => s.filename !== "stack-0-context.md");
+    const stepList = runSteps
         .map((s, i) => `${i + 1}. /${s.filename.replace(".md", "")}`)
         .join("\n");
-    return `<!-- Generated by claude-setup ${version} on ${date} — DO NOT hand-edit -->
-<!-- Run /stack-init in Claude Code -->
+    return `<!-- claude-setup ${version} ${date} -->
 
-Run these in order. If one fails, fix it and continue from that step only.
-Do not re-run steps that already completed.
+Run these in order. If one fails, fix and continue from that step.
 
 ${stepList}
 
-After all steps complete: one-line summary of what was created.
+After all complete: one-line summary of what was created.
 `;
 }

package/dist/collect.d.ts

@@ -9,5 +9,14 @@ export interface CollectedFiles {
         reason: string;
     }>;
 }
-export declare function collectProjectFiles(cwd?: string): Promise<CollectedFiles>;
+export interface ProjectDigest {
+    configFilesFound: string[];
+    deps: string[];
+    scripts: string[];
+    tree: string;
+    envVars: string[];
+    configs: Record<string, string>;
+}
+export type CollectMode = "deep" | "normal" | "configOnly";
+export declare function collectProjectFiles(cwd?: string, mode?: CollectMode): Promise<CollectedFiles>;
 export declare function isEmptyProject(collected: CollectedFiles): boolean;