Skip to main content

17. Structured Rule Data Definition

Status: Accepted Date: 2025-07-06

Context​

The kaido-cli tool manages different types of "rules" (e.g., Cursor agent rules, methodology rules, FDD validation rules). For the tool to manage these effectively and for developers to contribute new rules easily, the data structure for a rule must be consistent and predictable. Without a standardized structure, each rule might have a different shape, leading to complex, brittle, and error-prone code to handle all the variations.

Decision​

All rule definitions within the system will be implemented as TypeScript objects adhering to a common, strictly-typed Rule interface. This interface will define a consistent set of properties for every rule.

The base Rule interface will include:

  • id: A unique string identifier for the rule (e.g., kaseki-protocol).
  • title: A human-readable string title.
  • description: A short string explanation of the rule's purpose.
  • MANTRA: An optional string containing a memorable phrase that summarizes the rule's core principle.
  • content: A string containing the actual body of the rule or its implementation details.
  • category: A string literal type for classification (e.g., 'methodology' | 'fdd' | 'agent').

Using TypeScript interfaces and types ensures that all rule objects are structurally consistent, and the TypeScript compiler will enforce this consistency at build time.

Consequences​

Positive:

  • Consistency & Predictability: All rules have the same base shape, making the code that processes them simpler, more robust, and easier to reason about.
  • Type Safety: The TypeScript compiler prevents structural errors in rule definitions, catching many potential bugs before runtime.
  • Developer Experience: Developers have a clear, typed template to follow when creating new rules, improving productivity and reducing errors.
  • Tooling & Automation: It is significantly easier to build tools that can list, validate, display, or otherwise manipulate rules when they all share a common, predictable structure.

Negative:

  • Rigidity: A single, strict structure might not perfectly fit every possible type of rule. Some rules might need unique fields that others don't.
  • Initial Overhead: Defining the initial set of interfaces and types requires upfront design effort.

Mitigation:

  • Flexible Typing: The base Rule interface can be extended for more specific rule types. We can use interface inheritance or composition to add specific fields while maintaining the core structure. Optional properties (?) can also be used for non-essential fields.
  • Clear Documentation: The Rule interface and any related types must be well-documented using TSDoc to explain the purpose and usage of each property.