heraspec 0.1.0

package/bin/heraspec.js

@@ -0,0 +1,3803 @@
+#!/usr/bin/env node
+// src/cli/index.ts
+import { Command } from "commander";
+import { createRequire as createRequire2 } from "module";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { dirname as dirname2, join as join2 } from "path";
+
+// src/core/init.ts
+import ora from "ora";
+import chalk from "chalk";
+import path2 from "path";
+
+// src/utils/file-system.ts
+import { promises as fs } from "fs";
+import path from "path";
+var FileSystemUtils = class {
+  static async createDirectory(dirPath) {
+    await fs.mkdir(dirPath, { recursive: true });
+  }
+  static async fileExists(filePath) {
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  static async readFile(filePath) {
+    return await fs.readFile(filePath, "utf-8");
+  }
+  static async writeFile(filePath, content) {
+    await fs.writeFile(filePath, content, "utf-8");
+  }
+  static async readDirectory(dirPath) {
+    return await fs.readdir(dirPath);
+  }
+  static async stat(filePath) {
+    return await fs.stat(filePath);
+  }
+  static async copyFile(src, dest) {
+    await fs.copyFile(src, dest);
+  }
+  static async copyDirectory(src, dest) {
+    await fs.mkdir(dest, { recursive: true });
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      if (entry.isDirectory()) {
+        await this.copyDirectory(srcPath, destPath);
+      } else {
+        await fs.copyFile(srcPath, destPath);
+      }
+    }
+  }
+  static async removeFile(filePath) {
+    await fs.unlink(filePath);
+  }
+  static async removeDirectory(dirPath, recursive = true) {
+    if (typeof fs.rm === "function") {
+      await fs.rm(dirPath, { recursive, force: true });
+    } else {
+      await fs.rmdir(dirPath, { recursive });
+    }
+  }
+  static async moveFile(src, dest) {
+    await fs.rename(src, dest);
+  }
+  static joinPath(...segments) {
+    return path.join(...segments);
+  }
+  static resolvePath(...segments) {
+    return path.resolve(...segments);
+  }
+  static getDirectoryName(filePath) {
+    return path.dirname(filePath);
+  }
+  static getBaseName(filePath) {
+    return path.basename(filePath);
+  }
+};
+
+// src/core/templates/index.ts
+var PROJECT_TEMPLATE = `# HeraSpec Project
+
+## Overview
+Describe your project here.
+
+## Project Types
+- wordpress-plugin
+- wordpress-theme
+- perfex-module
+- laravel-package
+- node-service
+- generic-webapp
+- backend-api
+- frontend-app
+- multi-stack
+
+## Tech Stack
+List your technologies here (e.g., PHP 8.1, WordPress 6.0, Laravel 10, etc.)
+
+## Conventions
+Define coding standards, architectural patterns, and conventions to follow.
+
+`;
+var AGENTS_TEMPLATE = `# HeraSpec \u2014 AI Agent Instructions
+
+This document defines the workflow for AI agents working with HeraSpec.
+
+## Core Workflow
+
+### Step 1 \u2014 Create a Change
+
+**When creating changes, ALWAYS read heraspec/project.md first to understand:**
+- Project types being used
+- Tech stack and conventions
+- Existing architecture patterns
+- Coding standards
+
+**Then scaffold:**
+- \`heraspec/changes/<slug>/\` - Create proposal.md, tasks.md, design.md (optional)
+- \`heraspec/specs/<slug>/\` - Create delta specs here (NOT inside changes folder)
+
+**If user asks to create changes based on project.md:**
+1. Read \`heraspec/project.md\` thoroughly
+2. Identify all features/capabilities mentioned
+3. Create separate changes for each major feature
+4. Ensure each change follows project.md conventions
+5. Use correct project types and skills from project.md
+
+### Step 2 \u2014 Refine Specs
+- Update delta specs in \`heraspec/specs/<slug>/\`
+- Never modify source-of-truth specs directly
+
+### Step 3 \u2014 Approval
+- Wait for user: "Specs approved."
+
+### Step 4 \u2014 Implementation
+
+**CRITICAL: When implementing tasks, ALWAYS use Skills system:**
+
+1. **Read task line** to identify skill:
+   \`\`\`markdown
+   ## 1. Perfex module \u2013 Category Management (projectType: perfex-module, skill: module-codebase)
+   - [ ] 1.1 Create module structure
+   \`\`\`
+
+2. **Find skill folder**:
+   - Project-specific: \`heraspec/skills/<project-type>/<skill-name>/\`
+   - Cross-cutting: \`heraspec/skills/<skill-name>/\`
+
+3. **Read skill.md**:
+   - Understand purpose, steps, inputs, outputs
+   - Follow tone, rules, and limitations
+   - Check available templates and scripts
+
+4. **Use skill resources**:
+   - Run scripts from \`scripts/\` folder if needed
+   - Use templates from \`templates/\` folder
+   - Reference examples from \`examples/\` folder
+
+5. **Implement following skill.md guidance**:
+   - Follow step-by-step process
+   - Use correct naming conventions
+   - Apply code style rules
+   - Respect limitations
+
+**Example workflow:**
+- Task: \`(projectType: perfex-module, skill: module-codebase)\`
+- Agent reads: \`heraspec/skills/perfex-module/module-codebase/skill.md\`
+- Agent follows: Steps, uses templates, runs scripts
+- Agent implements: According to skill.md guidelines
+
+**Special case - UI/UX skill:**
+- Task: \`(skill: ui-ux)\`
+- Agent reads: \`heraspec/skills/ui-ux/skill.md\`
+- Agent MUST use search scripts before implementing:
+  \`\`\`bash
+  # Search for design intelligence
+  python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --domain <domain>
+  python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --stack <stack>
+  \`\`\`
+- Agent synthesizes search results
+- Agent implements with proper colors, fonts, styles from search results
+- Agent verifies with pre-delivery checklist
+
+- Follow tasks.md
+- Mark tasks completed: \`- [x]\`
+
+### Step 5 \u2014 Archive
+- Run: \`heraspec archive <slug> --yes\`
+- This merges delta specs into source specs
+- Moves change folder to archives
+
+## Spec Format
+
+Specs must include:
+- \`## Meta\` section with project type, domain, stack
+- \`## Purpose\`
+- \`## Requirements\` with scenarios
+
+## Delta Spec Format
+
+Delta specs use:
+- \`## ADDED Requirements\`
+- \`## MODIFIED Requirements\`
+- \`## REMOVED Requirements\`
+
+## Tasks Format
+
+Tasks grouped by project type and skill:
+\`\`\`
+## 1. WordPress plugin \u2013 admin settings page (projectType: wordpress-plugin, skill: admin-settings-page)
+- [ ] Task description
+\`\`\`
+
+## Skills System
+
+**CRITICAL: Always use Skills when implementing tasks!**
+
+### How Skills Work
+
+1. **Tasks reference skills**: \`(projectType: perfex-module, skill: module-codebase)\`
+2. **Find skill folder**: 
+   - Project-specific: \`heraspec/skills/<project-type>/<skill-name>/\`
+   - Cross-cutting: \`heraspec/skills/<skill-name>/\`
+3. **Read skill.md**: Understand purpose, steps, inputs, outputs, rules
+4. **Use skill resources**: Scripts, templates, examples
+5. **Implement following skill.md**: Follow step-by-step process
+
+### Skill Discovery
+
+- List all skills: Check \`heraspec/skills/\` directory
+- Project-specific skills: \`heraspec/skills/<project-type>/\`
+- Cross-cutting skills: \`heraspec/skills/<skill-name>/\` (root level)
+
+### When Change Has Multiple Skills
+
+**Important**: Each task group uses ONE skill. When working on a task group, agent MUST use that skill's skill.md.
+
+Example with multiple skills in one change:
+\`\`\`
+## 1. Perfex module \u2013 Feature (projectType: perfex-module, skill: module-codebase)
+- [ ] Task 1.1 Create module structure
+- [ ] Task 1.2 Configure registration
+
+## 2. UI/UX \u2013 Admin Interface (skill: ui-ux)
+- [ ] Task 2.1 Design color palette
+- [ ] Task 2.2 Create component styles
+
+## 3. Documents \u2013 User Guide (skill: documents)
+- [ ] Task 3.1 Write technical docs
+\`\`\`
+
+**Agent workflow:**
+1. **For task group 1** (module-codebase):
+   - Read: \`heraspec/skills/perfex-module/module-codebase/skill.md\`
+   - Follow: Module codebase process
+   - Use: Module codebase templates/scripts
+   - Implement: Tasks 1.1, 1.2
+
+2. **For task group 2** (ui-ux):
+   - Read: \`heraspec/skills/ui-ux/skill.md\`
+   - Follow: UI/UX process
+   - Use: UI/UX templates/scripts
+   - Implement: Tasks 2.1, 2.2
+
+3. **For task group 3** (documents):
+   - Read: \`heraspec/skills/documents/skill.md\`
+   - Follow: Documents process
+   - Use: Documents templates/scripts
+   - Implement: Task 3.1
+
+**Key rule**: Switch skill.md when switching task groups!
+
+## Rules
+
+1. **Specs first, tasks second, implementation last.**
+2. **Always use Skills**: When task has skill tag, MUST read and follow skill.md
+3. Never modify source-of-truth specs directly.
+4. Delta specs go in \`heraspec/specs/<slug>/\` (NOT in changes folder).
+5. Always wait for approval before implementation.
+6. **One skill per task group**: Each task group should use one skill consistently.
+
+`;
+var SKILLS_SECTION_TEMPLATE = `## Skills System
+
+**CRITICAL: When implementing tasks, ALWAYS use Skills system:**
+
+1. **Read task line** to identify skill:
+   \`\`\`markdown
+   ## 1. Perfex module \u2013 Category Management (projectType: perfex-module, skill: module-codebase)
+   - [ ] 1.1 Create module structure
+   \`\`\`
+
+2. **Find skill folder**:
+   - Project-specific: \`heraspec/skills/<project-type>/<skill-name>/\`
+   - Cross-cutting: \`heraspec/skills/<skill-name>/\`
+
+3. **Read skill.md**:
+   - Understand purpose, steps, inputs, outputs
+   - Follow tone, rules, and limitations
+   - Check available templates and scripts
+
+4. **Use skill resources**:
+   - Run scripts from \`scripts/\` folder if needed
+   - Use templates from \`templates/\` folder
+   - Reference examples from \`examples/\` folder
+
+5. **Implement following skill.md guidance**:
+   - Follow step-by-step process
+   - Use correct naming conventions
+   - Apply code style rules
+   - Respect limitations
+
+**Example workflow:**
+- Task: \`(projectType: perfex-module, skill: module-codebase)\`
+- Agent reads: \`heraspec/skills/perfex-module/module-codebase/skill.md\`
+- Agent follows: Steps, uses templates, runs scripts
+- Agent implements: According to skill.md guidelines
+
+**Special case - UI/UX skill:**
+- Task: \`(skill: ui-ux)\`
+- Agent reads: \`heraspec/skills/ui-ux/skill.md\`
+- Agent MUST use search scripts before implementing:
+  \`\`\`bash
+  # Search for design intelligence (BM25 - default, fast)
+  python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --domain <domain>
+  
+  # For better semantic results, use Vector or Hybrid mode:
+  python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --domain <domain> --mode vector
+  python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --domain <domain> --mode hybrid
+  
+  # Stack-specific search
+  python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --stack <stack>
+  \`\`\`
+- **Search Modes:**
+  - **BM25 (default)**: Fast keyword-based search, zero dependencies
+  - **Vector**: Semantic search, ~15-20% better results (requires: pip install sentence-transformers scikit-learn)
+  - **Hybrid**: Best of both, ~25% better results (requires: pip install sentence-transformers scikit-learn)
+- Agent synthesizes search results
+- Agent implements with proper colors, fonts, styles from search results
+- Agent verifies with pre-delivery checklist
+
+### Skill Discovery
+
+- List all skills: Check \`heraspec/skills/\` directory
+- Project-specific skills: \`heraspec/skills/<project-type>/\`
+- Cross-cutting skills: \`heraspec/skills/<skill-name>/\` (root level)
+
+### When Change Has Multiple Skills
+
+**Important**: Each task group uses ONE skill. When working on a task group, agent MUST use that skill's skill.md.
+
+Example with multiple skills in one change:
+\`\`\`
+## 1. Perfex module \u2013 Feature (projectType: perfex-module, skill: module-codebase)
+- [ ] Task 1.1 Create module structure
+- [ ] Task 1.2 Configure registration
+
+## 2. UI/UX \u2013 Admin Interface (skill: ui-ux)
+- [ ] Task 2.1 Design color palette
+- [ ] Task 2.2 Create component styles
+
+## 3. Documents \u2013 User Guide (skill: documents)
+- [ ] Task 3.1 Write technical docs
+\`\`\`
+
+**Agent workflow:**
+1. **For task group 1** (module-codebase):
+   - Read: \`heraspec/skills/perfex-module/module-codebase/skill.md\`
+   - Follow: Module codebase process
+   - Use: Module codebase templates/scripts
+   - Implement: Tasks 1.1, 1.2
+
+2. **For task group 2** (ui-ux):
+   - Read: \`heraspec/skills/ui-ux/skill.md\`
+   - Follow: UI/UX process
+   - Use: UI/UX templates/scripts
+   - Implement: Tasks 2.1, 2.2
+
+3. **For task group 3** (documents):
+   - Read: \`heraspec/skills/documents/skill.md\`
+   - Follow: Documents process
+   - Use: Documents templates/scripts
+   - Implement: Task 3.1
+
+**Key rule**: Switch skill.md when switching task groups!
+`;
+var CONFIG_TEMPLATE = `# HeraSpec Configuration
+
+projectTypes:
+  - wordpress-plugin
+  # Add other project types as needed
+
+defaultDomain: global
+
+`;
+var PROPOSAL_TEMPLATE = `# Change Proposal: <slug>
+
+## Purpose
+Describe why this change is needed.
+
+## Scope
+What will be changed?
+
+## Project Types
+- wordpress-plugin
+- perfex-module
+
+## Impact
+What parts of the system will be affected?
+
+`;
+var TASKS_TEMPLATE = `# Tasks
+
+## 1. WordPress plugin \u2013 feature name (projectType: wordpress-plugin, skill: admin-settings-page)
+- [ ] Task 1.1
+- [ ] Task 1.2
+
+## 2. Perfex module \u2013 feature name (projectType: perfex-module, skill: module-registration)
+- [ ] Task 2.1
+
+`;
+var TemplateManager = class {
+  static getProjectTemplate() {
+    return PROJECT_TEMPLATE;
+  }
+  static getAgentsTemplate() {
+    return AGENTS_TEMPLATE;
+  }
+  static getConfigTemplate() {
+    return CONFIG_TEMPLATE;
+  }
+  static getProposalTemplate(slug) {
+    return PROPOSAL_TEMPLATE.replace("<slug>", slug);
+  }
+  static getTasksTemplate() {
+    return TASKS_TEMPLATE;
+  }
+  static getSkillsSection() {
+    return SKILLS_SECTION_TEMPLATE;
+  }
+};
+
+// src/core/config.ts
+var HERASPEC_DIR_NAME = "heraspec";
+var SPECS_DIR_NAME = "specs";
+var CHANGES_DIR_NAME = "changes";
+var ARCHIVES_DIR_NAME = "archives";
+var SKILLS_DIR_NAME = "skills";
+var PROJECT_TYPES = [
+  "wordpress-plugin",
+  "wordpress-theme",
+  "perfex-module",
+  "laravel-package",
+  "node-service",
+  "generic-webapp",
+  "backend-api",
+  "frontend-app",
+  "multi-stack"
+];
+var HERASPEC_MARKERS = {
+  PROJECT_MD: "project.md",
+  AGENTS_MD: "AGENTS.heraspec.md",
+  CONFIG_YAML: "config.yaml",
+  PROPOSAL_MD: "proposal.md",
+  TASKS_MD: "tasks.md",
+  DESIGN_MD: "design.md"
+};
+
+// src/core/init.ts
+var InitCommand = class {
+  async execute(targetPath = ".") {
+    const resolvedPath = path2.resolve(targetPath);
+    const heraspecPath = path2.join(resolvedPath, HERASPEC_DIR_NAME);
+    const alreadyInitialized = await FileSystemUtils.fileExists(
+      path2.join(heraspecPath, HERASPEC_MARKERS.PROJECT_MD)
+    );
+    const spinner = ora({
+      text: alreadyInitialized ? "Updating HeraSpec..." : "Initializing HeraSpec...",
+      color: "blue"
+    }).start();
+    try {
+      await FileSystemUtils.createDirectory(heraspecPath);
+      await FileSystemUtils.createDirectory(path2.join(heraspecPath, SPECS_DIR_NAME));
+      await FileSystemUtils.createDirectory(path2.join(heraspecPath, CHANGES_DIR_NAME));
+      await FileSystemUtils.createDirectory(path2.join(heraspecPath, ARCHIVES_DIR_NAME));
+      await FileSystemUtils.createDirectory(path2.join(heraspecPath, SKILLS_DIR_NAME));
+      const skillsReadmePath = path2.join(heraspecPath, SKILLS_DIR_NAME, "README.md");
+      if (!await FileSystemUtils.fileExists(skillsReadmePath)) {
+        const skillsReadme = await this.getSkillsReadmeTemplate();
+        await FileSystemUtils.writeFile(skillsReadmePath, skillsReadme);
+      }
+      const uiuxGuidePath = path2.join(heraspecPath, SKILLS_DIR_NAME, "UI_UX_SKILL_QUICK_REFERENCE.md");
+      if (!await FileSystemUtils.fileExists(uiuxGuidePath)) {
+        const uiuxGuide = await this.getUIUXQuickReference();
+        await FileSystemUtils.writeFile(uiuxGuidePath, uiuxGuide);
+      }
+      await this.createTemplateFiles(heraspecPath, alreadyInitialized);
+      const agentsPath = path2.join(resolvedPath, HERASPEC_MARKERS.AGENTS_MD);
+      await this.updateAgentsFile(agentsPath, alreadyInitialized);
+      await this.updateRelatedMarkdownFiles(resolvedPath);
+      spinner.succeed(
+        chalk.green(
+          alreadyInitialized ? "HeraSpec updated successfully" : "HeraSpec initialized successfully"
+        )
+      );
+      console.log();
+      console.log(chalk.cyan("Next steps:"));
+      console.log(
+        chalk.gray("1. Review and update heraspec/project.md with your project details")
+      );
+      console.log(
+        chalk.gray('2. Create your first change: "Create a HeraSpec change to..."')
+      );
+      console.log(
+        chalk.gray("3. List changes: heraspec list")
+      );
+    } catch (error) {
+      spinner.fail(chalk.red(`Error: ${error.message}`));
+      throw error;
+    }
+  }
+  async createTemplateFiles(heraspecPath, skipExisting) {
+    const projectMdPath = path2.join(heraspecPath, HERASPEC_MARKERS.PROJECT_MD);
+    const configYamlPath = path2.join(heraspecPath, HERASPEC_MARKERS.CONFIG_YAML);
+    if (!await FileSystemUtils.fileExists(projectMdPath) || !skipExisting) {
+      await FileSystemUtils.writeFile(
+        projectMdPath,
+        TemplateManager.getProjectTemplate()
+      );
+    }
+    if (!await FileSystemUtils.fileExists(configYamlPath) || !skipExisting) {
+      await FileSystemUtils.writeFile(
+        configYamlPath,
+        TemplateManager.getConfigTemplate()
+      );
+    }
+  }
+  async updateAgentsFile(agentsPath, alreadyInitialized) {
+    const skillsSectionMarker = "## Skills System";
+    const skillsSectionEndMarker = "**Key rule**: Switch skill.md when switching task groups!";
+    if (!alreadyInitialized) {
+      await FileSystemUtils.writeFile(
+        agentsPath,
+        TemplateManager.getAgentsTemplate()
+      );
+      return;
+    }
+    let existingContent = "";
+    if (await FileSystemUtils.fileExists(agentsPath)) {
+      existingContent = await FileSystemUtils.readFile(agentsPath);
+    }
+    if (existingContent.includes(skillsSectionMarker)) {
+      const skillsSection = await this.getSkillsSection();
+      const updatedContent = this.replaceSkillsSection(existingContent, skillsSection);
+      await FileSystemUtils.writeFile(agentsPath, updatedContent);
+    } else {
+      const skillsSection = await this.getSkillsSection();
+      const updatedContent = this.appendSkillsSection(existingContent, skillsSection);
+      await FileSystemUtils.writeFile(agentsPath, updatedContent);
+    }
+  }
+  replaceSkillsSection(existingContent, newSkillsSection) {
+    const startMarker = "## Skills System";
+    const startIndex = existingContent.indexOf(startMarker);
+    if (startIndex === -1) {
+      return this.appendSkillsSection(existingContent, newSkillsSection);
+    }
+    let endIndex = existingContent.indexOf("\n## ", startIndex + startMarker.length);
+    if (endIndex === -1) {
+      endIndex = existingContent.length;
+    }
+    const before = existingContent.substring(0, startIndex).trimEnd();
+    const after = existingContent.substring(endIndex);
+    return before + "\n\n" + newSkillsSection + (after.trimStart().startsWith("\n") ? "" : "\n\n") + after;
+  }
+  appendSkillsSection(existingContent, skillsSection) {
+    const rulesMarker = "\n## Rules\n";
+    const rulesIndex = existingContent.indexOf(rulesMarker);
+    if (rulesIndex !== -1) {
+      const before = existingContent.substring(0, rulesIndex).trimEnd();
+      const after = existingContent.substring(rulesIndex);
+      return before + "\n\n" + skillsSection + "\n\n" + after;
+    }
+    const rulesMarker2 = "## Rules";
+    const rulesIndex2 = existingContent.indexOf(rulesMarker2);
+    if (rulesIndex2 !== -1 && rulesIndex2 > 0) {
+      const before = existingContent.substring(0, rulesIndex2).trimEnd();
+      const after = existingContent.substring(rulesIndex2);
+      return before + "\n\n" + skillsSection + "\n\n" + after;
+    }
+    return existingContent.trimEnd() + "\n\n" + skillsSection;
+  }
+  async getSkillsSection() {
+    return TemplateManager.getSkillsSection();
+  }
+  async getSkillsReadmeTemplate() {
+    return `# Skills Directory
+
+This directory contains reusable skills for HeraSpec projects.
+
+## What Are Skills?
+
+Skills are reusable patterns and workflows that help AI agents implement tasks consistently. Each skill contains:
+
+- **skill.md**: Complete guide on how to use the skill
+- **templates/**: Reusable templates
+- **scripts/**: Automation scripts
+- **examples/**: Good and bad examples
+
+## How Agents Use Skills
+
+When a task has a skill tag:
+\`\`\`markdown
+## 1. Feature (projectType: perfex-module, skill: module-codebase)
+- [ ] Task 1.1
+\`\`\`
+
+The agent will:
+1. Find skill folder: \`heraspec/skills/perfex-module/module-codebase/\`
+2. Read \`skill.md\` to understand process
+3. Use templates and scripts from skill folder
+4. Follow guidelines in skill.md
+
+## Available Skills
+
+Run \`heraspec skill list\` to see all available skills.
+
+## UI/UX Skill - Creating Full Theme Packages
+
+The **UI/UX skill** is particularly useful for creating complete website themes with multiple pages.
+
+### Quick Start
+
+When you need to create a full website package, use prompts like:
+
+\`\`\`
+T\u1EA1o g\xF3i website \u0111\u1EA7y \u0111\u1EE7 cho [PRODUCT_TYPE] v\u1EDBi style [STYLE_KEYWORDS].
+S\u1EED d\u1EE5ng skill ui-ux v\u1EDBi hybrid mode \u0111\u1EC3 search design intelligence.
+T\u1EA1o c\xE1c trang: home, about, [other pages].
+Stack: [html-tailwind/react/nextjs].
+\u0110\u1EA3m b\u1EA3o responsive, accessible, consistent design system.
+\`\`\`
+
+### Prompt Templates
+
+For detailed prompt examples and templates, see:
+- **Example Prompts**: \`heraspec/skills/ui-ux/templates/example-prompt-full-theme.md\`
+- **Prompt Templates**: \`heraspec/skills/ui-ux/templates/prompt-template-full-theme.md\`
+
+These templates include:
+- Ready-to-use prompts for different website types (E-commerce, SaaS, Service, Blog, Portfolio)
+- Step-by-step instructions
+- Search command examples
+- Best practices
+
+### Search Modes
+
+UI/UX skill supports 3 search modes:
+- **BM25 (default)**: Fast keyword-based search, zero dependencies
+- **Vector**: Semantic search, ~15-20% better results (requires: \`pip install sentence-transformers scikit-learn\`)
+- **Hybrid**: Best of both, ~25% better results (requires: \`pip install sentence-transformers scikit-learn\`)
+
+**Usage:**
+\`\`\`bash
+# BM25 (default)
+python3 heraspec/skills/ui-ux/scripts/search.py "minimalism" --domain style
+
+# Vector (semantic)
+python3 heraspec/skills/ui-ux/scripts/search.py "elegant dark theme" --domain style --mode vector
+
+# Hybrid (best)
+python3 heraspec/skills/ui-ux/scripts/search.py "modern minimal design" --domain style --mode hybrid
+\`\`\`
+
+### Multi-Page Support
+
+Default page set includes:
+1. Home
+2. About
+3. Post Details
+4. Category
+5. Pricing
+6. FAQ
+7. Contact
+8. Product Category (e-commerce)
+9. Product Details (e-commerce)
+
+Search page types:
+\`\`\`bash
+python3 heraspec/skills/ui-ux/scripts/search.py "home homepage" --domain pages
+python3 heraspec/skills/ui-ux/scripts/search.py "pricing plans" --domain pages
+\`\`\`
+
+### Adding UI/UX Skill to Your Project
+
+1. Copy skill from HeraSpec core:
+   \`\`\`bash
+   # Copy UI/UX skill
+   cp -r /path/to/HeraSpec/src/core/templates/skills/ui-ux-skill.md heraspec/skills/ui-ux/
+   cp -r /path/to/HeraSpec/src/core/templates/skills/scripts heraspec/skills/ui-ux/
+   cp -r /path/to/HeraSpec/src/core/templates/skills/data heraspec/skills/ui-ux/
+   cp -r /path/to/HeraSpec/src/core/templates/skills/templates heraspec/skills/ui-ux/
+   \`\`\`
+
+2. Or use \`heraspec skill add ui-ux\` (if available)
+
+3. Read \`heraspec/skills/ui-ux/ui-ux-skill.md\` for complete documentation
+
+## Creating New Skills
+
+1. Create skill folder structure
+2. Write \`skill.md\` following the template
+3. Add templates, scripts, examples as needed
+
+See \`docs/SKILLS_STRUCTURE_PROPOSAL.md\` for detailed structure.
+`;
+  }
+  async getUIUXQuickReference() {
+    return `# UI/UX Skill - Quick Reference Guide
+
+Quick guide for creating prompts to build full theme packages with multiple pages using the ui-ux skill.
+
+## \u{1F4CB} Basic Prompt Template
+
+\`\`\`
+Create a complete website package for [PRODUCT_TYPE] with the following requirements:
+
+**Project Information:**
+- Product type: [SaaS / E-commerce / Service / Portfolio / etc.]
+- Style: [minimal / elegant / modern / bold / etc.]
+- Industry: [Healthcare / Fintech / Beauty / etc.]
+- Stack: [html-tailwind / react / nextjs / etc.]
+- Pages to create: home, about, [add other pages if needed]
+
+**Process:**
+1. Use skill ui-ux to search design intelligence with hybrid mode
+2. Create shared components first (Header, Footer, Button, Card)
+3. Implement pages in order
+4. Ensure consistency in colors, typography, spacing
+5. Verify with pre-delivery checklist
+
+**Quality Requirements:**
+- \u2705 Consistent design system
+- \u2705 Responsive (320px, 768px, 1024px, 1440px)
+- \u2705 Accessible (WCAG AA minimum)
+- \u2705 Performance optimized
+\`\`\`
+
+## \u{1F3AF} Specific Prompt Examples
+
+### E-Commerce
+\`\`\`
+Create a complete website package for an online fashion store.
+
+Product type: E-commerce Luxury
+Style: elegant, premium, sophisticated
+Stack: Next.js with Tailwind CSS
+Pages: home, about, product category, product details, cart, checkout, thank you, faq, contact
+
+Use skill ui-ux with hybrid mode. Focus on conversion optimization.
+\`\`\`
+
+### SaaS
+\`\`\`
+Create a complete website package for a project management SaaS platform.
+
+Product type: SaaS (General)
+Style: modern, clean, professional
+Stack: React with Tailwind CSS
+Pages: home, about, pricing, features, faq, contact, login, register, dashboard
+
+Use skill ui-ux with hybrid mode. Ensure professional and trustworthy.
+\`\`\`
+
+### Service Business
+\`\`\`
+Create a complete website package for a healthcare service.
+
+Product type: Beauty & Wellness Service
+Style: elegant, minimal, soft, professional
+Stack: html-tailwind
+Pages: home, about, services, blog listing, post details, category, pricing, faq, contact
+
+Use skill ui-ux with hybrid mode. Focus on trust and credibility.
+\`\`\`
+
+## \u{1F50D} Search Modes
+
+### BM25 (Default)
+\`\`\`bash
+python3 heraspec/skills/ui-ux/scripts/search.py "minimalism" --domain style
+\`\`\`
+- \u2705 Fast, zero dependencies
+- \u2705 Best for exact keyword matches
+
+### Vector (Semantic)
+\`\`\`bash
+python3 heraspec/skills/ui-ux/scripts/search.py "elegant dark theme" --domain style --mode vector
+\`\`\`
+- \u2705 Understands meaning and synonyms
+- \u2705 ~15-20% better results
+- \u26A0\uFE0F Requires: \`pip install sentence-transformers scikit-learn\`
+
+### Hybrid (Best)
+\`\`\`bash
+python3 heraspec/skills/ui-ux/scripts/search.py "modern minimal design" --domain style --mode hybrid
+\`\`\`
+- \u2705 Combines BM25 + Vector
+- \u2705 ~25% better results
+- \u26A0\uFE0F Requires: \`pip install sentence-transformers scikit-learn\`
+
+## \u{1F4C4} Default Page Set
+
+When creating a "complete website package", the default set includes 9 pages:
+
+1. **Home** - Main homepage
+2. **About** - Company/story page
+3. **Post Details** - Blog/article detail
+4. **Category** - Blog/category listing
+5. **Pricing** - Pricing plans
+6. **FAQ** - Frequently asked questions
+7. **Contact** - Contact form
+8. **Product Category** - E-commerce category (if applicable)
+9. **Product Details** - E-commerce product detail (if applicable)
+
+## \u{1F527} Search Page Types
+
+\`\`\`bash
+# Home page
+python3 heraspec/skills/ui-ux/scripts/search.py "home homepage" --domain pages
+
+# About page
+python3 heraspec/skills/ui-ux/scripts/search.py "about company story" --domain pages
+
+# Pricing page
+python3 heraspec/skills/ui-ux/scripts/search.py "pricing plans tiers" --domain pages
+
+# E-commerce pages
+python3 heraspec/skills/ui-ux/scripts/search.py "product-category shop catalog" --domain pages
+python3 heraspec/skills/ui-ux/scripts/search.py "product-detail single-product" --domain pages
+\`\`\`
+
+## \u{1F4DA} Detailed Documentation
+
+After copying UI/UX skill to your project, see:
+- \`heraspec/skills/ui-ux/ui-ux-skill.md\` - Complete skill documentation
+- \`heraspec/skills/ui-ux/templates/example-prompt-full-theme.md\` - Detailed prompt examples
+- \`heraspec/skills/ui-ux/templates/prompt-template-full-theme.md\` - Copy-paste templates
+
+## \u{1F4A1} Tips
+
+1. **Always mention "skill ui-ux"** - Agent will know to use this skill
+2. **Encourage using hybrid mode** - Best results
+3. **List all pages clearly** - Agent knows exact scope
+4. **Require consistency** - Ensures unified design system
+5. **Mention pre-delivery checklist** - Agent will verify before delivering
+
+## \u{1F680} Quick Start
+
+1. Copy UI/UX skill to project:
+   \`\`\`bash
+   cp -r /path/to/HeraSpec/src/core/templates/skills/ui-ux-skill.md heraspec/skills/ui-ux/
+   cp -r /path/to/HeraSpec/src/core/templates/skills/scripts heraspec/skills/ui-ux/
+   cp -r /path/to/HeraSpec/src/core/templates/skills/data heraspec/skills/ui-ux/
+   cp -r /path/to/HeraSpec/src/core/templates/skills/templates heraspec/skills/ui-ux/
+   \`\`\`
+
+2. Use prompt template from above
+
+3. Agent will automatically:
+   - Search design intelligence with skill ui-ux
+   - Create shared components
+   - Implement each page
+   - Verify with checklist
+`;
+  }
+  /**
+   * Update related markdown files in the project (README.md, etc.)
+   */
+  async updateRelatedMarkdownFiles(projectPath) {
+    const readmePath = path2.join(projectPath, "README.md");
+    if (await FileSystemUtils.fileExists(readmePath)) {
+      await this.updateReadmeFile(readmePath);
+    }
+  }
+  /**
+   * Update README.md with HeraSpec information
+   */
+  async updateReadmeFile(readmePath) {
+    const existingContent = await FileSystemUtils.readFile(readmePath);
+    const heraspecSection = this.getHeraSpecReadmeSection();
+    const sectionMarkers = [
+      "## HeraSpec",
+      "## HeraSpec Development",
+      "### HeraSpec",
+      "### HeraSpec Development",
+      "<!-- HeraSpec Section -->"
+    ];
+    let hasHeraSpecSection = false;
+    let sectionStartIndex = -1;
+    let sectionEndIndex = -1;
+    for (const marker of sectionMarkers) {
+      const index = existingContent.indexOf(marker);
+      if (index !== -1) {
+        hasHeraSpecSection = true;
+        sectionStartIndex = index;
+        sectionEndIndex = existingContent.indexOf("\n## ", index + marker.length);
+        if (sectionEndIndex === -1) {
+          sectionEndIndex = existingContent.indexOf("\n### ", index + marker.length);
+        }
+        if (sectionEndIndex === -1) {
+          sectionEndIndex = existingContent.length;
+        }
+        break;
+      }
+    }
+    if (hasHeraSpecSection && sectionStartIndex !== -1) {
+      const before = existingContent.substring(0, sectionStartIndex).trimEnd();
+      const after = existingContent.substring(sectionEndIndex);
+      const updatedContent = before + "\n\n" + heraspecSection + (after.trimStart().startsWith("\n") ? "" : "\n\n") + after;
+      await FileSystemUtils.writeFile(readmePath, updatedContent);
+    } else {
+      const insertBeforeMarkers = [
+        "\n## Development",
+        "\n## Setup",
+        "\n## Contributing",
+        "\n## Installation",
+        "\n## Getting Started"
+      ];
+      let inserted = false;
+      for (const marker of insertBeforeMarkers) {
+        const index = existingContent.indexOf(marker);
+        if (index !== -1) {
+          const before = existingContent.substring(0, index).trimEnd();
+          const after = existingContent.substring(index);
+          const updatedContent = before + "\n\n" + heraspecSection + "\n\n" + after;
+          await FileSystemUtils.writeFile(readmePath, updatedContent);
+          inserted = true;
+          break;
+        }
+      }
+      if (!inserted) {
+        const updatedContent = existingContent.trimEnd() + "\n\n" + heraspecSection;
+        await FileSystemUtils.writeFile(readmePath, updatedContent);
+      }
+    }
+  }
+  /**
+   * Get HeraSpec section content for README.md
+   */
+  getHeraSpecReadmeSection() {
+    return `<!-- HeraSpec Section -->
+## HeraSpec Development
+
+This project uses [HeraSpec](https://github.com/your-org/heraspec) for spec-driven development.
+
+### Quick Start
+
+\`\`\`bash
+# Initialize HeraSpec (if not already done)
+heraspec init
+
+# List active changes
+heraspec list
+
+# View a change
+heraspec show <change-name>
+
+# Validate changes
+heraspec validate <change-name>
+\`\`\`
+
+### Project Structure
+
+- \`heraspec/project.md\` - Project overview and configuration
+- \`heraspec/specs/\` - Source of truth specifications
+- \`heraspec/changes/\` - Active changes in progress
+- \`heraspec/skills/\` - Reusable skills for AI agents
+- \`AGENTS.heraspec.md\` - AI agent instructions
+
+### Working with Changes
+
+1. **Create a change**: Ask AI to create a HeraSpec change, or create manually
+2. **Refine specs**: Review and update delta specs in \`heraspec/specs/<change-name>/\`
+3. **Implement**: Follow tasks in \`heraspec/changes/<change-name>/tasks.md\`
+4. **Archive**: Run \`heraspec archive <change-name> --yes\` when complete
+
+### Skills
+
+Add skills to your project:
+
+\`\`\`bash
+# List available skills
+heraspec skill list
+
+# Add a skill
+heraspec skill add ui-ux
+heraspec skill add unit-test
+
+# View skill details
+heraspec skill show ui-ux
+\`\`\`
+
+For more information, see the [HeraSpec documentation](https://github.com/your-org/heraspec/docs).
+
+---
+
+*This section is automatically updated by \`heraspec init\`. Last updated: ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}*`;
+  }
+};
+
+// src/core/list.ts
+import path3 from "path";
+var ListCommand = class {
+  async execute(targetPath = ".", mode = "changes") {
+    const heraspecPath = path3.join(targetPath, HERASPEC_DIR_NAME);
+    if (mode === "changes") {
+      await this.listChanges(heraspecPath);
+    } else {
+      await this.listSpecs(heraspecPath);
+    }
+  }
+  async listChanges(heraspecPath) {
+    const changesDir = path3.join(heraspecPath, CHANGES_DIR_NAME);
+    try {
+      await FileSystemUtils.stat(changesDir);
+    } catch {
+      console.log('No HeraSpec changes directory found. Run "heraspec init" first.');
+      return;
+    }
+    const entries = await FileSystemUtils.readDirectory(changesDir);
+    const changeDirs = [];
+    for (const entry of entries) {
+      const entryPath = path3.join(changesDir, entry);
+      const stats = await FileSystemUtils.stat(entryPath);
+      if (stats.isDirectory() && entry !== ARCHIVES_DIR_NAME) {
+        changeDirs.push(entry);
+      }
+    }
+    if (changeDirs.length === 0) {
+      console.log("No active changes found.");
+      return;
+    }
+    changeDirs.sort();
+    console.log("\nActive changes:");
+    console.log("\u2500".repeat(50));
+    for (const change of changeDirs) {
+      console.log(`  \u2022 ${change}`);
+    }
+    console.log();
+  }
+  async listSpecs(heraspecPath) {
+    const specsDir = path3.join(heraspecPath, SPECS_DIR_NAME);
+    try {
+      await FileSystemUtils.stat(specsDir);
+    } catch {
+      console.log('No HeraSpec specs directory found. Run "heraspec init" first.');
+      return;
+    }
+    const specs = await this.findSpecFiles(specsDir, "");
+    if (specs.length === 0) {
+      console.log("No specs found.");
+      return;
+    }
+    specs.sort();
+    console.log("\nSpecs:");
+    console.log("\u2500".repeat(50));
+    for (const spec of specs) {
+      console.log(`  \u2022 ${spec}`);
+    }
+    console.log();
+  }
+  async findSpecFiles(dir, prefix) {
+    const specs = [];
+    const entries = await FileSystemUtils.readDirectory(dir);
+    for (const entry of entries) {
+      const entryPath = path3.join(dir, entry);
+      const stats = await FileSystemUtils.stat(entryPath);
+      if (stats.isDirectory()) {
+        const subSpecs = await this.findSpecFiles(
+          entryPath,
+          prefix ? `${prefix}/${entry}` : entry
+        );
+        specs.push(...subSpecs);
+      } else if (entry === "spec.md") {
+        specs.push(prefix || "global");
+      }
+    }
+    return specs;
+  }
+};
+
+// src/core/archive.ts
+import path4 from "path";
+import ora2 from "ora";
+import chalk2 from "chalk";
+
+// src/core/parsers/markdown-parser.ts
+var MarkdownParser = class _MarkdownParser {
+  lines;
+  constructor(content) {
+    this.lines = _MarkdownParser.normalizeContent(content).split("\n");
+  }
+  static normalizeContent(content) {
+    return content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  }
+  parseSpec(name) {
+    const sections = this.parseSections();
+    const meta = this.parseMeta(sections);
+    const purpose = this.findSection(sections, "Purpose")?.content.join("\n").trim() || "";
+    const requirementsSection = this.findSection(sections, "Requirements");
+    if (!purpose) {
+      throw new Error("Spec must have a Purpose section");
+    }
+    if (!requirementsSection) {
+      throw new Error("Spec must have a Requirements section");
+    }
+    const requirements = this.parseRequirements(requirementsSection);
+    return {
+      name,
+      meta,
+      overview: purpose.trim(),
+      requirements,
+      metadata: {
+        version: "1.0.0",
+        format: "heraspec"
+      }
+    };
+  }
+  parseDeltaSpec(content) {
+    const sections = this.parseSections();
+    const added = this.findSection(sections, "ADDED Requirements");
+    const modified = this.findSection(sections, "MODIFIED Requirements");
+    const removed = this.findSection(sections, "REMOVED Requirements");
+    return {
+      added: added ? this.parseDeltaRequirements(added) : [],
+      modified: modified ? this.parseDeltaRequirements(modified) : [],
+      removed: removed ? this.parseDeltaRequirements(removed) : []
+    };
+  }
+  parseMeta(sections) {
+    const metaSection = this.findSection(sections, "Meta");
+    if (!metaSection) {
+      return void 0;
+    }
+    const meta = {};
+    const content = metaSection.content.join("\n");
+    const projectTypeMatch = content.match(/project type:\s*(.+)/i);
+    if (projectTypeMatch) {
+      const types = projectTypeMatch[1].split("|").map((t) => t.trim());
+      meta.projectType = types.length === 1 ? types[0] : types;
+    }
+    const domainMatch = content.match(/domain:\s*(.+)/i);
+    if (domainMatch) {
+      meta.domain = domainMatch[1].trim();
+    }
+    const stackMatch = content.match(/stack:\s*(.+)/i);
+    if (stackMatch) {
+      const stacks = stackMatch[1].split("|").map((s) => s.trim());
+      meta.stack = stacks.length === 1 ? stacks[0] : stacks;
+    }
+    return Object.keys(meta).length > 0 ? meta : void 0;
+  }
+  parseSections() {
+    const sections = [];
+    let currentSection = null;
+    for (const line of this.lines) {
+      const headerMatch = line.match(/^(#{1,6})\s+(.+)$/);
+      if (headerMatch) {
+        if (currentSection) {
+          sections.push(currentSection);
+        }
+        currentSection = {
+          level: headerMatch[1].length,
+          title: headerMatch[2].trim(),
+          content: []
+        };
+      } else if (currentSection) {
+        currentSection.content.push(line);
+      }
+    }
+    if (currentSection) {
+      sections.push(currentSection);
+    }
+    return sections;
+  }
+  findSection(sections, title) {
+    return sections.find(
+      (s) => s.title.toLowerCase() === title.toLowerCase() || s.title.toLowerCase().includes(title.toLowerCase())
+    );
+  }
+  parseRequirements(section) {
+    const requirements = [];
+    const lines = section.content;
+    let currentRequirement = null;
+    let inRequirement = false;
+    let inScenario = false;
+    let currentScenario = null;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const reqMatch = line.match(/^###\s+Requirement:\s*(.+)$/i);
+      if (reqMatch) {
+        if (currentRequirement) {
+          requirements.push(currentRequirement);
+        }
+        currentRequirement = {
+          name: reqMatch[1].trim(),
+          description: "",
+          scenarios: []
+        };
+        inRequirement = true;
+        continue;
+      }
+      const scenarioMatch = line.match(/^####\s+Scenario:\s*(.+)$/i);
+      if (scenarioMatch && currentRequirement) {
+        if (currentScenario) {
+          currentRequirement.scenarios.push(currentScenario);
+        }
+        currentScenario = {
+          name: scenarioMatch[1].trim(),
+          steps: []
+        };
+        inScenario = true;
+        continue;
+      }
+      if (currentScenario && line.match(/^-\s*(GIVEN|WHEN|THEN|AND|BUT)\s+/i)) {
+        const step = line.replace(/^-\s*/, "").trim();
+        currentScenario.steps.push(step);
+        continue;
+      }
+      if (currentRequirement && !inScenario) {
+        const trimmed = line.trim();
+        if (trimmed && !trimmed.startsWith("#")) {
+          currentRequirement.description += (currentRequirement.description ? "\n" : "") + trimmed;
+        }
+      }
+    }
+    if (currentScenario && currentRequirement) {
+      currentRequirement.scenarios.push(currentScenario);
+    }
+    if (currentRequirement) {
+      requirements.push(currentRequirement);
+    }
+    return requirements;
+  }
+  parseDeltaRequirements(section) {
+    return this.parseRequirements(section);
+  }
+};
+
+// src/core/archive.ts
+var ArchiveCommand = class {
+  async execute(changeName, options) {
+    if (!changeName) {
+      console.error("Error: Please specify a change name");
+      console.log("Usage: heraspec archive <change-name> [--yes]");
+      process.exitCode = 1;
+      return;
+    }
+    const changePath = path4.join(".", HERASPEC_DIR_NAME, CHANGES_DIR_NAME, changeName);
+    if (!await FileSystemUtils.fileExists(changePath)) {
+      console.error(`Error: Change "${changeName}" not found`);
+      process.exitCode = 1;
+      return;
+    }
+    if (!options?.yes) {
+      console.log(`
+This will archive "${changeName}" and merge delta specs into source specs.`);
+      console.log("This action cannot be undone.\n");
+      console.error("Error: Please use --yes flag to confirm");
+      process.exitCode = 1;
+      return;
+    }
+    const spinner = ora2({
+      text: `Archiving change "${changeName}"...`,
+      color: "blue"
+    }).start();
+    try {
+      await this.mergeDeltaSpecs(changePath, changeName);
+      const specsDir = path4.join(
+        ".",
+        HERASPEC_DIR_NAME,
+        SPECS_DIR_NAME,
+        changeName
+      );
+      if (await FileSystemUtils.fileExists(specsDir)) {
+        await FileSystemUtils.removeDirectory(specsDir, true);
+      }
+      const archiveDir = path4.join(
+        ".",
+        HERASPEC_DIR_NAME,
+        CHANGES_DIR_NAME,
+        ARCHIVES_DIR_NAME
+      );
+      await FileSystemUtils.createDirectory(archiveDir);
+      const datePrefix = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+      const archivePath = path4.join(archiveDir, `${datePrefix}-${changeName}`);
+      await FileSystemUtils.createDirectory(archivePath);
+      await this.moveChangeToArchive(changePath, archivePath);
+      await FileSystemUtils.removeDirectory(changePath, true);
+      spinner.succeed(chalk2.green(`Change "${changeName}" archived successfully`));
+    } catch (error) {
+      spinner.fail(chalk2.red(`Error: ${error.message}`));
+      throw error;
+    }
+  }
+  async mergeDeltaSpecs(changePath, changeName) {
+    const deltaSpecsDir = path4.join(
+      ".",
+      HERASPEC_DIR_NAME,
+      SPECS_DIR_NAME,
+      changeName
+    );
+    if (!await FileSystemUtils.fileExists(deltaSpecsDir)) {
+      return;
+    }
+    const deltaSpecs = await this.findDeltaSpecFiles(deltaSpecsDir);
+    for (const deltaSpec of deltaSpecs) {
+      const relativePath = path4.relative(deltaSpecsDir, deltaSpec.path);
+      const targetSpecPath = path4.join(
+        ".",
+        HERASPEC_DIR_NAME,
+        SPECS_DIR_NAME,
+        relativePath
+      );
+      const deltaContent = await FileSystemUtils.readFile(deltaSpec.path);
+      const parser = new MarkdownParser(deltaContent);
+      const delta = parser.parseDeltaSpec(deltaContent);
+      let targetContent = "";
+      if (await FileSystemUtils.fileExists(targetSpecPath)) {
+        targetContent = await FileSystemUtils.readFile(targetSpecPath);
+      }
+      const mergedContent = this.mergeDeltaIntoSpec(targetContent, delta, deltaSpec.name);
+      await FileSystemUtils.createDirectory(path4.dirname(targetSpecPath));
+      await FileSystemUtils.writeFile(targetSpecPath, mergedContent);
+    }
+  }
+  mergeDeltaIntoSpec(existingContent, delta, specName) {
+    let merged = existingContent || `# Spec: ${specName}
+
+## Purpose
+
+## Requirements
+
+`;
+    if (delta.added.length > 0) {
+      merged += "\n## ADDED Requirements\n\n";
+      for (const req of delta.added) {
+        merged += `### Requirement: ${req.name}
+${req.description}
+
+`;
+      }
+    }
+    return merged;
+  }
+  async moveChangeToArchive(sourcePath, archivePath) {
+    const entries = await FileSystemUtils.readDirectory(sourcePath);
+    for (const entry of entries) {
+      const sourceEntry = path4.join(sourcePath, entry);
+      const archiveEntry = path4.join(archivePath, entry);
+      const stats = await FileSystemUtils.stat(sourceEntry);
+      if (stats.isDirectory()) {
+        await FileSystemUtils.createDirectory(archiveEntry);
+        await this.moveChangeToArchive(sourceEntry, archiveEntry);
+      } else {
+        await FileSystemUtils.moveFile(sourceEntry, archiveEntry);
+      }
+    }
+  }
+  async findDeltaSpecFiles(dir, prefix = "") {
+    const specs = [];
+    const entries = await FileSystemUtils.readDirectory(dir);
+    for (const entry of entries) {
+      const entryPath = path4.join(dir, entry);
+      const stats = await FileSystemUtils.stat(entryPath);
+      if (stats.isDirectory()) {
+        const subSpecs = await this.findDeltaSpecFiles(
+          entryPath,
+          prefix ? `${prefix}/${entry}` : entry
+        );
+        specs.push(...subSpecs);
+      } else if (entry.endsWith(".md")) {
+        specs.push({
+          name: prefix || path4.basename(entry, ".md"),
+          path: entryPath
+        });
+      }
+    }
+    return specs;
+  }
+};
+
+// src/core/restore.ts
+import path5 from "path";
+import ora3 from "ora";
+import chalk3 from "chalk";
+var RestoreCommand = class {
+  async execute(archiveName, options) {
+    const archivesDir = path5.join(
+      ".",
+      HERASPEC_DIR_NAME,
+      CHANGES_DIR_NAME,
+      ARCHIVES_DIR_NAME
+    );
+    if (!await FileSystemUtils.fileExists(archivesDir)) {
+      console.error("Error: No archives directory found. No archives to restore.");
+      process.exitCode = 1;
+      return;
+    }
+    if (!archiveName) {
+      const archives = await this.listArchives(archivesDir);
+      if (archives.length === 0) {
+        console.log("No archived changes found.");
+        return;
+      }
+      console.log("\nAvailable archives:");
+      console.log("\u2500".repeat(60));
+      archives.forEach((archive, index) => {
+        console.log(`${index + 1}. ${archive}`);
+      });
+      console.log();
+      console.error("Error: Please specify archive name to restore");
+      console.log(`Usage: heraspec restore <archive-name>`);
+      console.log(`Example: heraspec restore 2025-01-15-add-two-factor-auth`);
+      process.exitCode = 1;
+      return;
+    }
+    const archivePath = path5.join(archivesDir, archiveName);
+    if (!await FileSystemUtils.fileExists(archivePath)) {
+      console.error(`Error: Archive "${archiveName}" not found`);
+      console.log("\nAvailable archives:");
+      const archives = await this.listArchives(archivesDir);
+      archives.forEach((archive) => {
+        console.log(`  - ${archive}`);
+      });
+      process.exitCode = 1;
+      return;
+    }
+    const changeName = this.extractChangeName(archiveName);
+    const changePath = path5.join(
+      ".",
+      HERASPEC_DIR_NAME,
+      CHANGES_DIR_NAME,
+      changeName
+    );
+    if (await FileSystemUtils.fileExists(changePath)) {
+      console.error(`Error: Change "${changeName}" already exists in active changes.`);
+      console.log("Please remove or rename the existing change first.");
+      process.exitCode = 1;
+      return;
+    }
+    if (!options?.yes) {
+      console.log(`
+This will restore archive "${archiveName}" to active change "${changeName}".`);
+      console.log("Note: This will not revert spec changes that were merged during archive.\n");
+      console.error("Error: Please use --yes flag to confirm");
+      process.exitCode = 1;
+      return;
+    }
+    const spinner = ora3({
+      text: `Restoring archive "${archiveName}"...`,
+      color: "blue"
+    }).start();
+    try {
+      const changesDir = path5.join(
+        ".",
+        HERASPEC_DIR_NAME,
+        CHANGES_DIR_NAME
+      );
+      await FileSystemUtils.createDirectory(changesDir);
+      await FileSystemUtils.createDirectory(changePath);
+      await this.moveArchiveToChanges(archivePath, changePath);
+      await FileSystemUtils.removeDirectory(archivePath, true);
+      spinner.succeed(
+        chalk3.green(`Archive "${archiveName}" restored successfully to "${changeName}"`)
+      );
+      console.log();
+      console.log(chalk3.cyan("Note:"));
+      console.log(
+        chalk3.gray(
+          "Spec changes that were merged during archive are still in source specs."
+        )
+      );
+      console.log(
+        chalk3.gray(
+          "You may need to manually review and revert spec changes if needed."
+        )
+      );
+    } catch (error) {
+      spinner.fail(chalk3.red(`Error: ${error.message}`));
+      throw error;
+    }
+  }
+  async listArchives(archivesDir) {
+    const archives = [];
+    const entries = await FileSystemUtils.readDirectory(archivesDir);
+    for (const entry of entries) {
+      const entryPath = path5.join(archivesDir, entry);
+      const stats = await FileSystemUtils.stat(entryPath);
+      if (stats.isDirectory()) {
+        archives.push(entry);
+      }
+    }
+    return archives.sort();
+  }
+  extractChangeName(archiveName) {
+    const datePattern = /^\d{4}-\d{2}-\d{2}-/;
+    return archiveName.replace(datePattern, "");
+  }
+  async moveArchiveToChanges(sourcePath, destPath) {
+    const entries = await FileSystemUtils.readDirectory(sourcePath);
+    for (const entry of entries) {
+      const sourceEntry = path5.join(sourcePath, entry);
+      const destEntry = path5.join(destPath, entry);
+      const stats = await FileSystemUtils.stat(sourceEntry);
+      if (stats.isDirectory()) {
+        await FileSystemUtils.createDirectory(destEntry);
+        await this.moveArchiveToChanges(sourceEntry, destEntry);
+      } else {
+        await FileSystemUtils.moveFile(sourceEntry, destEntry);
+      }
+    }
+  }
+};
+
+// src/commands/show.ts
+import path8 from "path";
+import chalk4 from "chalk";
+
+// src/utils/task-parser.ts
+import { readFileSync as readFileSync2 } from "fs";
+
+// src/core/skills/skill-parser.ts
+import { readFileSync } from "fs";
+import path6 from "path";
+var SkillParser = class {
+  static parseSkill(skillPath, skillName) {
+    const skillMdPath = path6.join(skillPath, "skill.md");
+    try {
+      const content = readFileSync(skillMdPath, "utf-8");
+      return this.parseSkillContent(content, skillName, skillPath);
+    } catch (error) {
+      throw new Error(`Failed to parse skill "${skillName}": ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+  }
+  static parseSkillContent(content, skillName, skillPath) {
+    const lines = content.split("\n");
+    const skill = {
+      name: skillName,
+      skillPath,
+      purpose: "",
+      whenToUse: [],
+      steps: [],
+      inputs: [],
+      outputs: [],
+      toneAndRules: {},
+      templates: [],
+      scripts: [],
+      examples: [],
+      relatedSkills: []
+    };
+    let currentSection = "";
+    let currentList = [];
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (line.match(/^##+\s+/)) {
+        this.saveList(currentSection, currentList, skill);
+        currentList = [];
+        const sectionName = line.replace(/^##+\s+/, "").toLowerCase();
+        currentSection = sectionName;
+        if (sectionName.includes("m\u1EE5c \u0111\xEDch") || sectionName.includes("purpose")) {
+          if (i + 1 < lines.length && lines[i + 1].trim()) {
+            skill.purpose = lines[i + 1].trim();
+          }
+        }
+        continue;
+      }
+      if (line.startsWith("- ") || line.startsWith("* ")) {
+        const item = line.replace(/^[-*]\s+/, "").trim();
+        if (item) {
+          currentList.push(item);
+        }
+        continue;
+      }
+      if (line.match(/^\d+\.\s+/)) {
+        const step = line.replace(/^\d+\.\s+/, "").trim();
+        if (step) {
+          skill.steps = skill.steps || [];
+          skill.steps.push(step);
+        }
+        continue;
+      }
+      if (currentSection.includes("input")) {
+        if (line.startsWith("- ")) {
+          skill.inputs = skill.inputs || [];
+          skill.inputs.push(line.replace(/^-\s+/, ""));
+        }
+      }
+      if (currentSection.includes("output")) {
+        if (line.startsWith("- ")) {
+          skill.outputs = skill.outputs || [];
+          skill.outputs.push(line.replace(/^-\s+/, ""));
+        }
+      }
+      if (currentSection.includes("template")) {
+        if (line.includes(".php") || line.includes(".md") || line.includes(".scss") || line.includes(".js") || line.includes(".sh")) {
+          skill.templates = skill.templates || [];
+          const templateName = line.match(/`([^`]+)`/) || line.match(/\*\*([^*]+)\*\*/);
+          if (templateName) {
+            skill.templates.push(templateName[1]);
+          }
+        }
+      }
+      if (currentSection.includes("script")) {
+        if (line.includes(".sh") || line.includes(".py") || line.includes(".js")) {
+          skill.scripts = skill.scripts || [];
+          const scriptName = line.match(/`([^`]+)`/) || line.match(/\*\*([^*]+)\*\*/);
+          if (scriptName) {
+            skill.scripts.push(scriptName[1]);
+          }
+        }
+      }
+    }
+    this.saveList(currentSection, currentList, skill);
+    return {
+      name: skill.name || skillName,
+      skillPath: skill.skillPath || skillPath,
+      purpose: skill.purpose || "No description available",
+      whenToUse: skill.whenToUse || [],
+      steps: skill.steps || [],
+      inputs: skill.inputs || [],
+      outputs: skill.outputs || [],
+      toneAndRules: skill.toneAndRules || {},
+      templates: skill.templates || [],
+      scripts: skill.scripts || [],
+      examples: skill.examples || [],
+      relatedSkills: skill.relatedSkills || []
+    };
+  }
+  static saveList(section, list, skill) {
+    if (list.length === 0) return;
+    if (section.includes("khi n\xE0o") || section.includes("when")) {
+      skill.whenToUse = list;
+    } else if (section.includes("input")) {
+      skill.inputs = list;
+    } else if (section.includes("output")) {
+      skill.outputs = list;
+    } else if (section.includes("h\u1EA1n ch\u1EBF") || section.includes("limitation")) {
+      skill.toneAndRules = skill.toneAndRules || {};
+      skill.toneAndRules.limitations = list;
+    } else if (section.includes("li\xEAn k\u1EBFt") || section.includes("related")) {
+      skill.relatedSkills = list;
+    }
+  }
+};
+
+// src/core/skills/skill-manager.ts
+import path7 from "path";
+var SkillManager = class {
+  /**
+   * Find skill path for a given project type and skill name
+   */
+  static async findSkillPath(projectType, skillName, projectPath = ".") {
+    const projectSkillPath = path7.join(
+      projectPath,
+      HERASPEC_DIR_NAME,
+      SKILLS_DIR_NAME,
+      projectType,
+      skillName
+    );
+    if (await FileSystemUtils.fileExists(path7.join(projectSkillPath, "skill.md"))) {
+      return projectSkillPath;
+    }
+    const crossCuttingPath = path7.join(
+      projectPath,
+      HERASPEC_DIR_NAME,
+      SKILLS_DIR_NAME,
+      skillName
+    );
+    if (await FileSystemUtils.fileExists(path7.join(crossCuttingPath, "skill.md"))) {
+      return crossCuttingPath;
+    }
+    return null;
+  }
+  /**
+   * Load skill information
+   */
+  static async loadSkill(projectType, skillName, projectPath = ".") {
+    const skillPath = await this.findSkillPath(projectType, skillName, projectPath);
+    if (!skillPath) {
+      return null;
+    }
+    try {
+      return SkillParser.parseSkill(skillPath, skillName);
+    } catch (error) {
+      console.error(`Failed to load skill "${skillName}": ${error instanceof Error ? error.message : "Unknown error"}`);
+      return null;
+    }
+  }
+  /**
+   * List all available skills
+   */
+  static async listSkills(projectPath = ".") {
+    const skillsDir = path7.join(projectPath, HERASPEC_DIR_NAME, SKILLS_DIR_NAME);
+    if (!await FileSystemUtils.fileExists(skillsDir)) {
+      return [];
+    }
+    const skills = [];
+    const entries = await FileSystemUtils.readDirectory(skillsDir);
+    for (const entry of entries) {
+      const entryPath = path7.join(skillsDir, entry);
+      const stats = await FileSystemUtils.stat(entryPath);
+      if (stats.isDirectory()) {
+        const isProjectType = PROJECT_TYPES.includes(entry);
+        if (isProjectType) {
+          const projectSkills = await this.listSkillsInDirectory(entryPath, entry);
+          skills.push(...projectSkills);
+        } else {
+          const skillMdPath = path7.join(entryPath, "skill.md");
+          if (await FileSystemUtils.fileExists(skillMdPath)) {
+            skills.push({
+              skillName: entry,
+              path: entryPath
+            });
+          }
+        }
+      }
+    }
+    return skills;
+  }
+  /**
+   * Extract skill from task line
+   */
+  static extractSkillFromTask(taskLine) {
+    const match = taskLine.match(/\(projectType:\s*([^,)]+)(?:,\s*skill:\s*([^)]+))?\)/i);
+    if (match) {
+      return {
+        projectType: match[1]?.trim(),
+        skill: match[2]?.trim()
+      };
+    }
+    const skillOnlyMatch = taskLine.match(/\(skill:\s*([^)]+)\)/i);
+    if (skillOnlyMatch) {
+      return {
+        skill: skillOnlyMatch[1]?.trim()
+      };
+    }
+    return null;
+  }
+  static async listSkillsInDirectory(dir, projectType) {
+    const skills = [];
+    const entries = await FileSystemUtils.readDirectory(dir);
+    for (const entry of entries) {
+      const entryPath = path7.join(dir, entry);
+      const stats = await FileSystemUtils.stat(entryPath);
+      if (stats.isDirectory()) {
+        const skillMdPath = path7.join(entryPath, "skill.md");
+        if (await FileSystemUtils.fileExists(skillMdPath)) {
+          skills.push({
+            projectType,
+            skillName: entry,
+            path: entryPath
+          });
+        }
+      }
+    }
+    return skills;
+  }
+};
+
+// src/utils/task-parser.ts
+var TaskParser = class {
+  static parseTasks(filePath) {
+    const content = readFileSync2(filePath, "utf-8");
+    const lines = content.split("\n");
+    const groups = [];
+    const skillsUsed = /* @__PURE__ */ new Set();
+    let currentGroup = null;
+    for (const line of lines) {
+      const groupMatch = line.match(/^##+\s+\d+\.\s+(.+?)\s*\((.+)\)/);
+      if (groupMatch) {
+        if (currentGroup) {
+          groups.push(currentGroup);
+        }
+        const title = groupMatch[1].trim();
+        const params = groupMatch[2];
+        const skillInfo = SkillManager.extractSkillFromTask(`(${params})`);
+        currentGroup = {
+          title,
+          projectType: skillInfo?.projectType,
+          skill: skillInfo?.skill,
+          tasks: []
+        };
+        if (skillInfo?.skill) {
+          const skillKey = skillInfo.projectType ? `${skillInfo.projectType}:${skillInfo.skill}` : skillInfo.skill;
+          skillsUsed.add(skillKey);
+        }
+        continue;
+      }
+      const taskMatch = line.match(/^-\s+\[([ x])\]\s+(.+)/);
+      if (taskMatch && currentGroup) {
+        const completed = taskMatch[1] === "x";
+        const description = taskMatch[2].trim();
+        const idMatch = description.match(/^(\d+\.\d+)\s+/);
+        const id = idMatch ? idMatch[1] : `${currentGroup.tasks.length + 1}`;
+        const taskDesc = idMatch ? description.replace(/^\d+\.\d+\s+/, "") : description;
+        currentGroup.tasks.push({
+          id,
+          description: taskDesc,
+          completed
+        });
+      }
+    }
+    if (currentGroup) {
+      groups.push(currentGroup);
+    }
+    const skillsArray = Array.from(skillsUsed).map((skillKey) => {
+      const [projectType, skill] = skillKey.includes(":") ? skillKey.split(":") : [void 0, skillKey];
+      return { projectType, skill };
+    });
+    return {
+      groups,
+      skillsUsed: skillsArray
+    };
+  }
+  static async getSkillsForTasks(filePath) {
+    const parsed = this.parseTasks(filePath);
+    const skills = [];
+    for (const skillInfo of parsed.skillsUsed) {
+      if (skillInfo.skill) {
+        const skillPath = await SkillManager.findSkillPath(
+          skillInfo.projectType || "",
+          skillInfo.skill,
+          "."
+        );
+        if (skillPath) {
+          skills.push({
+            projectType: skillInfo.projectType,
+            skill: skillInfo.skill,
+            path: skillPath
+          });
+        }
+      }
+    }
+    return skills;
+  }
+};
+
+// src/commands/show.ts
+var ShowCommand = class {
+  async execute(itemName) {
+    if (!itemName) {
+      console.error("Error: Please specify a change or spec name");
+      console.log("Usage: heraspec show <change-name>");
+      process.exitCode = 1;
+      return;
+    }
+    const changePath = path8.join(
+      ".",
+      HERASPEC_DIR_NAME,
+      CHANGES_DIR_NAME,
+      itemName
+    );
+    if (await FileSystemUtils.fileExists(changePath)) {
+      await this.showChange(itemName, changePath);
+      return;
+    }
+    const specPath = this.findSpecPath(itemName);
+    if (specPath && await FileSystemUtils.fileExists(specPath)) {
+      await this.showSpec(specPath);
+      return;
+    }
+    console.error(`Error: Change or spec "${itemName}" not found`);
+    process.exitCode = 1;
+  }
+  async showChange(changeName, changePath) {
+    console.log(`
+\u{1F4CB} Change: ${changeName}
+`);
+    console.log("\u2550".repeat(60));
+    const proposalPath = path8.join(changePath, HERASPEC_MARKERS.PROPOSAL_MD);
+    if (await FileSystemUtils.fileExists(proposalPath)) {
+      console.log("\n## Proposal\n");
+      const proposal = await FileSystemUtils.readFile(proposalPath);
+      console.log(proposal);
+    }
+    const tasksPath = path8.join(changePath, HERASPEC_MARKERS.TASKS_MD);
+    if (await FileSystemUtils.fileExists(tasksPath)) {
+      console.log("\n## Tasks\n");
+      const tasks = await FileSystemUtils.readFile(tasksPath);
+      console.log(tasks);
+      try {
+        const parsedTasks = TaskParser.parseTasks(tasksPath);
+        if (parsedTasks.skillsUsed.length > 0) {
+          console.log("\n## Skills Used in This Change\n");
+          for (const skillInfo of parsedTasks.skillsUsed) {
+            if (skillInfo.skill) {
+              const skillLabel = skillInfo.projectType ? `${skillInfo.projectType}/${skillInfo.skill}` : skillInfo.skill;
+              console.log(chalk4.cyan(`  \u2022 ${skillLabel}`));
+              console.log(chalk4.gray(`    Location: heraspec/skills/${skillInfo.projectType ? skillInfo.projectType + "/" : ""}${skillInfo.skill}/`));
+            }
+          }
+          console.log();
+          console.log(chalk4.yellow("\u{1F4A1} Tip: Read skill.md files to understand how to implement tasks."));
+          console.log();
+        }
+      } catch (error) {
+      }
+    }
+    const designPath = path8.join(changePath, HERASPEC_MARKERS.DESIGN_MD);
+    if (await FileSystemUtils.fileExists(designPath)) {
+      console.log("\n## Design\n");
+      const design = await FileSystemUtils.readFile(designPath);
+      console.log(design);
+    }
+    const specsPath = path8.join(
+      ".",
+      HERASPEC_DIR_NAME,
+      SPECS_DIR_NAME,
+      changeName
+    );
+    if (await FileSystemUtils.fileExists(specsPath)) {
+      const deltaSpecs = await this.findDeltaSpecs(specsPath);
+      if (deltaSpecs.length > 0) {
+        console.log("\n## Delta Specs\n");
+        for (const spec of deltaSpecs) {
+          console.log(`
+### ${spec.name}
+`);
+          const content = await FileSystemUtils.readFile(spec.path);
+          console.log(content);
+        }
+      }
+    }
+    console.log("\n" + "\u2550".repeat(60) + "\n");
+  }
+  async showSpec(specPath) {
+    console.log("\n\u{1F4C4} Spec\n");
+    console.log("\u2550".repeat(60));
+    const content = await FileSystemUtils.readFile(specPath);
+    console.log(content);
+    console.log("\u2550".repeat(60) + "\n");
+  }
+  findSpecPath(specName) {
+    const basePath = path8.join(".", HERASPEC_DIR_NAME, SPECS_DIR_NAME);
+    const paths = [
+      path8.join(basePath, `${specName}.md`),
+      path8.join(basePath, specName, "spec.md"),
+      path8.join(basePath, ...specName.split("/"), "spec.md")
+    ];
+    return paths[0];
+  }
+  async findDeltaSpecs(dir, prefix = "") {
+    const specs = [];
+    const entries = await FileSystemUtils.readDirectory(dir);
+    for (const entry of entries) {
+      const entryPath = path8.join(dir, entry);
+      const stats = await FileSystemUtils.stat(entryPath);
+      if (stats.isDirectory()) {
+        const subSpecs = await this.findDeltaSpecs(
+          entryPath,
+          prefix ? `${prefix}/${entry}` : entry
+        );
+        specs.push(...subSpecs);
+      } else if (entry === "spec.md" || entry.endsWith(".md")) {
+        specs.push({
+          name: prefix || "global",
+          path: entryPath
+        });
+      }
+    }
+    return specs;
+  }
+};
+
+// src/commands/validate.ts
+import path10 from "path";
+import chalk5 from "chalk";
+
+// src/core/validation/validator.ts
+import { readFileSync as readFileSync3 } from "fs";
+import path9 from "path";
+
+// src/core/schemas/base.schema.ts
+import { z } from "zod";
+var ProjectTypeSchema = z.enum([
+  "wordpress-plugin",
+  "wordpress-theme",
+  "perfex-module",
+  "laravel-package",
+  "node-service",
+  "generic-webapp",
+  "backend-api",
+  "frontend-app",
+  "multi-stack"
+]);
+var SpecMetaSchema = z.object({
+  projectType: z.union([
+    ProjectTypeSchema,
+    z.array(ProjectTypeSchema)
+  ]).optional(),
+  domain: z.string().optional(),
+  stack: z.union([
+    z.string(),
+    z.array(z.string())
+  ]).optional()
+}).optional();
+var ScenarioSchema = z.object({
+  name: z.string(),
+  steps: z.array(z.string()).min(1)
+});
+var RequirementSchema = z.object({
+  id: z.string().optional(),
+  name: z.string(),
+  description: z.string(),
+  scenarios: z.array(ScenarioSchema).optional(),
+  constraints: z.array(z.string()).optional()
+});
+
+// src/core/schemas/spec.schema.ts
+import { z as z2 } from "zod";
+var SpecSchema = z2.object({
+  name: z2.string().min(1),
+  meta: SpecMetaSchema,
+  overview: z2.string().min(1),
+  requirements: z2.array(RequirementSchema).min(1),
+  metadata: z2.object({
+    version: z2.string().default("1.0.0"),
+    format: z2.literal("heraspec"),
+    sourcePath: z2.string().optional()
+  }).optional()
+});
+
+// src/core/schemas/change.schema.ts
+import { z as z3 } from "zod";
+var DeltaTypeSchema = z3.enum(["ADDED", "MODIFIED", "REMOVED"]);
+var DeltaRequirementSchema = z3.object({
+  type: DeltaTypeSchema,
+  requirement: z3.object({
+    id: z3.string().optional(),
+    name: z3.string(),
+    description: z3.string(),
+    scenarios: z3.array(z3.object({
+      name: z3.string(),
+      steps: z3.array(z3.string())
+    })).optional(),
+    constraints: z3.array(z3.string()).optional()
+  })
+});
+var ChangeSchema = z3.object({
+  name: z3.string(),
+  proposal: z3.string().min(1),
+  tasks: z3.array(z3.string()).optional(),
+  design: z3.string().optional()
+});
+
+// src/core/validation/validator.ts
+var Validator = class {
+  strictMode;
+  constructor(strictMode = false) {
+    this.strictMode = strictMode;
+  }
+  async validateSpec(filePath) {
+    const errors = [];
+    const warnings = [];
+    try {
+      const content = readFileSync3(filePath, "utf-8");
+      const parser = new MarkdownParser(content);
+      const specName = this.extractNameFromPath(filePath);
+      const spec = parser.parseSpec(specName);
+      const result = SpecSchema.safeParse(spec);
+      if (!result.success) {
+        result.error.errors.forEach((err) => {
+          errors.push(`${err.path.join(".")}: ${err.message}`);
+        });
+      }
+      if (spec.requirements.length === 0) {
+        errors.push("Spec must have at least one requirement");
+      }
+      for (const req of spec.requirements) {
+        if (!req.description || req.description.trim().length === 0) {
+          errors.push(`Requirement "${req.name}" must have a description`);
+        }
+        if (!req.scenarios || req.scenarios.length === 0) {
+          warnings.push(`Requirement "${req.name}" has no scenarios`);
+        }
+      }
+      return {
+        valid: errors.length === 0,
+        errors,
+        warnings
+      };
+    } catch (error) {
+      return {
+        valid: false,
+        errors: [error instanceof Error ? error.message : "Unknown error"],
+        warnings: []
+      };
+    }
+  }
+  async validateChange(changePath) {
+    const errors = [];
+    const warnings = [];
+    const suggestions = [];
+    const proposalPath = path9.join(changePath, "proposal.md");
+    if (!await FileSystemUtils.fileExists(proposalPath)) {
+      errors.push({
+        message: "Change must have a proposal.md file",
+        path: proposalPath,
+        suggestion: `Create proposal.md in ${changePath} with: # Change Proposal: [name]
+
+## Purpose
+[Description]
+
+## Scope
+[What will change]`,
+        autoFixable: false
+      });
+      suggestions.push(`Create proposal.md file at ${proposalPath}`);
+    }
+    const tasksPath = path9.join(changePath, "tasks.md");
+    if (!await FileSystemUtils.fileExists(tasksPath)) {
+      warnings.push({
+        message: "Change has no tasks.md file",
+        path: tasksPath,
+        suggestion: `Create tasks.md with implementation tasks grouped by project type and skill`,
+        autoFixable: false
+      });
+    }
+    const changeName = path9.basename(changePath);
+    const specsDir = path9.join(
+      ".",
+      HERASPEC_DIR_NAME,
+      SPECS_DIR_NAME,
+      changeName
+    );
+    if (await FileSystemUtils.fileExists(specsDir)) {
+      const deltaSpecs = await this.findDeltaSpecs(specsDir);
+      for (const specPath of deltaSpecs) {
+        const report = await this.validateDeltaSpec(specPath);
+        errors.push(...report.errors);
+        warnings.push(...report.warnings);
+        if (report.suggestions) {
+          suggestions.push(...report.suggestions);
+        }
+      }
+    } else {
+      warnings.push({
+        message: "No delta specs found for this change",
+        suggestion: `Create delta specs in ${specsDir}/spec.md using ADDED/MODIFIED/REMOVED sections`,
+        autoFixable: false
+      });
+    }
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+      suggestions: suggestions.length > 0 ? suggestions : void 0
+    };
+  }
+  async validateDeltaSpec(filePath) {
+    const errors = [];
+    const warnings = [];
+    const suggestions = [];
+    try {
+      const content = readFileSync3(filePath, "utf-8");
+      const parser = new MarkdownParser(content);
+      const delta = parser.parseDeltaSpec(content);
+      if (delta.added.length === 0 && delta.modified.length === 0 && delta.removed.length === 0) {
+        warnings.push({
+          message: "Delta spec has no changes",
+          suggestion: "Add at least one section: ## ADDED Requirements, ## MODIFIED Requirements, or ## REMOVED Requirements",
+          autoFixable: false
+        });
+      }
+      if (!content.includes("## ADDED") && !content.includes("## MODIFIED") && !content.includes("## REMOVED")) {
+        warnings.push({
+          message: "Delta spec may not follow proper format",
+          suggestion: "Use sections: ## ADDED Requirements, ## MODIFIED Requirements, ## REMOVED Requirements",
+          autoFixable: false
+        });
+      }
+      return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        suggestions: suggestions.length > 0 ? suggestions : void 0
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      const suggestion = this.getParseErrorSuggestion(errorMessage);
+      return {
+        valid: false,
+        errors: [{
+          message: errorMessage,
+          suggestion,
+          autoFixable: false
+        }],
+        warnings: [],
+        suggestions: suggestion ? [suggestion] : void 0
+      };
+    }
+  }
+  extractNameFromPath(filePath) {
+    const baseName = path9.basename(filePath, ".md");
+    return baseName === "spec" ? path9.basename(path9.dirname(filePath)) : baseName;
+  }
+  async findDeltaSpecs(dir) {
+    const specs = [];
+    const entries = await FileSystemUtils.readDirectory(dir);
+    for (const entry of entries) {
+      const entryPath = path9.join(dir, entry);
+      const stats = await FileSystemUtils.stat(entryPath);
+      if (stats.isDirectory()) {
+        const subSpecs = await this.findDeltaSpecs(entryPath);
+        specs.push(...subSpecs);
+      } else if (entry.endsWith(".md")) {
+        specs.push(entryPath);
+      }
+    }
+    return specs;
+  }
+};
+
+// src/commands/validate.ts
+var ValidateCommand = class {
+  async execute(itemName, options) {
+    const validator = new Validator(options?.strict || false);
+    if (!itemName) {
+      console.error("Error: Please specify a change or spec name");
+      console.log("Usage: heraspec validate <change-name>");
+      process.exitCode = 1;
+      return;
+    }
+    const changePath = path10.join(".", HERASPEC_DIR_NAME, CHANGES_DIR_NAME, itemName);
+    if (await FileSystemUtils.fileExists(changePath)) {
+      const report = await validator.validateChange(changePath);
+      this.printReport(itemName, report);
+      if (!report.valid) {
+        process.exitCode = 1;
+      }
+      return;
+    }
+    const specPath = this.findSpecPath(itemName);
+    if (specPath && await FileSystemUtils.fileExists(specPath)) {
+      const report = await validator.validateSpec(specPath);
+      this.printReport(itemName, report);
+      if (!report.valid) {
+        process.exitCode = 1;
+      }
+      return;
+    }
+    console.error(`Error: Change or spec "${itemName}" not found`);
+    process.exitCode = 1;
+  }
+  findSpecPath(specName) {
+    const basePath = path10.join(".", HERASPEC_DIR_NAME, SPECS_DIR_NAME);
+    return path10.join(basePath, `${specName}.md`);
+  }
+  printReport(itemName, report) {
+    console.log(`
+Validation Report: ${itemName}
+`);
+    console.log("\u2500".repeat(60));
+    if (report.valid) {
+      console.log(chalk5.green("\u2713 Valid"));
+    } else {
+      console.log(chalk5.red("\u2717 Invalid"));
+    }
+    if (report.errors && report.errors.length > 0) {
+      console.log(chalk5.red("\nErrors:"));
+      report.errors.forEach((err) => {
+        console.log(chalk5.red(`  \u2022 ${err.message || err}`));
+        if (err.suggestion) {
+          console.log(chalk5.gray(`    \u{1F4A1} Suggestion: ${err.suggestion}`));
+        }
+        if (err.path) {
+          console.log(chalk5.gray(`    \u{1F4CD} Path: ${err.path}`));
+        }
+      });
+    }
+    if (report.warnings && report.warnings.length > 0) {
+      console.log(chalk5.yellow("\nWarnings:"));
+      report.warnings.forEach((warn) => {
+        console.log(chalk5.yellow(`  \u2022 ${warn.message || warn}`));
+        if (warn.suggestion) {
+          console.log(chalk5.gray(`    \u{1F4A1} Suggestion: ${warn.suggestion}`));
+        }
+        if (warn.path) {
+          console.log(chalk5.gray(`    \u{1F4CD} Path: ${warn.path}`));
+        }
+      });
+    }
+    if (report.suggestions && report.suggestions.length > 0) {
+      console.log(chalk5.cyan("\n\u{1F4A1} Quick Fixes:"));
+      report.suggestions.forEach((suggestion) => {
+        console.log(chalk5.cyan(`  \u2022 ${suggestion}`));
+      });
+    }
+    if (!report.valid && report.errors && report.errors.length > 0) {
+      console.log(chalk5.gray("\n\u{1F4DD} Next Steps:"));
+      console.log(chalk5.gray("  1. Review errors above"));
+      console.log(chalk5.gray("  2. Apply suggested fixes"));
+      console.log(chalk5.gray("  3. Run validation again: heraspec validate " + itemName));
+    }
+    console.log("\n" + "\u2500".repeat(60) + "\n");
+  }
+};
+
+// src/commands/skill.ts
+import path11 from "path";
+import ora4 from "ora";
+
+// src/core/templates/skills-template-map.ts
+var SKILL_TEMPLATE_MAP = {
+  // Cross-cutting skills
+  "ui-ux": {
+    templateFileName: "ui-ux-skill.md",
+    isCrossCutting: true,
+    resourceDirs: ["scripts", "templates", "data"]
+  },
+  "documents": {
+    templateFileName: "documents-skill.md",
+    isCrossCutting: true
+  },
+  "content-optimization": {
+    templateFileName: "content-optimization-skill.md",
+    isCrossCutting: true
+  },
+  "unit-test": {
+    templateFileName: "unit-test-skill.md",
+    isCrossCutting: true
+  },
+  "integration-test": {
+    templateFileName: "integration-test-skill.md",
+    isCrossCutting: true
+  },
+  "e2e-test": {
+    templateFileName: "e2e-test-skill.md",
+    isCrossCutting: true
+  },
+  "suggestion": {
+    templateFileName: "suggestion-skill.md",
+    isCrossCutting: true
+  },
+  // Perfex module skills
+  "perfex-module:module-codebase": {
+    templateFileName: "module-codebase-skill.md",
+    isCrossCutting: false,
+    projectType: "perfex-module"
+  }
+};
+function getSkillTemplateInfo(skillName, projectType) {
+  if (projectType) {
+    const key = `${projectType}:${skillName}`;
+    if (SKILL_TEMPLATE_MAP[key]) {
+      return SKILL_TEMPLATE_MAP[key];
+    }
+  }
+  if (SKILL_TEMPLATE_MAP[skillName]) {
+    return SKILL_TEMPLATE_MAP[skillName];
+  }
+  return null;
+}
+function getAllSkillTemplates() {
+  const result = [];
+  for (const [key, info] of Object.entries(SKILL_TEMPLATE_MAP)) {
+    if (info.isCrossCutting) {
+      result.push({ skillName: key, info });
+    } else {
+      const [projectType, skillName] = key.split(":");
+      result.push({ skillName, projectType, info });
+    }
+  }
+  return result;
+}
+
+// src/commands/skill.ts
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+async function getCoreTemplatesDir() {
+  const possiblePaths = [];
+  try {
+    const packageJsonPath2 = require2.resolve("../package.json");
+    const packageDir = path11.dirname(packageJsonPath2);
+    possiblePaths.push(
+      join(packageDir, "src", "core", "templates", "skills"),
+      // Source (when linked, this is the actual source)
+      join(packageDir, "dist", "core", "templates", "skills")
+      // Built (templates copied during build)
+    );
+  } catch {
+  }
+  try {
+    const packageJsonPath2 = require2.resolve("heraspec/package.json");
+    const packageDir = path11.dirname(packageJsonPath2);
+    possiblePaths.push(
+      join(packageDir, "dist", "core", "templates", "skills"),
+      // Built
+      join(packageDir, "src", "core", "templates", "skills")
+      // Source (if available)
+    );
+  } catch {
+  }
+  possiblePaths.push(
+    // Source version (for development) - when running from source: src/commands/skill.ts
+    join(__dirname, "..", "..", "src", "core", "templates", "skills"),
+    // Built version - when running from built: dist/commands/skill.js
+    join(__dirname, "..", "core", "templates", "skills"),
+    // Alternative: from project root (when running from HeraSpec source)
+    join(process.cwd(), "src", "core", "templates", "skills")
+  );
+  for (const possiblePath of possiblePaths) {
+    if (await FileSystemUtils.fileExists(possiblePath)) {
+      return possiblePath;
+    }
+  }
+  return null;
+}
+var SkillCommand = class {
+  async list(projectPath = ".") {
+    const skills = await SkillManager.listSkills(projectPath);
+    if (skills.length === 0) {
+      console.log("No skills found. Skills will be created as needed.");
+      console.log("See docs/SKILLS_STRUCTURE_PROPOSAL.md for skill structure.");
+      return;
+    }
+    console.log("\nAvailable Skills:\n");
+    console.log("\u2550".repeat(60));
+    const byProjectType = {};
+    const crossCutting = [];
+    for (const skill of skills) {
+      if (skill.projectType) {
+        if (!byProjectType[skill.projectType]) {
+          byProjectType[skill.projectType] = [];
+        }
+        byProjectType[skill.projectType].push({
+          skillName: skill.skillName,
+          path: skill.path
+        });
+      } else {
+        crossCutting.push({
+          skillName: skill.skillName,
+          path: skill.path
+        });
+      }
+    }
+    for (const [projectType, projectSkills] of Object.entries(byProjectType)) {
+      console.log(`
+\u{1F4E6} ${projectType}:`);
+      for (const skill of projectSkills) {
+        console.log(`   \u2022 ${skill.skillName}`);
+      }
+    }
+    if (crossCutting.length > 0) {
+      console.log(`
+\u{1F527} Cross-cutting skills:`);
+      for (const skill of crossCutting) {
+        console.log(`   \u2022 ${skill.skillName}`);
+      }
+    }
+    console.log("\n" + "\u2550".repeat(60) + "\n");
+  }
+  async show(skillName, projectType, projectPath = ".") {
+    if (!skillName) {
+      console.error("Error: Please specify a skill name");
+      console.log("Usage: heraspec skill show <skill-name> [--project-type <type>]");
+      process.exitCode = 1;
+      return;
+    }
+    let skillInfo = null;
+    if (projectType) {
+      skillInfo = await SkillManager.loadSkill(projectType, skillName, projectPath);
+    } else {
+      const skills = await SkillManager.listSkills(projectPath);
+      const found = skills.find((s) => s.skillName === skillName);
+      if (found) {
+        try {
+          skillInfo = SkillParser.parseSkill(found.path, skillName);
+        } catch (error) {
+          console.error(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+          process.exitCode = 1;
+          return;
+        }
+      }
+    }
+    if (!skillInfo) {
+      console.error(`Error: Skill "${skillName}" not found`);
+      if (projectType) {
+        console.log(`Searched in: heraspec/skills/${projectType}/${skillName}/`);
+      } else {
+        console.log("Searched in: heraspec/skills/");
+      }
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`
+\u{1F4DA} Skill: ${skillInfo.name}
+`);
+    console.log("\u2550".repeat(60));
+    console.log(`
+\u{1F4CD} Path: ${skillInfo.skillPath}
+`);
+    if (skillInfo.purpose) {
+      console.log("## Purpose");
+      console.log(skillInfo.purpose);
+      console.log();
+    }
+    if (skillInfo.whenToUse.length > 0) {
+      console.log("## When to Use");
+      skillInfo.whenToUse.forEach((item) => {
+        console.log(`- ${item}`);
+      });
+      console.log();
+    }
+    if (skillInfo.steps.length > 0) {
+      console.log("## Steps");
+      skillInfo.steps.forEach((step, index) => {
+        console.log(`${index + 1}. ${step}`);
+      });
+      console.log();
+    }
+    if (skillInfo.inputs.length > 0) {
+      console.log("## Inputs");
+      skillInfo.inputs.forEach((input) => {
+        console.log(`- ${input}`);
+      });
+      console.log();
+    }
+    if (skillInfo.outputs.length > 0) {
+      console.log("## Outputs");
+      skillInfo.outputs.forEach((output) => {
+        console.log(`- ${output}`);
+      });
+      console.log();
+    }
+    if (skillInfo.templates.length > 0) {
+      console.log("## Available Templates");
+      skillInfo.templates.forEach((template) => {
+        console.log(`- ${template}`);
+      });
+      console.log();
+    }
+    if (skillInfo.scripts.length > 0) {
+      console.log("## Available Scripts");
+      skillInfo.scripts.forEach((script) => {
+        console.log(`- ${script}`);
+      });
+      console.log();
+    }
+    if (skillInfo.toneAndRules.limitations && skillInfo.toneAndRules.limitations.length > 0) {
+      console.log("## Limitations");
+      skillInfo.toneAndRules.limitations.forEach((limitation) => {
+        console.log(`- ${limitation}`);
+      });
+      console.log();
+    }
+    const skillMdPath = path11.join(skillInfo.skillPath, "skill.md");
+    if (await FileSystemUtils.fileExists(skillMdPath)) {
+      console.log("\u2550".repeat(60));
+      console.log("\n## Full skill.md Content\n");
+      const content = await FileSystemUtils.readFile(skillMdPath);
+      console.log(content);
+    }
+    console.log("\n" + "\u2550".repeat(60) + "\n");
+  }
+  async repair(projectPath = ".") {
+    const spinner = ora4("Repairing skills structure...").start();
+    try {
+      const skillsDir = path11.join(projectPath, HERASPEC_DIR_NAME, SKILLS_DIR_NAME);
+      if (!await FileSystemUtils.fileExists(skillsDir)) {
+        spinner.fail('Skills directory does not exist. Run "heraspec init" first.');
+        process.exitCode = 1;
+        return;
+      }
+      const skills = await SkillManager.listSkills(projectPath);
+      let fixed = 0;
+      let errors = 0;
+      for (const skill of skills) {
+        const skillPath = skill.path;
+        const skillMdPath = path11.join(skillPath, "skill.md");
+        if (!await FileSystemUtils.fileExists(skillMdPath)) {
+          spinner.warn(`Missing skill.md in ${skillPath}`);
+          errors++;
+          continue;
+        }
+        const standardDirs = ["templates", "scripts", "examples"];
+        for (const dir of standardDirs) {
+          const dirPath = path11.join(skillPath, dir);
+          if (!await FileSystemUtils.fileExists(dirPath)) {
+            await FileSystemUtils.createDirectory(dirPath);
+            fixed++;
+          }
+        }
+        try {
+          const content = await FileSystemUtils.readFile(skillMdPath);
+          if (!content.includes("## Purpose") && !content.includes("# Skill:")) {
+            spinner.warn(`Invalid skill.md structure in ${skillPath}`);
+          }
+        } catch (error) {
+          spinner.warn(`Cannot read skill.md in ${skillPath}: ${error instanceof Error ? error.message : "Unknown error"}`);
+          errors++;
+        }
+      }
+      if (errors === 0 && fixed === 0) {
+        spinner.succeed("All skills are properly structured");
+      } else {
+        spinner.succeed(`Repaired ${fixed} issues, found ${errors} errors`);
+      }
+    } catch (error) {
+      spinner.fail(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+      process.exitCode = 1;
+    }
+  }
+  async add(skillName, projectType, projectPath = ".") {
+    if (!skillName) {
+      console.error("Error: Please specify a skill name");
+      console.log("Usage: heraspec skills add <skill-name> [--project-type <type>]");
+      process.exitCode = 1;
+      return;
+    }
+    const spinner = ora4(`Adding skill "${skillName}"...`).start();
+    try {
+      const templateInfo = getSkillTemplateInfo(skillName, projectType);
+      if (!templateInfo) {
+        spinner.fail(`Skill template "${skillName}" not found`);
+        console.log("\nAvailable skills:");
+        const allTemplates = getAllSkillTemplates();
+        for (const { skillName: name, projectType: pt } of allTemplates) {
+          if (pt) {
+            console.log(`  - ${name} (projectType: ${pt})`);
+          } else {
+            console.log(`  - ${name} (cross-cutting)`);
+          }
+        }
+        process.exitCode = 1;
+        return;
+      }
+      const skillsDir = path11.join(projectPath, HERASPEC_DIR_NAME, SKILLS_DIR_NAME);
+      let destPath;
+      if (templateInfo.isCrossCutting) {
+        destPath = path11.join(skillsDir, skillName);
+      } else {
+        if (!templateInfo.projectType) {
+          spinner.fail("Project type is required for this skill");
+          process.exitCode = 1;
+          return;
+        }
+        destPath = path11.join(skillsDir, templateInfo.projectType, skillName);
+      }
+      const isUpdate = await FileSystemUtils.fileExists(destPath);
+      if (isUpdate) {
+        spinner.info(`Skill "${skillName}" already exists at ${destPath}`);
+        spinner.start(`Removing old version to update with latest...`);
+        try {
+          await FileSystemUtils.removeDirectory(destPath, true);
+          spinner.succeed(`Removed old skill "${skillName}"`);
+        } catch (error) {
+          spinner.fail(`Failed to remove old skill: ${error instanceof Error ? error.message : "Unknown error"}`);
+          process.exitCode = 1;
+          return;
+        }
+        spinner.start(`Adding updated skill "${skillName}"...`);
+      }
+      await FileSystemUtils.createDirectory(destPath);
+      const coreTemplatesDir = await getCoreTemplatesDir();
+      if (!coreTemplatesDir) {
+        spinner.fail("Cannot find HeraSpec templates directory. Make sure you are running from HeraSpec project or have templates installed.");
+        process.exitCode = 1;
+        return;
+      }
+      const templateFile = path11.join(coreTemplatesDir, templateInfo.templateFileName);
+      if (!await FileSystemUtils.fileExists(templateFile)) {
+        spinner.fail(`Template file not found: ${templateFile}`);
+        process.exitCode = 1;
+        return;
+      }
+      await FileSystemUtils.copyFile(templateFile, path11.join(destPath, "skill.md"));
+      if (templateInfo.resourceDirs) {
+        for (const resourceDir of templateInfo.resourceDirs) {
+          const srcResourceDir = path11.join(coreTemplatesDir, resourceDir);
+          const destResourceDir = path11.join(destPath, resourceDir);
+          if (await FileSystemUtils.fileExists(srcResourceDir)) {
+            await FileSystemUtils.copyDirectory(srcResourceDir, destResourceDir);
+          }
+        }
+      }
+      await FileSystemUtils.createDirectory(path11.join(destPath, "templates"));
+      await FileSystemUtils.createDirectory(path11.join(destPath, "scripts"));
+      await FileSystemUtils.createDirectory(path11.join(destPath, "examples"));
+      const successMessage = isUpdate ? `Skill "${skillName}" updated successfully` : `Skill "${skillName}" added successfully`;
+      spinner.succeed(successMessage);
+      console.log(`
+\u{1F4CD} Location: ${destPath}`);
+      if (isUpdate) {
+        console.log(`
+\u2728 Skill has been updated with latest features and improvements.`);
+      }
+      console.log(`
+\u{1F4A1} Run "heraspec skill show ${skillName}${projectType ? ` --project-type ${projectType}` : ""}" to view details
+`);
+    } catch (error) {
+      spinner.fail(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+      process.exitCode = 1;
+    }
+  }
+};
+
+// src/commands/helper.ts
+import chalk6 from "chalk";
+var HelperCommand = class {
+  async execute() {
+    console.log(chalk6.cyan.bold("\n\u{1F4DA} HeraSpec Helper - Usage Guide\n"));
+    console.log("\u2550".repeat(70) + "\n");
+    this.showQuickStart();
+    this.showCommands();
+    this.showExamplePrompts();
+    this.showWorkflow();
+    this.showTips();
+    console.log("\n" + "\u2550".repeat(70));
+    console.log(chalk6.gray("\n\u{1F4A1} Tip: See details at docs/README.md (available in multiple languages)\n"));
+  }
+  showQuickStart() {
+    console.log(chalk6.yellow.bold("\u{1F680} Quick Start\n"));
+    console.log(chalk6.white("1. Initialize a new project:"));
+    console.log(chalk6.gray("   cd my-project"));
+    console.log(chalk6.cyan("   heraspec init\n"));
+    console.log(chalk6.white("2. Configure project.md:"));
+    console.log(chalk6.gray("   Edit heraspec/project.md with your project information\n"));
+    console.log(chalk6.white("3. Create your first change (using AI):"));
+    console.log(chalk6.cyan('   "Create a HeraSpec change to add feature X"\n'));
+    console.log(chalk6.white("4. View list:"));
+    console.log(chalk6.cyan("   heraspec list\n"));
+    console.log("\u2500".repeat(70) + "\n");
+  }
+  showCommands() {
+    console.log(chalk6.yellow.bold("\u26A1 Main CLI Commands\n"));
+    const commands = [
+      { cmd: "heraspec init [path]", desc: "Initialize HeraSpec in project" },
+      { cmd: "heraspec list", desc: "List changes (default)" },
+      { cmd: "heraspec list --specs", desc: "List specs" },
+      { cmd: "heraspec show [name]", desc: "Show change or spec details" },
+      { cmd: "heraspec validate [name]", desc: "Validate change or spec" },
+      { cmd: "heraspec archive [name]", desc: "Archive completed change" },
+      { cmd: "heraspec restore [name]", desc: "Restore change from archive" },
+      { cmd: "heraspec skill list", desc: "List available skills" },
+      { cmd: "heraspec skill show <name>", desc: "Show skill details" },
+      { cmd: "heraspec make docs", desc: "Generate product documentation" },
+      { cmd: "heraspec make docs --agent <name>", desc: "Generate docs with AI agent" },
+      { cmd: "heraspec make test", desc: "Generate test cases from specs" },
+      { cmd: "heraspec make test --type <type>", desc: "Generate tests (unit/integration/e2e)" },
+      { cmd: "heraspec suggest", desc: "Suggest new features for project" },
+      { cmd: "heraspec view", desc: "View dashboard overview" },
+      { cmd: "heraspec helper", desc: "Show this guide" }
+    ];
+    commands.forEach(({ cmd, desc }) => {
+      console.log(chalk6.cyan(`  ${cmd.padEnd(35)}`) + chalk6.white(desc));
+    });
+    console.log("\n" + "\u2500".repeat(70) + "\n");
+  }
+  showExamplePrompts() {
+    console.log(chalk6.yellow.bold("\u{1F4AC} Example Prompts for AI\n"));
+    console.log(chalk6.white.bold("1. Simple Change Creation:\n"));
+    console.log(chalk6.gray('   "Create a HeraSpec change to add 2FA authentication feature"\n'));
+    console.log(chalk6.gray('   "Create HeraSpec change for order management module"\n'));
+    console.log(chalk6.white.bold("2. Create Change Based on project.md:\n"));
+    console.log(chalk6.gray('   "Read heraspec/project.md and create HeraSpec changes for all\n'));
+    console.log(chalk6.gray('    features mentioned in it"\n'));
+    console.log(chalk6.gray('   "Based on project.md, create changes to implement by phase"\n'));
+    console.log(chalk6.white.bold("3. Detailed Change Creation:\n"));
+    console.log(chalk6.gray('   "Create HeraSpec change with the following steps:\n'));
+    console.log(chalk6.gray("    1. Read and analyze heraspec/project.md\n"));
+    console.log(chalk6.gray("    2. Identify features to build\n"));
+    console.log(chalk6.gray("    3. For each feature, create a separate change\n"));
+    console.log(chalk6.gray("    4. Each change needs proposal.md, tasks.md, specs/\n"));
+    console.log(chalk6.gray('    5. Follow conventions in project.md"\n'));
+    console.log(chalk6.white.bold("4. Prompt With Project Type and Skill:\n"));
+    console.log(chalk6.gray('   "Create change for WordPress plugin with skill admin-settings-page"\n'));
+    console.log(chalk6.gray('   "Create change for Perfex module with skill module-codebase"\n'));
+    console.log(chalk6.gray('   "Create UI/UX change with skill ui-ux for admin interface"\n'));
+    console.log(chalk6.white.bold("5. View and Validate:\n"));
+    console.log(chalk6.gray('   "View change add-user-auth"\n'));
+    console.log(chalk6.gray('   "Validate change add-user-auth --strict"\n'));
+    console.log(chalk6.gray('   "List all changes"\n'));
+    console.log(chalk6.white.bold("6. Implementation:\n"));
+    console.log(chalk6.gray('   "Specs approved, start implementing change add-user-auth"\n'));
+    console.log(chalk6.gray('   "Execute tasks in change add-user-auth"\n'));
+    console.log(chalk6.white.bold("7. Generate Documentation:\n"));
+    console.log(chalk6.gray('   "Generate product documentation from specs"\n'));
+    console.log(chalk6.gray("   heraspec make docs\n"));
+    console.log(chalk6.gray('   "Generate docs with specific AI agent"\n'));
+    console.log(chalk6.gray("   heraspec make docs --agent chatgpt\n"));
+    console.log(chalk6.gray("   heraspec make docs --agent claude\n"));
+    console.log("\u2500".repeat(70) + "\n");
+  }
+  showWorkflow() {
+    console.log(chalk6.yellow.bold("\u{1F504} Workflow\n"));
+    const steps = [
+      {
+        step: "1. Create Change",
+        actions: [
+          "AI or you create change directory",
+          "Write proposal.md describing purpose",
+          "Create tasks.md with task list",
+          "Write delta specs in specs/"
+        ],
+        prompt: '"Create HeraSpec change to..."'
+      },
+      {
+        step: "2. Refine Specs",
+        actions: [
+          "Review: heraspec show <name>",
+          "Ask AI to edit if needed",
+          "Validate: heraspec validate <name>"
+        ],
+        prompt: '"Edit specs in change..."'
+      },
+      {
+        step: "3. Approval",
+        actions: ['Wait for user: "Specs approved."'],
+        prompt: 'You confirm: "Specs approved."'
+      },
+      {
+        step: "4. Implementation",
+        actions: [
+          "AI reads tasks.md and skill.md",
+          "Execute each task",
+          "Mark completed: - [x]"
+        ],
+        prompt: '"Specs approved, implement change..."'
+      },
+      {
+        step: "5. Archive",
+        actions: [
+          "Review: heraspec show <name>",
+          "Archive: heraspec archive <name> --yes",
+          "Specs merged into source specs"
+        ],
+        prompt: "heraspec archive <name> --yes"
+      },
+      {
+        step: "6. Generate Documentation",
+        actions: [
+          "Generate product docs: heraspec make docs",
+          "With specific agent: heraspec make docs --agent <name>",
+          "Output: documentation/product-documentation.txt"
+        ],
+        prompt: "heraspec make docs --agent chatgpt"
+      }
+    ];
+    steps.forEach(({ step, actions, prompt }) => {
+      console.log(chalk6.cyan.bold(`  ${step}`));
+      actions.forEach((action) => {
+        console.log(chalk6.white(`    \u2022 ${action}`));
+      });
+      console.log(chalk6.gray(`    \u{1F4AC} ${prompt}
+`));
+    });
+    console.log("\u2500".repeat(70) + "\n");
+  }
+  showTips() {
+    console.log(chalk6.yellow.bold("\u{1F4A1} Tips & Best Practices\n"));
+    const tips = [
+      "Always read heraspec/project.md before creating change",
+      "Use Skills system when implementing (each task has skill tag)",
+      "Validate specs before requesting approval",
+      "One change should focus on one specific feature",
+      "Name change: kebab-case, verb-led (add-, create-, implement-)",
+      "Delta specs only change in change folder",
+      "Do not edit source-of-truth specs directly",
+      "Archive change after completion to merge specs",
+      "Use heraspec skill list to view available skills",
+      "UI/UX tasks: Use search scripts in skill ui-ux",
+      "Generate product docs: heraspec make docs (default agent: chatgpt)",
+      "Specify AI agent: heraspec make docs --agent <name> (chatgpt, claude, etc.)",
+      "Generate tests: heraspec make test (default: unit)",
+      "Test types: unit (individual functions), integration (components), e2e (user flows)",
+      "Generate code: heraspec make code (generates code skeletons from specs)",
+      "Validate with suggestions: heraspec validate <name> (includes fix suggestions)",
+      "Get feature suggestions: heraspec suggest (analyzes project and suggests enhancements)",
+      "Use test skills: unit-test, integration-test, e2e-test for test implementation"
+    ];
+    tips.forEach((tip) => {
+      console.log(chalk6.white(`  \u2022 ${tip}`));
+    });
+    console.log("");
+  }
+};
+
+// src/commands/make-docs.ts
+import path12 from "path";
+import chalk7 from "chalk";
+import ora5 from "ora";
+var MakeDocsCommand = class {
+  async execute(projectPath = ".", agent = "chatgpt") {
+    const spinner = ora5(`Generating product documentation (Agent: ${agent})...`).start();
+    try {
+      const resolvedPath = path12.resolve(projectPath);
+      const specsDir = path12.join(resolvedPath, HERASPEC_DIR_NAME, SPECS_DIR_NAME);
+      const docsDir = path12.join(resolvedPath, "documentation");
+      const projectMdPath = path12.join(resolvedPath, HERASPEC_DIR_NAME, HERASPEC_MARKERS.PROJECT_MD);
+      if (!await FileSystemUtils.fileExists(specsDir)) {
+        spinner.fail('Specs directory not found. Run "heraspec init" first.');
+        process.exitCode = 1;
+        return;
+      }
+      await FileSystemUtils.createDirectory(docsDir);
+      let projectInfo = {};
+      if (await FileSystemUtils.fileExists(projectMdPath)) {
+        const projectContent = await FileSystemUtils.readFile(projectMdPath);
+        projectInfo = this.extractProjectInfo(projectContent);
+      }
+      const specFiles = await this.findSpecFiles(specsDir);
+      if (specFiles.length === 0) {
+        spinner.warn('No specs found. Create specs first using "heraspec list --specs".');
+        return;
+      }
+      const specs = await this.readSpecs(specFiles);
+      const docContent = this.generateProductDocumentation(specs, projectInfo, agent);
+      const docFilePath = path12.join(docsDir, "product-documentation.txt");
+      await FileSystemUtils.writeFile(docFilePath, docContent);
+      spinner.succeed(`Product documentation generated: ${docFilePath}`);
+      console.log(chalk7.gray(`
+Found ${specFiles.length} feature(s)`));
+    } catch (error) {
+      spinner.fail(`Error: ${error.message}`);
+      process.exitCode = 1;
+      throw error;
+    }
+  }
+  /**
+   * Extract project information from project.md
+   */
+  extractProjectInfo(projectContent) {
+    const info = {};
+    const nameMatch = projectContent.match(/^#\s+(.+)$/m);
+    if (nameMatch) {
+      info.name = nameMatch[1].trim();
+    }
+    const lines = projectContent.split("\n");
+    let descriptionStart = false;
+    const descriptionLines = [];
+    for (const line of lines) {
+      if (line.startsWith("#") && !descriptionStart) {
+        descriptionStart = true;
+        continue;
+      }
+      if (descriptionStart && line.trim() && !line.startsWith("#")) {
+        descriptionLines.push(line.trim());
+        if (descriptionLines.length >= 3) break;
+      }
+    }
+    if (descriptionLines.length > 0) {
+      info.description = descriptionLines.join(" ");
+    }
+    return info;
+  }
+  /**
+   * Find all spec files recursively
+   */
+  async findSpecFiles(specsDir) {
+    const specFiles = [];
+    await this.findSpecFilesRecursive(specsDir, specFiles);
+    return specFiles.sort();
+  }
+  /**
+   * Recursively find spec files
+   */
+  async findSpecFilesRecursive(dir, files) {
+    const fs2 = await import("fs/promises");
+    const entries = await fs2.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const entryPath = path12.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await this.findSpecFilesRecursive(entryPath, files);
+      } else if (entry.name.endsWith(".md")) {
+        files.push(entryPath);
+      }
+    }
+  }
+  /**
+   * Read all spec files
+   */
+  async readSpecs(specFiles) {
+    const specs = [];
+    for (const specFile of specFiles) {
+      const content = await FileSystemUtils.readFile(specFile);
+      const name = this.extractFeatureName(specFile, content);
+      specs.push({
+        path: specFile,
+        content,
+        name
+      });
+    }
+    return specs;
+  }
+  /**
+   * Extract feature name from spec file
+   */
+  extractFeatureName(filePath, content) {
+    const headingMatch = content.match(/^#+\s+(.+)$/m);
+    if (headingMatch) {
+      return headingMatch[1].trim();
+    }
+    return path12.basename(filePath, ".md").split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+  }
+  /**
+   * Generate product documentation from specs
+   */
+  generateProductDocumentation(specs, projectInfo, agent = "chatgpt") {
+    const lines = [];
+    const productName = projectInfo.name || "Product";
+    lines.push(`# ${productName}`);
+    lines.push("");
+    if (projectInfo.description) {
+      lines.push(projectInfo.description);
+      lines.push("");
+    }
+    lines.push("---");
+    lines.push("");
+    lines.push("## Overview");
+    lines.push("");
+    lines.push(`This product includes ${specs.length} main feature${specs.length > 1 ? "s" : ""}:`);
+    lines.push("");
+    specs.forEach((spec, index) => {
+      lines.push(`${index + 1}. ${spec.name}`);
+    });
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    lines.push("## Features");
+    lines.push("");
+    specs.forEach((spec, index) => {
+      const featureInfo = this.extractFeatureInfo(spec.content);
+      lines.push(`### ${index + 1}. ${spec.name}`);
+      lines.push("");
+      if (featureInfo.description) {
+        lines.push(featureInfo.description);
+        lines.push("");
+      }
+      if (featureInfo.capabilities.length > 0) {
+        lines.push("**Key Capabilities:**");
+        lines.push("");
+        featureInfo.capabilities.forEach((cap) => {
+          lines.push(`- ${cap}`);
+        });
+        lines.push("");
+      }
+      if (featureInfo.useCases.length > 0) {
+        lines.push("**Use Cases:**");
+        lines.push("");
+        featureInfo.useCases.forEach((useCase) => {
+          lines.push(`- ${useCase}`);
+        });
+        lines.push("");
+      }
+      if (index < specs.length - 1) {
+        lines.push("---");
+        lines.push("");
+      }
+    });
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    lines.push(`*This documentation is auto-generated from product specifications using ${agent}.*`);
+    lines.push("");
+    return lines.join("\n");
+  }
+  /**
+   * Extract user-friendly information from spec content
+   */
+  extractFeatureInfo(content) {
+    const info = {
+      description: "",
+      capabilities: [],
+      useCases: []
+    };
+    const lines = content.split("\n");
+    let inPurpose = false;
+    let inRequirements = false;
+    let inScenarios = false;
+    let currentSection = "";
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+      if (trimmed.match(/^##+\s+Purpose/i)) {
+        inPurpose = true;
+        inRequirements = false;
+        inScenarios = false;
+        continue;
+      } else if (trimmed.match(/^##+\s+Requirements?/i)) {
+        inPurpose = false;
+        inRequirements = true;
+        inScenarios = false;
+        continue;
+      } else if (trimmed.match(/^##+\s+Scenarios?/i)) {
+        inPurpose = false;
+        inRequirements = false;
+        inScenarios = true;
+        continue;
+      } else if (trimmed.match(/^##+/)) {
+        inPurpose = false;
+        inRequirements = false;
+        inScenarios = false;
+        continue;
+      }
+      if (inPurpose && trimmed && !trimmed.startsWith("#")) {
+        if (!info.description) {
+          info.description = trimmed;
+        } else if (info.description.length < 300) {
+          info.description += " " + trimmed;
+        }
+      }
+      if (inRequirements && trimmed.startsWith("-")) {
+        const requirement = trimmed.replace(/^-\s*/, "").trim();
+        if (requirement) {
+          const userFriendly = this.makeUserFriendly(requirement);
+          info.capabilities.push(userFriendly);
+        }
+      }
+      if (inScenarios && trimmed.match(/^[*-]\s*.+:/)) {
+        const scenario = trimmed.replace(/^[*-]\s*/, "").split(":")[0].trim();
+        if (scenario) {
+          const userFriendly = this.makeUserFriendly(scenario);
+          info.useCases.push(userFriendly);
+        }
+      }
+    }
+    if (!info.description) {
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed && !trimmed.startsWith("#") && trimmed.length > 20) {
+          info.description = trimmed;
+          break;
+        }
+      }
+    }
+    return info;
+  }
+  /**
+   * Make technical text more user-friendly
+   */
+  makeUserFriendly(text) {
+    let result = text.replace(/\([^)]*\)/g, "").replace(/\[([^\]]+)\]/g, "$1").replace(/\{([^}]+)\}/g, "$1").replace(/\b(GET|POST|PUT|DELETE|API|REST|HTTP)\b/gi, "").replace(/\b(endpoint|route|method|parameter|query|body)\b/gi, "").trim();
+    if (result) {
+      result = result.charAt(0).toUpperCase() + result.slice(1);
+    }
+    result = result.replace(/\s+/g, " ");
+    return result;
+  }
+};
+
+// src/commands/make-test.ts
+import path13 from "path";
+import chalk8 from "chalk";
+import ora6 from "ora";
+var MakeTestCommand = class {
+  async execute(projectPath = ".", testType = "unit") {
+    const spinner = ora6(`Generating ${testType} tests...`).start();
+    try {
+      const resolvedPath = path13.resolve(projectPath);
+      const specsDir = path13.join(resolvedPath, HERASPEC_DIR_NAME, SPECS_DIR_NAME);
+      const projectMdPath = path13.join(resolvedPath, HERASPEC_DIR_NAME, HERASPEC_MARKERS.PROJECT_MD);
+      if (!await FileSystemUtils.fileExists(specsDir)) {
+        spinner.fail('Specs directory not found. Run "heraspec init" first.');
+        process.exitCode = 1;
+        return;
+      }
+      const testDir = this.getTestDirectory(resolvedPath, testType);
+      await FileSystemUtils.createDirectory(testDir);
+      let projectInfo = {};
+      if (await FileSystemUtils.fileExists(projectMdPath)) {
+        const projectContent = await FileSystemUtils.readFile(projectMdPath);
+        projectInfo = this.extractProjectInfo(projectContent);
+      }
+      const specFiles = await this.findSpecFiles(specsDir);
+      if (specFiles.length === 0) {
+        spinner.warn('No specs found. Create specs first using "heraspec list --specs".');
+        return;
+      }
+      const specs = await this.readSpecs(specFiles);
+      const testFilesCreated = await this.generateTestFiles(specs, testDir, testType, projectInfo);
+      spinner.succeed(`Generated ${testFilesCreated.length} test file(s) in ${testDir}`);
+      console.log(chalk8.gray(`
+Test type: ${testType}`));
+      console.log(chalk8.gray(`Specs analyzed: ${specFiles.length}`));
+    } catch (error) {
+      spinner.fail(`Error: ${error.message}`);
+      process.exitCode = 1;
+      throw error;
+    }
+  }
+  /**
+   * Get test directory path based on project type and test type
+   */
+  getTestDirectory(projectPath, testType) {
+    const testDirs = {
+      unit: "tests/unit",
+      integration: "tests/integration",
+      e2e: "tests/e2e"
+    };
+    const baseDir = testDirs[testType] || "tests";
+    return path13.join(projectPath, baseDir);
+  }
+  /**
+   * Extract project information from project.md
+   */
+  extractProjectInfo(projectContent) {
+    const info = {};
+    const projectTypeMatch = projectContent.match(/project[-\s]type[s]?[:\s]+([^\n]+)/i);
+    if (projectTypeMatch) {
+      info.projectType = projectTypeMatch[1].trim();
+    }
+    const stackMatch = projectContent.match(/tech[-\s]stack[:\s]+([^\n]+)/i);
+    if (stackMatch) {
+      info.stack = stackMatch[1].split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    }
+    return info;
+  }
+  /**
+   * Find all spec files recursively
+   */
+  async findSpecFiles(specsDir) {
+    const specFiles = [];
+    await this.findSpecFilesRecursive(specsDir, specFiles);
+    return specFiles.sort();
+  }
+  /**
+   * Recursively find spec files
+   */
+  async findSpecFilesRecursive(dir, files) {
+    const fs2 = await import("fs/promises");
+    const entries = await fs2.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const entryPath = path13.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await this.findSpecFilesRecursive(entryPath, files);
+      } else if (entry.name.endsWith(".md")) {
+        files.push(entryPath);
+      }
+    }
+  }
+  /**
+   * Read all spec files
+   */
+  async readSpecs(specFiles) {
+    const specs = [];
+    for (const specFile of specFiles) {
+      const content = await FileSystemUtils.readFile(specFile);
+      const name = this.extractFeatureName(specFile, content);
+      specs.push({
+        path: specFile,
+        content,
+        name
+      });
+    }
+    return specs;
+  }
+  /**
+   * Extract feature name from spec file
+   */
+  extractFeatureName(filePath, content) {
+    const headingMatch = content.match(/^#+\s+(.+)$/m);
+    if (headingMatch) {
+      return headingMatch[1].trim();
+    }
+    return path13.basename(filePath, ".md");
+  }
+  /**
+   * Generate test files from specs
+   */
+  async generateTestFiles(specs, testDir, testType, projectInfo) {
+    const createdFiles = [];
+    for (const spec of specs) {
+      const testContent = this.generateTestContent(spec, testType, projectInfo);
+      const testFileName = this.getTestFileName(spec.name, testType, projectInfo);
+      const testFilePath = path13.join(testDir, testFileName);
+      await FileSystemUtils.writeFile(testFilePath, testContent);
+      createdFiles.push(testFilePath);
+    }
+    return createdFiles;
+  }
+  /**
+   * Generate test file content
+   */
+  generateTestContent(spec, testType, projectInfo) {
+    const featureInfo = this.extractFeatureInfo(spec.content);
+    const testFramework = this.determineTestFramework(projectInfo);
+    const lines = [];
+    lines.push(`/**`);
+    lines.push(` * ${testType.charAt(0).toUpperCase() + testType.slice(1)} tests for: ${spec.name}`);
+    lines.push(` * Generated from spec: ${path13.basename(spec.path)}`);
+    lines.push(` */`);
+    lines.push("");
+    if (testFramework === "jest") {
+      lines.push(`describe('${spec.name}', () => {`);
+      lines.push("  // TODO: Implement test cases based on spec requirements");
+      lines.push("");
+      if (featureInfo.requirements.length > 0) {
+        featureInfo.requirements.forEach((req, index) => {
+          lines.push(`  test('should ${req}', () => {`);
+          lines.push(`    // Test implementation needed`);
+          lines.push(`    expect(true).toBe(true);`);
+          lines.push(`  });`);
+          if (index < featureInfo.requirements.length - 1) {
+            lines.push("");
+          }
+        });
+      }
+      lines.push("});");
+    } else if (testFramework === "phpunit") {
+      lines.push(`class ${this.toPascalCase(spec.name)}Test extends TestCase`);
+      lines.push("{");
+      lines.push("    // TODO: Implement test cases based on spec requirements");
+      lines.push("");
+      if (featureInfo.requirements.length > 0) {
+        featureInfo.requirements.forEach((req, index) => {
+          lines.push(`    public function test_${this.toSnakeCase(req)}()`);
+          lines.push("    {");
+          lines.push("        // Test implementation needed");
+          lines.push("        $this->assertTrue(true);");
+          lines.push("    }");
+          if (index < featureInfo.requirements.length - 1) {
+            lines.push("");
+          }
+        });
+      }
+      lines.push("}");
+    } else {
+      lines.push(`// ${testType.charAt(0).toUpperCase() + testType.slice(1)} tests for: ${spec.name}`);
+      lines.push("");
+      lines.push("// TODO: Implement test cases based on spec requirements");
+      lines.push("");
+      if (featureInfo.requirements.length > 0) {
+        featureInfo.requirements.forEach((req) => {
+          lines.push(`// Test: ${req}`);
+        });
+      }
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Determine test framework based on project info
+   */
+  determineTestFramework(projectInfo) {
+    if (projectInfo.stack) {
+      if (projectInfo.stack.some((s) => s.toLowerCase().includes("php"))) {
+        return "phpunit";
+      }
+      if (projectInfo.stack.some((s) => s.toLowerCase().includes("node") || s.toLowerCase().includes("javascript"))) {
+        return "jest";
+      }
+    }
+    return "jest";
+  }
+  /**
+   * Get test file name
+   */
+  getTestFileName(featureName, testType, projectInfo) {
+    const framework = this.determineTestFramework(projectInfo);
+    const baseName = this.toKebabCase(featureName);
+    if (framework === "phpunit") {
+      return `${this.toPascalCase(featureName)}Test.php`;
+    } else if (framework === "jest") {
+      return `${baseName}.test.js`;
+    }
+    return `${baseName}.test.js`;
+  }
+  /**
+   * Extract feature info from spec content
+   */
+  extractFeatureInfo(content) {
+    const info = {
+      requirements: []
+    };
+    const lines = content.split("\n");
+    let inRequirements = false;
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.match(/^##+\s+Requirements?/i)) {
+        inRequirements = true;
+        continue;
+      } else if (trimmed.match(/^##+/) && inRequirements) {
+        break;
+      }
+      if (inRequirements && trimmed.startsWith("-")) {
+        const requirement = trimmed.replace(/^-\s*/, "").trim();
+        if (requirement) {
+          info.requirements.push(requirement);
+        }
+      }
+    }
+    return info;
+  }
+  /**
+   * Convert to kebab-case
+   */
+  toKebabCase(str) {
+    return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  }
+  /**
+   * Convert to PascalCase
+   */
+  toPascalCase(str) {
+    return str.split(/[^a-zA-Z0-9]+/).map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join("");
+  }
+  /**
+   * Convert to snake_case
+   */
+  toSnakeCase(str) {
+    return str.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
+  }
+};
+
+// src/commands/make-code.ts
+import path14 from "path";
+import chalk9 from "chalk";
+import ora7 from "ora";
+var MakeCodeCommand = class {
+  async execute(projectPath = ".", specName) {
+    const spinner = ora7("Generating code from specs...").start();
+    try {
+      const resolvedPath = path14.resolve(projectPath);
+      const specsDir = path14.join(resolvedPath, HERASPEC_DIR_NAME, SPECS_DIR_NAME);
+      const projectMdPath = path14.join(resolvedPath, HERASPEC_DIR_NAME, HERASPEC_MARKERS.PROJECT_MD);
+      if (!await FileSystemUtils.fileExists(specsDir)) {
+        spinner.fail('Specs directory not found. Run "heraspec init" first.');
+        process.exitCode = 1;
+        return;
+      }
+      let projectInfo = {};
+      if (await FileSystemUtils.fileExists(projectMdPath)) {
+        const projectContent = await FileSystemUtils.readFile(projectMdPath);
+        projectInfo = this.extractProjectInfo(projectContent);
+      }
+      let specFiles = [];
+      if (specName) {
+        const specPath = this.findSpecPath(specsDir, specName);
+        if (specPath && await FileSystemUtils.fileExists(specPath)) {
+          specFiles = [specPath];
+        } else {
+          spinner.fail(`Spec "${specName}" not found`);
+          process.exitCode = 1;
+          return;
+        }
+      } else {
+        specFiles = await this.findSpecFiles(specsDir);
+      }
+      if (specFiles.length === 0) {
+        spinner.warn('No specs found. Create specs first using "heraspec list --specs".');
+        return;
+      }
+      const specs = await this.readSpecs(specFiles);
+      const generatedFiles = await this.generateCodeFiles(specs, resolvedPath, projectInfo);
+      spinner.succeed(`Generated ${generatedFiles.length} code file(s)`);
+      console.log(chalk9.gray(`
+Specs analyzed: ${specFiles.length}`));
+      generatedFiles.forEach((file) => {
+        console.log(chalk9.cyan(`  \u2713 ${path14.relative(resolvedPath, file)}`));
+      });
+    } catch (error) {
+      spinner.fail(`Error: ${error.message}`);
+      process.exitCode = 1;
+      throw error;
+    }
+  }
+  extractProjectInfo(content) {
+    const projectTypeMatch = content.match(/project[-\s]type[s]?[:\s]+([^\n]+)/i);
+    const stackMatch = content.match(/tech[-\s]stack[:\s]+([^\n]+)/i);
+    return {
+      projectType: projectTypeMatch ? projectTypeMatch[1].trim().split(",")[0].trim() : void 0,
+      stack: stackMatch ? stackMatch[1].split(",").map((s) => s.trim()).filter(Boolean) : void 0
+    };
+  }
+  findSpecPath(specsDir, specName) {
+    const directPath = path14.join(specsDir, `${specName}.md`);
+    const nestedPath = path14.join(specsDir, specName, "spec.md");
+    return directPath;
+  }
+  async findSpecFiles(specsDir) {
+    const specFiles = [];
+    await this.findSpecFilesRecursive(specsDir, specFiles);
+    return specFiles.sort();
+  }
+  async findSpecFilesRecursive(dir, files) {
+    const fs2 = await import("fs/promises");
+    const entries = await fs2.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const entryPath = path14.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await this.findSpecFilesRecursive(entryPath, files);
+      } else if (entry.name.endsWith(".md") && entry.name !== "README.md") {
+        files.push(entryPath);
+      }
+    }
+  }
+  async readSpecs(specFiles) {
+    const specs = [];
+    for (const specFile of specFiles) {
+      const content = await FileSystemUtils.readFile(specFile);
+      const parser = new MarkdownParser(content);
+      const specName = path14.basename(specFile, ".md");
+      try {
+        const parsed = parser.parseSpec(specName);
+        specs.push({
+          path: specFile,
+          content,
+          name: parsed.name,
+          parsed
+        });
+      } catch (error) {
+        console.warn(chalk9.yellow(`Warning: Could not parse spec file ${specFile}. Skipping.`));
+      }
+    }
+    return specs;
+  }
+  async generateCodeFiles(specs, projectPath, projectInfo) {
+    const generatedFiles = [];
+    const projectType = projectInfo.projectType || "generic-webapp";
+    for (const spec of specs) {
+      const codeContent = this.generateCodeContent(spec, projectType, projectInfo);
+      const outputPath = this.getOutputPath(projectPath, spec.name, projectType);
+      await FileSystemUtils.createDirectory(path14.dirname(outputPath));
+      await FileSystemUtils.writeFile(outputPath, codeContent);
+      generatedFiles.push(outputPath);
+    }
+    return generatedFiles;
+  }
+  getOutputPath(projectPath, specName, projectType) {
+    const sanitizedName = specName.toLowerCase().replace(/[^a-z0-9-]/g, "-");
+    if (projectType.includes("wordpress-plugin")) {
+      return path14.join(projectPath, "includes", `class-${sanitizedName}.php`);
+    } else if (projectType.includes("perfex-module")) {
+      return path14.join(projectPath, "modules", sanitizedName, `${sanitizedName}.php`);
+    } else if (projectType.includes("laravel")) {
+      return path14.join(projectPath, "app", "Services", `${this.toPascalCase(sanitizedName)}Service.php`);
+    } else if (projectType.includes("node")) {
+      return path14.join(projectPath, "src", "services", `${sanitizedName}.js`);
+    } else {
+      return path14.join(projectPath, "src", `${sanitizedName}.ts`);
+    }
+  }
+  generateCodeContent(spec, projectType, projectInfo) {
+    const lines = [];
+    const className = this.toPascalCase(spec.name.replace(/[^a-zA-Z0-9]/g, ""));
+    lines.push(`/**`);
+    lines.push(` * ${spec.name}`);
+    lines.push(` * Generated from spec: ${path14.basename(spec.path)}`);
+    lines.push(` *`);
+    lines.push(` * ${spec.parsed.overview || "Generated code skeleton"}`);
+    lines.push(` */`);
+    lines.push("");
+    if (projectType.includes("wordpress-plugin") || projectType.includes("perfex-module")) {
+      lines.push(`<?php`);
+      lines.push("");
+      lines.push(`class ${className} {`);
+      lines.push("");
+      spec.parsed.requirements.forEach((req) => {
+        const methodName = this.toCamelCase(req.name.replace(/[^a-zA-Z0-9]/g, ""));
+        lines.push(`  /**`);
+        lines.push(`   * ${req.description || req.name}`);
+        lines.push(`   */`);
+        lines.push(`  public function ${methodName}() {`);
+        lines.push(`    // TODO: Implement ${req.name}`);
+        lines.push(`  }`);
+        lines.push("");
+      });
+      lines.push("}");
+    } else if (projectType.includes("laravel")) {
+      lines.push(`<?php`);
+      lines.push("");
+      lines.push(`namespace App\\Services;`);
+      lines.push("");
+      lines.push(`class ${className}Service {`);
+      lines.push("");
+      spec.parsed.requirements.forEach((req) => {
+        const methodName = this.toCamelCase(req.name.replace(/[^a-zA-Z0-9]/g, ""));
+        lines.push(`  /**`);
+        lines.push(`   * ${req.description || req.name}`);
+        lines.push(`   */`);
+        lines.push(`  public function ${methodName}() {`);
+        lines.push(`    // TODO: Implement ${req.name}`);
+        lines.push(`  }`);
+        lines.push("");
+      });
+      lines.push("}");
+    } else if (projectType.includes("node")) {
+      lines.push(`/**`);
+      lines.push(` * ${spec.name} service`);
+      lines.push(` */`);
+      lines.push("");
+      lines.push(`class ${className} {`);
+      lines.push("");
+      spec.parsed.requirements.forEach((req) => {
+        const methodName = this.toCamelCase(req.name.replace(/[^a-zA-Z0-9]/g, ""));
+        lines.push(`  /**`);
+        lines.push(`   * ${req.description || req.name}`);
+        lines.push(`   */`);
+        lines.push(`  ${methodName}() {`);
+        lines.push(`    // TODO: Implement ${req.name}`);
+        lines.push(`  }`);
+        lines.push("");
+      });
+      lines.push("}");
+      lines.push("");
+      lines.push(`module.exports = ${className};`);
+    } else {
+      lines.push(`export class ${className} {`);
+      lines.push("");
+      spec.parsed.requirements.forEach((req) => {
+        const methodName = this.toCamelCase(req.name.replace(/[^a-zA-Z0-9]/g, ""));
+        lines.push(`  /**`);
+        lines.push(`   * ${req.description || req.name}`);
+        lines.push(`   */`);
+        lines.push(`  ${methodName}(): void {`);
+        lines.push(`    // TODO: Implement ${req.name}`);
+        lines.push(`  }`);
+        lines.push("");
+      });
+      lines.push("}");
+    }
+    lines.push("");
+    lines.push(`// Generated by HeraSpec - Update this file based on implementation requirements`);
+    return lines.join("\n");
+  }
+  toPascalCase(str) {
+    return str.replace(/[^a-zA-Z0-9]/g, " ").split(" ").map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join("");
+  }
+  toCamelCase(str) {
+    const pascal = this.toPascalCase(str);
+    return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+  }
+};
+
+// src/cli/index.ts
+var require3 = createRequire2(import.meta.url);
+var __filename2 = fileURLToPath2(import.meta.url);
+var __dirname2 = dirname2(__filename2);
+var packageJsonPath = join2(__dirname2, "..", "package.json");
+var { version } = require3(packageJsonPath);
+var program = new Command();
+program.name("heraspec").description("Universal spec-first development framework + CLI").version(version);
+program.command("init [path]").description("Initialize HeraSpec in your project").action(async (targetPath = ".") => {
+  try {
+    const initCommand = new InitCommand();
+    await initCommand.execute(targetPath);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+program.command("list").description("List items (changes by default). Use --specs to list specs.").option("--specs", "List specs instead of changes").option("--changes", "List changes explicitly (default)").action(async (options) => {
+  try {
+    const listCommand = new ListCommand();
+    const mode = options?.specs ? "specs" : "changes";
+    await listCommand.execute(".", mode);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+program.command("show [item-name]").description("Show a change or spec").action(async (itemName) => {
+  try {
+    const showCommand = new ShowCommand();
+    await showCommand.execute(itemName);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+program.command("validate [item-name]").description("Validate a change or spec").option("--strict", "Enable strict validation mode").action(async (itemName, options) => {
+  try {
+    const validateCommand = new ValidateCommand();
+    await validateCommand.execute(itemName, options);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+program.command("archive [change-name]").description("Archive a completed change and update main specs").option("-y, --yes", "Skip confirmation prompts").action(async (changeName, options) => {
+  try {
+    const archiveCommand = new ArchiveCommand();
+    await archiveCommand.execute(changeName, options);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+program.command("restore [archive-name]").description("Restore an archived change back to active changes").option("-y, --yes", "Skip confirmation prompts").action(async (archiveName, options) => {
+  try {
+    const restoreCommand = new RestoreCommand();
+    await restoreCommand.execute(archiveName, options);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+program.command("view").description("Display an interactive dashboard of specs and changes").action(async () => {
+  try {
+    const listCommand = new ListCommand();
+    console.log("\n\u{1F4CA} HeraSpec Dashboard\n");
+    console.log("\u2550".repeat(60));
+    await listCommand.execute(".", "changes");
+    await listCommand.execute(".", "specs");
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+program.command("helper").description("Show usage guide, example prompts, and workflow instructions").action(async () => {
+  try {
+    const helperCommand = new HelperCommand();
+    await helperCommand.execute();
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+var makeCmd = program.command("make").description("Generate project artifacts");
+makeCmd.command("docs").description("Generate project documentation from specs").option("--agent <agent>", "Specify AI agent for documentation (default: chatgpt)", "chatgpt").action(async (options) => {
+  try {
+    const makeDocsCommand = new MakeDocsCommand();
+    await makeDocsCommand.execute(".", options?.agent || "chatgpt");
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+makeCmd.command("test").description("Generate test cases from specs").option("--type <type>", "Test type: unit, integration, e2e (default: unit)", "unit").action(async (options) => {
+  try {
+    const makeTestCommand = new MakeTestCommand();
+    await makeTestCommand.execute(".", options?.type || "unit");
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+makeCmd.command("code").description("Generate code skeletons from specs").argument("[spec-name]", "Specific spec to generate code for (optional)").action(async (specName) => {
+  try {
+    const makeCodeCommand = new MakeCodeCommand();
+    await makeCodeCommand.execute(".", specName);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+program.command("suggest").description("Analyze project and suggest new features").action(async () => {
+  try {
+    const suggestCommand = new SuggestCommand();
+    await suggestCommand.execute(".");
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+var skillCmd = program.command("skill").description("Manage and view skills");
+skillCmd.command("list").description("List all available skills").action(async () => {
+  try {
+    const skillCommand = new SkillCommand();
+    await skillCommand.list(".");
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+skillCmd.command("show <skill-name>").description("Show detailed information about a skill").option("--project-type <type>", "Specify project type for project-specific skills").action(async (skillName, options) => {
+  try {
+    const skillCommand = new SkillCommand();
+    await skillCommand.show(skillName, options?.projectType, ".");
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+skillCmd.command("repair").description("Repair skills structure to match HeraSpec standards").action(async () => {
+  try {
+    const skillCommand = new SkillCommand();
+    await skillCommand.repair(".");
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+skillCmd.command("add <skill-name>").description("Add a default skill to the project from HeraSpec templates").option("--project-type <type>", "Specify project type for project-specific skills").action(async (skillName, options) => {
+  try {
+    const skillCommand = new SkillCommand();
+    await skillCommand.add(skillName, options?.projectType, ".");
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+program.parse();
+//# sourceMappingURL=heraspec.js.map