Workflow

For anything more involved than a one-shot fix, Weave uses an explicit Plan → Review → Execute workflow. The plan is a real file on disk you can read and edit, the review is a separate agent with its own bias, and execution is a resumable, checkbox-driven loop. If a session crashes mid-way, you pick up exactly where you left off.

When the full workflow runs

Loom uses the structured workflow when the request:

• Takes 5 or more steps.
• Touches multiple files.
• Involves an architectural decision.
• Benefits from a reviewable plan before any code is written.

For everything else — single-file fixes, quick questions, small tweaks — Loom either answers directly or delegates to a single subagent without writing a plan.

1. Plan

User → @loom (assesses) → @pattern (researches) → .weave/plans/{name}.md

Loom delegates to Pattern, which:

1. Researches the codebase by dispatching to @thread.
2. Looks up library docs via @spindle if needed.
3. Writes a structured markdown plan to .weave/plans/{name}.md.

The plan format is deliberately simple:

# Add OAuth2 device-flow login

## Objective
Allow CLI users to authenticate without pasting a token.

## Tasks
- [ ] Add `device-flow` command to `src/cli/commands/`
- [ ] Implement polling loop with backoff in `src/auth/device.ts`
- [ ] Wire token persistence into existing keychain helper
- [ ] Add integration test against the staging IdP
- [ ] Document the new command in the CLI reference

Every task is an actionable, atomic checkbox. Pattern never writes code — only plans.

2. Review (optional)

.weave/plans/{name}.md → @weft → APPROVE | REJECT

For high-stakes plans Loom hands the file to Weft, which validates that:

• Referenced files actually exist.
• Each task has enough context to execute independently.
• No two tasks contradict each other.
• The plan covers the stated objective.

Weft is approval-biased and caps rejection at three blocking issues per pass. If it rejects, the issues go back to Pattern for revision, then loop.

For plans involving auth, crypto, token storage, or input validation, Loom additionally routes through Warp, which is skeptical-biased and rejects by default until security claims are evidenced.

3. Execute

You start execution from the chat:

/start-work [plan-name]

That command:

1. Creates .weave/state.json with the plan path and progress markers.
2. Switches the active agent to Tapestry.
3. Begins working through tasks sequentially.

For each task Tapestry:

1. Finds the first unchecked - [ ] line.
2. Implements it (writes code, runs commands, creates files — usually by dispatching to Shuttle).
3. Verifies completion (reads files back, runs tests, checks acceptance criteria).
4. Ticks the box → - [x].
5. Moves to the next unchecked task.
6. When the file has no unchecked tasks, reports a final summary.

After implementation completes, Loom can route the diff through Weft for a post-implementation review.

Resuming interrupted work

State persists in .weave/state.json. If your session is interrupted — laptop sleep, Fabric crash, deliberate Ctrl-C — running /start-work again resumes from the first unchecked task. No re-planning, no restart.

$ ls .weave/
plans/
  add-oauth-device-flow.md
state.json

state.json is small and machine-readable; you can inspect it manually if a run wedges.

Quick tasks (no plan)

For requests that don't need the workflow — "rename this var", "what's in this file", "fix the typo on line 42" — Loom skips planning entirely and either answers directly or delegates to a single subagent. The Plan → Review → Execute machinery is opt-in based on complexity, not enforced on every request.

Supporting features

The workflow is the headline feature, but a few subsystems make it work reliably.

Hooks

Weave ships five lifecycle hooks. All are enabled by default; disable them via disabled_hooks when needed.

Skills

Skills are markdown files (SKILL.md) that get prepended to an agent's system prompt — domain expertise injected on demand. Weave loads skills from three scopes:

• builtin — shipped with the plugin.
• user — ~/.config/fabric/skills/.
• project — .fabric/skills/.

Add custom roots with skill_directories and pin which skills load into which agents:

{
  "agents": {
    "shuttle": {
      "skills": ["react-best-practices", "api-design"],
    },
  },
}

Background agents

Loom can spawn subagents in parallel via the BackgroundManager. Concurrency is bounded — globally, per-provider, and per-model — so parallel research doesn't blow your rate limits.

{
  "background": {
    "defaultConcurrency": 5,
    "providerConcurrency": { "anthropic": 5, "openai": 3 },
  },
}

See Background agents for the full set of knobs.

Tool permissions

Tool access is enforced per-agent. By default:

• @thread, @spindle, @weft, @warp, @pattern are read-only — no write, no edit, no shell mutations.
• @loom plans and delegates — its writes are intentional handoffs, not implementation.
• @tapestry, @shuttle have the broad permissions needed to execute work.

Override per-agent in your config:

{
  "agents": {
    "shuttle": {
      "tools": {
        "write": false,
        "bash": false,
      },
    },
  },
}

End-to-end example

> Add a /export command that dumps the current session to JSON.

@loom: This needs a plan — touches the command registry, session
serializer, and tests. Dispatching to @pattern.

@pattern: Researching… (delegates to @thread for command registry
location + @spindle for the JSON-Schema spec we use elsewhere)
→ wrote .weave/plans/add-export-command.md (4 tasks)

@weft: Plan APPROVED. Files exist, tasks atomic, no contradictions.

> /start-work add-export-command

@tapestry: Starting. Task 1/4: Register `/export` in command table…
→ implemented, verified, [x]
@tapestry: Task 2/4: Add JSON serializer for Session…
[…]
@tapestry: All 4 tasks complete. Summary: …

@weft: Post-implementation review — APPROVED. No leftover TODOs,
tests pass, file references resolve.

That's the full loop. Read the Configuration page next to tune model selection, concurrency, and which subagents are even active.