heraspec 0.1.18 → 0.1.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -134,6 +134,8 @@ var init_config = __esm({
134
134
  HERASPEC_MARKERS = {
135
135
  PROJECT_MD: "project.md",
136
136
  AGENTS_MD: "AGENTS.heraspec.md",
137
+ AGENTS_CUSTOM_MD: "AGENTS.custom.md",
138
+ STATE_JSON: ".heraspec-state.json",
137
139
  CONFIG_YAML: "config.yaml",
138
140
  PROPOSAL_MD: "proposal.md",
139
141
  TASKS_MD: "tasks.md",
@@ -266,6 +268,422 @@ var init_file_system = __esm({
266
268
  }
267
269
  });
268
270
 
271
+ // src/core/templates/index.ts
272
+ var TemplateManager;
273
+ var init_templates = __esm({
274
+ "src/core/templates/index.ts"() {
275
+ "use strict";
276
+ TemplateManager = class {
277
+ static getProjectTemplate() {
278
+ return `# HeraSpec Project
279
+
280
+ ## Slash Commands (Agent Triggers)
281
+
282
+ When the user types messages starting with a slash (/), you MUST intercept them as action triggers rather than conversational queries. Please execute the corresponding terminal commands immediately:
283
+
284
+ - /heraspec [args] : Run the heraspec CLI tool with the provided arguments (e.g. /heraspec validate my-change)
285
+ - /sync : Run heraspec sync <current-change>
286
+ - /archive : Run heraspec archive <current-change> --yes
287
+ - /skill [name] : Run heraspec skill add [name]
288
+ - /hotfix [title] : Run heraspec hotfix [title]
289
+
290
+ *If the user types a slash command, do not explain what you are going to do, just run the terminal command and report the output.*
291
+
292
+ ## Overview
293
+ Describe your project here.
294
+
295
+ ## Project Types
296
+ - List your project type(s) here (e.g., node-service, generic-webapp, backend-api, frontend-app, multi-stack, wordpress-plugin, wordpress-theme, perfex-module, laravel-package, content-channel)
297
+
298
+ ## Tech Stack
299
+ - List primary languages, frameworks, runtime, and key libraries
300
+
301
+ ## Architecture
302
+ Describe the high-level architecture: entry points, module structure, data flow.
303
+
304
+ ## Key Dependencies
305
+ List critical dependencies and their purposes (e.g., better-sqlite3 for memory, commander for CLI).
306
+
307
+ ## Conventions
308
+ Define coding standards, architectural patterns, and conventions to follow.
309
+ `;
310
+ }
311
+ static getCustomAgentsTemplate(projectName) {
312
+ const titleSuffix = projectName ? ` (${projectName})` : "";
313
+ return `# Project-Specific Agent Rules - HeraSpec Custom Layer${titleSuffix}
314
+
315
+ > **100% Project-Owned File**: HeraSpec CLI upgrades to \`AGENTS.heraspec.md\` will NEVER modify or overwrite this file.
316
+ > Add project-specific architecture invariants, CI/test gates, localization rules, security checks, and deployment bans below.
317
+
318
+ ## Project-Specific Invariants & Quality Gates
319
+
320
+ - Add project-specific architecture constraints, test commands, and verification gates here.
321
+ `;
322
+ }
323
+ static resolveActiveDomains(ctx) {
324
+ if (ctx?.includeAllStacks) {
325
+ return { includeWordpress: true, includePerfex: true, includeContentChannel: true };
326
+ }
327
+ const types = new Set((ctx?.projectTypes || []).map((t) => t.toLowerCase()));
328
+ const skillKeys = (ctx?.installedSkills || []).map(
329
+ (s) => `${s.projectType || ""}/${s.name}`.toLowerCase()
330
+ );
331
+ const includeWordpress = Array.from(types).some((t) => t.startsWith("wordpress")) || skillKeys.some((k) => k.includes("wordpress") || k.includes("ux-element") || k.includes("plugin-check") || k.includes("plugin-directory"));
332
+ const includePerfex = types.has("perfex-module") || skillKeys.some((k) => k.includes("perfex-module") || k.includes("module-codebase") || k.includes("code-quality-guidelines"));
333
+ const includeContentChannel = types.has("content-channel") || skillKeys.some((k) => k.includes("content-channel") || k.includes("content-strategy") || k.includes("content-scripting"));
334
+ return { includeWordpress, includePerfex, includeContentChannel };
335
+ }
336
+ static buildIdeDiscoverySection(ctx) {
337
+ const customFile = ctx?.customFileName || "AGENTS.custom.md";
338
+ const projectLabel = ctx?.projectName || "Current Project";
339
+ const typesLabel = ctx?.projectTypes && ctx.projectTypes.length > 0 ? ctx.projectTypes.join(", ") : "unspecified (configure in heraspec/config.yaml)";
340
+ const ideFiles = ctx?.detectedIdeFiles || [];
341
+ const skillRoots = ctx?.detectedSkillRoots || [];
342
+ const installedSkills = ctx?.installedSkills || [];
343
+ const ideFilesLines = ideFiles.length > 0 ? ideFiles.map((f) => ` - [${f.relativePath}](${f.relativePath}) (${f.label}, ${f.scope})`).join("\n") : " - None auto-detected yet (check `.` and `..` for `GEMINI.md`, `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.windsurfrules`, `.github/copilot-instructions.md`).";
344
+ const skillRootsLines = skillRoots.length > 0 ? skillRoots.map((r) => ` - \`${r.relativePath}\` (${r.profile}, ${r.scope})`).join("\n") : " - Use canonical `heraspec/skills/*/skill.md`.";
345
+ const skillsSummaryLines = installedSkills.length > 0 ? installedSkills.map((s) => {
346
+ const label = s.projectType ? `${s.projectType}/${s.name}` : s.name;
347
+ const desc = s.description ? `: ${s.description}` : "";
348
+ return ` - \`${label}\` ([${s.relativePath}](${s.relativePath}))${desc}`;
349
+ }).join("\n") : " - No skills installed yet (`heraspec skill list` / `heraspec skill add <name>`).";
350
+ return `## Rule Precedence & IDE Workspace Discovery (Auto-Combined)
351
+
352
+ Before planning or editing code, agents MUST load and combine workspace rules in this exact order of precedence:
353
+
354
+ 1. **Universal Safety Rules (This file - Immutable)**: Never relax \`NO AUTO-COMMIT\`, \`NO AUTO-PUBLISH\`, or dangerous command approval gates.
355
+ 2. **Project Custom Engineering Rules ([${customFile}](${customFile}))**: Always read \`${customFile}\` in the same directory as \`AGENTS.heraspec.md\` (if present) for project-specific architecture invariants, test gates, security policies, and deployment restrictions.
356
+ 3. **IDE-Native Workspace Rules (Auto-Discovery across \`.\` and \`..\`)**: Detect and apply active IDE rule files:
357
+ - Antigravity / Gemini: \`GEMINI.md\` or \`../GEMINI.md\`, skills in \`.agents/skills/*/SKILL.md\`
358
+ - Claude Code: \`CLAUDE.md\` or \`.claude/CLAUDE.md\`, skills in \`.claude/skills/*/SKILL.md\`
359
+ - Codex / Universal Agents: \`AGENTS.md\`
360
+ - Cursor / Windsurf / Copilot: \`.cursorrules\`, \`.cursor/rules/heraspec.mdc\`, \`.windsurfrules\`, \`.github/copilot-instructions.md\`
361
+ 4. **Domain Specs & Canonical Skills**: Read \`heraspec/project.md\`, \`heraspec/config.yaml\`, \`heraspec/specs/\`, \`heraspec/changes/\`, and English \`skill.md\` files inside \`heraspec/skills/\` (strictly ignore \`*.vi.md\`, \`project.back*.md\`, and \`AGENTS.heraspec.backup-*.md\`).
362
+
363
+ ### Auto-Detected Workspace Context
364
+
365
+ - **Project**: ${projectLabel} (\`projectType\`: ${typesLabel})
366
+ - **Project Custom Layer**: [${customFile}](${customFile})${ctx?.hasCustomFile === false ? " (create if needed for project rules)" : ""}
367
+ - **Detected IDE Rule Files**:
368
+ ${ideFilesLines}
369
+ - **Detected IDE Skill Roots**:
370
+ ${skillRootsLines}
371
+ - **Installed HeraSpec Skills**:
372
+ ${skillsSummaryLines}`;
373
+ }
374
+ static getAgentsTemplate(ctx) {
375
+ const { includeWordpress, includePerfex, includeContentChannel } = this.resolveActiveDomains(ctx);
376
+ const customFile = ctx?.customFileName || "AGENTS.custom.md";
377
+ const wordpressWorkflowBlock = includeWordpress ? `
378
+ **Special case - Flatsome UX Element skill:**
379
+ - Task: \`(projectType: wordpress, skill: ux-element)\`
380
+ - Agent reads: \`heraspec/skills/wordpress/ux-element/skill.md\`
381
+ - Agent MUST follow the **Wrapping Rule**: Use \`<span>\` with \`id="{{:: shortcode.$id }}"\`
382
+ - Agent uses templates from \`heraspec/skills/wordpress/ux-element/templates/\` (Controller, Shortcode, HTML Template, SVG Thumbnail)
383
+ - Agent ensures real-time preview support in AngularJS template.
384
+ - **Variable Translation**: Variables with underscores in PHP (e.g., \`bg_color\`) MUST be accessed via camelCase in AngularJS (e.g., \`shortcode.options.bgColor\`).
385
+
386
+ **Special case - Plugin Check skill:**
387
+ - Task: \`(projectType: wordpress-plugin, skill: plugin-check)\`
388
+ - Install: \`heraspec skill add plugin-check --project-type wordpress-plugin\`
389
+ - Agent reads: \`heraspec/skills/wordpress-plugin/plugin-check/skill.md\`
390
+ - Agent runs WordPress Plugin Check (PCP) tool and fixes coding standard issues iteratively until all pass.
391
+
392
+ **Special case - Plugin Directory skill:**
393
+ - Task: \`(projectType: wordpress-plugin, skill: plugin-directory)\`
394
+ - Install: \`heraspec skill add plugin-directory --project-type wordpress-plugin\`
395
+ - Agent reads: \`heraspec/skills/wordpress-plugin/plugin-directory/skill.md\`
396
+ - Agent MUST review plugin against **18 WordPress.org Directory Guidelines** and present a full compliance report waiting for user confirmation before making changes.
397
+ ` : "";
398
+ const perfexWorkflowBlock = includePerfex ? `
399
+ **Special case - Perfex Module Engineering skills:**
400
+ - Tasks: \`(projectType: perfex-module, skill: module-codebase)\` or \`(projectType: perfex-module, skill: code-quality-guidelines)\` or \`(skill: perfex-module)\`
401
+ - Install: \`heraspec skill add perfex-module\` or \`heraspec skill add module-codebase --project-type perfex-module\`
402
+ - Agent reads: \`heraspec/skills/perfex-module/skill.md\`, \`heraspec/skills/perfex-module/module-codebase/skill.md\`, and \`heraspec/skills/perfex-module/code-quality-guidelines/skill.md\`
403
+ - Agent MUST adhere to **10 Enterprise Code Quality & Clean Code Standards** (zero inline script/style, zero scanner triggers, \`editor.dom.loadCSS()\`, IIFE scoped admin JS, \`session_write_close()\` in read AJAX endpoints, clean release packaging, \`BASEPATH\` guard + CI Query Builder, DOM XSS prevention, 100% \`_l('key')\` parity, zero Unicode emojis).
404
+ ` : "";
405
+ const contentChannelWorkflowBlock = includeContentChannel ? `
406
+ **Special case - Content & Channel Development skills (projectType: content-channel):**
407
+ - Tasks: \`(projectType: content-channel, skill: content-strategy)\`, \`(skill: content-scaffolding)\`, \`(skill: content-scripting)\`, \`(skill: content-voice-adapter)\`, \`(skill: content-prompts)\`, \`(skill: content-compliance)\`, \`(skill: content-vault-sync)\`, or \`(skill: content-channel)\`
408
+ - Install: \`heraspec skill add content-channel\` or \`heraspec skill add <skill-name> --project-type content-channel\`
409
+ - Agent reads corresponding skill instructions in \`heraspec/skills/<skill-name>/skill.md\` or \`heraspec/skills/content-channel/<skill-name>/skill.md\` and enforces MTxStudio 2-level hierarchy, strict TTS pacing rules, newline preservation for verses, Decree 15/2020/ND-CP 3-position disclaimers, and safe vault export via \`Facebook/export_vault_json.py\`.
410
+ ` : "";
411
+ const skillsSection = this.getSkillsSection(ctx);
412
+ const discoverySection = this.buildIdeDiscoverySection(ctx);
413
+ return `# HeraSpec - AI Agent Instructions
414
+
415
+ This document defines the CLI-managed workflow for AI agents working with HeraSpec.
416
+ Project-specific rules, quality gates, and overrides live in [${customFile}](${customFile}) and are never overwritten by HeraSpec CLI upgrades.
417
+
418
+ ## Universal Safety Rules
419
+
420
+ - **NO AUTO-COMMIT**: Agent MUST NOT perform \`git commit\` or \`git push\` autonomously. This task is reserved for the User unless explicitly ordered.
421
+ - **NO AUTO-PUBLISH**: Agent MUST NOT perform \`npm publish\` or trigger automated releases/deployments autonomously.
422
+ - **SKILL PREREQUISITE**: If a task maps to a skill (e.g., "Generate documentation"), you **MUST** verify the skill folder exists in \`heraspec/skills/\`. If missing:
423
+ - **Preferred**: Proactively install it via \`heraspec skill add <name>\` (e.g., \`heraspec skill add documents\`) if you have terminal access.
424
+ - **Fallback**: If you cannot install it, **STOP** and ask the user to add it. **DO NOT** attempt manual generation without the skill.
425
+ - **IGNORE VIETNAMESE SKILL FILES**: When reading and executing skill workflows, you **MUST ONLY** look at the English version of the skill instructions (e.g., \`skill.md\`). You **MUST completely ignore** all Vietnamese versions (e.g., \`skill.vi.md\` or files ending with \`*.vi.md\`). These Vietnamese files are for reference/development purposes by the user only.
426
+ - **USER CONFIRMATION**: For destructive actions or public releases, always request explicit User approval first.
427
+
428
+ ### Restricted Commands (REQUIRE USER CONFIRMATION)
429
+
430
+ The following commands are classified by risk level. You **MUST NOT** execute them without explicit user confirmation/approval in the chat, especially if they are outside the source workspace or involve deletion.
431
+
432
+ #### GROUP 1 - EXTREMELY DANGEROUS (DATA DESTRUCTION, HARD / IMPOSSIBLE TO RECOVER)
433
+ - \`rm -rf\` : Recursive delete + no prompt, can wipe entire system
434
+ - \`rm -r\` : Delete directory and all contents
435
+ - \`rm\` : Delete file directly, bypassing trash
436
+ - \`unlink\` : Delete file at filesystem level, cannot undo
437
+ - \`shred\` : Overwrite data multiple times to make it unrecoverable
438
+ - \`wipe\` : Permanently wipe data on disk
439
+ - \`dd\` : Write/copy raw blocks, easily destroy disk or partition
440
+ - \`mkfs\`, \`mkfs.ext4\`, \`mkfs.xfs\` : Create new filesystem, wiping old data
441
+ - \`format\`, \`Format-Volume\` : Format drive/volume
442
+
443
+ #### GROUP 2 - HIGH DANGER (DELETE DIRECTORY / MULTIPLE FILES)
444
+ - \`rmdir\` : Delete directory
445
+ - \`rd\`, \`rmdir /s\` : Windows delete directory
446
+ - \`Remove-Item -Recurse\`, \`Remove-Item\` : PowerShell delete
447
+ - \`del /s\`, \`erase /s\` : CMD batch delete
448
+
449
+ #### GROUP 3 - MEDIUM DANGER (DELETE FILE / OVERWRITE)
450
+ - \`del\`, \`erase\` : Delete file
451
+ - \`Clear-Content\` : Clear file content
452
+ - \`cp --remove-destination\` : Overwrite destination by deleting first
453
+
454
+ #### GROUP 4 - INDIRECT DANGER (DATA LOSS)
455
+ - \`mv\` : Move / overwrite file, old data lost
456
+ - \`rsync --delete\` : Delete file at destination if not in source
457
+ - \`install\` : Overwrite system files
458
+
459
+ #### GROUP 5 - DISK / PARTITION MANAGEMENT
460
+ - \`fdisk\`, \`cfdisk\`, \`parted\`, \`diskpart\` : Partition management
461
+ - \`mount\`, \`umount\` : Filesystem mounting
462
+
463
+ #### GROUP 6 - LESS DANGEROUS (POTENTIAL CONSEQUENCES)
464
+ - \`truncate\` : Cut off file content
465
+ - \`chown\`, \`chmod\` : Change ownership/permissions
466
+ - \`attrib\` : Change attributes
467
+
468
+ ${discoverySection}
469
+
470
+ ## Core Workflow
471
+
472
+ ### Step 1 - Create a Change
473
+
474
+ **When creating changes, ALWAYS read \`heraspec/project.md\` and \`${customFile}\` first to understand:**
475
+ - Project types being used
476
+ - Tech stack, conventions, and project-specific invariants
477
+ - Existing architecture patterns
478
+ - Coding and quality standards
479
+
480
+ > **IGNORE backup files**: Files like \`project.back1.md\`, \`project.back2.md\`, \`AGENTS.heraspec.backup-*.md\`, etc. are automatic backups created during \`heraspec init\` updates. NEVER read or reference them unless explicitly asked by the user. Only \`project.md\`, \`AGENTS.heraspec.md\`, and \`${customFile}\` are active sources of truth.
481
+
482
+ **Then scaffold:**
483
+ - \`heraspec/changes/<slug>/\` - Create \`proposal.md\`, \`tasks.md\`, \`design.md\` (optional)
484
+ - \`heraspec/specs/<slug>/\` - Create delta specs here (NOT inside changes folder)
485
+
486
+ **If user asks to create changes based on project.md:**
487
+ 1. Read \`heraspec/project.md\` thoroughly
488
+ 2. Identify all features/capabilities mentioned
489
+ 3. Create separate changes for each major feature
490
+ 4. Ensure each change follows \`project.md\` and \`${customFile}\` conventions
491
+ 5. Use correct project types and skills from \`project.md\` / \`config.yaml\`
492
+
493
+ ### Step 2 - Refine Specs
494
+ - Update delta specs in \`heraspec/specs/<slug>/\`
495
+ - Never modify source-of-truth specs directly before approval and archive
496
+ - Validate changes cleanly with \`heraspec validate <slug> --strict\`
497
+
498
+ ### Step 3 - Approval
499
+ - Wait for user confirmation (for example: "Specs approved.") before starting implementation of major changes
500
+
501
+ ### Step 4 - Implementation
502
+
503
+ **CRITICAL: When implementing tasks, ALWAYS use the Skills system and project custom rules:**
504
+
505
+ 1. **Read task line** to identify skill:
506
+ \`\`\`markdown
507
+ ## 1. Module - Feature (projectType: backend-api, skill: ui-ux)
508
+ - [ ] 1.1 Implement feature
509
+ \`\`\`
510
+
511
+ 2. **Find skill folder**:
512
+ - Project-specific: \`heraspec/skills/<project-type>/<skill-name>/\`
513
+ - Cross-cutting: \`heraspec/skills/<skill-name>/\`
514
+
515
+ 3. **Read \`skill.md\`**:
516
+ - Understand purpose, steps, inputs, outputs
517
+ - Follow tone, rules, and limitations
518
+ - Check available templates and scripts
519
+ - **Ignore Vietnamese Skill Files**: Only read the English \`skill.md\` instructions. Completely ignore any \`*.vi.md\` translation files.
520
+
521
+ 4. **Use skill resources**:
522
+ - Run scripts from \`scripts/\` folder if needed
523
+ - Use templates from \`templates/\` folder
524
+ - Reference examples from \`examples/\` folder
525
+
526
+ 5. **Implement following \`skill.md\` and \`${customFile}\` guidance**:
527
+ - Follow step-by-step process and naming conventions
528
+ - Verify all quality/sync gates defined in \`${customFile}\` and active IDE rules
529
+ ${wordpressWorkflowBlock}${perfexWorkflowBlock}${contentChannelWorkflowBlock}
530
+ - Follow \`tasks.md\`
531
+ - Mark tasks completed: \`- [x]\`
532
+
533
+ ### Step 5 - Archive
534
+ - Run: \`heraspec archive <slug> --yes\`
535
+ - This merges delta specs into source specs
536
+ - Moves change folder to archives
537
+
538
+ #### Handling Parallel Merge Conflicts
539
+ If \`heraspec archive\` throws a **Parallel Merge Conflict** error:
540
+ 1. It means someone else modified the base requirement in the source spec while you were working.
541
+ 2. **DO NOT PANIC** and **DO NOT OVERWRITE** manually.
542
+ 3. Run: \`heraspec sync <slug>\`
543
+ 4. The system will automatically update your fingerprint to match the new source spec and warn you.
544
+ 5. Review your delta spec again. Make sure your \`MODIFIED/REMOVED\` requirements still make sense given the new source.
545
+ 6. Once verified, run \`heraspec archive <slug> --yes\` again.
546
+
547
+ ## Spec Format
548
+
549
+ Specs must include:
550
+ - \`## Meta\` section with project type, domain, stack
551
+ - \`## Purpose\`
552
+ - \`## Requirements\` with scenarios
553
+
554
+ ## Delta Spec Format
555
+
556
+ Delta specs use:
557
+ - \`## ADDED Requirements\`
558
+ - \`## MODIFIED Requirements\`
559
+ - \`## REMOVED Requirements\`
560
+
561
+ ## Tasks Format
562
+
563
+ Tasks grouped by project type and skill:
564
+ \`\`\`
565
+ ## 1. Feature Group - Capability (projectType: <type>, skill: <skill-name>)
566
+ - [ ] Task description
567
+ \`\`\`
568
+
569
+ ${skillsSection}
570
+
571
+ ## Proactive Memory-Aware Development
572
+
573
+ If \`heraspec/skills/project-memory/\` exists, the agent MUST proactively use memory to maintain project context. DO NOT wait for the user to prompt you to use memory.
574
+
575
+ ### CRITICAL RULES FOR AUTOMATIC MEMORY USAGE
576
+ 1. **Always Check Context First**: At the beginning of a complex task or when encountering an unfamiliar codebase area, you MUST autonomously run \`heraspec memory context\` or \`heraspec memory search "keywords"\` BEFORE writing any code.
577
+ 2. **Auto-Log via Archive**: You DO NOT need to run \`heraspec memory log\` manually. Every time you successfully implement a feature and run \`heraspec archive <change-name>\`, the system will automatically read your proposal and log the memory observation under the hood. Just use \`heraspec archive\` as normal!
578
+ 3. **Session Summary**: (Optional) When wrapping up a large session, you can run \`heraspec memory summarize --request "..." --completed "..."\` to compress knowledge, though \`archive\` already auto-logs completed features.
579
+
580
+ ### When to SKIP Memory
581
+ - Simple bug fixes, typo corrections, formatting changes
582
+ - Trivial tasks that take < 5 minutes
583
+ - When doing what the agent's built-in context already covers
584
+
585
+ ### Smart Code Exploration
586
+ If \`heraspec/skills/smart-explore/\` exists, prefer token-efficient exploration:
587
+ - \`heraspec explore outline <file>\` -> View structure (~1K tokens vs ~12K full file)
588
+ - \`heraspec explore search "<query>" <path>\` -> Find symbols across codebase
589
+ - \`heraspec explore unfold <file> <symbol>\` -> Read just one function
590
+ `;
591
+ }
592
+ static getSkillsSection(ctx) {
593
+ const { includeWordpress, includePerfex, includeContentChannel } = this.resolveActiveDomains(ctx);
594
+ const hasUiUx = (ctx?.installedSkills || []).some((s) => s.name === "ui-ux") || ctx?.includeAllStacks;
595
+ const hasDocuments = (ctx?.installedSkills || []).some((s) => s.name === "documents") || ctx?.includeAllStacks;
596
+ const primaryType = ctx?.projectTypes && ctx.projectTypes[0] || "backend-api";
597
+ const customSkillsBlock = (ctx?.installedSkills || []).map((s) => {
598
+ const key = s.projectType ? `${s.projectType}/${s.name}` : s.name;
599
+ return `- **${key}**: Read \`${s.relativePath}\`${s.description ? ` - ${s.description}` : ""}`;
600
+ }).join("\n");
601
+ const uiUxSnippet = hasUiUx ? `
602
+ **Special case - UI/UX skill:**
603
+ - Task: \`(skill: ui-ux)\`
604
+ - Agent reads: \`heraspec/skills/ui-ux/skill.md\`
605
+ - Agent MUST use search scripts before implementing:
606
+ \`\`\`bash
607
+ python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --domain <domain>
608
+ python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --stack <stack>
609
+ \`\`\`
610
+ ` : "";
611
+ const docsSnippet = hasDocuments ? `
612
+ **Example prompt for Documents skill:**
613
+ > "Generate documentation with skill documents for [project-name]. Include:
614
+ > - Concise overview (documentations/documentation.txt)
615
+ > - Technical Markdown (documentations/documentation.md)
616
+ > - Interactive HTML (documentations/documentation.html)
617
+ > - Premium Documentation Landing Page (documentations/documentation-landing-page.html)
618
+ > - CRITICAL: Save all files in the /documentations directory (create it if missing)."
619
+ ` : "";
620
+ const wpSnippet = includeWordpress ? `
621
+ **WordPress Skills:**
622
+ - Flatsome UX Element: \`heraspec/skills/wordpress/ux-element/skill.md\`
623
+ - WordPress Plugin Check / Directory: \`heraspec/skills/wordpress-plugin/plugin-check/skill.md\`, \`heraspec/skills/wordpress-plugin/plugin-directory/skill.md\`
624
+ ` : "";
625
+ const perfexSnippet = includePerfex ? `
626
+ **Perfex Module Engineering Skills:**
627
+ - Tasks: \`(projectType: perfex-module, skill: module-codebase)\` or \`(projectType: perfex-module, skill: code-quality-guidelines)\`
628
+ - Agent reads: \`heraspec/skills/perfex-module/skill.md\`, \`module-codebase/skill.md\`, and \`code-quality-guidelines/skill.md\`
629
+ ` : "";
630
+ const contentSnippet = includeContentChannel ? `
631
+ **Content & Channel Development Skills (content-channel):**
632
+ - Available skills: \`content-strategy\`, \`content-scaffolding\`, \`content-scripting\`, \`content-voice-adapter\`, \`content-prompts\`, \`content-compliance\`, \`content-vault-sync\`
633
+ - Agent reads \`heraspec/skills/content-channel/<skill-name>/skill.md\` (or \`heraspec/skills/<skill-name>/skill.md\`) and enforces strict TTS acoustics, verse newline preservation, legal disclaimers, and safe vault export.
634
+ ` : "";
635
+ const activeListBlock = customSkillsBlock ? `
636
+ ### Active Project Skills
637
+
638
+ ${customSkillsBlock}
639
+ ` : "";
640
+ return `## Skills System
641
+
642
+ **CRITICAL: Mandatory Prerequisite Check**
643
+
644
+ 1. **Stop & Verify**: If you are asked to implement a task requiring a skill (e.g., "Generate documentation...", "Create UI/UX...", etc.), you MUST first check if the skill folder exists in \`heraspec/skills/\`.
645
+ 2. **Missing Skill = AUTO-INSTALL OR STOP**: If the skill folder does NOT exist:
646
+ - **Option A (Preferred)**: If you can run commands, execute \`heraspec skill add <skill-name>\` immediately.
647
+ - **Option B (Fallback)**: If you cannot run commands, **STOP** and ask the user to run it.
648
+ - **DO NOT** create a task plan or attempt manual generation without the skill language.
649
+ 3. **Execute After Install**: Only after the skill folder is created (or installed), read the \`skill.md\` and proceed with the task.
650
+ 4. **Ignore Vietnamese Skill Files**: You MUST only read the English \`skill.md\` file inside the skill folder. Completely ignore all \`*.vi.md\` files (e.g., \`skill.vi.md\`), as they are strictly for reference purposes by human developers.
651
+ ${activeListBlock}${uiUxSnippet}${docsSnippet}${wpSnippet}${perfexSnippet}${contentSnippet}
652
+ ### Skill Discovery & Usage
653
+
654
+ - List all skills: Check \`heraspec/skills/\` directory or run \`heraspec skill list\`
655
+ - Project-specific skills: \`heraspec/skills/<project-type>/\`
656
+ - Cross-cutting skills: \`heraspec/skills/<skill-name>/\` (root level)
657
+ - IDE skill parity check: Run \`heraspec ide sync --check\` when mirroring skills to \`.agents/skills/\` or \`.claude/skills/\`
658
+ - **Consistency**: Follow the step-by-step process in the skill's \`skill.md\`.
659
+
660
+ ### When Change Has Multiple Skills
661
+
662
+ **Important**: Each task group uses ONE skill. When working on a task group, agent MUST use that skill's \`skill.md\`.
663
+
664
+ Example with multiple skills in one change:
665
+ \`\`\`markdown
666
+ ## 1. Domain Logic - Feature (projectType: ${primaryType}, skill: project-memory)
667
+ - [ ] Task 1.1 Design and implement core module
668
+
669
+ ## 2. UI/UX - Interface (skill: ui-ux)
670
+ - [ ] Task 2.1 Apply layout and accessibility checks
671
+ \`\`\`
672
+
673
+ **Key rule**: Switch \`skill.md\` when switching task groups!
674
+ `;
675
+ }
676
+ static getConfigTemplate() {
677
+ return `projectType: generic-webapp
678
+ projectName: "HeraSpec Project"
679
+ description: "A new project using HeraSpec"
680
+ skills: []
681
+ `;
682
+ }
683
+ };
684
+ }
685
+ });
686
+
269
687
  // src/core/templates/skills-template-map.ts
270
688
  function getSkillTemplateInfo(skillName, projectType) {
271
689
  if (projectType) {
@@ -2975,11 +3393,1069 @@ var init_skill_manager = __esm({
2975
3393
  }
2976
3394
  });
2977
3395
 
2978
- // src/core/skills/index.ts
2979
- var init_skills = __esm({
2980
- "src/core/skills/index.ts"() {
2981
- "use strict";
2982
- init_skill_parser();
3396
+ // src/core/ide-adapter.ts
3397
+ import path7 from "path";
3398
+ import { createHash } from "crypto";
3399
+ function normalizeLineEndings(content) {
3400
+ return content.replace(/\r\n/g, "\n");
3401
+ }
3402
+ function computeNormalizedSha256(content) {
3403
+ return createHash("sha256").update(normalizeLineEndings(content), "utf8").digest("hex");
3404
+ }
3405
+ function toPosixRelative(fromDir, targetPath) {
3406
+ const rel = path7.relative(fromDir, targetPath).replace(/\\/g, "/");
3407
+ return rel || ".";
3408
+ }
3409
+ function parseSkillFrontmatter(content) {
3410
+ const normalized = normalizeLineEndings(content);
3411
+ const fmMatch = normalized.match(/^---\n([\s\S]*?)\n---/);
3412
+ if (fmMatch) {
3413
+ const yamlBlock = fmMatch[1];
3414
+ const nameMatch = yamlBlock.match(/^name:\s*(.+)$/m);
3415
+ const descMatch = yamlBlock.match(/^description:\s*(.+)$/m);
3416
+ const stripQuotes = (s) => s ? s.trim().replace(/^["']|["']$/g, "") : void 0;
3417
+ return {
3418
+ name: stripQuotes(nameMatch?.[1]),
3419
+ description: stripQuotes(descMatch?.[1])
3420
+ };
3421
+ }
3422
+ const lines = normalized.split("\n");
3423
+ for (const rawLine of lines) {
3424
+ const line = rawLine.trim();
3425
+ if (!line || line.startsWith("#") || line.startsWith(">")) continue;
3426
+ return { description: line.length > 160 ? `${line.slice(0, 157)}...` : line };
3427
+ }
3428
+ return {};
3429
+ }
3430
+ var HERASPEC_ADAPTER_START, HERASPEC_ADAPTER_END, IDE_PROFILES, IdeAdapterManager;
3431
+ var init_ide_adapter = __esm({
3432
+ "src/core/ide-adapter.ts"() {
3433
+ "use strict";
3434
+ init_file_system();
3435
+ init_config();
3436
+ init_skill_manager();
3437
+ HERASPEC_ADAPTER_START = "<!-- HERASPEC:ADAPTER_START -->";
3438
+ HERASPEC_ADAPTER_END = "<!-- HERASPEC:ADAPTER_END -->";
3439
+ IDE_PROFILES = [
3440
+ {
3441
+ name: "gemini",
3442
+ label: "Antigravity / Gemini",
3443
+ primaryRuleFile: "GEMINI.md",
3444
+ ruleCandidates: ["GEMINI.md"],
3445
+ skillRootDir: ".agents/skills"
3446
+ },
3447
+ {
3448
+ name: "claude",
3449
+ label: "Claude Code",
3450
+ primaryRuleFile: "CLAUDE.md",
3451
+ ruleCandidates: ["CLAUDE.md", ".claude/CLAUDE.md"],
3452
+ skillRootDir: ".claude/skills"
3453
+ },
3454
+ {
3455
+ name: "codex",
3456
+ label: "OpenAI Codex / Universal Agents",
3457
+ primaryRuleFile: "AGENTS.md",
3458
+ ruleCandidates: ["AGENTS.md"]
3459
+ },
3460
+ {
3461
+ name: "cursor",
3462
+ label: "Cursor",
3463
+ primaryRuleFile: ".cursorrules",
3464
+ ruleCandidates: [".cursorrules", ".cursor/rules/heraspec.mdc"]
3465
+ },
3466
+ {
3467
+ name: "windsurf",
3468
+ label: "Windsurf",
3469
+ primaryRuleFile: ".windsurfrules",
3470
+ ruleCandidates: [".windsurfrules"]
3471
+ },
3472
+ {
3473
+ name: "copilot",
3474
+ label: "GitHub Copilot",
3475
+ primaryRuleFile: ".github/copilot-instructions.md",
3476
+ ruleCandidates: [".github/copilot-instructions.md"]
3477
+ }
3478
+ ];
3479
+ IdeAdapterManager = class {
3480
+ static async discoverWorkspace(projectPath, ideOption = "auto") {
3481
+ const resolvedProject = path7.resolve(projectPath);
3482
+ const parentCandidate = path7.dirname(resolvedProject);
3483
+ const hasDistinctParent = parentCandidate && parentCandidate !== resolvedProject && parentCandidate !== path7.parse(resolvedProject).root;
3484
+ const searchScopes = [
3485
+ { scope: "project", dir: resolvedProject }
3486
+ ];
3487
+ if (hasDistinctParent) {
3488
+ searchScopes.push({ scope: "parent", dir: parentCandidate });
3489
+ }
3490
+ const detectedFiles = [];
3491
+ const detectedSkillRoots = [];
3492
+ const existingTargets = [];
3493
+ const existingSkillRoots = [];
3494
+ const seenPaths = /* @__PURE__ */ new Set();
3495
+ for (const profile of IDE_PROFILES) {
3496
+ for (const { scope, dir } of searchScopes) {
3497
+ for (const candidate of profile.ruleCandidates) {
3498
+ const absPath = path7.join(dir, candidate);
3499
+ if (seenPaths.has(absPath)) continue;
3500
+ if (await FileSystemUtils.fileExists(absPath)) {
3501
+ seenPaths.add(absPath);
3502
+ const rel = toPosixRelative(resolvedProject, absPath);
3503
+ detectedFiles.push({
3504
+ profile: profile.name,
3505
+ label: profile.label,
3506
+ relativePath: rel,
3507
+ scope
3508
+ });
3509
+ existingTargets.push({
3510
+ profile: profile.name,
3511
+ label: profile.label,
3512
+ absolutePath: absPath,
3513
+ relativeFromProject: rel,
3514
+ scope,
3515
+ exists: true
3516
+ });
3517
+ }
3518
+ }
3519
+ if (profile.skillRootDir) {
3520
+ const skillRootAbs = path7.join(dir, profile.skillRootDir);
3521
+ if (!seenPaths.has(skillRootAbs) && await FileSystemUtils.fileExists(skillRootAbs)) {
3522
+ seenPaths.add(skillRootAbs);
3523
+ const relRoot = toPosixRelative(resolvedProject, skillRootAbs);
3524
+ detectedSkillRoots.push({
3525
+ profile: profile.name,
3526
+ relativePath: relRoot,
3527
+ scope
3528
+ });
3529
+ existingSkillRoots.push({
3530
+ profile: profile.name,
3531
+ absolutePath: skillRootAbs,
3532
+ relativeFromProject: relRoot,
3533
+ scope,
3534
+ exists: true
3535
+ });
3536
+ }
3537
+ }
3538
+ }
3539
+ }
3540
+ const targetRuleFiles = [];
3541
+ const targetSkillRoots = [];
3542
+ if (ideOption === "none") {
3543
+ return {
3544
+ projectPath: resolvedProject,
3545
+ parentPath: hasDistinctParent ? parentCandidate : null,
3546
+ ideOption,
3547
+ detectedFiles,
3548
+ detectedSkillRoots,
3549
+ targetRuleFiles,
3550
+ targetSkillRoots
3551
+ };
3552
+ }
3553
+ const selectedProfiles = ideOption === "all" ? IDE_PROFILES.map((p) => p.name) : ideOption === "auto" ? [] : [ideOption];
3554
+ if (ideOption === "auto") {
3555
+ targetRuleFiles.push(...existingTargets);
3556
+ targetSkillRoots.push(...existingSkillRoots);
3557
+ for (const profile of IDE_PROFILES) {
3558
+ if (!profile.skillRootDir) continue;
3559
+ const alreadyHasRoot = targetSkillRoots.some((r) => r.profile === profile.name);
3560
+ const hasProjectRule = existingTargets.some(
3561
+ (t) => t.profile === profile.name && t.scope === "project"
3562
+ );
3563
+ if (!alreadyHasRoot && hasProjectRule) {
3564
+ const absRoot = path7.join(resolvedProject, profile.skillRootDir);
3565
+ targetSkillRoots.push({
3566
+ profile: profile.name,
3567
+ absolutePath: absRoot,
3568
+ relativeFromProject: toPosixRelative(resolvedProject, absRoot),
3569
+ scope: "project",
3570
+ exists: false
3571
+ });
3572
+ }
3573
+ }
3574
+ } else {
3575
+ const addedRulePaths = /* @__PURE__ */ new Set();
3576
+ const addedSkillRoots = /* @__PURE__ */ new Set();
3577
+ for (const profileName of selectedProfiles) {
3578
+ const profile = IDE_PROFILES.find((p) => p.name === profileName);
3579
+ if (!profile) continue;
3580
+ const matchingExisting = existingTargets.filter((t) => t.profile === profileName);
3581
+ if (matchingExisting.length > 0) {
3582
+ for (const target of matchingExisting) {
3583
+ if (!addedRulePaths.has(target.absolutePath)) {
3584
+ addedRulePaths.add(target.absolutePath);
3585
+ targetRuleFiles.push(target);
3586
+ }
3587
+ }
3588
+ } else {
3589
+ const absNew = path7.join(resolvedProject, profile.primaryRuleFile);
3590
+ addedRulePaths.add(absNew);
3591
+ targetRuleFiles.push({
3592
+ profile: profile.name,
3593
+ label: profile.label,
3594
+ absolutePath: absNew,
3595
+ relativeFromProject: toPosixRelative(resolvedProject, absNew),
3596
+ scope: "project",
3597
+ exists: false
3598
+ });
3599
+ }
3600
+ if (profile.skillRootDir) {
3601
+ const matchingRoots = existingSkillRoots.filter((r) => r.profile === profileName);
3602
+ if (matchingRoots.length > 0) {
3603
+ for (const root of matchingRoots) {
3604
+ if (!addedSkillRoots.has(root.absolutePath)) {
3605
+ addedSkillRoots.add(root.absolutePath);
3606
+ targetSkillRoots.push(root);
3607
+ }
3608
+ }
3609
+ } else {
3610
+ const absRoot = path7.join(resolvedProject, profile.skillRootDir);
3611
+ addedSkillRoots.add(absRoot);
3612
+ targetSkillRoots.push({
3613
+ profile: profile.name,
3614
+ absolutePath: absRoot,
3615
+ relativeFromProject: toPosixRelative(resolvedProject, absRoot),
3616
+ scope: "project",
3617
+ exists: false
3618
+ });
3619
+ }
3620
+ }
3621
+ }
3622
+ }
3623
+ return {
3624
+ projectPath: resolvedProject,
3625
+ parentPath: hasDistinctParent ? parentCandidate : null,
3626
+ ideOption,
3627
+ detectedFiles,
3628
+ detectedSkillRoots,
3629
+ targetRuleFiles,
3630
+ targetSkillRoots
3631
+ };
3632
+ }
3633
+ static buildAdapterBlock(targetFilePath, projectPath, hasCustomFile) {
3634
+ const targetDir = path7.dirname(path7.resolve(targetFilePath));
3635
+ const resolvedProject = path7.resolve(projectPath);
3636
+ const relAgents = toPosixRelative(targetDir, path7.join(resolvedProject, HERASPEC_MARKERS.AGENTS_MD));
3637
+ const relCustom = toPosixRelative(
3638
+ targetDir,
3639
+ path7.join(resolvedProject, HERASPEC_MARKERS.AGENTS_CUSTOM_MD)
3640
+ );
3641
+ const relProjectMd = toPosixRelative(
3642
+ targetDir,
3643
+ path7.join(resolvedProject, HERASPEC_DIR_NAME, HERASPEC_MARKERS.PROJECT_MD)
3644
+ );
3645
+ const relSkillsDir = toPosixRelative(
3646
+ targetDir,
3647
+ path7.join(resolvedProject, HERASPEC_DIR_NAME, SKILLS_DIR_NAME)
3648
+ );
3649
+ const customPointer = hasCustomFile ? ` and [${relCustom}](${relCustom}) (project-specific rules and quality gates)` : ` (create \`${relCustom}\` for project-specific rules)`;
3650
+ return `${HERASPEC_ADAPTER_START}
3651
+ ## HeraSpec Workflow Integration
3652
+
3653
+ > **Managed by HeraSpec CLI** - Do not duplicate CLI workflow rules here.
3654
+ > Follow [${relAgents}](${relAgents}) (CLI workflow, safety rules, specs lifecycle)${customPointer}, alongside [${relProjectMd}](${relProjectMd}) and English \`${relSkillsDir}/*/skill.md\` (ignore \`*.vi.md\`).
3655
+ ${HERASPEC_ADAPTER_END}`;
3656
+ }
3657
+ static upsertAdapterBlock(existingContent, adapterBlock) {
3658
+ if (!existingContent || existingContent.trim().length === 0) {
3659
+ return `${adapterBlock}
3660
+ `;
3661
+ }
3662
+ const normalized = normalizeLineEndings(existingContent);
3663
+ const startIdx = normalized.indexOf(HERASPEC_ADAPTER_START);
3664
+ const endIdx = normalized.indexOf(HERASPEC_ADAPTER_END);
3665
+ if (startIdx !== -1 && endIdx !== -1 && endIdx >= startIdx) {
3666
+ const before = normalized.slice(0, startIdx).trimEnd();
3667
+ const after = normalized.slice(endIdx + HERASPEC_ADAPTER_END.length).trimStart();
3668
+ const parts = [];
3669
+ if (before) parts.push(before);
3670
+ parts.push(adapterBlock);
3671
+ if (after) parts.push(after);
3672
+ return parts.join("\n\n") + "\n";
3673
+ }
3674
+ return `${normalized.trimEnd()}
3675
+
3676
+ ${adapterBlock}
3677
+ `;
3678
+ }
3679
+ static async collectCanonicalSkills(projectPath) {
3680
+ const resolvedProject = path7.resolve(projectPath);
3681
+ const skills = await SkillManager.listSkills(resolvedProject);
3682
+ const summaries = [];
3683
+ const byName = /* @__PURE__ */ new Map();
3684
+ for (const skill of skills) {
3685
+ const lowerSkillMd = path7.join(skill.path, "skill.md");
3686
+ const upperSkillMd = path7.join(skill.path, "SKILL.md");
3687
+ const sourceSkillFile = await FileSystemUtils.fileExists(lowerSkillMd) ? lowerSkillMd : await FileSystemUtils.fileExists(upperSkillMd) ? upperSkillMd : null;
3688
+ if (!sourceSkillFile) continue;
3689
+ const rawContent = await FileSystemUtils.readFile(sourceSkillFile);
3690
+ const { description } = parseSkillFrontmatter(rawContent);
3691
+ const relativeSkillFile = toPosixRelative(resolvedProject, sourceSkillFile);
3692
+ summaries.push({
3693
+ name: skill.skillName,
3694
+ projectType: skill.projectType,
3695
+ relativePath: relativeSkillFile,
3696
+ description
3697
+ });
3698
+ const existing = byName.get(skill.skillName);
3699
+ if (!existing || !skill.projectType && existing.projectType) {
3700
+ byName.set(skill.skillName, {
3701
+ name: skill.skillName,
3702
+ projectType: skill.projectType,
3703
+ sourceDir: skill.path,
3704
+ sourceSkillFile,
3705
+ relativeSkillFile,
3706
+ description,
3707
+ content: rawContent,
3708
+ sha256: computeNormalizedSha256(rawContent)
3709
+ });
3710
+ }
3711
+ }
3712
+ summaries.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
3713
+ const canonical = Array.from(byName.values()).sort((a, b) => a.name.localeCompare(b.name));
3714
+ return { canonical, summaries };
3715
+ }
3716
+ static async syncAdaptersAndSkills(options) {
3717
+ const {
3718
+ projectPath,
3719
+ ideOption = "auto",
3720
+ hasCustomFile,
3721
+ checkOnly = false,
3722
+ dryRun = false,
3723
+ force = false,
3724
+ preserveModifiedSkillTargets = false,
3725
+ recordedMirrors = {},
3726
+ skipAdapters = false,
3727
+ skillNames
3728
+ } = options;
3729
+ const discovery = await this.discoverWorkspace(projectPath, ideOption);
3730
+ const reports = [];
3731
+ const updatedMirrors = { ...recordedMirrors };
3732
+ let hasDrift = false;
3733
+ const shouldWrite = !checkOnly && !dryRun;
3734
+ if (!skipAdapters) {
3735
+ for (const target of discovery.targetRuleFiles) {
3736
+ const exists = await FileSystemUtils.fileExists(target.absolutePath);
3737
+ const existing = exists ? await FileSystemUtils.readFile(target.absolutePath) : null;
3738
+ const adapterBlock = this.buildAdapterBlock(
3739
+ target.absolutePath,
3740
+ discovery.projectPath,
3741
+ hasCustomFile
3742
+ );
3743
+ const nextContent = this.upsertAdapterBlock(existing, adapterBlock);
3744
+ if (existing !== null && normalizeLineEndings(existing) === normalizeLineEndings(nextContent)) {
3745
+ reports.push({
3746
+ kind: "adapter",
3747
+ targetPath: target.absolutePath,
3748
+ relativePath: target.relativeFromProject,
3749
+ status: "in-sync"
3750
+ });
3751
+ continue;
3752
+ }
3753
+ if (checkOnly) {
3754
+ hasDrift = true;
3755
+ reports.push({
3756
+ kind: "adapter",
3757
+ targetPath: target.absolutePath,
3758
+ relativePath: target.relativeFromProject,
3759
+ status: exists ? "drifted" : "missing",
3760
+ detail: exists ? "HeraSpec adapter block missing or out of date" : "IDE rule file missing"
3761
+ });
3762
+ continue;
3763
+ }
3764
+ if (shouldWrite) {
3765
+ await FileSystemUtils.createDirectory(path7.dirname(target.absolutePath));
3766
+ await FileSystemUtils.writeFile(target.absolutePath, nextContent);
3767
+ }
3768
+ reports.push({
3769
+ kind: "adapter",
3770
+ targetPath: target.absolutePath,
3771
+ relativePath: target.relativeFromProject,
3772
+ status: exists ? "updated" : "created"
3773
+ });
3774
+ }
3775
+ }
3776
+ if (discovery.targetSkillRoots.length > 0) {
3777
+ const { canonical } = await this.collectCanonicalSkills(discovery.projectPath);
3778
+ const allowedSkillSet = skillNames ? new Set(skillNames) : null;
3779
+ const skillsToMirror = allowedSkillSet ? canonical.filter((s) => allowedSkillSet.has(s.name)) : canonical;
3780
+ for (const root of discovery.targetSkillRoots) {
3781
+ for (const skill of skillsToMirror) {
3782
+ const destSkillDir = path7.join(root.absolutePath, skill.name);
3783
+ const destSkillMd = path7.join(destSkillDir, "SKILL.md");
3784
+ const mirrorKey = toPosixRelative(discovery.projectPath, destSkillMd);
3785
+ const destExists = await FileSystemUtils.fileExists(destSkillMd);
3786
+ const destContent = destExists ? await FileSystemUtils.readFile(destSkillMd) : null;
3787
+ const destHash = destContent !== null ? computeNormalizedSha256(destContent) : null;
3788
+ if (destHash === skill.sha256) {
3789
+ updatedMirrors[mirrorKey] = skill.sha256;
3790
+ reports.push({
3791
+ kind: "skill",
3792
+ targetPath: destSkillMd,
3793
+ relativePath: mirrorKey,
3794
+ status: "in-sync",
3795
+ sha256: skill.sha256
3796
+ });
3797
+ continue;
3798
+ }
3799
+ if (checkOnly) {
3800
+ hasDrift = true;
3801
+ reports.push({
3802
+ kind: "skill",
3803
+ targetPath: destSkillMd,
3804
+ relativePath: mirrorKey,
3805
+ status: destExists ? "drifted" : "missing",
3806
+ detail: destExists ? `SHA-256 differs from ${skill.relativeSkillFile}` : `Missing mirror of ${skill.relativeSkillFile}`,
3807
+ sha256: destHash || void 0
3808
+ });
3809
+ continue;
3810
+ }
3811
+ const recordedBaseline = recordedMirrors[mirrorKey];
3812
+ if (preserveModifiedSkillTargets && !force && destExists && destHash !== null && destHash !== recordedBaseline) {
3813
+ hasDrift = true;
3814
+ reports.push({
3815
+ kind: "skill",
3816
+ targetPath: destSkillMd,
3817
+ relativePath: mirrorKey,
3818
+ status: "preserved",
3819
+ detail: `IDE skill modified locally; preserved (run "heraspec ide sync" to overwrite from ${skill.relativeSkillFile})`,
3820
+ sha256: destHash
3821
+ });
3822
+ continue;
3823
+ }
3824
+ if (shouldWrite) {
3825
+ await FileSystemUtils.createDirectory(destSkillDir);
3826
+ await FileSystemUtils.writeFile(destSkillMd, normalizeLineEndings(skill.content));
3827
+ await this.copySkillResourceSubdirs(skill.sourceDir, destSkillDir);
3828
+ }
3829
+ updatedMirrors[mirrorKey] = skill.sha256;
3830
+ reports.push({
3831
+ kind: "skill",
3832
+ targetPath: destSkillMd,
3833
+ relativePath: mirrorKey,
3834
+ status: destExists ? "updated" : "created",
3835
+ sha256: skill.sha256
3836
+ });
3837
+ }
3838
+ }
3839
+ }
3840
+ return {
3841
+ discovery,
3842
+ reports,
3843
+ updatedMirrors,
3844
+ hasDrift
3845
+ };
3846
+ }
3847
+ static async copySkillResourceSubdirs(sourceSkillDir, destSkillDir) {
3848
+ const resourceFolders = ["scripts", "templates", "examples", "references", "resources"];
3849
+ for (const folder of resourceFolders) {
3850
+ const srcSub = path7.join(sourceSkillDir, folder);
3851
+ if (!await FileSystemUtils.fileExists(srcSub)) continue;
3852
+ const entries = await FileSystemUtils.readDirectory(srcSub);
3853
+ const validEntries = entries.filter((name) => !name.endsWith(".vi.md"));
3854
+ if (validEntries.length === 0) continue;
3855
+ const destSub = path7.join(destSkillDir, folder);
3856
+ await FileSystemUtils.createDirectory(destSub);
3857
+ for (const entry of validEntries) {
3858
+ const srcEntry = path7.join(srcSub, entry);
3859
+ const destEntry = path7.join(destSub, entry);
3860
+ const stat = await FileSystemUtils.stat(srcEntry);
3861
+ if (stat.isDirectory()) {
3862
+ await FileSystemUtils.copyDirectory(srcEntry, destEntry);
3863
+ } else {
3864
+ await FileSystemUtils.copyFile(srcEntry, destEntry);
3865
+ }
3866
+ }
3867
+ }
3868
+ }
3869
+ };
3870
+ }
3871
+ });
3872
+
3873
+ // src/core/agents-composer.ts
3874
+ import path8 from "path";
3875
+ function normalizeHeadingKey(heading) {
3876
+ return heading.replace(/^#{1,6}\s+/, "").replace(/^\d+\.\s*/, "").replace(/[\u2014\u2013]/g, "-").replace(/[`*_]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
3877
+ }
3878
+ function normalizeComparisonLine(line) {
3879
+ return line.replace(/[\u2014\u2013]/g, "-").replace(/\u2192/g, "->").replace(/[`*_]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
3880
+ }
3881
+ function buildBaselineLineSet() {
3882
+ const set = /* @__PURE__ */ new Set();
3883
+ const seedTexts = [
3884
+ TemplateManager.getAgentsTemplate({ includeAllStacks: true }),
3885
+ TemplateManager.getSkillsSection({ includeAllStacks: true }),
3886
+ ...LEGACY_V01_EXTRA_BOILERPLATE
3887
+ ];
3888
+ for (const text of seedTexts) {
3889
+ for (const raw of normalizeLineEndings(text).split("\n")) {
3890
+ const norm = normalizeComparisonLine(raw);
3891
+ if (norm) set.add(norm);
3892
+ }
3893
+ }
3894
+ return set;
3895
+ }
3896
+ function splitTopLevelSections(content) {
3897
+ const normalized = normalizeLineEndings(content);
3898
+ const allLines = normalized.split("\n");
3899
+ const preamble = [];
3900
+ const sections = [];
3901
+ let current = null;
3902
+ let inCodeBlock = false;
3903
+ for (const line of allLines) {
3904
+ const trimmed = line.trim();
3905
+ if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) {
3906
+ inCodeBlock = !inCodeBlock;
3907
+ }
3908
+ if (!inCodeBlock && /^##\s+/.test(line)) {
3909
+ if (current) sections.push(current);
3910
+ current = {
3911
+ heading: line.trim(),
3912
+ key: normalizeHeadingKey(line),
3913
+ lines: []
3914
+ };
3915
+ continue;
3916
+ }
3917
+ if (current) {
3918
+ current.lines.push(line);
3919
+ } else {
3920
+ preamble.push(line);
3921
+ }
3922
+ }
3923
+ if (current) sections.push(current);
3924
+ return { preamble, sections };
3925
+ }
3926
+ function isLegacyBoilerplateLine(rawLine, normalized) {
3927
+ if (!normalized) return true;
3928
+ if (/^[-*_]{3,}$/.test(normalized)) return true;
3929
+ if (normalized === "```" || normalized.startsWith("```") || normalized === "~~~") return true;
3930
+ if (LEGACY_BASELINE_SET.has(normalized)) return true;
3931
+ if (/^\d{1,2}\.\s+(gpl compatibility|developer responsibility|stable version availability|human readable code|no trialware|software as a service|user tracking consent|no external executable code|legal and ethical conduct|external links and credits|admin dashboard experience|no spam in public pages|wordpress default libraries|commit frequency|version number increment|complete plugin required|trademark and copyright|directory maintenance rights)$/i.test(normalized)) {
3932
+ return true;
3933
+ }
3934
+ if (/^\d{1,2}\.\s+(separation of concerns|static analysis neutrality|safe stylesheet loading|scoped admin js|concurrency & performance|clean release packaging|defensive php security|dom xss prevention|100% multilingual parity|zero emojis|golden naming rule|mtxstudio 2-level|strict tts acoustic|strict poetry|mandatory 3-position disclaimer|safe vault sync|channel voice adaptation)/.test(normalized)) {
3935
+ return true;
3936
+ }
3937
+ if (/^#{3,4}\s+/.test(rawLine.trim())) {
3938
+ const key = normalizeHeadingKey(rawLine);
3939
+ if (STANDARD_CLI_H3_H4_KEYS.has(key)) return true;
3940
+ }
3941
+ if (rawLine.trim().startsWith(">") && (normalized.includes("generate documentation with skill documents") || normalized.includes("s\u1EED d\u1EE5ng skill content-") || normalized.includes("tip: add the") || normalized.includes("heraspec skill add documents") || normalized.includes("t\xEAn k\xEAnh:") || normalized.includes("tr\u1EE5 c\u1ED9t:") || normalized.includes("y\xEAu c\u1EA7u:"))) {
3942
+ return true;
3943
+ }
3944
+ return false;
3945
+ }
3946
+ function extractCustomRulesFromLegacyAgents(existingContent) {
3947
+ const { preamble, sections } = splitTopLevelSections(existingContent);
3948
+ const customSections = [];
3949
+ const migratedAdditions = [];
3950
+ const customPreambleLines = preamble.filter((raw) => {
3951
+ const trimmed = raw.trim();
3952
+ if (!trimmed) return false;
3953
+ if (/^#\s+HeraSpec\b/i.test(trimmed)) return false;
3954
+ const norm = normalizeComparisonLine(raw);
3955
+ return !isLegacyBoilerplateLine(raw, norm);
3956
+ });
3957
+ if (customPreambleLines.length > 0) {
3958
+ migratedAdditions.push({
3959
+ heading: "Project Notes (Header)",
3960
+ lines: customPreambleLines
3961
+ });
3962
+ }
3963
+ for (const section of sections) {
3964
+ if (!STANDARD_CLI_H2_KEYS.has(section.key)) {
3965
+ const body = section.lines.join("\n").trim();
3966
+ if (body.length > 0) {
3967
+ customSections.push(`${section.heading}
3968
+
3969
+ ${body}`);
3970
+ }
3971
+ continue;
3972
+ }
3973
+ const nonBaselineLines = [];
3974
+ for (const rawLine of section.lines) {
3975
+ const norm = normalizeComparisonLine(rawLine);
3976
+ if (!isLegacyBoilerplateLine(rawLine, norm)) {
3977
+ nonBaselineLines.push(rawLine.trimEnd());
3978
+ }
3979
+ }
3980
+ if (nonBaselineLines.length > 0) {
3981
+ const cleanHeading = section.heading.replace(/^##\s+/, "").trim();
3982
+ migratedAdditions.push({
3983
+ heading: `Migrated Customizations from "${cleanHeading}"`,
3984
+ lines: nonBaselineLines
3985
+ });
3986
+ }
3987
+ }
3988
+ return {
3989
+ customSections,
3990
+ migratedAdditions,
3991
+ hasCustomContent: customSections.length > 0 || migratedAdditions.length > 0
3992
+ };
3993
+ }
3994
+ function formatMigratedCustomContent(extraction, projectName) {
3995
+ const header = TemplateManager.getCustomAgentsTemplate(projectName).split("## Project-Specific Invariants & Quality Gates")[0].trimEnd();
3996
+ const parts = [header, "", HERASPEC_MIGRATION_MARKER, ""];
3997
+ for (const section of extraction.customSections) {
3998
+ parts.push(section.trim(), "");
3999
+ }
4000
+ for (const group of extraction.migratedAdditions) {
4001
+ parts.push(`## ${group.heading}`, "");
4002
+ parts.push(...group.lines, "");
4003
+ }
4004
+ return parts.join("\n").trimEnd() + "\n";
4005
+ }
4006
+ function appendMigratedCustomContent(existingCustom, extraction) {
4007
+ const newBlocks = [];
4008
+ const normalizedExisting = normalizeLineEndings(existingCustom);
4009
+ for (const section of extraction.customSections) {
4010
+ if (!normalizedExisting.includes(normalizeLineEndings(section).trim())) {
4011
+ newBlocks.push(section.trim());
4012
+ }
4013
+ }
4014
+ for (const group of extraction.migratedAdditions) {
4015
+ const missingLines = group.lines.filter(
4016
+ (line) => !normalizedExisting.includes(line.trim())
4017
+ );
4018
+ if (missingLines.length > 0) {
4019
+ newBlocks.push(`## ${group.heading}
4020
+
4021
+ ${missingLines.join("\n")}`);
4022
+ }
4023
+ }
4024
+ if (newBlocks.length === 0) return null;
4025
+ const stamp = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
4026
+ return normalizedExisting.trimEnd() + `
4027
+
4028
+ ${HERASPEC_MIGRATION_MARKER}
4029
+ <!-- Synced from legacy AGENTS.heraspec.md on ${stamp} -->
4030
+
4031
+ ` + newBlocks.join("\n\n") + "\n";
4032
+ }
4033
+ function parseConfigYamlContent(yamlContent) {
4034
+ const normalized = normalizeLineEndings(yamlContent);
4035
+ const lines = normalized.split("\n");
4036
+ let projectName;
4037
+ const projectTypes = [];
4038
+ const skills = [];
4039
+ let currentArrayKey = null;
4040
+ const validProjectTypes = new Set(PROJECT_TYPES);
4041
+ for (const rawLine of lines) {
4042
+ const line = rawLine.trim();
4043
+ if (!line || line.startsWith("#")) continue;
4044
+ const listMatch = rawLine.match(/^\s*-\s+(.+)$/);
4045
+ if (listMatch && currentArrayKey) {
4046
+ const value = listMatch[1].trim().replace(/^["']|["']$/g, "");
4047
+ if (value) {
4048
+ if (currentArrayKey === "projectType") projectTypes.push(value);
4049
+ if (currentArrayKey === "skills") skills.push(value);
4050
+ }
4051
+ continue;
4052
+ }
4053
+ currentArrayKey = null;
4054
+ const nameMatch = line.match(/^projectName:\s*(.+)$/i);
4055
+ if (nameMatch) {
4056
+ projectName = nameMatch[1].trim().replace(/^["']|["']$/g, "");
4057
+ continue;
4058
+ }
4059
+ const typeMatch = line.match(/^projectTypes?:\s*(.*)$/i);
4060
+ if (typeMatch) {
4061
+ const rhs = typeMatch[1].trim();
4062
+ if (!rhs) {
4063
+ currentArrayKey = "projectType";
4064
+ } else if (rhs.startsWith("[") && rhs.endsWith("]")) {
4065
+ rhs.slice(1, -1).split(",").map((v) => v.trim().replace(/^["']|["']$/g, "")).filter(Boolean).forEach((v) => projectTypes.push(v));
4066
+ } else {
4067
+ const clean = rhs.replace(/^["']|["']$/g, "");
4068
+ if (clean) projectTypes.push(clean);
4069
+ }
4070
+ continue;
4071
+ }
4072
+ const skillsMatch = line.match(/^skills:\s*(.*)$/i);
4073
+ if (skillsMatch) {
4074
+ const rhs = skillsMatch[1].trim();
4075
+ if (!rhs) {
4076
+ currentArrayKey = "skills";
4077
+ } else if (rhs.startsWith("[") && rhs.endsWith("]")) {
4078
+ rhs.slice(1, -1).split(",").map((v) => v.trim().replace(/^["']|["']$/g, "")).filter(Boolean).forEach((v) => skills.push(v));
4079
+ } else {
4080
+ const clean = rhs.replace(/^["']|["']$/g, "");
4081
+ if (clean) skills.push(clean);
4082
+ }
4083
+ }
4084
+ }
4085
+ const dedupedTypes = Array.from(
4086
+ new Set(projectTypes.filter((t) => validProjectTypes.has(t) || t.length > 0))
4087
+ );
4088
+ return {
4089
+ projectName,
4090
+ projectTypes: dedupedTypes,
4091
+ skills: Array.from(new Set(skills))
4092
+ };
4093
+ }
4094
+ async function readProjectMetadata(heraspecPath) {
4095
+ const configPath = path8.join(heraspecPath, HERASPEC_MARKERS.CONFIG_YAML);
4096
+ const projectMdPath = path8.join(heraspecPath, HERASPEC_MARKERS.PROJECT_MD);
4097
+ let metadata = { projectTypes: [], skills: [] };
4098
+ if (await FileSystemUtils.fileExists(configPath)) {
4099
+ const configContent = await FileSystemUtils.readFile(configPath);
4100
+ metadata = parseConfigYamlContent(configContent);
4101
+ }
4102
+ if (await FileSystemUtils.fileExists(projectMdPath)) {
4103
+ const projectContent = normalizeLineEndings(await FileSystemUtils.readFile(projectMdPath));
4104
+ if (!metadata.projectName) {
4105
+ const h1Match = projectContent.match(/^#\s+(?:HeraSpec Project:\s*)?(.+)$/m);
4106
+ if (h1Match) {
4107
+ const candidate = h1Match[1].trim();
4108
+ if (candidate && candidate.toLowerCase() !== "heraspec project") {
4109
+ metadata.projectName = candidate;
4110
+ }
4111
+ }
4112
+ }
4113
+ if (metadata.projectTypes.length === 0) {
4114
+ const typesSectionMatch = projectContent.match(/##\s+Project Types\s*\n([\s\S]*?)(?=\n##\s|$)/i);
4115
+ if (typesSectionMatch) {
4116
+ for (const rawLine of typesSectionMatch[1].split("\n")) {
4117
+ const itemMatch = rawLine.match(/^\s*-\s+`?([a-z0-9-]+)`?(?:\s*:|\s*$)/i);
4118
+ if (itemMatch && itemMatch[1] && itemMatch[1].toLowerCase() !== "list") {
4119
+ metadata.projectTypes.push(itemMatch[1].trim());
4120
+ }
4121
+ }
4122
+ metadata.projectTypes = Array.from(new Set(metadata.projectTypes));
4123
+ }
4124
+ }
4125
+ }
4126
+ return metadata;
4127
+ }
4128
+ async function readHeraspecState(heraspecPath) {
4129
+ const statePath = path8.join(heraspecPath, HERASPEC_MARKERS.STATE_JSON);
4130
+ if (!await FileSystemUtils.fileExists(statePath)) return null;
4131
+ try {
4132
+ const raw = await FileSystemUtils.readFile(statePath);
4133
+ return JSON.parse(raw);
4134
+ } catch {
4135
+ return null;
4136
+ }
4137
+ }
4138
+ async function writeHeraspecState(heraspecPath, state) {
4139
+ const statePath = path8.join(heraspecPath, HERASPEC_MARKERS.STATE_JSON);
4140
+ await FileSystemUtils.writeFile(statePath, JSON.stringify(state, null, 2) + "\n");
4141
+ }
4142
+ function formatBackupTimestamp(now = /* @__PURE__ */ new Date()) {
4143
+ const pad = (n) => String(n).padStart(2, "0");
4144
+ return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
4145
+ }
4146
+ async function resolveBackupFilePath(projectPath) {
4147
+ const stamp = formatBackupTimestamp();
4148
+ const baseName = `AGENTS.heraspec.backup-${stamp}.md`;
4149
+ let candidate = path8.join(projectPath, baseName);
4150
+ let suffix = 2;
4151
+ while (await FileSystemUtils.fileExists(candidate)) {
4152
+ candidate = path8.join(projectPath, `AGENTS.heraspec.backup-${stamp}-${suffix}.md`);
4153
+ suffix++;
4154
+ }
4155
+ return candidate;
4156
+ }
4157
+ async function buildAgentsComposePlan(options) {
4158
+ const { projectPath, heraspecPath, ideOption = "auto", force = false } = options;
4159
+ const agentsPath = path8.join(projectPath, HERASPEC_MARKERS.AGENTS_MD);
4160
+ const customAgentsPath = path8.join(projectPath, HERASPEC_MARKERS.AGENTS_CUSTOM_MD);
4161
+ const statePath = path8.join(heraspecPath, HERASPEC_MARKERS.STATE_JSON);
4162
+ const [metadata, discovery, skillsInfo, existingState, customExists, agentsExists] = await Promise.all([
4163
+ readProjectMetadata(heraspecPath),
4164
+ IdeAdapterManager.discoverWorkspace(projectPath, ideOption),
4165
+ IdeAdapterManager.collectCanonicalSkills(projectPath),
4166
+ readHeraspecState(heraspecPath),
4167
+ FileSystemUtils.fileExists(customAgentsPath),
4168
+ FileSystemUtils.fileExists(agentsPath)
4169
+ ]);
4170
+ const legacyCodexAgentsPath = path8.join(projectPath, "AGENTS.md");
4171
+ const legacyAgentsExists = !agentsExists && await FileSystemUtils.fileExists(legacyCodexAgentsPath);
4172
+ let legacyAgentsContent = null;
4173
+ if (legacyAgentsExists) {
4174
+ const candidateContent = await FileSystemUtils.readFile(legacyCodexAgentsPath);
4175
+ if (/HeraSpec|heraspec\/project\.md|Universal Safety Rules/i.test(candidateContent)) {
4176
+ legacyAgentsContent = candidateContent;
4177
+ }
4178
+ }
4179
+ let extraction = {
4180
+ customSections: [],
4181
+ migratedAdditions: [],
4182
+ hasCustomContent: false
4183
+ };
4184
+ let backupPath = null;
4185
+ let agentsAction = "create";
4186
+ let customAction = customExists ? "preserve" : "create-starter";
4187
+ let nextCustomContent = customExists ? null : TemplateManager.getCustomAgentsTemplate(metadata.projectName);
4188
+ const sourceToInspectPath = agentsExists ? agentsPath : legacyAgentsContent ? legacyCodexAgentsPath : null;
4189
+ const existingAgentsContent = agentsExists ? await FileSystemUtils.readFile(agentsPath) : legacyAgentsContent;
4190
+ if (existingAgentsContent !== null) {
4191
+ const existingSha = computeNormalizedSha256(existingAgentsContent);
4192
+ const hasTrackedHash = Boolean(existingState?.agentsHeraspecSha256);
4193
+ const matchesTrackedHash = hasTrackedHash && existingState?.agentsHeraspecSha256 === existingSha;
4194
+ if (agentsExists && matchesTrackedHash && !force) {
4195
+ agentsAction = "upgrade-clean";
4196
+ } else {
4197
+ extraction = extractCustomRulesFromLegacyAgents(existingAgentsContent);
4198
+ if (sourceToInspectPath === agentsPath) {
4199
+ if (!hasTrackedHash || !matchesTrackedHash) {
4200
+ backupPath = await resolveBackupFilePath(projectPath);
4201
+ }
4202
+ }
4203
+ if (extraction.hasCustomContent) {
4204
+ agentsAction = "migrate-and-regenerate";
4205
+ if (!customExists) {
4206
+ customAction = "create-from-migration";
4207
+ nextCustomContent = formatMigratedCustomContent(extraction, metadata.projectName);
4208
+ } else {
4209
+ const currentCustom = await FileSystemUtils.readFile(customAgentsPath);
4210
+ const appended = appendMigratedCustomContent(currentCustom, extraction);
4211
+ if (appended !== null) {
4212
+ customAction = "append-migration";
4213
+ nextCustomContent = appended;
4214
+ } else {
4215
+ customAction = "preserve";
4216
+ nextCustomContent = null;
4217
+ }
4218
+ }
4219
+ } else {
4220
+ agentsAction = hasTrackedHash && !matchesTrackedHash ? "migrate-and-regenerate" : "upgrade-clean";
4221
+ }
4222
+ }
4223
+ }
4224
+ const willHaveCustomFile = customExists || nextCustomContent !== null;
4225
+ const context = {
4226
+ projectName: metadata.projectName,
4227
+ projectTypes: metadata.projectTypes,
4228
+ hasCustomFile: willHaveCustomFile,
4229
+ customFileName: HERASPEC_MARKERS.AGENTS_CUSTOM_MD,
4230
+ detectedIdeFiles: discovery.detectedFiles,
4231
+ detectedSkillRoots: discovery.detectedSkillRoots,
4232
+ installedSkills: skillsInfo.summaries
4233
+ };
4234
+ const renderedAgents = TemplateManager.getAgentsTemplate(context);
4235
+ const renderedSha256 = computeNormalizedSha256(renderedAgents);
4236
+ if (agentsExists && existingAgentsContent !== null && computeNormalizedSha256(existingAgentsContent) === renderedSha256 && !force) {
4237
+ agentsAction = "up-to-date";
4238
+ backupPath = null;
4239
+ }
4240
+ return {
4241
+ agentsPath,
4242
+ customAgentsPath,
4243
+ statePath,
4244
+ backupPath,
4245
+ agentsAction,
4246
+ customAction,
4247
+ extraction,
4248
+ renderedAgents,
4249
+ nextCustomContent,
4250
+ renderedSha256,
4251
+ context
4252
+ };
4253
+ }
4254
+ var HERASPEC_MIGRATION_MARKER, STANDARD_CLI_H2_KEYS, STANDARD_CLI_H3_H4_KEYS, LEGACY_V01_EXTRA_BOILERPLATE, LEGACY_BASELINE_SET;
4255
+ var init_agents_composer = __esm({
4256
+ "src/core/agents-composer.ts"() {
4257
+ "use strict";
4258
+ init_file_system();
4259
+ init_config();
4260
+ init_templates();
4261
+ init_ide_adapter();
4262
+ HERASPEC_MIGRATION_MARKER = "<!-- HERASPEC:MIGRATED_FROM_LEGACY -->";
4263
+ STANDARD_CLI_H2_KEYS = /* @__PURE__ */ new Set([
4264
+ "universal safety rules",
4265
+ "core workflow",
4266
+ "spec format",
4267
+ "delta spec format",
4268
+ "tasks format",
4269
+ "skills system",
4270
+ "proactive memory-aware development",
4271
+ "memory-aware development",
4272
+ "rule precedence & ide workspace discovery (auto-combined)",
4273
+ "ide & workspace rule discovery",
4274
+ "ide & workspace rule discovery (auto-combined)"
4275
+ ]);
4276
+ STANDARD_CLI_H3_H4_KEYS = /* @__PURE__ */ new Set([
4277
+ "restricted commands (require user confirmation)",
4278
+ "group 1 - extremely dangerous (data destruction, hard / impossible to recover)",
4279
+ "group 2 - high danger (delete directory / multiple files)",
4280
+ "group 3 - medium danger (delete file / overwrite)",
4281
+ "group 4 - indirect danger (data loss)",
4282
+ "group 5 - disk / partition management",
4283
+ "group 6 - less dangerous (potential consequences)",
4284
+ "step 1 - create a change",
4285
+ "step 2 - refine specs",
4286
+ "step 3 - approval",
4287
+ "step 4 - implementation",
4288
+ "step 5 - archive",
4289
+ "handling parallel merge conflicts",
4290
+ "skill discovery & usage",
4291
+ "when change has multiple skills",
4292
+ "critical rules for automatic memory usage",
4293
+ "when to skip memory",
4294
+ "smart code exploration",
4295
+ "auto-detected workspace context",
4296
+ "active project skills",
4297
+ "skills system"
4298
+ ]);
4299
+ LEGACY_V01_EXTRA_BOILERPLATE = [
4300
+ "This document defines the workflow for AI agents working with HeraSpec.",
4301
+ "**CRITICAL: When implementing tasks, ALWAYS use Skills system:**",
4302
+ "**Important**: Each task group uses ONE skill. When working on a task group, agent MUST use that skill's skill.md.",
4303
+ "**Key rule**: Switch skill.md when switching task groups!",
4304
+ "Example workflow:",
4305
+ "**Example workflow:**",
4306
+ "### Step 1 - Create a Change",
4307
+ "### Step 2 - Refine Specs",
4308
+ "### Step 3 - Approval",
4309
+ "### Step 4 - Implementation",
4310
+ "### Step 5 - Archive",
4311
+ "> **IGNORE backup files**: Files like project.back1.md, project.back2.md, etc. are automatic backups created during heraspec init updates. NEVER read or reference them unless explicitly asked by the user. Only project.md is the source of truth.",
4312
+ "**When creating changes, ALWAYS read heraspec/project.md first to understand:**",
4313
+ "- Project types being used",
4314
+ "- Tech stack and conventions",
4315
+ "- Existing architecture patterns",
4316
+ "- Coding standards",
4317
+ "**Then scaffold:**",
4318
+ "- heraspec/changes/<slug>/ - Create proposal.md, tasks.md, design.md (optional)",
4319
+ "- heraspec/specs/<slug>/ - Create delta specs here (NOT inside changes folder)",
4320
+ "**If user asks to create changes based on project.md:**",
4321
+ "1. Read heraspec/project.md thoroughly",
4322
+ "2. Identify all features/capabilities mentioned",
4323
+ "3. Create separate changes for each major feature",
4324
+ "4. Ensure each change follows project.md conventions",
4325
+ "5. Use correct project types and skills from project.md",
4326
+ "- Never modify source-of-truth specs directly",
4327
+ '- Wait for user: "Specs approved."',
4328
+ "1. Read task line to identify skill:",
4329
+ "## 1. Perfex module - Category Management (projectType: perfex-module, skill: module-codebase)",
4330
+ "- [ ] 1.1 Create module structure",
4331
+ "2. Find skill folder:",
4332
+ "3. Read skill.md:",
4333
+ "- Understand purpose, steps, inputs, outputs",
4334
+ "- Follow tone, rules, and limitations",
4335
+ "- Check available templates and scripts",
4336
+ "- Ignore Vietnamese Skill Files: Only read the English skill.md instructions. Completely ignore any *.vi.md translation files.",
4337
+ "4. Use skill resources:",
4338
+ "5. Implement following skill.md guidance:",
4339
+ "- Follow step-by-step process",
4340
+ "- Use correct naming conventions",
4341
+ "- Apply code style rules",
4342
+ "- Respect limitations",
4343
+ "- Task: (projectType: perfex-module, skill: module-codebase)",
4344
+ "- Agent reads: heraspec/skills/perfex-module/module-codebase/skill.md",
4345
+ "- Agent follows: Steps, uses templates, runs scripts",
4346
+ "- Agent implements: According to skill.md guidelines",
4347
+ "- Task: (skill: ui-ux)",
4348
+ "- Agent reads: heraspec/skills/ui-ux/skill.md",
4349
+ "- Agent MUST use search scripts before implementing:",
4350
+ "# Search for design intelligence",
4351
+ "- Agent synthesizes search results",
4352
+ "- Agent implements with proper colors, fonts, styles from search results",
4353
+ "- Agent verifies with pre-delivery checklist",
4354
+ "- Agent generates a **Compliance Report** with:",
4355
+ "- \u2705 Passed items",
4356
+ "- \u26A0\uFE0F Items needing review",
4357
+ "- \u274C Violations with file paths and line numbers",
4358
+ "- **CRITICAL**: Agent MUST present full report and **wait for user confirmation** before making changes",
4359
+ '- Reference guideline numbers (e.g., "Guideline 7: User Tracking Consent")',
4360
+ "- Task: (projectType: wordpress-plugin, skill: ux-element)",
4361
+ "- **Special case - WordPress Plugin:**",
4362
+ "- **Example prompt for Documents skill:**",
4363
+ "If you need to generate multi-format documentation, use this prompt:",
4364
+ "- **Dynamic Documentation Generation**:",
4365
+ "When generating documentation, do NOT simply fill a template. The Agent MUST:",
4366
+ "1. **Create** the /documentations directory if it does not exist.",
4367
+ "2. **Design** a custom layout and content structure suitable for the project type.",
4368
+ "3. **Synchronize** with the ui-ux skill for premium visual design (colors, typography, animations).",
4369
+ "4. **Scan All Specs**: If project-wide, read heraspec/project.md and all files in heraspec/specs/ to synthesize the content.",
4370
+ "- Task: (projectType: wordpress, skill: ux-element)",
4371
+ "- Task: (projectType: wordpress-plugin, skill: plugin-check)",
4372
+ "- Task: (projectType: wordpress-plugin, skill: plugin-directory)",
4373
+ "- Follow tasks.md",
4374
+ "- Mark tasks completed: - [x]",
4375
+ `> "Tip: Add the 'documents' skill for premium HTML & Landing Page support:`,
4376
+ '> heraspec skill add documents"',
4377
+ "- Project-specific: heraspec/skills/<project-type>/",
4378
+ "- Cross-cutting: heraspec/skills/<skill-name>/ (root level)",
4379
+ "- **Consistency**: Follow the step-by-step process in the skill's skill.md.",
4380
+ "## 1. WordPress module - Feature (skill: admin-settings-page)",
4381
+ "- [ ] Task 1.1 Create module structure",
4382
+ "- [ ] Task 1.2 Configure registration",
4383
+ "## 2. UI/UX - Admin Interface (skill: ui-ux)",
4384
+ "- [ ] Task 2.1 Design color palette",
4385
+ "- [ ] Task 2.2 Create component styles",
4386
+ "## 3. Documents - User Guide (skill: documents)",
4387
+ "- [ ] Task 3.1 Write technical docs",
4388
+ "## 1. WordPress plugin - admin settings page (projectType: wordpress-plugin, skill: admin-settings-page)",
4389
+ "- [ ] Task description",
4390
+ "- `truncate` : Cutt off file content",
4391
+ "truncate : Cutt off file content",
4392
+ "- heraspec explore outline <file> -> View structure (~1K tokens vs ~12K full file)",
4393
+ '- heraspec explore search "<query>" <path> -> Find symbols across codebase',
4394
+ "- heraspec explore unfold <file> <symbol> -> Read just one function",
4395
+ "Example with multiple skills in one change:",
4396
+ 'python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --domain <domain>',
4397
+ 'python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --stack <stack>',
4398
+ "- Agent reads: heraspec/skills/wordpress-plugin/plugin-directory/skill.md",
4399
+ "- Agent MUST review plugin against **18 WordPress.org Directory Guidelines**:",
4400
+ "- Agent MUST adhere to **10 Enterprise Code Quality & Clean Code Standards**:",
4401
+ "- Use templates from heraspec/skills/perfex-module/module-codebase/templates/ (module-main.php, install.php, uninstall.php, controller-admin.php, controller-api.php, model-main.php, helper.php, deploy.ps1, webpack.config.js).",
4402
+ "- Tasks: (projectType: content-channel, skill: content-strategy), (skill: content-scaffolding), (skill: content-scripting), (skill: content-voice-adapter), (skill: content-prompts), (skill: content-compliance), (skill: content-vault-sync), or (skill: content-channel)",
4403
+ "- Install: heraspec skill add content-channel or heraspec skill add <skill-name> --project-type content-channel",
4404
+ "- Agent reads corresponding skill instructions in heraspec/skills/<skill-name>/skill.md or heraspec/skills/content-channel/<skill-name>/skill.md.",
4405
+ "- Agent MUST adhere to **7 Core Content Production Standards**:",
4406
+ "- Short sentences: 12 - 20 words max per sentence (never exceed 25 words or 120 chars).",
4407
+ "- Comma clauses: 8 - 12 words max.",
4408
+ "- Repetition Bug Prevention: Never place 2 reduplicative words (t\u1EEB l\xE1y) adjacently; always separate with a natural comma ,.",
4409
+ "- Clean text: Zero artificial bracket tags; rely entirely on natural punctuation (., ,, ..., !) and sentence rhythm for voice pacing.",
4410
+ "- **Example prompts for Content Channel Development (content-channel skills):**",
4411
+ "- Channel Strategy (content-strategy):",
4412
+ "- Channel Scaffolding (content-scaffolding):",
4413
+ "- Raw Text Transmutation (content-voice-adapter):",
4414
+ "- Scriptwriting from Scratch (content-scripting):",
4415
+ "- AI Visual & Suno BGM Prompts (content-prompts):",
4416
+ "- Legal Compliance & Disclaimer (content-compliance):",
4417
+ "- Vault Synchronization (content-vault-sync):",
4418
+ "- Agent reads: heraspec/skills/perfex-module/skill.md, heraspec/skills/perfex-module/module-codebase/skill.md, and heraspec/skills/perfex-module/code-quality-guidelines/skill.md",
4419
+ "- Install: heraspec skill add perfex-module or heraspec skill add module-codebase --project-type perfex-module or heraspec skill add code-quality-guidelines --project-type perfex-module",
4420
+ "- List all skills: Check heraspec/skills/ directory",
4421
+ "- Agent MUST run WordPress Plugin Check (PCP) tool",
4422
+ "- Agent fixes coding standard issues iteratively until all pass",
4423
+ "- If missing:",
4424
+ "- Preferred: Proactively install it via heraspec skill add <name> (e.g., heraspec skill add documents) if you have terminal access.",
4425
+ "- Fallback: If you cannot install it, STOP and ask the user to add it. DO NOT attempt manual generation without the skill.",
4426
+ "- Option A (Preferred): If you can run commands, execute heraspec skill add <skill-name> immediately.",
4427
+ "- Option B (Fallback): If you cannot run commands, STOP and ask the user to run it.",
4428
+ "- DO NOT create a task plan or attempt manual generation without the skill language.",
4429
+ '- CRITICAL: Save all files in the /documentations directory (create it if missing)."',
4430
+ "- Concise overview (documentations/documentation.txt)",
4431
+ "- Technical Markdown (documentations/documentation.md)",
4432
+ "- Interactive HTML (documentations/documentation.html)",
4433
+ "- Premium Documentation Landing Page (documentations/documentation-landing-page.html)",
4434
+ "- ## 1. WordPress module - Feature (skill: admin-settings-page)",
4435
+ "## 1. WordPress module - Feature (skill: admin-settings-page)",
4436
+ "- Agent runs WordPress Plugin Check (PCP) tool",
4437
+ "**Example prompts for Content Channel Development (content-channel skills):**",
4438
+ "**Dynamic Documentation Generation**:",
4439
+ "> - Ng\xE1ch: [V\xED d\u1EE5: Thi\u1EC1n \u0111\u1ECBnh & L\u1ED1i s\u1ED1ng t\u1ED1i gi\u1EA3n]",
4440
+ "> - Kh\xE1n gi\u1EA3 m\u1EE5c ti\xEAu: [V\xED d\u1EE5: 25 - 40 tu\u1ED5i, nh\xE2n vi\xEAn v\u0103n ph\xF2ng stress]",
4441
+ "> - Slogan: [V\xED d\u1EE5: Th\xE2n c\xF3 an, t\xE2m m\u1EDBi l\u1EA1c] | Icon Lucide: [Heart] | M\xE0u: [#10b981]",
4442
+ "> [D\xC1N \u0110O\u1EA0N V\u0102N B\u1EA2N TH\xD4 V\xC0O \u0110\xC2Y]",
4443
+ '> Y\xEAu c\u1EA7u qua 4 b\u01B0\u1EDBc: (1) L\u1ECDc l\u1EC7ch tone theo ma tr\u1EADn th\u1EC3 lo\u1EA1i (ch\u1EEFa l\xE0nh: l\u1ECDc m\xEA t\xEDn/\u0111\u1ED5 l\u1ED7i; truy\u1EC7n ma: l\u1ECDc m\xE1u me/vi ph\u1EA1m N\u0110 15 t\xEAn ng\u01B0\u1EDDi th\u1EADt/c\u1EE3t nh\u1EA3; d\u01B0\u1EE1ng sinh: l\u1ECDc ph\u1EA3n khoa h\u1ECDc/th\u1EA7n th\xE1nh h\xF3a; chi\xEAm nghi\u1EC7m: l\u1ECDc than th\u1EDF n\u1EA1n nh\xE2n), (2) T\xE1i c\u1EA5u tr\xFAc theo DNA tri\u1EBFt l\xFD v\xE0 \u0111\u1EA1i t\u1EEB nh\xE2n x\u01B0ng c\u1EE7a k\xEAnh, (3) T\u1ED1i \u01B0u \xE2m h\u1ECDc TTS 12-20 t\u1EEB/c\xE2u s\u1EA1ch th\u1EBB ngo\u1EB7c vu\xF4ng, (4) \u0110\xF3ng g\xF3i 6 ph\u1EA7n chu\u1EA9n MTxStudio k\xE8m Storyboard prompt, Caption v\xE0 Disclaimer ph\xE1p l\xFD ph\xF9 h\u1EE3p th\u1EC3 lo\u1EA1i."',
4444
+ '> - Y\xEAu c\u1EA7u \xE2m h\u1ECDc TTS: C\xE2u ng\u1EAFn 12-20 t\u1EEB, ng\u1EAFt nh\u1ECBp d\u1EA5u ph\u1EA9y r\xF5 r\xE0ng, kh\xF4ng \u0111i\u1EC7p \xE2m t\u1EEB l\xE1y, TUY\u1EC6T \u0110\u1ED0I KH\xD4NG ch\xE8n th\u1EBB ngo\u1EB7c vu\xF4ng ([l\u1EA5y h\u01A1i], [th\u1EDF d\xE0i]), b\u1EA3o to\xE0n th\u01A1 ca m\u1ED7i c\xE2u 1 d\xF2ng (\\n), xu\u1EA5t \u0111\u1EA7y \u0111\u1EE7 6 ph\u1EA7n k\xE8m Storyboard v\xE0 Caption Facebook."',
4445
+ `> - C\u1EA7n t\u1EA1o: Prompt Avatar 1:1, Cover 16:9, B\u1EA3ng 5 Prompts Storyboard b\xE0i vi\u1EBFt '[T\xEAn b\xE0i vi\u1EBFt]', v\xE0 Prompt Suno AI BGM kh\xF4ng l\u1EDDi."`,
4446
+ "> - Cung c\u1EA5p Disclaimer chu\u1EA9n ph\xE1p l\xFD (Ngh\u1ECB \u0111\u1ECBnh 15/2020/N\u0110-CP) \u0111\u1EB7t \u1EDF ch\xE2n Caption.",
4447
+ '> - Cung c\u1EA5p Prompt m\xE0n h\xECnh c\u1EA3nh b\xE1o Intro Warning Card (0:00 - 0:04, t\u1EF7 l\u1EC7 16:9)."',
4448
+ "- Use heraspec explore outline <file> -> View structure (~1K tokens vs ~12K full file)"
4449
+ ];
4450
+ LEGACY_BASELINE_SET = buildBaselineLineSet();
4451
+ }
4452
+ });
4453
+
4454
+ // src/core/skills/index.ts
4455
+ var init_skills = __esm({
4456
+ "src/core/skills/index.ts"() {
4457
+ "use strict";
4458
+ init_skill_parser();
2983
4459
  init_skill_manager();
2984
4460
  }
2985
4461
  });
@@ -2989,7 +4465,8 @@ var skill_exports = {};
2989
4465
  __export(skill_exports, {
2990
4466
  SkillCommand: () => SkillCommand
2991
4467
  });
2992
- import path7 from "path";
4468
+ import path9 from "path";
4469
+ import chalk2 from "chalk";
2993
4470
  import ora2 from "ora";
2994
4471
  import { fileURLToPath } from "url";
2995
4472
  import { dirname, join } from "path";
@@ -2998,7 +4475,7 @@ async function getCoreTemplatesDir() {
2998
4475
  const possiblePaths = [];
2999
4476
  try {
3000
4477
  const packageJsonPath = require2.resolve("../package.json");
3001
- const packageDir = path7.dirname(packageJsonPath);
4478
+ const packageDir = path9.dirname(packageJsonPath);
3002
4479
  possiblePaths.push(
3003
4480
  join(packageDir, "src", "core", "templates", "skills"),
3004
4481
  // Source (when linked, this is the actual source)
@@ -3009,7 +4486,7 @@ async function getCoreTemplatesDir() {
3009
4486
  }
3010
4487
  try {
3011
4488
  const packageJsonPath = require2.resolve("heraspec/package.json");
3012
- const packageDir = path7.dirname(packageJsonPath);
4489
+ const packageDir = path9.dirname(packageJsonPath);
3013
4490
  possiblePaths.push(
3014
4491
  join(packageDir, "dist", "core", "templates", "skills"),
3015
4492
  // Built
@@ -3041,6 +4518,8 @@ var init_skill = __esm({
3041
4518
  init_skills();
3042
4519
  init_config();
3043
4520
  init_skills_template_map();
4521
+ init_ide_adapter();
4522
+ init_agents_composer();
3044
4523
  require2 = createRequire(import.meta.url);
3045
4524
  __filename = fileURLToPath(import.meta.url);
3046
4525
  __dirname = dirname(__filename);
@@ -3182,7 +4661,7 @@ var init_skill = __esm({
3182
4661
  });
3183
4662
  console.log();
3184
4663
  }
3185
- const skillMdPath = path7.join(skillInfo.skillPath, "skill.md");
4664
+ const skillMdPath = path9.join(skillInfo.skillPath, "skill.md");
3186
4665
  if (await FileSystemUtils.fileExists(skillMdPath)) {
3187
4666
  console.log("\u2550".repeat(60));
3188
4667
  console.log("\n## Full skill.md Content\n");
@@ -3194,7 +4673,7 @@ var init_skill = __esm({
3194
4673
  async repair(projectPath = ".") {
3195
4674
  const spinner = ora2("Repairing skills structure...").start();
3196
4675
  try {
3197
- const skillsDir = path7.join(projectPath, HERASPEC_DIR_NAME, SKILLS_DIR_NAME);
4676
+ const skillsDir = path9.join(projectPath, HERASPEC_DIR_NAME, SKILLS_DIR_NAME);
3198
4677
  if (!await FileSystemUtils.fileExists(skillsDir)) {
3199
4678
  spinner.fail('Skills directory does not exist. Run "heraspec init" first.');
3200
4679
  process.exitCode = 1;
@@ -3205,7 +4684,7 @@ var init_skill = __esm({
3205
4684
  let errors = 0;
3206
4685
  for (const skill of skills) {
3207
4686
  const skillPath = skill.path;
3208
- const skillMdPath = path7.join(skillPath, "skill.md");
4687
+ const skillMdPath = path9.join(skillPath, "skill.md");
3209
4688
  if (!await FileSystemUtils.fileExists(skillMdPath)) {
3210
4689
  spinner.warn(`Missing skill.md in ${skillPath}`);
3211
4690
  errors++;
@@ -3213,7 +4692,7 @@ var init_skill = __esm({
3213
4692
  }
3214
4693
  const standardDirs = ["templates", "scripts", "examples"];
3215
4694
  for (const dir of standardDirs) {
3216
- const dirPath = path7.join(skillPath, dir);
4695
+ const dirPath = path9.join(skillPath, dir);
3217
4696
  if (!await FileSystemUtils.fileExists(dirPath)) {
3218
4697
  await FileSystemUtils.createDirectory(dirPath);
3219
4698
  fixed++;
@@ -3263,10 +4742,10 @@ var init_skill = __esm({
3263
4742
  process.exitCode = 1;
3264
4743
  return;
3265
4744
  }
3266
- const skillsDir = path7.join(projectPath, HERASPEC_DIR_NAME, SKILLS_DIR_NAME);
4745
+ const skillsDir = path9.join(projectPath, HERASPEC_DIR_NAME, SKILLS_DIR_NAME);
3267
4746
  let destPath;
3268
4747
  if (templateInfo.isCrossCutting) {
3269
- destPath = path7.join(skillsDir, skillName);
4748
+ destPath = path9.join(skillsDir, skillName);
3270
4749
  } else {
3271
4750
  if (!templateInfo.projectType) {
3272
4751
  spinner.fail("Project type is required for this skill");
@@ -3280,8 +4759,8 @@ var init_skill = __esm({
3280
4759
  effectiveSkillName = parts[1];
3281
4760
  }
3282
4761
  }
3283
- destPath = path7.join(skillsDir, templateInfo.projectType, effectiveSkillName);
3284
- const legacyPath = path7.join(skillsDir, templateInfo.projectType, `${templateInfo.projectType}:${effectiveSkillName}`);
4762
+ destPath = path9.join(skillsDir, templateInfo.projectType, effectiveSkillName);
4763
+ const legacyPath = path9.join(skillsDir, templateInfo.projectType, `${templateInfo.projectType}:${effectiveSkillName}`);
3285
4764
  if (legacyPath !== destPath && await FileSystemUtils.fileExists(legacyPath)) {
3286
4765
  spinner.info(`Cleaning up legacy prefixed skill folder: ${legacyPath}`);
3287
4766
  try {
@@ -3302,39 +4781,65 @@ var init_skill = __esm({
3302
4781
  process.exitCode = 1;
3303
4782
  return;
3304
4783
  }
3305
- const templateFile = path7.join(coreTemplatesDir, templateInfo.templateFileName);
4784
+ const templateFile = path9.join(coreTemplatesDir, templateInfo.templateFileName);
3306
4785
  if (!await FileSystemUtils.fileExists(templateFile)) {
3307
4786
  spinner.fail(`Template file not found: ${templateFile}`);
3308
4787
  process.exitCode = 1;
3309
4788
  return;
3310
4789
  }
3311
- await FileSystemUtils.copyFile(templateFile, path7.join(destPath, "skill.md"));
3312
- const upperTemplateFile = path7.join(path7.dirname(templateFile), "SKILL.md");
4790
+ await FileSystemUtils.copyFile(templateFile, path9.join(destPath, "skill.md"));
4791
+ const upperTemplateFile = path9.join(path9.dirname(templateFile), "SKILL.md");
3313
4792
  if (await FileSystemUtils.fileExists(upperTemplateFile)) {
3314
- await FileSystemUtils.copyFile(upperTemplateFile, path7.join(destPath, "SKILL.md"));
4793
+ await FileSystemUtils.copyFile(upperTemplateFile, path9.join(destPath, "SKILL.md"));
3315
4794
  }
3316
4795
  if (templateInfo.viFileName) {
3317
- const viFile = path7.join(coreTemplatesDir, templateInfo.viFileName);
4796
+ const viFile = path9.join(coreTemplatesDir, templateInfo.viFileName);
3318
4797
  if (await FileSystemUtils.fileExists(viFile)) {
3319
- await FileSystemUtils.copyFile(viFile, path7.join(destPath, "skill.vi.md"));
4798
+ await FileSystemUtils.copyFile(viFile, path9.join(destPath, "skill.vi.md"));
3320
4799
  }
3321
4800
  }
3322
4801
  if (templateInfo.resourceDirs) {
3323
4802
  for (const resourceDir of templateInfo.resourceDirs) {
3324
- const srcResourceDir = path7.join(coreTemplatesDir, resourceDir);
3325
- const destResourceDir = path7.join(destPath, path7.basename(resourceDir));
4803
+ const srcResourceDir = path9.join(coreTemplatesDir, resourceDir);
4804
+ const destResourceDir = path9.join(destPath, path9.basename(resourceDir));
3326
4805
  if (await FileSystemUtils.fileExists(srcResourceDir)) {
3327
4806
  await FileSystemUtils.copyDirectory(srcResourceDir, destResourceDir);
3328
4807
  }
3329
4808
  }
3330
4809
  }
3331
- await FileSystemUtils.createDirectory(path7.join(destPath, "templates"));
3332
- await FileSystemUtils.createDirectory(path7.join(destPath, "scripts"));
3333
- await FileSystemUtils.createDirectory(path7.join(destPath, "examples"));
4810
+ await FileSystemUtils.createDirectory(path9.join(destPath, "templates"));
4811
+ await FileSystemUtils.createDirectory(path9.join(destPath, "scripts"));
4812
+ await FileSystemUtils.createDirectory(path9.join(destPath, "examples"));
4813
+ const heraspecDir = path9.join(path9.resolve(projectPath), HERASPEC_DIR_NAME);
4814
+ const existingState = await readHeraspecState(heraspecDir);
4815
+ const installedName = path9.basename(destPath);
4816
+ const ideSync = await IdeAdapterManager.syncAdaptersAndSkills({
4817
+ projectPath,
4818
+ ideOption: "auto",
4819
+ hasCustomFile: await FileSystemUtils.fileExists(
4820
+ path9.join(path9.resolve(projectPath), HERASPEC_MARKERS.AGENTS_CUSTOM_MD)
4821
+ ),
4822
+ skipAdapters: true,
4823
+ skillNames: [installedName],
4824
+ force: true,
4825
+ recordedMirrors: existingState?.mirroredSkills
4826
+ });
4827
+ if (existingState) {
4828
+ await writeHeraspecState(heraspecDir, {
4829
+ ...existingState,
4830
+ updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
4831
+ mirroredSkills: ideSync.updatedMirrors
4832
+ });
4833
+ }
3334
4834
  const successMessage = isUpdate ? `Skill "${skillName}" updated successfully` : `Skill "${skillName}" added successfully`;
3335
4835
  spinner.succeed(successMessage);
3336
4836
  console.log(`
3337
4837
  \u{1F4CD} Location: ${destPath}`);
4838
+ for (const report of ideSync.reports) {
4839
+ if (report.status === "created" || report.status === "updated") {
4840
+ console.log(chalk2.cyan(` \u2713 Mirrored to IDE skill root: ${report.relativePath}`));
4841
+ }
4842
+ }
3338
4843
  if (isUpdate) {
3339
4844
  console.log(`
3340
4845
  \u2728 Skill has been updated with latest features and improvements.`);
@@ -3363,649 +4868,294 @@ var ProjectTypeSchema = z.enum([
3363
4868
  "wordpress-plugin",
3364
4869
  "wordpress-theme",
3365
4870
  "perfex-module",
3366
- "laravel-package",
3367
- "node-service",
3368
- "generic-webapp",
3369
- "backend-api",
3370
- "frontend-app",
3371
- "multi-stack",
3372
- "content-channel"
3373
- ]);
3374
- var SpecMetaSchema = z.object({
3375
- projectType: z.union([
3376
- ProjectTypeSchema,
3377
- z.array(ProjectTypeSchema)
3378
- ]).optional(),
3379
- domain: z.string().optional(),
3380
- stack: z.union([
3381
- z.string(),
3382
- z.array(z.string())
3383
- ]).optional()
3384
- }).optional();
3385
- var ScenarioSchema = z.object({
3386
- name: z.string(),
3387
- steps: z.array(z.string()).min(1)
3388
- });
3389
- var RequirementSchema = z.object({
3390
- id: z.string().optional(),
3391
- name: z.string(),
3392
- description: z.string(),
3393
- scenarios: z.array(ScenarioSchema).optional(),
3394
- constraints: z.array(z.string()).optional()
3395
- });
3396
-
3397
- // src/core/schemas/spec.schema.ts
3398
- import { z as z2 } from "zod";
3399
- var SpecSchema = z2.object({
3400
- name: z2.string().min(1),
3401
- meta: SpecMetaSchema,
3402
- overview: z2.string().min(1),
3403
- requirements: z2.array(RequirementSchema).min(1),
3404
- metadata: z2.object({
3405
- version: z2.string().default("1.0.0"),
3406
- format: z2.literal("heraspec"),
3407
- sourcePath: z2.string().optional()
3408
- }).optional()
3409
- });
3410
-
3411
- // src/core/schemas/change.schema.ts
3412
- import { z as z3 } from "zod";
3413
- var DeltaTypeSchema = z3.enum(["ADDED", "MODIFIED", "REMOVED"]);
3414
- var DeltaRequirementSchema = z3.object({
3415
- type: DeltaTypeSchema,
3416
- requirement: z3.object({
3417
- id: z3.string().optional(),
3418
- name: z3.string(),
3419
- description: z3.string(),
3420
- scenarios: z3.array(z3.object({
3421
- name: z3.string(),
3422
- steps: z3.array(z3.string())
3423
- })).optional(),
3424
- constraints: z3.array(z3.string()).optional()
3425
- })
3426
- });
3427
- var ChangeSchema = z3.object({
3428
- name: z3.string(),
3429
- proposal: z3.string().min(1),
3430
- tasks: z3.array(z3.string()).optional(),
3431
- design: z3.string().optional()
3432
- });
3433
-
3434
- // src/core/init.ts
3435
- init_file_system();
3436
- import ora3 from "ora";
3437
- import chalk2 from "chalk";
3438
- import path8 from "path";
3439
-
3440
- // src/core/templates/index.ts
3441
- var TemplateManager = class {
3442
- static getProjectTemplate() {
3443
- return `# HeraSpec Project
3444
-
3445
- ## \u26A1 Slash Commands (Agent Triggers)
3446
-
3447
- When the user types messages starting with a slash (/), you MUST intercept them as action triggers rather than conversational queries. Please execute the corresponding terminal commands immediately:
3448
-
3449
- - /heraspec [args] : Run the heraspec CLI tool with the provided arguments (e.g. /heraspec validate my-change)
3450
- - /sync : Run heraspec sync <current-change>
3451
- - /archive : Run heraspec archive <current-change> --yes
3452
- - /skill [name] : Run heraspec skill add [name]
3453
- - /hotfix [title] : Run heraspec hotfix [title]
3454
-
3455
- *If the user types a slash command, do not explain what you are going to do, just run the terminal command and report the output.*
3456
-
3457
- ## Overview
3458
- Describe your project here.
3459
-
3460
- ## Project Types
3461
- - List your project type(s) here (e.g., content-channel, node-service, wordpress-plugin, wordpress-theme, perfex-module, laravel-package, generic-webapp, backend-api, frontend-app, multi-stack)
3462
-
3463
- ## Tech Stack
3464
- - List primary languages, frameworks, runtime, and key libraries
3465
-
3466
- ## Architecture
3467
- Describe the high-level architecture: entry points, module structure, data flow.
3468
-
3469
- ## Key Dependencies
3470
- List critical dependencies and their purposes (e.g., better-sqlite3 for memory, commander for CLI).
3471
-
3472
- ## Conventions
3473
- Define coding standards, architectural patterns, and conventions to follow.
3474
- `;
3475
- }
3476
- static getAgentsTemplate() {
3477
- return `# HeraSpec \u2014 AI Agent Instructions
3478
-
3479
- This document defines the workflow for AI agents working with HeraSpec.
3480
-
3481
- ## Universal Safety Rules
3482
-
3483
- - **NO AUTO-COMMIT**: Agent MUST NOT perform \`git commit\` or \`git push\` autonomously. This task is reserved for the User unless explicitly ordered.
3484
- - **NO AUTO-PUBLISH**: Agent MUST NOT perform \`npm publish\` or trigger automated releases/deployments autonomously.
3485
- - **SKILL PREREQUISITE**: If a task maps to a skill (e.g., "Generate documentation"), you **MUST** verify the skill folder exists in \`heraspec/skills/\`. If missing:
3486
- - **Preferred**: Proactively install it via \`heraspec skill add <name>\` (e.g., \`heraspec skill add documents\`) if you have terminal access.
3487
- - **Fallback**: If you cannot install it, **STOP** and ask the user to add it. **DO NOT** attempt manual generation without the skill.
3488
- - **IGNORE VIETNAMESE SKILL FILES**: When reading and executing skill workflows, you **MUST ONLY** look at the English version of the skill instructions (e.g., \`skill.md\`). You **MUST completely ignore** all Vietnamese versions (e.g., \`skill.vi.md\` or files ending with \`*.vi.md\`). These Vietnamese files are for reference/development purposes by the user only.
3489
- - **USER CONFIRMATION**: For destructive actions or public releases, always request explicit User approval first.
3490
-
3491
- ### Restricted Commands (REQUIRE USER CONFIRMATION)
3492
-
3493
- The following commands are classified by risk level. You **MUST NOT** execute them without explicit user confirmation/approval in the chat, especially if they are outside the source workspace or involve deletion.
3494
-
3495
- #### GROUP 1 \u2013 EXTREMELY DANGEROUS (DATA DESTRUCTION, HARD / IMPOSSIBLE TO RECOVER)
3496
- - \`rm -rf\` : Recursive delete + no prompt, can wipe entire system
3497
- - \`rm -r\` : Delete directory and all contents
3498
- - \`rm\` : Delete file directly, bypassing trash
3499
- - \`unlink\` : Delete file at filesystem level, cannot undo
3500
- - \`shred\` : Overwrite data multiple times to make it unrecoverable
3501
- - \`wipe\` : Permanently wipe data on disk
3502
- - \`dd\` : Write/copy raw blocks, easily destroy disk or partition
3503
- - \`mkfs\`, \`mkfs.ext4\`, \`mkfs.xfs\` : Create new filesystem, wiping old data
3504
- - \`format\`, \`Format-Volume\` : Format drive/volume
3505
-
3506
- #### GROUP 2 \u2013 HIGH DANGER (DELETE DIRECTORY / MULTIPLE FILES)
3507
- - \`rmdir\` : Delete directory
3508
- - \`rd\`, \`rmdir /s\` : Windows delete directory
3509
- - \`Remove-Item -Recurse\`, \`Remove-Item\` : PowerShell delete
3510
- - \`del /s\`, \`erase /s\` : CMD batch delete
3511
-
3512
- #### GROUP 3 \u2013 MEDIUM DANGER (DELETE FILE / OVERWRITE)
3513
- - \`del\`, \`erase\` : Delete file
3514
- - \`Clear-Content\` : Clear file content
3515
- - \`cp --remove-destination\` : Overwrite destination by deleting first
3516
-
3517
- #### GROUP 4 \u2013 INDIRECT DANGER (DATA LOSS)
3518
- - \`mv\` : Move / overwrite file, old data lost
3519
- - \`rsync --delete\` : Delete file at destination if not in source
3520
- - \`install\` : Overwrite system files
3521
-
3522
- #### GROUP 5 \u2013 DISK / PARTITION MANAGEMENT
3523
- - \`fdisk\`, \`cfdisk\`, \`parted\`, \`diskpart\` : Partition management
3524
- - \`mount\`, \`umount\` : Filesystem mounting
3525
-
3526
- #### GROUP 6 \u2013 LESS DANGEROUS (POTENTIAL CONSEQUENCES)
3527
- - \`truncate\` : Cutt off file content
3528
- - \`chown\`, \`chmod\` : Change ownership/permissions
3529
- - \`attrib\` : Change attributes
3530
-
3531
- ## Core Workflow
3532
-
3533
- ### Step 1 \u2014 Create a Change
3534
-
3535
- **When creating changes, ALWAYS read heraspec/project.md first to understand:**
3536
- - Project types being used
3537
- - Tech stack and conventions
3538
- - Existing architecture patterns
3539
- - Coding standards
3540
-
3541
- > **IGNORE backup files**: Files like \`project.back1.md\`, \`project.back2.md\`, etc. are automatic backups created during \`heraspec init\` updates. NEVER read or reference them unless explicitly asked by the user. Only \`project.md\` is the source of truth.
3542
-
3543
- **Then scaffold:**
3544
- - \`heraspec/changes/<slug>/\` - Create proposal.md, tasks.md, design.md (optional)
3545
- - \`heraspec/specs/<slug>/\` - Create delta specs here (NOT inside changes folder)
3546
-
3547
- **If user asks to create changes based on project.md:**
3548
- 1. Read \`heraspec/project.md\` thoroughly
3549
- 2. Identify all features/capabilities mentioned
3550
- 3. Create separate changes for each major feature
3551
- 4. Ensure each change follows project.md conventions
3552
- 5. Use correct project types and skills from project.md
3553
-
3554
- ### Step 2 \u2014 Refine Specs
3555
- - Update delta specs in \`heraspec/specs/<slug>/\`
3556
- - Never modify source-of-truth specs directly
3557
-
3558
- ### Step 3 \u2014 Approval
3559
- - Wait for user: "Specs approved."
3560
-
3561
- ### Step 4 \u2014 Implementation
3562
-
3563
- **CRITICAL: When implementing tasks, ALWAYS use Skills system:**
3564
-
3565
- 1. **Read task line** to identify skill:
3566
- \`\`\`markdown
3567
- ## 1. Perfex module \u2013 Category Management (projectType: perfex-module, skill: module-codebase)
3568
- - [ ] 1.1 Create module structure
3569
- \`\`\`
3570
-
3571
- 2. **Find skill folder**:
3572
- - Project-specific: \`heraspec/skills/<project-type>/<skill-name>/\`
3573
- - Cross-cutting: \`heraspec/skills/<skill-name>/\`
3574
-
3575
- 3. **Read skill.md**:
3576
- - Understand purpose, steps, inputs, outputs
3577
- - Follow tone, rules, and limitations
3578
- - Check available templates and scripts
3579
- - **Ignore Vietnamese Skill Files**: Only read the English \`skill.md\` instructions. Completely ignore any \`*.vi.md\` translation files.
3580
-
3581
- 4. **Use skill resources**:
3582
- - Run scripts from \`scripts/\` folder if needed
3583
- - Use templates from \`templates/\` folder
3584
- - Reference examples from \`examples/\` folder
3585
-
3586
- 5. **Implement following skill.md guidance**:
3587
- - Follow step-by-step process
3588
- - Use correct naming conventions
3589
- - Apply code style rules
3590
- - Respect limitations
3591
-
3592
- **Example workflow:**
3593
- - Task: \`(projectType: perfex-module, skill: module-codebase)\`
3594
- - Agent reads: \`heraspec/skills/perfex-module/module-codebase/skill.md\`
3595
- - Agent follows: Steps, uses templates, runs scripts
3596
- - Agent implements: According to skill.md guidelines
3597
-
3598
- **Special case - UI/UX skill:**
3599
- - Task: \`(skill: ui-ux)\`
3600
- - Agent reads: \`heraspec/skills/ui-ux/skill.md\`
3601
- - Agent MUST use search scripts before implementing:
3602
- \`\`\`bash
3603
- # Search for design intelligence
3604
- python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --domain <domain>
3605
- python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --stack <stack>
3606
- \`\`\`
3607
- - Agent synthesizes search results
3608
- - Agent implements with proper colors, fonts, styles from search results
3609
- - Agent verifies with pre-delivery checklist
3610
-
3611
- **Special case - Flatsome UX Element skill:**
3612
- - Task: \`(projectType: wordpress, skill: ux-element)\`
3613
- - Agent reads: \`heraspec/skills/wordpress/ux-element/skill.md\`
3614
- - Agent MUST follow the **Wrapping Rule**: Use \`<span>\` with \`id="{{:: shortcode.$id }}"\`
3615
- - Agent uses templates from \`heraspec/skills/wordpress/ux-element/templates/\` (Controller, Shortcode, HTML Template, SVG Thumbnail)
3616
- - Agent ensures real-time preview support in AngularJS template.
3617
- - **Variable Translation**: Variables with underscores in PHP (e.g., \`bg_color\`) MUST be accessed via camelCase in AngularJS (e.g., \`shortcode.options.bgColor\`).
3618
-
3619
- **Special case - Plugin Check skill:**
3620
- - Task: \`(projectType: wordpress-plugin, skill: plugin-check)\`
3621
- - Install: \`heraspec skill add plugin-check --project-type wordpress-plugin\`
3622
- - Agent reads: \`heraspec/skills/wordpress-plugin/plugin-check/skill.md\`
3623
- - Agent runs WordPress Plugin Check (PCP) tool
3624
- - Agent fixes coding standard issues iteratively until all pass
3625
-
3626
- **Special case - Plugin Directory skill:**
3627
- - Task: \`(projectType: wordpress-plugin, skill: plugin-directory)\`
3628
- - Install: \`heraspec skill add plugin-directory --project-type wordpress-plugin\`
3629
- - Agent reads: \`heraspec/skills/wordpress-plugin/plugin-directory/skill.md\`
3630
- - Agent MUST review plugin against **18 WordPress.org Directory Guidelines**:
3631
- 1. GPL Compatibility
3632
- 2. Developer Responsibility
3633
- 3. Stable Version Availability
3634
- 4. Human Readable Code
3635
- 5. No Trialware
3636
- 6. Software as a Service
3637
- 7. User Tracking Consent
3638
- 8. No External Executable Code
3639
- 9. Legal and Ethical Conduct
3640
- 10. External Links and Credits
3641
- 11. Admin Dashboard Experience
3642
- 12. No Spam in Public Pages
3643
- 13. WordPress Default Libraries
3644
- 14. Commit Frequency
3645
- 15. Version Number Increment
3646
- 16. Complete Plugin Required
3647
- 17. Trademark and Copyright
3648
- 18. Directory Maintenance Rights
3649
- - Agent generates a **Compliance Report** with:
3650
- - \u2705 Passed items
3651
- - \u26A0\uFE0F Items needing review
3652
- - \u274C Violations with file paths and line numbers
3653
- - **CRITICAL**: Agent MUST present full report and **wait for user confirmation** before making changes
3654
- - Reference guideline numbers (e.g., "Guideline 7: User Tracking Consent")
3655
-
3656
- **Special case - Perfex Module Engineering skills:**
3657
- - Tasks: \`(projectType: perfex-module, skill: module-codebase)\` or \`(projectType: perfex-module, skill: code-quality-guidelines)\` or \`(skill: perfex-module)\`
3658
- - Install: \`heraspec skill add perfex-module\` or \`heraspec skill add module-codebase --project-type perfex-module\` or \`heraspec skill add code-quality-guidelines --project-type perfex-module\`
3659
- - Agent reads: \`heraspec/skills/perfex-module/skill.md\`, \`heraspec/skills/perfex-module/module-codebase/skill.md\`, and \`heraspec/skills/perfex-module/code-quality-guidelines/skill.md\`
3660
- - Agent MUST adhere to **10 Enterprise Code Quality & Clean Code Standards**:
3661
- 1. **Separation of Concerns (Zero Inline Code)**: 0 inline <script> or <style> blocks in views and documentation HTML.
3662
- 2. **Static Analysis Neutrality**: 0 occurrences of high-risk scanner triggers (inject, seeder, bypass, eval, unserialize).
3663
- 3. **Safe Stylesheet Loading**: Use editor.dom.loadCSS() for TinyMCE/iframes; never inject raw CSS string arrays.
3664
- 4. **Scoped Admin JS**: Enclose scripts in window.addEventListener('load') + strict IIFE.
3665
- 5. **Concurrency & Performance**: Always call session_write_close() at the start of read/search AJAX endpoints.
3666
- 6. **Clean Release Packaging**: Exclude package.json, webpack.config.js, tests/, scratch/, .git in deploy.ps1.
3667
- 7. **Defensive PHP Security & Guards**: 100% PHP files start with defined('BASEPATH') or exit('No direct script access allowed');. Use CI Query Builder with auto-escaping.
3668
- 8. **DOM XSS Prevention (CWE-79)**: Use .textContent, .innerText, or strict HTML escaping helper; purify rich text.
3669
- 9. **100% Multilingual Parity**: 100% labels and messages use _l('key') with zero missing keys across languages.
3670
- 10. **Zero Emojis**: 0 Unicode emojis across custom code, comments, views, documentation, and UI.
3671
- - Use templates from \`heraspec/skills/perfex-module/module-codebase/templates/\` (module-main.php, install.php, uninstall.php, controller-admin.php, controller-api.php, model-main.php, helper.php, deploy.ps1, webpack.config.js).
3672
-
3673
- **Special case - Content & Channel Development skills (projectType: content-channel):**
3674
- - Tasks: \`(projectType: content-channel, skill: content-strategy)\`, \`(skill: content-scaffolding)\`, \`(skill: content-scripting)\`, \`(skill: content-voice-adapter)\`, \`(skill: content-prompts)\`, \`(skill: content-compliance)\`, \`(skill: content-vault-sync)\`, or \`(skill: content-channel)\`
3675
- - Install: \`heraspec skill add content-channel\` or \`heraspec skill add <skill-name> --project-type content-channel\`
3676
- - Agent reads corresponding skill instructions in \`heraspec/skills/<skill-name>/skill.md\` or \`heraspec/skills/content-channel/<skill-name>/skill.md\`.
3677
- - Agent MUST adhere to **7 Core Content Production Standards**:
3678
- 1. **Golden Naming Rule**: ZERO \`[K\xEAnh]\`, \`[Channel]\`, or \`K\xEAnh:\` prefixes in channel/folder names. 100% pure brand names only.
3679
- 2. **MTxStudio 2-Level Tree Hierarchy**: Every channel must map to standard categories: \`_plan\` (\`type: "docs"\`), \`_posts\` (\`type: "article"\`), \`_prompts\` (\`type: "prompts"\`), \`_music\` (\`type: "music"\`), and optional \`_affiliate\` (\`type: "docs"\`).
3680
- 3. **Strict TTS Acoustic Rules (Natural Flow)**:
3681
- - Short sentences: 12 - 20 words max per sentence (never exceed 25 words or 120 chars).
3682
- - Comma clauses: 8 - 12 words max.
3683
- - Repetition Bug Prevention: Never place 2 reduplicative words (t\u1EEB l\xE1y) adjacently; always separate with a natural comma \`,\`.
3684
- - Clean text: Zero artificial bracket tags; rely entirely on natural punctuation (\`.\`, \`,\`, \`...\`, \`!\`) and sentence rhythm for voice pacing.
3685
- 4. **Strict Poetry & Verse Formatting**: Never use \`join(' ')\` or combine verses into a single line. EVERY verse line MUST preserve its \`\\n\` newline.
3686
- 5. **Mandatory 3-Position Disclaimer (Decree 15/2020/ND-CP)**: For horror, health, psychological healing, and finance niches, disclaimers are mandatory at: (1) Intro Warning Card 0:00-0:04, (2) Caption Footer / Pinned Comment, (3) Spoken Narration.
3687
- 6. **Safe Vault Sync (Zero SQLite Tampering)**: NEVER write directly to \`mtxstudio.db\`. All channel exports must go through \`Facebook/export_vault_json.py\` to generate sanitized JSON bundles (\`mtxstudio_vault_import.json\`, \`all_channels_bundle.json\`) with UTF-8 encoding and zero en-dash/em-dash characters.
3688
- 7. **Channel Voice Adaptation (Transmutation)**: When repurposing raw texts, always use \`content-voice-adapter\` to de-bias off-brand elements and reframe the message through the designated channel's core philosophy and natural voice style.
3689
-
3690
- - Follow tasks.md
3691
- - Mark tasks completed: \`- [x]\`
3692
-
3693
- ### Step 5 \u2014 Archive
3694
- - Run: \`heraspec archive <slug> --yes\`
3695
- - This merges delta specs into source specs
3696
- - Moves change folder to archives
3697
-
3698
- #### Handling Parallel Merge Conflicts
3699
- If \`heraspec archive\` throws a **Parallel Merge Conflict** error:
3700
- 1. It means someone else modified the base requirement in the source spec while you were working.
3701
- 2. **DO NOT PANIC** and **DO NOT OVERWRITE** manually.
3702
- 3. Run: \`heraspec sync <slug>\`
3703
- 4. The system will automatically update your fingerprint to match the new source spec and warn you.
3704
- 5. Review your delta spec again. Make sure your \`MODIFIED/REMOVED\` requirements still make sense given the new source.
3705
- 6. Once verified, run \`heraspec archive <slug> --yes\` again.
3706
-
3707
- ## Spec Format
3708
-
3709
- Specs must include:
3710
- - \`## Meta\` section with project type, domain, stack
3711
- - \`## Purpose\`
3712
- - \`## Requirements\` with scenarios
3713
-
3714
- ## Delta Spec Format
3715
-
3716
- Delta specs use:
3717
- - \`## ADDED Requirements\`
3718
- - \`## MODIFIED Requirements\`
3719
- - \`## REMOVED Requirements\`
3720
-
3721
- ## Tasks Format
3722
-
3723
- Tasks grouped by project type and skill:
3724
- \`\`\`
3725
- ## 1. WordPress plugin \u2013 admin settings page (projectType: wordpress-plugin, skill: admin-settings-page)
3726
- - [ ] Task description
3727
- \`\`\`
3728
-
3729
- ## Skills System
3730
-
3731
- **CRITICAL: Mandatory Prerequisite Check**
3732
-
3733
- 1. **Stop & Verify**: If you are asked to implement a task requiring a skill (e.g., "Generate documentation...", "Create UI/UX...", etc.), you MUST first check if the skill folder exists in \`heraspec/skills/\`.
3734
- 2. **Missing Skill = AUTO-INSTALL OR STOP**: If the skill folder does NOT exist:
3735
- - **Option A (Preferred)**: If you can run commands, execute \`heraspec skill add <skill-name>\` immediately.
3736
- - **Option B (Fallback)**: If you cannot run commands, **STOP** and ask the user to run it.
3737
- > "Tip: Add the 'documents' skill for premium HTML & Landing Page support:
3738
- > heraspec skill add documents"
3739
- - **DO NOT** create a task plan or attempt manual generation without the skill language.
3740
- 3. **Execute After Install**: Only after the skill folder is created (or installed), read the \`skill.md\` and proceed with the task.
3741
- 4. **Ignore Vietnamese Skill Files**: You MUST only read the English \`skill.md\` file inside the skill folder. Completely ignore all \`*.vi.md\` files (e.g., \`skill.vi.md\`), as they are strictly for reference purposes by human developers.
3742
-
3743
- **Example prompt for Documents skill:**
3744
- If you need to generate multi-format documentation, use this prompt:
3745
- > "Generate documentation with skill documents for [project-name]. Include:
3746
- > - Concise overview (documentations/documentation.txt)
3747
- > - Technical Markdown (documentations/documentation.md)
3748
- > - Interactive HTML (documentations/documentation.html)
3749
- > - Premium Documentation Landing Page (documentations/documentation-landing-page.html)
3750
- > - CRITICAL: Save all files in the /documentations directory (create it if missing)."
3751
-
3752
- **Example prompts for Content Channel Development (content-channel skills):**
3753
- - **Channel Strategy (\`content-strategy\`)**:
3754
- > "S\u1EED d\u1EE5ng skill content-strategy \u0111\u1EC3 l\u1EADp B\u1EA3n K\u1EBF Ho\u1EA1ch 30 Ng\xE0y (plan.md) cho k\xEAnh m\u1EDBi:
3755
- > - T\xEAn k\xEAnh: [T\xEAn thu\u1EA7n t\xFAy, v\xED d\u1EE5: G\xF3c An Tr\xFA]
3756
- > - Ng\xE1ch: [V\xED d\u1EE5: Thi\u1EC1n \u0111\u1ECBnh & L\u1ED1i s\u1ED1ng t\u1ED1i gi\u1EA3n]
3757
- > - Kh\xE1n gi\u1EA3 m\u1EE5c ti\xEAu: [V\xED d\u1EE5: 25 - 40 tu\u1ED5i, nh\xE2n vi\xEAn v\u0103n ph\xF2ng stress]
3758
- > - Y\xEAu c\u1EA7u: X\xE2y d\u1EF1ng 5 tr\u1EE5 c\u1ED9t n\u1ED9i dung, l\u1ED9 tr\xECnh Cold Start 14 ng\xE0y (70% Reels / 30% In-stream), khung gi\u1EDD v\xE0ng v\xE0 b\u1EA3ng ph\xE2n b\u1ED5 30 b\xE0i vi\u1EBFt chi ti\u1EBFt."
3759
-
3760
- - **Channel Scaffolding (\`content-scaffolding\`)**:
3761
- > "S\u1EED d\u1EE5ng skill content-scaffolding \u0111\u1EC3 kh\u1EDFi t\u1EA1o c\u1EA5u tr\xFAc th\u01B0 m\u1EE5c k\xEAnh m\u1EDBi:
3762
- > - T\xEAn k\xEAnh: [V\xED d\u1EE5: Th\xE2n An T\xE2m L\u1EA1c] | Folder: [Than-An-Tam-Lac]
3763
- > - Slogan: [V\xED d\u1EE5: Th\xE2n c\xF3 an, t\xE2m m\u1EDBi l\u1EA1c] | Icon Lucide: [Heart] | M\xE0u: [#10b981]
3764
- > - Y\xEAu c\u1EA7u: Tu\xE2n th\u1EE7 quy t\u1EAFc c\u1EA5m ti\u1EC1n t\u1ED1 [K\xEAnh], t\u1EA1o posts/README.md v\xE0 \u0111\u0103ng k\xFD v\xE0o CHANNELS_CONFIG trong export_vault_json.py."
3765
-
3766
- - **Raw Text Transmutation (\`content-voice-adapter\`)**:
3767
- > "S\u1EED d\u1EE5ng skill content-voice-adapter \u0111\u1EC3 chuy\u1EC3n th\u1EC3 \u0111o\u1EA1n v\u0103n b\u1EA3n th\xF4 d\u01B0\u1EDBi \u0111\xE2y th\xE0nh K\u1ECBch b\u1EA3n Video chu\u1EA9n cho k\xEAnh [T\xEAn K\xEAnh] (Th\u1EC3 lo\u1EA1i: [Ch\u1EEFa l\xE0nh / Truy\u1EC7n ma / D\u01B0\u1EE1ng sinh / Chi\xEAm nghi\u1EC7m...]):
3768
- > [D\xC1N \u0110O\u1EA0N V\u0102N B\u1EA2N TH\xD4 V\xC0O \u0110\xC2Y]
3769
- > Y\xEAu c\u1EA7u qua 4 b\u01B0\u1EDBc: (1) L\u1ECDc l\u1EC7ch tone theo ma tr\u1EADn th\u1EC3 lo\u1EA1i (ch\u1EEFa l\xE0nh: l\u1ECDc m\xEA t\xEDn/\u0111\u1ED5 l\u1ED7i; truy\u1EC7n ma: l\u1ECDc m\xE1u me/vi ph\u1EA1m N\u0110 15 t\xEAn ng\u01B0\u1EDDi th\u1EADt/c\u1EE3t nh\u1EA3; d\u01B0\u1EE1ng sinh: l\u1ECDc ph\u1EA3n khoa h\u1ECDc/th\u1EA7n th\xE1nh h\xF3a; chi\xEAm nghi\u1EC7m: l\u1ECDc than th\u1EDF n\u1EA1n nh\xE2n), (2) T\xE1i c\u1EA5u tr\xFAc theo DNA tri\u1EBFt l\xFD v\xE0 \u0111\u1EA1i t\u1EEB nh\xE2n x\u01B0ng c\u1EE7a k\xEAnh, (3) T\u1ED1i \u01B0u \xE2m h\u1ECDc TTS 12-20 t\u1EEB/c\xE2u s\u1EA1ch th\u1EBB ngo\u1EB7c vu\xF4ng, (4) \u0110\xF3ng g\xF3i 6 ph\u1EA7n chu\u1EA9n MTxStudio k\xE8m Storyboard prompt, Caption v\xE0 Disclaimer ph\xE1p l\xFD ph\xF9 h\u1EE3p th\u1EC3 lo\u1EA1i."
3770
-
3771
- - **Scriptwriting from Scratch (\`content-scripting\`)**:
3772
- > "S\u1EED d\u1EE5ng skill content-scripting \u0111\u1EC3 vi\u1EBFt K\u1ECBch b\u1EA3n T\u1EADp [S\u1ED1 t\u1EADp]: '[Ti\xEAu \u0111\u1EC1]' cho k\xEAnh [T\xEAn K\xEAnh]:
3773
- > - Tr\u1EE5 c\u1ED9t: [T\xEAn tr\u1EE5 c\u1ED9t n\u1ED9i dung] | \u0110\u1ECBnh d\u1EA1ng: [Video In-stream 16:9 ho\u1EB7c Reels 9:16]
3774
- > - Y\xEAu c\u1EA7u \xE2m h\u1ECDc TTS: C\xE2u ng\u1EAFn 12-20 t\u1EEB, ng\u1EAFt nh\u1ECBp d\u1EA5u ph\u1EA9y r\xF5 r\xE0ng, kh\xF4ng \u0111i\u1EC7p \xE2m t\u1EEB l\xE1y, TUY\u1EC6T \u0110\u1ED0I KH\xD4NG ch\xE8n th\u1EBB ngo\u1EB7c vu\xF4ng ([l\u1EA5y h\u01A1i], [th\u1EDF d\xE0i]), b\u1EA3o to\xE0n th\u01A1 ca m\u1ED7i c\xE2u 1 d\xF2ng (\\n), xu\u1EA5t \u0111\u1EA7y \u0111\u1EE7 6 ph\u1EA7n k\xE8m Storyboard v\xE0 Caption Facebook."
3775
-
3776
- - **AI Visual & Suno BGM Prompts (\`content-prompts\`)**:
3777
- > "S\u1EED d\u1EE5ng skill content-prompts \u0111\u1EC3 t\u1EA1o b\u1ED9 Prompt Visual v\xE0 \xC2m nh\u1EA1c cho k\xEAnh [T\xEAn K\xEAnh]:
3778
- > - C\u1EA7n t\u1EA1o: Prompt Avatar 1:1, Cover 16:9, B\u1EA3ng 5 Prompts Storyboard b\xE0i vi\u1EBFt '[T\xEAn b\xE0i vi\u1EBFt]', v\xE0 Prompt Suno AI BGM kh\xF4ng l\u1EDDi."
3779
-
3780
- - **Legal Compliance & Disclaimer (\`content-compliance\`)**:
3781
- > "S\u1EED d\u1EE5ng skill content-compliance \u0111\u1EC3 ki\u1EC3m duy\u1EC7t k\u1ECBch b\u1EA3n v\xE0 sinh Disclaimer cho video thu\u1ED9c th\u1EC3 lo\u1EA1i [Truy\u1EC7n Ma / D\u01B0\u1EE1ng Sinh / T\xE2m L\xFD / T\xE0i Ch\xEDnh]:
3782
- > - Cung c\u1EA5p Disclaimer chu\u1EA9n ph\xE1p l\xFD (Ngh\u1ECB \u0111\u1ECBnh 15/2020/N\u0110-CP) \u0111\u1EB7t \u1EDF ch\xE2n Caption.
3783
- > - Cung c\u1EA5p Prompt m\xE0n h\xECnh c\u1EA3nh b\xE1o Intro Warning Card (0:00 - 0:04, t\u1EF7 l\u1EC7 16:9)."
3784
-
3785
- - **Vault Synchronization (\`content-vault-sync\`)**:
3786
- > "S\u1EED d\u1EE5ng skill content-vault-sync \u0111\u1EC3 \u0111\u1ED3ng b\u1ED9 d\u1EEF li\u1EC7u: Ki\u1EC3m tra t\xEDnh to\xE0n v\u1EB9n c\xE1c k\xEAnh trong Facebook/, ch\u1EA1y export_vault_json.py \u0111\u1EC3 t\xE1i xu\u1EA5t mtxstudio_vault_import.json v\xE0 all_channels_bundle.json, b\xE1o c\xE1o s\u1ED1 l\u01B0\u1EE3ng k\xEAnh, danh m\u1EE5c v\xE0 k\u1ECBch b\u1EA3n \u0111\xE3 \u0111\xF3ng g\xF3i th\xE0nh c\xF4ng."
3787
-
3788
- **Dynamic Documentation Generation**:
3789
- When generating documentation, do NOT simply fill a template. The Agent MUST:
3790
- 1. **Create** the \`/documentations\` directory if it does not exist.
3791
- 2. **Design** a custom layout and content structure suitable for the project type.
3792
- 3. **Synchronize** with the \`ui-ux\` skill for premium visual design (colors, typography, animations).
3793
- 4. **Scan All Specs**: If project-wide, read \`heraspec/project.md\` and all files in \`heraspec/specs/\` to synthesize the content.
3794
-
3795
- ### Skill Discovery & Usage
3796
-
3797
- - List all skills: Check \`heraspec/skills/\` directory
3798
- - Project-specific skills: \`heraspec/skills/<project-type>/\`
3799
- - Cross-cutting skills: \`heraspec/skills/<skill-name>/\` (root level)
3800
- - **Consistency**: Follow the step-by-step process in the skill's \`skill.md\`.
3801
-
3802
- ### When Change Has Multiple Skills
3803
-
3804
- **Important**: Each task group uses ONE skill. When working on a task group, agent MUST use that skill's skill.md.
3805
-
3806
- Example with multiple skills in one change:
3807
- \`\`\`
3808
- ## 1. WordPress module \u2013 Feature (skill: admin-settings-page)
3809
- - [ ] Task 1.1 Create module structure
3810
- - [ ] Task 1.2 Configure registration
3811
-
3812
- ## 2. UI/UX \u2013 Admin Interface (skill: ui-ux)
3813
- - [ ] Task 2.1 Design color palette
3814
- - [ ] Task 2.2 Create component styles
3815
-
3816
- ## 3. Documents \u2013 User Guide (skill: documents)
3817
- - [ ] Task 3.1 Write technical docs
3818
- \`\`\`
3819
-
3820
- **Key rule**: Switch skill.md when switching task groups!
3821
-
3822
- ## Proactive Memory-Aware Development
3823
-
3824
- If \`heraspec/skills/project-memory/\` exists, the agent MUST proactively use memory to maintain project context. DO NOT wait for the user to prompt you to use memory.
3825
-
3826
- ### CRITICAL RULES FOR AUTOMATIC MEMORY USAGE
3827
- 1. **Always Check Context First**: At the beginning of a complex task or when encountering an unfamiliar codebase area, you MUST autonomously run \`heraspec memory context\` or \`heraspec memory search "keywords"\` BEFORE writing any code.
3828
- 2. **Auto-Log via Archive**: You DO NOT need to run \`heraspec memory log\` manually. Every time you successfully implement a feature and run \`heraspec archive <change-name>\`, the system will automatically read your proposal and log the memory observation under the hood. Just use \`heraspec archive\` as normal!
3829
- 3. **Session Summary**: (Optional) When wrapping up a large session, you can run \`heraspec memory summarize --request "..." --completed "..."\` to compress knowledge, though \`archive\` already auto-logs completed features.
3830
-
3831
- ### When to SKIP Memory
3832
- - Simple bug fixes, typo corrections, formatting changes
3833
- - Trivial tasks that take < 5 minutes
3834
- - When doing what the agent's built-in context already covers
3835
-
3836
- ### Smart Code Exploration
3837
- If \`heraspec/skills/smart-explore/\` exists, prefer token-efficient exploration:
3838
- - \`heraspec explore outline <file>\` \u2192 View structure (~1K tokens vs ~12K full file)
3839
- - \`heraspec explore search "<query>" <path>\` \u2192 Find symbols across codebase
3840
- - \`heraspec explore unfold <file> <symbol>\` \u2192 Read just one function
3841
- `;
3842
- }
3843
- static getSkillsSection() {
3844
- return `## Skills System
3845
-
3846
- **CRITICAL: Mandatory Prerequisite Check**
3847
-
3848
- 1. **Stop & Verify**: If you are asked to implement a task requiring a skill (e.g., "Generate documentation...", "Create UI/UX...", etc.), you MUST first check if the skill folder exists in \`heraspec/skills/\`.
3849
- 2. **Missing Skill = AUTO-INSTALL OR STOP**: If the skill folder does NOT exist:
3850
- - **Option A (Preferred)**: If you can run commands, execute \`heraspec skill add <skill-name>\` immediately.
3851
- - **Option B (Fallback)**: If you cannot run commands, **STOP** and ask the user to run it.
3852
- > "Tip: Add the 'documents' skill for premium HTML & Landing Page support:
3853
- > heraspec skill add documents"
3854
- - **DO NOT** create a task plan or attempt manual generation without the skill language.
3855
- 3. **Execute After Install**: Only after the skill folder is created (or installed), read the \`skill.md\` and proceed with the task.
3856
- 4. **Ignore Vietnamese Skill Files**: You MUST only read the English \`skill.md\` file inside the skill folder. Completely ignore all \`*.vi.md\` files (e.g., \`skill.vi.md\`), as they are strictly for reference purposes by human developers.
3857
-
3858
- **Example prompt for Documents skill:**
3859
- If you need to generate multi-format documentation, use this prompt:
3860
- > "Generate documentation with skill documents for [project-name]. Include:
3861
- > - Concise overview (documentations/documentation.txt)
3862
- > - Technical Markdown (documentations/documentation.md)
3863
- > - Interactive HTML (documentations/documentation.html)
3864
- > - Premium Documentation Landing Page (documentations/documentation-landing-page.html)
3865
- > - CRITICAL: Save all files in the /documentations directory (create it if missing)."
3866
-
3867
- **Dynamic Documentation Generation**:
3868
- When generating documentation, do NOT simply fill a template. The Agent MUST:
3869
- 1. **Create** the \`/documentations\` directory if it does not exist.
3870
- 2. **Design** a custom layout and content structure suitable for the project type.
3871
- 3. **Synchronize** with the \`ui-ux\` skill for premium visual design (colors, typography, animations).
3872
- 4. **Scan All Specs**: If project-wide, read \`heraspec/project.md\` and all files in \`heraspec/specs/\` to synthesize the content.
3873
-
3874
- ### Skill Discovery & Usage
3875
-
3876
- - List all skills: Check \`heraspec/skills/\` directory
3877
- - Project-specific skills: \`heraspec/skills/<project-type>/\`
3878
- - Cross-cutting skills: \`heraspec/skills/<skill-name>/\` (root level)
3879
- - **Consistency**: Follow the step-by-step process in the skill's \`skill.md\`.
3880
-
3881
- ### When Change Has Multiple Skills
3882
-
3883
- **Important**: Each task group uses ONE skill. When working on a task group, agent MUST use that skill's skill.md.
3884
-
3885
- Example with multiple skills in one change:
3886
- \`\`\`
3887
- ## 1. WordPress module \u2013 Feature (skill: admin-settings-page)
3888
- - [ ] Task 1.1 Create module structure
3889
- - [ ] Task 1.2 Configure registration
3890
-
3891
- ## 2. UI/UX \u2013 Admin Interface (skill: ui-ux)
3892
- - [ ] Task 2.1 Design color palette
3893
- - [ ] Task 2.2 Create component styles
4871
+ "laravel-package",
4872
+ "node-service",
4873
+ "generic-webapp",
4874
+ "backend-api",
4875
+ "frontend-app",
4876
+ "multi-stack",
4877
+ "content-channel"
4878
+ ]);
4879
+ var SpecMetaSchema = z.object({
4880
+ projectType: z.union([
4881
+ ProjectTypeSchema,
4882
+ z.array(ProjectTypeSchema)
4883
+ ]).optional(),
4884
+ domain: z.string().optional(),
4885
+ stack: z.union([
4886
+ z.string(),
4887
+ z.array(z.string())
4888
+ ]).optional()
4889
+ }).optional();
4890
+ var ScenarioSchema = z.object({
4891
+ name: z.string(),
4892
+ steps: z.array(z.string()).min(1)
4893
+ });
4894
+ var RequirementSchema = z.object({
4895
+ id: z.string().optional(),
4896
+ name: z.string(),
4897
+ description: z.string(),
4898
+ scenarios: z.array(ScenarioSchema).optional(),
4899
+ constraints: z.array(z.string()).optional()
4900
+ });
3894
4901
 
3895
- ## 3. Documents \u2013 User Guide (skill: documents)
3896
- - [ ] Task 3.1 Write technical docs
3897
- \`\`\`
4902
+ // src/core/schemas/spec.schema.ts
4903
+ import { z as z2 } from "zod";
4904
+ var SpecSchema = z2.object({
4905
+ name: z2.string().min(1),
4906
+ meta: SpecMetaSchema,
4907
+ overview: z2.string().min(1),
4908
+ requirements: z2.array(RequirementSchema).min(1),
4909
+ metadata: z2.object({
4910
+ version: z2.string().default("1.0.0"),
4911
+ format: z2.literal("heraspec"),
4912
+ sourcePath: z2.string().optional()
4913
+ }).optional()
4914
+ });
3898
4915
 
3899
- **Key rule**: Switch skill.md when switching task groups!
3900
- `;
3901
- }
3902
- static getConfigTemplate() {
3903
- return `projectType: generic-webapp
3904
- projectName: "HeraSpec Project"
3905
- description: "A new project using HeraSpec"
3906
- skills: []
3907
- `;
3908
- }
3909
- };
4916
+ // src/core/schemas/change.schema.ts
4917
+ import { z as z3 } from "zod";
4918
+ var DeltaTypeSchema = z3.enum(["ADDED", "MODIFIED", "REMOVED"]);
4919
+ var DeltaRequirementSchema = z3.object({
4920
+ type: DeltaTypeSchema,
4921
+ requirement: z3.object({
4922
+ id: z3.string().optional(),
4923
+ name: z3.string(),
4924
+ description: z3.string(),
4925
+ scenarios: z3.array(z3.object({
4926
+ name: z3.string(),
4927
+ steps: z3.array(z3.string())
4928
+ })).optional(),
4929
+ constraints: z3.array(z3.string()).optional()
4930
+ })
4931
+ });
4932
+ var ChangeSchema = z3.object({
4933
+ name: z3.string(),
4934
+ proposal: z3.string().min(1),
4935
+ tasks: z3.array(z3.string()).optional(),
4936
+ design: z3.string().optional()
4937
+ });
3910
4938
 
3911
4939
  // src/core/init.ts
4940
+ init_file_system();
4941
+ init_templates();
3912
4942
  init_config();
3913
4943
  init_skills_template_map();
3914
4944
  init_memory();
4945
+ init_ide_adapter();
4946
+ init_agents_composer();
4947
+ import ora3 from "ora";
4948
+ import chalk3 from "chalk";
4949
+ import path10 from "path";
3915
4950
  import { fileURLToPath as fileURLToPath2 } from "url";
3916
4951
  import { dirname as dirname2, join as join2 } from "path";
3917
4952
  import { createRequire as createRequire2 } from "module";
3918
4953
  var require3 = createRequire2(import.meta.url);
3919
4954
  var __filename2 = fileURLToPath2(import.meta.url);
3920
4955
  var __dirname2 = dirname2(__filename2);
4956
+ function getCliPackageVersion() {
4957
+ for (const rel of ["../package.json", "../../package.json"]) {
4958
+ try {
4959
+ const pkg = require3(rel);
4960
+ if (pkg?.version) return String(pkg.version);
4961
+ } catch {
4962
+ }
4963
+ }
4964
+ return "0.1.18";
4965
+ }
3921
4966
  var InitCommand = class {
3922
- async execute(targetPath = ".") {
3923
- const resolvedPath = path8.resolve(targetPath);
3924
- const heraspecPath = path8.join(resolvedPath, HERASPEC_DIR_NAME);
4967
+ async execute(targetPath = ".", options = {}) {
4968
+ const resolvedPath = path10.resolve(targetPath);
4969
+ const heraspecPath = path10.join(resolvedPath, HERASPEC_DIR_NAME);
4970
+ const ideOption = options.ide || "auto";
3925
4971
  const alreadyInitialized = await FileSystemUtils.fileExists(
3926
- path8.join(heraspecPath, HERASPEC_MARKERS.PROJECT_MD)
4972
+ path10.join(heraspecPath, HERASPEC_MARKERS.PROJECT_MD)
3927
4973
  );
4974
+ if (options.dryRun) {
4975
+ await this.runDryRunPreview(resolvedPath, heraspecPath, alreadyInitialized, {
4976
+ ...options,
4977
+ ide: ideOption
4978
+ });
4979
+ return;
4980
+ }
3928
4981
  const spinner = ora3({
3929
4982
  text: alreadyInitialized ? "Updating HeraSpec..." : "Initializing HeraSpec...",
3930
4983
  color: "blue"
3931
4984
  }).start();
3932
4985
  try {
3933
4986
  await FileSystemUtils.createDirectory(heraspecPath);
3934
- await FileSystemUtils.createDirectory(path8.join(heraspecPath, SPECS_DIR_NAME));
3935
- await FileSystemUtils.createDirectory(path8.join(heraspecPath, CHANGES_DIR_NAME));
3936
- await FileSystemUtils.createDirectory(path8.join(heraspecPath, ARCHIVES_DIR_NAME));
3937
- await FileSystemUtils.createDirectory(path8.join(heraspecPath, SKILLS_DIR_NAME));
3938
- await FileSystemUtils.createDirectory(path8.join(heraspecPath, KNOWLEDGE_DIR_NAME));
3939
- const skillsReadmePath = path8.join(heraspecPath, SKILLS_DIR_NAME, "README.md");
4987
+ await FileSystemUtils.createDirectory(path10.join(heraspecPath, SPECS_DIR_NAME));
4988
+ await FileSystemUtils.createDirectory(path10.join(heraspecPath, CHANGES_DIR_NAME));
4989
+ await FileSystemUtils.createDirectory(path10.join(heraspecPath, ARCHIVES_DIR_NAME));
4990
+ await FileSystemUtils.createDirectory(path10.join(heraspecPath, SKILLS_DIR_NAME));
4991
+ await FileSystemUtils.createDirectory(path10.join(heraspecPath, KNOWLEDGE_DIR_NAME));
4992
+ const skillsReadmePath = path10.join(heraspecPath, SKILLS_DIR_NAME, "README.md");
3940
4993
  if (!await FileSystemUtils.fileExists(skillsReadmePath)) {
3941
4994
  const skillsReadme = await this.getSkillsReadmeTemplate();
3942
4995
  await FileSystemUtils.writeFile(skillsReadmePath, skillsReadme);
3943
4996
  }
3944
- const uiuxGuidePath = path8.join(heraspecPath, SKILLS_DIR_NAME, "UI_UX_SKILL_QUICK_REFERENCE.md");
4997
+ const uiuxGuidePath = path10.join(heraspecPath, SKILLS_DIR_NAME, "UI_UX_SKILL_QUICK_REFERENCE.md");
3945
4998
  if (!await FileSystemUtils.fileExists(uiuxGuidePath)) {
3946
4999
  const uiuxGuide = await this.getUIUXQuickReference();
3947
5000
  await FileSystemUtils.writeFile(uiuxGuidePath, uiuxGuide);
3948
5001
  }
3949
5002
  await this.deployKnowledge(heraspecPath);
3950
5003
  await this.createTemplateFiles(heraspecPath, alreadyInitialized);
3951
- const legacyAgentsPath = path8.join(resolvedPath, "AGENTS.md");
3952
- const newAgentsPath = path8.join(resolvedPath, HERASPEC_MARKERS.AGENTS_MD);
3953
- if (await FileSystemUtils.fileExists(legacyAgentsPath) && !await FileSystemUtils.fileExists(newAgentsPath)) {
3954
- await FileSystemUtils.moveFile(legacyAgentsPath, newAgentsPath);
3955
- }
3956
- await this.updateAgentsFile(newAgentsPath, alreadyInitialized);
3957
5004
  if (alreadyInitialized) {
3958
5005
  await this.updateInstalledSkills(heraspecPath);
3959
5006
  }
3960
5007
  await this.checkAndBootstrapMemory(heraspecPath, resolvedPath, spinner);
3961
5008
  await this.checkAndBootstrapContentChannel(heraspecPath, resolvedPath, spinner);
3962
- await this.updateRelatedMarkdownFiles(resolvedPath);
5009
+ const existingState = await readHeraspecState(heraspecPath);
5010
+ const composePlan = await buildAgentsComposePlan({
5011
+ projectPath: resolvedPath,
5012
+ heraspecPath,
5013
+ ideOption,
5014
+ force: options.force
5015
+ });
3963
5016
  spinner.stop();
5017
+ if (composePlan.backupPath && await FileSystemUtils.fileExists(composePlan.agentsPath)) {
5018
+ const originalAgents = await FileSystemUtils.readFile(composePlan.agentsPath);
5019
+ await FileSystemUtils.writeFile(composePlan.backupPath, originalAgents);
5020
+ console.log(
5021
+ chalk3.yellow(` ! Created backup: ${path10.basename(composePlan.backupPath)}`)
5022
+ );
5023
+ }
5024
+ if (composePlan.nextCustomContent !== null) {
5025
+ await FileSystemUtils.writeFile(composePlan.customAgentsPath, composePlan.nextCustomContent);
5026
+ if (composePlan.customAction === "create-from-migration") {
5027
+ console.log(
5028
+ chalk3.green(
5029
+ ` \u2713 Migrated legacy custom rules to ${HERASPEC_MARKERS.AGENTS_CUSTOM_MD} (sections: ${composePlan.extraction.customSections.length}, inline additions: ${composePlan.extraction.migratedAdditions.length})`
5030
+ )
5031
+ );
5032
+ } else if (composePlan.customAction === "append-migration") {
5033
+ console.log(
5034
+ chalk3.green(
5035
+ ` \u2713 Appended inline AGENTS.heraspec.md edits safely into ${HERASPEC_MARKERS.AGENTS_CUSTOM_MD}`
5036
+ )
5037
+ );
5038
+ } else if (composePlan.customAction === "create-starter") {
5039
+ console.log(
5040
+ chalk3.gray(` \u2713 Created project-owned custom rules file: ${HERASPEC_MARKERS.AGENTS_CUSTOM_MD}`)
5041
+ );
5042
+ }
5043
+ } else {
5044
+ console.log(
5045
+ chalk3.gray(` \u2713 Preserved existing ${HERASPEC_MARKERS.AGENTS_CUSTOM_MD} untouched`)
5046
+ );
5047
+ }
5048
+ if (composePlan.agentsAction !== "up-to-date") {
5049
+ await FileSystemUtils.writeFile(composePlan.agentsPath, composePlan.renderedAgents);
5050
+ }
5051
+ const ideSync = await IdeAdapterManager.syncAdaptersAndSkills({
5052
+ projectPath: resolvedPath,
5053
+ ideOption,
5054
+ hasCustomFile: await FileSystemUtils.fileExists(composePlan.customAgentsPath),
5055
+ checkOnly: false,
5056
+ dryRun: false,
5057
+ force: options.force,
5058
+ preserveModifiedSkillTargets: true,
5059
+ recordedMirrors: existingState?.mirroredSkills
5060
+ });
5061
+ for (const report of ideSync.reports) {
5062
+ if (report.status === "created" || report.status === "updated") {
5063
+ console.log(
5064
+ chalk3.cyan(` \u2713 Synced ${report.kind}: ${report.relativePath} (${report.status})`)
5065
+ );
5066
+ } else if (report.status === "preserved") {
5067
+ console.log(
5068
+ chalk3.yellow(` ! Preserved modified IDE skill: ${report.relativePath} (${report.detail})`)
5069
+ );
5070
+ }
5071
+ }
5072
+ await writeHeraspecState(heraspecPath, {
5073
+ schemaVersion: 1,
5074
+ cliVersion: getCliPackageVersion(),
5075
+ updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
5076
+ agentsHeraspecSha256: composePlan.renderedSha256,
5077
+ mirroredSkills: ideSync.updatedMirrors
5078
+ });
5079
+ await this.updateRelatedMarkdownFiles(resolvedPath);
3964
5080
  try {
3965
5081
  const memoryCommand = new MemoryCommand();
3966
5082
  await memoryCommand.index({ depth: "3", yes: true }, resolvedPath);
3967
5083
  await memoryCommand.context({ output: "file" }, resolvedPath);
3968
- } catch (err) {
5084
+ } catch {
3969
5085
  }
3970
5086
  console.log();
3971
5087
  console.log(
3972
- chalk2.green(
5088
+ chalk3.green(
3973
5089
  alreadyInitialized ? "\u2714 HeraSpec updated successfully" : "\u2714 HeraSpec initialized successfully"
3974
5090
  )
3975
5091
  );
3976
5092
  console.log();
3977
- console.log(chalk2.cyan("Next steps:"));
5093
+ console.log(chalk3.cyan("Next steps:"));
3978
5094
  console.log(
3979
- chalk2.gray("1. Review and update heraspec/project.md with your project details")
5095
+ chalk3.gray(`1. Put project-specific engineering rules in ${HERASPEC_MARKERS.AGENTS_CUSTOM_MD}`)
3980
5096
  );
3981
5097
  console.log(
3982
- chalk2.gray('2. Create your first change: "Create a HeraSpec change to..."')
5098
+ chalk3.gray("2. Review heraspec/project.md and heraspec/config.yaml for project metadata")
3983
5099
  );
3984
5100
  console.log(
3985
- chalk2.gray("3. List changes: heraspec list")
5101
+ chalk3.gray('3. Run "heraspec ide sync --check" anytime to verify IDE adapter & skill parity')
3986
5102
  );
3987
5103
  } catch (error) {
3988
- spinner.fail(chalk2.red(`Error: ${error.message}`));
5104
+ spinner.fail(chalk3.red(`Error: ${error.message}`));
3989
5105
  throw error;
3990
5106
  }
3991
5107
  }
5108
+ async runDryRunPreview(resolvedPath, heraspecPath, alreadyInitialized, options) {
5109
+ const existingState = await readHeraspecState(heraspecPath);
5110
+ const composePlan = await buildAgentsComposePlan({
5111
+ projectPath: resolvedPath,
5112
+ heraspecPath,
5113
+ ideOption: options.ide || "auto",
5114
+ force: options.force
5115
+ });
5116
+ const willHaveCustom = composePlan.nextCustomContent !== null || await FileSystemUtils.fileExists(composePlan.customAgentsPath);
5117
+ const ideSync = await IdeAdapterManager.syncAdaptersAndSkills({
5118
+ projectPath: resolvedPath,
5119
+ ideOption: options.ide || "auto",
5120
+ hasCustomFile: willHaveCustom,
5121
+ checkOnly: false,
5122
+ dryRun: true,
5123
+ force: options.force,
5124
+ preserveModifiedSkillTargets: true,
5125
+ recordedMirrors: existingState?.mirroredSkills
5126
+ });
5127
+ console.log(chalk3.cyan.bold("\n[Dry-Run] HeraSpec Init Preview (no files written)\n"));
5128
+ console.log(` Target: ${resolvedPath}`);
5129
+ console.log(` Mode: ${alreadyInitialized ? "Re-init / Safe Upgrade" : "Fresh Init"}`);
5130
+ console.log(` AGENTS.heraspec.md: ${composePlan.agentsAction}`);
5131
+ if (composePlan.backupPath) {
5132
+ console.log(` Backup Planned: ${path10.basename(composePlan.backupPath)}`);
5133
+ }
5134
+ console.log(` AGENTS.custom.md: ${composePlan.customAction}`);
5135
+ if (composePlan.extraction.hasCustomContent) {
5136
+ console.log(
5137
+ chalk3.yellow(
5138
+ ` Extracted Legacy Rules: ${composePlan.extraction.customSections.length} custom H2 section(s), ${composePlan.extraction.migratedAdditions.length} inline customization group(s)`
5139
+ )
5140
+ );
5141
+ }
5142
+ console.log(` Detected IDE Rule Files: ${ideSync.discovery.detectedFiles.length}`);
5143
+ for (const f of ideSync.discovery.detectedFiles) {
5144
+ console.log(chalk3.gray(` - ${f.relativePath} (${f.label}, ${f.scope})`));
5145
+ }
5146
+ for (const report of ideSync.reports) {
5147
+ console.log(chalk3.gray(` - [${report.kind}] ${report.relativePath}: ${report.status}`));
5148
+ }
5149
+ console.log();
5150
+ }
3992
5151
  async createTemplateFiles(heraspecPath, skipExisting) {
3993
- const projectMdPath = path8.join(heraspecPath, HERASPEC_MARKERS.PROJECT_MD);
3994
- const configYamlPath = path8.join(heraspecPath, HERASPEC_MARKERS.CONFIG_YAML);
5152
+ const projectMdPath = path10.join(heraspecPath, HERASPEC_MARKERS.PROJECT_MD);
5153
+ const configYamlPath = path10.join(heraspecPath, HERASPEC_MARKERS.CONFIG_YAML);
3995
5154
  const newProjectTemplate = TemplateManager.getProjectTemplate();
3996
5155
  const projectExists = await FileSystemUtils.fileExists(projectMdPath);
3997
5156
  if (!projectExists) {
3998
5157
  await FileSystemUtils.writeFile(projectMdPath, newProjectTemplate);
3999
- } else if (skipExisting) {
4000
- const existingContent = await FileSystemUtils.readFile(projectMdPath);
4001
- const hasChanges = this.detectTemplateChanges(existingContent, newProjectTemplate);
4002
- if (hasChanges) {
4003
- const backupPath = await this.createNumberedBackup(projectMdPath, heraspecPath);
4004
- const backupName = path8.basename(backupPath);
4005
- const mergedContent = this.buildMergedProjectMd(existingContent, newProjectTemplate, backupName);
4006
- await FileSystemUtils.writeFile(projectMdPath, mergedContent);
4007
- }
4008
- } else {
5158
+ } else if (!skipExisting) {
4009
5159
  await FileSystemUtils.writeFile(projectMdPath, newProjectTemplate);
4010
5160
  }
4011
5161
  if (!await FileSystemUtils.fileExists(configYamlPath)) {
@@ -4020,333 +5170,28 @@ var InitCommand = class {
4020
5170
  }
4021
5171
  }
4022
5172
  /**
4023
- * Migrate legacy project.md (extract technical configs to config.yaml)
5173
+ * Migrate legacy project.md (extract technical configs to config.yaml without altering user prose)
4024
5174
  */
4025
5175
  async migrateLegacyProjectMd(projectMdPath, configYamlPath) {
4026
5176
  const content = await FileSystemUtils.readFile(projectMdPath);
4027
5177
  let newYaml = `projectType: generic-webapp
4028
5178
  projectName: "HeraSpec Project"
4029
- description: "A new project using HeraSpec"
5179
+ description: "A project using HeraSpec"
4030
5180
  skills: []
4031
5181
  `;
4032
- const projectTypeMatch = content.match(/## Project Types\\s*\\n\\s*-\\s*([a-zA-Z0-9-]+)/);
5182
+ const projectTypeMatch = content.match(/## Project Types\s*\n\s*-\s*`?([a-zA-Z0-9-]+)`?/);
4033
5183
  if (projectTypeMatch && projectTypeMatch[1]) {
4034
5184
  newYaml = newYaml.replace(/projectType:.*/, `projectType: ${projectTypeMatch[1]}`);
4035
5185
  }
4036
- const stackMatch = content.match(/## Tech Stack\\s*\\n([^#]+)/);
5186
+ const stackMatch = content.match(/## Tech Stack\s*\n([^#]+)/);
4037
5187
  if (stackMatch && stackMatch[1]) {
4038
- const stackItems = stackMatch[1].split("\\n").filter((line) => line.trim().startsWith("-")).map((line) => line.replace("-", "").trim());
5188
+ const stackItems = stackMatch[1].split("\n").filter((line) => line.trim().startsWith("-")).map((line) => line.replace(/^\s*-\s*/, "").trim()).filter(Boolean);
4039
5189
  if (stackItems.length > 0) {
4040
5190
  newYaml += `techStack:
4041
- ` + stackItems.map((item) => ` - "${item}"`).join("\n") + "\n";
5191
+ ` + stackItems.map((item) => ` - "${item.replace(/"/g, '\\"')}"`).join("\n") + "\n";
4042
5192
  }
4043
5193
  }
4044
5194
  await FileSystemUtils.writeFile(configYamlPath, newYaml);
4045
- let updatedMd = content;
4046
- updatedMd = updatedMd.replace(/## Project Types[\\s\\S]*?(?=##|$)/, "");
4047
- updatedMd = updatedMd.replace(/## Tech Stack[\\s\\S]*?(?=##|$)/, "");
4048
- if (!updatedMd.includes("<!-- HeraSpec Update: Migrated config to config.yaml -->")) {
4049
- updatedMd = `<!-- HeraSpec Update: Migrated config to config.yaml -->
4050
- ` + updatedMd.trimStart();
4051
- }
4052
- await FileSystemUtils.writeFile(projectMdPath, updatedMd);
4053
- }
4054
- /**
4055
- * Detect if the new template has sections that the existing file lacks
4056
- */
4057
- detectTemplateChanges(existingContent, newTemplate) {
4058
- const sectionRegex = /^## .+$/gm;
4059
- const existingSections = new Set(
4060
- (existingContent.match(sectionRegex) || []).map((s) => s.trim().toLowerCase())
4061
- );
4062
- const newSections = (newTemplate.match(sectionRegex) || []).map((s) => s.trim().toLowerCase());
4063
- for (const section of newSections) {
4064
- if (!existingSections.has(section)) {
4065
- return true;
4066
- }
4067
- }
4068
- return false;
4069
- }
4070
- /**
4071
- * Create numbered backup: project.back1.md, project.back2.md, etc.
4072
- */
4073
- async createNumberedBackup(filePath, dirPath) {
4074
- const ext = path8.extname(filePath);
4075
- const base = path8.basename(filePath, ext);
4076
- let backupNumber = 1;
4077
- while (true) {
4078
- const backupPath = path8.join(dirPath, `${base}.back${backupNumber}${ext}`);
4079
- if (!await FileSystemUtils.fileExists(backupPath)) {
4080
- await FileSystemUtils.copyFile(filePath, backupPath);
4081
- return backupPath;
4082
- }
4083
- backupNumber++;
4084
- if (backupNumber > 99) break;
4085
- }
4086
- const fallbackPath = path8.join(dirPath, `${base}.back99${ext}`);
4087
- await FileSystemUtils.copyFile(filePath, fallbackPath);
4088
- return fallbackPath;
4089
- }
4090
- /**
4091
- * Build merged project.md:
4092
- * - Keeps all existing user content (descriptions, tech stack, conventions)
4093
- * - Adds any NEW sections from the template that don't exist yet
4094
- * - Adds a merge note at the top referencing the backup
4095
- */
4096
- buildMergedProjectMd(existingContent, newTemplate, backupFileName) {
4097
- const existingSections = this.parseSections(existingContent);
4098
- const templateSections = this.parseSections(newTemplate);
4099
- const mergedParts = [];
4100
- const existingSectionHeaders = new Set(
4101
- existingSections.map((s) => s.header.trim().toLowerCase())
4102
- );
4103
- const mergeNote = `<!-- HeraSpec Update: Template updated. Previous version backed up to "${backupFileName}". New sections (if any) have been appended below. -->
4104
- `;
4105
- mergedParts.push(mergeNote);
4106
- mergedParts.push(existingContent.trimEnd());
4107
- const newSections = [];
4108
- for (const section of templateSections) {
4109
- if (!existingSectionHeaders.has(section.header.trim().toLowerCase())) {
4110
- newSections.push(section);
4111
- }
4112
- }
4113
- if (newSections.length > 0) {
4114
- mergedParts.push("\n\n<!-- New sections added by HeraSpec update -->");
4115
- for (const section of newSections) {
4116
- mergedParts.push(`
4117
- ${section.header}
4118
- ${section.content.trimEnd()}`);
4119
- }
4120
- }
4121
- return mergedParts.join("\n").trimEnd() + "\n";
4122
- }
4123
- /**
4124
- * Parse markdown sections (## headers) from content
4125
- */
4126
- parseSections(content) {
4127
- const sections = [];
4128
- const lines = content.split("\n");
4129
- let currentHeader = "";
4130
- let currentContent = [];
4131
- for (const line of lines) {
4132
- if (line.match(/^## /)) {
4133
- if (currentHeader) {
4134
- sections.push({ header: currentHeader, content: currentContent.join("\n") });
4135
- }
4136
- currentHeader = line;
4137
- currentContent = [];
4138
- } else if (currentHeader) {
4139
- currentContent.push(line);
4140
- }
4141
- }
4142
- if (currentHeader) {
4143
- sections.push({ header: currentHeader, content: currentContent.join("\n") });
4144
- }
4145
- return sections;
4146
- }
4147
- async updateAgentsFile(agentsPath, alreadyInitialized) {
4148
- const skillsSectionMarker = "## Skills System";
4149
- if (!alreadyInitialized) {
4150
- await FileSystemUtils.writeFile(
4151
- agentsPath,
4152
- TemplateManager.getAgentsTemplate()
4153
- );
4154
- return;
4155
- }
4156
- let existingContent = "";
4157
- if (await FileSystemUtils.fileExists(agentsPath)) {
4158
- existingContent = await FileSystemUtils.readFile(agentsPath);
4159
- } else {
4160
- await FileSystemUtils.writeFile(
4161
- agentsPath,
4162
- TemplateManager.getAgentsTemplate()
4163
- );
4164
- return;
4165
- }
4166
- const latestSkillsSection = await this.getSkillsSection();
4167
- const safetyMarker = "## Universal Safety Rules";
4168
- const fullTemplate = TemplateManager.getAgentsTemplate();
4169
- const safetyEndIndex = fullTemplate.indexOf("## Core Workflow");
4170
- const safetySection = fullTemplate.substring(fullTemplate.indexOf(safetyMarker), safetyEndIndex).trim();
4171
- if (existingContent.includes(safetyMarker)) {
4172
- existingContent = this.replaceSafetyRules(existingContent, safetySection);
4173
- } else {
4174
- if (existingContent.startsWith("# ")) {
4175
- const firstLineEnd = existingContent.indexOf("\n") + 1;
4176
- existingContent = existingContent.substring(0, firstLineEnd) + "\n" + safetySection + "\n\n" + existingContent.substring(firstLineEnd);
4177
- } else {
4178
- existingContent = safetySection + "\n\n" + existingContent;
4179
- }
4180
- }
4181
- const coreWorkflowMarker = "## Core Workflow";
4182
- const coreWorkflowEndMarker = "## Skills System";
4183
- const coreWorkflowEndIndex = fullTemplate.indexOf(coreWorkflowEndMarker);
4184
- const coreWorkflowStartIndex = fullTemplate.indexOf(coreWorkflowMarker);
4185
- if (coreWorkflowStartIndex !== -1 && coreWorkflowEndIndex !== -1) {
4186
- const coreWorkflowSection = fullTemplate.substring(coreWorkflowStartIndex, coreWorkflowEndIndex).trim();
4187
- if (existingContent.includes(coreWorkflowMarker)) {
4188
- existingContent = this.replaceSection(existingContent, coreWorkflowMarker, coreWorkflowSection);
4189
- } else {
4190
- const safetyEndPos = existingContent.indexOf("\n## ", existingContent.indexOf(safetyMarker) + safetyMarker.length);
4191
- if (safetyEndPos !== -1) {
4192
- const before = existingContent.substring(0, safetyEndPos).trimEnd();
4193
- const after = existingContent.substring(safetyEndPos);
4194
- existingContent = before + "\n\n" + coreWorkflowSection + "\n\n" + after;
4195
- }
4196
- }
4197
- }
4198
- let updatedContent = existingContent;
4199
- if (existingContent.includes(skillsSectionMarker) || existingContent.includes("## Skills system")) {
4200
- updatedContent = this.replaceSkillsSection(existingContent, latestSkillsSection);
4201
- } else {
4202
- updatedContent = this.appendSkillsSection(existingContent, latestSkillsSection);
4203
- }
4204
- const oldMemoryMarker = "## Memory-Aware Development";
4205
- const newMemoryMarker = "## Proactive Memory-Aware Development";
4206
- const memoryStartIndex = fullTemplate.indexOf(newMemoryMarker);
4207
- if (memoryStartIndex !== -1) {
4208
- let memoryEndIndex = fullTemplate.indexOf("\n## ", memoryStartIndex + newMemoryMarker.length);
4209
- if (memoryEndIndex === -1) memoryEndIndex = fullTemplate.length;
4210
- const memorySection = fullTemplate.substring(memoryStartIndex, memoryEndIndex).trim();
4211
- if (updatedContent.includes(oldMemoryMarker)) {
4212
- updatedContent = this.replaceSection(updatedContent, oldMemoryMarker, memorySection);
4213
- } else if (updatedContent.includes(newMemoryMarker)) {
4214
- updatedContent = this.replaceSection(updatedContent, newMemoryMarker, memorySection);
4215
- } else {
4216
- updatedContent = updatedContent.trimEnd() + "\n\n" + memorySection;
4217
- }
4218
- }
4219
- if (updatedContent !== existingContent) {
4220
- await FileSystemUtils.writeFile(agentsPath, updatedContent);
4221
- }
4222
- }
4223
- /**
4224
- * Find the index of the next top-level H2 section in the markdown content.
4225
- * Tracks fenced code blocks to ignore H2 headers inside code blocks.
4226
- */
4227
- findSectionEndIndex(content, startIndex) {
4228
- const lines = content.substring(startIndex).split(/\r?\n/);
4229
- let offset = startIndex;
4230
- let inCodeBlock = false;
4231
- for (let i = 0; i < lines.length; i++) {
4232
- const line = lines[i];
4233
- const lineLengthWithNewline = line.length + (content.charAt(offset + line.length) === "\r" ? 2 : 1);
4234
- if (i === 0) {
4235
- offset += lineLengthWithNewline;
4236
- continue;
4237
- }
4238
- if (line.trim().startsWith("```")) {
4239
- inCodeBlock = !inCodeBlock;
4240
- }
4241
- if (!inCodeBlock && line.startsWith("## ")) {
4242
- return offset;
4243
- }
4244
- offset += lineLengthWithNewline;
4245
- }
4246
- return content.length;
4247
- }
4248
- /**
4249
- * Finds the start index of the next standard section in the sequence.
4250
- * This is used to replace the entire section cleanly, even if there are internal H2s or duplicates.
4251
- */
4252
- findNextSectionIndex(content, startIndex, currentHeader) {
4253
- const sectionsOrder = [
4254
- ["## Universal Safety Rules"],
4255
- ["## Core Workflow"],
4256
- ["## Skills System", "## Skills system", "### Skills System", "### skills system"],
4257
- ["## Proactive Memory-Aware Development", "## Memory-Aware Development"]
4258
- ];
4259
- let currentGroupIndex = -1;
4260
- for (let i = 0; i < sectionsOrder.length; i++) {
4261
- if (sectionsOrder[i].some((h) => currentHeader.toLowerCase().trim() === h.toLowerCase().trim())) {
4262
- currentGroupIndex = i;
4263
- break;
4264
- }
4265
- }
4266
- if (currentGroupIndex === -1) {
4267
- return this.findSectionEndIndex(content, startIndex);
4268
- }
4269
- let nextSectionIndex = -1;
4270
- for (let i = currentGroupIndex + 1; i < sectionsOrder.length; i++) {
4271
- const variations = sectionsOrder[i];
4272
- for (const variation of variations) {
4273
- const idx = content.indexOf(variation, startIndex + currentHeader.length);
4274
- if (idx !== -1) {
4275
- if (nextSectionIndex === -1 || idx < nextSectionIndex) {
4276
- nextSectionIndex = idx;
4277
- }
4278
- }
4279
- }
4280
- }
4281
- if (nextSectionIndex !== -1) {
4282
- return nextSectionIndex;
4283
- }
4284
- return this.findSectionEndIndex(content, startIndex);
4285
- }
4286
- /**
4287
- * Generic section replacer: replace content from marker to next H2 header or endMarker
4288
- */
4289
- replaceSection(content, sectionMarker, newSection, endMarker) {
4290
- const startIndex = content.indexOf(sectionMarker);
4291
- if (startIndex === -1) return content;
4292
- let endIndex = -1;
4293
- if (endMarker) {
4294
- endIndex = content.indexOf(endMarker, startIndex + sectionMarker.length);
4295
- }
4296
- if (endIndex === -1) {
4297
- endIndex = this.findNextSectionIndex(content, startIndex, sectionMarker);
4298
- }
4299
- const before = content.substring(0, startIndex).trimEnd();
4300
- const after = content.substring(endIndex);
4301
- return before + "\n\n" + newSection + (after.trimStart().startsWith("\n") ? "" : "\n\n") + after;
4302
- }
4303
- replaceSkillsSection(existingContent, newSkillsSection, endMarker) {
4304
- const startMarkers = ["## Skills System", "## Skills system", "### Skills System", "### Skills system"];
4305
- let startIndex = -1;
4306
- let foundMarker = "";
4307
- for (const marker of startMarkers) {
4308
- startIndex = existingContent.indexOf(marker);
4309
- if (startIndex !== -1) {
4310
- foundMarker = marker;
4311
- break;
4312
- }
4313
- }
4314
- if (startIndex === -1) {
4315
- return this.appendSkillsSection(existingContent, newSkillsSection);
4316
- }
4317
- let endIndex = -1;
4318
- if (endMarker) {
4319
- endIndex = existingContent.indexOf(endMarker, startIndex + foundMarker.length);
4320
- }
4321
- if (endIndex === -1) {
4322
- endIndex = this.findNextSectionIndex(existingContent, startIndex, foundMarker);
4323
- }
4324
- const before = existingContent.substring(0, startIndex).trimEnd();
4325
- const after = existingContent.substring(endIndex);
4326
- return before + "\n\n" + newSkillsSection + (after.trimStart().startsWith("\n") ? "" : "\n\n") + after;
4327
- }
4328
- replaceSafetyRules(existingContent, newSafetySection) {
4329
- return this.replaceSection(existingContent, "## Universal Safety Rules", newSafetySection, "## Core Workflow");
4330
- }
4331
- appendSkillsSection(existingContent, skillsSection) {
4332
- const rulesMarker = "\n## Rules\n";
4333
- const rulesIndex = existingContent.indexOf(rulesMarker);
4334
- if (rulesIndex !== -1) {
4335
- const before = existingContent.substring(0, rulesIndex).trimEnd();
4336
- const after = existingContent.substring(rulesIndex);
4337
- return before + "\n\n" + skillsSection + "\n\n" + after;
4338
- }
4339
- const rulesMarker2 = "## Rules";
4340
- const rulesIndex2 = existingContent.indexOf(rulesMarker2);
4341
- if (rulesIndex2 !== -1 && rulesIndex2 > 0) {
4342
- const before = existingContent.substring(0, rulesIndex2).trimEnd();
4343
- const after = existingContent.substring(rulesIndex2);
4344
- return before + "\n\n" + skillsSection + "\n\n" + after;
4345
- }
4346
- return existingContent.trimEnd() + "\n\n" + skillsSection;
4347
- }
4348
- async getSkillsSection() {
4349
- return TemplateManager.getSkillsSection();
4350
5195
  }
4351
5196
  /**
4352
5197
  * Resolve core templates directory (same logic as skill.ts)
@@ -4355,7 +5200,7 @@ ${section.content.trimEnd()}`);
4355
5200
  const possiblePaths = [];
4356
5201
  try {
4357
5202
  const packageJsonPath = require3.resolve("../package.json");
4358
- const packageDir = path8.dirname(packageJsonPath);
5203
+ const packageDir = path10.dirname(packageJsonPath);
4359
5204
  possiblePaths.push(
4360
5205
  join2(packageDir, "src", "core", "templates", "skills"),
4361
5206
  join2(packageDir, "dist", "core", "templates", "skills")
@@ -4364,7 +5209,7 @@ ${section.content.trimEnd()}`);
4364
5209
  }
4365
5210
  try {
4366
5211
  const packageJsonPath = require3.resolve("heraspec/package.json");
4367
- const packageDir = path8.dirname(packageJsonPath);
5212
+ const packageDir = path10.dirname(packageJsonPath);
4368
5213
  possiblePaths.push(
4369
5214
  join2(packageDir, "dist", "core", "templates", "skills"),
4370
5215
  join2(packageDir, "src", "core", "templates", "skills")
@@ -4386,26 +5231,26 @@ ${section.content.trimEnd()}`);
4386
5231
  * Ensures backward compatibility and non-destructive enhancement for existing projects.
4387
5232
  */
4388
5233
  async refactorLegacySkills(skillsDir, coreTemplatesDir) {
4389
- const perfexSkillDir = path8.join(skillsDir, "perfex-module");
5234
+ const perfexSkillDir = path10.join(skillsDir, "perfex-module");
4390
5235
  if (await FileSystemUtils.fileExists(perfexSkillDir)) {
4391
- const rootSkillMd = path8.join(perfexSkillDir, "skill.md");
4392
- const rootSkillUpperMd = path8.join(perfexSkillDir, "SKILL.md");
4393
- const templateRootSkill = path8.join(coreTemplatesDir, "perfex-module", "skill.md");
4394
- const templateRootUpper = path8.join(coreTemplatesDir, "perfex-module", "SKILL.md");
5236
+ const rootSkillMd = path10.join(perfexSkillDir, "skill.md");
5237
+ const rootSkillUpperMd = path10.join(perfexSkillDir, "SKILL.md");
5238
+ const templateRootSkill = path10.join(coreTemplatesDir, "perfex-module", "skill.md");
5239
+ const templateRootUpper = path10.join(coreTemplatesDir, "perfex-module", "SKILL.md");
4395
5240
  if (!await FileSystemUtils.fileExists(rootSkillMd) && await FileSystemUtils.fileExists(templateRootSkill)) {
4396
5241
  await FileSystemUtils.copyFile(templateRootSkill, rootSkillMd);
4397
5242
  }
4398
5243
  if (!await FileSystemUtils.fileExists(rootSkillUpperMd) && await FileSystemUtils.fileExists(templateRootUpper)) {
4399
5244
  await FileSystemUtils.copyFile(templateRootUpper, rootSkillUpperMd);
4400
5245
  }
4401
- const qualityGuidelinesDir = path8.join(perfexSkillDir, "code-quality-guidelines");
4402
- const templateQualityDir = path8.join(coreTemplatesDir, "perfex-module", "code-quality-guidelines");
5246
+ const qualityGuidelinesDir = path10.join(perfexSkillDir, "code-quality-guidelines");
5247
+ const templateQualityDir = path10.join(coreTemplatesDir, "perfex-module", "code-quality-guidelines");
4403
5248
  if (!await FileSystemUtils.fileExists(qualityGuidelinesDir) && await FileSystemUtils.fileExists(templateQualityDir)) {
4404
- console.log(chalk2.cyan(" \u2713 Refactored perfex-module: added code-quality-guidelines skill"));
5249
+ console.log(chalk3.cyan(" \u2713 Refactored perfex-module: added code-quality-guidelines skill"));
4405
5250
  await FileSystemUtils.copyDirectory(templateQualityDir, qualityGuidelinesDir);
4406
5251
  }
4407
- const codebaseDir = path8.join(perfexSkillDir, "module-codebase");
4408
- const templateCodebaseDir = path8.join(coreTemplatesDir, "perfex-module", "module-codebase");
5252
+ const codebaseDir = path10.join(perfexSkillDir, "module-codebase");
5253
+ const templateCodebaseDir = path10.join(coreTemplatesDir, "perfex-module", "module-codebase");
4409
5254
  if (await FileSystemUtils.fileExists(codebaseDir) && await FileSystemUtils.fileExists(templateCodebaseDir)) {
4410
5255
  await FileSystemUtils.copyDirectory(templateCodebaseDir, codebaseDir);
4411
5256
  }
@@ -4422,7 +5267,7 @@ ${section.content.trimEnd()}`);
4422
5267
  * safely preserving any user files in templates/, scripts/, examples/ sub-folders
4423
5268
  */
4424
5269
  async updateInstalledSkills(heraspecPath) {
4425
- const skillsDir = path8.join(heraspecPath, SKILLS_DIR_NAME);
5270
+ const skillsDir = path10.join(heraspecPath, SKILLS_DIR_NAME);
4426
5271
  if (!await FileSystemUtils.fileExists(skillsDir)) return;
4427
5272
  const coreTemplatesDir = await this.getCoreTemplatesDir();
4428
5273
  if (!coreTemplatesDir) return;
@@ -4440,7 +5285,7 @@ ${section.content.trimEnd()}`);
4440
5285
  }
4441
5286
  continue;
4442
5287
  }
4443
- const templateFile = path8.join(coreTemplatesDir, templateInfo.templateFileName);
5288
+ const templateFile = path10.join(coreTemplatesDir, templateInfo.templateFileName);
4444
5289
  if (!await FileSystemUtils.fileExists(templateFile)) {
4445
5290
  const displayName = projectType ? `${projectType}/${skillName}` : skillName;
4446
5291
  if (!preservedSkills.includes(displayName)) {
@@ -4448,38 +5293,38 @@ ${section.content.trimEnd()}`);
4448
5293
  }
4449
5294
  continue;
4450
5295
  }
4451
- await FileSystemUtils.copyFile(templateFile, path8.join(skillPath, "skill.md"));
4452
- const upperTemplateFile = path8.join(path8.dirname(templateFile), "SKILL.md");
5296
+ await FileSystemUtils.copyFile(templateFile, path10.join(skillPath, "skill.md"));
5297
+ const upperTemplateFile = path10.join(path10.dirname(templateFile), "SKILL.md");
4453
5298
  if (await FileSystemUtils.fileExists(upperTemplateFile)) {
4454
- await FileSystemUtils.copyFile(upperTemplateFile, path8.join(skillPath, "SKILL.md"));
5299
+ await FileSystemUtils.copyFile(upperTemplateFile, path10.join(skillPath, "SKILL.md"));
4455
5300
  }
4456
5301
  if (templateInfo.viFileName) {
4457
- const viFile = path8.join(coreTemplatesDir, templateInfo.viFileName);
5302
+ const viFile = path10.join(coreTemplatesDir, templateInfo.viFileName);
4458
5303
  if (await FileSystemUtils.fileExists(viFile)) {
4459
- await FileSystemUtils.copyFile(viFile, path8.join(skillPath, "skill.vi.md"));
5304
+ await FileSystemUtils.copyFile(viFile, path10.join(skillPath, "skill.vi.md"));
4460
5305
  }
4461
5306
  }
4462
5307
  if (templateInfo.resourceDirs) {
4463
5308
  for (const resourceDir of templateInfo.resourceDirs) {
4464
- const srcResourceDir = path8.join(coreTemplatesDir, resourceDir);
4465
- const destResourceDir = path8.join(skillPath, path8.basename(resourceDir));
5309
+ const srcResourceDir = path10.join(coreTemplatesDir, resourceDir);
5310
+ const destResourceDir = path10.join(skillPath, path10.basename(resourceDir));
4466
5311
  if (await FileSystemUtils.fileExists(srcResourceDir)) {
4467
5312
  await FileSystemUtils.copyDirectory(srcResourceDir, destResourceDir);
4468
5313
  }
4469
5314
  }
4470
5315
  }
4471
5316
  for (const dir of ["templates", "scripts", "examples"]) {
4472
- await FileSystemUtils.createDirectory(path8.join(skillPath, dir));
5317
+ await FileSystemUtils.createDirectory(path10.join(skillPath, dir));
4473
5318
  }
4474
5319
  updatedCount++;
4475
5320
  }
4476
5321
  if (updatedCount > 0) {
4477
- console.log(chalk2.gray(` \u2713 Updated ${updatedCount} built-in skill(s)`));
5322
+ console.log(chalk3.gray(` \u2713 Updated ${updatedCount} built-in skill(s)`));
4478
5323
  }
4479
5324
  if (preservedSkills.length > 0) {
4480
- console.log(chalk2.green(` \u2713 Preserved ${preservedSkills.length} custom project skill(s) (never deleted or overwritten):`));
5325
+ console.log(chalk3.green(` \u2713 Preserved ${preservedSkills.length} custom project skill(s) (never deleted or overwritten):`));
4481
5326
  for (const skill of preservedSkills) {
4482
- console.log(chalk2.gray(` \u2022 ${skill}`));
5327
+ console.log(chalk3.gray(` \u2022 ${skill}`));
4483
5328
  }
4484
5329
  }
4485
5330
  }
@@ -4504,24 +5349,24 @@ ${section.content.trimEnd()}`);
4504
5349
  ];
4505
5350
  for (const entry of entries) {
4506
5351
  if (entry === "README.md" || entry === "UI_UX_SKILL_QUICK_REFERENCE.md") continue;
4507
- const entryPath = path8.join(skillsDir, entry);
5352
+ const entryPath = path10.join(skillsDir, entry);
4508
5353
  const stats = await FileSystemUtils.stat(entryPath);
4509
5354
  if (!stats.isDirectory()) continue;
4510
5355
  if (knownProjectTypes.includes(entry)) {
4511
5356
  const subEntries = await FileSystemUtils.readDirectory(entryPath);
4512
5357
  for (const sub of subEntries) {
4513
5358
  if (["templates", "scripts", "examples", "data", "knowledge", "tests", "docs"].includes(sub)) continue;
4514
- const subPath = path8.join(entryPath, sub);
5359
+ const subPath = path10.join(entryPath, sub);
4515
5360
  const subStats = await FileSystemUtils.stat(subPath);
4516
5361
  if (subStats.isDirectory()) {
4517
5362
  result.push({ skillPath: subPath, skillName: sub, projectType: entry });
4518
5363
  }
4519
5364
  }
4520
- if (await FileSystemUtils.fileExists(path8.join(entryPath, "skill.md")) || await FileSystemUtils.fileExists(path8.join(entryPath, "SKILL.md"))) {
5365
+ if (await FileSystemUtils.fileExists(path10.join(entryPath, "skill.md")) || await FileSystemUtils.fileExists(path10.join(entryPath, "SKILL.md"))) {
4521
5366
  result.push({ skillPath: entryPath, skillName: entry, projectType: entry });
4522
5367
  }
4523
5368
  } else {
4524
- if (await FileSystemUtils.fileExists(path8.join(entryPath, "skill.md")) || await FileSystemUtils.fileExists(path8.join(entryPath, "SKILL.md"))) {
5369
+ if (await FileSystemUtils.fileExists(path10.join(entryPath, "skill.md")) || await FileSystemUtils.fileExists(path10.join(entryPath, "SKILL.md"))) {
4525
5370
  result.push({ skillPath: entryPath, skillName: entry });
4526
5371
  }
4527
5372
  }
@@ -4532,13 +5377,13 @@ ${section.content.trimEnd()}`);
4532
5377
  * Prompt user to bootstrap memory if historical specs are found
4533
5378
  */
4534
5379
  async checkAndBootstrapMemory(heraspecPath, projectPath, spinner) {
4535
- const memorySkillDir = path8.join(heraspecPath, SKILLS_DIR_NAME, "project-memory");
5380
+ const memorySkillDir = path10.join(heraspecPath, SKILLS_DIR_NAME, "project-memory");
4536
5381
  if (!await FileSystemUtils.fileExists(memorySkillDir)) {
4537
5382
  spinner.stop();
4538
5383
  try {
4539
5384
  const { SkillCommand: SkillCommand2 } = await Promise.resolve().then(() => (init_skill(), skill_exports));
4540
5385
  const skillCommand = new SkillCommand2();
4541
- console.log(chalk2.cyan('\n\u{1F4E6} Auto-installing recommended skill: "project-memory"'));
5386
+ console.log(chalk3.cyan('\n\u{1F4E6} Auto-installing recommended skill: "project-memory"'));
4542
5387
  await skillCommand.add("project-memory", void 0, projectPath);
4543
5388
  console.log();
4544
5389
  } catch (err) {
@@ -4547,8 +5392,8 @@ ${section.content.trimEnd()}`);
4547
5392
  }
4548
5393
  spinner.start();
4549
5394
  }
4550
- const specsDir = path8.join(heraspecPath, SPECS_DIR_NAME);
4551
- const archivesDir = path8.join(heraspecPath, ARCHIVES_DIR_NAME);
5395
+ const specsDir = path10.join(heraspecPath, SPECS_DIR_NAME);
5396
+ const archivesDir = path10.join(heraspecPath, ARCHIVES_DIR_NAME);
4552
5397
  let hasHistoricalData = false;
4553
5398
  for (const dir of [specsDir, archivesDir]) {
4554
5399
  if (await FileSystemUtils.fileExists(dir)) {
@@ -4559,7 +5404,7 @@ ${section.content.trimEnd()}`);
4559
5404
  }
4560
5405
  if (!hasHistoricalData) {
4561
5406
  for (const e of entries) {
4562
- const fullPath = path8.join(dir, e);
5407
+ const fullPath = path10.join(dir, e);
4563
5408
  const st = await FileSystemUtils.stat(fullPath);
4564
5409
  if (st.isDirectory()) {
4565
5410
  const subEntries = await FileSystemUtils.readDirectory(fullPath);
@@ -4573,12 +5418,15 @@ ${section.content.trimEnd()}`);
4573
5418
  }
4574
5419
  }
4575
5420
  if (!hasHistoricalData) return;
4576
- const memoryDbPath = path8.join(heraspecPath, "memory", "heraspec-memory.db");
5421
+ const memoryDbPath = path10.join(heraspecPath, "memory", "heraspec-memory.db");
4577
5422
  if (await FileSystemUtils.fileExists(memoryDbPath)) {
4578
5423
  return;
4579
5424
  }
5425
+ if (!process.stdin.isTTY) {
5426
+ return;
5427
+ }
4580
5428
  spinner.stop();
4581
- console.log(chalk2.cyan("\n\u{1F4A1} Tip: Your project has historical specs."));
5429
+ console.log(chalk3.cyan("\n\u{1F4A1} Tip: Your project has historical specs."));
4582
5430
  const { confirm } = await import("@inquirer/prompts");
4583
5431
  const answer = await confirm({
4584
5432
  message: 'Would you like to bootstrap the "project-memory" system from these existing specs?',
@@ -4589,7 +5437,7 @@ ${section.content.trimEnd()}`);
4589
5437
  const memoryCommand = new MemoryCommand();
4590
5438
  await memoryCommand.bootstrap({ yes: true }, projectPath);
4591
5439
  } catch (error) {
4592
- console.log(chalk2.red(`Bootstrap failed: ${error instanceof Error ? error.message : "Unknown"}`));
5440
+ console.log(chalk3.red(`Bootstrap failed: ${error instanceof Error ? error.message : "Unknown"}`));
4593
5441
  }
4594
5442
  }
4595
5443
  spinner.start();
@@ -4598,8 +5446,8 @@ ${section.content.trimEnd()}`);
4598
5446
  * Automatically install content-channel skills if project type is content-channel
4599
5447
  */
4600
5448
  async checkAndBootstrapContentChannel(heraspecPath, projectPath, spinner) {
4601
- const configPath = path8.join(heraspecPath, HERASPEC_MARKERS.CONFIG_YAML);
4602
- const projectMdPath = path8.join(heraspecPath, HERASPEC_MARKERS.PROJECT_MD);
5449
+ const configPath = path10.join(heraspecPath, HERASPEC_MARKERS.CONFIG_YAML);
5450
+ const projectMdPath = path10.join(heraspecPath, HERASPEC_MARKERS.PROJECT_MD);
4603
5451
  let isContentChannel = false;
4604
5452
  if (await FileSystemUtils.fileExists(configPath)) {
4605
5453
  const configContent = await FileSystemUtils.readFile(configPath);
@@ -4614,9 +5462,9 @@ ${section.content.trimEnd()}`);
4614
5462
  }
4615
5463
  }
4616
5464
  if (!isContentChannel) {
4617
- const hasFacebook = await FileSystemUtils.fileExists(path8.join(projectPath, "Facebook"));
4618
- const hasPosts = await FileSystemUtils.fileExists(path8.join(projectPath, "posts"));
4619
- const hasPrompts = await FileSystemUtils.fileExists(path8.join(projectPath, "prompts"));
5465
+ const hasFacebook = await FileSystemUtils.fileExists(path10.join(projectPath, "Facebook"));
5466
+ const hasPosts = await FileSystemUtils.fileExists(path10.join(projectPath, "posts"));
5467
+ const hasPrompts = await FileSystemUtils.fileExists(path10.join(projectPath, "prompts"));
4620
5468
  if (hasFacebook || hasPosts && hasPrompts) {
4621
5469
  isContentChannel = true;
4622
5470
  }
@@ -4631,18 +5479,18 @@ ${section.content.trimEnd()}`);
4631
5479
  "content-compliance",
4632
5480
  "content-vault-sync"
4633
5481
  ];
4634
- const skillsDir = path8.join(heraspecPath, SKILLS_DIR_NAME);
5482
+ const skillsDir = path10.join(heraspecPath, SKILLS_DIR_NAME);
4635
5483
  const missingSkills = [];
4636
5484
  for (const skillName of channelSkills) {
4637
- const flatPath = path8.join(skillsDir, skillName);
4638
- const scopedPath = path8.join(skillsDir, "content-channel", skillName);
5485
+ const flatPath = path10.join(skillsDir, skillName);
5486
+ const scopedPath = path10.join(skillsDir, "content-channel", skillName);
4639
5487
  if (!await FileSystemUtils.fileExists(flatPath) && !await FileSystemUtils.fileExists(scopedPath)) {
4640
5488
  missingSkills.push(skillName);
4641
5489
  }
4642
5490
  }
4643
5491
  if (missingSkills.length > 0) {
4644
5492
  spinner.stop();
4645
- console.log(chalk2.cyan(`
5493
+ console.log(chalk3.cyan(`
4646
5494
  \u{1F3AC} Detected content-channel project. Installing ${missingSkills.length} channel skill(s)...`));
4647
5495
  try {
4648
5496
  const { SkillCommand: SkillCommand2 } = await Promise.resolve().then(() => (init_skill(), skill_exports));
@@ -4650,7 +5498,7 @@ ${section.content.trimEnd()}`);
4650
5498
  for (const skillName of missingSkills) {
4651
5499
  await skillCommand.add(skillName, void 0, projectPath);
4652
5500
  }
4653
- console.log(chalk2.green(`\u2713 Channel skills suite ready for production.
5501
+ console.log(chalk3.green(`\u2713 Channel skills suite ready for production.
4654
5502
  `));
4655
5503
  } catch (err) {
4656
5504
  }
@@ -4665,7 +5513,7 @@ ${section.content.trimEnd()}`);
4665
5513
  const possiblePaths = [];
4666
5514
  try {
4667
5515
  const packageJsonPath = require3.resolve("../package.json");
4668
- const packageDir = path8.dirname(packageJsonPath);
5516
+ const packageDir = path10.dirname(packageJsonPath);
4669
5517
  possiblePaths.push(
4670
5518
  join2(packageDir, "src", "core", "templates", "skills", "knowledge"),
4671
5519
  join2(packageDir, "dist", "core", "templates", "skills", "knowledge")
@@ -4674,7 +5522,7 @@ ${section.content.trimEnd()}`);
4674
5522
  }
4675
5523
  try {
4676
5524
  const packageJsonPath = require3.resolve("heraspec/package.json");
4677
- const packageDir = path8.dirname(packageJsonPath);
5525
+ const packageDir = path10.dirname(packageJsonPath);
4678
5526
  possiblePaths.push(
4679
5527
  join2(packageDir, "dist", "core", "templates", "skills", "knowledge"),
4680
5528
  join2(packageDir, "src", "core", "templates", "skills", "knowledge")
@@ -4697,34 +5545,34 @@ ${section.content.trimEnd()}`);
4697
5545
  * Deploy/update built-in knowledge base, preserving custom/ directory
4698
5546
  */
4699
5547
  async deployKnowledge(heraspecPath) {
4700
- const knowledgeDir = path8.join(heraspecPath, KNOWLEDGE_DIR_NAME);
5548
+ const knowledgeDir = path10.join(heraspecPath, KNOWLEDGE_DIR_NAME);
4701
5549
  const sourceDir = await this.getKnowledgeSourceDir();
4702
5550
  if (!sourceDir) {
4703
5551
  return;
4704
5552
  }
4705
5553
  const builtinFiles = ["index.json", "README.md"];
4706
5554
  for (const file of builtinFiles) {
4707
- const srcFile = path8.join(sourceDir, file);
5555
+ const srcFile = path10.join(sourceDir, file);
4708
5556
  if (await FileSystemUtils.fileExists(srcFile)) {
4709
- await FileSystemUtils.copyFile(srcFile, path8.join(knowledgeDir, file));
5557
+ await FileSystemUtils.copyFile(srcFile, path10.join(knowledgeDir, file));
4710
5558
  }
4711
5559
  }
4712
5560
  const builtinCategories = ["frameworks", "apis", "platforms"];
4713
5561
  for (const category of builtinCategories) {
4714
- const srcCategory = path8.join(sourceDir, category);
5562
+ const srcCategory = path10.join(sourceDir, category);
4715
5563
  if (await FileSystemUtils.fileExists(srcCategory)) {
4716
- const destCategory = path8.join(knowledgeDir, category);
5564
+ const destCategory = path10.join(knowledgeDir, category);
4717
5565
  if (await FileSystemUtils.fileExists(destCategory)) {
4718
5566
  await FileSystemUtils.removeDirectory(destCategory, true);
4719
5567
  }
4720
5568
  await FileSystemUtils.copyDirectory(srcCategory, destCategory);
4721
5569
  }
4722
5570
  }
4723
- const customDir = path8.join(knowledgeDir, "custom");
5571
+ const customDir = path10.join(knowledgeDir, "custom");
4724
5572
  if (!await FileSystemUtils.fileExists(customDir)) {
4725
5573
  await FileSystemUtils.createDirectory(customDir);
4726
5574
  await FileSystemUtils.writeFile(
4727
- path8.join(customDir, "index.json"),
5575
+ path10.join(customDir, "index.json"),
4728
5576
  JSON.stringify({
4729
5577
  version: "1.0",
4730
5578
  description: "Custom knowledge entries \u2014 managed by user, never overwritten by CLI",
@@ -5023,7 +5871,7 @@ After copying UI/UX skill to your project, see:
5023
5871
  * Update related markdown files in the project (README.md, etc.)
5024
5872
  */
5025
5873
  async updateRelatedMarkdownFiles(projectPath) {
5026
- const readmePath = path8.join(projectPath, "README.md");
5874
+ const readmePath = path10.join(projectPath, "README.md");
5027
5875
  if (await FileSystemUtils.fileExists(readmePath)) {
5028
5876
  await this.updateReadmeFile(readmePath);
5029
5877
  }
@@ -5134,7 +5982,8 @@ heraspec validate <change-name>
5134
5982
  - \`heraspec/specs/\` - Source of truth specifications
5135
5983
  - \`heraspec/changes/\` - Active changes in progress
5136
5984
  - \`heraspec/skills/\` - Reusable skills for AI agents
5137
- - \`AGENTS.heraspec.md\` - AI agent instructions
5985
+ - \`AGENTS.heraspec.md\` - CLI-managed AI agent workflow instructions
5986
+ - \`AGENTS.custom.md\` - Project-owned custom rules and engineering gates
5138
5987
 
5139
5988
  ### Working with Changes
5140
5989
 
@@ -5170,10 +6019,10 @@ For more information, see the [HeraSpec documentation](https://github.com/PolyXG
5170
6019
  // src/core/list.ts
5171
6020
  init_file_system();
5172
6021
  init_config();
5173
- import path9 from "path";
6022
+ import path11 from "path";
5174
6023
  var ListCommand = class {
5175
6024
  async execute(targetPath = ".", mode = "changes") {
5176
- const heraspecPath = path9.join(targetPath, HERASPEC_DIR_NAME);
6025
+ const heraspecPath = path11.join(targetPath, HERASPEC_DIR_NAME);
5177
6026
  if (mode === "changes") {
5178
6027
  await this.listChanges(heraspecPath);
5179
6028
  } else {
@@ -5181,7 +6030,7 @@ var ListCommand = class {
5181
6030
  }
5182
6031
  }
5183
6032
  async listChanges(heraspecPath) {
5184
- const changesDir = path9.join(heraspecPath, CHANGES_DIR_NAME);
6033
+ const changesDir = path11.join(heraspecPath, CHANGES_DIR_NAME);
5185
6034
  try {
5186
6035
  await FileSystemUtils.stat(changesDir);
5187
6036
  } catch {
@@ -5191,7 +6040,7 @@ var ListCommand = class {
5191
6040
  const entries = await FileSystemUtils.readDirectory(changesDir);
5192
6041
  const changeDirs = [];
5193
6042
  for (const entry of entries) {
5194
- const entryPath = path9.join(changesDir, entry);
6043
+ const entryPath = path11.join(changesDir, entry);
5195
6044
  const stats = await FileSystemUtils.stat(entryPath);
5196
6045
  if (stats.isDirectory() && entry !== ARCHIVES_DIR_NAME) {
5197
6046
  changeDirs.push(entry);
@@ -5210,7 +6059,7 @@ var ListCommand = class {
5210
6059
  console.log();
5211
6060
  }
5212
6061
  async listSpecs(heraspecPath) {
5213
- const specsDir = path9.join(heraspecPath, SPECS_DIR_NAME);
6062
+ const specsDir = path11.join(heraspecPath, SPECS_DIR_NAME);
5214
6063
  try {
5215
6064
  await FileSystemUtils.stat(specsDir);
5216
6065
  } catch {
@@ -5234,7 +6083,7 @@ var ListCommand = class {
5234
6083
  const specs = [];
5235
6084
  const entries = await FileSystemUtils.readDirectory(dir);
5236
6085
  for (const entry of entries) {
5237
- const entryPath = path9.join(dir, entry);
6086
+ const entryPath = path11.join(dir, entry);
5238
6087
  const stats = await FileSystemUtils.stat(entryPath);
5239
6088
  if (stats.isDirectory()) {
5240
6089
  const subSpecs = await this.findSpecFiles(
@@ -5253,10 +6102,10 @@ var ListCommand = class {
5253
6102
  // src/core/archive.ts
5254
6103
  init_file_system();
5255
6104
  init_config();
5256
- import path10 from "path";
6105
+ import path12 from "path";
5257
6106
  import ora4 from "ora";
5258
- import { createHash } from "crypto";
5259
- import chalk3 from "chalk";
6107
+ import { createHash as createHash2 } from "crypto";
6108
+ import chalk4 from "chalk";
5260
6109
 
5261
6110
  // src/core/parsers/markdown-parser.ts
5262
6111
  var MarkdownParser = class _MarkdownParser {
@@ -5268,7 +6117,7 @@ var MarkdownParser = class _MarkdownParser {
5268
6117
  return content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
5269
6118
  }
5270
6119
  parseSpec(name) {
5271
- const sections = this.parseSections();
6120
+ const sections = this.parseSections(this.lines, 2);
5272
6121
  const meta = this.parseMeta(sections);
5273
6122
  const purpose = this.findSection(sections, "Purpose")?.content.join("\n").trim() || "";
5274
6123
  const requirementsSection = this.findSection(sections, "Requirements");
@@ -5291,7 +6140,8 @@ var MarkdownParser = class _MarkdownParser {
5291
6140
  };
5292
6141
  }
5293
6142
  parseDeltaSpec(content) {
5294
- const sections = this.parseSections();
6143
+ const targetLines = content ? _MarkdownParser.normalizeContent(content).split("\n") : this.lines;
6144
+ const sections = this.parseSections(targetLines, 2);
5295
6145
  const added = this.findSection(sections, "ADDED Requirements");
5296
6146
  const modified = this.findSection(sections, "MODIFIED Requirements");
5297
6147
  const removed = this.findSection(sections, "REMOVED Requirements");
@@ -5324,12 +6174,17 @@ var MarkdownParser = class _MarkdownParser {
5324
6174
  }
5325
6175
  return Object.keys(meta).length > 0 ? meta : void 0;
5326
6176
  }
5327
- parseSections() {
6177
+ parseSections(lines = this.lines, maxHeadingLevel = 2) {
5328
6178
  const sections = [];
5329
6179
  let currentSection = null;
5330
- for (const line of this.lines) {
5331
- const headerMatch = line.match(/^(#{1,6})\s+(.+)$/);
5332
- if (headerMatch) {
6180
+ let inCodeBlock = false;
6181
+ for (const line of lines) {
6182
+ const trimmed = line.trim();
6183
+ if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) {
6184
+ inCodeBlock = !inCodeBlock;
6185
+ }
6186
+ const headerMatch = !inCodeBlock ? line.match(/^(#{1,6})\s+(.+)$/) : null;
6187
+ if (headerMatch && headerMatch[1].length <= maxHeadingLevel) {
5333
6188
  if (currentSection) {
5334
6189
  sections.push(currentSection);
5335
6190
  }
@@ -5348,33 +6203,42 @@ var MarkdownParser = class _MarkdownParser {
5348
6203
  return sections;
5349
6204
  }
5350
6205
  findSection(sections, title) {
5351
- return sections.find(
5352
- (s) => s.title.toLowerCase() === title.toLowerCase() || s.title.toLowerCase().includes(title.toLowerCase())
5353
- );
6206
+ const target = title.toLowerCase();
6207
+ return sections.find((s) => s.title.toLowerCase() === target) || sections.find((s) => s.title.toLowerCase().includes(target));
5354
6208
  }
5355
6209
  parseRequirements(section) {
5356
6210
  const requirements = [];
5357
6211
  const lines = section.content;
5358
6212
  let currentRequirement = null;
5359
- let inRequirement = false;
5360
6213
  let inScenario = false;
5361
6214
  let currentScenario = null;
5362
- for (let i = 0; i < lines.length; i++) {
5363
- const line = lines[i];
5364
- const reqMatch = line.match(/^###\s+Requirement:\s*(.+)$/i);
6215
+ let inCodeBlock = false;
6216
+ const flushCurrentRequirement = () => {
6217
+ if (!currentRequirement) return;
6218
+ if (currentScenario) {
6219
+ currentRequirement.scenarios.push(currentScenario);
6220
+ currentScenario = null;
6221
+ }
6222
+ requirements.push(currentRequirement);
6223
+ currentRequirement = null;
6224
+ inScenario = false;
6225
+ };
6226
+ for (const line of lines) {
6227
+ const trimmedLine = line.trim();
6228
+ if (trimmedLine.startsWith("```") || trimmedLine.startsWith("~~~")) {
6229
+ inCodeBlock = !inCodeBlock;
6230
+ }
6231
+ const reqMatch = !inCodeBlock ? line.match(/^###\s+Requirement:\s*(.+)$/i) : null;
5365
6232
  if (reqMatch) {
5366
- if (currentRequirement) {
5367
- requirements.push(currentRequirement);
5368
- }
6233
+ flushCurrentRequirement();
5369
6234
  currentRequirement = {
5370
6235
  name: reqMatch[1].trim(),
5371
6236
  description: "",
5372
6237
  scenarios: []
5373
6238
  };
5374
- inRequirement = true;
5375
6239
  continue;
5376
6240
  }
5377
- const scenarioMatch = line.match(/^####\s+Scenario:\s*(.+)$/i);
6241
+ const scenarioMatch = !inCodeBlock ? line.match(/^####\s+Scenario:\s*(.+)$/i) : null;
5378
6242
  if (scenarioMatch && currentRequirement) {
5379
6243
  if (currentScenario) {
5380
6244
  currentRequirement.scenarios.push(currentScenario);
@@ -5386,24 +6250,18 @@ var MarkdownParser = class _MarkdownParser {
5386
6250
  inScenario = true;
5387
6251
  continue;
5388
6252
  }
5389
- if (currentScenario && line.match(/^-\s*(GIVEN|WHEN|THEN|AND|BUT)\s+/i)) {
6253
+ if (currentScenario && /^-\s*(?:\*\*)?(?:GIVEN|WHEN|THEN|AND|BUT)(?:\*\*)?\b/i.test(trimmedLine)) {
5390
6254
  const step = line.replace(/^-\s*/, "").trim();
5391
6255
  currentScenario.steps.push(step);
5392
6256
  continue;
5393
6257
  }
5394
6258
  if (currentRequirement && !inScenario) {
5395
- const trimmed = line.trim();
5396
- if (trimmed && !trimmed.startsWith("#")) {
5397
- currentRequirement.description += (currentRequirement.description ? "\n" : "") + trimmed;
6259
+ if (trimmedLine && (inCodeBlock || !trimmedLine.startsWith("#"))) {
6260
+ currentRequirement.description += (currentRequirement.description ? "\n" : "") + trimmedLine;
5398
6261
  }
5399
6262
  }
5400
6263
  }
5401
- if (currentScenario && currentRequirement) {
5402
- currentRequirement.scenarios.push(currentScenario);
5403
- }
5404
- if (currentRequirement) {
5405
- requirements.push(currentRequirement);
5406
- }
6264
+ flushCurrentRequirement();
5407
6265
  return requirements;
5408
6266
  }
5409
6267
  parseDeltaRequirements(section) {
@@ -5420,7 +6278,7 @@ var ArchiveCommand = class {
5420
6278
  process.exitCode = 1;
5421
6279
  return;
5422
6280
  }
5423
- const changePath = path10.join(".", HERASPEC_DIR_NAME, CHANGES_DIR_NAME, changeName);
6281
+ const changePath = path12.join(".", HERASPEC_DIR_NAME, CHANGES_DIR_NAME, changeName);
5424
6282
  if (!await FileSystemUtils.fileExists(changePath)) {
5425
6283
  console.error(`Error: Change "${changeName}" not found`);
5426
6284
  process.exitCode = 1;
@@ -5440,7 +6298,7 @@ This will archive "${changeName}" and merge delta specs into source specs.`);
5440
6298
  }).start();
5441
6299
  try {
5442
6300
  await this.mergeDeltaSpecs(changePath, changeName);
5443
- const specsDir = path10.join(
6301
+ const specsDir = path12.join(
5444
6302
  ".",
5445
6303
  HERASPEC_DIR_NAME,
5446
6304
  SPECS_DIR_NAME,
@@ -5449,26 +6307,26 @@ This will archive "${changeName}" and merge delta specs into source specs.`);
5449
6307
  if (await FileSystemUtils.fileExists(specsDir)) {
5450
6308
  await FileSystemUtils.removeDirectory(specsDir, true);
5451
6309
  }
5452
- const archiveDir = path10.join(
6310
+ const archiveDir = path12.join(
5453
6311
  ".",
5454
6312
  HERASPEC_DIR_NAME,
5455
6313
  ARCHIVES_DIR_NAME
5456
6314
  );
5457
6315
  await FileSystemUtils.createDirectory(archiveDir);
5458
6316
  const datePrefix = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
5459
- const archivePath = path10.join(archiveDir, `${datePrefix}-${changeName}`);
6317
+ const archivePath = path12.join(archiveDir, `${datePrefix}-${changeName}`);
5460
6318
  await FileSystemUtils.createDirectory(archivePath);
5461
6319
  await this.moveChangeToArchive(changePath, archivePath);
5462
6320
  await FileSystemUtils.removeDirectory(changePath, true);
5463
- spinner.succeed(chalk3.green(`Change "${changeName}" archived successfully`));
6321
+ spinner.succeed(chalk4.green(`Change "${changeName}" archived successfully`));
5464
6322
  await this.autoLogToMemory(changeName, archivePath);
5465
6323
  } catch (error) {
5466
- spinner.fail(chalk3.red(`Error: ${error.message}`));
6324
+ spinner.fail(chalk4.red(`Error: ${error.message}`));
5467
6325
  throw error;
5468
6326
  }
5469
6327
  }
5470
6328
  async mergeDeltaSpecs(changePath, changeName) {
5471
- const deltaSpecsDir = path10.join(
6329
+ const deltaSpecsDir = path12.join(
5472
6330
  ".",
5473
6331
  HERASPEC_DIR_NAME,
5474
6332
  SPECS_DIR_NAME,
@@ -5479,8 +6337,8 @@ This will archive "${changeName}" and merge delta specs into source specs.`);
5479
6337
  }
5480
6338
  const deltaSpecs = await this.findDeltaSpecFiles(deltaSpecsDir);
5481
6339
  for (const deltaSpec of deltaSpecs) {
5482
- const relativePath = path10.relative(deltaSpecsDir, deltaSpec.path);
5483
- const targetSpecPath = path10.join(
6340
+ const relativePath = path12.relative(deltaSpecsDir, deltaSpec.path);
6341
+ const targetSpecPath = path12.join(
5484
6342
  ".",
5485
6343
  HERASPEC_DIR_NAME,
5486
6344
  SPECS_DIR_NAME,
@@ -5493,7 +6351,7 @@ This will archive "${changeName}" and merge delta specs into source specs.`);
5493
6351
  if (await FileSystemUtils.fileExists(targetSpecPath)) {
5494
6352
  targetContent = await FileSystemUtils.readFile(targetSpecPath);
5495
6353
  }
5496
- const fingerprintsPath = path10.join(changePath, "fingerprints.json");
6354
+ const fingerprintsPath = path12.join(changePath, "fingerprints.json");
5497
6355
  let fingerprints = {};
5498
6356
  if (await FileSystemUtils.fileExists(fingerprintsPath)) {
5499
6357
  fingerprints = JSON.parse(await FileSystemUtils.readFile(fingerprintsPath));
@@ -5504,7 +6362,7 @@ This will archive "${changeName}" and merge delta specs into source specs.`);
5504
6362
  const expectedHash = fingerprints[hashKey];
5505
6363
  if (expectedHash) {
5506
6364
  const currentReqBlock = this.extractRequirementBlock(targetContent, req.name);
5507
- const currentHash = currentReqBlock ? createHash("sha256").update(currentReqBlock).digest("hex") : null;
6365
+ const currentHash = currentReqBlock ? createHash2("sha256").update(currentReqBlock).digest("hex") : null;
5508
6366
  if (currentHash !== expectedHash) {
5509
6367
  throw new Error(
5510
6368
  `Parallel Merge Conflict: The requirement "${req.name}" in ${relativePath} has been changed by someone else since you started this change.
@@ -5514,7 +6372,7 @@ Please run "heraspec sync ${changeName}" to update your base and resolve the con
5514
6372
  }
5515
6373
  }
5516
6374
  const mergedContent = this.mergeDeltaIntoSpec(targetContent, delta, deltaSpec.name);
5517
- await FileSystemUtils.createDirectory(path10.dirname(targetSpecPath));
6375
+ await FileSystemUtils.createDirectory(path12.dirname(targetSpecPath));
5518
6376
  await FileSystemUtils.writeFile(targetSpecPath, mergedContent);
5519
6377
  }
5520
6378
  }
@@ -5587,8 +6445,8 @@ ${req.description}
5587
6445
  async moveChangeToArchive(sourcePath, archivePath) {
5588
6446
  const entries = await FileSystemUtils.readDirectory(sourcePath);
5589
6447
  for (const entry of entries) {
5590
- const sourceEntry = path10.join(sourcePath, entry);
5591
- const archiveEntry = path10.join(archivePath, entry);
6448
+ const sourceEntry = path12.join(sourcePath, entry);
6449
+ const archiveEntry = path12.join(archivePath, entry);
5592
6450
  const stats = await FileSystemUtils.stat(sourceEntry);
5593
6451
  if (stats.isDirectory()) {
5594
6452
  await FileSystemUtils.createDirectory(archiveEntry);
@@ -5602,7 +6460,7 @@ ${req.description}
5602
6460
  const specs = [];
5603
6461
  const entries = await FileSystemUtils.readDirectory(dir);
5604
6462
  for (const entry of entries) {
5605
- const entryPath = path10.join(dir, entry);
6463
+ const entryPath = path12.join(dir, entry);
5606
6464
  const stats = await FileSystemUtils.stat(entryPath);
5607
6465
  if (stats.isDirectory()) {
5608
6466
  const subSpecs = await this.findDeltaSpecFiles(
@@ -5612,7 +6470,7 @@ ${req.description}
5612
6470
  specs.push(...subSpecs);
5613
6471
  } else if (entry.endsWith(".md")) {
5614
6472
  specs.push({
5615
- name: prefix || path10.basename(entry, ".md"),
6473
+ name: prefix || path12.basename(entry, ".md"),
5616
6474
  path: entryPath
5617
6475
  });
5618
6476
  }
@@ -5621,18 +6479,18 @@ ${req.description}
5621
6479
  }
5622
6480
  async autoLogToMemory(changeName, archivePath) {
5623
6481
  try {
5624
- const memoryDbPath = path10.join(".", HERASPEC_DIR_NAME, "memory", "heraspec-memory.db");
6482
+ const memoryDbPath = path12.join(".", HERASPEC_DIR_NAME, "memory", "heraspec-memory.db");
5625
6483
  if (!await FileSystemUtils.fileExists(memoryDbPath)) {
5626
6484
  return;
5627
6485
  }
5628
6486
  const { MemoryCommand: MemoryCommand2 } = await Promise.resolve().then(() => (init_memory(), memory_exports));
5629
6487
  const memoryCmd = new MemoryCommand2();
5630
6488
  let narrative = "";
5631
- const proposalPath = path10.join(archivePath, "proposal.md");
6489
+ const proposalPath = path12.join(archivePath, "proposal.md");
5632
6490
  if (await FileSystemUtils.fileExists(proposalPath)) {
5633
6491
  narrative = await FileSystemUtils.readFile(proposalPath);
5634
6492
  }
5635
- const tasksPath = path10.join(archivePath, "tasks.md");
6493
+ const tasksPath = path12.join(archivePath, "tasks.md");
5636
6494
  if (await FileSystemUtils.fileExists(tasksPath)) {
5637
6495
  const tasksContent = await FileSystemUtils.readFile(tasksPath);
5638
6496
  if (narrative) narrative += "\n\n---\n\n";
@@ -5656,10 +6514,10 @@ ${req.description}
5656
6514
 
5657
6515
  // src/core/sync.ts
5658
6516
  init_file_system();
5659
- import path11 from "path";
5660
- import chalk4 from "chalk";
6517
+ import path13 from "path";
6518
+ import chalk5 from "chalk";
5661
6519
  import ora5 from "ora";
5662
- import { createHash as createHash2 } from "crypto";
6520
+ import { createHash as createHash3 } from "crypto";
5663
6521
  init_config();
5664
6522
  import { readFileSync as readFileSync2 } from "fs";
5665
6523
  var SyncCommand = class {
@@ -5670,7 +6528,7 @@ var SyncCommand = class {
5670
6528
  process.exitCode = 1;
5671
6529
  return;
5672
6530
  }
5673
- const changePath = path11.join(".", HERASPEC_DIR_NAME, CHANGES_DIR_NAME, changeName);
6531
+ const changePath = path13.join(".", HERASPEC_DIR_NAME, CHANGES_DIR_NAME, changeName);
5674
6532
  if (!await FileSystemUtils.fileExists(changePath)) {
5675
6533
  console.error(`Error: Change "${changeName}" not found at ${changePath}`);
5676
6534
  process.exitCode = 1;
@@ -5678,25 +6536,25 @@ var SyncCommand = class {
5678
6536
  }
5679
6537
  const spinner = ora5(`Syncing fingerprints for "${changeName}"...`).start();
5680
6538
  try {
5681
- const fingerprintsPath = path11.join(changePath, "fingerprints.json");
6539
+ const fingerprintsPath = path13.join(changePath, "fingerprints.json");
5682
6540
  let fingerprints = {};
5683
6541
  if (await FileSystemUtils.fileExists(fingerprintsPath)) {
5684
6542
  fingerprints = JSON.parse(readFileSync2(fingerprintsPath, "utf-8"));
5685
6543
  } else {
5686
- spinner.info(chalk4.blue(`No fingerprints.json found for "${changeName}". Run 'heraspec validate ${changeName}' to capture initial fingerprints.`));
6544
+ spinner.info(chalk5.blue(`No fingerprints.json found for "${changeName}". Run 'heraspec validate ${changeName}' to capture initial fingerprints.`));
5687
6545
  return;
5688
6546
  }
5689
- const specsDir = path11.join(".", HERASPEC_DIR_NAME, SPECS_DIR_NAME);
5690
- const deltaSpecsDir = path11.join(specsDir, changeName);
6547
+ const specsDir = path13.join(".", HERASPEC_DIR_NAME, SPECS_DIR_NAME);
6548
+ const deltaSpecsDir = path13.join(specsDir, changeName);
5691
6549
  if (!await FileSystemUtils.fileExists(deltaSpecsDir)) {
5692
- spinner.info(chalk4.yellow(`No delta specs found for "${changeName}". Nothing to sync.`));
6550
+ spinner.info(chalk5.yellow(`No delta specs found for "${changeName}". Nothing to sync.`));
5693
6551
  return;
5694
6552
  }
5695
6553
  const deltaSpecs = await this.findDeltaSpecs(deltaSpecsDir);
5696
6554
  let updatedCount = 0;
5697
6555
  for (const specPath of deltaSpecs) {
5698
- const relativePath = path11.relative(path11.resolve(deltaSpecsDir), path11.resolve(specPath));
5699
- const sourceSpecPath = path11.join(path11.resolve(specsDir), relativePath);
6556
+ const relativePath = path13.relative(path13.resolve(deltaSpecsDir), path13.resolve(specPath));
6557
+ const sourceSpecPath = path13.join(path13.resolve(specsDir), relativePath);
5700
6558
  let sourceContent = "";
5701
6559
  if (await FileSystemUtils.fileExists(sourceSpecPath)) {
5702
6560
  sourceContent = readFileSync2(sourceSpecPath, "utf-8");
@@ -5710,21 +6568,21 @@ var SyncCommand = class {
5710
6568
  const expectedHash = fingerprints[hashKey];
5711
6569
  if (expectedHash) {
5712
6570
  const currentReqBlock = this.extractRequirementBlock(sourceContent, req.name);
5713
- const currentHash = currentReqBlock ? createHash2("sha256").update(currentReqBlock).digest("hex") : null;
6571
+ const currentHash = currentReqBlock ? createHash3("sha256").update(currentReqBlock).digest("hex") : null;
5714
6572
  if (currentHash && currentHash !== expectedHash) {
5715
6573
  spinner.stop();
5716
- console.log(chalk4.yellow(`
6574
+ console.log(chalk5.yellow(`
5717
6575
  \u26A0\uFE0F Conflict detected for requirement "${req.name}" in ${relativePath}`));
5718
- console.log(chalk4.gray(`Source spec was updated after your change started.`));
6576
+ console.log(chalk5.gray(`Source spec was updated after your change started.`));
5719
6577
  fingerprints[hashKey] = currentHash;
5720
6578
  updatedCount++;
5721
- console.log(chalk4.green(`\u2713 Fingerprint updated. Please review the delta spec to ensure your modifications still apply correctly to the new source.`));
6579
+ console.log(chalk5.green(`\u2713 Fingerprint updated. Please review the delta spec to ensure your modifications still apply correctly to the new source.`));
5722
6580
  spinner.start();
5723
6581
  } else if (!currentHash) {
5724
6582
  spinner.stop();
5725
- console.log(chalk4.red(`
6583
+ console.log(chalk5.red(`
5726
6584
  \u274C Requirement "${req.name}" no longer exists in source spec ${relativePath}!`));
5727
- console.log(chalk4.gray(`You should probably remove this requirement from your delta spec.`));
6585
+ console.log(chalk5.gray(`You should probably remove this requirement from your delta spec.`));
5728
6586
  spinner.start();
5729
6587
  }
5730
6588
  }
@@ -5732,12 +6590,12 @@ var SyncCommand = class {
5732
6590
  }
5733
6591
  if (updatedCount > 0) {
5734
6592
  await FileSystemUtils.writeFile(fingerprintsPath, JSON.stringify(fingerprints, null, 2));
5735
- spinner.succeed(chalk4.green(`Synced ${updatedCount} fingerprint(s) successfully.`));
6593
+ spinner.succeed(chalk5.green(`Synced ${updatedCount} fingerprint(s) successfully.`));
5736
6594
  } else {
5737
- spinner.succeed(chalk4.green("Already up to date. No conflicts detected."));
6595
+ spinner.succeed(chalk5.green("Already up to date. No conflicts detected."));
5738
6596
  }
5739
6597
  } catch (error) {
5740
- spinner.fail(chalk4.red(`Error: ${error.message}`));
6598
+ spinner.fail(chalk5.red(`Error: ${error.message}`));
5741
6599
  process.exitCode = 1;
5742
6600
  }
5743
6601
  }
@@ -5745,7 +6603,7 @@ var SyncCommand = class {
5745
6603
  const specs = [];
5746
6604
  const entries = await FileSystemUtils.readDirectory(dir);
5747
6605
  for (const entry of entries) {
5748
- const entryPath = path11.join(dir, entry);
6606
+ const entryPath = path13.join(dir, entry);
5749
6607
  const stats = await FileSystemUtils.stat(entryPath);
5750
6608
  if (stats.isDirectory()) {
5751
6609
  const subSpecs = await this.findDeltaSpecs(entryPath);
@@ -5766,8 +6624,8 @@ var SyncCommand = class {
5766
6624
 
5767
6625
  // src/core/validation/validator.ts
5768
6626
  import { readFileSync as readFileSync3 } from "fs";
5769
- import path12 from "path";
5770
- import { createHash as createHash3 } from "crypto";
6627
+ import path14 from "path";
6628
+ import { createHash as createHash4 } from "crypto";
5771
6629
  init_file_system();
5772
6630
  init_config();
5773
6631
  var Validator = class {
@@ -5832,7 +6690,7 @@ var Validator = class {
5832
6690
  const errors = [];
5833
6691
  const warnings = [];
5834
6692
  const suggestions = [];
5835
- const proposalPath = path12.join(changePath, "proposal.md");
6693
+ const proposalPath = path14.join(changePath, "proposal.md");
5836
6694
  if (!await FileSystemUtils.fileExists(proposalPath)) {
5837
6695
  errors.push({
5838
6696
  message: "Change must have a proposal.md file",
@@ -5848,7 +6706,7 @@ var Validator = class {
5848
6706
  });
5849
6707
  suggestions.push(`Create proposal.md file at ${proposalPath}`);
5850
6708
  }
5851
- const tasksPath = path12.join(changePath, "tasks.md");
6709
+ const tasksPath = path14.join(changePath, "tasks.md");
5852
6710
  if (!await FileSystemUtils.fileExists(tasksPath)) {
5853
6711
  warnings.push({
5854
6712
  message: "Change has no tasks.md file",
@@ -5857,8 +6715,8 @@ var Validator = class {
5857
6715
  autoFixable: false
5858
6716
  });
5859
6717
  }
5860
- const changeName = path12.basename(changePath);
5861
- const specsDir = path12.join(
6718
+ const changeName = path14.basename(changePath);
6719
+ const specsDir = path14.join(
5862
6720
  ".",
5863
6721
  HERASPEC_DIR_NAME,
5864
6722
  SPECS_DIR_NAME,
@@ -5935,14 +6793,14 @@ var Validator = class {
5935
6793
  }
5936
6794
  }
5937
6795
  extractNameFromPath(filePath) {
5938
- const baseName = path12.basename(filePath, ".md");
5939
- return baseName === "spec" ? path12.basename(path12.dirname(filePath)) : baseName;
6796
+ const baseName = path14.basename(filePath, ".md");
6797
+ return baseName === "spec" ? path14.basename(path14.dirname(filePath)) : baseName;
5940
6798
  }
5941
6799
  async findDeltaSpecs(dir) {
5942
6800
  const specs = [];
5943
6801
  const entries = await FileSystemUtils.readDirectory(dir);
5944
6802
  for (const entry of entries) {
5945
- const entryPath = path12.join(dir, entry);
6803
+ const entryPath = path14.join(dir, entry);
5946
6804
  const stats = await FileSystemUtils.stat(entryPath);
5947
6805
  if (stats.isDirectory()) {
5948
6806
  const subSpecs = await this.findDeltaSpecs(entryPath);
@@ -5954,16 +6812,16 @@ var Validator = class {
5954
6812
  return specs;
5955
6813
  }
5956
6814
  async captureFingerprints(changePath, deltaSpecPath, delta) {
5957
- const changeName = path12.basename(changePath);
5958
- const specsDir = path12.join(HERASPEC_DIR_NAME, SPECS_DIR_NAME);
5959
- const deltaSpecsDir = path12.join(specsDir, changeName);
5960
- const relativePath = path12.relative(path12.resolve(deltaSpecsDir), path12.resolve(deltaSpecPath));
5961
- const sourceSpecPath = path12.join(path12.resolve(specsDir), relativePath);
6815
+ const changeName = path14.basename(changePath);
6816
+ const specsDir = path14.join(HERASPEC_DIR_NAME, SPECS_DIR_NAME);
6817
+ const deltaSpecsDir = path14.join(specsDir, changeName);
6818
+ const relativePath = path14.relative(path14.resolve(deltaSpecsDir), path14.resolve(deltaSpecPath));
6819
+ const sourceSpecPath = path14.join(path14.resolve(specsDir), relativePath);
5962
6820
  let sourceContent = "";
5963
6821
  if (await FileSystemUtils.fileExists(sourceSpecPath)) {
5964
6822
  sourceContent = readFileSync3(sourceSpecPath, "utf-8");
5965
6823
  }
5966
- const fingerprintsPath = path12.join(changePath, "fingerprints.json");
6824
+ const fingerprintsPath = path14.join(changePath, "fingerprints.json");
5967
6825
  let fingerprints = {};
5968
6826
  if (await FileSystemUtils.fileExists(fingerprintsPath)) {
5969
6827
  fingerprints = JSON.parse(readFileSync3(fingerprintsPath, "utf-8"));
@@ -5975,7 +6833,7 @@ var Validator = class {
5975
6833
  if (!fingerprints[hashKey]) {
5976
6834
  const reqBlock = this.extractRequirementBlock(sourceContent, req.name);
5977
6835
  if (reqBlock) {
5978
- fingerprints[hashKey] = createHash3("sha256").update(reqBlock).digest("hex");
6836
+ fingerprints[hashKey] = createHash4("sha256").update(reqBlock).digest("hex");
5979
6837
  updated = true;
5980
6838
  }
5981
6839
  }
@@ -6000,6 +6858,11 @@ var Validator = class {
6000
6858
  return void 0;
6001
6859
  }
6002
6860
  };
6861
+
6862
+ // src/index.ts
6863
+ init_templates();
6864
+ init_ide_adapter();
6865
+ init_agents_composer();
6003
6866
  export {
6004
6867
  ARCHIVES_DIR_NAME,
6005
6868
  ArchiveCommand,
@@ -6007,12 +6870,18 @@ export {
6007
6870
  ChangeSchema,
6008
6871
  DeltaRequirementSchema,
6009
6872
  DeltaTypeSchema,
6873
+ HERASPEC_ADAPTER_END,
6874
+ HERASPEC_ADAPTER_START,
6010
6875
  HERASPEC_DIR_NAME,
6011
6876
  HERASPEC_MARKERS,
6877
+ HERASPEC_MIGRATION_MARKER,
6878
+ IDE_PROFILES,
6879
+ IdeAdapterManager,
6012
6880
  InitCommand,
6013
6881
  KNOWLEDGE_DIR_NAME,
6014
6882
  ListCommand,
6015
6883
  MEMORY_DIR_NAME,
6884
+ MarkdownParser,
6016
6885
  PROJECT_TYPES,
6017
6886
  ProjectTypeSchema,
6018
6887
  RequirementSchema,
@@ -6023,6 +6892,20 @@ export {
6023
6892
  SpecMetaSchema,
6024
6893
  SpecSchema,
6025
6894
  SyncCommand,
6026
- Validator
6895
+ TemplateManager,
6896
+ Validator,
6897
+ appendMigratedCustomContent,
6898
+ buildAgentsComposePlan,
6899
+ computeNormalizedSha256,
6900
+ extractCustomRulesFromLegacyAgents,
6901
+ formatMigratedCustomContent,
6902
+ normalizeLineEndings,
6903
+ parseConfigYamlContent,
6904
+ parseSkillFrontmatter,
6905
+ readHeraspecState,
6906
+ readProjectMetadata,
6907
+ resolveBackupFilePath,
6908
+ toPosixRelative,
6909
+ writeHeraspecState
6027
6910
  };
6028
6911
  //# sourceMappingURL=index.js.map