learnwy/lwy-project-rules-writer

Project Rules Writer

Create rules that solve a specific problem in a specific project — never generic ones. Analyse the project first, design, confirm with AskUserQuestion, then generate.

Core discipline: understand the problem → analyse the project → design the rule → confirm → generate. No file lands without user confirmation.

Shared writing-discipline rules across this and the other writer skills (project-skill-writer / project-agent-writer / project-skill-installer): see ../project-skill-writer/references/writer-discipline.md.

When to use

• "create a rule", "for X create a rule", "set the code style"
• "make the AI always …", "enforce naming convention", "configure AI behaviour"
• User references .agents/rules/..., .trae/rules/..., or #RuleName syntax
• Constrain AI behaviour for a specific project or file pattern

When NOT to use

| User wants | Delegate to | |---|---| | A skill | project-skill-writer | | An agent / subagent | project-agent-writer | | Install an existing skill | project-skill-installer | | Documentation about how rules work | Just answer; don't generate |

Prerequisites

• Node.js ≥ 18
• A project where an AI assistant reads project rules (Trae, Cursor, Windsurf, Claude Code, etc.). This writer emits to <project>/.agents/rules/; symlink or sync to .trae/rules/ / .cursor/rules/ if your IDE needs that exact path.

Workflow (5 steps)

L1 Understand the problem  →  L2 Analyse the project  →  L3 Design the rule  →  L4 Confirm  →  L5 Generate + validate

L1 — Understand the problem

Don't ask "what rule do you want?" Infer from the prompt:

| Pattern | Rule type | Apply mode | Example | |---|---|---|---| | "AI keeps using wrong naming" | Convention | File-specific (globs) | camelCase for .ts, snake_case for .py | | "AI should always do X" | Behaviour | Always-apply | Always use the project logger | | "AI ignores our architecture" | Structure | Smart (description) | Enforce layered-arch boundaries | | "AI generates wrong imports" | Style | File-specific | Use @/ path aliases in .tsx | | "I want to toggle manually" | Manual | #RuleName | Ad-hoc code-review checklist |

Extract: problem, scope (which files/contexts), expected behaviour, exceptions.

L2 — Analyse the project

Run two agents in parallel via the Task tool:

• project-scanner — structure, existing rules, patterns
• convention-detector — naming / style / architecture conventions

Detect: language(s), framework, existing rule files (.agents/rules/*.md first, then .trae/rules/*.md if present), lint/format configs (ESLint, Prettier, EditorConfig, Ruff), naming patterns, layering.

L3 — Design the rule

Apply-mode picker:

| Mode | Use when | Frontmatter | |---|---|---| | Always-apply | Rule fits every AI interaction | alwaysApply: true | | File-specific | Rule applies to certain file types | globs: *.tsx,*.ts + alwaysApply: false | | Smart | AI decides per request via the description | description: "..." + alwaysApply: false | | Manual | User invokes via #RuleName | no frontmatter |

Design principles: one problem per rule • follow project conventions • narrowest scope that covers the problem • no conflict with existing rules.

Frontmatter format gotchas (the gate enforces these in L5):

| Wrong | Right | |---|---| | globs: "*.ts" | globs: *.ts,*.tsx | | globs: ["*.ts"] | globs: *.ts | | absolute paths | project-relative | | missing description | always include description | | alwaysApply: true AND globs: | one or the other |

L4 — Confirm (mandatory)

Use AskUserQuestion to present the design before any file is written. Include the rule name, apply mode, and output path. Offer "create / adjust / skip" — and if multiple modes are valid, offer the mode choice as a separate question. Never write a file without user confirmation. If the user says "adjust", loop back to L3.

L5 — Generate + validate

node scripts/cli.cjs init \
  --skill-dir <this-skill-dir> \
  --name <rule-name> \
  --description "<when-this-rule-applies>" \
  --output-dir <project>/.agents/rules/

Fallback: if init doesn't fit, write the .md file directly using assets/rule.md.template.

Then run quality-validator. Pre-delivery checklist:

• [ ] globs: comma-separated, no quotes, no array
• [ ] No absolute paths in rule content
• [ ] description present and explains when the rule applies
• [ ] alwaysApply and globs not both active
• [ ] No conflict with existing rules (from L2 analysis)
• [ ] Rule content is actionable (specific constraints, not vague advice)
• [ ] Content in English

Delivery report

Rule created:
  Name:    {rule-name}
  Mode:    {always|file-specific|smart|manual}
  Path:    {project-relative path}

Frontmatter:
  description: {value}
  globs:       {value if applicable}
  alwaysApply: {value}

Usage: {one-line note on how it fires}

Error handling

| Problem | Resolution | |---|---| | User's ask is too vague | Infer the most likely rule type from context, confirm in L4 | | Multiple valid apply modes | Surface the choice in L4 | | .agents/rules/ doesn't exist | Create it under the project root | | User wants a skill / agent / install | Route to the right writer skill | | User says "adjust design" in L4 | Loop back to L3 with feedback | | Rule contains an absolute path | Reject; convert to project-relative | | New rule conflicts with an existing one | Show diff, ask user to merge / replace / rename | | globs malformed | Auto-fix: drop quotes, flatten arrays, use commas | | No detectable conventions | Fall back to language defaults; note the assumption in the delivery report |

Boundaries

This skill only: analyses project context, designs a rule, confirms with the user, generates a frontmatter+markdown .md at <project>/.agents/rules/ (project-relative, IDE-neutral), validates the result.

This skill does not: create skills (→ project-skill-writer), create agents (→ project-agent-writer), install skills (→ project-skill-installer), edit any IDE's own settings, or install rules globally.

Agents and references

• Agents: project-scanner, convention-detector, quality-validator
• references/rule-types.md — pick the right rule type from a problem
• examples/application-modes.md — all four apply modes with frontmatter examples
• assets/rule.md.template — scaffold
• assets/trae-rules-docs.md — vendored frontmatter format reference (originally from Trae's rules doc; format is shared across Trae / Cursor / Windsurf)