Loom Usage

Loom Usage — Meta-Orchestration for Claude

Overview

This skill enables Claude to drive loom itself — initializing plans, running orchestration, monitoring execution, debugging failures, and recovering from errors. This is meta-orchestration: Claude operating loom as a tool rather than working inside a loom worktree as an agent.

When to Use

• Running a loom plan end-to-end
• Interpreting loom status output and deciding next steps
• Debugging why a stage failed, is blocked, or has merge conflicts
• Recovering from crashes, context exhaustion, or corrupted state
• Managing worktrees, sessions, and daemon lifecycle
• Understanding .loom/work/ directory structure and signal files

Complementary Skills

The Loom Lifecycle

WRITE PLAN          VALIDATE & INIT         EXECUTE            MONITOR & DEBUG
─────────────────── ─────────────────────── ────────────────── ──────────────────
/loom-plan-writer → loom init plan.md     → loom run         → loom status
                    loom repair --fix                           loom check
                                                               loom diagnose
                                                               loom stage retry
                                          ────────────────── ──────────────────
                                          COMPLETE            CLEAN UP
                                          ────────────────── ──────────────────
                                          All stages merged → loom clean
                                          Plan → DONE-PLAN-*

Phase 1: Validate & Initialize

Pre-Flight Checks

Before initializing, verify the workspace is healthy:

# Detect and fix common issues (missing hooks, stale state, gitignore gaps)
loom repair --fix

# If re-running a plan, clean previous state first
loom clean --all

Initialize a Plan

loom init doc/plans/PLAN-my-feature.md

What happens:

1. Parses the plan markdown, extracts YAML metadata
2. Validates all stages (IDs, dependencies, goal-backward fields)
3. Creates .loom/work/ directory with stage files, config.toml
4. Installs git hooks (commit guard, commit filter)
5. Builds execution DAG, checks for cycles

Common init failures and fixes:

⚠️ truths was removed as a standalone field. Behavioral checks now go in acceptance (Simple string / Extended object); the goal-backward layers are artifacts, wiring, wiring_tests, dead_code_check. Plan parsing rejects truths and every other unknown field, so migrate retired fields before initialization or verification.

Re-Initialization

# Clean slate — removes .loom/work/, worktrees, sessions
loom clean --all

# Then re-init
loom init doc/plans/PLAN-my-feature.md

# Or use --clean flag to do both in one step
loom init doc/plans/PLAN-my-feature.md --clean

Phase 2: Execute

Start Orchestration

# Default: background daemon, up to 4 parallel sessions
loom run

# With options
loom run --max-parallel 2      # Limit concurrency
loom run --manual              # Require approval before each stage
loom run --no-merge            # Skip auto-merge (manual merge later)
loom run --foreground          # Debug mode (blocks terminal)

What loom run does:

1. Renames plan file: PLAN-* → IN_PROGRESS-PLAN-*
2. Spawns background daemon on Unix socket (.loom/work/orchestrator.sock)
3. Daemon polls every 5 seconds:
   • Loads stage files → builds execution graph
   • Finds stages with all dependencies completed+merged
   • Creates worktrees, generates signals, spawns Claude Code sessions
   • Monitors sessions for crashes, context exhaustion, completion
4. Auto-merges completed stages to main branch (progressive merge)
5. When all stages complete → renames to DONE-PLAN-*

Plan File Lifecycle

Phase 3: Monitor

Check Status

# One-time snapshot
loom status

# Live TUI dashboard (real-time updates via daemon socket)
loom status --live

# Compact single-line per stage (good for scripting)
loom status --compact

# Verbose — includes failure details
loom status --verbose

Read the Execution Graph

loom graph

Status icons:

• ✓ Completed
• ● Executing
• ▶ Ready/Queued
• ○ WaitingForDeps
• ✗ Blocked
• ⟳ NeedsHandoff
• ⚡ MergeConflict
• ? WaitingForInput
• ⊘ Skipped
• ⚠ CompletedWithFailures
• ⊗ MergeBlocked

Interpret Status Output

When checking status, look for these patterns:

Healthy execution:

• Stages flowing left-to-right through the DAG
• Context usage < 60% (green)
• Sessions running with heartbeat

Warning signs:

• Context usage 60-75% (yellow) — handoff may be needed soon
• Stage stuck in Executing for a long time — check session liveness
• Multiple retries on same stage — investigate root cause

Failure indicators:

• Stage in Blocked state — read the block reason
• MergeConflict — needs manual resolution or retry
• NeedsHandoff — context exhausted, will auto-resume
• CompletedWithFailures — acceptance passed but with warnings

Phase 4: Debug & Recover

Stage Failed or Blocked

# See detailed failure information
loom status --verbose

# Run goal-backward verification to see what's missing
loom check <stage-id>

# Get fix suggestions
loom check <stage-id> --suggest

# Spawn diagnostic Claude session
loom diagnose <stage-id>

Common Failure Scenarios

Acceptance Criteria Failed

The stage's acceptance commands returned non-zero.

# Re-run acceptance and goal-backward checks without changing stage state
loom check <stage-id>

# After fixing issues, retry
loom stage retry <stage-id>

Debugging tips:

• Read stderr even when exit code is 0 — silent failures are common
• Check that working_dir is correct (most common cause of "command not found")
• Verify paths are relative to working_dir (no double-paths like loom/loom/src/)

Merge Conflict

Stage completed but merge to main failed.

# Option 1: Retry the merge (if conflict was transient)
loom stage merge <stage-id>

# Option 2: Manual resolution
cd .worktrees/<stage-id>
git merge main                    # Resolve conflicts
git add <resolved-files>
git commit -m "resolve merge conflict"
loom stage merge <stage-id> --resolved

Context Exhausted

Agent ran out of context window. Loom auto-creates handoff.

# Check handoff was created
ls .loom/work/handoffs/

# Resume with new session (reads handoff automatically)
loom resume <stage-id>

Session Crashed

Claude Code process died unexpectedly.

# Check crash report
ls .loom/work/crashes/

# Retry with recovery signal (auto-detected from crash context)
loom stage retry <stage-id>

# Or force retry with custom context
loom stage retry <stage-id> --force --context "crashed during compilation"

Stage Stuck in Executing

Session appears alive but making no progress.

# Check session liveness
loom sessions list

# Kill the stuck session
loom sessions kill --stage <stage-id>

# Reset and retry
loom stage reset <stage-id> --kill-session
loom stage retry <stage-id>

Daemon Not Running

# Check if daemon is alive
loom status  # Will show error if daemon is down

# Restart
loom run  # Safe to re-run; picks up where it left off

Phase 5: Manual Stage Management

Hold/Release Stages

Prevent a stage from auto-executing:

loom stage hold <stage-id>       # Prevent execution
loom stage release <stage-id>    # Allow execution

Skip a Stage

Mark a stage as intentionally skipped (dependents will be blocked):

loom stage skip <stage-id> --reason "not needed for this iteration"

Force Complete

When a stage is functionally done but acceptance criteria are wrong:

# Request human review (preferred)
loom stage dispute-criteria <stage-id> "criteria X is incorrect because..."

# Force complete (use sparingly)
loom stage complete <stage-id> --force-unsafe --assume-merged

Pass Data Between Stages

# Set output from completed stage
loom stage output set <stage-id> api_port 8080

# Read output in dependent stage
loom stage output get <dependency-stage-id> api_port

Memory & Knowledge Commands

During Knowledge-Bootstrap Stages

Knowledge has a collapsed command surface: loom knowledge sync is the one user-facing verb. It rebuilds derived retrieval artifacts after knowledge-tree changes and performs the one-time flat-to-hierarchical upgrade. loom knowledge context --query <text> [--budget-tokens N] [--scope knowledge|source|all] is deterministic offline retrieval and the same entry point that builds every stage signal's Knowledge Brief. loom knowledge update <target> [content] is the only write path; <target> is a tier-1 file name or <category>/<slug> for a tier-2 topic. loom map --outline <PATH>, --find-all <SYMBOL>, and --impact <SYMBOL_OR_PATH> are read-only views over the derived source graph. INDEX.md regenerates automatically on every knowledge write; there is no index command or final index step.

# Rebuild derived retrieval artifacts and upgrade a legacy flat tree if needed
loom knowledge sync

# Retrieve targeted, deterministic context (also used for every stage Knowledge Brief)
loom knowledge context --query "authentication flow" --budget-tokens 1200 --scope all

# Populate knowledge — the only write path
loom knowledge update architecture "## New Section\n\nContent here"

# Long content via heredoc
loom knowledge update patterns - <<'EOF'
## Authentication Pattern

Uses JWT with refresh token rotation.
Key files: src/auth/jwt.ts:15-80
EOF

# Read-only views over the derived source graph
loom map --outline src/auth
loom map --find-all authenticate
loom map --impact src/auth/jwt.ts

# Record session insights
loom memory note "Found that auth uses middleware pattern"
loom memory decision "Using JWT over sessions" --context "Stateless scaling"

During Implementation Stages

ONLY use loom memory — NEVER loom knowledge update

loom memory note "observation about code"
loom memory decision "chose approach X" --context "because Y"
loom memory question "why is Z done this way?"
loom memory change "src/foo.rs - Added bar() function"

# Review what you've recorded
loom memory list

Memory & knowledge routing by stage type

Knowledge curation happens in the LAST stage (knowledge-distill), not in integration-verify. IV records discoveries to memory; distill reads them and writes knowledge.

# integration-verify: record findings to memory only
loom memory note "IV: feature X reachable via CLI dispatch arm, confirmed end-to-end"

# knowledge-distill (last stage): read all memories, curate to permanent knowledge
loom memory show --all
loom knowledge update mistakes "## Lesson learned about X"
loom knowledge update patterns "## New pattern discovered"
loom review   # prune stale/duplicate knowledge entries

The .loom/work/ Directory

Understanding .loom/work/ structure is critical for debugging. (A workspace created before this directory moved from .work/ keeps that legacy layout forever — see the resolver's back-compat policy.)

.loom/work/
├── config.toml              # Plan reference: source_path, base_branch, plan_id
├── stages/
│   └── NN-<stage-id>.md    # Stage state (YAML frontmatter + markdown body)
│                            # NN = topological depth (01, 02, etc.)
├── sessions/
│   └── <session-id>.md     # Session tracking: PID, stage, status, context %
├── signals/
│   └── <session-id>.md     # Agent task assignment (self-contained instructions)
├── handoffs/
│   └── <stage-id>-handoff-NNN.md  # Context dumps for session continuity
├── memory/
│   └── <stage-id>.md       # Stage-scoped memory journal
├── crashes/                 # Crash reports for failed sessions
├── pids/
│   └── <stage-id>.pid      # PID files for session tracking
├── wrappers/
│   └── <stage-id>-wrapper.sh  # Session launcher scripts
├── orchestrator.sock        # Unix socket for daemon IPC
├── orchestrator.pid         # Daemon PID
└── merge.lock               # Exclusive lock for progressive merges

Key rules:

• NEVER edit .loom/work/ files directly — use loom CLI commands
• Stage files use YAML frontmatter with status, timestamps, merged flag
• Signal files are self-contained — agents read ONLY their signal, not main repo
• .loom/work/ is gitignored and symlinked into each worktree

Worktree Model

Each executing stage gets an isolated git worktree:

PROJECT ROOT
├── .worktrees/
│   └── <stage-id>/                        # Isolated copy of repo
│       ├── .loom/
│       │   └── work -> ../../../.loom/work # Symlink to shared state
│       ├── .claude/                       # Worktree-specific hooks
│       ├── CLAUDE.md                      # Project instructions
│       └── <project files>                # Full repo copy on loom/<stage-id> branch
├── .loom/
│   └── work/                              # Shared orchestration state
└── <main repo files>                      # Main branch

(A legacy workspace instead links <stage-id>/.work -> ../../.work, one level shallower — see the resolver's back-compat policy.)

Path resolution: EXECUTION_PATH = worktree_root + working_dir

If working_dir: "loom" and worktree is .worktrees/my-stage/, commands execute from .worktrees/my-stage/loom/.

Daemon Architecture

The daemon (loom run) is a background process that:

1. Listens on Unix socket (.loom/work/orchestrator.sock)
2. Polls stage files every 5 seconds
3. Creates worktrees for ready stages
4. Spawns Claude Code sessions in terminal windows
5. Monitors session health via heartbeat files
6. Detects crashes via PID liveness checks
7. Auto-merges completed stages (progressive merge)
8. Handles retries with exponential backoff

IPC commands:

• loom status → reads from socket (or files if daemon down)
• loom stop → sends Stop message via socket
• loom status --live → subscribes to streaming updates

Orchestration Decision Tree

Use this when deciding how to respond to loom state:

Is the plan initialized?
├── NO → loom init doc/plans/PLAN-*.md
└── YES
    Is the daemon running?
    ├── NO → loom run
    └── YES
        Check loom status
        ├── All stages Completed → Done! loom clean (optional)
        ├── Stage Executing → Wait (or check context %)
        │   ├── Context < 60% → Healthy, wait
        │   ├── Context 60-75% → Watch closely
        │   └── Context > 75% → Expect handoff soon
        ├── Stage Blocked → Investigate
        │   ├── Read block reason from status --verbose
        │   ├── Fix underlying issue
        │   └── loom stage retry <id>
        ├── Stage MergeConflict → Resolve
        │   ├── loom stage merge <id> (if transient)
        │   └── Manual resolution in worktree
        ├── Stage NeedsHandoff → Resume
        │   └── loom resume <id>
        ├── Stage CompletedWithFailures → Review
        │   ├── loom check <id> --suggest
        │   └── Fix and loom stage retry <id>
        ├── Stage WaitingForInput → Provide input
        │   └── loom stage resume <id>
        └── No stages ready, some WaitingForDeps → Wait for deps

Full Workflow Example

Claude orchestrating a complete loom run:

# 1. Pre-flight
loom repair --fix

# 2. Initialize
loom init doc/plans/PLAN-add-auth.md

# 3. Start execution
loom run

# 4. Monitor (periodically)
loom status
loom graph

# 5. If a stage fails
loom status --verbose                    # See what failed
loom check failed-stage --suggest        # Get fix suggestions
loom stage retry failed-stage            # Retry after fixing

# 6. If merge conflict
loom stage merge conflicted-stage        # Try auto-resolve

# 7. If context exhaustion
loom resume exhausted-stage              # Resume with handoff

# 8. When all complete
loom status                              # Verify DONE-PLAN-*
loom clean --worktrees                   # Clean up worktrees

Recovery Playbook

Corrupted .loom/work/ State

loom repair --fix          # Try repair first
# If repair can't fix:
loom clean --state         # Remove .loom/work/ only
loom init <plan-path>      # Re-initialize
loom run                   # Re-execute (completed work preserved in git)

Orphaned Worktrees

loom worktree list         # See all worktrees
loom worktree remove <id>  # Remove specific worktree
loom clean --worktrees     # Remove all worktrees

Stuck Daemon

loom stop                  # Graceful shutdown
# If that fails:
kill $(cat .loom/work/orchestrator.pid)  # Force kill
rm .loom/work/orchestrator.sock          # Clean socket
loom run                            # Restart

All Else Fails

loom clean --all                         # Nuclear option
loom init doc/plans/PLAN-feature.md      # Fresh start
loom run                                 # Git branches preserve prior work

Operator Gotchas

• The daemon loads the plan ONCE at startup. Editing the plan file (or a .loom/work/stages/*.md) while loom run is live has NO effect on the running graph — no reload mechanism exists. To apply plan changes, loom stop → edit → loom init --clean (or loom clean --state && loom init) → loom run. (Exception: the adjudicator may amend only a single stage's acceptance/wiring in place.)
• Exit code 0 ≠ success. Sandbox blocks, dep-fetch failures, and write denials all exit 0. Read stderr; "blocked / denied / connection refused / failed to download" means investigate, not proceed.
• fix_attempts caps at 3 by default. After repeated acceptance failures a stage stops auto-retrying and escalates (Blocked / NeedsHumanReview). Don't loop loom stage retry blindly — read the block reason and fix root cause, or loom stage dispute-criteria if the criteria themselves are wrong.
• All four stage types default to permission_mode: auto (resolves stage > plan > stage-type default). Loom stages run unattended, so the agent auto-accepts actions its heuristics deem safe; the sandbox deny/allow rules are the real boundary. Override to accept-edits/plan at plan or stage level to tighten.
• loom plan verify checks STRUCTURE only — valid YAML/DAG/bookends. It does NOT run acceptance, prove claims, or (currently) catch bypass-permissions. A plan can pass plan verify yet fail loom init or produce a non-working feature.
• loom check runs acceptance and every goal-backward layer (artifacts, wiring, wiring_tests, dead_code_check) without changing stage state. loom stage complete runs acceptance before transitioning the stage.

Anti-Patterns

Quick Reference: Essential Commands

Lifecycle

loom repair --fix                    # Pre-flight health check
loom init <plan>                     # Initialize from plan
loom run                             # Start daemon
loom status [--live|--verbose]       # Monitor
loom stop                            # Shutdown daemon
loom clean [--all|--worktrees]       # Cleanup

Stage Management

loom stage retry <id>                # Retry failed stage
loom stage reset <id>                # Reset to queued
loom stage complete <id>             # Mark done (runs acceptance)
loom stage merge <id>                # Retry failed merge
loom stage merge <id> --resolved     # After manual merge resolution
loom stage hold/release <id>         # Pause/unpause auto-execution
loom stage skip <id> --reason "..."  # Skip intentionally

Debugging

loom status --verbose                # Detailed failure info
loom check <id> --suggest            # Acceptance + goal-backward + suggestions
loom diagnose <id>                   # Spawn diagnostic session
loom graph                           # Visualize execution DAG

Memory & Knowledge

loom memory note "..."               # Record insight
loom memory decision "..." --context "..."  # Record decision
loom memory list                     # Review entries
loom memory show --all               # All stage memories
loom knowledge sync                  # Rebuild derived retrieval artifacts
loom knowledge context --query "..." # Deterministic offline retrieval
loom knowledge update <target> [content] # The only knowledge write path
loom map --outline <path>            # Read-only source-graph outline
loom map --find-all <symbol>         # Read-only source-graph symbol lookup
loom map --impact <symbol-or-path>   # Read-only source-graph impact view