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:

code

┌─────────────────────────────────────────┐
│ 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:

•Failing features first - Fix regressions before new work
•Priority order - Lower number = higher priority
•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:

code

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:

code

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):

code

Task(Worker for S01) + Task(Worker for S02)  # Same message = parallel

Anti-Patterns to Avoid

❌ Working on Multiple Features

code

# WRONG: Worker picks F001, then continues to F002
implement(F001)
implement(F002)  # Should have EXITED after F001!

❌ In-Memory State

code

# WRONG: Tracking progress in variable
completed_features = []
completed_features.append("F001")  # Lost on restart!

❌ Repeating Failed Approaches

code

# WRONG: Trying same thing that failed before
# Should check "tried" section first

❌ Skipping Boot-Up Ritual

code

# WRONG: Starting implementation without reading disk
implement()  # What features exist? What's their status? Unknown!

Integration Points

With /feature Command

code

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

With /epic Command

code

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

With /feature continue

code

/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:

•
Check domain-memory.yaml directly
- •Is the feature status correct?
- •Are dependencies properly marked?
- •What does the log show?
•
Check the "tried" section
- •What approaches have been attempted?
- •Why did they fail?

•

Validate the file

bash

domain-memory.sh validate specs/001-auth

•

Reset a stuck feature

bash

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