# Major Differences: ao-plan vs ao-task

## Overview

This document explains the key differences between the **ao-plan** (Planning skill) and **ao-task** (Issue Management skill) to help understand when to use each.

---

## Quick Summary

| Aspect | ao-plan | ao-task |
|---------|----------|----------|
| **Primary Purpose** | Create planning plans for implementation | Create, refine, and manage issues |
| **Issue Type Created** | `PLAN` only (for planning work) | All types (BUG, FEAT, CHORE, SEC, DOCS, etc.) |
| **Code Implementation** | No (never implements code) | No (never implements code directly) |
| **Reference Files** | Planning documents in `.agent/ops/issues/references/` | Issue reference files in `.agent/ops/issues/references/` |
| **Bulk Operations** | Not applicable | Yes (bulk create, update, move) |
| **Triage Support** | No | Yes (move between priority files) |
| **Backlog Integration** | Not mentioned | Yes (creates/uses backlog.md) |
| **Brainstorming** | Yes (enhanced process) | No (not needed) |
| **Auto-Handoff** | Never (always offers handoff) | Never (always offers handoff) |

---

## ao-plan — Planning Skill

### Primary Purpose

**Create thorough planning documents and implementation plans** before any code is written.

### Key Characteristics

1. **Planning-Focused**: All work is about creating plans, not implementing features
2. **Brainstorming Process**: Enhanced workflow that checks project state before creating plans
3. **PLAN Issue Type**: Creates issues with `type: PLAN` for planning work
4. **No Code Changes**: Never implements, fixes, or modifies code
5. **Structured Planning**: Creates multi-iteration plans with clear steps

### Typical Workflow

```
User Request: "Plan how to add user authentication"

ao-plan:
1. Check project state (read existing docs, commits, code)
2. Brainstorm potential approaches
3. Create planning issue: FEAT-0001@hash — "Plan user authentication"
4. Generate implementation plan with 2+ iterations
5. Validate plan (check with user)
6. Store plan in reference file: .agent/ops/issues/references/FEAT-0001@hash-impl-plan.md
```

### Issue Operations

- **Create**: Append new `PLAN` type issue to appropriate priority file
- **Update**: Edit existing planning issues
- **List**: Show current planning issues
- **Search**: Find planning issues by ID or keyword

### What It DOES NOT Do

- ❌ Create features (FEAT, BUG, etc.)
- ❌ Implement code changes
- ❌ Fix bugs
- ❌ Create working features
- ❌ Modify code directly

### Reference Management

Planning documents are stored as reference files:
- `.agent/ops/issues/references/{ISSUE-ID}-impl-plan.md`

---

## ao-task — Issue Management Skill

### Primary Purpose

**Create, refine, and manage issues throughout their lifecycle.** Handles all issue operations.

### Key Characteristics

1. **Issue-Centric**: Manages entire lifecycle of issues (creation to archiving)
2. **All Issue Types**: Creates BUG, FEAT, CHORE, DOCS, SEC, PEREF, TEST, REFAC, etc.
3. **Bulk Operations**: Supports creating multiple issues, batch updates, moving issues
4. **Triage Support**: Can move issues between priority files (backlog → priority)
5. **Backlog Integration**: Creates and manages `backlog.md` for unpriorized items
6. **No Code Changes**: Never implements code directly (but can create tasks for coding work)
7. **JSON Export**: Can export issues to/from JSON format

### Typical Workflow

```
User Request: "Fix authentication bug in login"

ao-task:
1. Create issue: BUG-0023@hash — "Fix login timeout" (type: BUG)
2. Append to: .agent/ops/issues/critical.md
3. Issue is now tracked and ready for implementation

Later:
User Request: "Move this bug to high priority"

ao-task:
1. Read BUG-0023 from critical.md
2. Move to: .agent/ops/issues/high.md
3. Update priority in issue metadata
4. Issue is now in high priority file
```

### Issue Operations

- **Create**: Append new issue to priority file OR backlog.md
- **Update**: Edit any issue field (title, description, status, priority, etc.)
- **List**: Search/list issues by type, priority, epic, status
- **Search**: Find specific issue by ID, keyword search across all files
- **Triage**: Move issues between priority files
- **Archive**: Move completed issues to history.md
- **Bulk Create**: Create multiple issues at once
- **Bulk Update**: Update multiple issues (status, priority, etc.)
- **Bulk Move**: Move multiple issues between files
- **JSON Export**: Export all issues to JSON, import from JSON

### What It DOES NOT Do

- ❌ Implement code directly (but can create tasks FOR coding work)
- ❌ Fix bugs (but can create BUG issues for fixing)
- ❌ Never modifies code files

### What CAN Do

- ✅ Create task issues for coding work (type: CHORE or custom type)
- ✅ Create BUG issues for bug fixes
- ✅ Create FEAT issues for feature implementation
- ✅ Manage issue metadata and state

### Reference Management

Issue details are stored as reference files:
- `.agent/ops/issues/references/{ISSUE-ID}.md` — Contains long descriptions, examples, diagrams
- Moving large details to reference files keeps issue files small

---

## Detailed Comparison

### 1. Purpose and Scope

| Aspect | ao-plan | ao-task |
|---------|----------|----------|
| **Scope** | Narrow: Planning only | Broad: Issue management |
| **Use Case** | "Plan this feature" | "Manage all issues" |
| **Primary Action** | Create documents/plans | Create/refine/move/archive issues |
| **Planning vs Execution** | Plans work, doesn't execute | Manages execution through issues |

### 2. Issue Types

| Aspect | ao-plan | ao-task |
|---------|----------|----------|
| **Issue Type Created** | `PLAN` only | All types: BUG, FEAT, CHORE, DOCS, SEC, PEREF, TEST, REFAC, etc. |
| **Planning Issues** | Used for planning work | Not used (except for planning tasks) |
| **Feature Issues** | Never creates FEAT issues | Creates FEAT issues for features |
| **Bug Issues** | Never creates BUG issues | Creates BUG issues for bug fixes |
| **Task Issues** | Can create CHORE issues for tasks | Can create CHORE issues for tasks |
| **Reference Files** | Implementation plans | Long descriptions, examples, diagrams |

**Key Insight**: ao-plan creates PLANS for how to implement features. ao-task creates the actual issues (FEAT, BUG, etc.) that track implementation work.

### 3. Code Implementation

| Aspect | ao-plan | ao-task |
|---------|----------|----------|
| **Implements Code?** | No | No (directly) |
| **Creates Coding Tasks?** | No | Can (via CHORE issues) |
| **Fixes Bugs?** | No | Can (via BUG issues) |
| **Modifies Files?** | No | No |
| **Primary Focus** | Planning documents | Issue metadata and state |

**Key Insight**: Neither skill implements code directly. Both rely on ao-implementation skill for actual code changes. However, ao-task manages the issues that drive ao-implementation.

### 4. Reference Management

| Aspect | ao-plan | ao-task |
|---------|----------|----------|
| **Reference Type** | Planning documents | Issue reference files |
| **Storage Location** | `.agent/ops/issues/references/{ISSUE-ID}-impl-plan.md` | `.agent/ops/issues/references/{ISSUE-ID}.md` |
| **Content** | Implementation plans with iterations | Long descriptions, examples, diagrams |
| **Purpose** | Guide implementation work | Keep large content out of issue files |
| **When Used** | During implementation (ao-implementation reads reference) | During implementation or review (ao-implementation reads reference) |

**Key Insight**: Both use references directory to store long-form content. ao-plan stores implementation plans; ao-task stores issue details like examples and research notes.

### 5. Bulk Operations

| Aspect | ao-plan | ao-task |
|---------|----------|----------|
| **Bulk Create** | Not supported | Yes (create multiple at once) |
| **Bulk Update** | Not supported | Yes (update multiple issues at once) |
| **Bulk Move** | Not supported | Yes (move multiple issues between files) |
| **Bulk Archive** | Not supported | Yes (archive multiple at once) |
| **JSON Export** | Not supported | Yes (export/import) |

**Key Insight**: ao-task is designed for efficiency with bulk operations. ao-plan is focused on planning quality, not operational efficiency.

### 6. Triage and Backlog

| Aspect | ao-plan | ao-task |
|---------|----------|----------|
| **Triage Support** | No | Yes (move issues between priority files) |
| **Backlog File** | Not mentioned | Yes (creates and manages backlog.md) |
| **Backlog Creation** | Creates backlog issues when needed | Can add items directly to backlog.md |
| **Backlog Promotion** | Move from backlog.md to priority files | Yes (triage workflow) |

**Key Insight**: ao-task provides complete issue triage and backlog management. ao-plan does not address backlog or triage.

### 7. Brainstorming

| Aspect | ao-plan | ao-task |
|---------|----------|----------|
| **Brainstorming Process** | Yes (enhanced workflow) | No (not needed) |
| **Project State Check** | Yes (before creating plans) | No (not planning focus) |
| **Interview Integration** | Yes (for clarifying unknowns) | Yes (for refining issues) |
| **Multiple Choice** | Yes (present options) | No (single-mode typically) |

**Key Insight**: ao-plan has a sophisticated brainstorming process that checks project state before planning. ao-task has interview capabilities but not the same brainstorming workflow.

### 8. Workflow Integration

| Aspect | ao-plan | ao-task |
|---------|----------|----------|
| **Planning Phase** | Creates planning issues (type: PLAN) | Uses existing issues or creates new ones |
| **Implementation Phase** | Handoff to ao-implementation | Creates issues (FEAT, BUG) for ao-implementation |
| **Validation Phase** | Handoff to ao-implementation | Updates issue status, manages state |
| **Completion** | Handoff to ao-complete | Archives to history.md |
| **Handoff Behavior** | Never auto-proceeds (always offers choices) | Never auto-proceeds (always offers choices) |

**Workflow Comparison:**
```
ao-plan:
Create PLAN issue → User approves → ao-implementation (uses reference) → Complete

ao-task:
Create FEAT/BUG issue → ao-implementation (implements) → Validate → Review → Complete
```

Both create issues that ao-implementation then works on, but they serve different purposes:
- ao-plan: Issues are PLANS (documentation)
- ao-task: Issues are WORK ITEMS (bugs, features, etc.)

### 9. When to Use Each

---

## Use ao-plan WHEN:

You want to plan HOW to implement a feature or solve a complex problem.

**Examples:**
- "Plan the architecture for the new reporting system"
- "Create a plan for migrating from Python 2 to Python 3"
- "Brainstorm approaches for handling large file uploads"
- "Explore different UI patterns for the settings page"

**Key Characteristics:**
- Solution is NOT obvious
- Multiple approaches possible
- Need to consider trade-offs
- Should involve brainstorming or multiple-choice decisions
- Requires research or exploration

**Workflow:**
```
ao-plan creates: PLAN-0001@hash — "Plan reporting architecture"
  → Brainstorming process checks current state
  → Creates 2-3 implementation options
  → Generates implementation plan
  → Stores in reference file
```

---

## Use ao-task WHEN:

You want to manage issues: create, update, move, triage, list.

**Examples:**
- "Create a new issue for the authentication bug I found"
- "Add the login timeout bug to high priority"
- "List all critical issues"
- "Search for issues related to authentication"
- "Move 3 completed issues to history.md"
- "Create 5 new tasks for the sprint"
- "Triage the backlog items and promote to priority files"
- "Export all issues to JSON"

**Key Characteristics:**
- Issue lifecycle management
- All issue types supported (BUG, FEAT, CHORE, etc.)
- Can work with backlog.md (unpriorized items)
- Bulk operations supported
- Triage and prioritization workflow

**Workflow:**
```
ao-task creates: BUG-0023@hash — "Fix login timeout"
  → Appends to critical.md
  → Issue is now tracked

ao-task can also:
  → Create multiple issues at once
  → Move issues between files (backlog → critical → high → medium → low)
  → Update issue metadata
  → Archive completed issues
```

---

## Key Insight Summary

### They Serve Different Stages

```
Planning Stage:
  ao-plan: Creates PLANS (documentation for how to implement)
  ao-task: NOT used (usually)

Implementation Stage:
  ao-plan: NOT used
  ao-task: Creates issues (BUG, FEAT) that track implementation work
  ao-implementation: Executes the work

Execution Stage:
  ao-plan: NEVER executes code
  ao-task: NEVER executes code (but can create task issues)
  ao-implementation: Executes code based on issues from ao-plan/ao-task

Completion Stage:
  ao-plan: Marks planning issue as done
  ao-task: Marks work issues as done, archives to history.md
  ao-complete: Verifies and archives
```

### Core Distinction

**ao-plan = Planning Documentation**
- Creates PLANS (what to do, how to do it)
- Documents multi-iteration approaches
- Generates implementation plans
- Reference files contain implementation strategies

**ao-task = Issue Management**
- Creates WORK ITEMS (bugs to fix, features to build)
- Manages issue state (todo → in_progress → done)
- Handles issue lifecycle from creation to archiving
- Reference files contain issue details, examples, diagrams

### Complementary Usage

These skills can work together in a workflow:

```
1. ao-plan: Create comprehensive plan for a large feature
   → Output: FEAT-0001@hash — "Plan: User Authentication System"
          with 3 implementation iterations in reference file

2. ao-task: Create implementation issues based on plan
   → Input: "Implement iteration 1 from FEAT-0001 plan"
   → Output: FEAT-0002@hash — "Add login page" (part of plan)
               FEAT-0003@hash — "Add authentication service"
               FEAT-0004@hash — "Add logout functionality"

3. ao-implementation: Execute each feature issue
   → Reads implementation plan from reference file
   → Implements code
   → Updates issue progress

4. ao-complete: Verify and archive each feature issue
   → Runs tests, checks coverage
   → Archives completed issues to history.md

5. Back to ao-plan: Mark plan as complete
```

---

## Common Misconceptions

### Misconception 1: "ao-plan implements features"

**False.** ao-plan creates PLANNING issues (type: PLAN), not feature issues (type: FEAT).

**Correct:** ao-plan creates documentation/plans. ao-task creates the actual feature issues.

### Misconception 2: "ao-task fixes bugs"

**False.** ao-task creates BUG issues, but doesn't fix them.

**Correct:** ao-task creates BUG issues. ao-implementation (invoked by ao-auto or ao-implement) fixes the bugs.

### Misconception 3: "They do the same thing"

**False.** They have overlapping purposes but different workflows.

**Correct:**
- ao-plan: Planning documentation (PLAN type issues)
- ao-task: Issue management (BUG/FEAT/CHORE type issues)
- Both use reference files to store detailed information
- Both create issues that ao-implementation then works on

---

## Decision Tree

```
Need to...?                 | Use ao-plan    | Use ao-task
-----------------------------|---------------|----------------
Plan a complex feature     | ✓                | ✗
Solve a design problem     | ✓                | ✗ (if planning)
Brainstorm approaches       | ✓                | ✗
Explore options             | ✓                | ✗
Create implementation plan    | ✓                | ✗
-----------------------------|---------------|-----------------
Create new issue            | ✗                | ✓
Refine existing issue       | ✗                | ✓
Update issue status         | ✗                | ✓
Move issue                | ✗                | ✓
Archive issue              | ✗                | ✓
Triage backlog             | ✗                | ✓
List/search issues         | ✗                | ✓
Bulk operations           | ✗                | ✓
Export/import JSON         | ✗                | ✓
-----------------------------|---------------|-----------------
Work on code implementation  | ✗ (use ao-implement) | ✗ (use ao-implementation via issues)
```

---

## Summary

### ao-plan — Planning Specialist

- ✅ Creates comprehensive planning documents
- ✅ Brainstorms multiple approaches
- ✅ Generates implementation plans with 2+ iterations
- ✅ Uses enhanced brainstorming process
- ✅ Stores implementation plans in reference files
- ❌ Does NOT implement features or fix bugs directly
- ❌ Does NOT manage issue lifecycle

**Best for:** Complex features requiring careful planning, research, or multiple approaches.

### ao-task — Issue Management Generalist

- ✅ Creates all issue types (BUG, FEAT, CHORE, DOCS, SEC, etc.)
- ✅ Refines existing issues
- ✅ Manages issue state and lifecycle
- ✅ Supports bulk operations
- ✅ Provides triage workflow
- ✅ Integrates with backlog.md
- ✅ Moves issues between priority files
- ✅ Archives completed issues
- ❌ Does NOT implement code directly (but can create task issues)
- ❌ Does NOT create planning documents

**Best for:** Issue lifecycle management, triage, bulk operations, backlog management.

### When to Use Together

They complement each other:

1. **Plan Complex Feature:** ao-plan creates comprehensive plan → ao-task creates feature issues from plan → ao-implementation executes
2. **Daily Issue Management:** ao-task creates, updates, moves issues → ao-implementation works on them
3. **Backlog Management:** ao-task triages backlog.md → moves items to priority files when ready

**They do NOT conflict or overlap.** They serve different purposes in the workflow.

---

## Files

- `.ao/skills/ao-planning/SKILL.md` — Planning skill documentation
- `.ao/skills/ao-task/SKILL.md` — Issue management skill documentation
- `.ao/skills/ao-init/SKILL.md` — Initialization skill (creates both)
- `.ao/skill-index.md` — Skill registry (lists both)
