Fimo agent templates: the parts and how they connect

Read the map from top to bottom. The top layer says who the agent is and when it works. The middle layer says how it works. The bottom layer is what the API owns at runtime: the database copy, the turn, and the tools.

The gallery is the odd one out. It is a separate, hand-written description of the same agents for the dev-only /components/agents page. It does not feed the product.

All five agents live in one array, CHAT_TEMPLATES, in templates.ts. A template has no logic. The description is the site stance: what the agent watches and what it never does without a person. Each routine is one sentence of task plus a cron. The routine never explains the method; it names the skill to load.

createdWithProject splits the agents in two groups. SEO and GEO start with every new project, routines on. Content, Quality and Compliance open only from the Chats “+” menu, so a project pays for no run it did not ask for.

Studio reads the template list to fill the “+” menu and the empty-agent starter prompts. To open an agent, Studio posts a chat create with only template. The DTO forbids kind, title and description beside it: the template brings them. Both calls return nothing when the organization does not have the agents feature.

After that, every routine call (list, edit, pause, run now) works on the database rows. No API call reads the template again for an existing agent.

openTemplateChat runs one transaction. It inserts the agent chat with the template's title, description and portrait, and records template = 'seo'. A unique index on (project_id, template) keeps one agent per template per project. Only when the insert really created the row does it insert the routines, each with its own run thread, and the empty memory files.

The routine row stores instructions “verbatim, each time the routine runs”. The row has no link back to the template routine it came from: no template key and no revision.

The minute sweep claims a due routine and starts a turn in its run thread. The turn builds a stable system prompt. The <agent> block holds the name, the description and the routine ids. The routine message holds the copied instructions. A reminder adds only what changes, such as a failing streak.

The model then calls skillLoad fimo-seo. This reads the skill from the running API build, so it is always current. Reading a topic reference with the session id writes site.mjs into the sandbox. The crawl and the topic check are code. The model ranks, fixes, and reports at most once.

A Studio skill is a VirtualSkill object, built into the API like the chat-UI skill, so it works on every project whatever its CLI version. skills/index.ts registers all six in one source called fimo-studio. The main document holds the stance-free method. Each routine topic is a separate reference, read only when needed.

site-crawl/ is the shared home. siteCrawlSteps(skill, topics) writes the same crawl instructions into four skills. SITE_RULES says what a run may change alone. SITE_DATA (new in this PR) says when to use Search Console and when to pay for data. The script itself does the crawl and the checks deterministically.

The model sees three tools: dataSearch to browse groups, dataDescribe to read one operation, and dataCall to run it. The catalog is generated by generate-data-catalog.mjs and lists only reviewed operations. This PR adds 24 DataForSEO operations, blocks two broken providers, and keeps the flat per-call fee in prices.

The data layer knows nothing about SEO. The skill text (SITE_DATA and each topic reference) names which operation a topic uses. That is the right direction: domain knowledge stays in the skill, transport stays in the catalog.

catalog.ts feeds the dev-only /components/agents page. It lists shipped and proposed routines with fields the template does not have: triggers, what a routine fixes alone, what it asks first, cost, outside data and price chips. A test keeps one thing aligned: every template routine is listed as Available, and nothing else is.

Everything else is free text that can drift from the template and the skill. This PR changed 140 lines here to follow the template and skill changes.

The copy is the only path from template to database, and it runs only when the agent chat is first created. No reconciler, migration, or template revision exists. The one manual way out is the staff ops command, where a person types each missing routine into a spec, project by project. Every later template edit therefore splits projects in two populations, and a new deploy cannot fix the old one.

The skill makes this worse, not better. It moves forward on every deploy, so an old routine instruction can point at a skill topic that has changed or does not exist yet. This PR shows the problem: its four new routines appear only for projects that open SEO, GEO or Content after the deploy. SEO and GEO are created with every project, so most existing projects already have them and never receive the new routines.

The routine “Technical SEO” says “check the technical basics”. The skill has a reference keyed technical, and its crawl steps list the topics as one string. The model must map one to the other. Nothing typed connects them, so a renamed topic or a new routine with no reference compiles and passes tests.

A comment in templates.ts states the rule “one routine per topic of the skill”. The code does not enforce it.

To add one SEO routine today you edit the template array, the SEO skill reference, the topic string in the crawl steps, and the gallery catalog. The E2E template list may also need an edit. None of these edits is wrong alone. Together they make the agent hard to see as one unit.

Co-locate each agent: identity, routines and skill in one folder. Give each routine a stable key and a typed topic. Then let the database row point to the template routine instead of copying its text. The turn reads the instructions from code unless a person overrode them. Fimo improvements then reach every project on deploy, like skills already do. User edits are kept because an override is explicit.

This is a proposal, not code in the PR. The folder below does not exist yet.

After the target lands, these become deletable: the comment-only “one routine per topic” rule, the topic list passed as a string to siteCrawlSteps, most of catalog.ts (only proposal-only rows remain), and the copy-semantics comments in templates.ts and openTemplateChat. The verbatim copy in templateRoutineValues shrinks to a key.

This recap is source inspection of the PR head. It does not measure how many existing projects already miss the new routines.