Skip to main content
Version: 2.28

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 doesn't 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).
  3. It runs the definition as a dedicated subagent using your host's own subagent / task mechanism — a fresh context separate from the main conversation — and 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 doesn't run tests, drive the browser, or debug failures; those stay with the main agent. If the workflow it's handed is incomplete or ambiguous, it authors what it can and reports the gap instead of papering over it.

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

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. We recommend keeping them self-contained.

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.