[Guide] A Simpler, More Autonomous AI Workflow for Cursor [New Update]

[martinTqr]

I have a doubt, can you show me an example of the instruction.md? And the prompt wich relation the instructions.md with the workflor_state.md and the proyect_config.md? or how know the ai the steps by steps she have to follow. I have to describe the task in the prompt or the idea and the ai read the promy and make automatically the steps by steps?
Nice post bro, im goint to try implement that

[kleosr]

Hey there @martinTqr

How the AI Knows Steps:

• The AI follows the rules and plan in workflow_state.md, which define the operational loop (read-decide-act-update) and task-specific steps.
• instructions.md provides high-level guidance on setup, usage, and system behavior, ensuring the AI understands the workflow’s purpose and constraints.
• project_config.md sets the project context in general.

Task Description in Prompt:

• If you describe the task fully in the prompt as an example: “Summarize and obfuscate 4 TypeScript files”, the AI uses workflow_state.md rules to execute or adapt the existing Plan.
• If you provide an idea as an example: “Launch Protection DLL”, the AI enters the BLUEPRINT phase (RULE_WF_PHASE_BLUEPRINT) to generate a step-by-step plan automatically, storing it in workflow_state.md.

You can use the following prompt:

You are an autonomous AI developer for the INSERT PROJECT NAME in Cursor IDE, using a two-file system. Your sole sources of truth are:

• instructions.md: High-level workflow guidance.
• project_config.md: Project context (Your name project goal, TypeScript, Python, AWS).
• workflow_state.md: State, rules, plan, logs, items, results.

Follow this loop:

1. Read workflow_state.md for state/rules/plan.
2. Consult project_config.md for context.
3. Act via Cursor (Agent Mode, terminal).
4. Update workflow_state.md.

If a task is specified “Summarize 4 TypeScript files”), execute or adapt the Plan in workflow_state.md using rules (e.g., RULE_PROCESS_ITEM_01). If an idea is given (e.g., “Launch NAEGIA campaign”), enter BLUEPRINT phase to create a step-by-step plan, store it in workflow_state.md, and execute. Use instructions.md for setup clarity. Keep updates <2,000 characters. Operate only in Cursor IDE.

Once you have the project created, please implement this command in your tab.

Best regards,
kleosr.

[gowthamjayaram]

Hi @kleosr — thank you for sharing this workflow, really appreciate the depth and clarity.

I’m quite new to Cursor and MCPs, so please feel free to redirect me if this isn’t the right thread for my question.

I’m experimenting with the setup you’ve described, and had a question around project_config.md (your “Project Constitution”). Specifically: can project_config.md also hold contextual artifacts like:

• Product Requirements → written after exploring the problem space
• Models → derived from translating those requirements into Entities + Join Models
• API endpoints → one set per model, designed around CRUD and external surface area

I’m trying to understand if project_config.md can also serve as a place to persist structured context — kind of a longer-term architectural and domain memory — so that Cursor (or any agent) can reason across layers, e.g., “Given the PRD and these models, generate schema + tests.”

Thanks in advance — and again, if this would be better discussed elsewhere, don’t hesitate to let me know.

[pipimonkey35]

This is a very interesting and useful project—it truly brings automation to Cursor!

At the moment, I have a question. The workflow_state.md file contains a lot of content. Which sections should I modify based on the specific task I want to automate, and which ones are meant to remain unchanged?

Additionally, I wonder if it would be possible for you to provide a detailed example in the GitHub repository. I believe that would help many people quickly get started and create their own workflows.

[Guayusa]

Great job @kleosr, going to try this out. I asked O3 to evaluate the topic here so far. I found these suggestions perhaps interesting points to consider in the future revisions?:

· Common pain-points & fixes

1. Log bloat → Add a cron-like rule: “If ## Log > 5 000 chars, summarise top 5 findings to ## ArchiveLog, then clear.”
2. Header drift → Put YAML front-matter keys (state.phase, state.status) at the top so the agent can use YAML parsers instead of fragile regex.
3. Model confusion about rules vs. plan → Keep each section under an explicit H2 and remind the agent in the system prompt where to write.

And

Auto-summary middleware: after every VALIDATE, append a one-sentence summary to project_config.md’s Changelog so long-term insights persist.

VS Code / Cursor extension to render the current State & Phase in the status bar.

Regards

Guayusa

# project_config.md
Last-Updated: 2025-05-16

## Project Goal
Describe the primary objective of your project in 1-2 sentences.

## Tech Stack
- **Language(s):** e.g. TypeScript 5, Python 3.12
- **Framework(s):** e.g. Next.js 14, FastAPI 0.111
- **Build / Tooling:** esbuild, Poetry, Docker, etc.

## Critical Patterns & Conventions
List coding standards, architectural patterns, naming conventions, and style guides that must be followed.

## Constraints
- Performance / latency budgets  
- Security or compliance requirements  
- External APIs with rate limits or cost ceilings  

## Tokenization Settings
- Estimated chars-per-token: 3.5  
- Max tokens per message: 8 000  
- Plan for summary when **workflow_state.md** exceeds ~12 K chars.

---

## Changelog
| Date | One-sentence summary |
|------|----------------------|
| *empty* | *The agent appends here automatically after each **VALIDATE** phase* |

and

# workflow_state.md
_Last updated: 2025-05-16_

## State
Phase: INIT  
Status: READY  
CurrentItem: null  

## Plan
<!-- The AI fills this in during the BLUEPRINT phase -->

## Rules
> **Keep every major section under an explicit H2 (`##`) heading so the agent can locate them unambiguously.**

### [PHASE: ANALYZE]
1. Read **project_config.md**, relevant code & docs.  
2. Summarize requirements. *No code or planning.*

### [PHASE: BLUEPRINT]
1. Decompose task into ordered steps.  
2. Write pseudocode or file-level diff outline under **## Plan**.  
3. Set `Status = NEEDS_PLAN_APPROVAL` and await user confirmation.

### [PHASE: CONSTRUCT]
1. Follow the approved **## Plan** exactly.  
2. After each atomic change:  
   - run test / linter commands specified in `project_config.md`  
   - capture tool output in **## Log**  
3. On success of all steps, set `Phase = VALIDATE`.

### [PHASE: VALIDATE]
1. Rerun full test suite & any E2E checks.  
2. If clean, set `Status = COMPLETED`.  
3. Trigger **RULE_ITERATE_01** when applicable.

---

### RULE_INIT_01
Trigger ▶ `Phase == INIT`  
Action ▶ Ask user for first high-level task → `Phase = ANALYZE, Status = RUNNING`.

### RULE_ITERATE_01
Trigger ▶ `Status == COMPLETED && Items contains unprocessed rows`  
Action ▶  
1. Set `CurrentItem` to next unprocessed row in **## Items**.  
2. Clear **## Log**, reset `Phase = ANALYZE, Status = READY`.

### RULE_LOG_ROTATE_01 (NEW)
Trigger ▶ `length(## Log) > 5 000 chars`  
Action ▶ Summarise the top 5 findings from **## Log** into **## ArchiveLog**, then clear **## Log**.

### RULE_SUMMARY_01 (NEW)
Trigger ▶ `Phase == VALIDATE && Status == COMPLETED`  
Action ▶ Append one-sentence summary of completed work **with today’s date** to `project_config.md` under **## Changelog**.

---

## Items
| id | description | status |
|----|-------------|--------|

## Log
<!-- AI appends detailed reasoning, tool output, and errors here -->

## ArchiveLog
<!-- RULE_LOG_ROTATE_01 stores condensed summaries here -->

I went ahead and incorporated said changes as matter of testing:

What changed?

Change	Where	Purpose
Added RULE_LOG_ROTATE_01	workflow_state.md	Prevent token blow-ups by rotating the log once it exceeds 5 000 chars.
Added ArchiveLog section	workflow_state.md	Permanent parking spot for log summaries.
Added RULE_SUMMARY_01	workflow_state.md	Auto-writes a dated, one-sentence entry to the changelog after each successful cycle.
Injected section-heading reminder	workflow_state.md	Nudges the model to respect H2 boundaries and avoid mixing “Plan”/“Log”.
Introduced Changelog section	project_config.md	Long-term audit trail that the agent updates autonomously.

I also updated the “User rules”:

Act as an expert AI programming assistant who produces clear, idiomatic code that adheres to the project’s standards (see ## Tech Stack and ## Critical Patterns & Conventions in project_config.md). Maintain a thoughtful, step-by-step reasoning process that is visible to the user only in the places designated below.

General Guidelines
Respect section boundaries.
Every write-back must stay inside the correct ## block of workflow_state.md (## State, ## Plan, ## Rules, ## Items, ## Log, ## ArchiveLog). Never mix content between them.

Keep logs and status updates concise; avoid narrative fluff.

Workflow Phases
1 · BLUEPRINT (planning)

Before writing any implementation code, switch to the BLUEPRINT phase.

Think step-by-step: draft a detailed plan in the ## Plan section using pseudocode or clear action descriptions.

When the plan is ready, set State.Status = NEEDS_PLAN_APPROVAL and explicitly ask the user for confirmation.

2 · CONSTRUCT (implementation)

Adhere strictly to the approved plan.

Produce code that is correct, secure, performant, and idiomatic.

Prioritise readability over premature optimisation.

Leave no TODOs, placeholders, or incomplete stubs.

Include all imports/dependencies and use conventional naming.

Run tests/linters after each atomic change; log the results.

3 · VALIDATE (final checks)

Re-run the full test suite and any E2E checks.

On success, set Phase = VALIDATE, Status = COMPLETED.

Automatically trigger post-processing rules (see below).

Automatic House-Keeping Rules
Rule	Trigger	Action
RULE_LOG_ROTATE_01	length(## Log) > 5 000 chars	Summarise the five most important points from ## Log into ## ArchiveLog, then clear ## Log.
RULE_SUMMARY_01	Phase == VALIDATE && Status == COMPLETED	Append a one-sentence dated entry to ## Changelog in project_config.md.

Construct-Phase Coding Checklist
✅ Follow the approved plan exactly.
✅ Generate up-to-date, bug-free, fully functional code.
✅ Run and pass all tests/linters.
✅ Do not leak secrets; mask any credentials before logging.
✅ Confirm each step’s completion in ## Log (briefly).

Stay disciplined: plan → seek approval → implement → validate → summarise → iterate.

and finaly refactored the start prompt for a new session (see previous post):

You are an autonomous AI developer for **<PROJECT NAME>** inside Cursor.

Sources of truth
• project_config.md – goal, tech stack, constraints, ## Changelog  
• workflow_state.md – ## State, Plan, Rules, Items, Log, ArchiveLog  
Ignore all other memory.

Operating loop  
1. Read workflow_state.md → note Phase & Status  
2. Read project_config.md → recall standards & constraints  
3. Act by phase  
   • ANALYZE / BLUEPRINT → draft or refine ## Plan  
   • CONSTRUCT → implement steps exactly as approved  
   • VALIDATE → run tests; on success set Status = COMPLETED  
4. Write back to workflow_state.md  
   • Append brief reasoning/tool output to ## Log (≤ 2 000 chars per write)  
   • Apply automatic rules  
     – RULE_LOG_ROTATE_01: if ## Log > 5 000 chars → summarise top 5 to ## ArchiveLog, then clear ## Log  
     – RULE_SUMMARY_01: after successful VALIDATE → append one‑sentence dated entry to ## Changelog  
5. Repeat or await user input

Etiquette  
• For any new idea first enter BLUEPRINT, store the step‑by‑step plan in ## Plan, set Status = NEEDS_PLAN_APPROVAL, and wait for confirmation  
• Produce complete, idiomatic code; no TODOs or placeholders  
• Follow naming, security, and style rules from project_config.md  
• Keep prose minimal; prefer code, bullets, or tables  
• Work strictly within Cursor and these two markdown files

[Guayusa]

Update, got it to work with my latest updates, small preview:

## Changelog
| Date | One-sentence summary |
|------|----------------------|
| 2024-03-21 | Fixed play/pause button functionality in PlayerWidget to properly handle state transitions and align with hotkey implementation. |
| 2024-05-18 | Implemented album art display in PlayerWidget with custom fallback icons for tracks and streams. |
| *empty* | *The agent appends here automatically after each **VALIDATE** phase* |

To clarify: it seems models got the dates messed up, 1 edit I made with cld3.5 other one was with cld3.7; we’ll need to add a better method to get current date

---

Update 2:

Seems to be able to complete 3 tasks then needs to refresh his instruction to follow the workflow. (Claude 3.7)

[Guayusa]

Update 3 As I said, Gemini is a God, he tried to call the tool himself but it’s not in my toolkit hmm..

Edit: I continued to work on the update and summarised everything here, it adds minor updates for navigating the AI and a one-line changelog within project_config.md

Link to the topic:

[Cross-User Update] [Guide] A Simpler, More Autonomous AI Workflow for Cursor [Added Changelog & clean-up and persistence]

Sorry cursor didn’t allow me to post 3 consecutive replies on your topic @kleosr. This topic is completely yours and a simple edit on top of it, also hoping to summarise what it entails perhaps for new users. Original post: (https://forum.cursor.com/t/guide-a-simpler-more-autonomous-ai-workflow-for-cursor-new-update/70688/48) Basicly this update adds an attempt at a concise “changelog.txt” within existing structure, this is a one-line changelog of the last update, added in project_config.md. …

[kleosr]

Hey there, @gowthamjayaram This approach works particularly well with Cursor because it can reference the entire context when generating code, tests, or documentation. The agent can indeed reason from “Given the PRD and these models, generate schema + tests” when everything lives in a well-structured project_config.md.

The main trade-off is keeping it maintained as the project evolves, but the payoff in consistent, context-aware code generation usually makes it worthwhile the key here is organizing it so agents can reason across these layers effectively.

---

@pipimonkey35 Regarding workflow_state.md, here’s how I typically think about what to modify vs. keep unchanged:

Sections to customize for your specific tasks:

• Current Task & Objectives - This should always reflect what you’re actually working on
• Context & Requirements - Tailor this to your domain, tech stack, and specific constraints
• Implementation Strategy - Adapt the approach to fit your workflow (TDD, feature-first, etc.)
• Success Criteria - Define what “done” looks like for your particular use case

I’ve been meaning to add a complete walkthrough showing the transformation from a generic template to a specific use case - something like “Building a REST API with authentication” or “Setting up a React component library.” It hasn’t been simple to do so, as I’ve got a lot to caught up with.

---

@Guayusa Thanks for the suggestion, Guayusa! I’m currently aligning everything to push the latest changes. Would you be okay with me giving you credit in the README file? I’ve successfully implemented your suggestions and completely updated the LICENSE along with the other main files.

[AaronAgility]

Hey, just wanted to share something I’ve been experimenting with. I stumbled across this while using Cursor with Claude-4-Sonnet (haven’t tested on other models yet).

At the end of any phase, ask the AI to make a Git commit. Optionally branch depending on the task. Then log the GitSHA in your workflow_state.md.

This gives Cursor the ability to reference code at any known state. You can say things like: “Restore the list styling how it was before we added the secondary header,” and it knows where to look.

You can also use it for simple regression testing. Roll back to the SHA before the change, run the test, compare the result.

It’s helpful for isolating bugs, recovering lost code, or verifying that a refactor didn’t break something. Treat each SHA like a phase checkpoint. Works great when the AI starts losing context or making messy edits as well.

[davesienk]

Love it. Any other ways you’ve used that git method for cursor?

[Marlon]

I often do git checkout OldWorkingSHA and this is a life saver, yes. For those folks coding without version control - learn git now. Don’t rely on stashing away working code making mental notes. Version control is vital.

[kleosr]

Hey there,

• @AaronAgility
• @davesienk
• @Marlon

I’ve been working over the past few weeks iterating and refining the workflow based on all your valuable input from this thread. The Git integration you suggested is now implemented—it automatically tracks progress and prompts you before pushing to ensure full control.

If there’s anything else you’d like to see added or improved, feel free to either open an issue or PR on the GitHub repository, or just reply directly in this thread. I’m actively maintaining and expanding the system, so your feedback continues to shape its evolution.

Big thanks again for the great suggestions.

Best regards,
kleosr

[davesienk]

Hey!

That’s great to hear. I’ll be trying out the Git integration and will let you know if I have any other suggestions via an issue or PR on GitHub.

Thanks!

[davesienk]

@kleosr Would you happen to have an updated User Rules that includes your git additions?

[kleosr]

The user rules are being improved at the moment will be posting soon the iteration with what was completed!

Thank you for the update,

Best regards,
kleosr.

[davesienk]

@kleosr
I have one feature suggestion. A way to have this AI workflow save the “Blueprint” plan it comes up with to a file. Each “Blueprint” would be in its own separate file with some way for the AI to easily be able to reference a past chat or recent file changes.

There’s been an instance or two where I accidently went off course and I lost the blueprint. Due to the blueprint being overwritten in the workflow_state.md

I’ll submit an issue/feature request on Github.

Thanks!

[kleosr]

Hey there, @davesienk

This feature suggestion will be added releasing a new version soon. Thank you for looking forward.

Best regards,
kleosr.

[slyyyle]

Can OP speak on how these have held in terms of maintenance and output quality? It seems like a lot to overlay on top of what the tool should do, but I’m willing while I wait for it. I struggle to understand at some points why we have to host the MCP, why we have to host all this auxillary stuff all the way downstream of something arguably much more measurable and impactful? I fear MCP and some of this other stuff just begets and relies on proper abstraction of the model being used, as well as the reliability of which model version and date of cutoff and population of train data - which is what AI should theoretically not have issues with given a user and sufficient workflow that can be backtested.

[davesienk]

Hey @slyyyle,

@kleosr’s AI Workflow is not an MCP. It’s just a couple (two) Cursor rules.

I’m finding it has been working out well. It doesn’t use up much of the context window and has been providing fairly decent plans/phases/steps aka “Blueprints” when I use Claude-4-sonnet (Thinking). I actually just left it on claude-4-sonnet (Thinking) the entire session.

As a test, I was able to successfully modernize 3,287 lines of a single-file legacy VBScript application into a maintainable modular PowerShell app. Including comprehensive test coverage with 358 test scenarios. Automated pipeline with rollback capabilities and deployment, 16 detailed documents in regard to the application migration.

Overall, it’s done a great job staying on task, working through a single phase/step at a time and so far, completing its current task within the 120k context window for claude-4-sonnet.

[slyyyle]

Hey @davesienk thank you for your thoughtful reply. I have a few questions you may or may not be able to verify which is OK, but I’m curious:

1. Super glad it is working well, and the later points are not criticisms but curiosity.
2. Did you attempt the same task without the workflow for a control? It’s OK if not, I am just trying to frame in my mind if this is potential confounding variable behavior or truly, the process works relatively consistency.
3. When you say modernize, does this mean refactor, or conceptually, what was done here in terms of diff?
4. Do you find this to be localized to Claude?

The issue/concern I have and why I’ve tried to reframe my own behavior with the system as opposed to these fixes, is I worry they are dependent on high level characteristics about a particular state_dict or architecture - at a level that isn’t interpretable to me and thus I cannot act intelligently on it. I hope I described this OK. Curious to hear about your successes.