How to Work with AI

The rules and skills in this repo make AI assistants more useful. Here's how to get the most out of them.

Rules kick in automatically

The .cursor/rules/ files are always active. You don't need to reference them or paste them into prompts. When you ask an AI agent to "add a new API route," it already knows to:

• Use getAuthenticatedApp() for the route group
• Add validate("json", schema) middleware
• Throw ApplicationError instead of using try/catch
• Put the route in src/routes/<domain>/index.ts
• Keep the handler thin and call a module function

Skills are triggered by context

Skills activate when the task matches their purpose. Ask the agent to "create a new pack" and the create-pack skill guides it through the right file structure. Ask it to "build a settings page" and the frontend-design skill produces polished UI.

Tips for better results

Be specific about location

Instead of "add a notification feature," say "add a notification feature in src/features/notifications/." The rules handle conventions, but you still need to tell the agent where to work.

Reference existing patterns

"Make it work like src/features/projects/" gives the AI a concrete example to follow. The codebase is consistent, so pointing at any domain works as a template.

Let it handle structure

Don't micromanage file placement. The rules encode the folder conventions (modules/, db/queries/, db/mutations/, schemas/). Say what you want built, and the rules handle where files go.

Review the output

AI-generated code follows your conventions, but it still needs review. Check that:

• Business logic makes sense
• Edge cases are handled
• Database queries are efficient
• The feature integrates with existing code correctly

Adding your own rules

Create a new .mdc file in .cursor/rules/:

---
description: When to activate this rule
globs:
  - "src/features/my-domain/**"
---

# My Rule

Instructions here.

Rules with globs activate only when editing matching files. Rules without globs are always active. Keep rules focused: one topic per file.

Adding skills

Create a new skill in .agents/skills/<name>/SKILL.md. Skills are longer-form guides that teach agents a complete workflow, like creating a pack or designing a UI component.