Executing Appgrammars

Once an appgrammar is created (status ready), your AI agent executes it by walking through stages one at a time. This guide explains the execution model, token chaining, and what each step contains.

Starting Execution

Call appgrammar_start with { "appgrammar_id": "your-appgrammar-uuid" }. The response contains:

• sys -- the system prompt with project-wide context and conventions
• sys_design -- the design system as JSON (colors, typography, spacing)
• step -- the first execution step
• nx -- the token for the next step
• dn -- false (execution is not complete)
• tokens -- array of all remaining step tokens, so the agent can plan ahead

Read sys and sys_design first. These set the context for the entire build. Then execute the first step.

Advancing Through Steps

After completing a step, call appgrammar_next with the appgrammar_id and the token from nx. Each call consumes the token (single-use) and returns the next step along with a new nx token. When dn: true, the plan is complete.

Step Structure

Every step contains these fields:

Field	Description
s	Step number
t	Step type: cf (create file), cmd (run command), rf (replace in file), if (insert before marker), af (append to file), mk (mkdir)
p	File path or command to execute
desc	Compressed specification -- what to implement
c	Code content or template (when applicable)
ctx	Context from previous steps relevant to this one
reg	File registry -- all project files with their roles and exports

The agent reads desc for the specification, uses ctx for awareness of what has been built, and references reg to understand the full project structure.

Stages and Parallel Groups

Steps are organized into stages. Each stage contains one or more parallel groups:

Stage 0: [Group A: steps 1-3] [Group B: steps 1-2]
Stage 1: [Group C: steps 1-4]
Stage 2: [Group D: steps 1-2] [Group E: step 1]

• Groups within the same stage have no dependencies between them and can run concurrently
• Steps within a group must run sequentially (each depends on the previous)
• The next stage starts only after all groups in the current stage complete

This structure maximizes parallelism. An agent (or swarm of agents) can execute independent groups simultaneously while respecting the dependency ordering between stages.

Token Chaining

Tokens are single-use UUIDs that enforce execution order:

1. appgrammar_start returns the first step and nx token
2. Each appgrammar_next call consumes its token and returns a new nx
3. Using a token twice results in an error
4. Tokens cannot be skipped -- each must be consumed in sequence

The tokens array returned by appgrammar_start contains all remaining tokens upfront. This lets the agent see how many steps remain and plan its execution strategy.

Convention Injection

When an appgrammar belongs to a team with conventions, those conventions are automatically injected into the sys (system prompt) at execution time. Conventions are matched by technology tags -- for example, conventions tagged ["typescript", "react"] are included when executing a TypeScript/React appgrammar. See the Teams & Conventions guide for details.

Monitoring Execution

In the web UI, the Execution Progress component shows real-time step completion via SSE events. Programmatically, call appgrammar_status with the appgrammar ID to check steps completed, total steps, and current status.