AGENTS.md

Guidance for human and AI contributors working in this repository.

1. Purpose

DealDesk is a control plane for AI-agent companies. The current implementation target is V1 and is defined in doc/SPEC-implementation.md.

2. Read This First

Before making changes, read in this order:

1. doc/GOAL.md
2. doc/PRODUCT.md
3. doc/SPEC-implementation.md
4. doc/DEVELOPING.md
5. doc/DATABASE.md

doc/SPEC.md is long-horizon product context. doc/SPEC-implementation.md is the concrete V1 build contract.

3. Repo Map

• server/: Express REST API and orchestration services
• ui/: React + Vite board UI
• packages/db/: Drizzle schema, migrations, DB clients
• packages/shared/: shared types, constants, validators, API path constants
• packages/adapters/: agent adapter implementations (Claude, Codex, Cursor, etc.)
• packages/adapter-utils/: shared adapter utilities
• packages/plugins/: plugin system packages
• doc/: operational and product docs

4. Dev Setup (Auto DB)

Use embedded PGlite in dev by leaving DATABASE_URL unset.

pnpm install
pnpm dev

This starts:

• API: http://localhost:3100
• UI: http://localhost:3100 (served by API server in dev middleware mode)

Quick checks:

curl http://localhost:3100/api/health
curl http://localhost:3100/api/companies

Reset local dev DB:

rm -rf data/pglite
pnpm dev

5. Core Engineering Rules

1. Keep changes company-scoped. Every domain entity should be scoped to a company and company boundaries must be enforced in routes/services.
2. Keep contracts synchronized. If you change schema/API behavior, update all impacted layers:

• packages/db schema and exports
• packages/shared types/constants/validators
• server routes/services
• ui API clients and pages

3. Preserve control-plane invariants.

• Single-assignee task model
• Atomic issue checkout semantics
• Approval gates for governed actions
• Budget hard-stop auto-pause behavior
• Activity logging for mutating actions

4. Do not replace strategic docs wholesale unless asked. Prefer additive updates. Keep doc/SPEC.md and doc/SPEC-implementation.md aligned.
5. Keep repo plan docs dated and centralized. When you are creating a plan file in the repository itself, new plan documents belong in doc/plans/ and should use YYYY-MM-DD-slug.md filenames. This does not replace DealDesk issue planning: if a DealDesk issue asks for a plan, update the issue plan document per the dealdesk skill instead of creating a repo markdown file.

6. Database Change Workflow

When changing data model:

1. Edit packages/db/src/schema/*.ts
2. Ensure new tables are exported from packages/db/src/schema/index.ts
3. Generate migration:

pnpm db:generate

4. Validate compile:

pnpm -r typecheck

Notes:

• packages/db/drizzle.config.ts reads compiled schema from dist/schema/*.js
• pnpm db:generate compiles packages/db first

7. Verification Before Hand-off

Default local/agent test path:

pnpm test

This is the cheap default and only runs the Vitest suite. Browser suites stay opt-in:

pnpm test:e2e
pnpm test:release-smoke

Run the browser suites only when your change touches them or when you are explicitly verifying CI/release flows.

For normal issue work, run the smallest relevant verification first. Do not default to repo-wide typecheck/build/test on every heartbeat when a narrower check is enough to prove the change.

Run this full check before claiming repo work done in a PR-ready hand-off, or when the change scope is broad enough that targeted checks are not sufficient:

pnpm -r typecheck
pnpm test:run
pnpm build

If anything cannot be run, explicitly report what was not run and why.

8. API and Auth Expectations

• Base path: /api
• Board access is treated as full-control operator context
• Agent access uses bearer API keys (agent_api_keys), hashed at rest
• Agent keys must not access other companies

When adding endpoints:

• apply company access checks
• enforce actor permissions (board vs agent)
• write activity log entries for mutations
• return consistent HTTP errors (400/401/403/404/409/422/500)

9. UI Expectations

• Keep routes and nav aligned with available API surface
• Use company selection context for company-scoped pages
• Surface failures clearly; do not silently ignore API errors

10. Pull Request Requirements

When creating a pull request (via gh pr create or any other method), you must read and fill in every section of .github/PULL_REQUEST_TEMPLATE.md. Do not craft ad-hoc PR bodies — use the template as the structure for your PR description. Required sections:

• Thinking Path — trace reasoning from project context to this change (see CONTRIBUTING.md for examples)
• What Changed — bullet list of concrete changes
• Verification — how a reviewer can confirm it works
• Risks — what could go wrong
• Model Used — the AI model that produced or assisted with the change (provider, exact model ID, context window, capabilities). Write "None — human-authored" if no AI was used.
• Checklist — all items checked

11. Definition of Done

A change is done when all are true:

1. Behavior matches doc/SPEC-implementation.md
2. Typecheck, tests, and build pass
3. Contracts are synced across db/shared/server/ui
4. Docs updated when behavior or commands change
5. PR description follows the PR template with all sections filled in (including Model Used)

12. DealDesk Product Notes

• CLI command: dealdesk (local dev: pnpm dealdesk or pnpm dev)
• Config home: ~/.dealdesk (legacy ~/.dealdesk supported via migration shim)
• Workspace packages: @dealdesk/*
• External Hermes adapter: @henkey/hermes-dealdesk-adapter (npm package name unchanged)
• Adapter plugins config: ~/.dealdesk/adapter-plugins.json