Skip to content

diegosouzapw/awesome-omni-skill / skills/ai-agents/agent-ops-state

agent-ops-state

Verified

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

AgentOps State Discipline

Works with or without aoc CLI installed. State management uses direct file operations by default.

State File Operations (Default)

All state files are managed via direct file operations:

FileOperations
.agent/constitution.mdRead/write directly
.agent/focus.mdRead/write directly
.agent/memory.mdRead/write directly
.agent/baseline.mdRead/write directly
.agent/issues/{priority}.mdRead/append/edit directly

Issue Management (File-Based)

OperationHow to Do It
List issues by priorityRead .agent/issues/{priority}.md directly
Show issue detailsSearch for issue ID in priority files
Create issueAppend to appropriate .agent/issues/{priority}.md file
Update issue statusEdit status: field directly in file
Close issueSet status: done + move to history.md
Get summaryCount issues across priority files

Git Status

# Check current branch
git branch --show-current

# Check for uncommitted changes
git status --porcelain

# Get last commit hash
git rev-parse --short HEAD

CLI Integration (when aoc is available)

When aoc CLI is detected in .agent/tools.json, these commands provide convenience shortcuts:

OperationCLI Command
List issues by priorityaoc issues list --priority critical
Show issue detailsaoc issues show <ID>
Create issueaoc issues create --type BUG --title "..."
Update issue statusaoc issues update <ID> --status in-progress
Close issueaoc issues close <ID>
Get summaryaoc issues summary

Note: CLI is optional — all operations can be performed via direct file editing.

When to Use

  • At the start of a session/response
  • After any meaningful step (analysis/plan decision/implementation/test run)
  • When adding/updating issues
  • Before concluding a response

Session Start

At session start:

  1. Check for staleness: Delegate to agent-ops-git stale detection
  2. Read state files in order (see below)
  3. Validate issue dependencies before starting work

Required Reads (in this order)

  1. .agent/constitution.md
  2. .agent/focus.md
  3. .agent/memory.md
  4. .agent/issues/index.md (compact issue summary — read this FIRST for issue overview)
  5. .agent/issues/critical.md and .agent/issues/critical-*.md (only if working on critical)
  6. .agent/issues/high.md and .agent/issues/high-*.md (only if working on high)
  7. .agent/issues/medium.md and .agent/issues/medium-*.md (only if needed)
  8. .agent/issues/low.md and .agent/issues/low-*.md (only if needed)
  9. .agent/baseline.md (if present)

Context Optimization: Read index.md first to understand the issue landscape. Only read full priority files when actively working on an issue from that priority level.

Note on split files: Issue files may be split when they exceed 100K. Always scan for {priority}-*.md files (e.g., backlog-1.md, history-2.md). Oldest issues are in numbered files, newest in the main file.

Required Updates

.agent/focus.md

Must always contain:

  • Session info (last_updated timestamp, branch, last_commit)
  • Just did (what changed since last update)
  • Doing now (current objective + issue ID if working on one)
  • Next (single best next step + prerequisites/unknowns)

.agent/issues/{priority}.md

  • Issues stored by priority: critical.md, high.md, medium.md, low.md
  • Only use the repo issue format (see template)
  • Create issues for follow-ups, blockers, open questions, approvals needed
  • Validate depends_on before starting an issue

.agent/memory.md

  • Only store durable learnings (workflow rules, stable conventions)
  • Do not duplicate constitution content

Dependency Validation

Before starting an issue:

  1. Read issue's depends_on field
  2. Search all priority files for dependency issues
  3. Check each dependency's status
  4. If any dependency is not done: mark issue as blocked, note which
  5. Only proceed if all dependencies satisfied

Templates

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall