Agentic Coding
Caspian gives coding agents explicit feature gates, ownership layers, runtime maps, and validation commands for grounded implementation work.
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
- Read
caspian.config.jsonto confirm which optional features are enabled. - Read the app-owned files that currently control behavior:
main.py,src/app/**,src/lib/**,public/js/**, andprisma/**. - Use
.github/copilot-instructions.mdandAGENTS.mdfor workspace rules and AI routing. - Use the packaged docs in
node_modules/caspian-utils/dist/docsfor feature discovery and ownership lookup. - Only after that should the agent step into installed framework internals under
.venv/Lib/site-packages/casp/**.
Runtime Alignment
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.
- Use current workspace contracts and the installed runtime for implementation decisions.
- 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.
“Run the narrowest relevant validation” has two halves here.
npm run check
covers the Python side. For anything that renders, the agent has a real
feedback signal too:
npm run logs
reports what each route actually did in the browser, read from
.casp/browser-log.jsonl.
That file exists precisely because the developer usually owns the
npm run dev
terminal, so its output is invisible to an agent session — and
spawning a second dev server to get one would orphan the tab the
developer is looking at. Without it, a template error is silent and the
agent has no way to know its change broke the page.
Two rules when acting on that log
-
Read the digest, not the raw JSONL. The file is history and can hold
errors resolved minutes ago;
npm run logsderives current status. - A route absent from the listing was never opened. That is no signal, not a pass — do not report the front end healthy on the strength of an empty line.