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

# 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

# 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

# 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

# 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

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:

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()  # What features exist? What's their status? Unknown!

Integration Points

With /feature Command

/feature "description"
    ↓
Task(Initializer) → Creates domain-memory.yaml
    ↓
/spec, /plan, /tasks → Normal phases
    ↓
/implement → Worker loop until all passing

With /epic Command

/epic "description"
    ↓
Task(Initializer) → Creates sprint-level domain-memory.yaml files
    ↓
/implement-epic → Parallel Workers per sprint

With /feature continue

/feature continue
    ↓
If domain-memory.yaml exists:
    Check for remaining features
    Spawn Worker if needed
Else:
    Generate from tasks.md
    Then spawn Worker

Debugging

When things go wrong:

1. Check domain-memory.yaml directly

   • Is the feature status correct?
   • Are dependencies properly marked?
   • What does the log show?

2. Check the "tried" section

   • What approaches have been attempted?
   • Why did they fail?

3. Validate the file

   domain-memory.sh validate specs/001-auth
   

4. Reset a stuck feature

   domain-memory.sh update specs/001-auth F001 untested
   domain-memory.sh unlock specs/001-auth