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:

Issue Management (File-Based)

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:

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

• focus template
• memory template
• issues template