domain-memory

# Domain Memory Skill

> Standardized boot-up ritual and memory access patterns for stateless agent workflows.

## Overview

The Domain Memory pattern enables agents to work effectively across sessions without shared context. All state lives on DISK in `domain-memory.yaml`. Agents read from disk, work, write to disk, and exit.

## Core Principle

**Disk is the only source of truth.**

- Agents are STATELESS - no memory of previous runs
- State is PERSISTENT - survives agent restarts
- Progress is OBSERVABLE - logged to disk
- Work is ATOMIC - one feature at a time

## Boot-Up Ritual

**Every agent session MUST follow this sequence:**

```
┌─────────────────────────────────────────┐
│ 1. READ domain-memory.yaml              │
│    - Load current state from disk       │
│    - Understand goals, features, status │
└─────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────┐
│ 2. VERIFY test baseline                 │
│    - Run existing tests                 │
│    - Ensure no regressions              │
│    - STOP if baseline fails             │
└─────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────┐
│ 3. SELECT one work item                 │
│    - Pick failing features first        │
│    - Then untested by priority          │
│    - Check dependencies are met         │
│    - Lock the selected feature          │
└─────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────┐
│ 4. EXECUTE with logging                 │
│    - Implement the feature              │
│    - Run feature-specific tests         │
│    - Log approach taken                 │
└─────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────┐
│ 5. UPDATE domain-memory.yaml            │
│    - Mark feature status                │
│    - Record what was tried              │
│    - Add log entry                      │
└─────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────┐
│ 6. EXIT cleanly                         │
│    - Unlock the feature                 │
│    - Commit changes                     │
│    - Return structured result           │
│    - DO NOT continue to next feature    │
└─────────────────────────────────────────┘
```

## Domain Memory CLI

All operations go through `.spec-flow/scripts/bash/domain-memory.sh`:

### Initialization
```bash
# Create new domain memory
domain-memory.sh init specs/001-auth

# Generate from existing tasks.md
domain-memory.sh generate-from-tasks specs/001-auth
```

### Reading State
```bash
# Get full status
domain-memory.sh status specs/001-auth

# Get next feature to work on (JSON)
domain-memory.sh pick specs/001-auth

# Validate structure
domain-memory.sh validate specs/001-auth
```

### Updating State
```bash
# Update feature status
domain-memory.sh update specs/001-auth F001 passing

# Lock feature for work
domain-memory.sh lock specs/001-auth F001

# Unlock feature
domain-memory.sh unlock specs/001-auth
```

### Logging
```bash
# Add log entry
domain-memory.sh log specs/001-auth "worker" "completed_feature" "Implemented login" F001

# Record tried approach
domain-memory.sh tried specs/001-auth F001 "Used async pattern" "Failed: race condition"
```

## Feature Status Values

| Status | Meaning | Worker Action |
|--------|---------|---------------|
| `untested` | No tests run yet | Implement and test |
| `passing` | Tests pass | Skip (done) |
| `failing` | Tests fail | Fix (priority) |
| `in_progress` | Currently locked | Skip (wait) |
| `blocked` | Cannot proceed | Skip (manual help needed) |

## Priority Rules

Workers select features by:
1. **Failing features first** - Fix regressions before new work
2. **Priority order** - Lower number = higher priority
3. **Dependencies met** - All dependencies must be passing

## The "Tried" Mechanism

Prevent infinite loops by tracking what approaches have failed:

```yaml
tried:
  F001:
    - approach: "Used async/await"
      result: "Failed: race condition"
      timestamp: "2025-01-15T10:00:00Z"
    - approach: "Used callbacks"
      result: "Failed: callback hell"
      timestamp: "2025-01-15T11:00:00Z"
```

Before implementing, check if your approach has already failed. Try something fundamentally different.

## Orchestrator Responsibilities

The orchestrator (main Claude Code session) is LIGHTWEIGHT:

```
WHILE features remain (failing or untested):
    1. Read domain-memory.yaml
    2. Spawn Task(Worker) with feature_dir
    3. Wait for Worker to complete
    4. Check domain-memory.yaml status
    5. If all passing: DONE
    6. If failures remain: Spawn next Worker
```

The orchestrator:
- Does NOT implement code
- Does NOT carry implementation context
- ONLY spawns Workers and checks disk state

## Epic Workflow

For epics, domain memory is hierarchical:

```
epics/001-ecom/
├── domain-memory.yaml          # Epic-level overview
└── sprints/
    ├── S01/
    │   └── domain-memory.yaml  # Sprint 1 features
    ├── S02/
    │   └── domain-memory.yaml  # Sprint 2 features
    └── S03/
        └── domain-memory.yaml  # Sprint 3 features
```

Parallel sprints get parallel Workers (spawned in single message):
```
Task(Worker for S01) + Task(Worker for S02)  # Same message = parallel
```

## Anti-Patterns to Avoid

### ❌ Working on Multiple Features
```
# WRONG: Worker picks F001, then continues to F002
implement(F001)
implement(F002)  # Should have EXITED after F001!
```

### ❌ In-Memory State
```
# WRONG: Tracking progress in variable
completed_features = []
completed_features.append("F001")  # Lost on restart!
```

### ❌ Repeating Failed Approaches
```
# WRONG: Trying same thing that failed before
# Should check "tried" section first
```

### ❌ Skipping Boot-Up Ritual
```
# WRONG: Starting implementation without reading disk
implement()