Skip to content

AGENTS.md

Latest commit

 

History

History
71 lines (46 loc) · 3.97 KB

AGENTS.md

File metadata and controls

71 lines (46 loc) · 3.97 KB

AGENTS.md

Git Safety

  • Never use --force, --no-verify, or any other flag that bypasses git hooks or safety checks without explicit user approval.
  • If a hook or check fails, diagnose the issue and either fix it or ask the user how to proceed — do not silently skip it.

Pull Request Titles

  • Use the format: type(scope): <description>
    • Common types: feat, fix, refactor, docs, test, chore, ci, style, perf
    • Scope is optional but encouraged (e.g., feat(auth): add SSO login)
  • Use imperative mood (e.g., "Add feature", not "Added feature").
  • Keep titles under 72 characters.
  • Do not end the title with a period.

GitHub User Assignment

When assigning PRs or issues (e.g., user says "assign to me"), resolve the GitHub username with gh api user --jq '.login'. Never guess usernames.

Draft PRs

When creating a pull request, create it as ready for review by default. Only create it as a draft (gh pr create --draft) if the user explicitly requests a draft PR. Look for phrases like "draft", "WIP", or "not ready for review" in the user's prompt.

Pull Request Descriptions

When creating or updating a pull request, you must follow the PR template in .github/pull_request_template.md. Every PR description must include these four sections in order:

## Summary

  • Describe what changed and why. Be outcome-focused.
  • Call out architectural changes explicitly.
  • Include enough context for a reviewer unfamiliar with this code area.
  • Keep it concise. Do not pad with generic filler.

## Verification

  • List the checks you actually ran during development (tests, typecheck, lint, build, manual checks).
  • Include command names and pass/fail outcomes where available.
  • Do not fabricate verification steps. Only list testing you actually performed. Reviewers rely on this section to assess risk — dishonest verification is worse than none.

## Visual Changes

  • If UI or visual behavior changed, include a before/after screenshot table.
  • If there are no visual changes, replace the section content with N/A.

## Reviewer Notes

  • Add concise context that helps reviewer efficiency: risk areas, tricky logic, rollout notes, or edge cases.
  • If there is nothing noteworthy, keep this section brief or write N/A.

General rules

  • Preserve section headings and order exactly as they appear in the template.
  • Do not add sections that are not in the template.
  • Do not leave HTML comments from the template in the final description — replace them with actual content.
  • PR descriptions must be accurate and valuable to reviewers. Generic or boilerplate descriptions waste reviewer time.
  • Review all commits on the branch (not just the latest) when writing the summary.

Database Migrations

Migrations live in packages/db/src/migrations/ and are generated by drizzle-kit via pnpm drizzle generate.

  • Never hand-write or hand-edit migration SQL, snapshots, or the journal. Always use pnpm drizzle generate to produce migrations from the schema.
  • Backfill statements (UPDATE/INSERT) can be appended to a generated migration file after the generated DDL, using --> statement-breakpoint separators.
  • After a rebase that conflicts on migration files: delete all migration files, snapshots, and journal entries that were added on the branch, then re-run pnpm drizzle generate to regenerate a clean migration from the current schema diff. Re-append any backfill SQL afterward.
  • Prefer a single migration per feature branch when the code has not yet been deployed to production. If multiple migrations accumulated during development, squash them by deleting all branch-local migrations and regenerating.

KiloClaw Billing

Before making any changes related to KiloClaw billing — including bug fixes, new features, refactors, or reviews — you must first read the billing spec at .specs/kiloclaw-billing.md. This applies to all code paths that touch billing logic, pricing, invoicing, usage metering, or payment flows.