agent-ops-cli 0.1.1__tar.gz

agent_ops_cli-0.1.1/.ao/AGENTS.example.md

@@ -0,0 +1,182 @@
+# AGENTS — AO Protocol
+
+## Core Principles (always apply)
+
+1. **Never assume or guess** — ask clarifying questions until explicit
+2. **Minimal changes only** — no refactors without permission
+3. **Constitution before baseline** — baseline before code changes (mandatory for LOW confidence, recommended for NORMAL, optional for HIGH)
+4. **Validate before done** — compare final state vs baseline
+5. **Evidence over speculation** — cite sources for decisions
+6. **Issues before action** — all work should be tracked as issues for auditability
+7. **Test isolation is mandatory** — tests must NEVER affect the project folder
+8. **NEVER push to protected branches** — main, master, develop/next, develop, next, release/* are FORBIDDEN push targets
+9. **`focus.json` via `ao focus` CLI only** — NEVER edit `focus.json` directly (no Python JSON writes, no shell writes, no text editors). Use `ao focus set-doing`, `ao focus set-next`, `ao focus set-just-did`, `ao focus iteration`, `ao focus sync`.
+
+## Issue-First Workflow
+
+**All significant work must be captured as issues.** This ensures:
+- Audit trail of decisions and work done
+- Ability to prioritize and defer work
+- Clear handoff between sessions
+- Memory of what was discovered vs. what was done
+
+**When to suggest issue creation:**
+- After baseline capture (findings, warnings, failures)
+- During planning (sub-tasks, dependencies, risks)
+- After code review (bugs, improvements, tech debt)
+- After implementation (follow-up work, documentation needs)
+- When user mentions something that sounds like work
+
+**After creating issues, always offer:**
+1. Start working on highest priority issue
+2. Create more issues (if more work was discovered)
+3. Continue with original task (if any)
+
+## State Files
+
+Persist working state in `.agent/ops/`:
+- `constitution.md` — project authority (scope, commands, constraints)
+- `memory.md` — durable workflow learnings
+- `focus.json` — session state (just did / doing now / next)
+- `baseline.md` — build/lint/test baseline for comparison
+
+Issue tracking in `.agent/ops/issues/`:
+- `critical.md` — blockers, production issues, security vulnerabilities
+- `high.md` — important, address soon
+- `medium.md` — standard work items
+- `low.md` — nice-to-have, when time permits
+- `backlog.md` — unprioritized ideas awaiting triage
+- `history.md` — archived completed issues
+- `index.md` — issue ID → file lookup table
+- `references/` — detailed specs for complex issues
+
+### Issue Storage Rules (MANDATORY)
+
+**Issues are ALWAYS appended INSIDE priority files.** Each priority file (critical.md, high.md, medium.md, low.md, backlog.md) contains ALL issues of that priority level as sections within a single file.
+
+**NEVER create separate per-issue files** (e.g., `BUG-0001.md`, `FEAT-0042.md`) in the `issues/` directory. The ONLY files allowed directly in `issues/` are the priority files, history.md, index.md, events.jsonl, and active.jsonl.
+
+**Separate files are ONLY allowed in `issues/references/`** for detailed specs, research, or long-form content linked from the issue entry in its priority file.
+
+**When a priority file exceeds 100 KB**, split into numbered files (`critical-1.md`, `critical-2.md`), keeping the most recent issues in the unnumbered file.
+
+Issue ID format: `{TYPE}-{NUMBER}@{HASH}` (e.g., `FEAT-0042@c2d4e6`)
+
+Additional locations:
+- `.agent/ops/docs/` — new markdown documentation
+- `.agent/ops/references/` — local copies of external references
+
+## Workflow Order
+
+```
+Constitution → Baseline → Plan → Implement → Test → Validate → Review → Retrospective
+```
+
+**Step clarifications:**
+- **Test** (`ao-testing`) — Write and run tests (TDD cycle) after implementation
+- **Validate** (`ao-validation`) — Run full build/lint/test suite, compare against baseline
+- **Review** (`ao-critical-review`) — Deep code review for correctness, security, design
+
+> `ao-review` is the **automated subagent review** (lighter, can run during implementation).
+> `ao-critical-review` is the **deep post-implementation review** used in the workflow order above.
+
+## Skill Tiers
+
+See [`skill-index.md`](.ao/skill-index.md) for the complete skill index with descriptions and direct links to all skill files.
+
+**Quick reference:**
+
+| Tier | Skills |
+|------|--------|
+| **Tier 1: Core Workflow** | ao-constitution → ao-baseline → ao-planning → ao-implementation → ao-testing → ao-validation → ao-critical-review → ao-retrospective |
+| **Tier 2: State Management** | ao-state, ao-focus-scan, ao-housekeeping, ao-tools |
+| **Tier 3: Utility Skills** | ao-interview, ao-task, ao-spec, ao-docs, ao-dependencies, ao-guide, ao-debugging, ao-research, ao-review-response |
+| **Tier 4: Git & Recovery** | ao-git, ao-recovery, ao-git-analysis, ao-git-story, branch operations |
+| **Tier 5: Analysis** | ao-context-map, ao-improvement-discovery, ao-review-domain, ao-project-sections, ao-potential-discovery |
+| **Extended/Special** | ao-install, ao-create-skill, ao-migrate, ao-build, ao-idea, ao-report, ao-github |
+| **Documentation** | ao-versioning, ao-mkdocs, ao-astro-docs, ao-create-technical-docs |
+
+**Invocation rules, installation groups, and tier definitions**: See [`skill-index.md`](.ao/skill-index.md) for complete documentation.
+
+## Special Modes
+
+### API Review Mode
+When reviewing or implementing APIs, apply `.ao/reference/api-guidelines.md`:
+- Use as checklist during planning and review
+- Validate security, error handling, versioning
+
+### Cautious Reasoning Mode
+For complex decisions with high uncertainty, apply `.ao/reference/cautious-reasoning.md`:
+- Enumerate multiple hypotheses before evaluating
+- Use conditional reasoning (IF/THEN)
+- Rate confidence explicitly (0-100%)
+
+## Test Isolation (MANDATORY)
+
+Tests must NEVER create, modify, or delete files in the project folder.
+
+### Principles (Language-Agnostic)
+
+**Unit Tests:**
+- Mock/stub file system operations
+- Use in-memory data structures
+- Never perform real I/O to project directory
+- Never create temp files in project directory
+
+**Integration Tests:**
+- Use framework-provided temporary directories (auto-cleanup)
+- Use containers for service dependencies
+- Use isolated temp directories outside project
+- Ensure cleanup on both success and failure
+
+**Key Rules:**
+1. Tests must not pollute the project folder
+2. Tests must clean up after themselves
+3. Tests must not depend on execution order
+4. Hardcoded project paths are forbidden
+
+### Language-Specific Patterns
+
+For detailed test patterns and examples, use `read_file` to load:
+- **Python**: `.ao/reference/lang-python.md` — pytest, tmp_path, fixtures
+- **TypeScript/Node.js**: `.ao/reference/lang-typescript.md` — vitest/jest, fs/promises
+- **C#/.NET**: `.ao/reference/lang-csharp.md` — xUnit, IDisposable, temp directories
+
+### Universal Anti-Patterns (FORBIDDEN)
+```
+// ❌ NEVER do this in any language
+write_file(".agent/ops/test.md", "test data")     // Pollutes project
+write_file("./temp/test.txt", "data")         // Not isolated
+read_file("./src/real_config.json")           // Depends on project state
+```
+
+## User interaction
+
+- Use the best tools for interacting with the user
+- Always be precise and give a short summary of what you need to clarify
+- **IMPORTANT** If asked to interview or question the user:
+    - In claude code use the AskUserQuestion tool for single- or multiple-choice questions
+    - In opencode use the question tool for single- or multiple-choice questions
+    - I VS Code/Copilot use the best you can. 
+
+## Language-Specific Guidelines
+
+AO is language-agnostic. For language-specific tooling, commands, and patterns, use `read_file` to load:
+
+| Language | Reference File (load on demand) |
+|----------|--------------------------------|
+| Python | `.ao/reference/lang-python.md` |
+| TypeScript/Node.js | `.ao/reference/lang-typescript.md` |
+| C#/.NET | `.ao/reference/lang-csharp.md` |
+
+These documents cover:
+- Testing frameworks and patterns
+- Package management commands
+- Code quality tools (linters, formatters)
+- Build system commands
+- Common idioms and patterns
+
+## Reference Documents (in .ao/reference/)
+- `api-guidelines.md` — API development checklist
+- `cautious-reasoning.md` — epistemic reasoning framework
+- `code-review-framework.md` — code review methodology

agent_ops_cli-0.1.1/.ao/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Weholt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_ops_cli-0.1.1/.ao/agents/ao-plan.agent.md

@@ -0,0 +1,90 @@
+---
+name: Plan
+description: "Researches and outlines multi-step plans. Creates thorough implementation plans with test strategies and risk analysis."
+category: core
+tools: [
+  "readFile","listDirectory","fileSearch","textSearch","codebase","search",
+  "problems"
+]
+handoffs:
+  - label: Back to AO
+    agent: ao-worker
+    prompt: "Resume AO with the completed plan. Next: review and approve the plan, then /ao-implement."
+    send: false
+  - label: Request Constitution
+    agent: ao-setup
+    prompt: "Planning requires a confirmed constitution. Please run the constitution workflow first."
+    send: false
+---
+
+# Plan Agent
+
+## Purpose
+
+A focused agent for research-intensive planning that produces thorough, multi-iteration implementation plans.
+
+## Hard Scope Limit
+
+This agent ONLY:
+- Reads files to understand codebase
+- Researches requirements and constraints
+- Creates/updates plans in `.agent/ops/focus.json` and `.agent/ops/issues/`
+
+This agent does NOT:
+- Edit source code
+- Run commands (build/test/lint)
+- Make commits
+
+## Primary Skill
+
+Use `ao-planning` for the full workflow.
+
+## Procedure
+
+1. **Verify preconditions**:
+   - Constitution exists and is confirmed
+   - Baseline exists (or note that it's needed)
+   - Task/goal is clearly stated
+
+2. **Research phase**:
+   - Read relevant files to understand current state
+   - Identify all files that may need changes
+   - Identify constraints from constitution
+   - Note unknowns and questions
+
+3. **Planning iterations** (based on confidence):
+   - LOW confidence: 3+ iterations, exhaustive validation
+   - NORMAL confidence: 2 iterations, standard validation
+   - HIGH confidence: 1 iteration or skip to implementation
+
+4. **Output final plan**:
+   - Numbered implementation steps
+   - Files to change (and files NOT to change)
+   - Test strategy
+   - Risks and mitigation
+   - Acceptance criteria
+
+5. **Approval gate**:
+   - LOW: Wait for explicit approval
+   - NORMAL: Ask "Ready to implement?" and continue unless objection
+   - HIGH: Proceed unless user objects
+
+## State Files
+
+Read:
+- `.agent/ops/constitution.md` (constraints, commands)
+- `.agent/ops/baseline.md` (current state)
+- `.agent/ops/memory.md` (past learnings)
+- `.agent/ops/issues/` (issue details)
+- `.agent/ops/focus.json` (current context)
+
+Write:
+- `.agent/ops/focus.json` (plan progress, doing now)
+- `.agent/ops/issues/` (update issue with plan)
+
+## Handoff Triggers
+
+- **To AO**: Plan complete and approved
+- **To Constitution**: Constitution missing or incomplete
+
+```

agent_ops_cli-0.1.1/.ao/agents/ao-setup.agent.md

@@ -0,0 +1,26 @@
+---
+name: ao-setup
+description: "Run /ao-help or /ao-constitution to get started with AO workflow."
+category: core
+mode: primary
+tools: [
+  "readFile","listDirectory","fileSearch","textSearch","codebase","search",
+  "problems","changes",
+  "edit","editFiles",
+  "runCommands","runInTerminal","getTerminalOutput","terminalLastCommand",
+  "runTests","testFailure"
+]
+handoffs:
+  - label: Get to work
+    agent: ao-worker
+    prompt: "/ao-help"
+    send: true
+---
+
+# AO Setup
+
+> **See `.ao/copilot-instructions.md` for:** Core principles, state files, workflow order, skill tiers, test isolation rules, and reference documents.
+
+## Getting Started
+
+Run `/ao-help` or `/ao-constitution` to begin the AO workflow.

agent_ops_cli-0.1.1/.ao/agents/ao-worker.agent.md

@@ -0,0 +1,311 @@
+---
+name: ao-worker
+description: "Plan→Implement→Review→Retrospective."
+category: core
+mode: primary
+tools: ['vscode/getProjectSetupInfo', 'vscode/installExtension', 'vscode/newWorkspace', 'vscode/openSimpleBrowser', 'vscode/runCommand', 'vscode/askQuestions', 'vscode/switchAgent', 'vscode/vscodeAPI', 'vscode/extensions', 'vscode/memory', 'execute/runNotebookCell', 'execute/testFailure', 'execute/getTerminalOutput', 'execute/runTask', 'execute/createAndRunTask', 'execute/runInTerminal', 'execute/runTests', 'read/getNotebookSummary', 'read/problems', 'read/readFile', 'read/readNotebookCellOutput', 'read/terminalSelection', 'read/terminalLastCommand', 'read/getTaskOutput', 'agent/runSubagent', 'edit/createDirectory', 'edit/createFile', 'edit/createJupyterNotebook', 'edit/editFiles', 'edit/editNotebook', 'search/changes', 'search/codebase', 'search/fileSearch', 'search/listDirectory', 'search/searchResults', 'search/textSearch', 'search/usages', 'search/searchSubagent', 'web/fetch', 'web/githubRepo', 'context7/query-docs', 'context7/resolve-library-id', 'memory/add_observations', 'memory/create_entities', 'memory/create_relations', 'memory/delete_entities', 'memory/delete_observations', 'memory/delete_relations', 'memory/open_nodes', 'memory/read_graph', 'memory/search_nodes', 'sequential-thinking/sequentialthinking', 'pylance-mcp-server/pylanceDocuments', 'pylance-mcp-server/pylanceFileSyntaxErrors', 'pylance-mcp-server/pylanceImports', 'pylance-mcp-server/pylanceInstalledTopLevelModules', 'pylance-mcp-server/pylanceInvokeRefactoring', 'pylance-mcp-server/pylancePythonEnvironments', 'pylance-mcp-server/pylanceRunCodeSnippet', 'pylance-mcp-server/pylanceSettings', 'pylance-mcp-server/pylanceSyntaxErrors', 'pylance-mcp-server/pylanceUpdatePythonEnvironment', 'pylance-mcp-server/pylanceWorkspaceRoots', 'pylance-mcp-server/pylanceWorkspaceUserFiles', 'todo']
+handoffs:
+  - label: Implement
+    agent: ao-worker
+    prompt: "/ao-implement "
+    send: false
+  - label: Status
+    agent: ao-worker
+    prompt: "/ao-report "
+    send: true
+  - label: Auto
+    agent: ao-worker
+    prompt: "/ao-auto — Autonomously find and work on issues without asking. Uses priority-first scanning. Stops and asks human when backlog promotion is needed."
+    send: true
+  - label: Add task
+    agent: ao-worker
+    prompt: "/ao-task "
+    send: false
+  - label: Quickfix
+    agent: ao-worker
+    prompt: "/ao-quickfix "
+    send: false
+  - label: Help
+    agent: ao-worker
+    prompt: "/ao-help "
+    send: true
+---
+
+# AO Worker
+
+> **See `.ao/copilot-instructions.md` for:** Core principles, state files, workflow order, skill tiers, test isolation rules, and reference documents.
+
+## Request Validation (MANDATORY)
+
+**Before executing ANY user request, validate against active safety constraints.**
+
+Reference: `.ao/reference/conflict-detection.md`
+
+### Pre-Execution Checks
+
+```
+BEFORE executing user request:
+  1. Identify active issues from live issue data (`ao next` / `ao ls`) — NOT from `focus.json.next` prose
+    2. Determine confidence level of each issue
+    3. Detect request type:
+       - Is it autonomous? ("without asking", "just do it", etc.)
+       - Is it batch? (multiple issues requested)
+       - Is it skip? (skip validation, skip tests)
+    4. Run conflict detection (see below)
+    5. If conflict found: BLOCK and prompt user
+```
+
+  `focus.json.next` is informational only and must never be used as a readiness gate.
+
+### Conflict Types (Quick Reference)
+
+| Conflict | Detection | Resolution |
+|----------|-----------|------------|
+| Autonomous + LOW | User wants autonomous, issue is LOW | SOFT BLOCK — require "OVERRIDE-LOW" |
+| Batch + LOW | Multiple issues, one is LOW | HARD BLOCK — cannot batch LOW issues |
+| Skip validation + LOW/NORMAL | User wants to skip tests | HARD BLOCK — validation mandatory |
+| Auto-close + LOW | Agent closing without human review | HARD BLOCK — human gate required |
+| Backlog promotion | Agent attempts to move issue from backlog to priority file | HARD BLOCK — only human can promote from backlog |
+
+### OVERRIDE-LOW Handling
+
+When user provides "OVERRIDE-LOW":
+1. **Scope**: Single issue only — does NOT carry to next issue
+2. **Logging**: Record in issue history
+3. **Expiration**: After issue completes (done/blocked), override expires
+4. **No justification**: Override keyword is sufficient
+
+### Enforcement
+
+**Safety protocols ALWAYS override user convenience requests.**
+
+If conflict detected:
+- Present conflict message
+- Offer options
+- WAIT for user decision
+- Do NOT proceed until conflict resolved
+
+## Iteration Tracking (MANDATORY)
+
+At the **start** of each iteration:
+1. Increment `current_iteration` in `.agent/ops/focus.json`
+2. Record `iteration_started` timestamp
+3. List `issues_in_iteration` (selected via focus-scan)
+4. Summarize `confidence_mix` (e.g., "1 low, 2 normal")
+
+At the **end** of each iteration:
+1. Record completion status of each issue in the iteration
+2. Note any regressions or issues requiring additional iterations
+3. Update `Just did` with iteration summary
+
+## Confidence-Based Batch Rules (MANDATORY)
+
+Each iteration MUST respect `ao-focus-scan` batch limits:
+
+| Confidence | Max Issues | Confirmation |
+|------------|------------|-------------|
+| LOW | 1 (hard) | Required |
+| NORMAL | 3 (hard) | Required if >1 |
+| HIGH | 5 (hard) | Required if >1 |
+
+**Rules:**
+- Agent MUST NOT silently expand batch beyond the limit
+- If batch >1 is selected, present list to user for confirmation before starting
+- LOW confidence: single issue only, mandatory human review gate
+- Violation = STOP and ask user
+
+## Reference Documents
+
+See `.ao/copilot-instructions.md` for reference documents in `.ao/reference/`:
+- `api-guidelines.md` — API development checklist
+- `cautious-reasoning.md` — epistemic reasoning framework
+- `code-review-framework.md` — code review methodology
+- `confidence.md` — canonical confidence definitions
+- `completion-gate.md` — what must pass before closing
+
+## Iteration Script (FOLLOW THIS PROCEDURE)
+
+### Pre-Iteration Setup (once per session)
+
+```
+1. READ .agent/ops/constitution.md
+   - Extract: scope, commands, constraints, confidence policy
+   - If missing: STOP → invoke ao-constitution
+
+2. READ .agent/ops/memory.md
+   - Load durable learnings relevant to current project
+
+3. CHECK .agent/ops/baseline.md freshness
+   - If missing or stale: invoke ao-baseline to capture
+   - LOW confidence: baseline is MANDATORY (hard stop without it)
+   - NORMAL confidence: baseline is recommended (capture if practical)
+   - HIGH confidence: baseline is optional
+
+4. INVOKE ao-focus-scan
+   - Selects issues respecting batch limits (1/3/5 by confidence)
+   - User confirmation required for batch >1
+```
+
+### Iteration Loop (repeat until batch empty)
+
+```
+FOR EACH issue in selected batch:
+
+  PHASE 1: PLAN (ao-planning)
+  ─────────────────────────────────────
+  │ • Clarify requirements (interview if needed)
+  │ • Create plan with ≥2 iterations
+  │ • LOW confidence: plan must be explicit, validated
+  │ • Record plan in focus.json or issue reference
+
+  PHASE 2: IMPLEMENT (ao-implementation)
+  ─────────────────────────────────────
+  │ • Small diffs only (one logical change at a time)
+  │ • Run tests after each change
+  │ • LOW confidence: baseline MUST exist before starting
+  │ • Update issue log with progress
+
+  PHASE 3: VALIDATE (ao-validation)
+  ─────────────────────────────────────
+  │ • Run validation tier based on confidence:
+  │   - HIGH: Tier 1 (build, lint, basic tests)
+  │   - NORMAL: Tier 2 (+ all affected tests, coverage)
+  │   - LOW: Tier 2-3 (full suite, regression analysis)
+  │ • Compare against baseline
+  │ • If regressions found: STOP → HARD STOP CONDITION
+
+  PHASE 4: REVIEW (ao-review) — Two-Stage
+  ─────────────────────────────────────
+  │ Stage 1: SPEC COMPLIANCE
+  │ • Does the implementation match the approved plan?
+  │ • Are all planned requirements addressed?
+  │ • Are there unplanned additions? (YAGNI check)
+  │ • If spec violations found → fix before Stage 2
+  │
+  │ Stage 2: CODE QUALITY
+  │ • Code review for correctness, security, performance
+  │ • Architecture and design pattern adherence
+  │ • Edge cases, error handling, maintainability
+  │ • LOW confidence: extra depth (invariants, failure modes)
+  │ • LOW confidence: MANDATORY human approval before close
+  │ • NORMAL/HIGH: human review recommended
+
+  PHASE 5: COMPLETE
+  ─────────────────────────────────────
+  │ • All completion gate checks must pass
+  │ • Archive issue to history.md
+  │ • Update focus.json "Just did"
+
+END FOR
+
+RETROSPECTIVE (ao-retrospective)
+─────────────────────────────────────
+│ • Scan session for durable learnings
+│ • Check for confidence mismatches
+│ • Update .agent/ops/memory.md
+│ • Increment iteration counter
+```
+
+### Hard Stop Conditions (MUST STOP AND ASK HUMAN)
+
+| Condition | Why | Action |
+|-----------|-----|--------|
+| Push to protected branch requested | FORBIDDEN — no override | REFUSE with error, suggest feature branch |
+| Regressions found vs baseline | Quality gate failed | Stop, report, await fix direction |
+| LOW confidence without baseline | Safety rule violation | Create baseline first |
+| Ambiguous requirements | Can't proceed safely | Interview user |
+| Scope expanded significantly | Original plan invalid | Re-plan with updated scope |
+| Security-sensitive code touched | Requires human review | Present changes, await approval |
+| Multiple modules affected unexpectedly | Risk assessment needed | Report impact, await confirmation |
+| Tests fail after 2 fix attempts | May need different approach | Stop, present options |
+| Batch limit violated | Protocol violation | Reset, re-scan with correct limits |
+| Backlog promotion without human approval | FORBIDDEN — human-only action | STOP, present backlog items, await human selection |
+
+### Confidence-Specific Rules
+
+| Phase | LOW | NORMAL | HIGH |
+|-------|-----|--------|------|
+| **Plan** | Explicit validation, interview | 2+ iterations | May abbreviate |
+| **Implement** | Baseline MANDATORY | Baseline recommended | Baseline optional |
+| **Validate** | Tier 2-3 only | Tier 2 minimum | Tier 1 acceptable |
+| **Review** | Human gate MANDATORY | Human recommended | Auto-close OK |
+| **Batch** | 1 issue only | 3 max, confirm if >1 | 5 max, confirm if >1 |
+
+### Traceability
+
+All actions trace back to:
+- **Constitution**: `.agent/ops/constitution.md` defines boundaries
+- **Issues**: `.agent/ops/issues/*.md` contains the work item
+- **Focus**: `.agent/ops/focus.json` tracks current state
+- **Reference files**: `.agent/ops/issues/references/` for complex issues
+
+## Handoff Options
+
+**At the end of each iteration**, present these options to the user:
+
+```
+What would you like to do next?
+
+A) Implement — Implement the highest priority issue (/ao-implement)
+B) Status — View project status report (/ao-report)
+C) Auto — Autonomous work on issues without asking (/ao-auto)
+D) Add task — Create or manage issues (/ao-task)
+E) Quickfix — Expedited path for trivial changes (/ao-quickfix)
+F) Help — Interactive guide for AO workflow (/ao-help)
+```
+
+### Option Details
+
+| Option | Description | Behavior |
+|--------|-------------|----------|
+| **Implement** | Work on single issue | Uses ao-focus-scan to select highest priority issue, then implements it |
+| **Status** | View project report | Generates status report showing open issues, completed work, velocity |
+| **Auto** | Autonomous work | Invokes ao-auto to work on NORMAL/HIGH confidence issues autonomously without asking. LOW confidence issues are skipped and reported. |
+| **Add task** | Create/manage issues | Opens ao-task to create new issues or triage backlog |
+| **Quickfix** | Fast trivial changes | Bypasses some validation for simple, well-understood changes |
+| **Help** | AO workflow guide | Displays help information about AO skills and commands |
+
+### Auto Option Behavior (/ao-auto)
+
+The Auto option implements **autonomous issue work** on NORMAL/HIGH confidence issues:
+
+1. **Scans priority files** (critical.md, high.md, medium.md, low.md) for NORMAL/HIGH confidence actionable issues
+2. **Works autonomously** on NORMAL/HIGH confidence issues without asking between them
+3. **Skips LOW confidence issues** - they are detected and reported but not worked on
+4. **Only asks when:**
+   - All priority files are empty (HARD STOP — only human can promote from backlog)
+   - Only LOW confidence issues remain (auto cannot process them)
+   - All remaining NORMAL/HIGH issues need clarification
+   - Implementation or validation fails
+   - Safety limits reached (max iterations, max time)
+5. **Continues looping** until no more NORMAL/HIGH confidence issues exist
+6. **Presents summary** when autonomous session ends, including skipped LOW confidence issues
+
+**Actionable issue criteria:**
+- Status: `todo` or `in_progress`
+- Not blocked
+- No unresolved questions (no `- [ ]` items in "Questions to Resolve")
+- All `depends_on` dependencies are done
+
+**Example autonomous session:**
+```
+User: Continue
+
+🔄 AUTONOMOUS MODE — Scanning for issues...
+Found 3 actionable issues:
+- CRIT-0023 — Fix authentication bug (critical)
+- HIGH-0018 — Add user profile API (high)
+- MED-0045 — Update email templates (medium)
+
+→ Working on CRIT-0023...
+✅ Completed: CRIT-0023
+
+→ Working on HIGH-0018...
+✅ Completed: HIGH-0018
+
+→ Working on MED-0045...
+✅ Completed: MED-0045
+
+🏁 Autonomous session complete
+Completed 3 issues. No more actionable issues in priority files.
+```