# Workflow Updates — Backlog.md Integration

## Overview

Updated ao-plan and ao-idea skills to properly integrate with backlog.md. This creates a complete workflow:

**Proper Flow:**
1. **ao-idea**: Adds IDEA items to backlog.md (loose concepts, needs research)
2. **ao-plan**: Adds PLANNING items to backlog.md (structured plans, ready for implementation)
3. **ao-task**: Promotes items from backlog.md to priority files when ready (**human-initiated only**)
4. **ao-focus-scan**: Scans priority files only (skips backlog.md)
5. **ao-auto**: Works on actionable issues in priority files only (skips backlog.md)

## Changes Made

### 1. Updated: `.ao/skills/ao-planning/SKILL.md`

**Change (line 23):**

**Before:**
```markdown
| Create planning issue | Append to `.agent/ops/issues/medium.md` with type `PLAN` |
```

**After:**
```markdown
| Create planning issue | Append to `.agent/ops/issues/backlog.md` with type `PLAN` |

**IMPORTANT:** Planning items go to backlog.md for initial triage. When an issue is ready for implementation, it should be promoted from backlog.md to the appropriate priority file (critical.md, high.md, medium.md, or low.md) using /ao-task or ao-focus-scan.
```

**Rationale:**
- Planning issues should NOT go directly to priority files
- They need triage/prioritization first
- backlog.md holds unpriorized items (IDEA and PLAN types)
- ao-task can promote items from backlog.md to priority files when ready
- ao-focus-scan scans priority files (not backlog.md) for actionable work

### 2. Verified: `.ao/skills/ao-idea/SKILL.md`

**No changes needed** — ao-idea already correctly adds IDEA items to backlog.md.

**From ao-idea/SKILL.md (line 187):**
```markdown
2. **Append to backlog.md**: Add issue at end of file
   - Transform loosely structured ideas into well-researched IDEA issues in backlog.md. This skill bridges the gap between "I have a vague idea" and "I have a trackable, researched issue ready for triage."

3. `ao-focus-scan` | IDEA issues appear in backlog for triage

The idea has been added to backlog.md with status `idea`.
```

**Confirmed Workflow:**
```
ao-idea → adds IDEA to backlog.md
ao-plan → adds PLAN to backlog.md
ao-task → promotes from backlog.md to priority files (human-initiated only)
ao-focus-scan → scans priority files (excludes backlog.md)
```

### 3. Verified: `.ao/skills/ao-task/SKILL.md`

**No changes needed** — ao-task already supports backlog promotion.

**From ao-task/SKILL.md (line 294):**
```markdown
For each backlog item: assign priority or skip/delete.
```

**Confirmed Workflow:**
- ao-task can promote items from backlog.md to priority files
- Supports triage workflow

### 4. Updated: `.ao/skills/ao-init/SKILL.md`

**No changes needed** — ao-init already creates backlog.md.

### 5. Verified: `.ao/skill-index.md`

**No changes needed** — already properly reflects the skill capabilities.

---

## New Workflow Diagram

```
┌─────────────────────────────────────────────────────┐
│                                             │
│   User has Idea                               │
│   └─→ ao-idea                               │
│         └─→ Adds to backlog.md (status: idea) │
│                                             │
│   backlog.md contains:                          │
│   - IDEA items (needs research)                │
│   - PLAN items (ready for implementation)       │
│                                             │
│   ao-plan → adds PLAN to backlog.md             │
│   (structured plans, ready to implement)         │
│                                             │
│   User wants to implement                     │
│   └─→ ao-task → Promotes from backlog.md       │
│         └─→ critical.md / high.md / medium.md / low.md │
│                                             │
│   ao-focus-scan / ao-auto → Work on priority files │
│   (scans critical/high/medium/low, skips backlog.md) │
│                                             │
│   Completed → ao-complete → Archive to history.md  │
└─────────────────────────────────────────────────────┘
```

---

## Key Points

### File Separation

| File | Purpose | Issue Types |
|------|---------|-------------|
| `backlog.md` | Unpriorized items awaiting triage | IDEA, PLAN |
| `critical.md` | Ready for implementation (P0 priority) | BUG, FEAT, SEC |
| `high.md` | Important, address soon (P1 priority) | BUG, FEAT, CHORE |
| `medium.md` | Standard work (P2 priority) | FEAT, CHORE, DOCS |
| `low.md` | Nice to have (P3 priority) | CHORE, DOCS, PERF |
| `history.md` | Completed and archived | All types (status: done) |

### Skill Responsibilities

| Skill | Primary Action | Target File |
|-------|----------------|-------------|
| **ao-idea** | Add IDEA items | backlog.md |
| **ao-plan** | Add PLAN items | backlog.md |
| **ao-task** | Promote from backlog.md | All priority files |
| **ao-focus-scan** | Scan for actionable work | Priority files (not backlog.md) |
| **ao-auto** | Work autonomously | Priority files (not backlog.md) |
| **ao-complete** | Verify and archive | history.md |

### Issue Type Flow

```
1. User has raw idea
   └─→ ao-idea → Creates IDEA item in backlog.md (status: idea, needs research)

2. Research completes, ready to plan
   └─→ ao-plan → Creates PLAN item in backlog.md (status: todo, has plan)

3. Plan ready for implementation
   └─→ ao-task → Promotes PLAN item from backlog.md → high.md or medium.md

4. Implementation complete
   └─→ ao-focus-scan / ao-auto → Works on item → ao-complete → Archives to history.md
```

---

## Testing the New Workflow

### Test 1: Create and Promote

```bash
# 1. Create a raw idea
/ao-idea "Need a user preferences page"

# Verify: IDEA item in backlog.md
grep -A 5 "idea" .agent/ops/issues/backlog.md | tail -1

# 2. Plan the idea
/ao-plan "Plan user preferences page"

# Verify: PLAN item in backlog.md
grep -A 5 "PLAN" .agent/ops/issues/backlog.md | tail -1

# 3. Promote to implementation
/ao-task "Promote IDEA-001 from backlog.md to high priority"

# Verify: Item moved from backlog.md, added to high.md
grep "IDEA-001" .agent/ops/issues/high.md
```

### Test 2: Multiple Ideas in Backlog

```bash
# Create multiple ideas
/ao-idea "Dark mode"
/ao-idea "Mobile app"
/ao-idea "Export to PDF"

# Plan them together
/ao-plan "Dark mode and mobile support"

# Verify single PLAN item in backlog.md
grep -A 5 "PLAN" .agent/ops/issues/backlog.md | tail -3

# Promote the PLAN
/ao-task "Promote PLAN-001 from backlog.md to high priority"
```

---

## Benefits

1. **Clear Separation of Concerns** - backlog.md is for unpriorized items (IDEA, PLAN), priority files are for implementation-ready issues
2. **Proper Triage Flow** - Ideas/plans go to backlog.md first, then promoted when ready
3. **No Priority Pollution** - Priority files don't get mixed with unready items
4. **Better Visibility** - All ideas and plans are in backlog.md for easy review
5. **Standard Workflow** - Matches industry best practices for backlog management

---

## Files Modified

1. ✅ `.ao/skills/ao-planning/SKILL.md` — Updated to append PLANNING items to backlog.md
2. ✅ `.ao/skills/ao-init/SKILL.md` — Already creates backlog.md (no changes needed)
3. ✅ `.ao/skills/ao-idea/SKILL.md` — Already adds to backlog.md (no changes needed)
4. ✅ `.ao/skills/ao-task/SKILL.md` — Already supports backlog promotion (no changes needed)
5. ✅ `.ao/skills/COMPARISON_plan-vs-task.md` — NEW - Documents the changes and workflow

---

## Next Steps

The workflow is now correct and complete. Skills properly integrate:

✅ ao-idea adds IDEA items to backlog.md
✅ ao-plan adds PLAN items to backlog.md
✅ ao-task promotes from backlog.md to priority files
✅ ao-focus-scan scans priority files (not backlog.md)
✅ ao-auto works on actionable issues in priority files

This creates a proper end-to-end workflow for issue management!
