# Ruler Setup

This project uses [Ruler](https://github.com/intellectronica/ruler) to keep AI assistant instructions in one committed source of truth.

## Source Of Truth

```
.ruler/
├── AGENTS.md      # Repo-wide guidance + always-on rules (appended at the end)
├── skills/        # Shared source skills propagated by Ruler
└── ruler.toml     # Ruler agent configuration
```

Use `.ruler/AGENTS.md` for always-on repository context and rules (the rules live as sections at the
end of that file). Use `.ruler/skills/` for task-specific workflows that should be loaded only when
relevant.

Always-on rules currently in `.ruler/AGENTS.md`:

- `changeset-conventions`
- `code-quality`
- `generated-output-boundaries`
- `guidance-source-of-truth`
- `no-hydration-terminology`
- `security-and-supply-chain`
- `test-driven-development`

Current source skills:

- `qwik-core-development`
- `qwik-router-development`
- `qwik-optimizer-development`
- `qwik-e2e-verification`
- `qwik-docs-development`
- `qwik-guidance-maintenance`

The `qwik-` prefix is intentional. Ruler copies skills into assistant-native directories where they
can appear beside personal and plugin skills, so the prefix keeps these repo skills recognizable
outside the `.ruler/` tree.

Root `AGENTS.md` and `CLAUDE.md` are generated by Ruler but committed (so fresh clones and worktrees
have the always-on guidance immediately). The generated skill directories (`.claude/skills/`,
`.codex/skills/`) and the rest of `.claude/`/`.codex/`/`.cursor/` stay local and gitignored — run
`ruler apply` to materialize the skills. Never edit a generated file directly — update `.ruler/`,
run `ruler apply`, and commit the regenerated root files.

## AI Config Builder

Treat Ruler as the source layer and the selected assistant as the output layer.

When you are setting up or debugging an assistant-specific config:

1. Identify the target assistant and Ruler agent id.
2. Read this file and `.ruler/ruler.toml`.
3. Research the target assistant's current native instruction, rule, skill, config, and policy
   formats when the mapping is ambiguous.
4. Map `.ruler` files by semantic role, not by filename.
5. Run `ruler apply --agents <agent>`.
6. Verify that the generated files contain the expected source guidance and skills.

| Ruler source | Semantic role | Builder action |
| --- | --- | --- |
| `.ruler/AGENTS.md` | Repo-wide AI guidance + always-on rules | Generate into the target assistant's primary native guidance file. |
| `.ruler/skills/*/SKILL.md` | Task-triggered workflows | Copy to the target assistant's native skills directory when supported. |
| `.ruler/ruler.toml` and Ruler MCP config | Agent selection, output paths, MCP/config | Generate or merge native config only where Ruler and the target assistant support it. |

Different tools use words like "rules" for different things. A native rules file may mean
natural-language guidance, directory-scoped steering, MCP config, hooks, or command execution
policy. Check current docs or the installed Ruler adapter before creating or copying a tool-specific
file.

## Markdown Guidance Bundle

The AI-agnostic Markdown guidance bundle is `.ruler/AGENTS.md` (repo-wide context plus the always-on
rules appended at its end) together with this `.ruler/README.md`.

Ruler concatenates that bundle and writes it to each selected assistant's native AI guidance file.
Use source markers in the generated file to verify inclusion. Do not bypass Ruler by copying these
Markdown files into a tool-specific directory whose format has not been verified.

If you are an AI assistant building local config for a target tool, research that tool's current
native guidance, skill, config, and policy formats before adding any tool-specific output. Map
`.ruler` files by what they mean, not by filename: Markdown guidance belongs in the assistant's
native AI guidance surface, skills belong in native skills if supported, and command-permission
policy belongs only in a separately researched policy format. For Codex, Ruler includes all
`.ruler` Markdown guidance in generated `AGENTS.md`; `.codex/rules/*.rules` is command policy, not
Markdown guidance.

### Worked Example: Codex

Current Ruler and OpenAI Codex behavior maps this repo's sources as follows:

| Ruler source | Codex-native output | Verify after `ruler apply --agents codex` |
| --- | --- | --- |
| `.ruler/AGENTS.md` | Generated root `AGENTS.md` | `rg -n 'Source: .ruler/AGENTS.md' AGENTS.md` |
| `.ruler/skills/*/SKILL.md` | `.codex/skills/*/SKILL.md` | `find .codex/skills -name SKILL.md` |
| Ruler MCP config | `.codex/config.toml` when MCP config is generated | `test -f .codex/config.toml` when MCP/config is expected |

Codex `.rules` files are command execution policy files that use `prefix_rule(...)`. They are not a
target for `.ruler/AGENTS.md` prose guidance. If Codex command policy is needed, maintain it as a
separate local or team policy using OpenAI Codex's `.rules` format; do not treat it as Ruler
Markdown guidance.

Expected Codex check:

```bash
ruler apply --agents codex
rg -n 'Source: .ruler/AGENTS.md' AGENTS.md
find .codex/skills -name SKILL.md
```

## What Is Committed vs Regenerated

Only the root `AGENTS.md` and `CLAUDE.md` are **committed** generated outputs, so a fresh clone or
worktree has the always-on guidance immediately (`.ruler/ruler.toml` keeps `[gitignore] enabled = false`
so Ruler leaves those two files tracked). The generated skill copies (`.claude/skills/`,
`.codex/skills/`) are **gitignored** — regenerate them locally with `ruler apply`. This keeps skill
and note edits from appearing three times (source plus two copies) in every PR.

To change guidance, edit `.ruler/`, run `ruler apply`, and commit the regenerated root files
alongside your `.ruler/` change. Never hand-edit the generated files. A CI check
(`.github/workflows/ruler-check.yml`) re-runs `ruler apply` and fails if the committed root files
drift from `.ruler/`.

## Generate Local Assistant Files

Install Ruler if you do not already have it:

```bash
npm install -g @intellectronica/ruler
```

Or run it without installing (the form used by fresh worktrees and CI):

```bash
pnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp
```

Generate files for the default configured agents:

```bash
ruler apply
```

Generate files for a specific assistant:

```bash
ruler apply --agents claude
ruler apply --agents codex
```

Generate files for multiple assistants:

```bash
ruler apply --agents claude,codex
```

## Project And Personal Configuration

Use `.ruler/` for team-shared instructions and project conventions that should travel with the repo.

Use `~/.config/ruler/` for personal preferences, local workflow shortcuts, API keys, and personal MCP servers:

```bash
ruler init --global
```

If it helps everyone working in this repo, add it to `.ruler/`. If it only helps your local setup,
keep it in your global Ruler config.

## Updating Instructions

Edit `.ruler/AGENTS.md` for repository-wide guidance and always-on rules (the rules are sections at
the end of that file). Edit the relevant `.ruler/skills/<skill-name>/SKILL.md` file for
package-specific or workflow-specific guidance.

If a code task proves a skill or reference stale, update that guidance as part of the same task when
the scope allows it.

Then regenerate the local assistant files:

```bash
ruler apply --agents <your-tool>
```

Do not update generated files like `CLAUDE.md` or `AGENTS.md` by hand. They will be overwritten the
next time Ruler runs.

## Skills

Author shared skills under `.ruler/skills/` (the committed source). Ruler copies them into each
enabled agent's skill directory (`.claude/skills/` for Claude, `.codex/skills/` for Codex); those
copies are gitignored, so run `ruler apply` once per fresh clone or worktree to materialize them.
Never hand-edit the copies — edit `.ruler/skills/` and regenerate.

Keep each skill focused:

- Use frontmatter with `name` and a trigger-oriented `description`.
- Put the fast path in `SKILL.md`.
- Move long notes into `references/` only when progressive disclosure helps.
- Keep always-on policy in `.ruler/AGENTS.md`, not duplicated in every skill.
- Keep durable maintainer lessons current. Prefer updating the specific skill/reference that was
  wrong over adding broad prose here.
