Imported from awsaavedra/agent-loom (AGENTS.md). Install upstream with npx skills add awsaavedra/agent-loom. Copyright stays with the author.

Loom — AGENTS.md

AI assistant context. Tool mapping: Claude Code → symlink CLAUDE.md here · Cursor → .cursor/rules/ · Copilot → .github/copilot-instructions.md · Codex/generic → this file. Symlink: ln -sf AGENTS.md CLAUDE.md

Project

Multi-agent Obsidian vault orchestrator: decompose a knowledge-work prompt into subtasks, route each to the right model tier via Bifrost, write all outputs back as native Markdown.

Quickstart

Default vault (loom repo as vault root)

sudo -v && ./scripts/install.sh   # one-shot: system deps, venv, Ollama, Bifrost (repo-local)
npx @maximhq/bifrost              # configure providers at http://localhost:8080 (manual step)
loom init
loom validate
loom run "synthesize recent notes on X"

External vault (e.g. {handle}-knowledge-management) — deferred; do loom-side work first

Wire up an external vault only after loom validate passes cleanly here first.

# 1. Start Bifrost (once per session — from agent-loom dir)
npx @maximhq/bifrost -app-dir .bifrost/
# 2. Init the vault (once — reads existing .loom/loom.yaml for paths; skips existing files)
loom init --vault /path/to/your-vault
# 3. Validate (all checks except Bifrost require no live model)
loom validate --vault /path/to/your-vault
# 4. Run
loom run "tag untagged inbox notes" --vault /path/to/your-vault --dry-run

Manual smoke tests (required before first live run against external vault)

Stack

Python 3.11–3.12 · typer · rich · httpx + tenacity · python-frontmatter · obsidiantools · pytest · ruff · mypy
External: Bifrost (Go sidecar, LLM routing) · Obsidian CLI v1.12+ · TurboVault (headless MCP) · Ollama + Gemma 4 (local models)

Commands

• Install dev: pip install -e ".[dev]"
• Test single: python3 -m pytest tests/path/to/test.py -v
• Test all: python3 -m pytest tests/ -v
• Lint: python3 -m ruff check loom/
• Type check: python3 -m mypy loom/ --ignore-missing-imports
• Init vault: loom init [--vault PATH]
• Validate: loom validate [--vault PATH]
• Run: loom run "prompt" [--dry-run] [--plan-only] [--vault PATH]
• Status: loom status [--vault PATH]
• Diff: loom diff [RUN_ID] [--vault PATH]

Architecture

loom/              → orchestrator, agents, config, models, CLI
loom/vault/        → adapter + three backends (direct, obsidian_cli, turbovault)
loom/routing/      → bifrost HTTP client
tests/unit/        → pure unit tests (mocked models, no I/O)
tests/integration/ → full-run tests with mocked Bifrost
tests/fixtures/    → sample vault for test harness
.loom/             → project-level default config + zone registry
.ai/skills/        → reusable AI skills (invoke by name)

Key files:

loom/models.py           → all shared dataclasses + exceptions (zero internal imports)
loom/config.py           → load_config, load_zone_registry, validate_config
loom/orchestrator.py     → Plan-then-Execute loop, run_orchestration()
loom/agents.py           → delegate_task() + SYSTEM_PROMPTS for 4 agent roles
loom/vault/adapter.py    → central I/O hub: zone enforcement + atomic writes
loom/vault/direct.py     → direct filesystem backend (CI/fallback)
loom/vault/turbovault.py → MCP stdio client; protocol hard-pinned "2025-11-25"
loom/vault/obsidian_cli.py → Obsidian Desktop CLI wrapper
loom/routing/bifrost.py  → BifrostClient: httpx + tenacity 3× exponential retry
loom/cli.py              → typer app: init, run, status, diff, validate, rerun

Rules

Cross-cutting

0. No internet without permission.
1. Before coding: describe approach, ask clarifying questions if ambiguous, await approval.
2. Tasks touching >3 files: stop and split into subtasks first.
3. After coding: list breakage risks, suggest covering tests.
4. Bugs: write failing reproduction test, then fix until passing. Test must fail without the fix.
5. On correction: add rule here to prevent recurrence.
6. Minimize tokens, preserve utility.
7. Build artifacts and envs (venv/, *.egg-info/, __pycache__/, node_modules/, target/) are noise — gitignore and never read.

Loom-specific

• IMPORTANT: type check after every code change (python3 -m mypy loom/ --ignore-missing-imports)
• IMPORTANT: No LiteLLM — supply chain attack on 1.82.7/1.82.8 (March 2026); all LLM calls go through Bifrost
• No shell=True in subprocess calls — list form only in vault/obsidian_cli.py
• Obsidian CLI always exits 0 — validate stdout content, never returncode
• TurboVault protocol: hard-pinned "2025-11-25" in vault/turbovault.py
• 02_notes/ (raw_notes zone) is read-only for all agents — ZoneViolationError on any write
• python-frontmatter for all frontmatter reads/writes; obsidiantools only for graph/link queries
• CI: always use LOOM_VAULT_MODE=direct — no Obsidian Desktop or TurboVault in CI

Workflow

• Model calls → Bifrost at http://localhost:8080/v1/chat/completions; model strings: anthropic/claude-sonnet-4, ollama/gemma4
• All vault writes go through vault/adapter.py — never bypass
• Vault backend auto-selected: obsidian CLI → turbovault → direct
• Commit style: #type, terse description
• Test then type-check after every code change

Design Principles

• Vault-native. The vault IS shared memory; every orchestration artifact is a readable Markdown note
• Plan-then-Execute. Full subtask plan written to ledger before any vault writes occur
• No Python LLM lib. Bifrost (Go binary) handles routing; no PyPI LLM abstraction surface
• CLI-first. loom run is a single shell command; no GUI dependencies
• Ejectable. Local models + local vault; no cloud lock-in

Out of scope (v0)

• Parallel subtask execution → v1 (--parallel N)
• Web search for researcher → v1 (implemented; gated by config, off by default)
• loom rerun → v1 (implemented)
• Dynamic replanning mid-run
• Non-Obsidian vault support
• LiteLLM or any PyPI LLM routing library

Skills

Catalog + lane definitions: .ai/readme.md.

Software

@.ai/skills/software-engineering.md @.ai/skills/api-design.md @.ai/skills/testing.md @.ai/skills/debug.md @.ai/skills/performance.md @.ai/skills/security.md @.ai/skills/code-review.md @.ai/skills/docs-review.md @.ai/skills/release-engineering.md @.ai/skills/governance.md @.ai/skills/ship.md

Writing

@.ai/skills/communication.md

Both

@.ai/skills/argumentation.md @.ai/skills/diagnostic.md @.ai/skills/planning.md @.ai/skills/estimation.md @.ai/skills/delegation.md @.ai/skills/research.md @.ai/skills/data-analysis.md @.ai/skills/legal.md @.ai/skills/privacy.md @.ai/skills/skill-authoring.md