@promptscript/cli 1.0.0-alpha.4 → 1.0.0-alpha.6

package/index.js

@@ -296,6 +296,14 @@ function getPackageVersion(baseDir, relativePath = "../package.json") {
   return getPackageInfo(baseDir, relativePath).version;
 }
 
+// packages/core/src/logger.ts
+var noopLogger = {
+  verbose: () => {
+  },
+  debug: () => {
+  }
+};
+
 // packages/cli/src/commands/init.ts
 import { fileURLToPath } from "url";
 import { dirname as dirname2 } from "path";
@@ -331,6 +339,7 @@ var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
   LogLevel2[LogLevel2["Quiet"] = 0] = "Quiet";
   LogLevel2[LogLevel2["Normal"] = 1] = "Normal";
   LogLevel2[LogLevel2["Verbose"] = 2] = "Verbose";
+  LogLevel2[LogLevel2["Debug"] = 3] = "Debug";
   return LogLevel2;
 })(LogLevel || {});
 var globalContext = {
@@ -349,6 +358,9 @@ function isVerbose() {
 function isQuiet() {
   return globalContext.logLevel <= 0 /* Quiet */;
 }
+function isDebug() {
+  return globalContext.logLevel >= 3 /* Debug */;
+}
 function createSpinner(text) {
   if (isQuiet()) {
     const noopSpinner = ora({ isSilent: true });
@@ -393,6 +405,13 @@ var ConsoleOutput = {
     if (isQuiet()) return;
     console.log(chalk.yellow(`  \u2298 ${message}`));
   },
+  /**
+   * Print an unchanged file message.
+   */
+  unchanged(message) {
+    if (isQuiet()) return;
+    console.log(chalk.gray(`  \u25CB ${message}`));
+  },
   /**
    * Print an info message.
    */
@@ -617,6 +636,16 @@ async function detectFrameworks(services) {
 }
 
 // packages/cli/src/utils/ai-tools-detector.ts
+var PROMPTSCRIPT_MARKER = "PromptScript";
+var INSTRUCTION_FILES = [
+  "CLAUDE.md",
+  "claude.md",
+  ".cursorrules",
+  ".github/copilot-instructions.md",
+  "AGENTS.md",
+  "AI_INSTRUCTIONS.md",
+  "AI.md"
+];
 var AI_TOOL_PATTERNS = [
   {
     target: "github",
@@ -648,6 +677,15 @@ async function directoryHasContent(dir, services) {
     return false;
   }
 }
+async function isPromptScriptGenerated(filePath, services) {
+  try {
+    const content = await services.fs.readFile(filePath, "utf-8");
+    const header = content.slice(0, 500);
+    return header.includes(PROMPTSCRIPT_MARKER);
+  } catch {
+    return false;
+  }
+}
 async function detectAITools(services = createDefaultServices()) {
   const detected = [];
   const details = {
@@ -656,6 +694,7 @@ async function detectAITools(services = createDefaultServices()) {
     cursor: [],
     antigravity: []
   };
+  const migrationCandidates = [];
   for (const pattern of AI_TOOL_PATTERNS) {
     const foundFiles = [];
     for (const file of pattern.files) {
@@ -673,7 +712,15 @@ async function detectAITools(services = createDefaultServices()) {
       details[pattern.target] = foundFiles;
     }
   }
-  return { detected, details };
+  for (const file of INSTRUCTION_FILES) {
+    if (services.fs.existsSync(file)) {
+      const isGenerated = await isPromptScriptGenerated(file, services);
+      if (!isGenerated) {
+        migrationCandidates.push(file);
+      }
+    }
+  }
+  return { detected, details, migrationCandidates };
 }
 function getAllTargets() {
   return ["github", "claude", "cursor", "antigravity"];
@@ -694,6 +741,25 @@ function formatDetectionResults(detection) {
   }
   return lines;
 }
+function hasMigrationCandidates(detection) {
+  return detection.migrationCandidates.length > 0;
+}
+function formatMigrationHint(detection) {
+  if (detection.migrationCandidates.length === 0) {
+    return [];
+  }
+  const lines = [];
+  lines.push("");
+  lines.push("\u{1F4CB} Existing instruction files detected:");
+  for (const file of detection.migrationCandidates) {
+    lines.push(`   \u2022 ${file}`);
+  }
+  lines.push("");
+  lines.push("   These can be migrated to PromptScript for unified management.");
+  lines.push("   See: https://getpromptscript.dev/latest/guides/ai-migration-best-practices");
+  lines.push("   Or use the /migrate skill in Claude Code.");
+  return lines;
+}
 
 // packages/cli/src/prettier/loader.ts
 import { existsSync as existsSync2 } from "fs";
@@ -800,6 +866,506 @@ async function resolvePrettierOptions(config, basePath = process.cwd()) {
   return result;
 }
 
+// packages/cli/src/templates/migrate-skill.ts
+var MIGRATE_SKILL_CLAUDE = `---
+name: 'migrate-to-promptscript'
+description: 'Migrate existing AI instruction files to PromptScript format'
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash
+user-invocable: true
+---
+
+# Migrate to PromptScript
+
+## Overview
+
+This skill guides you through migrating existing AI instruction files
+to PromptScript format, creating a unified source of truth for all
+AI coding assistants.
+
+## Step 1: Discovery
+
+Search for existing instruction files using these patterns:
+
+Claude Code:
+
+- CLAUDE.md, claude.md, CLAUDE.local.md
+
+Cursor:
+
+- .cursorrules
+- .cursor/rules/\\*.md
+- .cursor/rules/\\*.mdc
+
+GitHub Copilot:
+
+- .github/copilot-instructions.md
+- .github/instructions/\\*.md
+
+Other:
+
+- AGENTS.md
+- AI_INSTRUCTIONS.md
+- AI.md
+- .ai/instructions.md
+
+Use Glob tool to find these files.
+
+## Step 2: Read and Analyze
+
+For each discovered file:
+
+1. Read the full content using the Read tool
+2. Identify sections by headers (##, ###) and patterns
+3. Classify content type using the mapping table below
+4. Note any tool-specific content that may need special handling
+
+## Step 3: Content Mapping
+
+Map source content to PromptScript blocks:
+
+| Source Pattern                       | PromptScript Block |
+| ------------------------------------ | ------------------ |
+| You are, persona, identity, role     | @identity          |
+| Tech stack, languages, frameworks    | @context           |
+| Coding standards, conventions, rules | @standards         |
+| Don't, Never, restrictions           | @restrictions      |
+| Commands, shortcuts                  | @shortcuts         |
+| API docs, references, knowledge base | @knowledge         |
+| Parameters, config values            | @params            |
+| File patterns, globs, applyTo        | @guards            |
+| Skills, capabilities                 | @skills            |
+| Agents, subagents                    | @agents            |
+| Local-only settings                  | @local             |
+
+## Step 4: Generate PromptScript
+
+### Required: @meta block
+
+Every PromptScript file needs metadata with id and syntax fields.
+
+### Identity (persona)
+
+Convert persona descriptions to @identity block with triple-quote string.
+
+### Context (project info)
+
+Convert tech stack to @context block with structured properties
+like project, languages, frameworks.
+
+### Standards (conventions)
+
+Convert coding standards to @standards block organized by category:
+code, naming, commits, etc.
+
+### Restrictions (don'ts)
+
+Convert restrictions to @restrictions block using dash prefix for each item.
+
+### Shortcuts (commands)
+
+Convert custom commands to @shortcuts block. Simple shortcuts use
+key-value format. Complex shortcuts use object format with
+prompt, description, and content fields.
+
+### Knowledge (references)
+
+Convert API docs and reference material to @knowledge block
+using triple-quote string for rich content.
+
+### Guards (file patterns)
+
+Convert file-specific rules to @guards block with globs array
+specifying file patterns.
+
+### Params (configuration)
+
+Convert configuration parameters to @params block with type annotations:
+range(), enum(), boolean.
+
+### Skills (capabilities)
+
+Convert skill definitions to @skills block with description,
+trigger, and content fields.
+
+### Agents (subagents)
+
+Convert agent definitions to @agents block with description,
+tools, model, and content fields.
+
+## Step 5: File Organization
+
+Simple Projects - single file structure:
+
+- .promptscript/project.prs
+- promptscript.yaml
+
+Complex Projects - modular file structure:
+
+- .promptscript/project.prs (main with @use imports)
+- .promptscript/context.prs
+- .promptscript/standards.prs
+- .promptscript/restrictions.prs
+- .promptscript/commands.prs
+- promptscript.yaml
+
+## Step 6: Configuration
+
+Create promptscript.yaml with:
+
+- version: '1'
+- project.id
+- input.entry pointing to main .prs file
+- targets for github, claude, cursor
+
+## Step 7: Validation
+
+After generating PromptScript files:
+
+1. Validate syntax: prs validate
+2. Test compilation: prs compile --dry-run
+3. Compare output with original files
+4. Iterate if content is missing or incorrect
+
+## Common Patterns
+
+### Merging Multiple Sources
+
+When instructions exist in multiple files:
+
+1. Identity: Take from most detailed source
+2. Standards: Merge all, deduplicate
+3. Restrictions: Combine all (union)
+4. Commands: Merge, resolve conflicts
+
+### Tool-Specific Content
+
+Handle tool-specific content:
+
+- GitHub prompts: Use @shortcuts with prompt: true
+- Claude agents: Use @agents block
+- Cursor rules: Map to @standards
+- Local content: Use @local block
+
+### Preserving Formatting
+
+Use triple-quote multiline strings for:
+
+- Rich markdown content
+- Code examples
+- Complex instructions
+
+## Syntax Rules
+
+Quick reference for PromptScript syntax:
+
+- Strings: quoted or identifier
+- Multi-line: triple quotes
+- Arrays: [item1, item2] or - item prefix
+- Objects: { key: value }
+- Comments: # comment
+- Required @meta fields: id, syntax
+
+## Quality Checklist
+
+Before completing migration:
+
+- @meta block has id and syntax
+- Identity is clear and specific
+- Standards are organized by category
+- Restrictions use dash prefix (-)
+- Shortcuts work in target tools
+- prs validate passes
+- prs compile produces correct output
+- No duplicate content across blocks
+
+## Troubleshooting
+
+### Missing @meta Error
+Add required metadata block at the start.
+
+### Multiline String in Object Error
+Assign multiline strings to named keys, don't leave them loose
+inside objects.
+
+### Content Not Appearing in Output
+Check block names match expected patterns and
+verify syntax with prs validate --verbose.
+`;
+var MIGRATE_SKILL_CURSOR = `# Migrate to PromptScript
+
+Use this command to migrate existing AI instruction files to PromptScript format.
+
+## Step 1: Discovery
+
+Search for existing instruction files:
+
+- CLAUDE.md, claude.md, CLAUDE.local.md
+- .cursorrules, .cursor/rules/*.mdc
+- .github/copilot-instructions.md
+- AGENTS.md, AI_INSTRUCTIONS.md
+
+## Step 2: Content Mapping
+
+Map source content to PromptScript blocks:
+
+| Source Pattern                       | PromptScript Block |
+| ------------------------------------ | ------------------ |
+| You are, persona, identity, role     | @identity          |
+| Tech stack, languages, frameworks    | @context           |
+| Coding standards, conventions, rules | @standards         |
+| Don't, Never, restrictions           | @restrictions      |
+| Commands, shortcuts                  | @shortcuts         |
+| API docs, references                 | @knowledge         |
+
+## Step 3: Generate PromptScript
+
+Create \`.promptscript/project.prs\` with:
+
+1. **@meta** block with id and syntax fields (required)
+2. **@identity** for persona/role descriptions
+3. **@context** for tech stack info
+4. **@standards** organized by category
+5. **@restrictions** with dash prefix for each item
+6. **@shortcuts** for commands
+
+## Step 4: Validation
+
+After generating:
+
+1. Run \`prs validate\`
+2. Run \`prs compile --dry-run\`
+3. Compare output with original files
+
+## Syntax Quick Reference
+
+- Strings: quoted or identifier
+- Multi-line: triple quotes (\`"""\`)
+- Arrays: \`[item1, item2]\`
+- Objects: \`{ key: value }\`
+- Comments: \`# comment\`
+
+## Quality Checklist
+
+- @meta block has id and syntax
+- Standards organized by category
+- Restrictions use dash prefix (-)
+- prs validate passes
+`;
+var MIGRATE_SKILL_ANTIGRAVITY = `# Migrate to PromptScript
+
+This rule provides guidance for migrating existing AI instruction files to PromptScript format.
+
+## Overview
+
+PromptScript creates a unified source of truth for all AI coding assistants,
+compiling to native formats for Claude, GitHub Copilot, Cursor, and Antigravity.
+
+## Step 1: Discovery
+
+Search for existing instruction files:
+
+- CLAUDE.md, claude.md, CLAUDE.local.md
+- .cursorrules, .cursor/rules/*.mdc
+- .github/copilot-instructions.md
+- .agent/rules/*.md
+- AGENTS.md, AI_INSTRUCTIONS.md
+
+## Step 2: Content Mapping
+
+Map source content to PromptScript blocks:
+
+| Source Pattern                       | PromptScript Block |
+| ------------------------------------ | ------------------ |
+| You are, persona, identity, role     | @identity          |
+| Tech stack, languages, frameworks    | @context           |
+| Coding standards, conventions, rules | @standards         |
+| Don't, Never, restrictions           | @restrictions      |
+| Commands, shortcuts                  | @shortcuts         |
+| API docs, references                 | @knowledge         |
+
+## Step 3: Generate PromptScript
+
+Create \`.promptscript/project.prs\` with required blocks:
+
+1. **@meta** - id and syntax fields (required)
+2. **@identity** - persona/role descriptions
+3. **@context** - tech stack info
+4. **@standards** - coding rules organized by category
+5. **@restrictions** - things to avoid (dash prefix)
+6. **@shortcuts** - commands
+
+## Step 4: Validation
+
+After generating PromptScript files:
+
+1. Run \`prs validate\` to check syntax
+2. Run \`prs compile --dry-run\` to preview output
+3. Compare compiled output with original files
+
+## Syntax Reference
+
+- Strings: quoted or identifier
+- Multi-line: triple quotes
+- Arrays: [item1, item2]
+- Objects: { key: value }
+- Comments: # comment
+`;
+var MIGRATE_SKILL_GITHUB = `---
+name: 'migrate-to-promptscript'
+description: 'Migrate existing AI instruction files to PromptScript format'
+allowed-tools:
+  - read
+  - write
+  - glob
+  - grep
+  - execute
+user-invocable: true
+---
+
+# Migrate to PromptScript
+
+## Overview
+
+This skill guides you through migrating existing AI instruction files
+to PromptScript format, creating a unified source of truth for all
+AI coding assistants.
+
+## Step 1: Discovery
+
+Search for existing instruction files using these patterns:
+
+Claude Code:
+
+- CLAUDE.md, claude.md, CLAUDE.local.md
+
+Cursor:
+
+- .cursorrules
+- .cursor/rules/\\*.md
+- .cursor/rules/\\*.mdc
+
+GitHub Copilot:
+
+- .github/copilot-instructions.md
+- .github/instructions/\\*.md
+
+Other:
+
+- AGENTS.md
+- AI_INSTRUCTIONS.md
+- AI.md
+- .ai/instructions.md
+
+## Step 2: Read and Analyze
+
+For each discovered file:
+
+1. Read the full content
+2. Identify sections by headers (##, ###) and patterns
+3. Classify content type using the mapping table below
+4. Note any tool-specific content that may need special handling
+
+## Step 3: Content Mapping
+
+Map source content to PromptScript blocks:
+
+| Source Pattern                       | PromptScript Block |
+| ------------------------------------ | ------------------ |
+| You are, persona, identity, role     | @identity          |
+| Tech stack, languages, frameworks    | @context           |
+| Coding standards, conventions, rules | @standards         |
+| Don't, Never, restrictions           | @restrictions      |
+| Commands, shortcuts                  | @shortcuts         |
+| API docs, references, knowledge base | @knowledge         |
+| Parameters, config values            | @params            |
+| File patterns, globs, applyTo        | @guards            |
+| Skills, capabilities                 | @skills            |
+| Agents, subagents                    | @agents            |
+| Local-only settings                  | @local             |
+
+## Step 4: Generate PromptScript
+
+### Required: @meta block
+
+Every PromptScript file needs metadata with id and syntax fields.
+
+### Identity (persona)
+
+Convert persona descriptions to @identity block with triple-quote string.
+
+### Context (project info)
+
+Convert tech stack to @context block with structured properties
+like project, languages, frameworks.
+
+### Standards (conventions)
+
+Convert coding standards to @standards block organized by category:
+code, naming, commits, etc.
+
+### Restrictions (don'ts)
+
+Convert restrictions to @restrictions block using dash prefix for each item.
+
+### Shortcuts (commands)
+
+Convert custom commands to @shortcuts block. Simple shortcuts use
+key-value format. Complex shortcuts use object format with
+prompt, description, and content fields.
+
+## Step 5: File Organization
+
+Simple Projects - single file structure:
+
+- .promptscript/project.prs
+- promptscript.yaml
+
+Complex Projects - modular file structure:
+
+- .promptscript/project.prs (main with @use imports)
+- .promptscript/context.prs
+- .promptscript/standards.prs
+- .promptscript/restrictions.prs
+- .promptscript/commands.prs
+- promptscript.yaml
+
+## Step 6: Configuration
+
+Create promptscript.yaml with:
+
+- version: '1'
+- project.id
+- input.entry pointing to main .prs file
+- targets for github, claude, cursor
+
+## Step 7: Validation
+
+After generating PromptScript files:
+
+1. Validate syntax: prs validate
+2. Test compilation: prs compile --dry-run
+3. Compare output with original files
+4. Iterate if content is missing or incorrect
+
+## Quality Checklist
+
+Before completing migration:
+
+- @meta block has id and syntax
+- Identity is clear and specific
+- Standards are organized by category
+- Restrictions use dash prefix (-)
+- Shortcuts work in target tools
+- prs validate passes
+- prs compile produces correct output
+- No duplicate content across blocks
+`;
+
 // packages/cli/src/commands/init.ts
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname2(__filename);
@@ -827,11 +1393,45 @@ async function initCommand(options, services = createDefaultServices()) {
     await fs4.writeFile("promptscript.yaml", configContent, "utf-8");
     const projectPsContent = generateProjectPs(config, projectInfo);
     await fs4.writeFile(".promptscript/project.prs", projectPsContent, "utf-8");
+    const installedSkillPaths = [];
+    if (options.migrate) {
+      if (config.targets.includes("claude")) {
+        await fs4.mkdir(".claude/skills/migrate-to-promptscript", { recursive: true });
+        await fs4.writeFile(
+          ".claude/skills/migrate-to-promptscript/SKILL.md",
+          MIGRATE_SKILL_CLAUDE,
+          "utf-8"
+        );
+        installedSkillPaths.push(".claude/skills/migrate-to-promptscript/SKILL.md");
+      }
+      if (config.targets.includes("github")) {
+        await fs4.mkdir(".github/skills/migrate-to-promptscript", { recursive: true });
+        await fs4.writeFile(
+          ".github/skills/migrate-to-promptscript/SKILL.md",
+          MIGRATE_SKILL_GITHUB,
+          "utf-8"
+        );
+        installedSkillPaths.push(".github/skills/migrate-to-promptscript/SKILL.md");
+      }
+      if (config.targets.includes("cursor")) {
+        await fs4.mkdir(".cursor/commands", { recursive: true });
+        await fs4.writeFile(".cursor/commands/migrate.md", MIGRATE_SKILL_CURSOR, "utf-8");
+        installedSkillPaths.push(".cursor/commands/migrate.md");
+      }
+      if (config.targets.includes("antigravity")) {
+        await fs4.mkdir(".agent/rules", { recursive: true });
+        await fs4.writeFile(".agent/rules/migrate.md", MIGRATE_SKILL_ANTIGRAVITY, "utf-8");
+        installedSkillPaths.push(".agent/rules/migrate.md");
+      }
+    }
     spinner.succeed("PromptScript initialized");
     ConsoleOutput.newline();
     console.log("Created:");
     ConsoleOutput.success("promptscript.yaml");
     ConsoleOutput.success(".promptscript/project.prs");
+    for (const skillPath of installedSkillPaths) {
+      ConsoleOutput.success(skillPath);
+    }
     ConsoleOutput.newline();
     console.log("Configuration:");
     ConsoleOutput.muted(`  Project: ${config.projectId}`);
@@ -852,8 +1452,38 @@ async function initCommand(options, services = createDefaultServices()) {
     }
     ConsoleOutput.newline();
     console.log("Next steps:");
-    ConsoleOutput.muted("1. Edit .promptscript/project.prs to customize your AI instructions");
-    ConsoleOutput.muted("2. Run: prs compile");
+    if (options.migrate && installedSkillPaths.length > 0) {
+      ConsoleOutput.muted("1. Use the migration skill to convert existing instructions:");
+      if (config.targets.includes("claude")) {
+        ConsoleOutput.muted("   Claude Code: /migrate");
+      }
+      if (config.targets.includes("github")) {
+        ConsoleOutput.muted("   GitHub Copilot: @workspace /migrate");
+      }
+      if (config.targets.includes("cursor")) {
+        ConsoleOutput.muted("   Cursor: /migrate");
+      }
+      if (config.targets.includes("antigravity")) {
+        ConsoleOutput.muted('   Antigravity: Ask to "migrate to PromptScript"');
+      }
+      ConsoleOutput.muted("2. Review generated .promptscript/project.prs");
+      ConsoleOutput.muted("3. Run: prs compile");
+    } else {
+      ConsoleOutput.muted("1. Edit .promptscript/project.prs to customize your AI instructions");
+      ConsoleOutput.muted("2. Run: prs compile");
+      if (hasMigrationCandidates(aiToolsDetection)) {
+        const migrationHint = formatMigrationHint(aiToolsDetection);
+        for (const line of migrationHint) {
+          if (line.startsWith("\u{1F4CB}") || line.includes("migrated") || line.includes("See:") || line.includes("Or use")) {
+            ConsoleOutput.info(line.replace(/^\s+/, ""));
+          } else if (line.trim().startsWith("\u2022")) {
+            ConsoleOutput.muted(line);
+          } else if (line.trim()) {
+            console.log(line);
+          }
+        }
+      }
+    }
   } catch (error) {
     if (error.name === "ExitPromptError") {
       ConsoleOutput.newline();
@@ -1294,10 +1924,26 @@ ${this.convention.rootWrapper.end}`;
   /**
    * Escape markdown special characters for Prettier compatibility.
    * - Escapes __ to \_\_ (to avoid emphasis)
-   * - Escapes /* to /\* (to avoid glob patterns being interpreted)
+   * - Escapes * in glob patterns (like packages/*) outside backticks
    */
   escapeMarkdownSpecialChars(content) {
-    return content.replace(/__/g, "\\_\\_").replace(/\/\*/g, "/\\*");
+    return content.split("\n").map((line) => {
+      let result = line.replace(/__/g, "\\_\\_");
+      result = this.escapeGlobAsteriskOutsideBackticks(result);
+      return result;
+    }).join("\n");
+  }
+  /**
+   * Escape glob asterisks (like packages/* or .cursor/rules/*.md) outside of backticks.
+   */
+  escapeGlobAsteriskOutsideBackticks(line) {
+    const parts = line.split("`");
+    return parts.map((part, index) => {
+      if (index % 2 === 0) {
+        return part.replace(/\/\*/g, "/\\*");
+      }
+      return part;
+    }).join("`");
   }
   indentContent(content, renderer, level) {
     const indent = renderer.indent ?? "";
@@ -1469,6 +2115,7 @@ var BaseFormatter = class {
    * - Trims trailing whitespace from lines
    * - Normalizes markdown table formatting
    * - Adds blank lines before lists when preceded by text
+   * - Adds blank lines before code blocks when preceded by text
    * - Escapes markdown special characters in paths
    */
   normalizeMarkdownForPrettier(content) {
@@ -1477,8 +2124,13 @@ var BaseFormatter = class {
     let inCodeBlock = false;
     for (const line of lines) {
       const trimmed = line.trimEnd();
-      if (trimmed.startsWith("```")) {
+      if (trimmed.trimStart().startsWith("```")) {
         inCodeBlock = !inCodeBlock;
+        if (trimmed.length > 0) {
+          const match2 = line.match(/^(\s*)/);
+          const leadingSpaces2 = match2?.[1]?.length ?? 0;
+          minIndent = Math.min(minIndent, leadingSpaces2);
+        }
         continue;
       }
       if (inCodeBlock) continue;
@@ -1494,17 +2146,30 @@ var BaseFormatter = class {
     inCodeBlock = false;
     for (const line of lines) {
       const trimmedLine = line.trimEnd();
-      if (trimmedLine.trimStart().startsWith("```")) {
+      const unindentedLine = minIndent > 0 ? trimmedLine.slice(minIndent) : trimmedLine;
+      const isCodeBlockMarker = trimmedLine.trimStart().startsWith("```");
+      const isCodeBlockStart = isCodeBlockMarker && !inCodeBlock;
+      if (isCodeBlockMarker) {
         inCodeBlock = !inCodeBlock;
       }
-      const unindentedLine = minIndent > 0 ? trimmedLine.slice(minIndent) : trimmedLine;
       if (inCodeBlock || unindentedLine.startsWith("```")) {
+        if (isCodeBlockStart) {
+          const prevLine2 = result.length > 0 ? result[result.length - 1] ?? "" : "";
+          if (prevLine2.trim() && !prevLine2.startsWith("#")) {
+            result.push("");
+          }
+        }
         result.push(unindentedLine);
         continue;
       }
       let processedLine = unindentedLine;
       processedLine = processedLine.replace(/__([^_]+)__/g, "\\_\\_$1\\_\\_");
-      processedLine = processedLine.replace(/\/\*/g, "/\\*");
+      processedLine = this.escapeGlobAsteriskOutsideBackticks(processedLine);
+      const prevLine = result.length > 0 ? result[result.length - 1] : "";
+      const isHeader = prevLine?.trimStart().startsWith("#");
+      if (isHeader && processedLine.trim()) {
+        result.push("");
+      }
       if (processedLine.trimStart().startsWith("|") && processedLine.trimEnd().endsWith("|")) {
         inTable = true;
         tableLines.push(processedLine.trim());
@@ -1514,9 +2179,14 @@ var BaseFormatter = class {
           tableLines = [];
           inTable = false;
         }
-        const prevLine = result.length > 0 ? result[result.length - 1] : "";
         const isListItem = processedLine.trimStart().startsWith("- ");
-        if (isListItem && prevLine && !prevLine.trimStart().startsWith("- ")) {
+        const isNumberedItem = /^\d+\.\s/.test(processedLine.trimStart());
+        const prevLineTrimmed = prevLine?.trimStart() ?? "";
+        const isPrevListItem = prevLineTrimmed.startsWith("- ") || /^\d+\.\s/.test(prevLineTrimmed);
+        const prevEndsWithColon = prevLine?.trimEnd().endsWith(":") ?? false;
+        if ((isListItem || isNumberedItem) && prevLine && !isPrevListItem && !isHeader) {
+          result.push("");
+        } else if ((isListItem || isNumberedItem) && prevEndsWithColon) {
           result.push("");
         }
         result.push(processedLine);
@@ -1527,6 +2197,19 @@ var BaseFormatter = class {
     }
     return result.join("\n");
   }
+  /**
+   * Escape glob asterisks (like packages/* or .cursor/rules/*.md) outside of backticks.
+   * Prettier escapes these to prevent them from being interpreted as emphasis markers.
+   */
+  escapeGlobAsteriskOutsideBackticks(line) {
+    const parts = line.split("`");
+    return parts.map((part, index) => {
+      if (index % 2 === 0) {
+        return part.replace(/\/\*/g, "/\\*");
+      }
+      return part;
+    }).join("`");
+  }
   /**
    * Strip all leading indentation from markdown content.
    * Used for AGENTS.md where content from multiple sources has inconsistent indentation.
@@ -1540,7 +2223,7 @@ var BaseFormatter = class {
       const trimmedEnd = line.trimEnd();
       if (trimmedEnd.trimStart().startsWith("```")) {
         if (!inCodeBlock) {
-          const prevLine2 = result.length > 0 ? result[result.length - 1] : "";
+          const prevLine2 = result.length > 0 ? result[result.length - 1] ?? "" : "";
           if (prevLine2 && prevLine2.trim()) {
             result.push("");
           }
@@ -1555,9 +2238,14 @@ var BaseFormatter = class {
       }
       let stripped = trimmedEnd.trimStart();
       stripped = stripped.replace(/__/g, "\\_\\_");
-      stripped = stripped.replace(/\/\*/g, "/\\*");
-      const prevLine = result.length > 0 ? result[result.length - 1] : "";
-      if (stripped.startsWith("- ") && prevLine && !prevLine.startsWith("- ")) {
+      stripped = this.escapeGlobAsteriskOutsideBackticks(stripped);
+      const prevLine = result.length > 0 ? result[result.length - 1] ?? "" : "";
+      const isListItem = stripped.startsWith("- ") || /^\d+\.\s/.test(stripped);
+      const isPrevList = prevLine.startsWith("- ") || /^\d+\.\s/.test(prevLine);
+      const prevEndsWithColon = prevLine.trimEnd().endsWith(":");
+      if (isListItem && prevLine && !isPrevList) {
+        result.push("");
+      } else if (isListItem && prevEndsWithColon) {
         result.push("");
       }
       result.push(stripped);
@@ -1898,7 +2586,9 @@ var GitHubFormatter = class extends BaseFormatter {
     lines.push(`# ${config.description}`);
     lines.push("");
     if (config.content) {
-      lines.push(config.content);
+      const dedentedContent = this.dedent(config.content);
+      const normalizedContent = this.normalizeMarkdownForPrettier(dedentedContent);
+      lines.push(normalizedContent);
     }
     return {
       path: `.github/instructions/${config.name}.instructions.md`,
@@ -1986,7 +2676,8 @@ var GitHubFormatter = class extends BaseFormatter {
   generatePromptFile(config) {
     const lines = [];
     lines.push("---");
-    lines.push(`description: "${config.description}"`);
+    const descQuote = config.description.includes("'") ? '"' : "'";
+    lines.push(`description: ${descQuote}${config.description}${descQuote}`);
     if (config.mode === "agent") {
       lines.push("mode: agent");
       if (config.tools && config.tools.length > 0) {
@@ -1998,11 +2689,13 @@ var GitHubFormatter = class extends BaseFormatter {
     lines.push("---");
     lines.push("");
     if (config.content) {
-      lines.push(config.content);
+      const dedentedContent = this.dedent(config.content);
+      const normalizedContent = this.normalizeMarkdownForPrettier(dedentedContent);
+      lines.push(normalizedContent);
     }
     return {
       path: `.github/prompts/${config.name}.prompt.md`,
-      content: lines.join("\n")
+      content: lines.join("\n") + "\n"
     };
   }
   // ============================================================
@@ -2044,7 +2737,8 @@ var GitHubFormatter = class extends BaseFormatter {
     lines.push("---");
     lines.push("");
     if (config.content) {
-      const normalizedContent = this.normalizeMarkdownForPrettier(config.content);
+      const dedentedContent = this.dedent(config.content);
+      const normalizedContent = this.normalizeMarkdownForPrettier(dedentedContent);
       lines.push(normalizedContent);
     }
     return {
@@ -2052,6 +2746,28 @@ var GitHubFormatter = class extends BaseFormatter {
       content: lines.join("\n") + "\n"
     };
   }
+  /**
+   * Remove common leading indentation from multiline text.
+   * Calculates minimum indent from lines 2+ only, since line 1 may have been
+   * trimmed (losing its indentation) while subsequent lines retain theirs.
+   */
+  dedent(text) {
+    const lines = text.split("\n");
+    if (lines.length <= 1) return text.trim();
+    const minIndent = lines.slice(1).filter((line) => line.trim().length > 0).reduce((min, line) => {
+      const match = line.match(/^(\s*)/);
+      const indent = match?.[1]?.length ?? 0;
+      return Math.min(min, indent);
+    }, Infinity);
+    if (minIndent === 0 || minIndent === Infinity) {
+      return text.trim();
+    }
+    const firstLine = lines[0] ?? "";
+    return [
+      firstLine.trim(),
+      ...lines.slice(1).map((line) => line.trim().length > 0 ? line.slice(minIndent) : "")
+    ].join("\n").trim();
+  }
   // ============================================================
   // AGENTS.md Generation
   // ============================================================
@@ -2187,7 +2903,9 @@ var GitHubFormatter = class extends BaseFormatter {
     lines.push("---");
     lines.push("");
     if (config.content) {
-      lines.push(config.content);
+      const dedentedContent = this.dedent(config.content);
+      const normalizedContent = this.normalizeMarkdownForPrettier(dedentedContent);
+      lines.push(normalizedContent);
     }
     return {
       path: `.github/agents/${config.name}.md`,
@@ -2642,7 +3360,9 @@ var ClaudeFormatter = class extends BaseFormatter {
     lines.push(`# ${config.description}`);
     lines.push("");
     if (config.content) {
-      lines.push(config.content);
+      const dedentedContent = this.dedent(config.content);
+      const normalizedContent = this.normalizeMarkdownForPrettier(dedentedContent);
+      lines.push(normalizedContent);
     }
     return {
       path: `.claude/rules/${config.name}.md`,
@@ -2741,7 +3461,8 @@ var ClaudeFormatter = class extends BaseFormatter {
     lines.push("---");
     lines.push("");
     if (config.content) {
-      const normalizedContent = this.normalizeMarkdownForPrettier(config.content);
+      const dedentedContent = this.dedent(config.content);
+      const normalizedContent = this.normalizeMarkdownForPrettier(dedentedContent);
       lines.push(normalizedContent);
     }
     return {
@@ -2749,6 +3470,28 @@ var ClaudeFormatter = class extends BaseFormatter {
       content: lines.join("\n") + "\n"
     };
   }
+  /**
+   * Remove common leading indentation from multiline text.
+   * Calculates minimum indent from lines 2+ only, since line 1 may have been
+   * trimmed (losing its indentation) while subsequent lines retain theirs.
+   */
+  dedent(text) {
+    const lines = text.split("\n");
+    if (lines.length <= 1) return text.trim();
+    const minIndent = lines.slice(1).filter((line) => line.trim().length > 0).reduce((min, line) => {
+      const match = line.match(/^(\s*)/);
+      const indent = match?.[1]?.length ?? 0;
+      return Math.min(min, indent);
+    }, Infinity);
+    if (minIndent === 0 || minIndent === Infinity) {
+      return text.trim();
+    }
+    const firstLine = lines[0] ?? "";
+    return [
+      firstLine.trim(),
+      ...lines.slice(1).map((line) => line.trim().length > 0 ? line.slice(minIndent) : "")
+    ].join("\n").trim();
+  }
   // ============================================================
   // Agent File Generation
   // ============================================================
@@ -2851,7 +3594,9 @@ var ClaudeFormatter = class extends BaseFormatter {
     lines.push("---");
     lines.push("");
     if (config.content) {
-      lines.push(config.content);
+      const dedentedContent = this.dedent(config.content);
+      const normalizedContent = this.normalizeMarkdownForPrettier(dedentedContent);
+      lines.push(normalizedContent);
     }
     return {
       path: `.claude/agents/${config.name}.md`,
@@ -2906,7 +3651,8 @@ var ClaudeFormatter = class extends BaseFormatter {
     const cleanText = text.split(/\n{2,}/).map(
       (para) => para.split("\n").map((line) => line.trim()).filter((line) => line).join("\n")
     ).filter((para) => para).join("\n\n");
-    return renderer.renderSection("Project", cleanText) + "\n";
+    const normalizedText = this.normalizeMarkdownForPrettier(cleanText);
+    return renderer.renderSection("Project", normalizedText) + "\n";
   }
   techStack(ast, renderer) {
     const context = this.findBlock(ast, "context");
@@ -2964,8 +3710,9 @@ var ClaudeFormatter = class extends BaseFormatter {
     const text = this.extractText(context.content);
     const archMatch = this.extractSectionWithCodeBlock(text, "## Architecture");
     if (!archMatch) return null;
-    const content = archMatch.replace("## Architecture", "").trim();
-    return renderer.renderSection("Architecture", content) + "\n";
+    const content = archMatch.replace("## Architecture", "");
+    const normalizedContent = this.normalizeMarkdownForPrettier(content);
+    return renderer.renderSection("Architecture", normalizedContent.trim()) + "\n";
   }
   codeStandards(ast, renderer) {
     const standards = this.findBlock(ast, "standards");
@@ -3046,7 +3793,7 @@ var ClaudeFormatter = class extends BaseFormatter {
       const props = this.getProps(shortcuts.content);
       for (const [cmd, desc] of Object.entries(props)) {
         const shortDesc = this.valueToString(desc).split("\n")[0] ?? "";
-        commandLines.push(`${cmd.padEnd(10)} - ${shortDesc}`);
+        commandLines.push(`${cmd.padEnd(10)} - ${shortDesc}`.trimEnd());
       }
     }
     if (commandLines.length === 0) return null;
@@ -3055,8 +3802,9 @@ var ClaudeFormatter = class extends BaseFormatter {
       const text = this.extractText(knowledge.content);
       const match = this.extractSectionWithCodeBlock(text, "## Development Commands");
       if (match) {
-        const devCmds = match.replace("## Development Commands", "").trim();
-        content += "\n\n" + devCmds;
+        const devCmds = match.replace("## Development Commands", "");
+        const normalizedDevCmds = this.normalizeMarkdownForPrettier(devCmds);
+        content += "\n\n" + normalizedDevCmds.trim();
       }
     }
     return renderer.renderSection("Commands", content) + "\n";
@@ -3067,8 +3815,9 @@ var ClaudeFormatter = class extends BaseFormatter {
     const text = this.extractText(knowledge.content);
     const match = this.extractSectionWithCodeBlock(text, "## Post-Work Verification");
     if (!match) return null;
-    const content = match.replace("## Post-Work Verification", "").trim();
-    return renderer.renderSection("Post-Work Verification", content) + "\n";
+    const content = match.replace("## Post-Work Verification", "");
+    const normalizedContent = this.normalizeMarkdownForPrettier(content);
+    return renderer.renderSection("Post-Work Verification", normalizedContent.trim()) + "\n";
   }
   documentation(ast, renderer) {
     const standards = this.findBlock(ast, "standards");
@@ -3446,13 +4195,39 @@ var CursorFormatter = class extends BaseFormatter {
     if (never) sections.push(never);
   }
   intro(ast) {
-    const projectInfo = this.extractProjectInfo(ast);
-    if (projectInfo.text.toLowerCase().startsWith("you are")) {
-      return projectInfo.text;
+    const identity2 = this.findBlock(ast, "identity");
+    if (identity2) {
+      const fullText = this.dedent(this.extractText(identity2.content));
+      if (fullText.toLowerCase().startsWith("you are")) {
+        return fullText;
+      }
     }
+    const projectInfo = this.extractProjectInfo(ast);
     const orgSuffix = projectInfo.org ? ` at ${projectInfo.org}` : "";
     return `You are working on ${projectInfo.text}${orgSuffix}.`;
   }
+  /**
+   * Remove common leading whitespace from all lines (dedent).
+   * Handles the case where trim() was already called, causing the first line
+   * to lose its indentation while subsequent lines retain theirs.
+   */
+  dedent(text) {
+    const lines = text.split("\n");
+    if (lines.length <= 1) return text.trim();
+    const minIndent = lines.slice(1).filter((line) => line.trim().length > 0).reduce((min, line) => {
+      const match = line.match(/^(\s*)/);
+      const indent = match?.[1]?.length ?? 0;
+      return Math.min(min, indent);
+    }, Infinity);
+    if (minIndent === 0 || minIndent === Infinity) {
+      return text.trim();
+    }
+    const firstLine = lines[0] ?? "";
+    return [
+      firstLine.trim(),
+      ...lines.slice(1).map((line) => line.trim().length > 0 ? line.slice(minIndent) : "")
+    ].join("\n").trim();
+  }
   /**
    * Generate YAML frontmatter for Cursor MDC format.
    * @see https://cursor.com/docs/context/rules
@@ -15378,11 +16153,13 @@ var Resolver = class {
   cache;
   resolving;
   cacheEnabled;
+  logger;
   constructor(options) {
     this.loader = new FileLoader(options);
     this.cache = /* @__PURE__ */ new Map();
     this.resolving = /* @__PURE__ */ new Set();
     this.cacheEnabled = options.cache !== false;
+    this.logger = options.logger ?? noopLogger;
   }
   /**
    * Resolve a PromptScript file and all its dependencies.
@@ -15394,15 +16171,19 @@ var Resolver = class {
   async resolve(entryPath) {
     const absPath = this.loader.toAbsolutePath(entryPath);
     if (this.resolving.has(absPath)) {
+      this.logger.debug(`Circular dependency detected: ${absPath}`);
       throw new CircularDependencyError([...this.resolving, absPath]);
     }
     if (this.cacheEnabled && this.cache.has(absPath)) {
+      this.logger.debug(`Cache hit: ${absPath}`);
       return this.cache.get(absPath);
     }
     this.resolving.add(absPath);
+    this.logger.verbose(`Parsing ${absPath}`);
     try {
       const result = await this.doResolve(absPath);
       if (this.cacheEnabled) {
+        this.logger.debug(`Cache store: ${absPath}`);
         this.cache.set(absPath, result);
       }
       return result;
@@ -15421,16 +16202,33 @@ var Resolver = class {
       return { ast: null, sources, errors };
     }
     let ast = parseData.ast;
+    this.logger.debug(`AST node count: ${this.countNodes(ast)}`);
     ast = await this.resolveInherit(ast, absPath, sources, errors);
     ast = await this.resolveImports(ast, absPath, sources, errors);
+    if (ast.extends.length > 0) {
+      this.logger.debug(`Applying ${ast.extends.length} extension(s)`);
+    }
     ast = applyExtends(ast);
     ast = await resolveNativeSkills(ast, this.loader.getRegistryPath(), absPath);
+    this.logger.debug(`Resolved ${sources.length} source file(s)`);
     return {
       ast,
       sources: [...new Set(sources)],
       errors
     };
   }
+  /**
+   * Count nodes in AST for debug output.
+   */
+  countNodes(ast) {
+    let count = 1;
+    if (ast.meta) count++;
+    if (ast.inherit) count++;
+    count += ast.uses.length;
+    count += ast.blocks.length;
+    count += ast.extends.length;
+    return count;
+  }
   /**
    * Load and parse a file.
    */
@@ -15465,11 +16263,14 @@ var Resolver = class {
       return ast;
     }
     const parentPath = this.loader.resolveRef(ast.inherit.path, absPath);
+    this.logger.verbose(`Resolving inherit: ${ast.inherit.path.raw}`);
+    this.logger.verbose(`  \u2192 ${parentPath}`);
     try {
       const parent = await this.resolve(parentPath);
       sources.push(...parent.sources);
       errors.push(...parent.errors);
       if (parent.ast) {
+        this.logger.debug(`Merging with parent AST`);
         return resolveInheritance(parent.ast, ast);
       }
     } catch (err) {
@@ -15487,11 +16288,14 @@ var Resolver = class {
     let result = ast;
     for (const use of ast.uses) {
       const importPath = this.loader.resolveRef(use.path, absPath);
+      this.logger.verbose(`Resolving import: ${use.path.raw}`);
+      this.logger.verbose(`  \u2192 ${importPath}`);
       try {
         const imported = await this.resolve(importPath);
         sources.push(...imported.sources);
         errors.push(...imported.errors);
         if (imported.ast) {
+          this.logger.debug(`Merging import${use.alias ? ` as "${use.alias}"` : ""}`);
           result = resolveUses(result, use, imported.ast);
         }
       } catch (err) {
@@ -16765,6 +17569,7 @@ var Validator = class {
   rules;
   config;
   disabledRules;
+  logger;
   /**
    * Create a new validator instance.
    *
@@ -16774,11 +17579,13 @@ var Validator = class {
     this.config = config;
     this.rules = [...allRules];
     this.disabledRules = new Set(config.disableRules ?? []);
+    this.logger = config.logger ?? noopLogger;
     if (config.customRules) {
       for (const rule of config.customRules) {
         this.rules.push(rule);
       }
     }
+    this.logger.debug(`Validator initialized with ${this.rules.length} rules`);
   }
   /**
    * Validate an AST.
@@ -16788,15 +17595,22 @@ var Validator = class {
    */
   validate(ast) {
     const messages = [];
+    const activeRules = this.rules.filter(
+      (r) => !this.disabledRules.has(r.name) && !this.disabledRules.has(r.id)
+    );
+    this.logger.verbose(`Running ${activeRules.length} validation rules`);
     for (const rule of this.rules) {
       if (this.disabledRules.has(rule.name) || this.disabledRules.has(rule.id)) {
+        this.logger.debug(`Skipping disabled rule: ${rule.name}`);
         continue;
       }
       const configuredSeverity = this.config.rules?.[rule.name];
       const severity = configuredSeverity ?? rule.defaultSeverity;
       if (severity === "off") {
+        this.logger.debug(`Skipping off rule: ${rule.name}`);
         continue;
       }
+      this.logger.debug(`Running rule: ${rule.name} (${severity})`);
       const ctx = {
         ast,
         config: this.config,
@@ -16814,6 +17628,9 @@ var Validator = class {
     const errors = messages.filter((m) => m.severity === "error");
     const warnings = messages.filter((m) => m.severity === "warning");
     const infos = messages.filter((m) => m.severity === "info");
+    if (errors.length > 0 || warnings.length > 0) {
+      this.logger.verbose(`Validation: ${errors.length} error(s), ${warnings.length} warning(s)`);
+    }
     return {
       valid: errors.length === 0,
       errors,
@@ -16895,13 +17712,16 @@ ${afterMarker.replace(/^\n+/, "\n")}`;
 var Compiler = class _Compiler {
   constructor(options) {
     this.options = options;
-    this.resolver = new Resolver(options.resolver);
-    this.validator = new Validator(options.validator);
+    this.logger = options.logger ?? noopLogger;
+    this.resolver = new Resolver({ ...options.resolver, logger: this.logger });
+    this.validator = new Validator({ ...options.validator, logger: this.logger });
     this.loadedFormatters = this.loadFormatters(options.formatters);
+    this.logger.debug(`Compiler initialized with ${this.loadedFormatters.length} formatters`);
   }
   resolver;
   validator;
   loadedFormatters;
+  logger;
   /**
    * Compile a PromptScript file through the full pipeline.
    *
@@ -16909,6 +17729,10 @@ var Compiler = class _Compiler {
    * @returns Compilation result with outputs, errors, and stats
    */
   async compile(entryPath) {
+    this.logger.verbose(`Entry: ${entryPath}`);
+    this.logger.verbose(
+      `Targets: ${this.loadedFormatters.map((f) => f.formatter.name).join(", ")}`
+    );
     const startTotal = Date.now();
     const stats = {
       resolveTime: 0,
@@ -16916,6 +17740,7 @@ var Compiler = class _Compiler {
       formatTime: 0,
       totalTime: 0
     };
+    this.logger.verbose("=== Stage 1: Resolve ===");
     const startResolve = Date.now();
     let resolved;
     try {
@@ -16923,6 +17748,7 @@ var Compiler = class _Compiler {
     } catch (err) {
       stats.resolveTime = Date.now() - startResolve;
       stats.totalTime = Date.now() - startTotal;
+      this.logger.verbose(`Resolve failed (${stats.resolveTime}ms)`);
       return {
         success: false,
         outputs: /* @__PURE__ */ new Map(),
@@ -16932,6 +17758,7 @@ var Compiler = class _Compiler {
       };
     }
     stats.resolveTime = Date.now() - startResolve;
+    this.logger.verbose(`Resolve completed (${stats.resolveTime}ms)`);
     if (resolved.errors.length > 0 || !resolved.ast) {
       stats.totalTime = Date.now() - startTotal;
       return {
@@ -16942,9 +17769,11 @@ var Compiler = class _Compiler {
         stats
       };
     }
+    this.logger.verbose("=== Stage 2: Validate ===");
     const startValidate = Date.now();
     const validation = this.validator.validate(resolved.ast);
     stats.validateTime = Date.now() - startValidate;
+    this.logger.verbose(`Validate completed (${stats.validateTime}ms)`);
     if (!validation.valid) {
       stats.totalTime = Date.now() - startTotal;
       return {
@@ -16955,16 +17784,23 @@ var Compiler = class _Compiler {
         stats
       };
     }
+    this.logger.verbose("=== Stage 3: Format ===");
     const startFormat = Date.now();
     const outputs = /* @__PURE__ */ new Map();
     const formatErrors = [];
     for (const { formatter, config } of this.loadedFormatters) {
+      const formatterStart = Date.now();
+      this.logger.verbose(`Formatting for ${formatter.name}`);
       try {
         const formatOptions = this.getFormatOptionsForTarget(formatter.name, config);
+        this.logger.debug(`  Convention: ${formatOptions.convention ?? "default"}`);
         const output = formatter.format(resolved.ast, formatOptions);
+        const formatterTime = Date.now() - formatterStart;
+        this.logger.verbose(`  \u2192 ${output.path} (${formatterTime}ms)`);
         outputs.set(output.path, addMarkerToOutput(output));
         if (output.additionalFiles) {
           for (const additionalFile of output.additionalFiles) {
+            this.logger.verbose(`  \u2192 ${additionalFile.path} (additional)`);
             outputs.set(additionalFile.path, addMarkerToOutput(additionalFile));
           }
         }
@@ -16978,6 +17814,7 @@ var Compiler = class _Compiler {
     }
     stats.formatTime = Date.now() - startFormat;
     stats.totalTime = Date.now() - startTotal;
+    this.logger.verbose(`Format completed (${stats.formatTime}ms)`);
     if (formatErrors.length > 0) {
       return {
         success: false,
@@ -17277,6 +18114,24 @@ var PROMPTSCRIPT_MARKERS = [
   "> Auto-generated by PromptScript"
   // Legacy - for backwards compatibility
 ];
+var MARKER_REGEX = /<!-- PromptScript [^>]+ -->\n*/g;
+function stripMarkers(content) {
+  return content.replace(MARKER_REGEX, "");
+}
+function createCliLogger() {
+  return {
+    verbose: (message) => {
+      if (isVerbose() || isDebug()) {
+        ConsoleOutput.verbose(message);
+      }
+    },
+    debug: (message) => {
+      if (isDebug()) {
+        ConsoleOutput.debug(message);
+      }
+    }
+  };
+}
 function parseTargets(targets) {
   return targets.map((entry) => {
     if (typeof entry === "string") {
@@ -17290,10 +18145,10 @@ function parseTargets(targets) {
     return { name, config };
   }).filter((target) => target.config?.enabled !== false);
 }
-async function isPromptScriptGenerated(filePath) {
+async function isPromptScriptGenerated2(filePath) {
   try {
     const content = await readFile6(filePath, "utf-8");
-    const lines = content.split("\n").slice(0, 10);
+    const lines = content.split("\n").slice(0, 20);
     return lines.some((line) => PROMPTSCRIPT_MARKERS.some((marker) => line.includes(marker)));
   } catch {
     return false;
@@ -17321,7 +18176,7 @@ function printErrors(errors) {
   }
 }
 async function writeOutputs(outputs, options, _config, services) {
-  const result = { written: [], skipped: [] };
+  const result = { written: [], skipped: [], unchanged: [] };
   let overwriteAll = false;
   const conflicts = [];
   for (const output of outputs.values()) {
@@ -17329,16 +18184,26 @@ async function writeOutputs(outputs, options, _config, services) {
     const fileExists2 = existsSync7(outputPath);
     if (options.dryRun) {
       if (fileExists2) {
-        const isGenerated2 = await isPromptScriptGenerated(outputPath);
+        const isGenerated2 = await isPromptScriptGenerated2(outputPath);
         if (isGenerated2) {
-          ConsoleOutput.dryRun(`Would overwrite: ${outputPath}`);
+          const existingContent = await readFile6(outputPath, "utf-8");
+          const existingWithoutMarker = stripMarkers(existingContent);
+          const newWithoutMarker = stripMarkers(output.content);
+          if (existingWithoutMarker === newWithoutMarker) {
+            ConsoleOutput.dryRun(`Unchanged: ${outputPath}`);
+            result.unchanged.push(outputPath);
+          } else {
+            ConsoleOutput.dryRun(`Would overwrite: ${outputPath}`);
+            result.written.push(outputPath);
+          }
         } else {
           ConsoleOutput.warning(`Would conflict: ${outputPath} (not generated by PromptScript)`);
+          result.written.push(outputPath);
         }
       } else {
         ConsoleOutput.dryRun(`Would write: ${outputPath}`);
+        result.written.push(outputPath);
       }
-      result.written.push(outputPath);
       continue;
     }
     if (!fileExists2) {
@@ -17348,8 +18213,16 @@ async function writeOutputs(outputs, options, _config, services) {
       result.written.push(outputPath);
       continue;
     }
-    const isGenerated = await isPromptScriptGenerated(outputPath);
+    const isGenerated = await isPromptScriptGenerated2(outputPath);
     if (isGenerated) {
+      const existingContent = await readFile6(outputPath, "utf-8");
+      const existingWithoutMarker = stripMarkers(existingContent);
+      const newWithoutMarker = stripMarkers(output.content);
+      if (existingWithoutMarker === newWithoutMarker) {
+        ConsoleOutput.unchanged(outputPath);
+        result.unchanged.push(outputPath);
+        continue;
+      }
       await mkdir2(dirname5(outputPath), { recursive: true });
       await writeFile2(outputPath, output.content, "utf-8");
       ConsoleOutput.success(outputPath);
@@ -17416,12 +18289,16 @@ function printWarnings(warnings) {
 }
 async function compileCommand(options, services = createDefaultServices()) {
   const spinner = createSpinner("Loading configuration...").start();
+  const logger = createCliLogger();
   try {
+    logger.verbose("Loading configuration...");
     const config = await loadConfig(options.config);
     spinner.text = "Compiling...";
     const selectedTarget = options.target ?? options.format;
     const targets = selectedTarget ? [{ name: selectedTarget }] : parseTargets(config.targets);
     const registryPath = options.registry ?? config.registry?.path ?? "./registry";
+    logger.verbose(`Registry: ${registryPath}`);
+    logger.debug(`Config: ${JSON.stringify(config, null, 2)}`);
     const prettierOptions = await resolvePrettierOptions(config, process.cwd());
     const compiler = new Compiler({
       resolver: {
@@ -17431,7 +18308,8 @@ async function compileCommand(options, services = createDefaultServices()) {
       validator: config.validation,
       formatters: targets,
       customConventions: config.customConventions,
-      prettier: prettierOptions
+      prettier: prettierOptions,
+      logger
     });
     const entryPath = resolve4("./.promptscript/project.prs");
     if (!existsSync7(entryPath)) {
@@ -17450,6 +18328,9 @@ async function compileCommand(options, services = createDefaultServices()) {
     spinner.succeed("Compilation successful");
     ConsoleOutput.newline();
     const writeResult = await writeOutputs(result.outputs, options, config, services);
+    if (writeResult.unchanged.length > 0) {
+      ConsoleOutput.muted(`Unchanged ${writeResult.unchanged.length} file(s)`);
+    }
     if (writeResult.skipped.length > 0) {
       ConsoleOutput.muted(`Skipped ${writeResult.skipped.length} file(s)`);
     }
@@ -18080,18 +18961,22 @@ function printResults(results) {
 var __filename2 = fileURLToPath2(import.meta.url);
 var __dirname2 = dirname7(__filename2);
 var program = new Command();
-program.name("prs").description("PromptScript CLI - Standardize AI instructions").version(getPackageVersion(__dirname2, "./package.json")).option("--verbose", "Enable verbose output").option("--quiet", "Suppress non-error output").hook("preAction", (thisCommand) => {
+program.name("prs").description("PromptScript CLI - Standardize AI instructions").version(getPackageVersion(__dirname2, "./package.json")).option("--verbose", "Enable verbose output").option("--debug", "Enable debug output (includes verbose)").option("--quiet", "Suppress non-error output").hook("preAction", (thisCommand) => {
   const opts = thisCommand.opts();
   if (opts["quiet"]) {
     setContext({ logLevel: 0 /* Quiet */ });
+  } else if (opts["debug"]) {
+    setContext({ logLevel: 3 /* Debug */ });
   } else if (opts["verbose"]) {
     setContext({ logLevel: 2 /* Verbose */ });
   }
-  if (process.env["PROMPTSCRIPT_VERBOSE"] === "1" || process.env["PROMPTSCRIPT_VERBOSE"] === "true") {
+  if (process.env["PROMPTSCRIPT_DEBUG"] === "1" || process.env["PROMPTSCRIPT_DEBUG"] === "true") {
+    setContext({ logLevel: 3 /* Debug */ });
+  } else if (process.env["PROMPTSCRIPT_VERBOSE"] === "1" || process.env["PROMPTSCRIPT_VERBOSE"] === "true") {
     setContext({ logLevel: 2 /* Verbose */ });
   }
 });
-program.command("init").description("Initialize PromptScript in current directory").option("-n, --name <name>", "Project name (auto-detected from package.json, etc.)").option("-t, --team <team>", "Team namespace").option("--inherit <path>", "Inheritance path (e.g., @company/team)").option("--registry <path>", "Registry path").option("--targets <targets...>", "Target AI tools (github, claude, cursor)").option("-i, --interactive", "Force interactive mode").option("-y, --yes", "Skip prompts, use defaults").option("-f, --force", "Force reinitialize even if already initialized").action((opts) => initCommand(opts));
+program.command("init").description("Initialize PromptScript in current directory").option("-n, --name <name>", "Project name (auto-detected from package.json, etc.)").option("-t, --team <team>", "Team namespace").option("--inherit <path>", "Inheritance path (e.g., @company/team)").option("--registry <path>", "Registry path").option("--targets <targets...>", "Target AI tools (github, claude, cursor)").option("-i, --interactive", "Force interactive mode").option("-y, --yes", "Skip prompts, use defaults").option("-f, --force", "Force reinitialize even if already initialized").option("-m, --migrate", "Install migration skill for AI-assisted migration").action((opts) => initCommand(opts));
 program.command("compile").description("Compile PromptScript to target formats").option("-t, --target <target>", "Specific target (github, claude, cursor)").option("-f, --format <format>", "Output format (alias for --target)").option("-a, --all", "All configured targets", true).option("-w, --watch", "Watch mode").option("-o, --output <dir>", "Output directory").option("--dry-run", "Preview changes").option("--registry <path>", "Registry path (overrides config)").option("-c, --config <path>", "Path to custom config file").option("--force", "Force overwrite existing files without prompts").action((opts) => compileCommand(opts));
 program.command("validate").description("Validate PromptScript files").option("--strict", "Treat warnings as errors").option("--format <format>", "Output format (text, json)", "text").action(validateCommand);
 program.command("pull").description("Pull updates from registry").option("-f, --force", "Force overwrite").option("--dry-run", "Preview changes without pulling").option("-b, --branch <name>", "Git branch to pull from").option("--tag <name>", "Git tag to pull from").option("--commit <hash>", "Git commit to pull from").option("--refresh", "Force re-fetch from remote (ignore cache)").action(pullCommand);