Rule Creator

Creates a properly formatted rule file in the correct best-practices skill folder and registers it in the corresponding SKILL.md Quick Reference.

Rule destinations

Rules always go into one of these three locations under skills/:

Category	Rules folder	SKILL.md
Backend	`skills/backend-best-practices/rules/`	`skills/backend-best-practices/SKILL.md`
Frontend	`skills/frontend-best-practices/rules/`	`skills/frontend-best-practices/SKILL.md`
General	`skills/general-best-practices/rules/`	`skills/general-best-practices/SKILL.md`

Only write to the skills/ paths. Never touch .agents/skills/.

Step 1 — Determine the category

Ask the user which category applies:

"Is this rule backend-specific (PHP/Laravel/API), frontend-specific (Vue/TypeScript/CSS), or general (language-agnostic pattern)?"

If the description clearly implies a category (e.g., mentions Laravel, PHP, Eloquent → backend; Vue, Nuxt, TypeScript component → frontend), you can auto-detect and confirm with one sentence instead of asking.

Step 2 — Gather rule content

Ask the user:

"Can you describe the rule? A short sentence is fine — e.g. 'never use dd() in production PHP code'. If you have a code example showing the wrong and right way, share it. Otherwise I'll look for examples in the codebase."

Then:

If the user provides examples → use them directly
If the user doesn't provide examples → search the codebase for real usage (see Step 2a)
Always generate or confirm the incorrect and correct examples before writing the file

Step 2a — Finding examples in the codebase

Use Grep or Glob to locate relevant code. Common search targets:

/Users/francoisauclair/Code/adra-backends — backend (PHP/Laravel)
/Users/francoisauclair/Code/adra-frontends — frontend (Vue/TypeScript)

If you can't find examples automatically, ask:

"I couldn't find clear examples in the codebase. Can you point me to a file or PR where this pattern appears?"

Step 3 — Derive the rule metadata

From the description and examples, determine:

title — Short, clear title (e.g. "No Debug Statements in Production")
slug — kebab-case filename (e.g. no-debug-statements.md)
impact — LOW, MEDIUM, or HIGH
impactDescription — One phrase explaining the impact (e.g. "Prevents accidental data exposure")
tags — 2–5 relevant tags
Quick Reference line — \slug` - One-sentence summary of the rule`

When in doubt about impact level:

HIGH — security, data loss, broken functionality, production errors
MEDIUM — maintainability, consistency, avoidable bugs
LOW — style, minor performance, developer ergonomics

Step 4 — Write the rule file

Use this exact template:

---
title: Rule Title Here
impact: MEDIUM
impactDescription: Optional description of impact
tags: tag1, tag2
---

## Rule Title Here

**Impact: MEDIUM (optional impact description)**

Brief explanation of the rule and why it matters.

**Incorrect (description of what's wrong):**

```[language]
// bad example
```

Correct (description of what's right):

// good example

Reference: Link to docs or resource


- Use the actual language tag (`php`, `typescript`, `vue`, etc.)
- Keep the explanation concise — 2–4 sentences max
- If there's no external reference, omit the Reference line
- If the rule has multiple sub-patterns (e.g. "applies to commands, resources, and middleware"), add a `###` subsection per pattern rather than cramming everything into one block

## Step 5 — Write the rule file

Write the rule to:

skills/-best-practices/rules/.md


## Step 6 — Update SKILL.md Quick Reference

Add one line to the `## Quick Reference` section of:

skills/-best-practices/SKILL.md


Insert the new line in alphabetical order by slug within the Quick Reference list.

Insert the new line in alphabetical order by slug within the Quick Reference list.

## Step 7 — Confirm

Tell the user:

- The file(s) created
- The slug and category chosen
- The Quick Reference line added

Example:
> Created `no-debug-statements` in **backend** best practices.
> Quick Reference updated: `` `no-debug-statements` - Never use `dd()` or `dump()` in production code ``

rule-creator