feat: add AI agent instrumentation and developer tooling

[Copilot]

Adds comprehensive instrumentation for AI coding agents working on Compass, implementing Harness Engineering and Loop methodology patterns. Reduces context-gathering time and enables safe automated ****** through explicit interfaces, boundaries, and verification tools.

Documentation Structure

• AI-AGENT-GUIDE.md: Central reference covering architecture, patterns, common tasks, and standards
• README.md: Added "For AI Agents" quick-start section with entry points and module aliases
• CONTRIBUTING.md: AI-specific guidelines for coding standards, git workflow, and review process

AI Tooling (ai-tools/)

API Documentation Generator

yarn docs:generate
# Extracts endpoints from *routes.config.ts → ai-tools/api-documentation.md

Type Reference Extractor

// Generates documentation from all TypeScript types, interfaces, and Zod schemas
yarn ts-node ai-tools/extract-types.ts

Code Health Auditor

yarn audit:code-health
# Reports complexity, test coverage gaps, import issues, file size

Workflow Examples
Harness and Loop-style patterns demonstrating incremental, test-driven changes with safety nets.

Enhanced Code Documentation

JSDoc added to key interfaces:

/**
 * GET /api/event
 * Retrieves all events for the authenticated user
 * 
 * POST /api/event
 * Creates a new calendar event
 * 
 * @auth Required - Supertokens session
 * @auth Required for POST - Google Calendar connection
 * @throws {401} Unauthorized - Invalid session
 * @throws {403} Forbidden - No Google Calendar connection (POST)
 */

Package Scripts

• yarn type-check: TypeScript validation across monorepo
• yarn ai:index: Run all documentation generators
• yarn audit:code-health: Code quality metrics

Architecture Documentation

Explicit mapping of:

• Module aliases (@compass/*, @web/*, @core/*)
• State management boundaries (Redux store structure)
• API authentication patterns (Supertokens, Google OAuth)
• Testing conventions (semantic queries, user-event patterns)
• Validation patterns (Zod schemas with type inference)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Instrument, Document, and Tool Compass for AI Coding Agents</issue_title>
<issue_description>### 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.</issue_description>

<agent_instructions>Create one PR that addressess all the subissues. Test your work and be creative in your ability to make this simple and efficient</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes Instrument, Document, and Tool Compass for AI Coding Agents #1485

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.