Instrument, Document, and Tool Compass for AI Coding Agents

[tyler-dane]

Feature Description

Introduce comprehensive instrumentation and developer tooling specifically for AI coding agents working on Compass. This includes adding and documenting standard interfaces, code annotations, and tailored README sections that clarify API boundaries, stateful logic entry points, and file structure. Add scripts for type checking, code health audits, and semantic code search helpers. Where applicable, include code comments and doc blocks for AI-readability. Propose a CONTRIBUTING.md update with AI agent-specific onboarding guidelines and clarify common coding/routing conventions. Opportunity to add a dedicated directory (e.g., agents/, ai-tools/) for generic agent scripts, test harnesses, and reference implementations. Ensure usage of OpenAI's Harness-style engineering methods where feasible.

Use Case

Giving AI agents explicit instruments and developer docs decreases ambiguity, reduces context gathering time, and speeds up safe automation. This enables scalable AI-assisted code reviews, bug fixes, and feature development, lowering onboarding barriers and making Compass a model repo for AI-first engineering teams.

Additional Context

Reference:

• OpenAI Harness Engineering: https://openai.com/index/harness-engineering/
• Loop: https://ghuntley.com/loop/

Implementation to include:

1. Add a dedicated section in the README explaining interfaces, boundaries, key flows, and directory purpose.
2. Create or extend docblocks and type annotations for AI comprehension in common, util, hooks, backend, and web layers.
3. Update CONTRIBUTING.md with agent usage best practices and AI-specific process guidelines (coding standards, review rules, semantic commit examples).
4. Introduce scripts/checks for linting, type validation, search/indexing, and endpoint/documentation extraction.
5. Set up an agents/ directory for generic scripts, harnesses, test stubs, and example agent workflows.
6. Add example PRs or diffs demonstrating Harness and Loop-style changes.

This work will ensure Compass is a well-documented, AI-ready codebase with tooling that supports automated development and review.