Skip to content

README.md

Latest commit

 

History

History
74 lines (57 loc) · 2.76 KB

README.md

File metadata and controls

74 lines (57 loc) · 2.76 KB

AgentProbe

AgentProbe is an agent-first repository for a Bun + TypeScript CLI that runs repeatable evaluations against HTTP, WebSocket, and local harness endpoints. The implementation, tests, and repo workflows are Bun-first and TypeScript-only.

Why this repo is structured this way

  • Humans steer by describing intent, reviewing outcomes, and tightening rules.
  • Agents execute against repository-local context, not tribal knowledge.
  • AGENTS.md is the router, not the manual.
  • docs/ is the source of truth for architecture, plans, product specs, reliability rules, and quality standards.
  • Mechanical checks keep the knowledge base fresh enough for future agent runs.

Bun-first repo workflows

Use Bun entrypoints for the repository workflow:

# Validate docs, links, indexes, and generated artifacts
bun run docs:validate

# Refresh generated documentation surfaces
bun run docs:index
bun run docs:workspace
bun run docs:quality

# Run the Bun-owned tests
bun run test
bun run test:e2e

# Run the repo-wide PR loop
bun run fast-feedback

# Run the local CI-equivalent gate
bun run ci

Docs map

  • docs/README.md: best starting point for the knowledge base
  • docs/ARCHITECTURE.md: layered domain architecture and dependency rules
  • docs/DESIGN.md: agent-first principles and repository legibility standards
  • docs/PRODUCT_SENSE.md: product goals, CLI UX priorities, and scope
  • docs/RELIABILITY.md: logging, metrics, traces, and latency budgets
  • docs/SECURITY.md: boundary validation, secret handling, and SDK rules
  • docs/product-specs/platform.md: canonical product behavior contract
  • docs/PLANS.md: how active plans, completed plans, and debt are managed

Engineering contract

  • Bun + TypeScript is the canonical runtime contract.
  • The target quality gate stack is strict tsc --noEmit, Biome, repo-specific structural checks, and deterministic test evidence.
  • External systems must be accessed through typed SDK/provider interfaces.
  • Boundary parsing is required for YAML, config, network payloads, and SDK responses. No unchecked any, no guessed shapes.
  • UTF-8 is the default for committed text files and explicit "utf8" is required in Bun/Node text I/O.
  • Structured logs, metrics, and spans are required on critical paths so agents can debug failures and enforce response-time budgets.

Product priorities

  • Fast validation loops for suite authors and agent developers

  • Repeatable evaluation runs with inspectable artifacts

  • Clear run/report output that supports automated diagnosis

  • Strong separation between CLI orchestration, domain logic, persistence, and external endpoint integrations

  • data/: sample endpoint, scenario, persona, and rubric YAML

  • tests/: test suite

  • agentprobe-spec-v0.2.md: working spec/reference document