diff --git a/README.md b/README.md index 63c6a2ff..79f7a950 100644 --- a/README.md +++ b/README.md @@ -286,6 +286,7 @@ By creating a `.cursorrules` file in your project's root directory, you can leve ### Utilities - [Cursor Watchful Headers](https://github.com/johnbenac/cursor-watchful-headers) - A Python-based file watching system that automatically manages headers in text files and maintains a clean, focused project tree structure. Perfect for maintaining consistent file headers and documentation across your project, with special features to help LLMs maintain better project awareness. +- [OSOP Session Logging](./rules/osop-session-logging-cursorrules-prompt-file/.cursorrules) - Cursor rules for recording AI coding sessions as structured `.osop` + `.osoplog.yaml` workflow logs using the [OSOP protocol](https://github.com/Archie0125/osop-spec). View logs at [osop-editor.vercel.app](https://osop-editor.vercel.app). ## Directories diff --git a/rules-new/osop-session-logging.mdc b/rules-new/osop-session-logging.mdc new file mode 100644 index 00000000..85d460a0 --- /dev/null +++ b/rules-new/osop-session-logging.mdc @@ -0,0 +1,108 @@ +--- +description: OSOP session logging - record AI coding sessions as structured .osop + .osoplog.yaml files for reproducibility and observability. Apply after completing multi-step tasks. +globs: +alwaysApply: true +--- +# OSOP Session Logging + +After completing a significant task (multi-step work, not trivial one-liners), produce an **OSOP session log** so there is a structured, portable record of what was done. + +1. **Create a `.osop` file** describing the workflow you followed +2. **Create a `.osoplog.yaml` file** recording what you actually did +3. **Tell the user** to open both files at https://osop-editor.vercel.app + +## .osop format (workflow definition) + +```yaml +osop_version: "1.0" +id: "session-" +name: "" +description: "<1-2 sentence summary>" +version: "1.0.0" +tags: [cursor, ] + +nodes: + - id: "" + type: "" # human, agent, mcp, cli, api, cicd, git, db, docker, infra, system, event, gateway, data + subtype: "" # Optional: llm, explore, plan, worker, tool, test, commit, rest, script + name: "" + description: "" + security: + risk_level: "" + +edges: + - from: "" + to: "" + mode: "sequential" # sequential, parallel, conditional, fallback, error, spawn, loop, timeout +``` + +## .osoplog.yaml format (execution record) + +```yaml +osoplog_version: "1.0" +run_id: "" +workflow_id: "" +mode: "live" +status: "COMPLETED" + +trigger: + type: "manual" + actor: "user" + timestamp: "" + +started_at: "" +ended_at: "" +duration_ms: + +runtime: + agent: "cursor" + model: "" + +node_records: + - node_id: "" + node_type: "" + attempt: 1 + status: "COMPLETED" + started_at: "" + ended_at: "" + duration_ms: + outputs: + + tools_used: + - { tool: "", calls: } + reasoning: + question: "" + selected: "" + confidence: <0.0-1.0> + +result_summary: "<1-2 sentence summary>" +``` + +## Node type mapping + +| Agent Action | OSOP Node Type | Subtype | +|---|---|---| +| Read/explore files | `mcp` | `tool` | +| Edit/write files | `mcp` | `tool` | +| Run shell commands | `cli` | `script` | +| Run tests | `cicd` | `test` | +| Git operations | `git` | `commit` / `branch` / `pr` | +| Analyze/reason about code | `agent` | `llm` | +| Search codebase | `mcp` | `tool` | +| Ask user a question | `human` | `input` | +| User reviews/approves | `human` | `review` | +| API calls | `api` | `rest` | + +## Where to save + +Save to `sessions/` in the project root: +- `sessions/YYYY-MM-DD-.osop` +- `sessions/YYYY-MM-DD-.osoplog.yaml` + +## When to generate + +- After completing multi-step tasks (3+ distinct steps) +- After debugging sessions +- After feature implementations +- After refactoring work +- When the user asks "what did you do?" diff --git a/rules/osop-session-logging-cursorrules-prompt-file/.cursorrules b/rules/osop-session-logging-cursorrules-prompt-file/.cursorrules new file mode 100644 index 00000000..5cdc252c --- /dev/null +++ b/rules/osop-session-logging-cursorrules-prompt-file/.cursorrules @@ -0,0 +1,105 @@ + + +# OSOP Session Logging + +After completing a significant task (multi-step work, not trivial one-liners), produce an **OSOP session log** so there is a structured, portable record of what was done. + +1. **Create a `.osop` file** describing the workflow you followed +2. **Create a `.osoplog.yaml` file** recording what you actually did +3. **Tell the user** to open both files at https://osop-editor.vercel.app + +## .osop format (workflow definition) + +```yaml +osop_version: "1.0" +id: "session-" +name: "" +description: "<1-2 sentence summary>" +version: "1.0.0" +tags: [cursor, ] + +nodes: + - id: "" + type: "" # human, agent, mcp, cli, api, cicd, git, db, docker, infra, system, event, gateway, data + subtype: "" # Optional: llm, explore, plan, worker, tool, test, commit, rest, script + name: "" + description: "" + security: + risk_level: "" + +edges: + - from: "" + to: "" + mode: "sequential" # sequential, parallel, conditional, fallback, error, spawn, loop, timeout +``` + +## .osoplog.yaml format (execution record) + +```yaml +osoplog_version: "1.0" +run_id: "" +workflow_id: "" +mode: "live" +status: "COMPLETED" + +trigger: + type: "manual" + actor: "user" + timestamp: "" + +started_at: "" +ended_at: "" +duration_ms: + +runtime: + agent: "cursor" + model: "" + +node_records: + - node_id: "" + node_type: "" + attempt: 1 + status: "COMPLETED" + started_at: "" + ended_at: "" + duration_ms: + outputs: + + tools_used: + - { tool: "", calls: } + reasoning: + question: "" + selected: "" + confidence: <0.0-1.0> + +result_summary: "<1-2 sentence summary>" +``` + +## Node type mapping + +| Agent Action | OSOP Node Type | Subtype | +|---|---|---| +| Read/explore files | `mcp` | `tool` | +| Edit/write files | `mcp` | `tool` | +| Run shell commands | `cli` | `script` | +| Run tests | `cicd` | `test` | +| Git operations | `git` | `commit` / `branch` / `pr` | +| Analyze/reason about code | `agent` | `llm` | +| Search codebase | `mcp` | `tool` | +| Ask user a question | `human` | `input` | +| User reviews/approves | `human` | `review` | +| API calls | `api` | `rest` | + +## Where to save + +Save to `sessions/` in the project root: +- `sessions/YYYY-MM-DD-.osop` +- `sessions/YYYY-MM-DD-.osoplog.yaml` + +## When to generate + +- After completing multi-step tasks (3+ distinct steps) +- After debugging sessions +- After feature implementations +- After refactoring work +- When the user asks "what did you do?"