AI

Agentic Coding

Caspian is compatible with agentic coding when the agent follows the feature gate, checks the correct ownership layer, and validates behavior before assuming a doc or example is authoritative.

Feature gate first

Agents should read caspian.config.json before assuming Prisma, MCP, TypeScript, Tailwind, or other optional features exist.

Own the right layer

App code decides current project behavior. Packaged docs help the agent discover the right file, but they do not override the running app.

Validate after edits

The agent should run the narrowest available validation after touching a route, helper, or runtime-facing surface.

Decision Order

  1. Read caspian.config.json to confirm which optional features are enabled.
  2. Read the app-owned files that currently control behavior: main.py, src/app/**, src/lib/**, public/js/**, and prisma/**.
  3. Use .github/copilot-instructions.md and AGENTS.md for workspace rules and AI routing.
  4. Use the packaged docs in node_modules/caspian-utils/dist/docs for feature discovery and ownership lookup.
  5. Only after that should the agent step into installed framework internals under .venv/Lib/site-packages/casp/**.

Compatibility Rules

What makes this agent-friendly

  • The project ships explicit instructions for coding agents.
  • The packaged docs expose runtime maps and validation checklists.
  • The route system is local and file-based, which keeps edits grounded.
  • The app keeps clear boundaries between route code, shared libs, and runtime internals.

What the agent must avoid

  • Do not assume a feature is enabled just because a packaged doc exists.
  • Do not edit installed framework files when the fix belongs in app code.
  • Do not treat old examples as stronger than the current workspace rules.
  • Do not skip validation after changing the docs route or runtime-facing code.

Practical Workflow

For a normal task, the agent should start from the most local file or failing behavior it can identify, read only enough surrounding context to form a testable hypothesis, make the smallest grounded change, then run the narrowest relevant validation.

This matches the repo rules already defined in AGENTS.md and .github/copilot-instructions.md. The docs route should reinforce that same workflow instead of teaching a separate process.