Skip to content
Agent Detective

Agent harness — runbook

Agent harness — runbook

Section titled “Agent harness — runbook”

This page is for humans steering and agents executing: how to boot the app, verify changes, and find signals when something breaks. Keep long prose in docs/; keep AGENTS.md as a short index.

Quick verify (from repo root)

Section titled “Quick verify (from repo root)”

  1. Install dependencies and build workspace packages:

    Terminal window
    pnpm install
    pnpm run build

  2. Run type checking and linting:

    Terminal window
    pnpm run typecheck
    pnpm run lint

  3. Run the full test suite:

    Terminal window
    pnpm test

After config or plugin option schema edits, regenerate and check drift:

Regenerate generated docs
pnpm docs:config
pnpm docs:plugins
# CI equivalents:
pnpm run docs:config:check
pnpm run docs:plugins:check

Run the server

Section titled “Run the server”
Terminal window
pnpm run dev

Uses tsx watch mode — restarts on file changes.

Default config: config/default.json; overrides: config/local.json (deep merge). See Configuration hub.

Plugin / integration smoke

Section titled “Plugin / integration smoke”
  • Jira webhook smoke (server on PORT): agent-detective smoke (npm) or pnpm run jira:webhook-smoke (monorepo)
  • CI webhook E2E (temp config, mock agent, mock Jira — no real OpenCode/Cursor): pnpm run ci:webhook-smoke (also runs in the build CI job after build:app)
  • Manual Jira E2E (tunnel, labels): e2e/jira-manual-e2e.md

Set AGENT_DETECTIVE_MOCK_AGENT=1 (or true / yes) to skip the real agent subprocess; the runner returns a fixed mock analysis string. Used by scripts/ci-webhook-smoke.mjs so CI can POST a Jira fixture and assert [MOCK] Added comment in logs without installing OpenCode or Cursor.

Logs and observability

Section titled “Logs and observability”
  • Tune level via observability in config or env (see Observability).
  • Request logging excludes paths such as /api/health and /api/metrics — adjust in config if you add new high-chatter routes.

Worktrees and agents

Section titled “Worktrees and agents”
  • Use a clean worktree per task when possible; run pnpm install if dependencies changed.
  • Prefer absolute paths in config/local.json for repo entries so worktrees do not depend on cwd.

Parallel runs (PORT)

Section titled “Parallel runs (PORT)”
Run on a custom port
PORT=3001 pnpm run dev

Then hit health on that port (see below).

Quick HTTP checks

Section titled “Quick HTTP checks”

With the server listening (dev or pnpm start after build:app):

Health check
curl -sf "http://127.0.0.1:${PORT:-3001}/api/health"
curl -sf "http://127.0.0.1:${PORT:-3001}/api/metrics" | head

Adjust the path if your deployment uses a different base URL. High-chatter routes may be excluded from request logs; use structured logs for deep debugging — see Observability.

Plans and acceptance criteria

Section titled “Plans and acceptance criteria”
  • Architecture decisions: docs/architecture/adr/ — link new behavior-changing work to an ADR when appropriate.
  • Large multi-step work: add markdown under docs/exec-plans/active/ (and docs/exec-plans/README.md as an index when you introduce that folder); move to docs/exec-plans/completed/ when done so intent lives in git, not only in chat.

Site and docs builds

Section titled “Site and docs builds”
Documentation site commands
pnpm run docs:site:sync    # mirror docs/ → Starlight content
pnpm run docs:site:dev     # Starlight dev
pnpm run docs:site:landing # docs + landing for same artifact as GitHub Pages

Starlight home apps/docs/src/content/docs/index.mdx is not overwritten by sync — see apps/docs/README.md.

Mechanical guards (lint)

Section titled “Mechanical guards (lint)”

pnpm run lint includes:

  • scripts/check-package-root-imports.mjs — fails if packages/*/src/** reaches root src/ via a relative import.
  • scripts/check-plugin-cross-imports.mjs — fails if one plugin package compile-imports another (ADR 0001); use @agent-detective/types and getService().
  • scripts/check-docs-internal-links.mjs — fails on broken relative links from docs/**/*.md into the repo.
Section titled “Related”