heraspec 0.1.4 → 0.1.5

package/bin/heraspec.js

@@ -81,7 +81,9 @@ var FileSystemUtils = class {
 };
 
 // src/core/templates/index.ts
-var PROJECT_TEMPLATE = `# HeraSpec Project
+var TemplateManager = class {
+  static getProjectTemplate() {
+    return `# HeraSpec Project
 
 ## Overview
 Describe your project here.
@@ -102,12 +104,22 @@ 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
+  }
+  static getAgentsTemplate() {
+    return `# HeraSpec \u2014 AI Agent Instructions
 
 This document defines the workflow for AI agents working with HeraSpec.
 
+## Universal Safety Rules
+
+- **NO AUTO-COMMIT**: Agent MUST NOT perform \`git commit\` or \`git push\` autonomously. This task is reserved for the User unless explicitly ordered.
+- **NO AUTO-PUBLISH**: Agent MUST NOT perform \`npm publish\` or trigger automated releases/deployments autonomously.
+- **SKILL PREREQUISITE**: If a task maps to a skill (e.g., "Generate documentation"), you **MUST** verify the skill folder exists in \`heraspec/skills/\`. If missing:
+  - **Preferred**: Proactively install it via \`heraspec skill add <name>\` (e.g., \`heraspec skill add documents\`) if you have terminal access.
+  - **Fallback**: If you cannot install it, **STOP** and ask the user to add it. **DO NOT** attempt manual generation without the skill.
+- **USER CONFIRMATION**: For destructive actions or public releases, always request explicit User approval first.
+
 ## Core Workflow
 
 ### Step 1 \u2014 Create a Change
@@ -176,11 +188,11 @@ This document defines the workflow for AI agents working with HeraSpec.
 - 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>
-  \`\`\`
+   \`\`\`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
@@ -225,23 +237,39 @@ Tasks grouped by project type and skill:
 
 ## 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
+**CRITICAL: Mandatory Prerequisite Check**
+
+1. **Stop & Verify**: If you are asked to implement a task requiring a skill (e.g., "Generate documentation...", "Create UI/UX...", etc.), you MUST first check if the skill folder exists in \`heraspec/skills/\`.
+2. **Missing Skill = AUTO-INSTALL OR STOP**: If the skill folder does NOT exist:
+   - **Option A (Preferred)**: If you can run commands, execute \`heraspec skill add <skill-name>\` immediately.
+   - **Option B (Fallback)**: If you cannot run commands, **STOP** and ask the user to run it.
+     > "Tip: Add the 'documents' skill for premium HTML & Landing Page support: 
+     > heraspec skill add documents"
+   - **DO NOT** create a task plan or attempt manual generation without the skill language.
+3. **Execute After Install**: Only after the skill folder is created (or installed), read the \`skill.md\` and proceed with the task.
+
+**Example prompt for Documents skill:**
+If you need to generate multi-format documentation, use this prompt:
+> "Generate documentation with skill documents for [project-name]. Include:
+> - Concise overview (documentations/documentation.txt)
+> - Technical Markdown (documentations/documentation.md)
+> - Interactive HTML (documentations/documentation.html)
+> - Premium Documentation Landing Page (documentations/documentation-landing-page.html)
+> - CRITICAL: Save all files in the /documentations directory (create it if missing)."
+
+**Dynamic Documentation Generation**:
+When generating documentation, do NOT simply fill a template. The Agent MUST:
+1. **Create** the \`/documentations\` directory if it does not exist.
+2. **Design** a custom layout and content structure suitable for the project type.
+3. **Synchronize** with the \`ui-ux\` skill for premium visual design (colors, typography, animations).
+4. **Scan All Specs**: If project-wide, read \`heraspec/project.md\` and all files in \`heraspec/specs/\` to synthesize the content.
+
+### Skill Discovery & Usage
 
 - List all skills: Check \`heraspec/skills/\` directory
 - Project-specific skills: \`heraspec/skills/<project-type>/\`
 - Cross-cutting skills: \`heraspec/skills/<skill-name>/\` (root level)
+- **Consistency**: Follow the step-by-step process in the skill's \`skill.md\`.
 
 ### When Change Has Multiple Skills
 
@@ -249,7 +277,7 @@ Tasks grouped by project type and skill:
 
 Example with multiple skills in one change:
 \`\`\`
-## 1. Perfex module \u2013 Feature (projectType: perfex-module, skill: module-codebase)
+## 1. WordPress module \u2013 Feature (skill: admin-settings-page)
 - [ ] Task 1.1 Create module structure
 - [ ] Task 1.2 Configure registration
 
@@ -261,89 +289,45 @@ Example with multiple skills in one change:
 - [ ] 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
-
-- Agent implements with proper colors, fonts, styles from search results
-- Agent verifies with pre-delivery checklist
-
-**Special case - Flatsome UX Element skill:**
-- Task: \`(projectType: wordpress, skill: ux-element)\`
-- Agent reads: \`heraspec/skills/wordpress/ux-element/skill.md\`
-- Agent MUST follow the **Wrapping Rule**: Use \`<span>\` with \`id="{{:: shortcode.$id }}"\`
-- Agent uses templates from \`heraspec/skills/wordpress/ux-element/templates/\` (Controller, Shortcode, HTML Template, SVG Thumbnail)
-- Agent ensures real-time preview support in AngularJS template.
-- **Variable Translation**: Variables with underscores in PHP (e.g., \`bg_color\`) MUST be accessed via camelCase in AngularJS (e.g., \`shortcode.options.bgColor\`).
-
-### Skill Discovery
+  }
+  static getSkillsSection() {
+    return `## Skills System
+
+**CRITICAL: Mandatory Prerequisite Check**
+
+1. **Stop & Verify**: If you are asked to implement a task requiring a skill (e.g., "Generate documentation...", "Create UI/UX...", etc.), you MUST first check if the skill folder exists in \`heraspec/skills/\`.
+2. **Missing Skill = AUTO-INSTALL OR STOP**: If the skill folder does NOT exist:
+   - **Option A (Preferred)**: If you can run commands, execute \`heraspec skill add <skill-name>\` immediately.
+   - **Option B (Fallback)**: If you cannot run commands, **STOP** and ask the user to run it.
+     > "Tip: Add the 'documents' skill for premium HTML & Landing Page support: 
+     > heraspec skill add documents"
+   - **DO NOT** create a task plan or attempt manual generation without the skill language.
+3. **Execute After Install**: Only after the skill folder is created (or installed), read the \`skill.md\` and proceed with the task.
+
+**Example prompt for Documents skill:**
+If you need to generate multi-format documentation, use this prompt:
+> "Generate documentation with skill documents for [project-name]. Include:
+> - Concise overview (documentations/documentation.txt)
+> - Technical Markdown (documentations/documentation.md)
+> - Interactive HTML (documentations/documentation.html)
+> - Premium Documentation Landing Page (documentations/documentation-landing-page.html)
+> - CRITICAL: Save all files in the /documentations directory (create it if missing)."
+
+**Dynamic Documentation Generation**:
+When generating documentation, do NOT simply fill a template. The Agent MUST:
+1. **Create** the \`/documentations\` directory if it does not exist.
+2. **Design** a custom layout and content structure suitable for the project type.
+3. **Synchronize** with the \`ui-ux\` skill for premium visual design (colors, typography, animations).
+4. **Scan All Specs**: If project-wide, read \`heraspec/project.md\` and all files in \`heraspec/specs/\` to synthesize the content.
+
+### Skill Discovery & Usage
 
 - List all skills: Check \`heraspec/skills/\` directory
 - Project-specific skills: \`heraspec/skills/<project-type>/\`
 - Cross-cutting skills: \`heraspec/skills/<skill-name>/\` (root level)
+- **Consistency**: Follow the step-by-step process in the skill's \`skill.md\`.
 
 ### When Change Has Multiple Skills
 
@@ -351,7 +335,7 @@ var SKILLS_SECTION_TEMPLATE = `## Skills System
 
 Example with multiple skills in one change:
 \`\`\`
-## 1. Perfex module \u2013 Feature (projectType: perfex-module, skill: module-codebase)
+## 1. WordPress module \u2013 Feature (skill: admin-settings-page)
 - [ ] Task 1.1 Create module structure
 - [ ] Task 1.2 Configure registration
 
@@ -363,80 +347,15 @@ Example with multiple skills in one change:
 - [ ] 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;
+    return `projectType: generic-webapp
+projectName: "HeraSpec Project"
+description: "A new project using HeraSpec"
+skills: []
+`;
   }
 };
 
@@ -495,8 +414,12 @@ var InitCommand = class {
         await FileSystemUtils.writeFile(uiuxGuidePath, uiuxGuide);
       }
       await this.createTemplateFiles(heraspecPath, alreadyInitialized);
-      const agentsPath = path2.join(resolvedPath, HERASPEC_MARKERS.AGENTS_MD);
-      await this.updateAgentsFile(agentsPath, alreadyInitialized);
+      const legacyAgentsPath = path2.join(resolvedPath, "AGENTS.md");
+      const newAgentsPath = path2.join(resolvedPath, HERASPEC_MARKERS.AGENTS_MD);
+      if (await FileSystemUtils.fileExists(legacyAgentsPath) && !await FileSystemUtils.fileExists(newAgentsPath)) {
+        await FileSystemUtils.moveFile(legacyAgentsPath, newAgentsPath);
+      }
+      await this.updateAgentsFile(newAgentsPath, alreadyInitialized);
       await this.updateRelatedMarkdownFiles(resolvedPath);
       spinner.succeed(
         chalk.green(
@@ -537,7 +460,6 @@ var InitCommand = class {
   }
   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,
@@ -548,24 +470,56 @@ var InitCommand = class {
     let existingContent = "";
     if (await FileSystemUtils.fileExists(agentsPath)) {
       existingContent = await FileSystemUtils.readFile(agentsPath);
+    } else {
+      await FileSystemUtils.writeFile(
+        agentsPath,
+        TemplateManager.getAgentsTemplate()
+      );
+      return;
     }
-    if (existingContent.includes(skillsSectionMarker)) {
-      const skillsSection = await this.getSkillsSection();
-      const updatedContent = this.replaceSkillsSection(existingContent, skillsSection);
-      await FileSystemUtils.writeFile(agentsPath, updatedContent);
+    const latestSkillsSection = await this.getSkillsSection();
+    const safetyMarker = "## Universal Safety Rules";
+    const fullTemplate = TemplateManager.getAgentsTemplate();
+    const safetyEndIndex = fullTemplate.indexOf("## Core Workflow");
+    const safetySection = fullTemplate.substring(fullTemplate.indexOf(safetyMarker), safetyEndIndex).trim();
+    if (existingContent.includes(safetyMarker)) {
+      existingContent = this.replaceSafetyRules(existingContent, safetySection);
+    } else {
+      if (existingContent.startsWith("# ")) {
+        const firstLineEnd = existingContent.indexOf("\n") + 1;
+        existingContent = existingContent.substring(0, firstLineEnd) + "\n" + safetySection + "\n\n" + existingContent.substring(firstLineEnd);
+      } else {
+        existingContent = safetySection + "\n\n" + existingContent;
+      }
+    }
+    let updatedContent = existingContent;
+    if (existingContent.includes(skillsSectionMarker) || existingContent.includes("## Skills system")) {
+      updatedContent = this.replaceSkillsSection(existingContent, latestSkillsSection);
     } else {
-      const skillsSection = await this.getSkillsSection();
-      const updatedContent = this.appendSkillsSection(existingContent, skillsSection);
+      updatedContent = this.appendSkillsSection(existingContent, latestSkillsSection);
+    }
+    if (updatedContent !== existingContent) {
       await FileSystemUtils.writeFile(agentsPath, updatedContent);
     }
   }
   replaceSkillsSection(existingContent, newSkillsSection) {
-    const startMarker = "## Skills System";
-    const startIndex = existingContent.indexOf(startMarker);
+    const startMarkers = ["## Skills System", "## Skills system", "### Skills System", "### Skills system"];
+    let startIndex = -1;
+    let foundMarker = "";
+    for (const marker of startMarkers) {
+      startIndex = existingContent.indexOf(marker);
+      if (startIndex !== -1) {
+        foundMarker = marker;
+        break;
+      }
+    }
     if (startIndex === -1) {
       return this.appendSkillsSection(existingContent, newSkillsSection);
     }
-    let endIndex = existingContent.indexOf("\n## ", startIndex + startMarker.length);
+    let endIndex = existingContent.indexOf("\n## ", startIndex + foundMarker.length);
+    if (endIndex === -1) {
+      endIndex = existingContent.indexOf("\n### ", startIndex + foundMarker.length);
+    }
     if (endIndex === -1) {
       endIndex = existingContent.length;
     }
@@ -573,6 +527,18 @@ var InitCommand = class {
     const after = existingContent.substring(endIndex);
     return before + "\n\n" + newSkillsSection + (after.trimStart().startsWith("\n") ? "" : "\n\n") + after;
   }
+  replaceSafetyRules(existingContent, newSafetySection) {
+    const marker = "## Universal Safety Rules";
+    const startIndex = existingContent.indexOf(marker);
+    if (startIndex === -1) return existingContent;
+    let endIndex = existingContent.indexOf("\n## ", startIndex + marker.length);
+    if (endIndex === -1) {
+      endIndex = existingContent.length;
+    }
+    const before = existingContent.substring(0, startIndex).trimEnd();
+    const after = existingContent.substring(endIndex);
+    return before + "\n\n" + newSafetySection + (after.trimStart().startsWith("\n") ? "" : "\n\n") + after;
+  }
   appendSkillsSection(existingContent, skillsSection) {
     const rulesMarker = "\n## Rules\n";
     const rulesIndex = existingContent.indexOf(rulesMarker);
@@ -2825,11 +2791,12 @@ var HelperCommand = class {
     console.log(chalk6.gray("   heraspec make docs --agent chatgpt\n"));
     console.log(chalk6.gray("   heraspec make docs --agent claude\n"));
     console.log(chalk6.white.bold("8. Multi-Format Documentation (Skill: Documents):\n"));
-    console.log(chalk6.gray('   "Generate documentation with skill documents. Include:\n'));
-    console.log(chalk6.gray("    - Standard Markdown file (.md)\n"));
-    console.log(chalk6.gray("    - Interactive HTML Documentation (panel layout)\n"));
-    console.log(chalk6.gray('    - Premium Documentation Landing Page (visual showcase)"\n'));
-    console.log(chalk6.gray('   "Use documents skill to create parallel MD and Landing Page"\n'));
+    console.log(chalk6.gray('   "Generate documentation with skill documents for [project-name]. Include:\n'));
+    console.log(chalk6.gray("    - Concise overview (documentation.txt)\n"));
+    console.log(chalk6.gray("    - Technical Markdown (documentation.md)\n"));
+    console.log(chalk6.gray("    - Interactive HTML Documentation (documentation.html)\n"));
+    console.log(chalk6.gray('    - Premium Documentation Landing Page (documentation-landing-page.html)"\n'));
+    console.log(chalk6.gray('   "Use documents skill to create dynamic, project-specific docs"\n'));
     console.log("\u2500".repeat(70) + "\n");
   }
   showWorkflow() {
@@ -2880,11 +2847,12 @@ var HelperCommand = class {
       {
         step: "6. Generate Documentation",
         actions: [
-          "Generate product docs: heraspec make docs",
-          "With specific agent: heraspec make docs --agent <name>",
-          "Output: documentation/product-documentation.txt"
+          "Generate basic docs: heraspec make docs",
+          'Use Skill Documents: "Generate documentation with skill documents"',
+          "Outputs: documentation.txt, .md, .html, and landing-page.html",
+          "Agent uses ui-ux skill for premium dynamic design"
         ],
-        prompt: "heraspec make docs --agent chatgpt"
+        prompt: '"Generate documentation with skill documents for polyutilities"'
       }
     ];
     steps.forEach(({ step, actions, prompt }) => {
@@ -2910,6 +2878,8 @@ var HelperCommand = class {
       "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",
+      'Premium Documentation: Use "skill documents" for txt, md, html, and landing page',
+      "Dynamic Docs: Documents skill generates custom layouts based on your project specs",
       "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)",
@@ -2936,7 +2906,7 @@ var MakeDocsCommand = class {
     try {
       const resolvedPath = path12.resolve(projectPath);
       const specsDir = path12.join(resolvedPath, HERASPEC_DIR_NAME, SPECS_DIR_NAME);
-      const docsDir = path12.join(resolvedPath, "documentation");
+      const docsDir = path12.join(resolvedPath, "documentations");
       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.');
@@ -2949,6 +2919,8 @@ var MakeDocsCommand = class {
         const projectContent = await FileSystemUtils.readFile(projectMdPath);
         projectInfo = this.extractProjectInfo(projectContent);
       }
+      const hasDocumentsSkill = await FileSystemUtils.fileExists(path12.join(resolvedPath, HERASPEC_DIR_NAME, "skills", "documents"));
+      const hasUIUXSkill = await FileSystemUtils.fileExists(path12.join(resolvedPath, HERASPEC_DIR_NAME, "skills", "ui-ux"));
       const specFiles = await this.findSpecFiles(specsDir);
       if (specFiles.length === 0) {
         spinner.warn('No specs found. Create specs first using "heraspec list --specs".');
@@ -2956,9 +2928,26 @@ var MakeDocsCommand = class {
       }
       const specs = await this.readSpecs(specFiles);
       const docContent = this.generateProductDocumentation(specs, projectInfo, agent);
-      const docFilePath = path12.join(docsDir, "product-documentation.txt");
+      const docFilePath = path12.join(docsDir, "documentation.txt");
       await FileSystemUtils.writeFile(docFilePath, docContent);
-      spinner.succeed(`Product documentation generated: ${docFilePath}`);
+      spinner.succeed(`Basic documentation generated: ${docFilePath}`);
+      if (hasDocumentsSkill) {
+        console.log(chalk7.green.bold("\n\u2728 Documents Skill Detected!"));
+        console.log(chalk7.white("AI Agent Instruction:"));
+        console.log(chalk7.gray('   "Now use the documents skill to generate the full multi-format package:'));
+        console.log(chalk7.gray("    - Use documentation.txt as context"));
+        console.log(chalk7.gray("    - Create documentation.md, documentation.html, and landing page"));
+        console.log(chalk7.gray("    - CRITICAL: Save all files in the /documentations directory (create it if missing)"));
+        if (hasUIUXSkill) {
+          console.log(chalk7.gray('    - Apply premium design from the ui-ux skill standards"'));
+        } else {
+          console.log(chalk7.yellow('    - WARNING: "ui-ux" skill is MISSING but required for HTML/Landing Page.'));
+          console.log(chalk7.gray('    - Agent must install it first: heraspec skill add ui-ux"'));
+        }
+      } else {
+        console.log(chalk7.yellow('\n\u{1F4A1} Tip: Add the "documents" skill for premium HTML & Landing Page support:'));
+        console.log(chalk7.gray("   heraspec skill add documents"));
+      }
       console.log(chalk7.gray(`
 Found ${specFiles.length} feature(s)`));
     } catch (error) {