@hivehub/rulebook 5.2.1 → 5.3.0

package/.claude/commands/analysis.md

@@ -0,0 +1,35 @@
+# /analysis — Structured analysis workflow
+
+Create a structured analysis for a topic. Scaffolds `docs/analysis/<slug>/` with skeleton files (README.md, findings.md, execution-plan.md, manifest.json).
+
+## Usage
+
+```
+/analysis <topic>
+```
+
+## What it does
+
+1. Slugifies the topic (e.g. "Auth Refactor v2" → `auth-refactor-v2`)
+2. Creates `docs/analysis/<slug>/` with:
+   - **README.md** — executive summary, methodology, conclusion
+   - **findings.md** — numbered findings F-001..F-NNN (title, evidence, impact, confidence)
+   - **execution-plan.md** — phased implementation plan
+   - **manifest.json** — metadata (agents, timestamps, version)
+3. Idempotent: re-running updates manifest but preserves user-edited content files
+
+## After scaffolding
+
+1. Fill `findings.md` with investigation results
+2. Design the phases in `execution-plan.md`
+3. Create implementation tasks from the plan: `rulebook task create phase1_<slug>-<name>`
+4. Each task should reference the analysis: `Source: docs/analysis/<slug>/README.md#F-NNN`
+5. Before implementing, consult the knowledge base: `rulebook_knowledge_list` filtered by `analysis:<slug>`
+
+## MCP equivalent
+
+```
+rulebook_analysis_create({ topic: "<topic>" })
+rulebook_analysis_list()
+rulebook_analysis_show({ slug: "<slug>" })
+```

package/.claude/commands/rulebook-task-apply.md

@@ -14,35 +14,24 @@ description: Implement an approved Rulebook task and keep tasks checklist in syn
 **Steps**
 Track these steps as TODOs and complete them one by one.
 
-1. **Check Knowledge Base FIRST (MANDATORY)**:
-   Before writing any code, search for relevant patterns and anti-patterns:
-   ```bash
-   rulebook knowledge list
-   ```
-   Also search learnings related to this area:
-   ```bash
-   rulebook learn list
-   ```
-   Apply any relevant patterns. Avoid any documented anti-patterns.
-
-2. **Read Task Details**:
+1. **Read Task Details**:
    ```bash
    rulebook task show <task-id>
    ```
    Read `proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
 
-3. **Follow Priority Order (MANDATORY)**:
+2. **Follow Priority Order (MANDATORY)**:
    - **Tests** (HIGHEST PRIORITY) - Write tests first
    - **Coverage Verification** (CRITICAL) - Verify coverage ≥95%
    - **Update Task Status** (MANDATORY) - Mark completed items as `[x]` in `tasks.md`
    - **Next Task** (Only after above steps)
 
-4. **Work Through Tasks Sequentially**:
+3. **Work Through Tasks Sequentially**:
    - Work through `tasks.md` checklist item by item
    - Keep edits minimal and focused on the requested change
    - Follow priority order (most critical first)
 
-5. **After Each Implementation Step**:
+4. **After Each Implementation Step**:
    - ✅ Implement the feature
    - ✅ Test the implementation
    - ✅ Verify test coverage (run `npm test -- --coverage`)
@@ -50,7 +39,7 @@ Track these steps as TODOs and complete them one by one.
    - ✅ Commit locally (backup)
    - ✅ Only then proceed to next task
 
-6. **Update Tasks Checklist**:
+5. **Update Tasks Checklist**:
    After completing and testing each item:
    ```markdown
    ## 1. Implementation Phase
@@ -59,24 +48,17 @@ Track these steps as TODOs and complete them one by one.
    - [ ] 1.3 Add archive functionality <!-- next: will start after status update -->
    ```
 
-7. **Confirm Completion**:
+6. **Confirm Completion**:
    - Make sure every item in `tasks.md` is finished
    - All tests pass
    - Coverage meets thresholds
    - Documentation updated
 
-8. **Update Checklist After All Work**:
+7. **Update Checklist After All Work**:
    - Mark each completed task as `[x]`
    - Add comments with test status and coverage
    - Reflect reality in the checklist
 
-9. **Capture Learnings (MANDATORY)**:
-   After completing the task, record what you learned:
-   - **Patterns that worked** → `rulebook knowledge add pattern "<title>" --category <cat>`
-   - **Anti-patterns discovered** → `rulebook knowledge add anti-pattern "<title>" --category <cat>`
-   - **Debugging insights** → `rulebook learn capture --title "<title>" --content "<what you learned>"`
-   - If nothing significant was learned, record at minimum: `rulebook learn capture --title "Completed <task-id>" --content "Implemented <summary>. No unexpected issues."`
-
 **Reference**
 - Use `rulebook task show <task-id>` when additional context is required
 - Use `rulebook task validate <task-id>` to check format before archiving

package/.claude/commands/rulebook-task-archive.md

@@ -11,22 +11,13 @@ description: Archive a completed Rulebook task and apply spec deltas to main spe
 - Refer to `/.rulebook/specs/RULEBOOK.md` for complete task management guidelines.
 
 **Steps**
-1. **Capture Learnings BEFORE Archiving (MANDATORY)**:
-   Before archiving, record what was learned during this task:
-   - **Patterns discovered** → `rulebook knowledge add pattern "<title>" --category <cat> --description "<desc>"`
-   - **Anti-patterns found** → `rulebook knowledge add anti-pattern "<title>" --category <cat> --description "<desc>"`
-   - **Implementation learnings** → `rulebook learn capture --title "<title>" --content "<what you learned>"`
-   - **Architectural decisions** → record via `rulebook decision create` if a significant design choice was made
-
-   Minimum: at least ONE learning must be captured per task archive. If the task was trivial, record: `rulebook learn capture --title "Completed <task-id>" --content "<1-line summary of what was done>"`
-
-2. **Verify Task Completion**:
+1. **Verify Task Completion**:
    - All items in `tasks.md` must be marked as `[x]`
    - All tests must pass
    - Code review complete (if applicable)
    - Documentation updated (README, CHANGELOG, specs)
 
-3. **Run Quality Checks**:
+2. **Run Quality Checks**:
    ```bash
    npm test
    npm run lint
@@ -35,13 +26,13 @@ description: Archive a completed Rulebook task and apply spec deltas to main spe
    ```
    Ensure all checks pass before archiving.
 
-4. **Validate Task Format**:
+3. **Validate Task Format**:
    ```bash
    rulebook task validate <task-id>
    ```
    Must pass all format checks.
 
-5. **Archive Task**:
+4. **Archive Task**:
    ```bash
    rulebook task archive <task-id>
    ```
@@ -51,27 +42,27 @@ description: Archive a completed Rulebook task and apply spec deltas to main spe
    ```
    (Only use `--skip-validation` if you're certain the task is valid)
 
-6. **Archive Process**:
+5. **Archive Process**:
    - Validates task format (unless skipped)
    - Checks task completion status
    - Applies spec deltas to main specifications
-   - Moves task to `/.rulebook/archive/YYYY-MM-DD-<task-id>/`
+   - Moves task to `/.rulebook/tasks/archive/YYYY-MM-DD-<task-id>/`
    - Updates related specifications
 
-7. **Verify Archive**:
+6. **Verify Archive**:
    ```bash
    rulebook task list --archived
    ```
    Task should appear in archived list.
 
-8. **Post-Archive Actions**:
+7. **Post-Archive Actions**:
    - Ensure spec deltas are applied to main specifications
    - Update CHANGELOG.md with the change
    - Document any breaking changes
    - Create migration guides (if needed)
    - Unblock related tasks (if any)
 
-9. **🚨 MANDATORY: Deferred Items → Tasks Rule**:
+8. **🚨 MANDATORY: Deferred Items → Tasks Rule**:
    **ABSOLUTE RULE — NO EXCEPTIONS**: Whenever a task is archived with items marked as "Deferred" or "Phase X+", you MUST immediately create Rulebook tasks for those deferred items **before archiving**.
 
    ```
@@ -81,7 +72,7 @@ description: Archive a completed Rulebook task and apply spec deltas to main spe
 
    ✅ CORRECT — defer with tracking:
    1. Add "- [ ] D1. feature X — deferred Phase 4" to tasks.md
-   2. Call rulebook_task_create("phase4_feature-x")
+   2. Call rulebook_task_create("phase4-feature-x")
    3. Write tasks.md for the new task with full context
    4. THEN call rulebook_task_archive
    ```

package/.claude/commands/rulebook-task-create.md

@@ -24,7 +24,7 @@ description: Create a new Rulebook task following OpenSpec-compatible format wit
    - Review related code or docs (e.g., via `rg`/`ls`) to understand current behavior
    - Note any gaps that require clarification
 
-3. **Choose Task ID**: MUST use phase prefix: `phase<N>[subletter]_<description>` in kebab-case (e.g., `phase1_add-feature`, `phase2a_fix-login`). Must be unique. Tasks must be sized to fit a single implementation cycle — if a task is too large, split it into multiple smaller tasks within the same phase or across phases.
+3. **Choose Task ID**: Use verb-led kebab-case (e.g., `add-feature`, `update-api`, `refactor-module`). Must be unique.
 
 4. **Create Task Structure**:
    ```bash