heraspec 0.1.0

package/dist/index.js

@@ -0,0 +1,1736 @@
+import { createRequire } from 'module'; const require = createRequire(import.meta.url);
+
+// 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 SKILLS = {
+  "wordpress-plugin": [
+    "admin-settings-page",
+    "custom-post-type",
+    "shortcode",
+    "rest-endpoint",
+    "ajax-handler",
+    "activation-hook",
+    "deactivation-hook",
+    "admin-menu-item",
+    "meta-box",
+    "taxonomy"
+  ],
+  "wordpress-theme": [
+    "theme-setup",
+    "custom-post-type",
+    "template-part",
+    "widget-area",
+    "customizer-setting",
+    "theme-option"
+  ],
+  "perfex-module": [
+    "module-codebase",
+    "module-registration",
+    "permission-group",
+    "admin-menu-item",
+    "login-hook",
+    "database-table",
+    "api-endpoint"
+  ],
+  "laravel-package": [
+    "service-provider",
+    "config-file",
+    "artisan-command",
+    "migration",
+    "model",
+    "controller",
+    "middleware",
+    "route"
+  ],
+  "node-service": [
+    "express-route",
+    "middleware",
+    "database-model",
+    "service-layer",
+    "api-endpoint",
+    "background-job"
+  ],
+  "generic-webapp": [
+    "page",
+    "component",
+    "api-endpoint",
+    "database-table",
+    "authentication",
+    "authorization"
+  ],
+  "backend-api": [
+    "endpoint",
+    "middleware",
+    "authentication",
+    "authorization",
+    "database-model",
+    "validation"
+  ],
+  "frontend-app": [
+    "page",
+    "component",
+    "route",
+    "store",
+    "service",
+    "hook"
+  ],
+  "multi-stack": [
+    "cross-platform-feature",
+    "api-contract",
+    "shared-type",
+    "integration-point"
+  ]
+};
+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/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/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/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/validation/validator.ts
+import { readFileSync } from "fs";
+import path5 from "path";
+var Validator = class {
+  strictMode;
+  constructor(strictMode = false) {
+    this.strictMode = strictMode;
+  }
+  async validateSpec(filePath) {
+    const errors = [];
+    const warnings = [];
+    try {
+      const content = readFileSync(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 = path5.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 = path5.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 = path5.basename(changePath);
+    const specsDir = path5.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 = readFileSync(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 = path5.basename(filePath, ".md");
+    return baseName === "spec" ? path5.basename(path5.dirname(filePath)) : baseName;
+  }
+  async findDeltaSpecs(dir) {
+    const specs = [];
+    const entries = await FileSystemUtils.readDirectory(dir);
+    for (const entry of entries) {
+      const entryPath = path5.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;
+  }
+};
+export {
+  ARCHIVES_DIR_NAME,
+  ArchiveCommand,
+  CHANGES_DIR_NAME,
+  ChangeSchema,
+  DeltaRequirementSchema,
+  DeltaTypeSchema,
+  HERASPEC_DIR_NAME,
+  HERASPEC_MARKERS,
+  InitCommand,
+  ListCommand,
+  PROJECT_TYPES,
+  ProjectTypeSchema,
+  RequirementSchema,
+  SKILLS,
+  SKILLS_DIR_NAME,
+  SPECS_DIR_NAME,
+  ScenarioSchema,
+  SpecMetaSchema,
+  SpecSchema,
+  Validator
+};
+//# sourceMappingURL=index.js.map