Skip to content

AGENTS.md

Latest commit

 

History

History
135 lines (95 loc) · 5.3 KB

AGENTS.md

File metadata and controls

135 lines (95 loc) · 5.3 KB
Raw

Agent Instructions

Package Manager

Use pnpm: pnpm install, pnpm build, pnpm test

Commit Attribution

AI commits MUST include:

Co-Authored-By: <model name> <noreply@anthropic.com>

Example: Co-Authored-By: Claude Sonnet 4 <noreply@anthropic.com>

Architecture

This is a pnpm workspace monorepo. Shared build tools (oxlint, lint-staged, simple-git-hooks, typescript, vitest) live in the root package.json.

TELEMETRY.md           # Sentry telemetry investigation map; points to Junior's shared spec

packages/
├── warden/            # @sentry/warden core package
│   └── src/
│       ├── index.ts   # Library entry point
│       ├── types/     # Zod schemas and types
│       ├── config/    # Config loading (warden.toml)
│       ├── triggers/  # Event trigger matching
│       ├── event/     # GitHub event parsing
│       ├── diff/      # Diff parsing and context
│       ├── output/    # Report rendering
│       ├── skills/    # Skill discovery and loading
│       ├── sdk/       # Agent SDK runner
│       ├── cli/       # CLI entry and commands
│       ├── action/    # GitHub Action entry
│       ├── utils/     # Shared utilities
│       └── examples/  # Example configurations
├── docs/              # Astro docs site (warden-docs), deployed via Vercel
├── evals/             # Private eval package: runner, scenarios, fixtures, test skills

Key Conventions

  • TypeScript strict mode
  • Zod for runtime validation
  • ESM modules ("type": "module")
  • Vitest for testing

TypeScript Exports

Use export type for type-only exports. This is required for Bun compatibility:

// Good
export type { SkillReport } from "./types/index.js";
export { runSkill } from "./sdk/runner.js";

// Bad - fails in Bun
export { SkillReport, runSkill } from "./types/index.js";

Testing

Use /testing-guidelines when writing tests. Key principles:

  • Mock external services, use sanitized real-world fixtures
  • Prefer integration tests over unit tests
  • Always add regression tests for bugs
  • Cover every user entry point with at least a happy-path test
  • Co-locate tests with source (foo.ts → foo.test.ts)

Build & Dist

The ncc action bundle (dist/action/) is committed so every commit and release tag can run as an Action. On same-repo PRs, action-dist.yml rebuilds it and commit-action-dist.yml commits it back. On fork PRs, run pnpm build:action and commit dist/action/. CI fails when it is stale. The rest of dist/ is gitignored. Craft moves v0 to each stable release commit (floatingTags) and skips v0 when it looks up versions. See specs/release-process.md.

Verifying Changes

pnpm lint && pnpm build && pnpm test

Policies

Repo-wide defaults live under policies/.

  • Benchmark tables: Don't add metadata to benchmark tables or their variants unless explicitly requested.
  • policies/code-comments.md: Exported functions need brief JSDoc. Comments explain non-obvious intent, invariants, or tradeoffs. Remove stale or obvious comments when behavior changes.

Task Management

Use /dex to break down complex work, track progress across sessions, and coordinate multi-step implementations.

Skills

Workflow

  • /commit — Always use for commits. Never commit directly
  • /create-pr — Always use for PRs. Never create PRs directly
  • /iterate-pr — Fix CI failures and review feedback until checks pass

Code Quality

  • /warden — Run Warden analysis before committing. See packages/warden/skills/warden/SKILL.md
  • /warden-service — Query the Warden Service read API. See packages/warden/skills/warden-service/SKILL.md
  • /warden-sweep — Full-repo code sweep: scan, verify, patch, draft PRs. See packages/warden/skills/warden-sweep/SKILL.md
  • /code-simplifier — Simplify and refine code
  • /architecture-review — Staff-level codebase health review. See .agents/skills/architecture-review/SKILL.md

Authoring

  • /testing-guidelines — Required when writing tests. See .agents/skills/testing-guidelines/SKILL.md
  • /agent-prompt — Reference for writing skills and prompts. See .agents/skills/agent-prompt/SKILL.md
  • /skill-creator — Always use when creating or updating skills
  • /brand-guidelines — Sentry voice and copy guidelines

Skills Policy

Skills define what to look for, not how to respond to findings:

  • When Warden reports findings, fix the code. Don't modify skills to suppress results
  • Skills should only change to improve detection accuracy, not to reduce reported findings
  • Each skill owns its domain expertise; severity definitions are intentionally domain-agnostic

Evals

End-to-end evals for the full pipeline plus verifier-only evals live in packages/evals/. See packages/evals/INTERNAL.md for maintainer workflow and packages/evals/README.md for schemas. Run with pnpm evals; scaffold PR fixtures with pnpm evals:scaffold <github-pr-url>.

Voice

Warden watches over your code. Not "AI code reviewer" or similar.

Keep it brief, dry, and slightly ominous. Think security guard who's seen everything. Professional but with personality. No fluff, no hype, no em-dashes.