Docs: Finalize manage_rules spec documentation

memory/docs/features/manage_rules/historical_task_plan.md

@@ -0,0 +1,77 @@
+# Refactoring Task Plan (As Executed)
+
+## 🎯 Goal
+
+This document breaks down the work performed during the internal refactoring of the `rulebook-ai` core and CLI components. The objective was to improve code modularity, maintainability, and extensibility by separating declarative assistant specifications from the file-generation engine.
+
+This plan is a historical record of the tasks completed, based on the final design in the [Refactoring Plan](./refactoring_plan.md).
+
+---
+
+### Phase 1: Separate Specification from Logic
+
+**Description:** This phase focused on creating a purely data-driven architecture, separating the "what" (the assistant spec) from the "how" (the generation engine).
+
+| Task ID | Description                                                                              | Importance | Status      | Dependencies      |
+|:--------|:-----------------------------------------------------------------------------------------|:-----------|:------------|:------------------|
+| **1.1** | Define the `AssistantSpec` dataclass in a new `assistants.py` file.                      | P0         | Completed   | -                 |
+| **1.2** | Create the `SUPPORTED_ASSISTANTS` list in `assistants.py` as the single source of truth. | P0         | Completed   | 1.1               |
+| **1.3** | Refactor `RuleManager` in `core.py` into a generic engine that interprets `AssistantSpec` data. | P0         | Completed   | 1.2               |
+| **1.4** | Implement private generation strategies (`_strategy_flatten_and_number`, etc.) in `RuleManager`. | P0         | Completed   | 1.3               |
+| **1.5** | Refactor public methods (`install`, `sync`, `clean_rules`) to be data-driven and compliant with the design spec. | P0         | Completed   | 1.4               |
+
+### Phase 2: Simplify and Automate the CLI
+
+**Description:** This phase refactored the command-line interface to be dynamically generated from the single source of truth, eliminating hardcoded logic.
+
+| Task ID | Description                                                                              | Importance | Status      | Dependencies      |
+|:--------|:-----------------------------------------------------------------------------------------|:-----------|:------------|:------------------|
+| **2.1** | Refactor `cli.py` to dynamically generate assistant flags (e.g., `--cursor`) from `SUPPORTED_ASSISTANTS`. | P1         | Completed   | 1.2               |
+| **2.2** | Simplify `handle_install` and `handle_sync` to pass the list of selected assistants to `RuleManager`. | P1         | Completed   | 1.4, 2.1          |
+
+### Phase 3: Verification and Documentation
+
+**Description:** This final phase ensured that the refactoring was correct, robust, and fully documented.
+
+| Task ID | Description                                                                              | Importance | Status      | Dependencies      |
+|:--------|:-----------------------------------------------------------------------------------------|:-----------|:------------|:------------------|
+| **3.1** | Manually test CLI commands to confirm compliance and identify bugs in the new logic.       | P0         | Completed   | 1.5, 2.2          |
+| **3.2** | Run the full automated test suite (`pytest`) to identify all regressions.                  | P0         | Completed   | 3.1               |
+| **3.3** | Fix all failing integration tests in `test_cli_commands.py` and other files to align with the new CLI behavior. | P0         | Completed   | 3.2               |
+| **3.4** | Rewrite the unit tests in `test_rule_manager_unit.py` to validate the new core generation strategies. | P0         | Completed   | 3.3               |
+| **3.5** | Update the public design spec (`manage_rules_script_design.md`) to include the new assistant-selection features. | P1         | Completed   | 3.4               |
+
+### Enhancement: Additional Assistant Support
+
+**Description:** Post-refactor improvements that expand assistant coverage and strengthen file cleanup.
+
+| Task ID | Description | Importance | Status | Dependencies |
+|:--------|:------------|:-----------|:-------|:-------------|
+| **E1** | Define Claude Code, Codex CLI, and Gemini CLI assistants with dedicated rule file paths. | P1 | Completed | 3.5 |
+| **E2** | Handle cleanup of assistant files and empty parent directories generically. | P1 | Completed | E1 |
+| **E3** | Extend CLI and integration tests for new assistant flags. | P1 | Completed | E1 |
+| **E4** | Document new assistant support in design spec, CLI flows, README, and task plan. | P1 | Completed | E3 |
+| **E5** | Add `bug-report` CLI command linking to the issue tracker. | P3 | Completed | - |
+
+### Enhancement: Kilo Code and Warp Support
+
+**Description:** Added support for the Kilo Code and Warp assistants, which required refactoring the generation logic to handle mode-based subdirectories.
+
+| Task ID | Description | Importance | Status | Dependencies |
+|:--------|:------------|:-----------|:-------|:-------------|
+| **E6** | Add `kilocode` and `warp` to `assistants.py` and introduce the `has_modes` flag to `AssistantSpec`. | P1 | Completed | E4 |
+| **E7** | Refactor `RuleManager._generate_for_assistant` to use the `has_modes` flag for mode-based generation. | P1 | Completed | E6 |
+| **E8** | Update unit and integration tests to verify the new mode-based logic and assistant support. | P1 | Completed | E7 |
+| **E9** | Enhance integration tests to check for multiple sub-modes and files within them. | P2 | Completed | E8 |
+| **E10** | Update design documents to reflect Kilo Code and Warp support. | P2 | Completed | E7 |
+
+### Enhancement: Ratings & Reviews Command
+
+**Description:** Introduced a utility command that directs users to the project's Ratings & Reviews wiki for rule sets.
+
+| Task ID | Description | Importance | Status | Dependencies |
+|:--------|:------------|:-----------|:-------|:-------------|
+| **E11** | Add `rate-ruleset` CLI command linking to the ratings wiki. | P3 | Completed | - |
+| **E12** | Update design docs and tests for ratings command. | P3 | Completed | E11 |
+| **E13** | Surface ratings wiki link in `list-rules` output. | P3 | Completed | E11 |
+| **E14** | Update docs and tests for ratings link in `list-rules`. | P3 | Completed | E13 |

memory/docs/features/manage_rules/implementation_design.md

@@ -0,0 +1,24 @@
+# Implementation Design: Rulebook-AI CLI
+
+## 1. High-Level Goal & Architecture
+
+The `rulebook-ai` CLI is designed to be maintainable and extensible. The core implementation follows a clean **separation of concerns**, splitting the logic into two distinct parts:
+
+1.  **A declarative configuration (`assistants.py`)**: This file defines the *specification* for each AI assistant—what they expect to find on the filesystem—using a pure, data-only `AssistantSpec` class. It is the single source of truth for all assistant-specific information.
+2.  **A generic engine (`core.py`)**: The `RuleManager` class acts as a generic engine that reads the assistant specifications and performs the necessary file operations (copying, cleaning, generating rules). It contains all the logic for *how* to generate rules based on the specifications.
+
+This architecture makes adding a new assistant a simple matter of adding a new entry to the configuration file, without touching the core engine logic.
+
+## 2. Code Structure
+
+-   **`src/rulebook_ai/cli.py`**: Handles command-line argument parsing using Python's `argparse` library. It dynamically generates CLI flags (e.g., `--cursor`, `--cline`) from the `SUPPORTED_ASSISTANTS` list in `assistants.py`. It then calls the appropriate methods in the `RuleManager`.
+-   **`src/rulebook_ai/core.py`**: Contains the `RuleManager` class, which implements the main business logic for the `install`, `sync`, `clean-rules`, and `clean-all` commands.
+-   **`src/rulebook_ai/assistants.py`**: Contains the `AssistantSpec` dataclass and the `SUPPORTED_ASSISTANTS` list, which provides the specifications for all supported AI assistants.
+
+## 3. Core Implementation Notes
+
+-   **Path Handling:** The implementation must use robust path handling to manage files and directories across different operating systems.
+-   **User Feedback:** The CLI should provide clear and concise feedback to the user for all operations.
+-   **Hardcoded Constants:** Directory names for the framework components (e.g., `rule_sets` in the source repo, `project_rules`, `memory`, `tools` in the target repo) are hardcoded as constants within the script for simplicity and reliability.
+-   **Parent Directory Creation:** Helper functions that write files (e.g., for `copilot-instructions.md` or `GEMINI.md`) must ensure that the parent directories (`.github/`, `.gemini/`) are created if they do not exist.
+-   **Extensibility for Assistants:** The `AssistantSpec` is designed to be extensible. For example, the `has_modes` flag was added to support assistants like Kilo Code and Roo Code, which use subdirectories for different modes. The `RuleManager`'s generation logic was extended to interpret this flag.