@fabriccode/weave

v0.7.14

Published

14 days ago

Weave — lean Fabric plugin with multi-agent orchestration

0High
0Medium
0Low

preddy4690

fabric plugin agents weave

Weave

Weave is a lean Fabric plugin with multi-agent orchestration. It provides a cohesive framework for weaving agents, tools, and skills into structured workflows. By delegating complex tasks to specialized agents and monitoring execution state through hooks, Weave ensures reliable and efficient project development.

Quick Install

The easiest way (Fabric v7.0.50+):

fabric install-weave

This command automatically:

✅ Adds @fabriccode/weave to your fabric.jsonc
✅ Creates weave-fabric.jsonc with default settings
✅ Offers to restart Fabric to activate the plugin

Alternative: One-liner installation (macOS/Linux):

curl -fsSL https://raw.githubusercontent.com/Fabric-Pro/fabric-weave/main/script/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/Fabric-Pro/fabric-weave/main/script/install.ps1 | iex

See the Installation section below for manual setup instructions.

Overview

8 specialized agents with weaving-themed names designed for specific roles in the development lifecycle.
Category-based task dispatch to route work to domain-optimized models and configurations.
Skill system for injecting domain-specific expertise that modifies agent behavior via prompt orchestration.
Background agent management for parallel asynchronous sub-agent execution with concurrency control.
Context window monitoring to track token usage and suggest recovery strategies when limits are approached.
Tool permissions enforced per-agent to ensure safety and prevent unauthorized file modifications.
JSONC configuration supporting comments and trailing commas with hierarchical user and project-level merging.

Documentation

Visit Fabric Agents for more information, or head straight to the documentation for detailed guides on setup, configuration, and usage.

Agents

Agents appear in the Fabric UI as @loom, @tapestry, @thread, etc. The same lowercase names are used as config keys in weave-fabric.jsonc.

Agent Modes

primary: Uses the user-selected model in the Fabric UI.
subagent: Defaults to the same model as the main orchestrator unless explicitly overridden in config.
all: Available in both primary and subagent contexts.

Agent Details

Loom is the central orchestrator and the default entry point for every request. It breaks down complex problems into tasks, decides which agents to delegate to, and tracks progress obsessively via todo lists. Loom never implements code directly — it plans and delegates. For quick fixes it acts immediately; for complex work it kicks off the plan → review → execute workflow.

Pattern is the strategic planner. When a task requires 5+ steps or involves architectural decisions, Loom delegates to Pattern, which researches the codebase (via Thread) and external docs (via Spindle), then produces a structured implementation plan saved to .weave/plans/{name}.md. Plans use - [ ] checkboxes for every actionable task. Pattern never writes code — only plans.

Weft is the reviewer and auditor. It validates plans before execution and reviews completed work after implementation. Weft is approval-biased and only rejects for true blocking issues (max 3 per review). It checks that file references are correct, tasks have sufficient context, implementations match requirements, and no stubs or TODOs are left behind. Weft is read-only.

Warp is the security and specification compliance auditor. It reviews code changes for security vulnerabilities (injection, auth bypass, token handling, crypto weaknesses) and verifies compliance with standards like OAuth2, OIDC, WebAuthn, and JWT. Warp has a skeptical bias — unlike Weft, it rejects by default when security patterns are detected. It self-triages to fast-exit on non-security changes, and can webfetch RFCs for verification. Warp is read-only.

Tapestry is the execution engine. Activated by the /start-work command, it reads a plan from .weave/plans/ and works through tasks sequentially — writing code, running commands, verifying output, and marking checkboxes as it goes. Tapestry cannot spawn subagents; it focuses on heads-down implementation. If interrupted, it resumes from the first unchecked task.

Thread is the fast codebase explorer. Loom delegates to Thread whenever it needs to understand code structure, find files, or answer questions about the repository. Thread uses grep, glob, and read tools with zero creativity (temperature 0.0) to return precise, factual answers with file paths and line numbers. Thread is read-only.

Spindle is the external researcher. When Loom needs documentation for a library, API reference, or any information outside the codebase, Spindle fetches URLs, reads docs, and synthesizes findings with source citations. Spindle is read-only.

Shuttle is the domain specialist. When work falls into a specific category (e.g., visual engineering, data processing), Loom dispatches Shuttle with full tool access to execute the task. Shuttle's model and configuration can be overridden per-category for domain-optimized performance.

Workflow

Weave uses a structured Plan → Review → Execute workflow for complex tasks. Simple requests are handled directly by Loom without the full cycle.

When the Full Workflow Is Used

Tasks requiring 5+ steps or architectural decisions
Multi-file refactors or new feature implementations
Work that benefits from a reviewable plan before execution

1. Plan

Loom delegates to Pattern, which researches the codebase and produces a detailed implementation plan:

User Request → Loom (assesses complexity) → Pattern (researches + plans)
                                              ↓
                                     .weave/plans/{name}.md

The plan includes clear objectives, deliverables, and atomic tasks marked with - [ ] checkboxes. Pattern never writes code.

2. Review (Optional)

For high-stakes or complex plans, Loom delegates to Weft to validate the plan before execution:

.weave/plans/{name}.md → Weft (validates) → APPROVE or REJECT

Weft checks that referenced files exist, tasks have sufficient context, and there are no contradictions. If rejected, issues are sent back to Pattern for revision.

3. Execute

The user runs /start-work to begin execution:

/start-work [plan-name] → creates .weave/state.json → switches to Tapestry

Tapestry reads the plan and executes tasks sequentially:

Find the first unchecked - [ ] task
Implement the task (write code, run commands, create files)
Verify completion (read files, run tests, check acceptance criteria)
Mark the checkbox - [x]
Move to the next unchecked task
When all tasks are complete, report a final summary

Resuming Interrupted Work

If a session is interrupted, running /start-work again resumes from the first unchecked task — no re-planning or restarting. The work state is persisted in .weave/state.json, so progress is never lost.

Quick Tasks (No Plan Needed)

For simple requests — single-file fixes, quick questions, small edits — Loom handles the work directly or delegates to the appropriate agent without creating a formal plan.

Installation

This package is published on npm.

Prerequisites

Fabric v7.0.50 or later

Automated Installation (Recommended)

Using Fabric CLI (all platforms - macOS, Linux, Windows):

fabric install-weave

This built-in command will:

✅ Detect your Fabric configuration directory
✅ Add @fabriccode/weave to your fabric.jsonc
✅ Create weave-fabric.jsonc with sensible defaults
✅ Offer to restart Fabric to activate the plugin

Alternative: Shell installer (macOS/Linux):

curl -fsSL https://raw.githubusercontent.com/Fabric-Pro/fabric-weave/main/script/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/Fabric-Pro/fabric-weave/main/script/install.ps1 | iex

Manual Installation

If you prefer to configure manually:

Open ~/.config/fabric/fabric.jsonc and add the plugin:

{
  "plugin": ["@fabriccode/weave"],
}

Optional: Create ~/.config/fabric/weave-fabric.jsonc for custom agent configuration (see Configuration section)
Restart Fabric — it automatically installs npm plugins at startup. The plugin works with zero configuration out of the box.

Troubleshooting

| Issue | Solution | | --------------------------------- | ----------------------------------------------------------------------------------- | | 404 Not Found | Ensure the package name is correct: @fabriccode/weave. | | Package not found after publish | npm can take a few minutes to propagate. Wait and retry. | | Blank screen / plugin not loading | Auto-install may have failed silently. See manual install below. |

Manual install

If Fabric shows a blank screen after restart, the plugin may not have auto-installed (this can happen if ~/.config/fabric/package.json has a stale dependency that blocks bun). Install manually:

cd /tmp
npm pack @fabriccode/weave@latest

mkdir -p ~/.config/fabric/node_modules/@fabriccode/weave
tar xzf fabriccode-weave-*.tgz -C ~/.config/fabric/node_modules/@fabriccode/weave --strip-components=1

mkdir -p ~/.config/fabric/node_modules/@fabriccode/plugin
npm pack @fabriccode/plugin@latest
tar xzf fabriccode-plugin-*.tgz -C ~/.config/fabric/node_modules/@fabriccode/plugin --strip-components=1

mkdir -p ~/.config/fabric/node_modules/@fabriccode/sdk
npm pack @fabriccode/sdk@latest
tar xzf fabriccode-sdk-*.tgz -C ~/.config/fabric/node_modules/@fabriccode/sdk --strip-components=1

Then restart Fabric.

Uninstalling

To fully remove the Weave plugin from your project:

Step 1: Remove from fabric.jsonc

Delete the @fabriccode/weave entry from the plugin array in your ~/.config/fabric/fabric.jsonc:

{
  "plugin": []
}

Step 2: Clean up project artifacts (optional)

Weave may have created plan and state files during usage. Remove them if no longer needed:

rm -rf .weave/

You can also remove any project-level configuration if present:

rm -f .fabric/weave-fabric.jsonc .fabric/weave-fabric.json

Step 3: Clean up user-level configuration (optional)

If you no longer use Weave in any project, remove the global configuration:

rm -f ~/.config/fabric/weave-fabric.jsonc ~/.config/fabric/weave-fabric.json

Configuration

Weave searches for configuration files in the following locations, merging them in order (user config → project config → defaults):

Project: .fabric/weave-fabric.jsonc or .fabric/weave-fabric.json
User: ~/.config/fabric/weave-fabric.jsonc or ~/.config/fabric/weave-fabric.json

The configuration uses JSONC format, allowing for comments and trailing commas.

Example Configuration

Place this file at ~/.config/fabric/weave-fabric.jsonc (user-wide) or .fabric/weave-fabric.jsonc (project-specific):

{
  "$schema": "https://agents.fabric.pro/weave-config.json",

  // Override model per agent. Keys are the lowercase agent names shown in the UI.
  // Subagents default to the same model as loom when not set here.
  "agents": {
    // Primary agents — use your main model by default, override here if needed
    "loom": {
      "model": "anthropic/claude-opus-4",
    },
    "tapestry": {
      "model": "anthropic/claude-sonnet-4",
    },
    // Subagents — pin to a faster/cheaper model for high-volume tasks
    "thread": {
      "model": "anthropic/claude-haiku-4",
    },
    "spindle": {
      "model": "anthropic/claude-haiku-4",
    },
    "pattern": {
      "model": "anthropic/claude-sonnet-4",
    },
    "weft": {
      "model": "anthropic/claude-sonnet-4",
    },
    "warp": {
      "model": "anthropic/claude-sonnet-4",
    },
    "shuttle": {
      "model": "anthropic/claude-sonnet-4",
    },
  },

  // Pin all subagents to a single provider (e.g. Kimi K2.5)
  // "agents": {
  //   "thread":  { "model": "kimi-for-coding/k2p5" },
  //   "spindle": { "model": "kimi-for-coding/k2p5" },
  //   "pattern": { "model": "kimi-for-coding/k2p5" },
  //   "weft":    { "model": "kimi-for-coding/k2p5" },
  //   "warp":    { "model": "kimi-for-coding/k2p5" }
  // },

  // Category-based dispatch — override model for shuttle when working in a domain
  "categories": {
    "visual-engineering": {
      "model": "google/gemini-3-pro",
    },
  },

  // Disable specific hooks, agents, tools, or skills
  "disabled_hooks": [],
  "disabled_agents": [],
  "disabled_tools": [],
  "disabled_skills": [],

  // Background agent concurrency (default: 5)
  "background": {
    "defaultConcurrency": 5,
  },
}

Configuration Fields

agents — Override model, temperature, prompt_append, tools, and skills per agent. Keys are lowercase agent names (loom, tapestry, shuttle, pattern, thread, spindle, weft, warp).
categories — Model and tool overrides for category-based dispatch via @shuttle.
disabled_hooks / disabled_agents / disabled_tools / disabled_skills — Selective feature disabling.
background — Concurrency limits for parallel background agents.
skills — Custom skill discovery paths and recursion settings.
experimental — Plugin load timeouts and context window threshold adjustments.

Features

Hooks

Weave includes 5 built-in hooks that monitor and modify agent behavior:

context-window-monitor — Warns when token usage approaches limits and suggests recovery strategies.
write-existing-file-guard — Tracks file reads to prevent agents from overwriting files they haven't examined.
rules-injector — Automatically injects contextual rules when agents enter directories containing AGENTS.md.
first-message-variant — Applies specific prompt variants on session start for consistent behavior.
keyword-detector — Detects keywords in messages to trigger behavioral changes or agent switches.

All hooks are enabled by default and can be disabled via the disabled_hooks configuration.

Skills

Skills are injectable prompt expertise loaded from markdown files (SKILL.md). They modify agent behavior by prepending domain-specific instructions to the agent's system prompt.

Skills are discovered across three scopes:

builtin — Provided by the Weave plugin.
user — Located in the user's global configuration directory.
project — Located in the current project's .fabric/skills/ directory.

Background Agents

Weave supports parallel asynchronous sub-agent management via the BackgroundManager. This allows Loom to spawn multiple agents simultaneously to handle independent tasks, with configurable concurrency limits to manage API rate limits.

Tool Permissions

Tool access is controlled per-agent to ensure safety and specialized focus. For example, Thread and Spindle are strictly read-only; they are denied access to write, edit, and task management tools. These permissions can be customized globally or per-agent in the configuration.

Development

Build: bun run build
Test: bun test
Typecheck: bun run typecheck
Clean: bun run clean

License

MIT