heraspec 0.1.12 → 0.1.14

package/dist/core/templates/skills/documents-skill.md

@@ -1,104 +1,104 @@
-# Skill: Documents (Cross-Cutting & Multi-Format)
-
-## Purpose
-
-This skill is used to create comprehensive documentation for both technical and end-user audiences. It supports parallel generation of Markdown files (for repository/GitHub) and interactive HTML files (for browser-based manuals).
-
-## Core Requirements
-
-### 1. Multi-Format Output
-Every documentation task should ideally generate four versions:
-- `documentation.txt`: A concise, text-only overview for quick reading and AI context.
-- `documentation.md`: High-quality Markdown for version control and GitHub READMEs.
-- `documentation.html`: An interactive, premium documentation page with sidebar navigation.
-- `documentation-landing-page.html`: A visual, high-end landing page to showcase the project/plugin.
-
-### 2. Dynamic Design (Not Fixed Templates)
-- **Do NOT follow a rigid template**: The Agent must **design** the documentation layout and content structure specifically for the project.
-- **Synergy with ui-ux**: use of the `ui-ux` skill is **MANDATORY** for `documentation.html` and `documentation-landing-page.html`.
-
-### 3. Standard Quality Structure (Mandatory)
-To ensure clarity and completeness, the generated documentation MUST include:
-
-#### A. Interactive Documentation (documentation.html)
-1.  **Quick Start**: Clear steps to get running in < 2 minutes.
-2.  **System Requirements**: OS, versions, dependencies.
-3.  **Installation & Setup**: Detailed step-by-step guide.
-4.  **Configuration**: Explanation of all settings (config files, UI settings).
-5.  **Core Features**: Deep dive into each component found in `heraspec/specs/`.
-6.  **Technical Reference**: (For Devs) API endpoints, Hooks, Filters, Functions.
-7.  **Troubleshooting & FAQ**: Common issues and solutions.
-
-#### B. Premium Landing Page (documentation-landing-page.html)
-1.  **Hero Section**: High-impact headline and clear sub-headline.
-2.  **Value Proposition**: Briefly explain "The Problem" vs "The Solution".
-3.  **Feature Showcase**: A visual grid of key benefits with icons/images.
-4.  **How It Works**: A simplified 1-2-3 step process of using the project.
-5.  **CTA (Call to Action)**: Prominent buttons to "Get Started" or "View Docs".
-
-### 4. Visual Excellence
-- Use gradients, smooth animations (fade-in, slide), and premium fonts (e.g., Inter, Montserrat).
-- The HTML documentation should feel like a modern SaaS dashboard or a high-end technical manual.
-
-### 4. Project-Wide Scope
-When tasked with generating documentation for the entire project:
-- **Data Source**: Agent MUST read `heraspec/project.md` and ALL files in `heraspec/specs/`.
-- **Synthesis**: Agent must combine information from all components and features into a unified manual.
-- **Landing Page**: Should serve as the project homepage, summarizing the main value proposition and key features across all modules.
-
-## Implementation Steps
-
-### Step 1: Intelligence Gathering & Design Planning
-1. **Analyze Project**: Scan all relevant `.md` files in the project. Understand the core purpose and technical details.
-2. **Enforce UI/UX Dependency**:
-   - Check if `heraspec/skills/ui-ux/` exists.
-   - If missing: **Execute `heraspec skill add ui-ux`** immediately. Do NOT proceed with HTML generation until this skill is available.
-3. **Define Design System**: Consult the `ui-ux` skill to establish a visual language (colors, fonts, animation styles).
-4. **Plan Structures**: Outline what needs to go into the `.txt`, `.md`, and `.html` versions.
-
-### Step 2: Constructing Documentation Assets
-1. **Compose documentation.txt & .md**: Focus on clarity and technical accuracy.
-2. **Develop documentation.html**: Build a split-panel layout (Sidebar + Content). DO NOT just fill a template; **write the HTML/CSS/JS** needed to make it look premium and project-specific.
-3. **Design documentation-landing-page.html**: Create a compelling Hero section and feature showcase. Link to the main docs.
-
-## Required Input
-
-- **Project Context**: The name of the plugin/project (e.g., "polyutilities").
-- **Specs/Docs**: All existing documentation and specification files.
-- **Design Guidelines**: Inputs from the `ui-ux` skill.
-
-## Expected Output (Save to /documentations/)
-
-**CRITICAL**: All files MUST be placed in a `/documentations` folder at the project root. If this folder does not exist, the Agent MUST create it first.
-
-- `/documentations/documentation.txt`: Plain text overview.
-- `/documentations/documentation.md`: Markdown version.
-- `/documentations/documentation.html`: Interactive split-panel HTML.
-- `/documentations/documentation-landing-page.html`: Visual landing page.
-- `/documentations/style.css` & `/documentations/landing-style.css`: Custom-generated styles.
-- `/documentations/script.js` & `/documentations/landing-script.js`: Interactive logic.
-
-## Tone & Rules
-
-- **Consistent Content**: The core information must be synchronized across all formats.
-- **Design Autonomy**: The Agent is responsible for the final aesthetic and structural quality.
-- **Visual Impact**: Documentation must WOW the user with its premium feel.
-
-## Reference Templates
-These are provided as starting points or inspiration. The Agent should feel free to expand or modify them to suit the project:
-
-- `templates/documentation.html` - Base HTML documentation layout
-- `templates/documentation-landing-page.html` - Premium Landing Page layout
-- `templates/style.css` - Premium styles for HTML documentation
-- `templates/landing-style.css` - Premium styles for Landing Page
-- `templates/script.js` - Interactive logic for HTML documentation
-- `templates/landing-script.js` - Interactive logic for Landing Page
-- `templates/technical-doc-template.md` - Technical documentation
-- `templates/user-guide-template.md` - User guide
-- `templates/api-doc-template.md` - API documentation
-- `templates/changelog-template.md` - Changelog template
-
-## Links to Other Skills
-
-- **ui-ux**: ESSENTIAL. Use this to determine the look and feel of the HTML documentation.
-- **content-optimization**: Use to ensure the text is clear and professional.
+# Skill: Documents (Cross-Cutting & Multi-Format)
+
+## Purpose
+
+This skill is used to create comprehensive documentation for both technical and end-user audiences. It supports parallel generation of Markdown files (for repository/GitHub) and interactive HTML files (for browser-based manuals).
+
+## Core Requirements
+
+### 1. Multi-Format Output
+Every documentation task should ideally generate four versions:
+- `documentation.txt`: A concise, text-only overview for quick reading and AI context.
+- `documentation.md`: High-quality Markdown for version control and GitHub READMEs.
+- `documentation.html`: An interactive, premium documentation page with sidebar navigation.
+- `documentation-landing-page.html`: A visual, high-end landing page to showcase the project/plugin.
+
+### 2. Dynamic Design (Not Fixed Templates)
+- **Do NOT follow a rigid template**: The Agent must **design** the documentation layout and content structure specifically for the project.
+- **Synergy with ui-ux**: use of the `ui-ux` skill is **MANDATORY** for `documentation.html` and `documentation-landing-page.html`.
+
+### 3. Standard Quality Structure (Mandatory)
+To ensure clarity and completeness, the generated documentation MUST include:
+
+#### A. Interactive Documentation (documentation.html)
+1.  **Quick Start**: Clear steps to get running in < 2 minutes.
+2.  **System Requirements**: OS, versions, dependencies.
+3.  **Installation & Setup**: Detailed step-by-step guide.
+4.  **Configuration**: Explanation of all settings (config files, UI settings).
+5.  **Core Features**: Deep dive into each component found in `heraspec/specs/`.
+6.  **Technical Reference**: (For Devs) API endpoints, Hooks, Filters, Functions.
+7.  **Troubleshooting & FAQ**: Common issues and solutions.
+
+#### B. Premium Landing Page (documentation-landing-page.html)
+1.  **Hero Section**: High-impact headline and clear sub-headline.
+2.  **Value Proposition**: Briefly explain "The Problem" vs "The Solution".
+3.  **Feature Showcase**: A visual grid of key benefits with icons/images.
+4.  **How It Works**: A simplified 1-2-3 step process of using the project.
+5.  **CTA (Call to Action)**: Prominent buttons to "Get Started" or "View Docs".
+
+### 4. Visual Excellence
+- Use gradients, smooth animations (fade-in, slide), and premium fonts (e.g., Inter, Montserrat).
+- The HTML documentation should feel like a modern SaaS dashboard or a high-end technical manual.
+
+### 4. Project-Wide Scope
+When tasked with generating documentation for the entire project:
+- **Data Source**: Agent MUST read `heraspec/project.md` and ALL files in `heraspec/specs/`.
+- **Synthesis**: Agent must combine information from all components and features into a unified manual.
+- **Landing Page**: Should serve as the project homepage, summarizing the main value proposition and key features across all modules.
+
+## Implementation Steps
+
+### Step 1: Intelligence Gathering & Design Planning
+1. **Analyze Project**: Scan all relevant `.md` files in the project. Understand the core purpose and technical details.
+2. **Enforce UI/UX Dependency**:
+   - Check if `heraspec/skills/ui-ux/` exists.
+   - If missing: **Execute `heraspec skill add ui-ux`** immediately. Do NOT proceed with HTML generation until this skill is available.
+3. **Define Design System**: Consult the `ui-ux` skill to establish a visual language (colors, fonts, animation styles).
+4. **Plan Structures**: Outline what needs to go into the `.txt`, `.md`, and `.html` versions.
+
+### Step 2: Constructing Documentation Assets
+1. **Compose documentation.txt & .md**: Focus on clarity and technical accuracy.
+2. **Develop documentation.html**: Build a split-panel layout (Sidebar + Content). DO NOT just fill a template; **write the HTML/CSS/JS** needed to make it look premium and project-specific.
+3. **Design documentation-landing-page.html**: Create a compelling Hero section and feature showcase. Link to the main docs.
+
+## Required Input
+
+- **Project Context**: The name of the plugin/project (e.g., "polyutilities").
+- **Specs/Docs**: All existing documentation and specification files.
+- **Design Guidelines**: Inputs from the `ui-ux` skill.
+
+## Expected Output (Save to /documentations/)
+
+**CRITICAL**: All files MUST be placed in a `/documentations` folder at the project root. If this folder does not exist, the Agent MUST create it first.
+
+- `/documentations/documentation.txt`: Plain text overview.
+- `/documentations/documentation.md`: Markdown version.
+- `/documentations/documentation.html`: Interactive split-panel HTML.
+- `/documentations/documentation-landing-page.html`: Visual landing page.
+- `/documentations/style.css` & `/documentations/landing-style.css`: Custom-generated styles.
+- `/documentations/script.js` & `/documentations/landing-script.js`: Interactive logic.
+
+## Tone & Rules
+
+- **Consistent Content**: The core information must be synchronized across all formats.
+- **Design Autonomy**: The Agent is responsible for the final aesthetic and structural quality.
+- **Visual Impact**: Documentation must WOW the user with its premium feel.
+
+## Reference Templates
+These are provided as starting points or inspiration. The Agent should feel free to expand or modify them to suit the project:
+
+- `templates/documentation.html` - Base HTML documentation layout
+- `templates/documentation-landing-page.html` - Premium Landing Page layout
+- `templates/style.css` - Premium styles for HTML documentation
+- `templates/landing-style.css` - Premium styles for Landing Page
+- `templates/script.js` - Interactive logic for HTML documentation
+- `templates/landing-script.js` - Interactive logic for Landing Page
+- `templates/technical-doc-template.md` - Technical documentation
+- `templates/user-guide-template.md` - User guide
+- `templates/api-doc-template.md` - API documentation
+- `templates/changelog-template.md` - Changelog template
+
+## Links to Other Skills
+
+- **ui-ux**: ESSENTIAL. Use this to determine the look and feel of the HTML documentation.
+- **content-optimization**: Use to ensure the text is clear and professional.

package/dist/core/templates/skills/e2e-test-skill.md

@@ -1,119 +1,119 @@
-# Skill: End-to-End (E2E) Testing (Cross-Cutting)
-
-## Purpose
-
-This skill is used to create end-to-end tests that verify complete user workflows from start to finish. E2E tests simulate real user interactions with the application.
-
-## When to Use
-
-- When testing complete user workflows
-- When testing critical user journeys
-- When testing UI interactions
-- When verifying application behavior from user perspective
-- When testing authentication flows
-- When testing payment/transaction flows
-
-## Step-by-Step Process
-
-### Step 1: Identify User Journeys
-- Map critical user workflows
-- Identify key user scenarios
-- List user personas and their goals
-- Determine test priorities (critical paths first)
-- Document expected user behavior
-
-### Step 2: Set Up E2E Testing Framework
-- Choose E2E testing tool (Playwright, Cypress, Selenium, etc.)
-- Configure test environment
-- Set up test browser/headless mode
-- Configure test data and user accounts
-- Set up test application instance
-
-### Step 3: Write E2E Tests
-- Create test files for each user journey
-- Write tests simulating user actions (click, type, navigate)
-- Test complete workflows from start to finish
-- Verify UI elements and feedback
-- Test error scenarios and edge cases
-- Use page objects for maintainability
-
-### Step 4: Run and Verify
-- Run E2E tests
-- Verify tests pass consistently
-- Check test execution time
-- Review test failures and flakiness
-- Ensure tests are stable and reliable
-
-### Step 5: Maintain Tests
-- Update tests when UI changes
-- Keep page objects synchronized with UI
-- Document test scenarios
-- Monitor test stability
-
-## Required Input
-
-- **User journeys**: List of critical user workflows
-- **Test environment**: Application URL and test environment setup
-- **Test accounts**: User accounts for testing
-- **E2E framework**: Testing framework to use
-- **Browser**: Browser to test in (Chrome, Firefox, etc.)
-
-## Expected Output
-
-- E2E test files
-- Test scenarios covering user journeys
-- Page objects for UI elements
-- Passing E2E test suite
-- Documentation of E2E test scenarios
-
-## Tone & Rules
-
-### Test Scope
-- Focus on critical user journeys
-- Test from user perspective
-- Verify complete workflows
-- Test happy paths and error scenarios
-
-### Test Stability
-- Use reliable selectors (data-testid, stable IDs)
-- Add appropriate waits for async operations
-- Handle flaky elements (retries, explicit waits)
-- Keep tests independent and isolated
-
-### Performance
-- E2E tests are slowest (run separately)
-- Use headless mode for CI
-- Parallelize tests when possible
-- Consider test execution time
-
-### Limitations
-- ❌ DO NOT test every UI element (focus on journeys)
-- ❌ DO NOT use brittle selectors (XPath with complex paths)
-- ❌ DO NOT skip error handling
-- ❌ DO NOT write tests that depend on timing
-- ❌ DO NOT test implementation details
-
-## Available Templates
-
-- `templates/e2e-test-template.js` - JavaScript/Playwright template
-- `templates/e2e-test-template.ts` - TypeScript/Cypress template
-- `templates/e2e-test-template.py` - Python/Selenium template
-
-## Available Scripts
-
-- `scripts/setup-e2e-env.sh` - Set up E2E test environment
-- `scripts/run-e2e-tests.sh` - Run E2E test suite
-
-## Examples
-
-See `examples/` directory for reference:
-- `good-e2e-test/` - Well-structured E2E tests
-- `bad-e2e-test/` - Examples to avoid
-
-## Links to Other Skills
-
-- **unit-test**: Use for testing individual components
-- **integration-test**: Use for testing component interactions
-- **ui-ux**: Reference when testing UI interactions
-- **documents**: Use to document E2E test strategy
-
+# Skill: End-to-End (E2E) Testing (Cross-Cutting)
+
+## Purpose
+
+This skill is used to create end-to-end tests that verify complete user workflows from start to finish. E2E tests simulate real user interactions with the application.
+
+## When to Use
+
+- When testing complete user workflows
+- When testing critical user journeys
+- When testing UI interactions
+- When verifying application behavior from user perspective
+- When testing authentication flows
+- When testing payment/transaction flows
+
+## Step-by-Step Process
+
+### Step 1: Identify User Journeys
+- Map critical user workflows
+- Identify key user scenarios
+- List user personas and their goals
+- Determine test priorities (critical paths first)
+- Document expected user behavior
+
+### Step 2: Set Up E2E Testing Framework
+- Choose E2E testing tool (Playwright, Cypress, Selenium, etc.)
+- Configure test environment
+- Set up test browser/headless mode
+- Configure test data and user accounts
+- Set up test application instance
+
+### Step 3: Write E2E Tests
+- Create test files for each user journey
+- Write tests simulating user actions (click, type, navigate)
+- Test complete workflows from start to finish
+- Verify UI elements and feedback
+- Test error scenarios and edge cases
+- Use page objects for maintainability
+
+### Step 4: Run and Verify
+- Run E2E tests
+- Verify tests pass consistently
+- Check test execution time
+- Review test failures and flakiness
+- Ensure tests are stable and reliable
+
+### Step 5: Maintain Tests
+- Update tests when UI changes
+- Keep page objects synchronized with UI
+- Document test scenarios
+- Monitor test stability
+
+## Required Input
+
+- **User journeys**: List of critical user workflows
+- **Test environment**: Application URL and test environment setup
+- **Test accounts**: User accounts for testing
+- **E2E framework**: Testing framework to use
+- **Browser**: Browser to test in (Chrome, Firefox, etc.)
+
+## Expected Output
+
+- E2E test files
+- Test scenarios covering user journeys
+- Page objects for UI elements
+- Passing E2E test suite
+- Documentation of E2E test scenarios
+
+## Tone & Rules
+
+### Test Scope
+- Focus on critical user journeys
+- Test from user perspective
+- Verify complete workflows
+- Test happy paths and error scenarios
+
+### Test Stability
+- Use reliable selectors (data-testid, stable IDs)
+- Add appropriate waits for async operations
+- Handle flaky elements (retries, explicit waits)
+- Keep tests independent and isolated
+
+### Performance
+- E2E tests are slowest (run separately)
+- Use headless mode for CI
+- Parallelize tests when possible
+- Consider test execution time
+
+### Limitations
+- ❌ DO NOT test every UI element (focus on journeys)
+- ❌ DO NOT use brittle selectors (XPath with complex paths)
+- ❌ DO NOT skip error handling
+- ❌ DO NOT write tests that depend on timing
+- ❌ DO NOT test implementation details
+
+## Available Templates
+
+- `templates/e2e-test-template.js` - JavaScript/Playwright template
+- `templates/e2e-test-template.ts` - TypeScript/Cypress template
+- `templates/e2e-test-template.py` - Python/Selenium template
+
+## Available Scripts
+
+- `scripts/setup-e2e-env.sh` - Set up E2E test environment
+- `scripts/run-e2e-tests.sh` - Run E2E test suite
+
+## Examples
+
+See `examples/` directory for reference:
+- `good-e2e-test/` - Well-structured E2E tests
+- `bad-e2e-test/` - Examples to avoid
+
+## Links to Other Skills
+
+- **unit-test**: Use for testing individual components
+- **integration-test**: Use for testing component interactions
+- **ui-ux**: Reference when testing UI interactions
+- **documents**: Use to document E2E test strategy
+

package/dist/core/templates/skills/git-embed-skill.md

@@ -0,0 +1,57 @@
+# Skill: Git Embed
+
+## Purpose
+
+This skill establishes a nested Git repository structure (Monorepo) where the outer (parent) repository physically tracks and stores the source code of an inner (child) repository, without using the standard Git Submodule mechanism. This allows the child repository to retain its own `.git` directory for independent committing and pushing.
+
+## When to Use
+
+- When migrating an existing Git repository to be embedded within a parent Monorepo.
+- When the parent repository needs full direct physical access to the child's source files.
+- When you need to avoid "empty folder" issues caused by standard Git submodules during cloning.
+- When you want to commit and push independently from both the parent root and the child root.
+
+## Step-by-Step Process
+
+### Step 1: Remove Submodule References (If Any)
+- Ensure the inner repository is not tracked as a submodule.
+- Run `git rm -r --cached <child-folder>` from the parent root.
+- Remove `.gitmodules` if it exists: `rm .gitmodules` and `git add .gitmodules` (if tracked).
+
+### Step 2: Temporary `.git` Relocation
+- Move the inner repository's `.git` directory out of the way to prevent Git from treating it as an embedded repo.
+- Run `mv <child-folder>/.git /tmp/<child-name>_git_bak`.
+
+### Step 3: Embed Source Code into Parent
+- Add the inner folder directly to the parent repository.
+- Run `git add <child-folder>/`.
+- Commit the changes: `git commit -m "Embed full source of <child-name> independent of submodule"`.
+
+### Step 4: Restore Independent `.git`
+- Move the inner repository's `.git` directory back to its original location.
+- Run `mv /tmp/<child-name>_git_bak <child-folder>/.git`.
+
+### Step 5: Verification
+- Run `git status` in the parent directory to ensure no submodule links are shown.
+- Navigate into `<child-folder>` and run `git status` to verify the independent repository tracking is intact.
+
+## Required Input
+
+- **Child folder path**: The relative path to the nested repository.
+- **Child name**: A short identifier used for the backup directory.
+
+## Expected Output
+
+- The parent's remote repository will contain all physical files natively without gitlinks.
+- The child folder will retain its `.git` folder for completely independent repository operations.
+
+## Tone & Rules
+
+### Git Rules
+- The child folder's `.gitignore` MUST be preserved, as the parent git will natively respect `.gitignore` rules in subdirectories.
+- Ensure all uncommitted changes in the parent repo are stashed or committed before starting.
+
+### Limitations
+- ❌ DO NOT use `git submodule add` under any circumstances for this skill.
+- ❌ DO NOT delete the inner `.git` folder permanently.
+- ❌ DO NOT use `git subtree` as it creates a different tracking model.