Agent Flows for Reliable, Step-by-Step Automation

Hey Cursor Team,

I’m really excited about the release of Project Rules, but I’ve noticed some limitations, particularly with consistency and enforcement. This isn’t limited to Project Rules, but also to the regular Cursor Rules. I think we can take the concept even further with a related feature I’m dubbing “Agent Flows” (or “Flow Rules”).

Feature Request: Agent Flows (or Flow Rules)

I’d like to propose a new feature that would allow us to define a precise sequence of steps for the agent to follow. Unlike Project Rules, these flows would be enforced programmatically by the Cursor agent engine, not just through LLM prompting, leading to more reliable automation.

Key Features of Agent Flows:

  1. Strictly Ordered Steps: Flows would consist of numbered lists, where each step is executed sequentially and to completion before moving to the next.
  2. Conditional Sub-steps: Bulleted lists within steps could represent conditional actions. The condition would typically be evaluated by the LLM (though other mechanisms could be envisioned), and the sub-steps executed only if the condition is met.
  3. Distinct File Type: These flows could be defined in separate files (e.g., .mdf for “Markdown Flow”) to distinguish them from regular project rules.
  4. Following Established Conventions: Agent Flows would support the description and globs fields used in Project Rules, following established conventions.
  5. Smart @ Mentions: @ mentions would only be included in the Composer’s context if that specific step is executed, optimizing context usage. Also, @ mentioning an Agent Flow (either in another flow or in the Composer) would execute that flow.
  6. Comments: Lines starting with ^\W*# (regex as an example) would be treated as comments and ignored by the engine (not passed to the LLM), allowing for documentation within flow files that don’t get passed on to the LLM.

Example src-updates.mdf:

---
description: Updates source code and ensures linting, testing, and documentation are up to date.
globs: src/**/*.ts
---
1. Run `npm lint`.
    - If syntax errors exist:
        # LLM attempts to fix all syntax errors
        1. Fix all syntax errors.
2. Run `npm test`.
    - If there is a failed test:
        1. Determine the failed assertion.
        2. Analyze the code around the assertion.
        3. Identify the source code causing the failure.
        # Recursively trigger another flow, only if a test fails
        4. Execute @test-rules.mdf
    - If there is uncovered code:
        # Only run if there is uncovered code
        1. Trigger @test-coverage.mdf
3. Examine @/docs and update relevant files based on code changes.
    # Update documentation to reflect any changes in the source code

Future Considerations:

While the core concept of Agent Flows focuses on sequential and conditional steps, addressing specific reliability concerns over the existing rule features. Some possible future additions:

  • Trigger-Based Execution: Initiating flows based on specific, defined agent actions. These would be in a new field (similar to globs and description). Some examples (very rough idea, based loosely on @ mentions and agent tools):

    • file:write:before: Triggered before the agent writes to a file.
    • file:write:after: Triggered after the agent successfully writes to a file.
    • file:read:after: Triggered after the agent reads from a file.
    • terminal:execute:after: Triggered after the agent executes a terminal command.
    • git:read:after: Triggered after the agent reads a git diff.
  • Looping Constructs: Introducing ways to repeat a set of steps, similar to for or while loops in programming.

  • Step Skipping: Providing mechanisms to conditionally skip certain steps, or goto-like functionality, based on specific criteria.

These additions could provide even greater flexibility and control over complex workflows but are not the main focus of this feature request. I think it’s both important to define a starting scope but acknowledge future enhancements.

Benefits:

  • Reliable Automation: Ensures critical steps are always followed. The Cursor engine enforces the flow logic, guaranteeing execution and reducing reliance on the LLM’s interpretation.
  • Complex Workflows: Enables the creation of sophisticated, multi-step processes for various development tasks.
  • Improved Code Quality: By automating tasks like linting, testing, and documentation updates, Agent Flows help ensure a higher level of code consistency and adherence to best practices, ultimately contributing to improved code quality.
  • Optimized Context: @ mentions are only included when necessary.

I think Agent Flows (or Flow Rules) would complement the existing Project Rules by providing a mechanism for programmatically enforcing strict, step-by-step procedures, guaranteeing their execution. This would significantly enhance Cursor’s capabilities for automating complex development tasks. I believe this feature could be a valuable addition to the Cursor platform, making development more efficient and reliable.

1 Like

I think this would be the next feature that would improve cursor tremendously! after two months of intensively using cursor i realized that a lot of flows are starting to repeat and your idea would help a lot.

Agreed. I still feel even after the recent updates to Project Rules, I still feel we need a separate feature for “Flows” that define a strict step-by-step execution based on some trigger.

I think I should revise my original post, specifically to update it based on the recent changes to Project Rule - Rule Types.

Some other clarifications:

  • Conditional Sub-steps (bulleted lists) - are always a true/false evaluation, generally from an LLM. If true, then it executes the steps underneath it.

Anything else I should flesh out above? Or clean up?

May relate to #Please make "thinking toggle" visible

In fact, in my prompt, I already did something similar as what you have planned here, basically, if we allow Cursor to do the steps automation itself, it can be very random, and sometimes it will get the information that it shouldn’t get, and that will affect the final output in general, but by restricting its thinking process (eg., force it to use certain internal tools), it gets improved a lot.

But again, if its thinking process remains private, it is freaking hard to debug or just hard to polish the prompt in a confident way.