Skip to content

AGENTS.md

Latest commit

 

History

History
38 lines (27 loc) · 1.63 KB

AGENTS.md

File metadata and controls

38 lines (27 loc) · 1.63 KB

Capstan Agent Guide

Capstan is an agent-first project. This repository should stay easy for coding agents to read, modify, verify, and operate.

Working Rules

  • Prefer one obvious implementation path over flexible but ambiguous patterns.
  • Keep files and folders predictable. Repo structure is part of the product.
  • Make machine-readable contracts explicit instead of hiding behavior in prose.
  • Favor deterministic flows over clever implicit behavior.
  • Add documentation whenever a new core concept is introduced.
  • Keep naming stable. Renames should be rare and intentional.

Design Lens

When adding or changing a feature, ask:

  1. How does an agent discover this?
  2. How does an agent execute this?
  3. How does an agent verify success or failure?
  4. How does an agent recover or retry?
  5. How does a human supervise or override it?

Architecture Highlights

  • Streaming SSR — renderToReadableStream (React 18) via renderPageStream() in @zauso-ai/capstan-react. Falls back to string-based renderPage().
  • Module caching — dev server caches imported modules by mtime + generation counter; only re-evaluates on actual file changes.
  • Parallel layout loading — all _layout.tsx files in a route's hierarchy are loaded concurrently via Promise.all().
  • Multi-protocol — every defineAPI() simultaneously exposes HTTP, MCP, A2A, and OpenAPI interfaces.

Source Of Truth

  • CLAUDE.md — contributor guide, package map, build/test commands
  • README.md — user-facing documentation
  • Scaffolded AGENTS.md — generated by create-capstan-app for each project

Keep these documents aligned as the project evolves.