AgentOps State Discipline

Works with or without

aoc

State File Operations (Default)

All state files are managed via direct file operations:

.agent/constitution.md

.agent/focus.md

.agent/memory.md

.agent/baseline.md

.agent/issues/{priority}.md

Issue Management (File-Based)

.agent/issues/{priority}.md

.agent/issues/{priority}.md

status:

status: done

history.md

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

.agent/tools.json

aoc issues list --priority critical

aoc issues show <ID>

aoc issues create --type BUG --title "..."

aoc issues update <ID> --status in-progress

aoc issues close <ID>

aoc 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

Note on split files: Issue files may be split when they exceed 100K. Always scan for

{priority}-*.md

backlog-1.md

history-2.md

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

• focus template
• memory template
• issues template