AGENTS.md · spinabot/brigade

Sections

1. What Brigade is
2. Naming & brand conventions (MUST follow)
3. Commands
4. Repository layout
5. Conventions (non-negotiable)
6. Recipes
7. Storage modes (filesystem vs. Convex)
8. Architecture invariants
9. Proactive checks when touching subsystems
10. Commit & release policy

First lines (shown under the repo's MIT license)

# AGENTS.md — Working in the Brigade codebase

This guide is for humans and AI coding agents contributing to Brigade. It covers
the layout, the commands, the conventions you must follow, and the recipes for
common changes. Read it before you touch the tree.

For user-facing docs see [README.md](README.md). For the release flow see
[docs/RELEASING.md](docs/RELEASING.md).

---

## What Brigade is

A single-operator, multi-agent AI-crew runtime written in TypeScript. It runs as a
headless WebSocket **gateway** (the state-holding daemon) with thin clients (a chat
TUI, `connect`, channel adapters). It is built on the **pi** SDK
(`@earendil-works/pi-agent-core` + `@earendil-works/pi-ai` +
`@earendil-works/pi-coding-agent` + `@earendil-works/pi-tui`, pinned exact at
`0.79.9`) and adds product layers on top: memory, skills, sub-agents, tools, an org
hierarchy, channels, cron, an extension SDK, and a dual-mode storage layer.

- **Stack:** TypeScript (strict), ESM, Node **≥ 22.12**, **npm** (never pnpm).
- **Build:** `tsc` → `dist/`. No bundler.
- **Tests:** Node's built-in `node:test`, run via `tsx`.
- **State:** everything under `~/.brigade/` (override: `BRIGADE_STATE_DIR`).

---

## Naming & brand conventions (MUST follow)

- The product is **Brigade**. In code, comments, copy, CLI help, error messages,
  env vars, daemon labels, and docs, refer to the agent SDK **only** as `pi` /
  `@earendil-works/pi-coding-agent`. Do not name other third-party AI agent projects.
- **Never** commit secrets, real personal data (names, phone numbers, emails), or
  local absolute paths. Use placeholders (`+1 555 010 0001`, `/path/to/project`).
- The mascot is 🦁 the Pride. No other animal/symbol.
- `templates/workspace/` holds default persona files and is **off-limits**:
  behavioural fixes go in code, never in template content.
- No `Co-Authored-By` trailers on commits.

Daemon labels (don't rename): macOS launchd `com.brigade.gateway`, Linux systemd
`brigade-gateway`, Windows Task Scheduler `BrigadeGateway`.

---

## Commands

| Task | Command |
|---|---|
| Build | `npm run build` (`tsc -p tsconfig.build.json` → `dist/`) |
| Build (watch) | `npm run build:watch` |
| Typecheck | `npm run typecheck` (`tsc -p tsconfig.json --noEmit`, includes tests) |
| Test (all) | `npm test` (`node scripts/run-tests.mjs`) |
| Test (one file) | `npm test -- src/agents/tools/registry.test.ts` |
| Memory eval/bench | `npm run bench` |
| Run built binary | `npm run brigade -- <args>` (e.g. `npm run brigade -- agent -m "hi"`) |
| Dev (build-then-run) | `npm run dev -- <args>` |
| Dev (no build, tsx) | `npm run dev:tsx -- <args>` |
| Dev (auto-restart) | `npm run watch` |
| Clean | `npm run clean` |

Before opening a PR, all three of these must pass: `npm run typecheck`,
`npm test`, `npm run build`.

**Test isolation:** `scripts/run-tests.mjs` pins `BRIGADE_STATE_DIR` to a fresh
tempdir so tests never touch your real `~/.brigade`. There are **281** `.test.ts`
files under `src/`.

---

## Repository layout

```
brigade/  (working tree; storage is ~/.brigade)
├── brigade.mjs                 # bin shim: enforces Node ≥22.12, routes to dist/entry.js
├── package.json                # npm; pi 0.79.9 pinned exact
├── tsconfig.json               # typecheck config (includes tests)
├── tsconfig.build.json         # build config (emits dist/, excludes tests/templates)
├── scripts/                    # run-brigade.mjs, run-tests.mjs, build-done.mjs, convex-*.mjs
├── skills/                     # 56 bundled skill directories
├── templates/workspace/        # default persona files — OFF LIMITS for edits
├── convex/                     # Convex schema + functions (optional storage backend)
└── src/
    ├── entry.ts                # CLI entry (fast-path version/help, lazy dispatch)
    ├── extension-sdk.ts        # public plugin SDK (defineModule + re-exports)
    ├── cli/                    # command files + program/build-program.ts (command registry)
    ├── core/                   # gateway server.ts, daemon/ installers, dispatch
    ├── agents/                 # the runtime (see below) — the bulk of the code
    │   ├── agent-loop.ts       # per-turn loop
    │   ├── session-wiring.ts   # toolset assembly + before-tool-call guards
    │   ├── tools/              # Brigade-native tools + registry.ts
    │   ├── memory/             # facts store, decay, auto-recall, consolidate
    │   ├── skills/             # 6-source discovery, eligibility, manage
    │   ├── subagent-*.ts       # spawn, policy, abort cascade, completion bridge
    │   ├── channels/           # adapter contract + inbound-pipeline + whatsapp/
    │   ├── routing/            # inbound → (agentId, sessionKey)
    │   ├── org/                # org/Pride hierarchy + A2A policy
    │   └── extensions/         # plugin engine + bundled modules/ (web search, etc.)
    ├── tideline/               # long-term memory engine (hybrid recall, link graph)
    ├── system-prompt/          # assembler.ts + sections (persona pin, org anchor)
    ├── sessions/               # session store, write-lock, transcript repair
    ├── storage/                # dual-mode store: local/ (filesystem) + convex/
    ├── config/                 # brigade.json schema, io, validators
    ├── providers/              # model provider catalog + auth detection
    ├── auth/ · security/       # auth profiles, encryption (libsodium seal)
    ├── cron/                   # scheduler + isolated-agent run executor
    ├── tui/ · ui/              # terminal client + brand frames
    └── workspace/              # persona file loaders (bootstrap.ts)
```

---

## Conventions (non-negotiable)

### ESM imports — always include the `.js` extension
```ts
import { makeAgentsListTool } from "./agents-list-tool.js";  // ✅
import { makeAgentsListTool } from "./agents-list-tool";     // ❌ breaks at runtime
```
This applies to every relative import. The project compiles TS → ESM (NodeNext).

### Strict TypeScript
`strict`, `noUncheckedIndexedAccess`, and `noImplicitOverride` are on. Avoid `any`
except for unavoidable schema/plugin boundaries. Tests must pass `npm run
typecheck`.

### Ownership gates
Privileged tools use one of two postures — prefer the first:
1. **Per-call gate:** the tool is registered for everyone but branches on
   `opts.senderIsOwner` to refuse mutating actions for channel peers (e.g.
   `cron list` is allowed, `cron add` is not). Per-action granularity.
2. **Blanket `ownerOnly: true`:** refused to non-owners at registration. Use when
   *every* action is privileged (e.g. `manage_provider`, `composio`).
   `senderIsOwner` defaults to `false`; only an explicit owner flow sets it `true`.

### Memory origin isolation (load-bearing)
Every memory read/write threads a `MemoryRecordOrigin` (`owner` vs.
`channel+conversationId+sessionKey`). Owner facts are never visible to peers;
channel facts recall only on an exact origin match. Dedup is same-origin only.
Auto-recall filters by origin **before** injecting. Any new memory path must thread
origin or isolation breaks silently.

### Config & secrets
`brigade.json` writes keep 5 forensic backups (`.bak` + `.bak.{1..4}`, mode 0600).
Secrets use `${VAR_NAME}` references that resolve at read and are **restored** (not
persisted resolved) on write. Keep `brigade secrets audit` clean.

### No per-cwd persona walker
Brigade does **not** walk project rule files. Persona comes from
`~/.brigade/workspace/` only.

---

## Recipes

### Add a tool
1. Create `src/agents/tools/my-tool.ts` exporting a `makeMyTool()` factory that
   returns a `BrigadeTool` (TypeBox params, `jsonResult`).
2. Register it in `src/agents/tools/registry.ts` (`createBrigadeTools`).
3. Choose a gate posture (per-call `senderIsOwner` recommended).