Skip to content
Agent Detective

Golden rules (humans & agents)

Golden rules (humans & agents)

Section titled “Golden rules (humans & agents)”

These rules keep the monorepo buildable, type-safe, and easy for agents to navigate. AGENTS.md at the repo root stays short — this file is the expanded checklist.

Do

Section titled “Do”

Do not

Section titled “Do not”

Plugin HTTP and loading

Section titled “Plugin HTTP and loading”
  • Routes are auto-prefixed with /plugins/{sanitized-name}; register plugins with relative paths via defineRoute() + registerRoutes(scope, ...) on the Fastify scope passed to register.
  • Use dependsOn so services load before dependents.
  • Plugin uses schemaVersion: '1.0' and register(scope: FastifyInstance, context: PluginContext) — see Plugins guide, ADR 0001: layering and plugin boundaries, and ADR 0002: HTTP framework.
Plugin nameHTTP prefix
@agent-detective/jira-adapter/plugins/agent-detective-jira-adapter
@agent-detective/linear-adapter/plugins/agent-detective-linear-adapter
my-plugin/plugins/my-plugin

Example: dependsOn

Section titled “Example: dependsOn”
{
  name: '@agent-detective/my-adapter',
  dependsOn: ['@agent-detective/local-repos-plugin'],
  register(app, context) {
    const localReposService = context.getService<LocalReposService>(
      '@agent-detective/local-repos-plugin',
    );
    // localReposService.localRepos, localReposService.buildRepoContext
  },
}

Types reference

Section titled “Types reference”

Full definitions: packages/types/src/index.ts. Shapes you touch most often:

  • Plugin — name, version, schemaVersion: '1.0', optional schema, dependsOn, register(app, context) (may return controller objects for OpenAPI).
  • PluginContext — agentRunner, enqueue, config, logger, controllers, events, registerService / getService, agents and capabilities, registerTaskQueue, onShutdown.
  • TaskEvent — source, type, payload, optional timestamp.

Common failures

Section titled “Common failures”
Section titled “Where to read next”