AI Agents
An AI coding agent is an assistant that reads your project and writes or changes code for you: Claude Code, Cursor, GitHub Copilot, OpenAI Codex and others. Agents do their best work when a project is predictable: one place for each kind of file, one command per task, clear errors. Strutvane is built that way, and adds a few things just for agents: an AGENTS.md playbook, docs in plain Markdown, --json output from inspect commands, and an error page you can copy as Markdown.
This page is about agents that help you build the app. Letting agents use your running app (an MCP server) and adding AI features inside your app are covered at the end.
The smallest example
Section titled “The smallest example”Answer yes when the installer asks “Set up AI coding assistants?” (it’s the default):
? Set up AI coding assistants? (AGENTS.md, skills, local docs MCP) › YesWhat you’ll see: an AGENTS.md at the root of your project. Agents that support the convention (most do) read it before they touch your code:
# AGENTS.md
This is a Strutvane app (TypeScript, MVC, npm only). Read this before changing code.
- Run project commands with `node strut <command>` (`node strut list` lists them). Never use pnpm or yarn.- Columns live in migrations (`database/migrations`). Add a column with a new migration, then `node strut migrate`.- Controllers: `app/http/controllers`. Models: `app/models`. Policies: `app/policies` (deny by default).- Routes: `routes/web.ts` (pages) and `routes/api.ts` (served under /api).- Settings come from `.env` (never commit it). `.env.example` lists every key without secrets.- Docker mode: every `node strut` command runs inside the app container (`node strut services:up` / `services:down`).- Before you finish: `npm test`.The Docker line reads “Runs on this computer (no Docker)” when you chose no Docker, followed by your database. It’s your file: add your team’s rules (naming, what never to change, how to run a single test).
Why Strutvane is easy for agents
Section titled “Why Strutvane is easy for agents”| Convention | Why it helps an agent |
|---|---|
| Columns only in migrations | one place to add a field; types, API, validation and screens follow from node strut migrate |
node strut make:* generators |
the agent runs a command instead of guessing a file’s shape |
Generated, committed .strutvane/ |
model types the agent can read without a database |
| Typed routes and config | a wrong route name or config key is a compile error the agent sees immediately |
| Deny by default | a new endpoint an agent adds is closed until a policy opens it |
| One error shape with stable codes | the agent can branch on code, and every code has a docs page |
npm test |
one command to check its work |
A good first prompt:
Read AGENTS.md. Add a "featured" boolean to posts (default false) with a migration,let admins set it, and show featured posts first. Run the tests before you finish.Docs agents can read
Section titled “Docs agents can read”Every page of this site has, at the top right:
- Copy as Markdown: the page as clean Markdown on your clipboard, to paste into a chat;
- View as Markdown: the same at
…/<page>.md, for agents that fetch URLs.
And each version publishes:
| URL | What it is |
|---|---|
/docs/0.2.x/llms.txt |
an index of every page, with links to the Markdown versions |
/docs/0.2.x/llms-full.txt |
every page of the version in one Markdown file |
Point your agent at the version you use (0.2.x), so it doesn’t read docs for another version.
Commands with JSON output
Section titled “Commands with JSON output”Inspect commands accept --json, so an agent can read your app’s structure exactly instead of scraping a table:
node strut route:list --jsonnode strut about --jsonnode strut model:show PostWhat you’ll see for route:list --json (shortened; the exact uri and action formats are the prototype’s and may change):
[ { "method": "GET|HEAD", "uri": "/api/posts", "name": "posts.index", "action": "PostController@index", "middleware": "api, auth:optional" }, { "method": "POST", "uri": "/api/posts", "name": "posts.store", "action": "PostController@store", "middleware": "api, auth" }]about --json never includes secrets (keys, passwords, tokens), so it’s safe to paste into a chat.
Errors you can paste
Section titled “Errors you can paste”In local development, the error page has a Copy as Markdown for AI button. It copies the exception, the exact line of your code with a few lines around it, the request (method, path, redacted headers and query) and the stack frames from your own files, as Markdown. Credentials are redacted and the request body is never included. Paste it into your agent and ask “fix this”.
API errors in development carry a hint (for example which policy method denied a request), which agents read as well as you do.
The agent-tools package (coming in 0.3)
Section titled “The agent-tools package (coming in 0.3)”node strut install:agent-toolsIt adds:
- managed blocks in
AGENTS.md(andCLAUDE.md), kept up to date with the packages you install, without touching your own lines; - skills contributed by every installed package (how to add a policy, a migration, a queue job…), in
.ai/rules/; - a local MCP dev server (MCP, the Model Context Protocol, is how agents call tools), configured in a git-ignored
.mcp.json. Its tools let the agent list routes, read the schema, search these docs offline, and query the database read-only: inside a transaction that’s always rolled back, under the current team, with secrets redacted.
It’s a development tool: it never runs in production.
Keeping agents safe
Section titled “Keeping agents safe”Agents run commands with your permissions. A few rules keep that safe:
- Never give an agent production secrets. Keep
.env.productionand production database credentials out of the project folder the agent can read..envis git-ignored for a reason. - Review migrations before running them.
node strut migrate --pretendprints the SQL. A migration that drops a column drops data. - Check policies. If an agent adds an endpoint, read its policy: deny by default only helps if nobody opens everything with
return true. - Keep tests green. Ask the agent to run
npm testand fix failures, and don’t accept “I skipped the failing test”. - Treat pasted content as data. Text in an issue, an email or a web page that tells your agent to do something isn’t an instruction from you.
Agents using your app: MCP server (later)
Section titled “Agents using your app: MCP server (later)”AI features in your app (later)
Section titled “AI features in your app (later)”With Docker or without Docker
Section titled “With Docker or without Docker”Agents run on your computer, so in Docker mode they type node strut … like you do, and it’s forwarded into the container. Tell the agent not to run npm install on the host in Docker mode (node strut npm install … runs it in the container); the generated AGENTS.md mentions Docker mode for that reason.
Common mistakes
Section titled “Common mistakes”My agent keeps running pnpm install
Section titled “My agent keeps running pnpm install”Why: it guessed from habit.
Fix: AGENTS.md says “npm only”; check the file exists at the project root, and repeat the rule in your prompt.
The agent adds columns to the model file
Section titled “The agent adds columns to the model file”Why: in many frameworks the model is the source of truth. In Strutvane, columns live only in migrations.
Fix: point it at the rule in AGENTS.md, or ask for node strut make:migration add_featured_to_posts_table.
The agent’s answers are about another version
Section titled “The agent’s answers are about another version”Why: it read docs for latest or an older line.
Fix: give it the versioned URL: /docs/0.2.x/llms.txt.
The agent pasted my .env into a chat
Section titled “The agent pasted my .env into a chat”Why: it was asked to “debug the config” and read every file it could.
Fix: rotate every secret in that file (node strut key:rotate for APP_KEY), and share node strut about --json instead, which leaves secrets out.
Next steps
Section titled “Next steps”- Installation: question 24 and the other installer questions.
- CLI Reference: every
node strutcommand. - Error Handling: the error page and problem codes.
- agent-tools: the package page.