---
name: ao-plan
description: "Create a multi-iteration plan (>=2) and produce a final implementation plan + test strategy."
agent: AO
---

Perform AO planning phase, but do not implement.

Use skill `ao-planning` for the full workflow.

## Issue-First Principle (MANDATORY)

**Before starting detailed planning, you MUST create an issue.**

1. **Check for existing issue**: Is there already an issue for this work?
   - Yes → proceed with planning, reference the issue ID
   - No → create one first (see below)

2. **Create issue if needed**:
   - Determine type: `FEAT`, `BUG`, `ENH`, `CHORE`, `REFAC`, `TEST`, `DOCS`, `SEC`, `PERF`, `PLAN`
   - Determine priority: `critical`, `high`, `medium`, `low`, `backlog`
   - Generate valid ID format: `{TYPE}-{NUMBER}@{HASH}` (use 4-digit zero-padded number, 6-char hex hash)
   - Append to appropriate file: `.agent/ops/issues/{priority}.md`
   - Include fields: `id`, `title`, `type`, `status: todo`, `priority`, `confidence`, `description`
   - If details >20 lines, add `details: references/{ISSUE-ID}.md` and create reference file

3. **Reference issue throughout**:
   - Plan title: "Plan for {ISSUE-ID}: {title}"
   - Update issue status to `in_progress` when planning starts

## Planning Steps

1. **Ask clarifying questions** until requirements are explicit.

2. **Produce at least two planning iterations.** Each iteration must include:
   - steps
   - files to touch
   - test strategy
   - risks/unknowns
   - why this is minimal change

3. **MANDATORY: Generate implementation details file.**

   Determine detail level from confidence:
   | Confidence | Detail Level | What to Include |
   |------------|--------------|-----------------|
   | low | **extensive** | Actual code snippets, full function implementations, edge case handling code, complete test cases with assertions |
   | normal | **normal** | Function signatures, pseudo-code, data structures, API contracts |
   | high | **low** | File list, brief approach, risks |

   **For extensive level (low confidence), you MUST include:**
   - Actual Python/TypeScript/etc. code blocks showing the implementation
   - Not pseudo-code, but real executable code
   - Edge case handling with specific code
   - Complete test functions with assertions

   Example extensive output:
   ```python
   # Actual implementation code
   def process_user(user_id: str) -> UserResult:
       """Process user with full validation."""
       if not user_id:
           raise ValueError("user_id is required")

       user = db.get_user(user_id)
       if not user:
           raise NotFoundError(f"User {user_id} not found")

       return UserResult(
           id=user.id,
           name=user.name,
           processed_at=datetime.utcnow()
       )
   ```

4. **Save to reference file**: `.agent/ops/issues/references/{ISSUE-ID}-impl-plan.md`
   - This is the SECONDARY file for detailed implementation plans
   - The PRIMARY issue must already exist in a priority file (critical/high/medium/low/backlog)
   - Link the reference file from the issue's `details` field

5. **Finish with Final Implementation Plan** and explicit "Ready to implement?" checkpoint.

6. **Update state**: `.agent/ops/focus.json` using skill `ao-state`.
