# Agentic Workflow Integration Overview

## System Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    PERSISTENT MEMORY LAYER                       │
│                  (@.opencode/memory/)                            │
│                                                                  │
│  What we know (project context, patterns, decisions)            │
│  • memory.md - Project context & learnings                      │
│  • development-guidelines.md - Coding patterns                  │
│  • architecture-decisions.md - Design decisions                 │
│  • blockers.md - Known issues                                   │
│  • research/ - Research findings (YYYY-MM-DD-*.md)              │
│  • specs/ - Task specifications                                 │
│  • handoffs/ - Phase transition bundles                         │
│  • _templates/ - Document templates                             │
│                                                                  │
│  Updated AFTER major work phases                                │
└─────────────────────────────────────────────────────────────────┘
                               ▲ │
                     Read at   │ │ Update after
                 session start │ │ phase completion
                               │ ▼
┌─────────────────────────────────────────────────────────────────┐
│                   PROJECT TRACKING LAYER                         │
│                    (backlog/tasks/)                              │
│                                                                  │
│  What we're building (multi-session, strategic)                 │
│  • User stories & features (multi-session)                      │
│  • Roadmap items & dependencies                                 │
│  • Status: To Do → In Progress → Blocked → Done                 │
│  • Notes field: current approach, blockers, next steps          │
│  • Timeline: Days-weeks per task                                │
│                                                                  │
│  Built-in via backlog MCP                                       │
└─────────────────────────────────────────────────────────────────┘
                               ▲ │
               Create backlog  │ │ Update status on
               task for multi- │ │ completion
               session work    │ │
                               │ ▼
┌─────────────────────────────────────────────────────────────────┐
│                      AGENT EXECUTION                             │
│                                                                  │
│  Built-in tools:                                                │
│  • todowrite/todoread - In-session task tracking                │
│  • bash, edit, write, read, grep, glob, patch - File ops       │
│  • backlog_task_* - Project task management                     │
│  • memory-read, memory-update - Cross-session context           │
│                                                                  │
│  Execution tracking:                                             │
│  • Git commits show what was done, when, by whom                │
│  • Diffs show iteration and decisions made                      │
│  • Backlog task notes capture current approach                  │
│                                                                  │
│  Each session:                                                   │
│  1. Read memory context (@.opencode/memory/)                    │
│  2. Load backlog task (if multi-session)                        │
│  3. Execute work using built-in tools                           │
│  4. Commit code to git (automatic audit trail)                  │
│  5. Update backlog task notes with progress                     │
└─────────────────────────────────────────────────────────────────┘
```

## Two-Layer Architecture

| Layer       | Directory            | Lifespan   | Purpose                                                 | When to Use                                  |
| ----------- | -------------------- | ---------- | ------------------------------------------------------- | -------------------------------------------- |
| **Memory**  | `@.opencode/memory/` | Permanent  | Cross-session knowledge: what we know, decided, learned | Every session start; update after major work |
| **Backlog** | `backlog/tasks/`     | Days-weeks | Project planning: features, roadmap, dependencies       | For multi-session work; strategic planning   |
| **Git**     | `.git/`              | Permanent  | Execution audit trail: commits show what was done       | Automatic; every code change recorded        |

**Execution tracking** (automatic via git):

- Commits show implementation history
- Diffs reveal iteration and decisions
- Backlog notes capture current approach
- No separate ledger files needed

## Workflow Lifecycle

### 1. Task Creation

```
User Request
    ↓
Is multi-session work? ────YES───→ backlog_task_create()
    │                                    ↓
    NO                        Use git commits to track work
    ↓                                    ↓
Execute directly ←──────────────────────┘
Update memory.md when complete
```

### 2. Execution (Multi-Session)

```
Load backlog task
    ↓
Read @.opencode/memory/ for context
    ↓
Update backlog task notes: current approach
    ↓
Execute work using built-in tools
    ↓
Commit code to git (automatic execution record)
    ↓
Session N+1: backlog task shows progress, notes show approach
```

### 3. Re-planning (If Stuck)

```
Trigger detected:
• Backlog task status = "In Progress" for >24h
• No commits in past 24h
    ↓
@plan reads backlog task + memory.md
    ↓
Generates alternative approach
    ↓
Updates backlog task notes with new strategy
    ↓
Status remains "In Progress"
    ↓
Resume execution with fresh approach
```

### 4. Completion

```
All work 🟢 Complete
    ↓
Update backlog task status → Done
    ↓
Update @.opencode/memory/memory.md with learnings
    ↓
Document patterns in development-guidelines.md
```

## File Organization

```
.opencode/
├── memory/
│   ├── memory.md                    # Session learnings
│   ├── architecture-decisions.md    # Design decisions
│   ├── development-guidelines.md    # Patterns & conventions
│   ├── blockers.md                  # Known issues
│   ├── research/                    # YYYY-MM-DD-topic.md
│   ├── specs/                       # Task specifications
│   ├── handoffs/                    # Phase bundles
│   └── _templates/                  # Document templates
│
├── AGENTS.md                        # Global rules
└── INTEGRATION_OVERVIEW.md          # This file

backlog/
└── tasks/
    ├── task-001.md                  # Feature X (backlog MCP)
    └── task-002.md                  # Bug Y (status + notes)

(Git history)                        # Execution audit trail
```

## Integration Patterns

### Pattern 1: Single-Session Task

```
1. Execute work directly
2. Commit to git
3. After completion: update memory.md with learnings
4. Done
```

### Pattern 2: Multi-Session Feature

```
1. Create backlog task: "Feature X"
2. Session 1:
   - Read memory.md for context
   - Update backlog notes: initial approach
   - Execute work, commit to git
3. Session 2:
   - Read backlog task (see progress + approach)
   - Execute work, commit to git
   - Update backlog notes if approach changes
4. Completion:
   - Update backlog status → Done
   - Update memory.md with learnings
```

### Pattern 3: Stalled Work (Re-planning)

```
1. Backlog task stuck "In Progress" for 24h+
2. @plan reads:
   - Backlog task (status + notes)
   - Git log (commits show attempts)
   - memory.md (patterns & constraints)
3. Generates new approach
4. Updates backlog notes with strategy revision
5. Resume execution (next session picks up fresh plan)
```

## Key Principles

1. **Separation of Concerns**
   - Memory: Permanent knowledge (patterns, decisions, learnings)
   - Backlog: Strategic planning (what we're building, when, why)
   - Git: Execution record (what was actually done)

2. **Single Source of Truth (per layer)**
   - Memory: Cross-session knowledge
   - Backlog: Multi-session project state
   - Git: Implementation history

3. **Minimal Overhead**
   - No separate ledger files to maintain
   - No Facts/Guesses/Plans structure overhead
   - No sync burden between layers
   - Built-in tools handle everything

4. **Built-in Tool Integration**
   - `backlog_task_*` - Multi-session project tracking
   - `todowrite/todoread` - In-session task tracking (optional)
   - `memory-read/update` - Cross-session context
   - `bash`, `edit`, `write` - Execution
   - Git - Automatic audit trail

## Quick Reference

**Create multi-session task:**

```bash
backlog_task_create(title: "Feature X")
```

**During work:**

```bash
# Update backlog notes with current approach
backlog_task_edit(id: "task-001", notes: "Currently implementing...")

# Commit code
git commit -m "Implement X"
```

**If stuck:**

```bash
# @plan reads backlog + memory, updates approach
backlog_task_edit(id: "task-001", notes: "New approach: ...")
```

**On completion:**

```bash
# Update backlog status
backlog_task_edit(id: "task-001", status: "Done")

# Update memory with learnings
# Edit @.opencode/memory/memory.md
```

## What Changed (From Old Architecture)

**Removed:**

- `@.opencode/ledgers/` directory (no longer needed)
- `task-ledger.md` (Facts/Guesses/Plans pattern - backlog notes handle this)
- `progress-ledger.md` (git log + backlog status shows progress)
- `ledger-create`, `ledger-update`, `ledger-archive` tools
- Ledger archive for post-mortems

**Kept:**

- Memory layer (permanent knowledge)
- Backlog layer (project planning)
- `/handoff` command (phase transitions)
- Git history (execution audit)

**Benefit:**

- Simpler architecture (2 layers instead of 3)
- Less file overhead (no ledger directories)
- No sync burden (backlog is source of truth for current work)
- Built-in tools handle everything
- Git provides better audit trail than ledger archives

---

**Last Updated:** November 20, 2025  
**Status:** ✅ Simplified Architecture - Memory + Backlog + Git  
**Decision:** Remove redundant ledger layer, use built-in OpenCode tools
