@hivehub/rulebook 1.2.0

package/templates/commands/rulebook-task-list.md

@@ -0,0 +1,42 @@
+---
+name: /rulebook-task-list
+id: rulebook-task-list
+category: Rulebook
+description: List all Rulebook tasks (active and optionally archived).
+---
+<!-- RULEBOOK:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `/rulebook/RULEBOOK.md` for complete task management guidelines.
+
+**Steps**
+1. **List Active Tasks**:
+   ```bash
+   rulebook task list
+   ```
+   Shows all active tasks with their status (pending, in-progress, completed, blocked).
+
+2. **List Including Archived**:
+   ```bash
+   rulebook task list --archived
+   ```
+   Shows both active and archived tasks.
+
+3. **Review Task Status**:
+   - **pending**: Task not started
+   - **in-progress**: Task being worked on
+   - **completed**: Task finished (ready for archive)
+   - **blocked**: Task blocked by dependency
+
+4. **Select Task to Work On**:
+   - Choose task with highest priority
+   - Check task status before starting
+   - Verify task is not blocked
+
+**Reference**
+- Use `rulebook task show <task-id>` to view task details
+- Use `rulebook task validate <task-id>` to check task format
+- See `/rulebook/RULEBOOK.md` for complete task management guidelines
+<!-- RULEBOOK:END -->
+

package/templates/commands/rulebook-task-show.md

@@ -0,0 +1,52 @@
+---
+name: /rulebook-task-show
+id: rulebook-task-show
+category: Rulebook
+description: Show detailed information about a specific Rulebook task.
+---
+<!-- RULEBOOK:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `/rulebook/RULEBOOK.md` for complete task management guidelines.
+
+**Steps**
+1. **Show Task Details**:
+   ```bash
+   rulebook task show <task-id>
+   ```
+   Displays:
+   - Task ID and title
+   - Status (pending, in-progress, completed, blocked)
+   - Created and updated dates
+   - Archive date (if archived)
+   - Proposal summary
+   - Spec files list
+
+2. **Review Proposal**:
+   - Read `proposal.md` to understand why and what changes
+   - Check impact assessment
+   - Verify breaking changes are documented
+
+3. **Review Tasks Checklist**:
+   - Check `tasks.md` for implementation checklist
+   - Identify completed items (`[x]`)
+   - Identify pending items (`[ ]`)
+   - Follow priority order (most critical first)
+
+4. **Review Spec Deltas**:
+   - Check `specs/*/spec.md` files
+   - Verify format compliance (SHALL/MUST, 4 hashtags for scenarios)
+   - Understand requirements and scenarios
+
+5. **Check Task Status**:
+   - Verify task is not blocked
+   - Check if task is ready for implementation
+   - Confirm all prerequisites are met
+
+**Reference**
+- Use `rulebook task list` to see all tasks
+- Use `rulebook task validate <task-id>` to check task format
+- See `/rulebook/RULEBOOK.md` for complete task management guidelines
+<!-- RULEBOOK:END -->
+

package/templates/commands/rulebook-task-validate.md

@@ -0,0 +1,53 @@
+---
+name: /rulebook-task-validate
+id: rulebook-task-validate
+category: Rulebook
+description: Validate Rulebook task format against OpenSpec-compatible requirements.
+---
+<!-- RULEBOOK:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `/rulebook/RULEBOOK.md` for complete task management guidelines and format requirements.
+
+**Steps**
+1. **Validate Task Format**:
+   ```bash
+   rulebook task validate <task-id>
+   ```
+   Checks:
+   - Purpose section length (≥20 characters)
+   - Requirement keywords (SHALL/MUST)
+   - Scenario format (4 hashtags, not 3)
+   - Given/When/Then structure
+   - Delta headers format (ADDED/MODIFIED/REMOVED/RENAMED)
+
+2. **Review Validation Results**:
+   - **Errors**: Must be fixed before proceeding
+   - **Warnings**: Should be addressed but not blocking
+
+3. **Fix Format Issues**:
+   - **Purpose too short**: Expand "Why" section to ≥20 characters
+   - **Missing SHALL/MUST**: Add SHALL or MUST keyword to requirements
+   - **Wrong scenario format**: Change `### Scenario:` to `#### Scenario:` (4 hashtags)
+   - **Missing Given/When/Then**: Replace bullet points with Given/When/Then structure
+   - **Wrong delta headers**: Use ADDED/MODIFIED/REMOVED/RENAMED, not "New Requirements"
+
+4. **Re-validate After Fixes**:
+   ```bash
+   rulebook task validate <task-id>
+   ```
+   Ensure all errors are resolved.
+
+5. **Common Format Errors**:
+   - ❌ `### Scenario:` (3 hashtags) → ✅ `#### Scenario:` (4 hashtags)
+   - ❌ "The system provides X" → ✅ "The system SHALL provide X"
+   - ❌ `- WHEN user does X THEN Y` → ✅ `Given X\nWhen Y\nThen Z`
+   - ❌ `## New Requirements` → ✅ `## ADDED Requirements`
+
+**Reference**
+- See `/rulebook/RULEBOOK.md` for complete format requirements
+- Use Context7 MCP to get official OpenSpec format documentation
+- Use `rulebook task show <task-id>` to view task details
+<!-- RULEBOOK:END -->
+

package/templates/core/AGENT_AUTOMATION.md

@@ -0,0 +1,184 @@
+<!-- AGENT_AUTOMATION:START -->
+# Agent Automation Rules
+
+**CRITICAL**: Mandatory workflow that AI agents MUST execute after EVERY implementation.
+
+## Workflow Overview
+
+After completing ANY feature, bug fix, or code change, execute this workflow in order:
+
+### Step 1: Quality Checks (MANDATORY)
+
+Run these checks in order - ALL must pass:
+
+```bash
+1. Type check (if applicable)
+2. Lint (MUST pass with ZERO warnings)
+3. Format code
+4. Run ALL tests (MUST pass 100%)
+5. Verify coverage meets threshold (default 95%)
+```
+
+**Language-specific commands**: See your language template (TYPESCRIPT, RUST, PYTHON, etc.) for exact commands.
+
+**IF ANY CHECK FAILS:**
+- ❌ STOP immediately
+- ❌ DO NOT proceed
+- ❌ DO NOT commit
+- ✅ Fix the issue first
+- ✅ Re-run ALL checks
+
+### Step 2: Security & Dependency Audits
+
+```bash
+# Check for vulnerabilities (language-specific)
+# Check for outdated dependencies (informational)
+# Find unused dependencies (optional)
+```
+
+**Language-specific commands**: See your language template for audit commands.
+
+**IF VULNERABILITIES FOUND:**
+- ✅ Attempt automatic fix
+- ✅ Document if auto-fix fails
+- ✅ Include in Step 5 report
+- ❌ Never ignore critical/high vulnerabilities without user approval
+
+### Step 3: Update OpenSpec Tasks
+
+If `openspec/` directory exists:
+
+```bash
+# Mark completed tasks as [DONE]
+# Update in-progress tasks
+# Add new tasks if discovered
+# Update progress percentages
+# Document deviations or blockers
+```
+
+### Step 4: Update Documentation
+
+```bash
+# Update ROADMAP.md (if feature is milestone)
+# Update CHANGELOG.md (conventional commits format)
+# Update feature specs (if implementation differs)
+# Update README.md (if public API changed)
+```
+
+### Step 5: Git Commit
+
+**ONLY after ALL above steps pass:**
+
+**⚠️ CRITICAL: All commit messages MUST be in English**
+
+```bash
+git add .
+git commit -m "<type>(<scope>): <description>
+
+- Detailed change 1
+- Detailed change 2
+- Tests: [describe coverage]
+- Coverage: X% (threshold: 95%)
+
+Closes #<issue> (if applicable)"
+```
+
+**Commit Types**: `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`
+
+**Language Requirement**: Commit messages must be written in English. Never use Portuguese, Spanish, or any other language.
+
+### Step 6: Report to User
+
+```
+✅ Implementation Complete
+
+📝 Changes:
+- [List main changes]
+
+🧪 Quality Checks:
+- ✅ Type check: Passed
+- ✅ Linting: Passed (0 warnings)
+- ✅ Formatting: Applied
+- ✅ Tests: X/X passed (100%)
+- ✅ Coverage: X% (threshold: 95%)
+
+🔒 Security:
+- ✅ No vulnerabilities
+
+📊 OpenSpec:
+- ✅ Tasks updated
+- ✅ Progress: X% → Y%
+
+📚 Documentation:
+- ✅ CHANGELOG.md updated
+- ✅ [other docs updated]
+
+💾 Git:
+- ✅ Committed: <commit message>
+- ✅ Hash: <commit hash>
+
+📋 Next Steps:
+- [ ] Review changes
+- [ ] Push to remote (if ready)
+```
+
+## Automation Exceptions
+
+Skip steps ONLY when:
+
+1. **Exploratory Code**: User says "experimental", "draft", "try"
+   - Still run quality checks
+   - Don't commit
+
+2. **User Explicitly Requests**: User says "skip tests", "no commit"
+   - Only skip requested step
+   - Warn about skipped steps
+
+3. **Emergency Hotfix**: Critical production bug
+   - Run minimal checks
+   - Document technical debt
+
+**In ALL other cases: Execute complete workflow**
+
+## Error Recovery
+
+If workflow fails 3+ times:
+
+```bash
+1. Create backup branch
+2. Reset to last stable commit
+3. Report to user with error details
+4. Request guidance or try alternative approach
+```
+
+## Best Practices
+
+### DO's ✅
+- ALWAYS run complete workflow
+- ALWAYS update OpenSpec and documentation
+- ALWAYS use conventional commits
+- ALWAYS report summary to user
+- ASK before skipping steps
+
+### DON'Ts ❌
+- NEVER skip quality checks without permission
+- NEVER commit failing tests
+- NEVER commit linting errors
+- NEVER skip documentation updates
+- NEVER assume user wants to skip automation
+- NEVER commit debug code or secrets
+
+## Summary
+
+**Complete workflow after EVERY implementation:**
+
+1. ✅ Quality checks (type, lint, format, test, coverage)
+2. ✅ Security audit
+3. ✅ Update OpenSpec tasks
+4. ✅ Update documentation
+5. ✅ Git commit (conventional format)
+6. ✅ Report summary to user
+
+**Only skip with explicit user permission and document why.**
+
+<!-- AGENT_AUTOMATION:END -->

package/templates/core/DAG.md

@@ -0,0 +1,304 @@
+<!-- DAG:START -->
+# Dependency Architecture Guidelines (DAG)
+
+**CRITICAL**: Maintain a clean dependency graph (DAG) to prevent circular dependencies and ensure maintainable architecture.
+
+## Core Principles
+
+### No Circular Dependencies
+- **NEVER** create circular dependencies between components
+- **ALWAYS** ensure dependencies form a Directed Acyclic Graph (DAG)
+- **ALWAYS** validate dependency structure before committing
+
+### Layer Separation
+- **ALWAYS** maintain clear layer boundaries
+- **ALWAYS** ensure higher layers depend only on lower layers
+- **NEVER** allow lower layers to depend on higher layers
+
+### Interface Boundaries
+- **ALWAYS** use interfaces for cross-component communication
+- **ALWAYS** define clear contracts between components
+- **NEVER** create tight coupling between components
+
+## Dependency Rules
+
+### Layer Architecture
+
+**Layer 1: Foundation**
+- Utils, helpers, utilities
+- Type definitions
+- Configuration management
+- Base constants and enums
+
+**Layer 2: Core**
+- Core business logic
+- Data models and schemas
+- Base services and repositories
+- Domain entities
+
+**Layer 3: Features**
+- Feature implementations
+- Business logic
+- API endpoints
+- Service orchestration
+
+**Layer 4: Presentation**
+- UI components
+- CLI interfaces
+- API controllers
+- View models
+
+### Dependency Flow
+
+```
+Foundation → Core → Features → Presentation
+```
+
+**Rules:**
+- ✅ Foundation can depend on nothing (or external libraries only)
+- ✅ Core can depend on Foundation
+- ✅ Features can depend on Core and Foundation
+- ✅ Presentation can depend on Features, Core, and Foundation
+- ❌ Foundation CANNOT depend on Core, Features, or Presentation
+- ❌ Core CANNOT depend on Features or Presentation
+- ❌ Features CANNOT depend on Presentation
+
+## Component Graph Structure
+
+### Example Valid DAG
+
+```
+Core
+  ├── Utils
+  ├── Types
+  └── Config
+
+Features
+  ├── Feature A
+  │   └── Core
+  └── Feature B
+      ├── Core
+      └── Feature A
+
+Presentation
+  ├── CLI
+  │   └── Features
+  └── API
+      └── Features
+```
+
+### Invalid Patterns (Circular Dependencies)
+
+```
+❌ Feature A → Feature B → Feature A
+❌ Core → Feature → Core
+❌ Utils → Core → Utils
+```
+
+## Verification
+
+### Before Committing
+
+**MANDATORY**: Verify dependency structure:
+
+```bash
+# Check for circular dependencies
+# Add your dependency check command here
+# Examples:
+# - TypeScript: tsc --noEmit (catches import cycles)
+# - Rust: cargo check (catches circular dependencies)
+# - Python: pylint --disable=all --enable=import-error
+# - Go: go vet ./...
+```
+
+### Dependency Analysis Tools
+
+**TypeScript/JavaScript:**
+```bash
+# Use madge to detect circular dependencies
+npx madge --circular src/
+
+# Use dependency-cruiser
+npx dependency-cruiser --validate src/
+```
+
+**Rust:**
+```bash
+# Cargo automatically detects circular dependencies
+cargo check
+```
+
+**Python:**
+```bash
+# Use vulture or pylint
+pylint --disable=all --enable=import-error src/
+```
+
+**Go:**
+```bash
+# Use go vet
+go vet ./...
+```
+
+## Best Practices
+
+### DO's ✅
+
+- **ALWAYS** maintain clear layer boundaries
+- **ALWAYS** validate dependencies before committing
+- **ALWAYS** use interfaces for cross-layer communication
+- **ALWAYS** document component dependencies
+- **ALWAYS** refactor when circular dependencies are detected
+- **ALWAYS** keep dependency graph shallow (avoid deep nesting)
+
+### DON'Ts ❌
+
+- **NEVER** create circular dependencies
+- **NEVER** allow lower layers to depend on higher layers
+- **NEVER** create tight coupling between components
+- **NEVER** skip dependency validation
+- **NEVER** mix concerns across layers
+- **NEVER** create bidirectional dependencies
+
+## Dependency Documentation
+
+### Documenting Dependencies
+
+**In code:**
+```typescript
+// Component: UserService
+// Dependencies:
+//   - UserRepository (Core layer)
+//   - Logger (Foundation layer)
+//   - Config (Foundation layer)
+// Does NOT depend on:
+//   - UserController (Presentation layer)
+//   - UserAPI (Presentation layer)
+```
+
+**In documentation:**
+- Maintain `docs/DAG.md` with component dependency graph
+- Update when adding new components
+- Include dependency direction and purpose
+
+## Refactoring Circular Dependencies
+
+### When Circular Dependency is Detected
+
+1. **Identify the cycle**: Map the dependency chain
+2. **Find common dependency**: Extract shared functionality
+3. **Introduce interface**: Use dependency inversion
+4. **Restructure layers**: Move components to appropriate layer
+5. **Validate fix**: Run dependency check again
+
+### Example Refactoring
+
+**Before (Circular):**
+```
+Feature A → Feature B → Feature A
+```
+
+**After (Fixed):**
+```
+Core
+  └── SharedService
+
+Feature A → Core
+Feature B → Core
+```
+
+## Integration with AGENT_AUTOMATION
+
+**CRITICAL**: Include dependency validation in AGENT_AUTOMATION workflow:
+
+```bash
+# Step 1.5: Dependency Validation (before implementation)
+# Check for circular dependencies
+npm run check-deps  # or equivalent for your language
+
+# If circular dependencies detected:
+# ❌ STOP - Fix architecture first
+# ✅ Refactor to remove cycles
+# ✅ Re-validate before proceeding
+```
+
+## Language-Specific Guidelines
+
+### TypeScript/JavaScript
+- Use `madge` or `dependency-cruiser` for validation
+- Configure ESLint rules for import ordering
+- Use path aliases to enforce layer structure
+
+### Rust
+- Cargo automatically detects circular dependencies
+- Use `cargo tree` to visualize dependencies
+- Organize modules to reflect layer structure
+
+### Python
+- Use `pylint` or `vulture` for import analysis
+- Organize packages to reflect layer structure
+- Use `__init__.py` to control exports
+
+### Go
+- Use `go vet` for dependency validation
+- Organize packages in directories reflecting layers
+- Use interfaces to decouple components
+
+## Examples
+
+### Good Architecture ✅
+
+```
+src/
+├── foundation/
+│   ├── utils/
+│   ├── types/
+│   └── config/
+├── core/
+│   ├── models/
+│   ├── services/
+│   └── repositories/
+├── features/
+│   ├── auth/
+│   │   └── (depends on core, foundation)
+│   └── payments/
+│       └── (depends on core, foundation)
+└── presentation/
+    ├── cli/
+    │   └── (depends on features, core, foundation)
+    └── api/
+        └── (depends on features, core, foundation)
+```
+
+### Bad Architecture ❌
+
+```
+src/
+├── features/
+│   └── auth/
+│       └── (depends on presentation)  # ❌ Wrong direction
+├── core/
+│   └── (depends on features)  # ❌ Wrong direction
+└── presentation/
+    └── (depends on foundation only)  # ❌ Missing dependencies
+```
+
+## Maintenance
+
+### Regular Checks
+
+- **Before every commit**: Run dependency validation
+- **Weekly**: Review dependency graph for optimization
+- **Before major refactoring**: Document current dependencies
+- **After adding new components**: Update DAG documentation
+
+### Tools Integration
+
+Add dependency checks to:
+- Pre-commit hooks
+- CI/CD pipelines
+- AGENT_AUTOMATION workflow
+- Quality gates
+
+<!-- DAG:END -->
+

package/templates/core/DOCUMENTATION_RULES.md

@@ -0,0 +1,37 @@
+# Documentation Standards
+
+**CRITICAL**: All documentation in English. Root README concise, detailed docs in `/docs`.
+
+## Structure
+
+**Root-Level (ONLY):**
+- `README.md` - Overview + quick start
+- `CHANGELOG.md` - Version history
+- `AGENTS.md` - AI instructions
+- `LICENSE`, `CONTRIBUTING.md`, `SECURITY.md`
+
+**All Other Docs in `/docs`:**
+- `ARCHITECTURE.md`, `DEVELOPMENT.md`, `ROADMAP.md`
+- `specs/`, `guides/`, `diagrams/`, `benchmarks/`
+
+## Update Requirements by Commit Type
+
+| Type | Update |
+|------|--------|
+| `feat` | README features, API docs, CHANGELOG "Added" |
+| `fix` | Troubleshooting, CHANGELOG "Fixed" |
+| `breaking` | CHANGELOG + migration guide, version docs |
+| `perf` | Benchmarks, CHANGELOG "Performance" |
+| `security` | SECURITY.md, CHANGELOG "Security" |
+| `docs` | Verify spelling/links only |
+| `refactor` | Update if behavior changed |
+
+## Quality Checks (CI/CD)
+
+```bash
+markdownlint **/*.md         # Lint markdown
+markdown-link-check **/*.md  # Check links
+codespell **/*.md            # Spell check
+```
+
+**MUST pass before commit** (see AGENT_AUTOMATION).