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/:

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:

````markdown

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):**

```[language]
// 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/<category>-best-practices/rules/<slug>.md

## Step 6 — Update SKILL.md Quick Reference

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

skills/<category>-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 ``