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 | Skill | Use For | | --- | --- | | `/loom-plan-writer` | Creating new plan files | | `/loom-wiring-test` | Designing wiring verification YAML | | `/loom-before-after` | Before/after delta-proof verification pairs | | `/loom-dead-code-check` | Dead code detection configuration | | **This skill** | Everything after the plan is written | --- ## The Loom Lifecycle ```text WRITE PLAN VALIDATE & INIT EXECUTE MONITOR & DEBUG ─────────────────── ─────────────────────── ────────────────── ────────────────── /loom-plan-writer → loom init plan.md → loom run → loom status loom repair --fix loom check 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: ```bash # 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 ```bash 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:** | Error | Cause | Fix | | --- | --- | --- | | "must define acceptance criteria or ... artifact, wiring check, or wiring_test" | Standard/IV stage has no `acceptance` AND no goal-backward check | Add non-empty `acceptance` OR one of `artifacts`/`wiring`/`wiring_tests`/`dead_code_check` | | "cycle detected" | Circular dependencies between stages | Remove the cycle in the dependency graph | | "invalid stage_type" | PascalCase like "Standard" | Use lowercase: `standard`, `knowledge`, `integration-verify`, `knowledge-distill` | | "working_dir required" | Stage missing working_dir field | Add `working_dir: "."` or appropriate subdirectory | | "path traversal" | `../` in any path field | Use paths relative to working_dir, no `../` | | "triple backticks in YAML" | Code fences inside description | Use plain indented text instead of fences | | "bypass-permissions is not allowed" | `permission_mode: bypass-permissions` | Use `auto` (default), `accept-edits`, `plan`, or `default`. Note: `loom plan verify` misses this; only `loom init` catches it | > ⚠️ **`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 ```bash # 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 ```bash # 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 | State | Filename | When | | --- | --- | --- | | Not started | `PLAN-feature.md` | After writing | | Running | `IN_PROGRESS-PLAN-feature.md` | After `loom run` | | Finished | `DONE-PLAN-feature.md` | All stages merged | --- ## Phase 3: Monitor ### Check Status ```bash # 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 ```bash 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 ```bash # 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 ``` ### Common Failure Scenarios #### Acceptance Criteria Failed The stage's acceptance commands returned non-zero. ```bash # 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. ```bash # 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. ```bash # 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. ```bash # 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. ```bash # 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 ```bash # 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: ```bash 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): ```bash loom stage skip <stage-id> --reason "not needed for this iteration" ``` ### Force Complete When a stage is functionally done but acceptance criteria are wrong: ```bash # Dispute a wrong check; routes to the adjudicator, which can amend it loom stage dispute-criteria <stage-id> --criterion-index <n> --reason "<why it is wrong>" loom stage dispute-criteria <stage-id> --field wiring --criterion-index <n> --reason "<why>" # A need only a person can meet (credential, host install, network domain or path) loom stage block <stage-id> "<what is needed and why>" # Force complete (use sparingly) loom stage complete <stage-id> --force-unsafe --assume-merged ``` ### Pass Data Between Stages ```bash # 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. ```bash # 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`** ```bash 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 | Stage type | `loom memory` | `loom knowledge` | | ---------- | ------------- | ---------------- | | knowledge (bootstrap) | YES | YES | | standard (implementation) | YES (ONLY) | FORBIDDEN | | integration-verify | YES (record findings for distill) | NO | | knowledge-distill | YES | YES (curate from memory) | Knowledge **curation** happens in the LAST stage (`knowledge-distill`), not in integration-verify. IV records discoveries to memory; distill reads them and writes knowledge. ```bash # 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.) ```text .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: ```text PROJECT ROOT ├── .worktrees/ │ └── <stage-id>/ # Isolated copy of repo │ ├── .loom/ │ │ └── work -> ../../../.loom/work # Symlink to shared state