{"slug": "trama-see-your-agent-s-changes-as-state-machines-before-any-code", "title": "Trama – See your agent's changes as state machines before any code", "summary": "Trama, a tool from developer Nicchia Code, lets an AI coding agent write a plain-text state-machine map of an application that Trama renders as an always-current diagram before any code is written. In its shop example, adding returns generated nine agent questions, a Proposal showing new parts in blue and removed parts in red, and nine Tasks, with any mismatch between code and map flagged as a Drift that blocks further agent work on that part of the app until the user decides. Trama's stated trade-off is that every feature takes more steps than raw vibe coding, spending that time on decisions made before building.", "body_md": "**T** asks · **R** equirements · **A** nalysis · **M** ap · **A** gents\n\n**Your AI agent writes code fast. Trama makes sure it's the code you meant.**\n\nWhen an agent writes most of the code, it's easy to lose track of what your software actually does. Every prompt adds behaviour nobody looked at.\n\nTrama gives you and your agent a shared **map of your app**: every situation it can be in, and what moves it from one to the next. The agent writes the map as plain text, and Trama draws the diagram from it, automatically and always up to date. You never drag a box or draw an arrow. The agent reads the map before it writes a line.\n\nLet's add returns to a small online shop: the [shop example](https://github.com/nicchia-code/trama/blob/main/examples/shop) that comes with Trama.\n\nWrite it the way you'd tell a colleague. One line is enough, or take a whole page. Send it from the tab's menu; closing the tab sends it too.\n\nYour agent picks it up right away, in the chat or terminal you already use, and starts reading the map.\n\nThe agent asks only what it can't decide alone. For returns it had nine questions, starting with how a delivery should be modelled, since the 14 days start from it. Each one comes with the agent's recommendation already selected, so most of the time you just confirm. Skip the ones you don't care about: the agent uses its recommendation and lists it as an assumption for you to check.\n\nWhen the agent is done, pick its Proposal on the map: new parts in blue, removed parts in red. Here, returns bring in a new Actor, time, which closes the return window. The side panel sums up every decision and every assumption.\n\nOn the board, the Proposal lists every file it touches. Approve it, or reject it with a note.\n\nApprove, and the agent checks what changed against the code, one sub-agent per Machine, in parallel.\n\nTasks appear on the board as the agent prepares them.\n\nThe returns design became nine Tasks, grouped under it.\n\nClick **Run this design**, and the agent works through them while you follow along.\n\nWhen the code does something the map doesn't say, or breaks one of your rules, Trama calls it a **Drift**.\n\nA Drift is not a bug report. It only says that the code and the map no longer tell the same story, and it doesn't decide which one is right:\n\n- **The code may be wrong.** The agent misread a Task, or a quick hand fix skipped a case: a bug.\n- **The map may be out of date.** You changed your mind while coding, or the code handles a case nobody thought to draw: the code is right, and the map should catch up.\n- **Both may be reasonable.** Two valid answers to a question the map never asked: it's a decision only you can make.\n\nSmall details that change neither the diagram nor one of your rules aren't Drifts: Trama raises one only when the behaviour itself differs.\n\nEach Drift shows what happens, what should happen, and two to five ways to fix the code, with the agent's recommendation first. You pick one. Or you keep the code as it is, and the map is updated to match. Until you decide, the agent won't start any Task about that part of the app, so nothing new gets built on shaky ground.\n\nTech stack, design, data, business rules: write them once, next to the map, and the agent follows them on every task.\n\nRules grow with the map. The returns design added its own: the window ends at 23:59 on the 14th day after delivery, a return covers the whole order, and the refund is the full total. Each rule is tied to the exact part of the map it applies to, like `order/Delivered`.\n\nTrama is still vibe coding: you describe what you want, and the agent writes the code. What changes is what happens in between.\n\nWith raw vibe coding, you type a prompt and code appears. With Trama, you answer questions, look at the change on the map, approve it, and only then does the agent write code. Every feature takes more steps, and you'll feel it.\n\nThat time isn't lost. It's spent where it's cheapest:\n\n- **Deciding before building.** A question answered now is cheaper than a feature rebuilt later. Changing a line on the map takes a second; ripping out code that went the wrong way takes an afternoon.\n- **Never explaining twice.** The map and your rules stay in the repo. Every new session, every agent, every teammate starts from what's already decided, not from an empty chat.\n- **Catching mistakes while they're small.** A Drift flags code that went off the map as soon as it's scanned, before more features get piled on top of it.\n- **Letting agents work in parallel.** Because every Task is tied to a clear part of the map, several agents can build at once without stepping on each other.\n\nThe first feature is slower. The fiftieth isn't, because the app is still one you understand.\n\nIf you're hacking a weekend prototype you'll throw away on Monday, raw vibe coding is fine. Trama is for software you mean to keep.\n\nPoint Trama at your existing code. The agent draws the map of what your app does today, and flags anything that looks wrong along the way.\n\n*Trama* is Italian for the **weft**: the thread a weaver passes back and forth through the loom until a pattern appears. Once the cloth is woven, the pattern holds. You can't change it by tugging at a single thread: a stray pull shows at once, and a new pattern has to be woven on purpose.\n\nThat's the idea behind Trama. Your agent is a very fast weaver, and the map is the pattern. Every change to the design is woven in deliberately, as a Proposal you approve, and a thread pulled out of place in the code shows up as a Drift.\n\nIn Italian, *trama* is also the **plot** of a story: what happens, in what order, and why. A map of every state your app can be in, and every event that moves it on, is exactly that.\n\nThe letters spell out what's inside:\n\n- **Tasks** : the work the agent picks up, on a board you can follow.\n- **Requirements** : how your app must be built, written once and followed every time.\n- **Analysis** : the agent compares your code with the map and tells you where they disagree.\n- **Map** : every situation your app can be in, drawn for you as a diagram.\n- **Agents** : works with the one you already use: Copilot Chat, Cursor, Claude Code or omp.\n\nTrama runs in VS Code and Cursor, on Linux (x64) and macOS (Apple silicon).\n\n1. \n**Install the extension.** Download the`.vsix` for your platform from[Releases](https://github.com/nicchia-code/trama/releases) , then run**Extensions: Install from VSIX…** from the command palette, or:\n\n```\ncode --install-extension trama-<platform>-<version>.vsix\n```\n\n The `trama` command line comes inside the extension, so there's nothing else to install.\n2. \n**Pick your agent** in Settings (`trama.agent` ),*before* you initialize a project:\n  - `chat` (default): Copilot Chat in VS Code, or the chat in Cursor.\n  - `claude` : Claude Code in a terminal. Also set`trama.skillsDir` to`.claude/skills` , so Claude Code finds Trama's skills.\n  - `omp` : omp in a terminal.\n Terminal agents must already be installed and on your `PATH` .\n3. \n**Open your project** and run**Trama: Open** .\n4. \nChoose **Initialize Project** for a fresh start, or**Import from Code** for an existing app.\n5. \nClick **Design…** and describe your first feature.\n\nFor Claude Code, writing in Italian, a typical setup looks like this:\n\n```\n// settings.json\n{\n  \"trama.agent\": \"claude\",\n  \"trama.skillsDir\": \".claude/skills\",\n  \"trama.language\": \"Italian\"\n}\n```\n\n| Setting | Default | What it does | \n|---|---|---|\n| `trama.agent` | `chat` | Where Trama sends its instructions: `chat` ,`claude` or`omp` . | \n| `trama.skillsDir` | `.agents/skills` | Where **Initialize Project** installs the agent skills. Use`.claude/skills` for Claude Code. | \n| `trama.language` | *empty* | Language for the prose the agent writes (descriptions, Proposals, Tasks, Drifts), e.g. `Italian` . Code, names, titles and IDs stay in English. | \n| `trama.terminalLocation` | `panel` | Where terminal agents open: `panel` (terminal area, in the background) or`editor` (a tab beside your code). | \n| `trama.analysis` | *empty* | Model for design requests, Drift resolution and import. | \n| `trama.scan` | *empty* | Model for scans, including the sub-agents that compare each Machine. | \n| `trama.execution` | *empty* | Model for implementing Tasks. | \n| `trama.autoScan` | `true` | After you approve a Proposal, scan what it changed and create the Tasks. | \n| `trama.autoExit` | `true` | Close an agent's terminal as soon as it's done. | \n| `trama.maxParallelAgents` | `20` | How many sub-agents the agent may run at once. | \n| `trama.submitWhileRunning` | `disabled` | `enabled` lets you start a run while another is in progress. | \n| `trama.driftAutoPilot` | `disabled` | Let the agent resolve Drifts on its own: `enabled` for non-critical ones,`yolo` for all of them. | \n\nFor the three model settings, write the model name as your agent accepts it, or leave it empty for the agent's default. In the chat they pick the model of the new conversation: in Copilot, a model with that name; in Cursor, the conversation's starting model. Every setting except `trama.autoScan`, `trama.skillsDir`, `trama.language` and `trama.submitWhileRunning` lives in your user settings only, so it can't be overridden per workspace. All the details are in the [extension README](https://github.com/nicchia-code/trama/blob/main/extension/README.md).\n\n```\nflowchart LR\n  subgraph repo[\".trama/ in your repo\"]\n    M[Model]\n    R[Requirements]\n    W[Proposals · Tasks · Drifts]\n  end\n  E[Editor extension] -->|reads, renders| repo\n  E -->|sends instructions| A[Your agent]\n  A -->|loads| S[Skills]\n  A -->|explores, writes through| C[trama CLI]\n  C --> repo\n  R -.->|generated into| S\n  A -->|writes| Code[Your code]\n```\n\n**Everything is plain Markdown in your repo.** `.trama/` lives next to your code and is versioned with it: the Model in `model/`, the Requirements in `requirements/`, and the work in `proposals/`, `tasks/` and `drifts/`. No database, no cloud service, no account.\n\n**The Model is a set of state machines.** A System is split into Features. Each Feature groups Machines, and each Machine is one file listing its States, the Events that move it, and where each move leads, with conditions written as plain prose. States can nest. Machines never call each other: they react to Events, emitted by other Machines or by Actors outside the System (the user, a payment provider, time). The Diagram is generated from these files and laid out automatically. It's read-only: to change it, you ask the agent for a Proposal, so the files stay the single source of truth. [File format](https://github.com/nicchia-code/trama/blob/main/docs/model-format.md).\n\n**Requirements become skills.** Requirements are grouped into Areas (`ui`, `tech`, `quality`, `data`, `rules`, or your own), split into fragments. Each Area and fragment says when an agent needs it, and each section applies to the whole System or to one Feature, Machine or State. Whenever a Requirement file changes, Trama regenerates them as agent skills (`trama-req-<area>-<fragment>`), with that \"when\" as the skill's description. The agent's own skill loader then pulls in only the rules that matter for the task at hand. Past a size budget, each Area becomes one index skill instead, so a large rulebook never floods the agent's context.\n\n**Agents go through the CLI.** The `trama` CLI is a single binary bundled with the extension. Agents use it to explore the Model (`trama machine order`, `trama paths order Draft Shipped`, `trama search refund`), check it (` trama validate`, `trama analyze`), and create Proposals, Tasks and Drifts. It never reads your code: comparing the Model with the code is the agent's job.\n\n**Skills drive the workflow.** `trama init` installs five agent skills into your project, each one step of the loop:\n\n| Skill | Does | \n|---|---|\n| `trama-design` | Asks you questions in rounds, then writes a Proposal | \n| `trama-scan` | Compares Model and Requirements with the code; files Tasks and Drifts | \n| `trama-implement` | Turns Tasks into code; files a Drift when the Model can't be followed | \n| `trama-resolve-drifts` | Asks you how to settle each Drift, then records your choices in one Proposal | \n| `trama-import` | Describes existing code as Proposals | \n\n**Nothing changes without you.** A Proposal holds the full new version of every file it touches and must pass validation against the whole Model before you see it. Nothing changes until you approve it. Decisions such as approving, rejecting or resolving a Drift are yours: agents take them only when you explicitly ask. An open Drift blocks every Task about the same part of the Model until you resolve it.\n\n**Built for parallel agents.** A scan gives each Machine to its own sub-agent. Implementation runs hand out Tasks in groups that touch different parts of the Model. After you approve a Proposal, only what it changed is scanned again.\n\n**The editor never calls a model.** The extension renders the Diagram, Board and Requirements, shows the agent's questions in its own panel, and sends instructions to the agent you choose. All the reasoning happens in your agent, with your subscription.\n\nTrama is open source under the [GNU AGPL v3](https://github.com/nicchia-code/trama/blob/main/LICENSE): use it, change it and share it, as long as your changes stay open too.\n\nWant to use Trama in a closed-source product? [Get in touch](mailto:luca.soda@gmail.com) for a commercial license.\n\nCopyright © 2026 Luca Soda", "url": "https://wpnews.pro/news/trama-see-your-agent-s-changes-as-state-machines-before-any-code", "canonical_source": "https://github.com/nicchia-code/trama", "published_at": "2026-10-11 12:38:31+00:00", "updated_at": "2026-10-11 12:52:52.264655+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "artificial-intelligence"], "entities": ["Trama", "Nicchia Code"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/trama-see-your-agent-s-changes-as-state-machines-before-any-code", "markdown": "https://wpnews.pro/news/trama-see-your-agent-s-changes-as-state-machines-before-any-code.md", "text": "https://wpnews.pro/news/trama-see-your-agent-s-changes-as-state-machines-before-any-code.txt", "jsonld": "https://wpnews.pro/news/trama-see-your-agent-s-changes-as-state-machines-before-any-code.jsonld"}}