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
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.mdprovides high-level guidance on setup, usage, and system behavior, ensuring the AI understands the workflow’s purpose and constraints.project_config.mdsets 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.mdrules 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 inworkflow_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:
- Read
workflow_state.mdfor state/rules/plan.- Consult
project_config.mdfor context.- Act via Cursor (Agent Mode, terminal).
- Update
workflow_state.md.If a task is specified “Summarize 4 TypeScript files”), execute or adapt the
Planinworkflow_state.mdusing 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 inworkflow_state.md, and execute. Useinstructions.mdfor 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.
1 Like
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.
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.
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
- Log bloat → Add a cron-like rule: “If ## Log > 5 000 chars, summarise top 5 findings to ## ArchiveLog, then clear.”
- 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. - 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
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)
As I said, Gemini is a God, he tried to call the tool himself but it’s not in my toolkit hmm..