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:

File	Operations
.agent/constitution.md	Read/write directly
.agent/focus.md	Read/write directly
.agent/memory.md	Read/write directly
.agent/baseline.md	Read/write directly
.agent/issues/{priority}.md	Read/append/edit directly

Issue Management (File-Based)

Operation	How to Do It
List issues by priority	Read .agent/issues/{priority}.md directly
Show issue details	Search for issue ID in priority files
Create issue	Append to appropriate .agent/issues/{priority}.md file
Update issue status	Edit status: field directly in file
Close issue	Set status: done + move to history.md
Get summary	Count 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:

Operation	CLI Command
List issues by priority	aoc issues list --priority critical
Show issue details	aoc issues show <ID>
Create issue	aoc issues create --type BUG --title "..."
Update issue status	aoc issues update <ID> --status in-progress
Close issue	aoc issues close <ID>
Get summary	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 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