| name | qwik-guidance-maintenance |
| description | Use when editing Qwik's .ruler guidance, adding or changing rules or skills, keeping AI guidance from going stale, updating assistant setup docs, or answering how Ruler should generate assistant-native guidance, skills, config, or policy for this repo. |
Qwik Guidance Maintenance
Use this skill for .ruler/**, README AI assistant setup, dedicated rules, generated
assistant-output boundaries, rule-vs-skill taxonomy work, and assistant-native config questions.
Also use it at the end of a code task when source inspection proves a loaded skill or reference is
stale.
Fast Path
- Follow the Guidance Source Of Truth rule (in
.ruler/AGENTS.md) for source layout, rule-vs-skill
taxonomy, generated assistant outputs, AI config builder behavior, skill naming, and stale-guidance policy.
- Follow the Generated Output Boundaries rule (in
.ruler/AGENTS.md) before editing, regenerating,
or relying on generated output.
- Edit committed source files in
.ruler/, not generated assistant outputs.
- Keep new durable policy in the narrowest source:
.ruler/AGENTS.md for repo-wide context and
always-on rules, and .ruler/skills/** for task-specific workflows.
- For a target assistant, research the current native guidance, skill, config, and policy formats
when the mapping is ambiguous.
- Verify Ruler behavior with a dry run when the CLI is available.
- Verify generated guidance by checking source markers in the target assistant's native guidance
file and generated skills in the target assistant's native skills directory when supported.
Freshness Workflow
When an agent uses a skill and current source contradicts it:
- Finish the user's product-code task first unless the guidance defect blocks the task.
- Update the narrowest
.ruler source that was wrong.
- Prefer replacing stale details over appending another long lesson.
- Keep history-derived guidance behavioral and durable.
- Mention the guidance update in the final response so reviewers know why
.ruler changed.
Source Map
- Repo-wide guidance + always-on rules:
.ruler/AGENTS.md
- Human setup guide:
.ruler/README.md
- Ruler config:
.ruler/ruler.toml
- Source skills:
.ruler/skills/**/SKILL.md
- Generated outputs (committed): root
AGENTS.md, root CLAUDE.md, and .claude/skills/ /
.codex/skills/; other .claude//.codex//.cursor/ files stay local
Rule And Skill Workflow
- For a new always-on policy, add or update a rule section in
.ruler/AGENTS.md and its summary in
the Source Rules index there.
- For package-specific details, update the package skill or a directly linked reference.
- For long notes, add a
references/ file only when progressive disclosure keeps the skill body
smaller and clearer.
- For assistant setup changes, keep human setup steps in
.ruler/README.md and behavioral agent
rules in .ruler/AGENTS.md.
- For assistant output questions, use the
guidance-source-of-truth rule unless current Ruler or
target-tool docs have changed.
- Treat command execution policy as a separate native format from prose guidance. Do not translate
.ruler/AGENTS.md guidance into command-policy files just because the target tool calls them "rules".
Verification
Use the target assistant for the change. For a Codex example:
npx @intellectronica/ruler apply --agents codex --dry-run --no-mcp --no-gitignore
ruler apply --agents codex
rg -n 'Source: .ruler/AGENTS.md' AGENTS.md
find .codex/skills -name SKILL.md
pnpm prettier --check .ruler README.md .gitignore
git diff --check
If npx cannot reach the registry, retry only when network approval is appropriate; otherwise
record the blocker and still run local formatting/diff checks.
Stop Conditions
- Stop before editing generated assistant outputs directly.
- Stop if a proposed rule duplicates detailed skill content instead of summarizing durable policy.
- Stop if current Ruler or target-tool docs contradict the Guidance Source Of Truth rule in
.ruler/AGENTS.md.
