heraspec 0.1.12 → 0.1.14

package/dist/core/templates/skills/scripts/search.py

@@ -4,7 +4,7 @@
 UI/UX Builder Search - BM25, Vector, and Hybrid search engine for UI/UX style guides
 Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--mode <mode>] [--max-results 3]
 
-Domains: style, prompt, color, chart, landing, product, ux, typography, pages
+Domains: style, prompt, color, chart, landing, product, ux, typography, pages, design-system
 Stacks: html-tailwind, react, nextjs, vue, svelte, swiftui, react-native, flutter
 Modes: bm25 (default), vector, hybrid
 

package/dist/core/templates/skills/smart-explore-skill.md

@@ -0,0 +1,141 @@
+---
+name: smart-explore
+description: Token-efficient code exploration — view file structure, search symbols, and read specific implementations without loading full files. Reduces token usage by 4-18x compared to reading entire files.
+projectType: all
+---
+
+# Smart Explore Skill
+
+## Purpose
+
+Enable AI agents to **explore codebases efficiently** by viewing structural outlines, searching for symbols, and extracting specific implementations — without reading entire files. This dramatically reduces token consumption when navigating large projects.
+
+## When to Use
+
+- **Understanding a new file**: Use `outline` instead of reading the full file
+- **Finding where something is defined**: Use `search` to locate symbols across the project
+- **Reading a specific function**: Use `unfold` to extract just that function's code
+
+## Token Savings
+
+| Method | Typical Token Cost | Notes |
+|--------|-------------------|-------|
+| Read full file | ~12,000+ | All content, most irrelevant |
+| **Outline** | ~1,000-2,000 | Structural skeleton only |
+| **Search** | ~2,000-6,000 | Symbol locations across codebase |
+| **Unfold** | ~400-2,100 | Exact function/class source |
+
+**Savings: 4-18x** compared to reading full files.
+
+## Available Commands
+
+### 1. Outline — Structural Skeleton
+
+View all symbols (functions, classes, interfaces, exports) in a file without reading the full source:
+
+```bash
+heraspec explore outline src/core/memory/memory-store.ts
+```
+
+**Output example:**
+```
+## 📄 src/core/memory/memory-store.ts
+*typescript | 285 lines | ~71250 tokens*
+
+🏛️ export class MemoryStore (L20-285)
+  ↳ open() (L32-58)
+  ↳ close() (L63-68)
+  ↳ addObservation(input) (L88-120)
+  ↳ getObservationById(id) (L125-132)
+  ↳ getRecentObservations(project, limit) (L140-160)
+  ↳ addSummary(input) (L165-195)
+  ↳ getStatus(project) (L200-260)
+```
+
+### 2. Search — Find Symbols Across Codebase
+
+Search for functions, classes, interfaces by name across the project:
+
+```bash
+heraspec explore search "MemoryStore" src/
+heraspec explore search "addObservation" src/ --limit 10
+```
+
+**Output example:**
+```
+## Symbol Search: "MemoryStore" (3 results)
+
+| Rel | Type | Name | File | Lines |
+|-----|------|------|------|-------|
+| 100% | 🏛️ class | MemoryStore | src/core/memory/memory-store.ts | L20-285 |
+| 60% | ⚡ function | MemoryStoreFactory | src/core/memory/index.ts | L10-15 |
+| 40% | 📌 variable | memoryStore | src/commands/memory.ts | L25-25 |
+```
+
+### 3. Unfold — Extract Specific Symbol Source
+
+Read just the implementation of a specific function or class:
+
+```bash
+heraspec explore unfold src/core/memory/memory-store.ts addObservation
+```
+
+**Output example:**
+```
+## method: addObservation
+*src/core/memory/memory-store.ts:L88-120 | ~800 tokens (vs ~71250 full file)*
+
+  addObservation(input: ObservationInput): Observation {
+    this.ensureOpen();
+    // ... full implementation
+  }
+```
+
+## Supported Languages
+
+| Language | Extensions | Symbols Detected |
+|----------|-----------|-----------------|
+| TypeScript | `.ts`, `.tsx` | class, interface, type, enum, function, method, variable |
+| JavaScript | `.js`, `.jsx`, `.mjs` | class, function, method, variable |
+| Python | `.py` | class, function, method, variable |
+| PHP | `.php` | class, interface, function |
+| Go | `.go` | struct, interface, func |
+| Rust | `.rs` | struct, trait, enum, fn |
+| Java | `.java` | class, interface, method |
+| C# | `.cs` | class, interface, method |
+| Vue | `.vue` | Same as TypeScript |
+| Svelte | `.svelte` | Same as TypeScript |
+
+## Workflow for AI Agents
+
+### Exploration Strategy
+
+```
+Need to understand a file?
+├── Step 1: heraspec explore outline <file>
+│   → See all functions, classes, interfaces (~1K tokens)
+├── Step 2: Identify relevant symbols from outline
+├── Step 3: heraspec explore unfold <file> <symbol>
+│   → Read just the relevant function (~400-2K tokens)
+└── Only read full file if you need comprehensive understanding
+
+Need to find where something is?
+├── heraspec explore search "<name>" <path>
+│   → Find symbol locations across codebase
+├── Then use unfold to read specific implementations
+└── Avoid grep-like full-text search when possible
+```
+
+### Key Principles
+
+1. **Outline first, read later**: Always check the outline before reading full files
+2. **Unfold specific symbols**: Don't read entire files when you only need one function
+3. **Search before browsing**: Find what you need by name rather than scanning directories
+4. **Skip node_modules, dist, .git**: Automatically excluded from search
+
+## Limitations
+
+- Uses regex-based parsing (not AST) — may miss some complex patterns
+- Symbol end-line detection is approximate (brace/indent counting)
+- Method detection within classes requires proper indentation
+- Does not handle dynamically generated code or macros

package/dist/core/templates/skills/sourcecode-analyzer-skill.md

@@ -0,0 +1,210 @@
+---
+name: sourcecode-analyzer
+description: Multi-agent deep source code analysis for architecture, coding style, design patterns, languages, frameworks, libraries, module structure, extension points, and integration readiness. Use when agents must understand a codebase before planning features, refactoring, integration, migration, auditing, or documentation.
+projectType: all
+---
+
+# Source Code Analyzer
+
+## Objective
+Produce a high-confidence architecture and integration analysis of the repository with evidence from real files.
+
+## Scope
+Analyze:
+- Architecture boundaries and layering
+- Framework/CMS/runtime and dependency stack
+- Coding style and conventions
+- Modules/themes/plugins and extension points
+- API surfaces (REST/GraphQL/webhooks/events/CLI/jobs)
+- Data layer and configuration model
+- Security and operational posture
+- Integration capability and constraints
+
+Do not:
+- Modify business logic
+- Run destructive commands
+- Install or upgrade dependencies unless requested
+
+## Required Output
+Write a report to `_analytics/structure.md` (or user-provided path) with the exact section order defined in "Report Template".
+
+## Evidence Rules
+For every important claim:
+- Include concrete evidence (file path, symbol/class/function, and short snippet summary)
+- Mark confidence as `High`, `Medium`, or `Low`
+- Label statement type:
+  - `Observed`: Directly confirmed in source
+  - `Inferred`: Derived from multiple observed facts
+  - `Assumed`: Plausible but not yet confirmed
+
+Avoid ungrounded conclusions.
+
+## Multi-Agent Orchestration
+If subagents are available, split work in parallel:
+
+1. `Architecture lane`
+- Map directory topology, layers, modules/plugins/themes
+- Identify entry points and dependency direction
+
+2. `Style and design lane`
+- Detect naming conventions, folder conventions, patterns, anti-patterns
+- Detect coding standards and linting/testing quality gates
+
+3. `Dependency and runtime lane`
+- Detect language/runtime/framework versions
+- Inventory key libraries and their roles
+
+4. `Integration and security lane`
+- Map APIs, events/hooks, queues, cron/jobs, webhooks, third-party SDKs
+- Assess authN/authZ, input validation, secrets handling, and attack surface
+
+Coordinator responsibilities:
+- Normalize lane outputs
+- Resolve contradictions
+- Produce one final report with evidence and confidence
+
+If subagents are unavailable, execute the same lanes sequentially.
+
+## Workflow
+
+### Step 0 — Knowledge Lookup (Pre-Analysis)
+Before starting full analysis, check if pre-analyzed knowledge exists:
+
+1. Check if `heraspec/knowledge/index.json` exists in the project
+2. Read all entries and match against the current project:
+   - For `file-contains` signals: check if the file exists AND contains the specified string
+   - For `directory-exists` signals: check if the directory exists
+   - Each matched signal = +1 to the match score
+3. If `score >= minMatchScore` for any entry:
+   - Read the corresponding `structure.md` from `heraspec/knowledge/<knowledgePath>/`
+   - Use it as the **baseline analysis** — skip redundant Steps 1-8 for sections already covered
+   - Focus only on **project-specific differences** (custom plugins, configs, .env, custom code)
+   - Output: merge baseline knowledge + project-specific delta into final report
+4. Also check `heraspec/knowledge/custom/index.json` for project-specific knowledge entries
+5. If no match found in either index: proceed with full analysis from Step 1
+
+Knowledge hierarchy: `heraspec/knowledge/<category>/<runtime>/<framework>/<cms>/`
+
+### Step 1 - Baseline Metadata
+Read root metadata first:
+- `composer.json`, `composer.lock`
+- `package.json`, lockfiles
+- `docker*`, `Makefile`, CI configs
+- `.env.example`, config directories
+
+Capture:
+- Language/runtime versions
+- Framework/CMS versions
+- Build and deployment model
+
+### Step 2 - Repository Topology
+Map major folders and responsibilities:
+- Core/domain/infrastructure boundaries
+- Plugin/module/theme architecture
+- Shared libraries and cross-cutting concerns
+- Bootstrapping and entry points
+
+### Step 3 - Architectural Patterns
+Identify and evaluate:
+- Layered/hexagonal/modular/monolith/microservice patterns
+- Service container/DI usage
+- Event-driven flows
+- Boundaries and coupling hotspots
+
+### Step 4 - Coding Style and Design Conventions
+Inspect representative files from each major layer:
+- Naming conventions (class/function/file)
+- Folder and namespace strategy
+- Error handling patterns
+- Test style and coverage signals
+- Static analysis/lint/format rules
+
+### Step 5 - Extension Model
+Map extensibility mechanisms:
+- Hooks/filters/events/listeners
+- Plugin/module registration and lifecycle
+- Theme/template override model
+- Custom providers, middleware, policies
+
+### Step 6 - API and Interaction Surfaces
+Inventory internal and external interfaces:
+- REST/GraphQL routes and controllers
+- Command bus, queues, jobs, schedulers
+- CLI commands, webhooks, callbacks
+- Public SDK/service abstractions
+
+### Step 7 - Data and State
+Analyze:
+- ORM/data access strategy
+- Migration and seeding patterns
+- Cache/session/queue drivers
+- Transaction boundaries and consistency risks
+
+### Step 8 - Security and Compliance Signals
+Check:
+- Authentication and authorization model
+- CSRF/XSS/SQLi protections
+- Secrets and credential handling
+- Rate limiting and abuse protection
+- Audit logging and sensitive operation traces
+
+### Step 9 - Integration Readiness
+Evaluate integration capability across:
+- Data integration
+- API integration
+- Event integration
+- UI/theme integration
+- Deployment/infra integration
+
+For each integration type, summarize:
+- Available entry points
+- Required adapters
+- Estimated complexity (`Low`/`Medium`/`High`)
+- Major risks and mitigations
+
+### Step 10 - Synthesis
+Consolidate findings into one report, prioritize evidence-backed conclusions, and list unknowns that block confidence.
+
+## Report Template
+
+Use this exact section order in `_analytics/structure.md`:
+
+1. `Executive Summary`
+2. `Technology Profile`
+3. `Repository Topology`
+4. `Architecture and Dependency Flow`
+5. `Coding Style and Conventions`
+6. `Extension Points (Modules/Themes/Plugins/Hooks)`
+7. `API and Interaction Surfaces`
+8. `Data Model and State Management`
+9. `Security Posture`
+10. `Integration Capability Matrix`
+11. `Strengths, Weaknesses, Risks`
+12. `Top 10 Evidence Items`
+13. `Unknowns and Verification Plan`
+14. `Recommended Next Actions (30/60/90 day)`
+
+## Integration Capability Matrix Format
+
+Use one row per integration domain:
+
+| Domain | Entry Points | Required Adapters | Complexity | Risks | Confidence |
+|---|---|---|---|---|---|
+
+Domains to include:
+- External APIs
+- Authentication/SSO
+- Payment
+- Messaging/Queue
+- Storage/CDN
+- Observability
+- Admin/UI customization
+- Content/data migration
+
+## Completion Checklist
+Complete the skill execution only when all conditions are met:
+- Report file exists at target path
+- Every critical claim has evidence
+- Assumptions are explicitly marked
+- Integration matrix is complete
+- Top risks include mitigation guidance

package/dist/core/templates/skills/sourcecode-analyzer-skill.vi.md

@@ -0,0 +1,210 @@
+---
+name: sourcecode-analyzer
+description: Phân tích sâu source code theo mô hình đa agent cho kiến trúc, coding style, design pattern, ngôn ngữ, framework, thư viện, cấu trúc module, extension point và khả năng tích hợp. Sử dụng khi agent cần hiểu tối đa codebase trước khi lập kế hoạch feature, refactor, integration, migration, audit hoặc documentation.
+projectType: all
+---
+
+# Source Code Analyzer (Tiếng Việt)
+
+## Mục tiêu
+Tạo báo cáo phân tích kiến trúc và khả năng tích hợp có độ tin cậy cao, dựa trên bằng chứng trực tiếp từ source code.
+
+## Phạm vi
+Phân tích:
+- Ranh giới kiến trúc và phân lớp
+- Stack framework/CMS/runtime và dependency
+- Coding style và conventions
+- Modules/themes/plugins và extension points
+- API surfaces (REST/GraphQL/webhooks/events/CLI/jobs)
+- Data layer và mô hình cấu hình
+- Bảo mật và vận hành
+- Khả năng tích hợp và các ràng buộc
+
+Không:
+- Sửa business logic
+- Chạy lệnh hủy hoại
+- Cài đặt hoặc nâng cấp dependency nếu chưa được yêu cầu
+
+## Đầu ra bắt buộc
+Ghi báo cáo vào `_analytics/structure.md` (hoặc đường dẫn do người dùng chỉ định), đúng thứ tự section như trong `Report Template`.
+
+## Quy tắc bằng chứng
+Mỗi nhận định quan trọng phải:
+- Có bằng chứng cụ thể (đường dẫn file, symbol/class/function, tóm tắt snippet ngắn)
+- Gán mức độ tin cậy `High`, `Medium` hoặc `Low`
+- Gán loại nhận định:
+  - `Observed`: Xác nhận trực tiếp trong source
+  - `Inferred`: Suy ra từ nhiều quan sát đã xác thực
+  - `Assumed`: Giả định hợp lý nhưng chưa xác thực
+
+Không đưa ra kết luận không có cơ sở.
+
+## Điều phối đa agent
+Nếu có subagents, tách song song 4 lane:
+
+1. `Architecture lane`
+- Lập bản đồ topology thư mục, layers, modules/plugins/themes
+- Xác định entry points và hướng phụ thuộc
+
+2. `Style and design lane`
+- Xác định naming conventions, folder conventions, patterns, anti-patterns
+- Xác định coding standards và quality gates (lint/test/static check)
+
+3. `Dependency and runtime lane`
+- Xác định ngôn ngữ/runtime/framework versions
+- Inventory thư viện quan trọng và vai trò
+
+4. `Integration and security lane`
+- Lập bản đồ APIs, events/hooks, queues, cron/jobs, webhooks, third-party SDKs
+- Đánh giá authN/authZ, input validation, secrets handling và attack surface
+
+Nhiệm vụ của coordinator:
+- Chuẩn hóa output của các lane
+- Xử lý mâu thuẫn giữa các lane
+- Tổng hợp 1 báo cáo cuối cùng có bằng chứng và confidence
+
+Nếu không có subagents, chạy tuần tự theo cùng quy trình lane.
+
+## Workflow
+
+### Step 0 — Knowledge Lookup (Tra cứu kiến thức sẵn có)
+Trước khi phân tích toàn bộ, kiểm tra knowledge base đã có sẵn:
+
+1. Kiểm tra `heraspec/knowledge/index.json` có tồn tại trong dự án không
+2. Đọc tất cả entries và đối chiếu với dự án hiện tại:
+   - Với signal `file-contains`: kiểm tra file tồn tại VÀ chứa chuỗi chỉ định
+   - Với signal `directory-exists`: kiểm tra thư mục tồn tại
+   - Mỗi signal khớp = +1 điểm match score
+3. Nếu `score >= minMatchScore` cho bất kỳ entry nào:
+   - Đọc `structure.md` tương ứng từ `heraspec/knowledge/<knowledgePath>/`
+   - Sử dụng làm **baseline phân tích** — bỏ qua Steps 1-8 cho các section đã có
+   - Chỉ tập trung vào **khác biệt riêng dự án** (custom plugins, configs, .env, custom code)
+   - Đầu ra: gộp baseline knowledge + delta riêng dự án thành báo cáo cuối
+4. Kiểm tra thêm `heraspec/knowledge/custom/index.json` cho knowledge riêng dự án
+5. Nếu không match: tiến hành phân tích đầy đủ từ Step 1
+
+Phân cấp knowledge: `heraspec/knowledge/<category>/<runtime>/<framework>/<cms>/`
+
+### Step 1 - Baseline Metadata
+Đọc metadata ở root trước:
+- `composer.json`, `composer.lock`
+- `package.json`, lockfiles
+- `docker*`, `Makefile`, CI configs
+- `.env.example`, config directories
+
+Thu thập:
+- Language/runtime versions
+- Framework/CMS versions
+- Build và deployment model
+
+### Step 2 - Repository Topology
+Lập bản đồ thư mục chính và trách nhiệm:
+- Core/domain/infrastructure boundaries
+- Kiến trúc plugin/module/theme
+- Shared libraries và cross-cutting concerns
+- Bootstrapping và entry points
+
+### Step 3 - Architectural Patterns
+Xác định và đánh giá:
+- Layered/hexagonal/modular/monolith/microservice patterns
+- Sử dụng service container/DI
+- Event-driven flows
+- Điểm nóng coupling và boundaries
+
+### Step 4 - Coding Style and Design Conventions
+Kiểm tra các file đại diện mỗi layer:
+- Naming conventions (class/function/file)
+- Folder và namespace strategy
+- Error handling patterns
+- Test style và coverage signals
+- Static analysis/lint/format rules
+
+### Step 5 - Extension Model
+Lập bản đồ cơ chế mở rộng:
+- Hooks/filters/events/listeners
+- Đăng ký module/plugin và lifecycle
+- Theme/template override model
+- Custom providers, middleware, policies
+
+### Step 6 - API and Interaction Surfaces
+Thống kê interfaces nội bộ và bên ngoài:
+- REST/GraphQL routes và controllers
+- Command bus, queues, jobs, schedulers
+- CLI commands, webhooks, callbacks
+- Public SDK/service abstractions
+
+### Step 7 - Data and State
+Phân tích:
+- ORM/data access strategy
+- Migration và seeding patterns
+- Cache/session/queue drivers
+- Transaction boundaries và consistency risks
+
+### Step 8 - Security and Compliance Signals
+Kiểm tra:
+- Authentication và authorization model
+- CSRF/XSS/SQLi protections
+- Secrets và credential handling
+- Rate limiting và abuse protection
+- Audit logging và trace các thao tác nhạy cảm
+
+### Step 9 - Integration Readiness
+Đánh giá khả năng tích hợp theo:
+- Data integration
+- API integration
+- Event integration
+- UI/theme integration
+- Deployment/infra integration
+
+Mỗi loại tích hợp cần tóm tắt:
+- Entry points hiện có
+- Adapters cần bổ sung
+- Độ phức tạp ước tính (`Low`/`Medium`/`High`)
+- Rủi ro chính và hướng giảm thiểu
+
+### Step 10 - Synthesis
+Tổng hợp findings vào một báo cáo, ưu tiên kết luận có bằng chứng, và liệt kê unknowns đang cần xác minh.
+
+## Report Template
+
+Sử dụng đúng thứ tự section sau trong `_analytics/structure.md`:
+
+1. `Executive Summary`
+2. `Technology Profile`
+3. `Repository Topology`
+4. `Architecture and Dependency Flow`
+5. `Coding Style and Conventions`
+6. `Extension Points (Modules/Themes/Plugins/Hooks)`
+7. `API and Interaction Surfaces`
+8. `Data Model and State Management`
+9. `Security Posture`
+10. `Integration Capability Matrix`
+11. `Strengths, Weaknesses, Risks`
+12. `Top 10 Evidence Items`
+13. `Unknowns and Verification Plan`
+14. `Recommended Next Actions (30/60/90 day)`
+
+## Integration Capability Matrix Format
+
+Mỗi integration domain là 1 dòng:
+
+| Domain | Entry Points | Required Adapters | Complexity | Risks | Confidence |
+|---|---|---|---|---|---|
+
+Bắt buộc gồm:
+- External APIs
+- Authentication/SSO
+- Payment
+- Messaging/Queue
+- Storage/CDN
+- Observability
+- Admin/UI customization
+- Content/data migration
+
+## Completion Checklist
+Chỉ kết thúc skill khi đủ các điều kiện:
+- Report tồn tại ở đường dẫn mục tiêu
+- Mỗi nhận định quan trọng đều có bằng chứng
+- Giả định được đánh dấu rõ ràng
+- Integration matrix đầy đủ
+- Top risks có hướng giảm thiểu đề xuất