Openkata Rule Conventions

OpenKata Rule Conventions

Project-specific additions to the create-rule workflow. This skill activates alongside the generic create-rule and adds OpenKata conventions.

Additional Steps

After the generic create-rule skill workflow, also do:

1. Determine placement — Ask whether this rule is:

   • Local → .agents/rules/<name>/
   • Distributable → rules/<name>/

2. Create CHANGELOG.md — Every rule gets a changelog starting at v1.0.0 with an initial ### Added entry. Follow the markdown-style rule for formatting.

   # Changelog
   
   ## [1.0.0] - YYYY-MM-DD
   
   ### Added
   
   - Initial release of `<rule-name>` rule.
   

3. Symlink if distributable — For rules in rules/, ask the user if they want it symlinked into .agents/rules/:

   ln -s ../../rules/<name> .agents/rules/<name>
   

4. Acknowledge sources — If the rule draws on external style guides or standards, create references/ACKNOWLEDGMENTS.md listing each source with a link, license, what was adapted, and the version it was adopted in.

5. Quality check (mandatory gate) — Do not commit until all checks pass:

   • Pass the rule design checklist from create-rule
   • Every convention is literally enforceable
   • RULE.md is under 100 lines

Naming

• Distributable rules: no prefix, pattern-based
  • <domain>-style — formatting/coding conventions
  • <domain>-naming — naming conventions
  • <domain>-system — system-level constraints
• Local rules: always openkata- prefixed

Conventions

• Rule names are lowercase-hyphenated: git-naming, markdown-style
• Always ask the user before running destructive commands
• Local rules go in .agents/rules/<name>/
• Distributable rules go in rules/<name>/ with a symlink in .agents/rules/
• Every rule gets a CHANGELOG.md
• Changelogs document rule-facing changes only
• Keep rules focused — one rule, one concern

Example Scenario

User: "Create a rule for SQL naming conventions."

1. create-rule produces rules/sql-naming/RULE.md
2. This skill activates: asks local or distributable?
3. Creates CHANGELOG.md, symlinks into .agents/rules/, adds ACKNOWLEDGMENTS.md referencing the SQL style guide

Boundaries

DOES:

• Add CHANGELOG.md, symlinks, and ACKNOWLEDGMENTS.md to rules
• Determine placement (local vs distributable)
• Enforce quality gate before commit

Does NOT:

• Create the rule itself (that's create-rule)
• Run tessl commands (rules don't use tessl)
• Publish or release rules