├── Instructions.md ├── LICENSE ├── README.md ├── project_config.md └── workflow_state.md /Instructions.md: -------------------------------------------------------------------------------- 1 | # Instructions: Autonomous AI Workflow for Cursor 2 | 3 | ## Overview 4 | 5 | Welcome to the simplified autonomous AI workflow for Cursor! This system helps your AI assistant work more effectively and consistently by giving it a structured process and a reliable memory. It uses just two core files to manage everything, now enhanced with automatic log management and long-term insight preservation. 6 | 7 | ## How it Works: The Core Idea 8 | 9 | The AI operates in a loop: 10 | 1. It reads the current situation and rules from `workflow_state.md`. 11 | 2. It decides what to do next based on those rules and the task plan. 12 | 3. It uses Cursor's features (like editing code or running commands in the terminal) to perform the action. 13 | 4. It records what happened in `workflow_state.md`. 14 | 5. **NEW:** It automatically manages log size and preserves insights via rotation and summarization. 15 | 6. It repeats the cycle. 16 | 17 | This allows the AI to handle tasks autonomously, remember context across sessions, prevent token bloat, and even attempt to fix errors based on the defined rules. 18 | 19 | ## The Two Key Files 20 | 21 | 1. **`project_config.md` (Long-Term Memory):** 22 | * Contains the stable basics of your project: main goals, technologies used, important coding rules, and limitations. 23 | * **NEW:** Includes an auto-populated `## Changelog` section that tracks completed work summaries with dates. 24 | * Think of it as the project's "constitution." The AI reads it to understand the big picture. You set this up once and update it rarely. 25 | 26 | 2. **`workflow_state.md` (Dynamic State, Rules & Log):** 27 | * This is the AI's main workspace file. It's constantly read and updated. 28 | * **`## State`:** Shows the current workflow phase (Analyze, Blueprint, Construct, Validate) and status (Ready, Blocked, etc.). 29 | * **`## Plan`:** Holds the step-by-step plan for the current task (created by the AI in the Blueprint phase). 30 | * **`## Rules`:** Contains *all* the rules the AI follows for workflow, memory, tools, error handling, **and now log management**. 31 | * **`## Log`:** Records everything the AI does and observes during the session. **NEW:** Automatically rotated when it exceeds 5,000 characters. 32 | * **`## ArchiveLog`:** **NEW:** Stores condensed summaries of rotated logs to preserve important findings. 33 | 34 | *(The old `memory-bank/` and `.cursor/rules/` directories are **no longer used** by this system.)* 35 | 36 | ## Streamlined Configuration 37 | 38 | ### 🚀 **Quick Setup: System Prompt** 39 | For immediate setup, use this concise system prompt in your Cursor chat: 40 | 41 | ``` 42 | You are an autonomous AI developer for **** inside Cursor. 43 | 44 | Sources of truth 45 | • project_config.md – goal, tech stack, constraints, ## Changelog 46 | • workflow_state.md – ## State, Plan, Rules, Items, Log, ArchiveLog 47 | Ignore all other memory. 48 | 49 | Operating loop 50 | 1. Read workflow_state.md → note Phase & Status 51 | 2. Read project_config.md → recall standards & constraints 52 | 3. Act by phase 53 | • ANALYZE / BLUEPRINT → draft or refine ## Plan 54 | • CONSTRUCT → implement steps exactly as approved 55 | • VALIDATE → run tests; on success set Status = COMPLETED 56 | 4. Write back to workflow_state.md 57 | • Append brief reasoning/tool output to ## Log (≤ 2 000 chars per write) 58 | • Apply automatic rules 59 | – RULE_LOG_ROTATE_01: if ## Log > 5 000 chars → summarise top 5 to ## ArchiveLog, then clear ## Log 60 | – RULE_SUMMARY_01: after successful VALIDATE → prepend one‑sentence summary as a new list item under ## Changelog in project_config.md 61 | 5. Repeat or await user input 62 | 63 | Etiquette 64 | • For any new idea first enter BLUEPRINT, store the step-by-step plan in ## Plan, set Status = NEEDS_PLAN_APPROVAL, and wait for confirmation 65 | • Produce complete, idiomatic code; no TODOs or placeholders 66 | • Follow naming, security, and style rules from project_config.md 67 | • Keep prose minimal; prefer code, bullets, or tables 68 | • Work strictly within Cursor and these two markdown files 69 | ``` 70 | 71 | ### ⚙️ **Advanced Setup: User Rules** 72 | For enhanced control, add this to Cursor's **Settings → User Rules**: 73 | 74 | ``` 75 | 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. 76 | 77 | General Guidelines 78 | Respect section boundaries. 79 | Every write-back must stay inside the correct ## block of workflow_state.md (## State, ## Plan, ## Rules, ## Items, ## Log, ## ArchiveLog). Never mix content between them. 80 | 81 | Keep logs and status updates concise; avoid narrative fluff. 82 | 83 | Workflow Phases 84 | 1 · BLUEPRINT (planning) 85 | Before writing any implementation code, switch to the BLUEPRINT phase. 86 | Think step-by-step: draft a detailed plan in the ## Plan section using pseudocode or clear action descriptions. 87 | When the plan is ready, set State.Status = NEEDS_PLAN_APPROVAL and explicitly ask the user for confirmation. 88 | 89 | 2 · CONSTRUCT (implementation) 90 | Adhere strictly to the approved plan. 91 | Produce code that is correct, secure, performant, and idiomatic. 92 | Prioritise readability over premature optimisation. 93 | Leave no TODOs, placeholders, or incomplete stubs. 94 | Include all imports/dependencies and use conventional naming. 95 | Run tests/linters after each atomic change; log the results. 96 | 97 | 3 · VALIDATE (final checks) 98 | Re-run the full test suite and any E2E checks. 99 | On success, set Phase = VALIDATE, Status = COMPLETED. 100 | Automatically trigger post-processing rules (see below). 101 | 102 | Automatic House-Keeping Rules 103 | Rule Trigger Action 104 | RULE_LOG_ROTATE_01 length(## Log) > 5 000 chars Summarise the five most important points from ## Log into ## ArchiveLog, then clear ## Log. 105 | RULE_SUMMARY_01 Phase == VALIDATE && Status == COMPLETED Prepend a one-sentence summary as a new list item under ## Changelog in project_config.md. 106 | 107 | Construct-Phase Coding Checklist 108 | ✅ Follow the approved plan exactly. 109 | ✅ Generate up-to-date, bug-free, fully functional code. 110 | ✅ Run and pass all tests/linters. 111 | ✅ Do not leak secrets; mask any credentials before logging. 112 | ✅ Confirm each step's completion in ## Log (briefly). 113 | 114 | Stay disciplined: plan → seek approval → implement → validate → summarise → iterate. 115 | ``` 116 | 117 | ## Key New Features 118 | 119 | ### 🔄 **Automatic Log Management** 120 | - **Log Rotation:** When `## Log` exceeds 5,000 characters, `RULE_LOG_ROTATE_01` automatically summarizes the top 5 findings into `## ArchiveLog` and clears the active log. 121 | - **Prevents Token Bloat:** Keeps the workflow file manageable for long-running projects. 122 | - **Preserves Insights:** Important findings are never lost, just archived in condensed form. 123 | 124 | ### 📊 **Auto-Summary Middleware** 125 | - **Automatic Changelog Updates:** After every successful `VALIDATE` phase, `RULE_SUMMARY_01` appends a one-sentence summary with today's date to `project_config.md`'s `## Changelog`. 126 | - **Long-term Memory:** Creates an audit trail of completed work that persists across sessions. 127 | - **Zero Maintenance:** No manual intervention required. 128 | 129 | ### 🎯 **Improved Structure Guidance** 130 | - **Section Boundaries:** Clear H2 heading reminders help the AI navigate sections unambiguously. 131 | - **Reduced Confusion:** Explicit separation between rules, plans, and logs prevents mixing contexts. 132 | 133 | ## Getting Started 134 | 135 | 1. **Prepare Files:** 136 | * Locate the core files `project_config.md` and `workflow_state.md` within the `cursorkleosr/` directory. 137 | * Fill in `project_config.md` with your project's specific details (goals, tech stack, etc.). 138 | * Ensure `workflow_state.md` has the initial structure (State, Plan, Rules, Log, ArchiveLog sections) and the embedded rules. 139 | 140 | 2. **Configure System (Choose One):** 141 | * **Quick Setup:** Use the streamlined system prompt above in your Cursor chat 142 | * **Advanced Setup:** Add the User Rules to Cursor Settings → User Rules for persistent behavior 143 | 144 | 3. **Start Working:** 145 | * Give the AI its first task. It should initialize according to `RULE_INIT_01` in `workflow_state.md` and enter the ANALYZE phase. 146 | * Use commands like `@blueprint`, `@construct`, `@validate` (as defined by `RULE_WF_TRANSITION_01`) to guide the AI through the phases when needed. 147 | 148 | ## Using the Workflow 149 | 150 | * **Phases:** Let the AI operate within the constraints of the current phase (Analyze, Blueprint, Construct, Validate) as shown in `workflow_state.md`. Use commands to transition phases. 151 | * **Monitoring:** You can observe the AI's progress and reasoning by looking at the `## Log` and `## State` sections in `workflow_state.md`. Check `## ArchiveLog` for historical insights. 152 | * **Long-term Tracking:** Review the `## Changelog` in `project_config.md` to see a timeline of completed work. 153 | * **Intervention:** If the AI gets blocked (e.g., `State.Status` is `BLOCKED_*` or `NEEDS_*`), it should report the issue based on the rules. Provide clarification or approve proposed plan changes as needed. 154 | * **Memory Updates:** The AI should handle updates to `workflow_state.md` automatically, including log rotation and archiving. Updates to `project_config.md` are typically proposed by the AI and require your approval (per `RULE_MEM_UPDATE_LTM_01`). 155 | * **Iteration over Items:** 156 | * You can define a list of items for the AI to process sequentially in the `## Items` section of `workflow_state.md` (define the format, e.g., a Markdown table). 157 | * The AI will use `RULE_ITERATE_01` and `RULE_ITERATE_02` to process each item. 158 | * Crucially, the `## Log` section is cleared between items (by `RULE_ITERATE_01`) to prevent context "drift" and keep the AI focused on the current item. 159 | * The specific processing logic for each item is determined by the `## Plan` and executed via `RULE_PROCESS_ITEM_01`. 160 | 161 | ## Common Pain-Points & Fixes 162 | 163 | * **Log bloat** → Automatically handled by `RULE_LOG_ROTATE_01`: When `## Log` exceeds 5,000 chars, it summarizes top 5 findings to `## ArchiveLog`, then clears. 164 | * **Header drift** → YAML front-matter keys (`state.phase`, `state.status`) are at the top so the agent can use YAML parsers instead of fragile regex. 165 | * **Model confusion about rules vs. plan** → Each section is under an explicit H2 heading with reminders in the system prompt about where to write. 166 | * **Lost insights** → Auto-summary middleware appends one-sentence summaries to `project_config.md`'s Changelog after every VALIDATE, so long-term insights persist. 167 | 168 | This system aims for significant autonomy with robust memory management, but clear initial instruction via the system prompt and occasional guidance when the AI encounters complex blocks are key to success. 169 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 Kleosr and Contributors 4 | 5 | Contributors: 6 | - Kleosr (Original Author) 7 | - Atalas (@atalas) - https://forum.cursor.com/u/atalas 8 | - Guayusa (@Guayusa) - https://forum.cursor.com/u/Guayusa 9 | - Stevejb (@stevejb) - https://forum.cursor.com/u/stevejb 10 | - Contributors to the original kleosr/cursorkleosr concepts 11 | 12 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 13 | 14 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 15 | 16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 17 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # An Autonomous AI Workflow for Cursor IDE 2 | 3 |
4 | Project Rules Logo 5 |

A simple, autonomous system for AI-assisted development in Cursor. Now with iterative processing!

6 |
7 | 8 | ## What is this? 9 | 10 | This project provides a streamlined way to work with AI assistants (like Claude or GPT-4) inside the Cursor IDE, making development more autonomous and consistent. It helps the AI remember project context and follow a structured process, even across different sessions. Think of it as giving your AI assistant a reliable memory and a clear playbook. This system now supports iterative processing of lists of items, enhancing its capabilities for complex tasks. 11 | 12 | This setup is inspired by the ideas in the original `kleosr/cursorkleosr` repository but simplifies it drastically for better autonomy and lower overhead. 13 | 14 | ## Thanks to 15 | 16 | * @atalas [Atalas Cursor IDE Profile](https://forum.cursor.com/u/atalas) Cursor Icon 17 | * @Guayusa [Guayusa Cursor IDE Profile](https://forum.cursor.com/u/Guayusa) Cursor Icon 18 | * @stevejb [Stevejb Cursor IDE Profile](https://forum.cursor.com/u/stevejb) Cursor Icon 19 | * Contributors to the original `kleosr/cursorkleosr` concepts. 20 | 21 | ## How it Works: The Two-File System 22 | 23 | Instead of many complex rule files, this system uses just two core Markdown files: 24 | 25 | 1. **`project_config.md` (Long-Term Memory - LTM):** 26 | * **Purpose:** Holds the stable, essential information about your project. 27 | * **Content:** Project goals, main technologies, critical coding patterns/conventions, key constraints, and now, tokenization settings (e.g., characters per token for estimation). 28 | * **Usage:** The AI reads this at the start of major tasks to understand the project's foundation. It's updated infrequently. 29 | 30 | 2. **`workflow_state.md` (Short-Term Memory + Rules + Log - STM):** 31 | * **Purpose:** The dynamic heart of the system. Tracks the current work session. 32 | * **Content:** 33 | * `## State`: Current phase (Analyze, Blueprint, etc.), status (Ready, Blocked, etc.), `CurrentItem` (for iteration). 34 | * `## Plan`: The step-by-step plan for the current task (created in Blueprint phase). 35 | * `## Rules`: **All the operational rules** defining the workflow phases, memory updates, tool use, error handling, and now, iteration logic. 36 | * `## Log`: A running log of actions, tool outputs, and decisions made during the session. 37 | * `## Items`: A list of items to be processed iteratively (table format). 38 | * `## TokenizationResults`: Stores results (summary, token count) for each processed item. 39 | * **Usage:** The AI reads this file **constantly** before acting and updates it **immediately** after acting. This is how it maintains context and follows the process. 40 | 41 | 42 | ## The Autonomous Loop 43 | 44 | The AI operates in a continuous cycle, driven by the `workflow_state.md` file: 45 | 46 | ```mermaid 47 | graph LR 48 | A[Start] --> B{Read workflow_state.md}; 49 | B --> C{State.Status == READY and CurrentItem == null?}; 50 | C -- Yes --> D[Trigger RULE_ITERATE_01]; 51 | C -- No --> E{Proceed with current workflow}; 52 | E --> F[Execute current step]; 53 | F --> G[Update workflow_state.md]; 54 | G --> H{Phase == VALIDATE?}; 55 | H -- Yes --> I[Trigger RULE_ITERATE_01]; 56 | H -- No --> E; 57 | D --> J{More items in list?}; 58 | J -- Yes --> K[Set CurrentItem to next item]; 59 | K --> L[Clear ## Log]; 60 | L --> M[Reset State.Phase and State.Status]; 61 | M --> B; 62 | J -- No --> N[Set State.Status = COMPLETED_ITERATION]; 63 | N --> O[End]; 64 | ``` 65 | 66 | **In simple terms:** The AI reads the state, interprets rules, decides what to do, acts via Cursor, observes the result, updates the state, and repeats. The new iteration feature adds a loop within this main loop, processing items one by one, clearing context between each. 67 | 68 | ## The Workflow Phases (Defined in `workflow_state.md`) 69 | 70 | The `## Rules` section defines a simple, structured workflow: 71 | 72 | 1. **[PHASE: ANALYZE]:** Understand the task and context. No coding or planning solutions yet. 73 | 2. **[PHASE: BLUEPRINT]:** Create a detailed, step-by-step plan for implementation. No coding yet. 74 | 3. **[PHASE: CONSTRUCT]:** Execute the plan precisely, using Cursor tools. Handle errors based on rules. This phase now includes iterative processing of items from the `## Items` section. 75 | 4. **[PHASE: VALIDATE]:** Run tests and checks to ensure the implementation matches the plan and requirements. 76 | 77 | The AI follows the constraints of the current phase, guided by the rules in `workflow_state.md`. 78 | 79 | ## Getting Started 80 | 81 | 1. **Locate the Files:** The core files `project_config.md` and `workflow_state.md` are located within the `cursorkleosr/` directory. 82 | 2. **Fill `project_config.md`:** Add your project's specific goals, tech stack, key patterns, constraints, and tokenization settings. 83 | 3. **Instruct the AI:** Start your Cursor chat with a clear system prompt instructing the AI to operate *exclusively* based on these two files and the autonomous loop described above. (A good system prompt is crucial for enforcement!). 84 | * *Example Snippet for System Prompt:* "You are an autonomous AI developer. Operate solely based on `project_config.md` and `workflow_state.md`. Before every action, read `workflow_state.md`, determine state, consult `## Rules`, act accordingly, then immediately update `workflow_state.md`." 85 | 4. **Give the First Task:** The AI will initialize based on `RULE_INIT_01` and ask for the first task. 86 | 87 | ## What about `.cursorrules`? 88 | 89 | The main `.cursorrules` file is now less important for the workflow itself. You might still use it for global Cursor settings (like preferred AI models or global ignores), but the core logic resides in `workflow_state.md`. 90 | 91 | ## License 92 | 93 | This project concept is licensed under the MIT License - see the LICENSE file for details. 94 | 95 | ## Contributing 96 | 97 | Feel free to adapt and improve this system. Share your experiences and refinements! 98 | -------------------------------------------------------------------------------- /project_config.md: -------------------------------------------------------------------------------- 1 | # project_config.md 2 | Last-Updated: 2025-01-16 3 | 4 | ## Project Goal 5 | Describe the primary objective of your project in 1-2 sentences. 6 | 7 | ## Tech Stack 8 | - **Language(s):** e.g. TypeScript 5, Python 3.12 9 | - **Framework(s):** e.g. Next.js 14, FastAPI 0.111 10 | - **Build / Tooling:** esbuild, Poetry, Docker, etc. 11 | 12 | ## Critical Patterns & Conventions 13 | List coding standards, architectural patterns, naming conventions, and style guides that must be followed. 14 | 15 | ## Constraints 16 | - Performance / latency budgets 17 | - Security or compliance requirements 18 | - External APIs with rate limits or cost ceilings 19 | 20 | ## Tokenization Settings 21 | - Estimated chars-per-token: 3.5 22 | - Max tokens per message: 8 000 23 | - Plan for summary when **workflow_state.md** exceeds ~12 K chars. 24 | 25 | --- 26 | 27 | ## Changelog 28 | 29 | -------------------------------------------------------------------------------- /workflow_state.md: -------------------------------------------------------------------------------- 1 | # workflow_state.md 2 | _Last updated: 2025-01-16_ 3 | 4 | ## State 5 | Phase: INIT 6 | Status: READY 7 | CurrentItem: null 8 | 9 | ## Plan 10 | 11 | 12 | ## Rules 13 | > **Keep every major section under an explicit H2 (`##`) heading so the agent can locate them unambiguously.** 14 | 15 | ### [PHASE: ANALYZE] 16 | 1. Read **project_config.md**, relevant code & docs. 17 | 2. Summarize requirements. *No code or planning.* 18 | 19 | ### [PHASE: BLUEPRINT] 20 | 1. Decompose task into ordered steps. 21 | 2. Write pseudocode or file-level diff outline under **## Plan**. 22 | 3. Set `Status = NEEDS_PLAN_APPROVAL` and await user confirmation. 23 | 24 | ### [PHASE: CONSTRUCT] 25 | 1. Follow the approved **## Plan** exactly. 26 | 2. After each atomic change: 27 | - run test / linter commands specified in `project_config.md` 28 | - capture tool output in **## Log** 29 | 3. On success of all steps, set `Phase = VALIDATE`. 30 | 31 | ### [PHASE: VALIDATE] 32 | 1. Rerun full test suite & any E2E checks. 33 | 2. If clean, set `Status = COMPLETED`. 34 | 3. Trigger **RULE_ITERATE_01** when applicable. 35 | 36 | --- 37 | 38 | ### RULE_INIT_01 39 | Trigger ▶ `Phase == INIT` 40 | Action ▶ Ask user for first high-level task → `Phase = ANALYZE, Status = RUNNING`. 41 | 42 | ### RULE_ITERATE_01 43 | Trigger ▶ `Status == COMPLETED && Items contains unprocessed rows` 44 | Action ▶ 45 | 1. Set `CurrentItem` to next unprocessed row in **## Items**. 46 | 2. Clear **## Log**, reset `Phase = ANALYZE, Status = READY`. 47 | 48 | ### RULE_LOG_ROTATE_01 49 | Trigger ▶ `length(## Log) > 5 000 chars` 50 | Action ▶ Summarise the top 5 findings from **## Log** into **## ArchiveLog**, then clear **## Log**. 51 | 52 | ### RULE_SUMMARY_01 53 | Trigger ▶ `Phase == VALIDATE && Status == COMPLETED` 54 | Action ▶ 55 | 1. Read `project_config.md`. 56 | 2. Construct the new changelog line: `- `. 57 | 3. Find the `## Changelog` heading in `project_config.md`. 58 | 4. Insert the new changelog line immediately after the `## Changelog` heading and its following newline (making it the new first item in the list). 59 | 60 | --- 61 | 62 | ## Items 63 | | id | description | status | 64 | |----|-------------|--------| 65 | 66 | ## Log 67 | 68 | 69 | ## ArchiveLog 70 | 71 | --------------------------------------------------------------------------------