Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

AI Agents

View as Markdownllms.txt

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.

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) › Yes

What 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
# 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).

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.

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.

Inspect commands accept --json, so an agent can read your app’s structure exactly instead of scraping a table:

Terminal window
node strut route:list --json
node strut about --json
node strut model:show Post

What 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.

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.

Terminal window
node strut install:agent-tools

It adds:

  • managed blocks in AGENTS.md (and CLAUDE.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.

Agents run commands with your permissions. A few rules keep that safe:

  1. Never give an agent production secrets. Keep .env.production and production database credentials out of the project folder the agent can read. .env is git-ignored for a reason.
  2. Review migrations before running them. node strut migrate --pretend prints the SQL. A migration that drops a column drops data.
  3. Check policies. If an agent adds an endpoint, read its policy: deny by default only helps if nobody opens everything with return true.
  4. Keep tests green. Ask the agent to run npm test and fix failures, and don’t accept “I skipped the failing test”.
  5. 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 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.

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.

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.

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.