🌐 Website • 💻 GitHub • 📦 NPM • 📚 Documentation
HeraSpec is a specification-based development framework that helps you:
- Plan before coding by creating detailed project specifications
- Track changes through delta specifications
- Work across multiple project types (WordPress, Laravel, React, etc.)
- Integrate with AI tools for better development workflow
Note: HeraSpec is a workflow framework that I have personally designed, tested, and continuously refined through real-world production use. It is primarily optimized for small to medium-sized projects, especially for solo developers and freelancers building products independently — including plugins, modules, themes, templates, and software distributed on platforms such as Envato.
HeraSpec serves as the specification and workflow backbone behind the entire PolyCMS.org ecosystem and multiple commercial products developed under the Antigravity workflow.
It powers AI-assisted architecture planning, specification management, documentation pipelines, content operations, and development workflows through a multi-model ecosystem built around Google Gemini, OpenAI ChatGPT, and Anthropic Claude Opus.
Because HeraSpec evolved from practical production needs rather than enterprise-first design, some structures, conventions, or workflows may not be fully standardized or suitable for highly complex large-scale organizations. In such cases, you are encouraged to adapt, simplify, or restructure the system to better fit your own workflow and operational requirements — including asking your AI agents to customize and extend it accordingly.
If you have ideas, improvements, or additional skills that could enhance HeraSpec, contributions and suggestions are always welcome.
Good luck, and build with love.
Here are some products built partially or entirely using the HeraSpec framework:
- FlexNote for Perfex CRM - Advanced note management with AI capabilities.
- PolyUtilities for Perfex CRM - Essential toolkit for Perfex CRM customization.
- Data Builder — Visual Reporting, REST API & GraphQL for Perfex CRM - Automated demo instance creator.
- FlexNote - Sticky Notes for Web - Create, manage, and customize notes directly on any webpage.
GitHub: FlexNote - Smart Sticky Notes - PolyMetrics - Product price analysis extension for Envato.
- PolyDemo - Dynamic demonstration environment for web applications.
- Smart Payment for Perfex CRM - Intelligent payment gateway integration.
- PolyCMS.org - Open Source CMS based on Laravel, inspired by WordPress CMS.
- PolyCMS – CMS & Website Builder Module for Perfex CRM - A CMS system inspired by WordPress integrated into the open-source Perfex CRM.
- WooCommerce Sync for Perfex CRM - A module for syncing products, customers, orders, and data between Perfex CRM and WooCommerce stores.
- HeadRandom.com - Products and content on this platform are managed with the support of HeraSpec.
- Xem Ngày Tốt Xấu
- Xem và Lập Lá Số Tứ Trụ - Bát Tự
- Giao Quẻ Kinh Dịch - Lục Hào - Mai Hoa Tiên Thiên
- Thước Lập Cực
- Xem Chỉ Tay
- Diện Tướng
This project uses HeraSpec for spec-driven development. For more information, see the HeraSpec documentation.
# 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>heraspec/project.md- Project overview and configurationheraspec/specs/- Source of truth specificationsheraspec/changes/- Active changes in progressheraspec/skills/- Reusable skills for AI agentsAGENTS.heraspec.md- AI agent instructions
- Create a change: Ask AI to create a HeraSpec change, or create manually
- Refine specs: Review and update delta specs in
heraspec/specs/<change-name>/ - Implement: Follow tasks in
heraspec/changes/<change-name>/tasks.md - Archive: Run
heraspec archive <change-name> --yeswhen complete
Add skills to your project:
# 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-uxFor more information, see the HeraSpec documentation.
This section is automatically updated by heraspec init. Last updated: 2026-05-21
npm install -g heraspecgit clone https://github.com/PolyXGO/HeraSpec.git
cd HeraSpec
npm install
npm run build
npm link# 1. Scaffold a new module or plugin with Clean Architecture
heraspec create my_module --type perfex-module
# 2. Or initialize HeraSpec in an existing codebase
cd my-project
heraspec init
# 3. Audit codebase for code quality, security (OWASP) & clean standards
heraspec audit --fix
# 4. Package clean production .zip release (strips dev bloat)
heraspec pack| Command | Description |
|---|---|
heraspec create <name> [--type <t>] |
Scaffold new module or plugin adhering to Clean Architecture standards |
heraspec audit [path] [--fix] |
Automated code quality, security, concurrency, and clean code auditor |
heraspec pack [path] [--out <dir>] |
Auto-compile assets and package production .zip release without dev bloat |
heraspec init [path] |
Initialize HeraSpec (with smart re-init and custom skill preservation) |
heraspec list [--specs] |
List active changes or specifications |
heraspec show <name> |
Display detailed change proposal or specification |
heraspec validate <name> |
Validate specification integrity and consistency |
heraspec archive <name> --yes |
Merge completed delta specs into source of truth |
heraspec sync <name> |
Sync change with source specs to resolve parallel merge conflicts |
heraspec skill list |
List all available built-in and project-specific skills |
heraspec skill add <name> |
Install a skill suite to the project |
heraspec memory context |
Generate token-efficient agent session context |
heraspec helper |
Interactive CLI usage guide and prompts |
- ✅ Enterprise Code Quality Auditor (
heraspec auditwith 7 automated checks and safe auto-fix) - ✅ Clean Architecture Scaffolder (
heraspec createfor Perfex CRM, WordPress plugins/themes) - ✅ Production Release Packager (
heraspec packwith cross-platform compression & strict bloat exclusion) - ✅ Custom Skill Preservation (Existing projects safely retain custom skills on
heraspec init) - ✅ Multi-project type support (WordPress, Perfex CRM, Laravel, React, Vue, Node.js)
- ✅ Specification-driven development with delta specs and conflict-free parallel merging
- ✅ AI Integration Ready (Cursor, Antigravity, Windsurf, Copilot, Claude Desktop)
- ✅ Proactive Memory & Semantic Search (Token savings & architecture tracking)
Integrate with AI tools for better development workflow: Cursor, Antigravity, Windsurf, Copilot, and Claude Desktop. HeraSpec automatically generates specifications that AI tools can understand and implement.
- Cursor - Native AGENTS.md support for automatic change creation
- Antigravity - AGENTS.md integration for spec-driven development
- Windsurf - AI-powered workflow with HeraSpec specifications
- Copilot - Enhanced development with structured specs
- Claude Desktop - MCP-ready architecture for AI assistance
If you find this source code helpful, consider buying me a coffee to support my work! ☕
-or-
MIT License - see LICENSE file for details.