Docs & rules

bradygaster/squadGitHub

This is a public, read-only report. Striff reads this repository's docs, turns each sentence that makes a claim about the code into a rule, and checks the rule against the code on the default branch. How this works

dev1f8daeeLast read 19 min ago

Is this yours? Install to manage it

Once installed, Striff checks every pull request.

119

715 docs

bradygaster/squadOpen repository

bradygaster/squad — documented rules

119 of 119 rules, printed October 25, 2026.

The sentence in your docs
Prefer `archiveEntries()`, `prepareInboxBodyForMerge()`, and `formatArchivalReport()` from `packages/squad-sdk/src/state/io/archival.ts` over hand-rolled archival logic. 3 rules from this sentence	`archiveEntries` is in `packages/squad-sdk/src/state/io` checks “archiveEntries()”	Holds
	`prepareInboxBodyForMerge` is in `packages/squad-sdk/src/state/io` checks “prepareInboxBodyForMerge()”	Holds
	`formatArchivalReport` is in `packages/squad-sdk/src/state/io` checks “formatArchivalReport() from packages/squad-sdk/src/state/io/archival.ts”	Holds
❌ NEVER add `import` or `require` statements referencing packages outside `node:*` built-ins 5 rules from this sentence	`packages/squad-cli/src/cli/core/detect-squad-dir.ts` may only import `node:*` Not written in the sentence: the type `packages/squad-cli/src/cli/core/detect-squad-dir.ts`. Striff read its words as this and checked the rule on it.	Holds
	`packages/squad-cli/src/cli/core/errors.ts` may only import `node:*` Not written in the sentence: the type `packages/squad-cli/src/cli/core/errors.ts`. Striff read its words as this and checked the rule on it.	Holds
	`packages/squad-cli/src/cli/core/gh-cli.ts` may only import `node:*` Not written in the sentence: the type `packages/squad-cli/src/cli/core/gh-cli.ts`. Striff read its words as this and checked the rule on it.	Holds
	`packages/squad-cli/src/cli/core/output.ts` may only import `node:*` Not written in the sentence: the type `packages/squad-cli/src/cli/core/output.ts`. Striff read its words as this and checked the rule on it.	Holds
	`packages/squad-cli/src/cli/core/history-split.ts` may only import `node:*` Not written in the sentence: the type `packages/squad-cli/src/cli/core/history-split.ts`. Striff read its words as this and checked the rule on it.	Holds
We use a TypeScript interface (`PlatformAdapter`) rather than an abstract class.	`PlatformAdapter` is a contract	Holds
An approval record is `{ approvalId, version, scope, action, hash, payload?, state, runId, requestedAt, decidedAt?, decision?, reason? }`. 12 rules from this sentence	`ApprovalRecord` has `approvalId`, `version`, `scope` and 9 more	Holdsall 12
Resource POST /v1/conversations, SquadBackend method createConversation (idempotent per conversationId ), Canonical shape BackendConversation 2 rules from this sentence	`SquadBackend` depends on `BackendConversation`	Holds
	`SquadBackend` has a `createConversation` method checks “SquadBackend method createConversation”	Holds
Resource POST /v1/capabilities, SquadBackend method negotiate, Canonical shape NegotiatedCapabilities 2 rules from this sentence	`SquadBackend` depends on `NegotiatedCapabilities`	Holds
	`SquadBackend` has a `negotiate` method checks “SquadBackend method negotiate”	Holds
Resource POST /v1/conversations/{id}/messages, SquadBackend method sendMessage (idempotent per (runId, seq) ), Canonical shape BackendMessage → BackendAdmission 3 rules from this sentence	`SquadBackend` depends on `BackendMessage`	Holds
	`SquadBackend` depends on `BackendAdmission`	Holds
	`SquadBackend` has a `sendMessage` method checks “SquadBackend method sendMessage”	Holds
Resource GET /v1/conversations/{id}/transcript, SquadBackend method getTranscript, Canonical shape BackendMessage[]	`SquadBackend` has a `getTranscript` method	Holds
Resource GET /v1/conversations/{id}/events?after=&limit=&stream=, SquadBackend method readEvents, Canonical shape BackendEventPage of BackendEnvelope 3 rules from this sentence	`SquadBackend` depends on `BackendEventPage`	Holds
	`BackendEventPage` depends on `BackendEnvelope` checks “Canonical shape BackendEventPage of BackendEnvelope”	Holds
	`SquadBackend` has a `readEvents` method checks “SquadBackend method readEvents”	Holds
Resource GET /v1/conversations/{id}/turns/{seq}, SquadBackend method getTurn, Canonical shape BackendTurn 2 rules from this sentence	`SquadBackend` depends on `BackendTurn`	Holds
	`SquadBackend` has a `getTurn` method checks “SquadBackend method getTurn”	Holds
Resource POST /v1/conversations/{id}/turns/{seq}/cancel, SquadBackend method cancelTurn, Canonical shape BackendTurn	`SquadBackend` has a `cancelTurn` method	Holds
Resource POST /v1/conversations/{id}/runs/{runId}/cancel, SquadBackend method cancelRun (stable run identity), Canonical shape BackendTurn	`SquadBackend` has a `cancelRun` method	Holds
Resource GET /v1/conversations/{id}/approvals, SquadBackend method getApprovals, Canonical shape ApprovalRecord[] 2 rules from this sentence	`SquadBackend` depends on `ApprovalRecord`	Holds
	`SquadBackend` has a `getApprovals` method checks “SquadBackend method getApprovals”	Holds
Resource POST /v1/conversations/{id}/approvals/{approvalId}, SquadBackend method respondApproval (echoes the request hash ), Canonical shape ApprovalResponse → BackendTurn	`SquadBackend` has a `respondApproval` method	Holds
`approvalId`, `turnSeq`, `runId` and a `scope` (`turn` by default); 4 rules from this sentence	`ApprovalRecord` has `approvalId` Not written in the sentence: the type `ApprovalRecord`. Striff read its words as this and checked the rule on it.checks “approvalId”	Holds
	`ApprovalRecord` has `turnSeq` Not written in the sentence: the type `ApprovalRecord`. Striff read its words as this and checked the rule on it.checks “turnSeq”	Holds
	`ApprovalRecord` has `runId` Not written in the sentence: the type `ApprovalRecord`. Striff read its words as this and checked the rule on it.checks “runId”	Holds
	`ApprovalRecord` has `scope` Not written in the sentence: the type `ApprovalRecord`. Striff read its words as this and checked the rule on it.checks “scope”	Holds
`version` (1 while pending, 2 once decided or cancelled) and `state` (`pending`, `approved`, `denied`, `cancelled`); 2 rules from this sentence	`ApprovalRecord` has `version` Not written in the sentence: the type `ApprovalRecord`. Striff read its words as this and checked the rule on it.checks “version”	Holds
	`ApprovalRecord` has `state` Not written in the sentence: the type `ApprovalRecord`. Striff read its words as this and checked the rule on it.checks “state”	Holds
`hash`, an opaque string supplied by the harness together with the request;	`ApprovalRecord` has `hash` Not written in the sentence: the type `ApprovalRecord`. Striff read its words as this and checked the rule on it.	Holds
`requestedAt` and, after the decision, `decidedAt`, `decision` and `reason`. 4 rules from this sentence	`ApprovalRecord` has `requestedAt` Not written in the sentence: the type `ApprovalRecord`. Striff read its words as this and checked the rule on it.checks “requestedAt”	Holds
	`ApprovalRecord` has `decidedAt` Not written in the sentence: the type `ApprovalRecord`. Striff read its words as this and checked the rule on it.checks “decidedAt”	Holds
	`ApprovalRecord` has `decision` Not written in the sentence: the type `ApprovalRecord`. Striff read its words as this and checked the rule on it.	Holds
	`ApprovalRecord` has `reason` Not written in the sentence: the type `ApprovalRecord`. Striff read its words as this and checked the rule on it.checks “reason”	Holds
Adapter HostProjection, Plane boundary workspace projection only, Responsibility writes, updates, and removes host-owned files without runtime or backend dependencies 2 rules from this sentence	`HostProjection` may not depend on `packages/squad-sdk/src/runtime` Not written in the sentence: the part of the code `packages/squad-sdk/src/runtime`. Striff read its words as this and checked the rule on it.	Holdsclient runtime
	`HostProjection` may not depend on `packages/squad-sdk/src/backend` Not written in the sentence: the part of the code `packages/squad-sdk/src/backend`. Striff read its words as this and checked the rule on it.	Holdsclient backend
The `HarnessAdapter` SPI is defined in `packages/squad-sdk/src/backend/types.ts` and exported from `@bradygaster/squad-sdk/backend`; the broker (`LocalSquadBackend`) calls it through a `HarnessRegistry`.	`HarnessRegistry` depends on `HarnessAdapter`	Holds
The `HarnessAdapter` SPI is defined in `packages/squad-sdk/src/backend/types.ts` and exported from `@bradygaster/squad-sdk/backend`;	`HarnessAdapter` is in `packages/squad-sdk/src/backend`	Holds
the broker (`LocalSquadBackend`) calls it through a `HarnessRegistry`.	`LocalSquadBackend` depends on `HarnessRegistry`	Holds
`describe` and `projectWorkspace` on `ClientAdapter` let the broker reason about host capabilities and file projection without special-casing each client in coordinator logic. 2 rules from this sentence	`ClientAdapter` has `describe` checks “describe”	Holds
	`ClientAdapter` has `projectWorkspace` checks “projectWorkspace on ClientAdapter”	Holds
backend --> harness	`SquadBackend` depends on `HarnessAdapter` Not written in the sentence: the types `SquadBackend` and `HarnessAdapter`. Striff read its words as these and checked the rule on them.	Holds
`HarnessAdapter` (`submit`, `subscribe`, `cancel`, `respondApproval`, `describe`) connects execution runtimes to the broker. 5 rules from this sentence	`HarnessAdapter` has `submit`	Holds
	`HarnessAdapter` has `subscribe`	Holds
	`HarnessAdapter` has `cancel`	Holds
	`HarnessAdapter` has `respondApproval`	Holds
	`HarnessAdapter` has `describe`	Holds
The execution plane is the experimental `HarnessAdapter` SPI in `@bradygaster/squad-sdk/backend` (`submit`, `subscribe`, `cancel`, `respondApproval`, `describe`, registered via `DefaultHarnessRegistry`). 5 rules from this sentence	`HarnessAdapter` has `submit`	Holds
	`HarnessAdapter` has `subscribe`	Holds
	`HarnessAdapter` has `cancel`	Holds
	`HarnessAdapter` has `respondApproval`	Holds
	`HarnessAdapter` has `describe`	Holds
`defineSquad()` validates every nested section through its respective builder — `defineTeam()`, `defineAgent()`, `defineRouting()`, `defineDefaults()`. 4 rules from this sentence	`defineSquad` depends on `defineTeam`	Holds
	`defineSquad` depends on `defineAgent`	Holds
	`defineSquad` depends on `defineRouting`	Holds
	`defineSquad` depends on `defineDefaults`	Holds
`SquadClientWithPool` adds capacity limits, session lifecycle management, and an `eventBus` for session and pool events.	`SquadClientWithPool` has `eventBus`	Holds
The root package exports the built-in role catalogs, `CastingEngine`, and `CastingHistory`. 2 rules from this sentence	`CastingEngine` is in `packages/squad-sdk/src` Not written in the sentence: the part of the code `packages/squad-sdk/src`. Striff read its words as this and checked the rule on it.	Holds
	`CastingHistory` is in `packages/squad-sdk/src` Not written in the sentence: the part of the code `packages/squad-sdk/src`. Striff read its words as this and checked the rule on it.	Holds
`describe()`, `projectWorkspace()` and `getCapabilities()` work locally; 3 rules from this sentence	`ClientAdapter` has a `describe` method Not written in the sentence: the type `ClientAdapter`. Striff read its words as this and checked the rule on it.	Holds
	`ClientAdapter` has a `projectWorkspace` method Not written in the sentence: the type `ClientAdapter`. Striff read its words as this and checked the rule on it.	Holds
	`ClientAdapter` has a `getCapabilities` method Not written in the sentence: the type `ClientAdapter`. Striff read its words as this and checked the rule on it.	Holds
`submit`, `subscribe`, `cancel` and `respondApproval` delegate to a bound `RuntimeBinding` and otherwise throw `AdapterUnboundError`. 4 rules from this sentence	`ClientAdapter` has `submit` Not written in the sentence: the type `ClientAdapter`. Striff read its words as this and checked the rule on it.	Holds
	`ClientAdapter` has `subscribe` Not written in the sentence: the type `ClientAdapter`. Striff read its words as this and checked the rule on it.	Holds
	`ClientAdapter` has `cancel` Not written in the sentence: the type `ClientAdapter`. Striff read its words as this and checked the rule on it.	Holds
	`ClientAdapter` has `respondApproval` Not written in the sentence: the type `ClientAdapter`. Striff read its words as this and checked the rule on it.	Holds
`createClientAdapter({ host, ctx, runtime? })` returns the spec-level `ClientAdapter` facade: `describe()`, `projectWorkspace()` and `getCapabilities()` work locally;	`createClientAdapter` depends on `ClientAdapter`	Holds
Squad ships the `SquadBackend` / `HarnessAdapter` interfaces, the local file/state-store backend, and the outbound `durable-http` client — it does not bundle a remote DurableSquad server, and server-side DurableSquad Phase 2 integration (remote durable approvals and lease-epoch coordination) is pending. 2 rules from this sentence	`SquadBackend` is a contract	Holds
	`HarnessAdapter` is a contract	Holds
`SquadBackend` exposes `negotiate`, `createConversation`, `sendMessage`, `getTranscript`, `getTurn`, `readEvents`, `getApprovals`, `respondApproval`, `cancelTurn`, `cancelRun`, and `health`. 11 rules from this sentence	`SquadBackend` has `negotiate`, `createConversation`, `sendMessage` and 8 more	Holdsall 11
`HookPipeline` intercepts tool calls at two points: before execution (`PreToolUseHook`) and after (`PostToolUseHook`). 2 rules from this sentence	`HookPipeline` depends on `PreToolUseHook`	Holds
	`HookPipeline` depends on `PostToolUseHook`	Holds
Wiring requirement: `squad_route` creates sessions via `spawnParallel`, which requires fan-out dependencies.	`spawnParallel` depends on `FanOutDependencies`	Holds
All persistent storage — sessions, state, decisions, histories — flows through a pluggable `StorageProvider` interface.	`StorageProvider` is a contract	Holds
Module resolution, Key Exports resolveSquad() , ensureSquadPath() , resolveExternalStateDir(), Purpose Find .squad/ directory externalized state location path validation 3 rules from this sentence	`resolveSquad` is exported checks “Key Exports resolveSquad()”	Holds
	`ensureSquadPath` is exported checks “ensureSquadPath()”	Holds
	`resolveExternalStateDir` is exported checks “resolveExternalStateDir()”	Holds
Module config, Key Exports loadConfig() , loadConfigSync(), Purpose Load and parse squad configuration from disk 2 rules from this sentence	`loadConfig` is exported checks “Key Exports loadConfig()”	Holds
	`loadConfigSync` is exported checks “loadConfigSync()”	Holds
Module casting, Key Exports CastingEngine, Purpose Universe selection, name allocation, persistent registry 2 rules from this sentence	`CastingEngine` is in `packages/squad-sdk/src/casting` Not written in the sentence: the part of the code `packages/squad-sdk/src/casting`. Striff read its words as this and checked the rule on it.	Holds
	`CastingEngine` is exported checks “Key Exports CastingEngine”	Holds
Module coordinator, Key Exports selectResponseTier() , getTier(), Purpose Route requests to Direct/Lightweight/Standard/Full tiers 4 rules from this sentence	`selectResponseTier` is in `packages/squad-sdk/src/coordinator` Not written in the sentence: the part of the code `packages/squad-sdk/src/coordinator`. Striff read its words as this and checked the rule on it.	Holds
	`getTier` is in `packages/squad-sdk/src/coordinator` Not written in the sentence: the part of the code `packages/squad-sdk/src/coordinator`. Striff read its words as this and checked the rule on it.	Holds
	`selectResponseTier` is exported checks “Key Exports selectResponseTier()”	Holds
	`getTier` is exported checks “getTier()”	Holds
Module runtime, Key Exports Streaming pipeline, cost tracker, telemetry, Purpose Core async execution, event streaming, i18n 4 rules from this sentence	`StreamingPipeline` is in `packages/squad-sdk/src/runtime` Not written in the sentence: the part of the code `packages/squad-sdk/src/runtime`. Striff read its words as this and checked the rule on it.	Holds
	`CostTracker` is in `packages/squad-sdk/src/runtime` Not written in the sentence: the part of the code `packages/squad-sdk/src/runtime`. Striff read its words as this and checked the rule on it.	Holds
	`StreamingPipeline` is exported checks “Key Exports Streaming pipeline”	Holds
	`CostTracker` is exported checks “cost tracker”	Holds
Module cli, Key Exports checkForUpdate() , performUpgrade(), Purpose SDK version management and update checking 4 rules from this sentence	`checkForUpdate` is in `packages/squad-cli/src/cli` Not written in the sentence: the part of the code `packages/squad-cli/src/cli`. Striff read its words as this and checked the rule on it.	Holds
	`performUpgrade` is in `packages/squad-cli/src/cli` Not written in the sentence: the part of the code `packages/squad-cli/src/cli`. Striff read its words as this and checked the rule on it.	Holds
	`checkForUpdate` is exported checks “Key Exports checkForUpdate()”	Holds
	`performUpgrade` is exported checks “performUpgrade()”	Holds

119 rules from 12 docs

See these where the change is. The browser extension puts a pull request's doc findings, and a diagram of what it changed, on the GitHub page itself, so the code and what your docs say about it are side by side.