AGENTS.md

Agent Development Guide

Non-obvious constraints and gotchas for AI agents working on this codebase.

Critical Gotchas

Handler Ordering

In src/main.ts, CustomHandler must be last in the handlers array:

const handlers: EventHandler[] = [
  new WorkflowHandler(),
  new SecurityHandler(),
  new DeploymentHandler(),
  new PRHandler(),
  new CustomHandler(), // ⚠️ MUST BE LAST - matches everything
];

Why: First matching handler processes the event. CustomHandler is a catch-all.

Commit dist/ Directory

The dist/index.js bundle must be committed to version control.

Why: GitHub Actions run pre-built artifacts. They don't execute build steps.

Workflow: After changing src/, run npm run bundle and commit both src/ and dist/. whi

Non-Obvious Patterns

Entry Point Split

src/index.ts calls src/main.ts:

// index.ts - minimal, just triggers execution
import { run } from "./main.js";
run();

// main.ts - exports function for testing
export async function run(): Promise<void> {
  // All action logic here
}

Purpose: Allows main.ts to be imported in tests without executing.

Integration Tests Skip Gracefully

__tests__/incident-api.test.ts skips (not fails) when INCIDENT_TEST_API_KEY is unset. This is intentional - allows CI/local runs without credentials.

Before Completing Work

• Whenever a change that impacts the behavior or functionality of the code is applied, propose a matching documentation update. Check all documentation files to ensure consistency.
• Run npm run all - this is the full validation pipeline. All steps must pass.
• Update the project's documentation to reflect changes that impact the user, such as how to configure or run anything, or operational concerns the user should consider.