Skip to content
/

cursor-coding-agent-os (Mugiwara555343)

cursor-coding-agent-os · Mugiwara555343/cursor-coding-agent-os · ★ 3 · last commit 2025-08-05

Lean/Verbose dual-mode Agent OS fork for solo developers on token budgets.

Best whenEvery instruction phase should have both a fast (lean) and thorough (verbose) variant — cost and quality are a developer-controlled tradeoff.
Skip ifGenerating code before analysis is complete, Executing without explicit [EXECUTE] token
vs seeds
superpowers(autonomous skill activation), this framework is explicitly human-gated at every execution step.
Primitive shape 6 total
Commands 4 Skills 2
00

Summary

cursor-coding-agent-os — Summary

cursor-coding-agent-os is a fork of Brian Casel's Agent OS framework (buildermethods/agent-os), purpose-built for solo developers working with low-budget or local LLMs (o3/o4-mini, etc.). The author has split every instruction file into two variants — Lean (60-80% token reduction, used for diagnostics and fast execution) and Verbose (full architectural context, used for planning and spec creation) — while preserving the four-phase Agent OS workflow (Analyze → Plan → Spec → Execute). It targets Cursor specifically, writing .mdc rule files, though the underlying markdown format works in any AI coding IDE. The framework ships strict execution gates: the Lean execute file requires explicit [EXECUTE] confirmation before any code runs, [MODIFY-FS] before file system operations, and maintains a rollback policy with timestamped diffs. Standards files (best-practices.md, code-style.md, tech-stack.md) encode project-specific norms that override global defaults per-product.

differs_from_seeds: Closest to agent-os (the direct upstream seed). Like agent-os, this is a markdown-scaffold framework with no commands, hooks, MCP, or subagents — the value lives in the standards/ and instructions/ file content. The specific delta is the Lean/Verbose dual-mode split: every MDC instruction file has a token-optimized variant, something the upstream agent-os seed does not have. Compared to superpowers (skills-only behavioral), this framework relies on explicit gate commands ([EXECUTE], [NEXT], [STOP]) rather than autonomous skill activation, making the human approval loop more prominent.

01

Overview

cursor-coding-agent-os — Overview

Origin

Fork of buildermethods/agent-os by GitHub user Mugiwara555343. Created circa 2025 as a personal adaptation for solo developers working under token budget constraints. The original Agent OS framework was created by Brian Casel of Builder Methods.

Philosophy

"This fork adapts Brian Casel's Agent OS instruction set for solo builders who need low-token speed where it matters and rich, self-documenting detail where it helps."

The author's central insight is that a single prompt size does not fit all workflow stages. Fast diagnostic and execution phases benefit from lean, compressed prompts; architectural planning and spec-writing benefit from verbose, self-documenting instructions. The fork maintains both so developers can trade off between cost and guidance depth dynamically.

Manifesto-style principles (from instruction files)

From analyze-product-v2.md:

"You are a software agent embedded within the Agent OS architecture. You prioritize precision, traceability, and correctness over speed. Your job is to: Validate architectural and formatting consistency, Prevent premature code execution, Encourage structured reasoning and confirmation loops before acting."

"Never generate code unless an analysis summary has been completed. Wait for an explicit [EXECUTE] command before producing implementation. If any ambiguity exists, pause and ask for clarification."

From execute-tasks-v2.md:

"Treat all tasks as potentially irreversible. Before executing, summarize the task's purpose in plain language. Confirm file paths and scope before modifying any code or data. Maintain idempotent actions unless instructed otherwise. Never create, move, or delete files unless [MODIFY-FS] is explicitly given."

Upstream Credit

The README explicitly thanks Brian Casel and the Builder Methods project:

"Huge thanks to Brian Casel and the Builder Methods / Agent OS project for the original concept and structure. This fork simply tailors that work for a lean, single-developer workflow."

Target Audience

Solo developers and small teams using local LLMs or API-billed frontier models (o3, o4-mini) where token cost is a real constraint. Users who want the Agent OS workflow discipline without the verbosity cost of the original prompts.

02

Architecture

cursor-coding-agent-os — Architecture

Distribution

Standalone repository — clone and copy. No npm package, no CLI, no MCP server. Installation is manual file copy.

Install

git clone https://github.com/Mugiwara555343/cursor-coding-agent-os
# Copy commands/ → ~/.agent-os/instructions/ (referenced with @~/.agent-os/... in Cursor)
# Copy instructions/ → ~/.agent-os/instructions/ (Lean variant files)
# Copy standards/ → ~/.agent-os/standards/

Cursor is the primary IDE target (files use .mdc naming convention and the @~/.agent-os/ path syntax). The framework also works with Claude Code and any AI coding tool that reads markdown files.

Directory Tree

cursor-coding-agent-os/
├── README.md
├── LICENSE
├── setup.sh                    # Shell setup helper
├── setup-cursor.sh             # Cursor-specific setup
├── commands/                   # "Verbose" command stubs (thin wrappers)
│   ├── analyze-product.md      # -> references ~/.agent-os/instructions/analyze-product.md
│   ├── create-spec.md          # -> references ~/.agent-os/instructions/create-spec.md
│   ├── execute-tasks.md        # -> references ~/.agent-os/instructions/execute-tasks.md
│   └── plan-product.md         # -> references ~/.agent-os/instructions/plan-product.md
├── instructions/               # "Lean" variant instruction files
│   ├── README.md
│   ├── analyze-product-v2.md   # Lean analyze (60-80% fewer tokens)
│   └── execute-tasks-v2.md     # Lean execute (with explicit gate commands)
└── standards/                  # Project-level standards (override global)
    ├── best-practices.md
    ├── code-style.md
    └── tech-stack.md

File Formats

  • Commands (.md): Thin one-line stubs that reference the real instruction via @~/.agent-os/instructions/<file>.md. Cursor resolves the @ path at prompt-injection time.
  • Instructions (.md with YAML front matter): Full behavioral prompts using XML structural tags (<ai_meta>, <role>, <parsing_rules>, <thinking_loop>, <execution_mode>, etc.)
  • Standards (.md): Plain markdown reference documents for best-practices, code-style, and tech-stack.

Rule File Format Details

The Lean instruction files use YAML front matter + structured XML sections:

version: 1.1
encoding: UTF-8
---
<ai_meta>
  <role>...</role>
  <parsing_rules>...</parsing_rules>
  <thinking_loop>...</thinking_loop>
  <execution_mode>...</execution_mode>
  <rollback_policy>...</rollback_policy>
</ai_meta>

This is distinct from Cursor's native .mdc format (which uses ---description/globs/alwaysApply--- front matter), but the files serve the same purpose when injected into context.

Target AI Tools

Primary: Cursor IDE (MDC path syntax) Secondary: Claude Code (via @ path references), any AI coding tool that reads markdown

Required Runtime

None beyond a text editor and AI coding IDE. Shell scripts (setup.sh, setup-cursor.sh) require bash.

03

Components

cursor-coding-agent-os — Components

Commands (4 total — Verbose stubs)

Name File Purpose
analyze-product commands/analyze-product.md Stub: delegates to ~/.agent-os/instructions/analyze-product.md for full product analysis
create-spec commands/create-spec.md Stub: delegates to ~/.agent-os/instructions/create-spec.md for feature spec creation
execute-tasks commands/execute-tasks.md Stub: delegates to ~/.agent-os/instructions/execute-tasks.md for task execution
plan-product commands/plan-product.md Stub: delegates to ~/.agent-os/instructions/plan-product.md for product planning

Instructions / Lean Variants (2 shipped, 2 from upstream)

Name File Purpose
analyze-product-v2 (Lean) instructions/analyze-product-v2.md Token-optimized analysis: install Agent OS, analyze codebase, generate docs. Enforces thinking loop + explicit EXECUTE gate
execute-tasks-v2 (Lean) instructions/execute-tasks-v2.md Token-optimized execution: step-by-step task execution with [EXECUTE], [NEXT], [STOP] gates and rollback policy

Standards (3 total)

Name File Purpose
best-practices standards/best-practices.md Global dev best practices: simplicity, readability, DRY, dependency selection, testing, file structure
code-style standards/code-style.md Code formatting and style conventions (project-level overrides apply)
tech-stack standards/tech-stack.md Technology stack declaration for the project

Scripts (2 total)

Name File Purpose
setup.sh setup.sh General Agent OS setup helper
setup-cursor.sh setup-cursor.sh Cursor-specific setup (installs files to Cursor config paths)

Hooks

None. Zero hooks shipped.

MCP Servers

None.

Templates

The standards files (best-practices.md, code-style.md, tech-stack.md) serve as templates for project-specific overrides.

05

Prompts

cursor-coding-agent-os — Prompts

Prompt 1: analyze-product-v2.md (Lean Analyze)

Technique: Structured XML behavioral framing with explicit thinking loop and gate-based execution control.

version: 1.1
encoding: UTF-8
---

# Analyze Current Product & Install Agent OS

<ai_meta>

<role>
You are a software agent embedded within the Agent OS architecture. You prioritize precision, traceability, and correctness over speed. Your job is to:
- Validate architectural and formatting consistency
- Prevent premature code execution
- Encourage structured reasoning and confirmation loops before acting
</role>

<parsing_rules>
- Always process XML or structured data blocks first before generating any code.
- Never generate code unless an analysis summary has been completed.
- Wait for an explicit [EXECUTE] command before producing implementation.
- If any ambiguity exists, pause and ask for clarification.
</parsing_rules>

<thinking_loop>
1. Determine the task type (e.g., analyze, generate, refactor, debug).
2. Validate the inputs (code snippet, intent, attached files).
3. Propose a clear, short plan of action (2–3 sentences).
4. Wait for user confirmation before continuing.
</thinking_loop>

<sanity_checks>
- Review output for unintended side effects before writing code.
- Ensure responses match the framework/language being used.
- Annotate any non‑obvious logic or assumptions in code suggestions.
</sanity_checks>

</ai_meta>

Technique: Role injection + behavioral constraints via XML tags. "Never generate code unless analysis is complete" is a gate-based anti-hallucination constraint. The <thinking_loop> functions as a meta-reasoning scaffold injected at prompt parse time.


Prompt 2: execute-tasks-v2.md (Lean Execute)

Technique: Safety-oriented task execution with explicit filesystem permission model and rollback policy.

<role>
You are a task execution assistant embedded in the Agent OS environment. You carry out planned operations cautiously and only upon clear approval. You act deliberately, confirm often, and prioritize system safety over speed.
</role>

<execution_mode>
- Treat all tasks as potentially irreversible.
- Before executing, summarize the task's purpose in plain language.
- Confirm file paths and scope before modifying any code or data.
- Maintain idempotent actions unless instructed otherwise.
- Never create, move, or delete files unless [MODIFY-FS] is explicitly given.
</execution_mode>

<rollback_policy>
- Provide a diff or step summary for each executed change.
- Ensure reversibility of all steps, or explain why the action is irreversible.
- Maintain a logical undo path unless explicitly told to skip it.
</rollback_policy>

Technique: Declarative behavioral policy expressed as named XML sections. The <execution_mode> and <rollback_policy> sections function as domain-specific system constraints. The [MODIFY-FS] gate pattern is a novel permission token that requires explicit human authorization before any destructive filesystem operation.


Prompt 3: standards/best-practices.md

Technique: Reference document injected into context as persistent project standards. Encodes opinions as principles.

## Core Principles

### Keep It Simple
- Implement code in the fewest lines possible
- Avoid over-engineering solutions
- Choose straightforward approaches over clever ones

### Optimize for Readability
- Prioritize code clarity over micro-optimizations
- Write self-documenting code with clear variable names
- Add comments for "why" not "what"

Technique: Opinionated declarative standards document. Acts as a persistent behavioral anchor when injected into the AI context alongside task prompts. The "fewer lines" and "no over-engineering" constraints directly counter verbosity tendencies in LLMs.

09

Uniqueness

cursor-coding-agent-os — Uniqueness

differs_from_seeds

This framework is a direct fork of agent-os (the seed archetype for "Markdown scaffold, zero primitives"). It shares agent-os's core DNA: no commands, no hooks, no MCP — the value is entirely in the structured markdown content. The key architectural delta is the Lean/Verbose dual-mode split: every instruction file ships in two sizes, with the Lean variants running 60-80% smaller for token-constrained environments (local LLMs, o3/o4-mini). The upstream agent-os seed has no such dual-mode concept. Additionally, this fork introduces named permission gate tokens ([EXECUTE], [MODIFY-FS], [GENERATE-TESTS]) as explicit human authorization checkpoints embedded in the instruction prose — a more granular safety model than the upstream's implicit approval flow. Compared to superpowers (the skills-only behavioral archetype), this framework is more human-in-the-loop by design, requiring typed gate tokens rather than relying on autonomous skill activation.

Positioning

  • Upstream relationship: Direct fork of buildermethods/agent-os
  • Niche: Solo developers, local LLMs, token-budget-sensitive workflows
  • Competitive position: More token-efficient than upstream agent-os; more structured than raw Agent OS with its explicit gate tokens; less automated than frameworks like superpowers or spec-kit

Observable Failure Modes

  1. Gate token friction: Requiring [EXECUTE] before every code change adds human round-trips that slow development velocity significantly.
  2. No automated memory: The lack of session persistence means context must be manually re-injected each session — breaks down on long-running projects.
  3. Upstream dependency: The "Verbose" command stubs reference files from the upstream agent-os install (~/.agent-os/instructions/). If the upstream changes breaking its interface, the stubs silently fail.
  4. Lean instruction correctness: The execute-tasks-v2.md file contains a Python script artifact in the raw GitHub content (appears to be a notebook-generated artifact that leaked into the markdown), suggesting the Lean files may not always be clean prompts.
  5. Low adoption signal: 3 stars, 0 forks — likely a personal configuration that has not been battle-tested by a diverse user base.
04

Workflow

cursor-coding-agent-os — Workflow

Phases

Phase Command Lean Variant? Artifact Produced
1. Analyze analyze-product Yes (analyze-product-v2.md) Product state documentation, architectural review
2. Plan plan-product No (uses upstream) IMPLEMENTATION_PLAN.md (or equivalent)
3. Specify create-spec No (uses upstream) Feature spec document
4. Execute execute-tasks Yes (execute-tasks-v2.md) Implemented code changes with timestamped diffs

Approval Gates

All gates are explicit command-word based (typed by the human in the chat):

Gate Token Trigger Point Effect
[EXECUTE] Before any code generation or implementation Required confirmation to proceed from analysis to execution
[NEXT] After each step in execution Advance to next step
[CLARIFY] Any ambiguous step Request clarification before proceeding
[STOP] Any step Halt all execution
[MODIFY-FS] Before file creation, move, or deletion Explicit authorization for filesystem changes
[GENERATE-TESTS] Before test stub generation Explicit authorization for test creation
[START] Beginning of execution phase Triggers first execution step

Phase-to-Artifact Map

Phase Artifact
Analyze Architectural review doc, gap analysis
Plan Product plan, implementation phases
Specify Feature spec with technical details + task breakdown
Execute Staged code changes, timestamped diffs, rollback log

Execution Safety Protocol

From execute-tasks-v2.md:

  1. Summarize task purpose in plain language before each step
  2. Confirm file paths and scope before modifying code
  3. Maintain idempotent actions unless told otherwise
  4. Never create/move/delete files without [MODIFY-FS]
  5. Provide diff/step summary for each change
  6. Ensure reversibility, or explain why action is irreversible
  7. Maintain logical undo path

Thinking Loop (Analyze phase)

From analyze-product-v2.md:

  1. Determine task type (analyze, generate, refactor, debug)
  2. Validate inputs (code snippet, intent, attached files)
  3. Propose a clear, short plan of action (2-3 sentences)
  4. Wait for user confirmation before continuing
06

Memory Context

cursor-coding-agent-os — Memory & Context

State Storage

File-based, project-scoped. No database, no vector store.

The framework inherits Agent OS's memory model:

  • .agent-os/product/ — product state docs (PRD, tech stack, architecture)
  • .agent-os/specs/<feature>/ — per-feature spec files
  • standards/ — global project standards (override per-project)

Persistence

Project-level persistence: The spec and standards files persist across sessions as markdown files checked into the project repository.

Session state: Not persisted. Each command invocation starts fresh with whatever files are currently in .agent-os/.

Context Injection Pattern

Commands reference upstream instruction files via @~/.agent-os/instructions/<file>.md — Cursor resolves these at prompt injection time. The effective context for each session = task prompt + referenced instruction file + relevant standards files manually included.

Compaction

None. No explicit compaction handling. Token budget is managed by choosing between Lean (small) and Verbose (large) instruction variants manually.

The Lean variants are the framework's token management strategy — instead of automated compaction, the developer picks the right-sized instruction file per task.

Cross-Session Handoff

No automated handoff mechanism. The product state docs in .agent-os/product/ serve as implicit session memory — re-injecting these at the start of a new session provides continuity.

Memory Type Summary

Dimension Value
Memory type file-based
Persistence scope project
State files .agent-os/product/*.md, .agent-os/specs/**/*.md, standards/*.md
Search mechanism none (manual injection)
Compaction none (manual Lean/Verbose selection)
07

Orchestration

cursor-coding-agent-os — Orchestration

Multi-Agent

No. Single-agent framework. No subagents, no spawning, no delegation.

Orchestration Pattern

Sequential. The workflow moves linearly through Analyze → Plan → Spec → Execute phases.

Isolation Mechanism

None. All changes are made in-place to the working directory. No git branch or worktree isolation is enforced by the framework (though the rollback policy in execute-tasks-v2 requires timestamped diffs per change).

Multi-Model

No. The framework is model-agnostic but does not route different models to different tasks. The Lean/Verbose split is about prompt size, not model selection.

Execution Mode

Interactive-loop. Every phase requires explicit human gate tokens ([EXECUTE], [NEXT], [START], etc.) before proceeding.

Crash Recovery

No explicit crash recovery mechanism. The rollback policy documents reversibility, but recovery depends on the developer restoring from diffs.

Context Compaction

No automated compaction. The developer manually selects Lean vs Verbose instructions to manage token budget.

Consensus Mechanism

None.

Prompt Chaining

Yes (implicit). The Analyze phase output (architectural review) is intended to be fed as context into the Plan phase, which feeds into Spec, which feeds into Execute. The chain is manual (developer copies/references outputs).

Summary Table

Dimension Value
Multi-agent no
Orchestration pattern sequential
Max concurrent agents 1
Isolation none
Consensus none
Prompt chaining yes (manual)
Multi-model no
Execution mode interactive-loop
Crash recovery no
08

Ui Cli Surface

cursor-coding-agent-os — UI / CLI Surface

Dedicated CLI Binary

None. No package.json, no binary, no CLI tool.

Local UI / Dashboard

None. No web dashboard, no TUI, no desktop app.

IDE Integration

Primary IDE: Cursor

The framework is designed for Cursor's @path reference syntax:

  • Commands reference instruction files via @~/.agent-os/instructions/<file>.md
  • Standards files are intended to be placed in a Cursor-accessible path
  • The setup-cursor.sh script automates Cursor-specific file placement

Secondary IDE: Claude Code

The original Agent OS upstream supports Claude Code equally. This fork's lean variants work in Claude Code since they are plain markdown.

Other IDEs: Any AI coding IDE that supports markdown file injection (Cline, Windsurf) can use the standards and instruction files, but the @~/.agent-os/ path syntax is Cursor-specific.

Observability

None. No logging, no audit trail, no activity file. The rollback policy in execute-tasks-v2 requires the agent to document timestamped diffs, but there is no automated observability infrastructure.

Setup Scripts

Script Purpose
setup.sh General setup — copies files to ~/.agent-os/
setup-cursor.sh Cursor-specific setup — places files at Cursor config paths

Cross-Tool Portability

Medium. The instruction content is IDE-agnostic markdown, but the @~/.agent-os/ path syntax is Cursor-specific. The Lean/Verbose variants and gate token approach work equally well in Claude Code or any markdown-aware AI IDE.

Related frameworks

same archetype · same primary tool · same memory type

Context Mode ★ 16k

Keeps raw tool output data out of the context window via sandbox execution and SQLite+FTS5 session indexing, reducing context…

lean-ctx ★ 2.2k

A full-session context runtime that compresses file reads (10 modes), shell output (60+ patterns), and session memory (CCP) to…

Nemp Memory ★ 101

Persists AI agent context across sessions as 100%-local plain JSON files with zero dependencies, zero cloud, and agent identity…

CogniLayer v4 ★ 28

Provides AI coding agents with typed semantic memory, tree-sitter code intelligence, and a multi-agent coordination protocol to…

rtk (Real Token Killer) ★ 55k

Intercepts Claude Code's Bash tool calls at the PreToolUse hook and compresses verbose CLI output (git status, test runners,…

Code-Mode Library ★ 1.5k

Replaces traditional tool-calling with TypeScript code execution in a sandbox, collapsing N sequential tool calls into 1 code…