Agents

Some work is best handed to a specialist. The Cycle MCP Server ships agents (also called subagents): self-contained, host-neutral definitions that the main coding agent can delegate a focused job to. Each agent carries everything it needs for its task, so the main agent does not have to.

The clearest example is authoring. Turning an explored workflow into a correct .feature file requires CycleScript authoring rules, locator formats, and language grammar: a lot of context. Rather than loading all of that into the main agent (where it competes for attention with driving the browser and talking to you), Cycle packages it inside a dedicated authoring agent. The main agent stays focused on getting a good workflow; the subagent owns the heavy authoring knowledge.

How delegation works

Agents are part of Cycle's resources, not a separate setup step:

1. The main agent reads the cycle://subagents catalog to see which specialized agents exist and what each one takes as input and returns as output.
2. When a job matches, it reads that agent's full definition at cycle://subagents/{name} (for example, cycle://subagents/feature-file-author or cycle://subagents/blueprint-author).
3. It runs the definition as a dedicated subagent using your host's own subagent or task mechanism: a fresh context separate from the main conversation. Then it uses the result.

Because the definitions are host-neutral, there are no agent files for you to install or configure for the built-ins. How a host spins up a subagent varies (Claude Code, Cursor, and Copilot each have their own mechanism), but the Cycle definition the agent runs is the same everywhere.

You can always ask: "What Cycle subagents are available?" to have the agent read the catalog for you.

Built-in agents

feature-file-author

Authors a validated CycleScript .feature file from a workflow the main agent has already explored.

• Input: The assembled exploration workflow (the ordered sequence of steps the main agent discovered, required); optionally the goal of the test and the target project directory.
• Output: Exactly one validated .feature file (its path plus a short summary of what it covers), or a clear report of what could not be authored and why.
• What it owns: The complete authoring rules: it maps each workflow item to a real step (reading cycle://steps and cycle://step/{id} to confirm exact step text and parameters rather than inventing syntax), writes a readable file under the project's Test Cases/ directory, and runs validate_feature itself, fixing diagnostics until the file is clean before returning it.
• What it does not do: It does not run tests, drive the browser, or debug failures; those stay with the main agent. If the workflow it is handed is incomplete or ambiguous, it authors what it can and reports the gap instead of covering over it.

This is the agent the author-a-test prompt hands off to.

blueprint-author

Sets up or tears down test data by authoring, validating, running, and tearing down a Blueprint over MOCA, SQL, REST, MongoDB, or flat files.

• Input: A plain-English data-setup or teardown intent, plus the target Cycle project (its directory or .cycproj) whose connections and blueprint library to use. Optionally the system configuration or connection to target, and any field values already known.
• Output: The Blueprint it authored and where it lives, the validation result, the run verdict with the realized blueprint-{entity}-{column} variables, and the teardown state. Failing that, a clear report of what it could not do and why.
• What it owns: The whole Blueprint loop. It reads the Blueprint reference resources rather than recalling the schema, surveys your library by reading its catalog and system configuration so it adapts an existing scenario instead of inventing one, validates every draft before touching a datastore, runs it, and reports the values it realized. It also owns the gotchas: that a system configuration's default variables do not reach a create op unless bound as a field, and that ensure records are never removed automatically.
• What it does not do: It does not drive the browser, author .feature files, or run tests. It never runs a datastore-touching tool without validating first, and it never executes a teardown without explicit confirmation.

Teardown is deliberately gated. The agent calls blueprint_teardown once to get a preview of what would be removed, shows you that preview, and only calls again with confirmation after you say yes. An ambiguous answer is treated as a no.

Adding your own agents

You can extend or override the built-in agents without rebuilding Cycle. The server scans a subagents directory for custom definitions: subagents/ next to cycle-cli.exe by default, or wherever you point the --subagents-dir flag. A custom definition whose name matches a built-in replaces the built-in agent.

Like the built-in agents, a good subagent carries the knowledge its task needs so the main agent can stay lean. Keeping them self-contained is recommended.

To add one:

1. Create a Markdown file in that directory with frontmatter describing the agent (name, description, input, and output), followed by the agent's instructions (its system prompt) in the body. Ask the agent to read cycle://subagents/feature-file-author and use the built-in definition as a template for the shape.
2. Restart your coding agent so the server reloads the directory.
3. The new agent appears in cycle://subagents alongside the built-ins, and the main agent can dispatch it.