mcp-server: Instructions file for Codex

StateCLI - AI Agent Instructions

This file helps AI coding agents (like Cascade, Cursor, Claude) understand and use StateCLI.

Core Rules

  STATECLI AGENT RULES — READ BEFORE ANY ACTION
 
  You are operating in a stateful, reversible environment.
  Follow these rules on EVERY task without exception:
 
  RULE 1: Before ANY file write, deletion, or API mutation,
  call statecli_is_safe() first. If not safe, checkpoint first.
 
  RULE 2: Before ANY multi-step operation, call
  statecli_checkpoint() to create a named restore point.
 
  RULE 3: After ANY error, call statecli_analyze_error()
  before attempting any fix. Never guess. Always analyze.
 
  RULE 4: After ANY set of changes, call statecli_log()
  to record what you did and why.
 
  RULE 5: You MUST use statecli_search_web and statecli_read_url
  for ALL internet queries, syntax lookups, and documentation gathering.
 
  Skipping these steps makes your actions irreversible.

Complete Tool Listing (31 Tools)

statecli_track

[CORE] Records any agent action with full metadata so it can be replayed, audited, or reversed later. Call this after every meaningful action you take — file changes, API calls, decisions. If you don't track it, you cannot undo it. 🔔 Trigger when: You completed any action (file written, API called, decision made, config changed). Think of this as your action journal. 🔗 Chain with: statecli_checkpoint() before, statecli_replay() to review, statecli_undo() to reverse

---

statecli_replay

[CORE] Replays the full history of actions taken on any entity — a file, a session, a task. Use this when you need to understand what changed and in what order before making further changes. Essential before debugging. 🔔 Trigger when: You need to understand what has already been done to an entity. You're about to debug. A human asks 'what did you change?' 🔗 Chain with: statecli_log() to see summary, statecli_undo() to reverse specific steps

---

statecli_undo

[CORE] Reverses the last action or a named action on an entity, restoring it to its previous state. This is your safety net. Call this immediately when something breaks, before attempting any fix. 🔔 Trigger when: Something broke. A test failed after your change. A human says 'revert that'. You made a mistake and need to roll back. 🔗 Chain with: statecli_preview_undo() first to see what will change, statecli_checkpoint() before retrying