Skip to content

INSTRUCTIONS.md

Latest commit

 

History

History
140 lines (102 loc) · 4.7 KB

INSTRUCTIONS.md

File metadata and controls

140 lines (102 loc) · 4.7 KB
Raw

AI Development Guidelines

Agent-specific instructions are in .agents/ subfolders and override these guidelines.

Core Principles

Minimalism

  • Only write what's necessary, avoid over-engineering
  • Less code = less maintenance

Code Quality

  • Prioritize clarity over cleverness
  • Use meaningful names and simple logic

No Duplicate Code

  • Extract shared logic into reusable modules
  • If you write the same code twice, refactor it

Small Functions

  • Under ~100 lines
  • Single purpose

Testing

  • Focus on critical paths and edge cases, not the obvious
  • Keep tests short and simple

Documentation

  • Document "why", not "what" (code shows what)
  • Keep docs near the code
  • Update docs when code changes

DX First

When modifying interfaces or their usage:

  1. Update documentation first
  2. Ensure the design is clear and simple to use
  3. Then implement the changes

Why: Writing docs first forces you to think through the API from the user's perspective before coding.

Changesets

When modifying packages that are published (check for "private": true in package.json):

  • Create a changeset file in .changeset/ with a random filename (e.g., happy-tiger-123.md): 
    ---
"package-name": patch
---

Short summary of the change from user's perspective
  • Bump types: patch (bug fixes), minor (new features), major (breaking changes)
  • Skip changesets for: docs-only changes, test-only changes, internal tooling

Why: Changesets automate versioning and changelog generation, ensuring users know what changed between releases.

Plans

Store in /.plans/ with date prefix (e.g., 2026-01-27-feature-name.md).

  • Keep plans focused on one feature/system
  • Include a Progress section with task status table
  • Plans are temporary: delete when complete, preserve knowledge in code and docs

When starting a task, review existing plans in /.plans/ to find relevant context.

Claim a Plan Before Executing It

A plan sitting in /.plans/ is not evidence that nobody is working on it. Sessions run concurrently and cannot see each other, so before executing a plan:

  1. Search open and recently closed PRs for the plan's filename.
  2. If one references it, the plan is claimed — do not execute it. Review or extend that PR instead.
  3. If none does, name the plan file in your PR body so the next session sees your claim.
  4. Delete the plan file in the same PR that completes it.

Why: duplicate PRs have twice been opened because a plan sat unclaimed while two sessions independently picked it up and built the same thing. The PR is the only state both sessions can see, so the claim has to live there.

Task Management

Plans are living documents that evolve as understanding grows:

  • Break work into concrete, actionable tasks
  • Update task definitions as you learn more
  • Add new tasks as complexity is discovered
  • Remove or merge tasks that become unnecessary

If a task proves too complex:

  • Pause to research and understand the problem deeper
  • Break it into smaller tasks and update the plan
  • This is valid progress - don't force completion of oversized tasks

Risk-First Prioritization

Always pick the highest-risk task first - the one with most uncertainty:

  • Unknown technical feasibility → tackle first
  • Unclear requirements → clarify and implement early
  • Complex integrations → prove them before building around them

Why: Early failures are cheap. Discovering a blocker after building dependent features is expensive.

Keeping Plans Current

After completing any task:

  • Mark it done in the Progress table
  • Update remaining task definitions if understanding changed
  • Add new tasks discovered during implementation
  • Revise estimates/scope based on what you learned

Completing Plans

When all tasks in a plan are done:

  1. Preserve knowledge before deleting:

    • Add TODO: comments in code for future enhancements mentioned in the plan
    • Document architectural decisions with "why" comments where non-obvious
    • Update README or other docs if the plan contained user-facing information
    • Ensure any competitor analysis or research insights are captured where relevant

  2. Delete the plan file - Plans are temporary; don't let them accumulate

Why: Plans contain valuable context (future ideas, design rationale, research). Embedding this in code/docs keeps it discoverable and maintained, while removing the stale plan file.

Pre-PR Validation

All steps must pass before submitting:

pnpm install --frozen-lockfile
pnpm lint    # Run 'pnpm fix' to auto-fix
pnpm build
pnpm test

Checklist

  • Lint passes
  • Build succeeds
  • Tests pass
  • README updated (if user-facing changes)
  • Changeset added (if modifying published packages)