Skip to content

Commit 428c151

Browse files
botingwbotingw
authored
Merge pull request #41 from botingw/docs/finalize-manage-rules-spec
Docs: Finalize manage_rules spec documentation
2 parents 8dec010 + dcab154 commit 428c151

File tree

6 files changed

+175
-165
lines changed

6 files changed

+175
-165
lines changed

memory/docs/features/manage_rules/refactoring_plan.md renamed to memory/docs/features/manage_rules/archive_refactoring_plan.md

File renamed without changes.

‎memory/docs/features/manage_rules/historical_task_plan.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Refactoring Task Plan (As Executed)
2+
3+
## 🎯 Goal
4+
5+
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.
6+
7+
This plan is a historical record of the tasks completed, based on the final design in the [Refactoring Plan](./refactoring_plan.md).
8+
9+
---
10+
11+
### Phase 1: Separate Specification from Logic
12+
13+
**Description:** This phase focused on creating a purely data-driven architecture, separating the "what" (the assistant spec) from the "how" (the generation engine).
14+
15+
| Task ID | Description | Importance | Status | Dependencies |
16+
|:--------|:-----------------------------------------------------------------------------------------|:-----------|:------------|:------------------|
17+
| **1.1** | Define the `AssistantSpec` dataclass in a new `assistants.py` file. | P0 | Completed | - |
18+
| **1.2** | Create the `SUPPORTED_ASSISTANTS` list in `assistants.py` as the single source of truth. | P0 | Completed | 1.1 |
19+
| **1.3** | Refactor `RuleManager` in `core.py` into a generic engine that interprets `AssistantSpec` data. | P0 | Completed | 1.2 |
20+
| **1.4** | Implement private generation strategies (`_strategy_flatten_and_number`, etc.) in `RuleManager`. | P0 | Completed | 1.3 |
21+
| **1.5** | Refactor public methods (`install`, `sync`, `clean_rules`) to be data-driven and compliant with the design spec. | P0 | Completed | 1.4 |
22+
23+
### Phase 2: Simplify and Automate the CLI
24+
25+
**Description:** This phase refactored the command-line interface to be dynamically generated from the single source of truth, eliminating hardcoded logic.
26+
27+
| Task ID | Description | Importance | Status | Dependencies |
28+
|:--------|:-----------------------------------------------------------------------------------------|:-----------|:------------|:------------------|
29+
| **2.1** | Refactor `cli.py` to dynamically generate assistant flags (e.g., `--cursor`) from `SUPPORTED_ASSISTANTS`. | P1 | Completed | 1.2 |
30+
| **2.2** | Simplify `handle_install` and `handle_sync` to pass the list of selected assistants to `RuleManager`. | P1 | Completed | 1.4, 2.1 |
31+
32+
### Phase 3: Verification and Documentation
33+
34+
**Description:** This final phase ensured that the refactoring was correct, robust, and fully documented.
35+
36+
| Task ID | Description | Importance | Status | Dependencies |
37+
|:--------|:-----------------------------------------------------------------------------------------|:-----------|:------------|:------------------|
38+
| **3.1** | Manually test CLI commands to confirm compliance and identify bugs in the new logic. | P0 | Completed | 1.5, 2.2 |
39+
| **3.2** | Run the full automated test suite (`pytest`) to identify all regressions. | P0 | Completed | 3.1 |
40+
| **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 |
41+
| **3.4** | Rewrite the unit tests in `test_rule_manager_unit.py` to validate the new core generation strategies. | P0 | Completed | 3.3 |
42+
| **3.5** | Update the public design spec (`manage_rules_script_design.md`) to include the new assistant-selection features. | P1 | Completed | 3.4 |
43+
44+
### Enhancement: Additional Assistant Support
45+
46+
**Description:** Post-refactor improvements that expand assistant coverage and strengthen file cleanup.
47+
48+
| Task ID | Description | Importance | Status | Dependencies |
49+
|:--------|:------------|:-----------|:-------|:-------------|
50+
| **E1** | Define Claude Code, Codex CLI, and Gemini CLI assistants with dedicated rule file paths. | P1 | Completed | 3.5 |
51+
| **E2** | Handle cleanup of assistant files and empty parent directories generically. | P1 | Completed | E1 |
52+
| **E3** | Extend CLI and integration tests for new assistant flags. | P1 | Completed | E1 |
53+
| **E4** | Document new assistant support in design spec, CLI flows, README, and task plan. | P1 | Completed | E3 |
54+
| **E5** | Add `bug-report` CLI command linking to the issue tracker. | P3 | Completed | - |
55+
56+
### Enhancement: Kilo Code and Warp Support
57+
58+
**Description:** Added support for the Kilo Code and Warp assistants, which required refactoring the generation logic to handle mode-based subdirectories.
59+
60+
| Task ID | Description | Importance | Status | Dependencies |
61+
|:--------|:------------|:-----------|:-------|:-------------|
62+
| **E6** | Add `kilocode` and `warp` to `assistants.py` and introduce the `has_modes` flag to `AssistantSpec`. | P1 | Completed | E4 |
63+
| **E7** | Refactor `RuleManager._generate_for_assistant` to use the `has_modes` flag for mode-based generation. | P1 | Completed | E6 |
64+
| **E8** | Update unit and integration tests to verify the new mode-based logic and assistant support. | P1 | Completed | E7 |
65+
| **E9** | Enhance integration tests to check for multiple sub-modes and files within them. | P2 | Completed | E8 |
66+
| **E10** | Update design documents to reflect Kilo Code and Warp support. | P2 | Completed | E7 |
67+
68+
### Enhancement: Ratings & Reviews Command
69+
70+
**Description:** Introduced a utility command that directs users to the project's Ratings & Reviews wiki for rule sets.
71+
72+
| Task ID | Description | Importance | Status | Dependencies |
73+
|:--------|:------------|:-----------|:-------|:-------------|
74+
| **E11** | Add `rate-ruleset` CLI command linking to the ratings wiki. | P3 | Completed | - |
75+
| **E12** | Update design docs and tests for ratings command. | P3 | Completed | E11 |
76+
| **E13** | Surface ratings wiki link in `list-rules` output. | P3 | Completed | E11 |
77+
| **E14** | Update docs and tests for ratings link in `list-rules`. | P3 | Completed | E13 |

‎memory/docs/features/manage_rules/implementation_design.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Implementation Design: Rulebook-AI CLI
2+
3+
## 1. High-Level Goal & Architecture
4+
5+
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:
6+
7+
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.
8+
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.
9+
10+
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.
11+
12+
## 2. Code Structure
13+
14+
- **`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`.
15+
- **`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.
16+
- **`src/rulebook_ai/assistants.py`**: Contains the `AssistantSpec` dataclass and the `SUPPORTED_ASSISTANTS` list, which provides the specifications for all supported AI assistants.
17+
18+
## 3. Core Implementation Notes
19+
20+
- **Path Handling:** The implementation must use robust path handling to manage files and directories across different operating systems.
21+
- **User Feedback:** The CLI should provide clear and concise feedback to the user for all operations.
22+
- **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.
23+
- **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.
24+
- **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.

0 commit comments

Comments
 (0)