AI Agents in Soli Projects

soli new scaffolds a project that's ready for AI coding agents (Claude Code, Cursor, Aider, Copilot CLI, Codex CLI) from the first commit. This page describes what ships and how to use it.

What you get

Every fresh soli new myapp project includes:

Path	Purpose
CLAUDE.md	Root agent guide — verification loop, footgun cheatsheet, recipes
AGENTS.md	Tool-agnostic stub pointing other agents to `CLAUDE.md`
app/controllers/CLAUDE.md	Controller-specific rules: auto-loaded models, named route helpers, mass-assignment
app/models/CLAUDE.md	Model rules: don't override CRUD; safe `where` / `@sdbql{}` forms
app/views/CLAUDE.md	Escaping, locals, helpers, indent
app/middleware/CLAUDE.md	Shape and directive comments
tests/CLAUDE.md	BDD DSL, controller HTTP client, coverage gate
db/migrations/CLAUDE.md	Migration naming and `up`/`down` requirements
.claude/settings.json	Permissions allowlist for safe `soli` subcommands
.claude/commands/soli-verify.md	`/soli-verify` — lint + test + coverage
.claude/commands/soli-test.md	`/soli-test [path]` — one spec or full suite
.claude/commands/soli-resource.md	`/soli-resource <name>` — full RESTful resource

The per-directory CLAUDE.md files are picked up automatically by Claude Code as the agent works in that directory; you don't need to import them. Other agents read the root CLAUDE.md (and AGENTS.md as a fallback).

The verification loop

Every agent working in a Soli project should run, before reporting a task complete:

Terminal

$ soli lint <files-you-changed>
$ soli test tests/<the-relevant-spec>.sl
$ soli test --coverage --coverage-min 90
$ soli serve . --dev   # if a UI/route changed, hit it in a browser

The /soli-verify slash command bundles soli lint + soli test --coverage --coverage-min 90. If any step fails, the rule is to fix the root cause — never weaken assertions, lower the coverage gate, or skip hooks.

Slash commands

Command	What it does
/soli-verify	Full pre-merge check (lint + test with coverage gate)
/soli-test [path\|all]	One spec for fast feedback, or the full suite with coverage
/soli-resource <singular>	Scaffolds model + migration + controller + views + route + spec

/soli-resource post runs soli generate model post, soli generate migration create_posts, soli generate controller posts, adds resources("posts") to config/routes.sl, and stubs the views and spec. It pauses after step 4 so you can fill in fields and validations on the model before continuing.

Permissions

.claude/settings.json pre-allows the safe, read-only-or-sandboxed soli subcommands an agent uses constantly: soli lint, soli test, soli serve, soli generate, soli db:migrate, soli run. This removes the per-prompt approval tax without granting blanket access. Destructive things (git push, package mutations, anything outside the project) are deliberately left to require explicit approval.

Migrating an existing project

To bring an older Soli project up to the new layout:

Run soli new tmp-agent-kit in a scratch directory.
Copy AGENTS.md, every per-directory CLAUDE.md, and the .claude/ folder into your project, preserving paths.
Merge the new "For AI agents — read this first", "Footgun cheatsheet", and "Recipes" sections from tmp-agent-kit/CLAUDE.md into the top of your existing CLAUDE.md.
Delete tmp-agent-kit/.
Run /soli-verify to confirm nothing regresses.

Customizing

The shipped files are starting points — edit them to fit project conventions. Common additions:

Project-specific recipes in the root CLAUDE.md (e.g. "deploy: run bin/deploy.sh").
Stop hook in .claude/settings.local.json (not the shipped settings.json) to auto-run soli lint after the agent stops editing.
Extra slash commands under .claude/commands/ — anything reusable enough to deserve a shortcut.

Don't store secrets or environment-specific paths in the shipped .claude/settings.json — that file is committed. Use .claude/settings.local.json (gitignored) for per-machine overrides.