YAML composer for assembling agent prompts, hooks, and MCP configs from reusable behaviors.
Make your agent prompts, hooks, and MCP configs maintainable, vendor-agnostic, and diffable.
Define agent identity, capabilities, and constraints in version-controlled YAML. Diff your prompts in code review like any other change.
The same behavior catalog renders prompts, hooks, and MCP configs for Claude Code, Cursor, Cline, Aider — anything that consumes prompt + hook + MCP-config triples.
Behaviors compose. A read-only-mode overlay rewrites the agent's instructions automatically when paired with announce-before-write, instead of duplicating prompt text across roles.
inspectproject-context
worktree-isolation
read-only-mode
announce-readonly-adaptationEvery behavior contributes numbered sections. The assembler sorts them, dedups, and produces byte-identical output for identical inputs — perfect for CI.
Generated agents pair with mcp-coordinator for runtime announce/conflict/quota; see essaim for an end-to-end example.
Hand-written agent prompts don't scale. Once you have 5+ roles across 2+ vendors, the catalog becomes unmaintainable.
Every new agent role starts as a copy of an existing prompt. Drift sets in. The team's many agents say slightly different things about the same constraints.
Prompts live in scattered files, copy-paste blocks in chat windows, or commits from days ago that nobody can reconstruct. Reviewing a prompt change is harder than reviewing code.
Switching from Claude Code to Cursor or Aider means rewriting prompts, hooks, and MCP configs by hand. The same behavior — say, "work in read-only mode" — gets rewritten three times.
Compose your behavior catalog once, ship hundreds of agent variants. Without copy-paste, without drift, without vendor lock-in.
All assembled from N YAML files. Add a vendor target — every preset re-renders. Change a behavior — all M presets pick it up. Hand-edited prompts cannot do this.
Change a single line in read-only-mode.yaml — every preset that includes it re-renders byte-deterministically. No find-and-replace across 50 prompt files. No drift between agents that should say the same thing.
Composition rules apply mutations declaratively when behaviors meet — "if A and B both present, rewrite section X". Replaces dozens of conditional if/else blocks copy-pasted across role-specific prompts.
The same N behaviors compose for Claude Code, Cursor, Cline, Aider — anything consuming prompt + hook + MCP-config triples. Add vendor #5 with one writer plugin; never rewrite a behavior.
Generated outputs are deterministic. Diff them in PRs. Catch behavior drift in CI before it ships. Onboarding a new agent role → copy a preset, change one parameter, ship.
Watch a complex 6-behavior preset assemble. Composition rules fire automatically. Three artifacts emerge — deterministic, vendor-portable, diffable.
audit-team-leader
project-context
000
worktree-isolation
010, 055
sequential-wait
012
announce-before-write
020
read-only-mode
090
activity-tracking
095
3 of 4 matched
sequential-then-announce
when both present
announce-readonly-adaptation
when both present
tracking-overlay
when activity-tracking
byte-deterministic
Change one behavior YAML → every preset that includes it re-renders byte-identically. That's the leverage.
Five passes from a preset to ready-to-ship prompts, hooks, and MCP configs.
A preset is resolved into a flat list of behaviors. Shared dependencies are deduplicated automatically.
Every behavior is checked: required parameters present, references resolve, schema valid. Errors point to the source YAML.
Composition rules apply: when behaviors A and B are both present, override section X, inject section Y, or strip behavior Z.
Sections sort numerically into a single prompt. Hooks consolidate per lifecycle. MCP tools merge into a single .mcp.json. Output is byte-deterministic.
One YAML file. Every field, optional or required, in one place.
name — Unique kebab-case identifier used to composedescription — One-line summary shown in catalogs and diffssections — Prompt fragments keyed by NNN-name, deterministic ordercategory — Taxonomy bucket: workspace, coordination, mission, safety, tonerequires — Hard dependencies on other behaviors and infrastructureconflicts_with — Behaviors that cannot be composed alongside this onesuggests — Soft hints surfaced to the user, never enforcedparams — Typed inputs with default, required flag, and descriptionhooks — Lifecycle scripts (script, args, blocking, order) per phasemcp_tools — MCP servers this behavior declares as neededphase — Declares phase name, tools_mode, and loopapplies_when — Conditional gate based on the active phase tools_modeOnly name, description, and sections are strictly required. Everything else is opt-in — declare exactly what your behavior needs, nothing more.
When two behaviors meet, rewrite or strip sections — without forcing every behavior to know about every other.
when predicateA rule fires only when the assembled behavior set matches its predicate. Combine all, any, none, and params_match to express « these two together, but not with that third one » without coupling behavior YAMLs to each other.
Once a rule matches, its actions reshape the assembly. Override an existing section in place, inject a brand-new bridge section, force params on a behavior you don't own, or strip a behavior wholesale — all declaratively, no JS hooks.
Rules are evaluated in ascending priority order (default 0), then by registration order. Lower priorities run first — so a high-priority « strip » rule sees the result of every override beneath it. Deterministic. Diffable.
compositions/*.yamlOne file per rule, version-controlled next to your behaviors. The engine auto-loads the directory, evaluates every rule against the resolved behavior set, and emits a compositionRulesApplied trace in the pipeline result — so you can audit which rules fired on every render.
Bash scripts run at four lifecycle points. Behaviors compose them; the engine merges them per point in declared order.
| Lifecycle point | Fires | Typical use | Example |
|---|---|---|---|
| session-start | Once, before agent's first turn | Setup workspace, env, worktree | worktree-isolation creates a branch |
| pre-tool-use | Before every tool call | Validate, log, gate | Custom rules check before file edit |
| post-tool-use | After every tool call | Audit, sync, cleanup | Activity tracking writes to log |
| session-stop | Once, after agent's last turn | Teardown, archive | worktree-isolation cleans up branch |
Add a hooks: block to any behavior YAML. The engine collects entries from every behavior in the preset and writes one merged script per lifecycle point.
The engine merges hooks from multiple behaviors by lifecycle point, sorted by order. The Bundle target writes them as hooks/<lifecycle>.sh. The Skill target drops them with a warning.
Multi-stage workflows out of the box. Tools modes per phase, profiles for intent.
A behavior can declare a phase; presets that include phased behaviors render as a multi-stage workflow, while presets without any phase produce a single one-shot prompt (backward-compat).
| Phase | Tools | Loop | Purpose |
|---|---|---|---|
discover |
read_only | no | Scan code, list findings independently. |
review |
none | no | Compare findings, dedup pool. |
execute |
full | yes | Atomic claim → run → claim next. |
no-phase |
configurable | no | One-shot mode (backward-compat). |
A behavior can also declare applies_when.phase_tools_mode: ["read_only"] to scope itself to phases with a matching tools mode — included in some stages, filtered out of others.
A profile is a shorthand declared on a preset or an agent. It signals what the agent is for; composition rules and templates can read it.
codeurprofile: codeur
Agent that writes code. Defaults to full tool access. Pairs with worktree-isolation and mission behaviors.
communicantprofile: communicant
Agent that reports, reviews, communicates. Pairs with read-only-mode for analysis-only flows.
A preset names the behaviors. The engine resolves, validates, composes, assembles, and emits prompt.md + hooks/*.sh + .mcp.json — deterministic, byte-for-byte.
Each behavior contributes numbered sections. Layers are a recommended convention so prompts stay readable as your catalog grows.
From npm install to a shipped bundle — with full control over what lands on disk.
Grab the npm package. The CLI is self-contained — only Node.js 20+ required.
4 demo behaviors and 2 demo presets ship bundled — just enough to feel the engine. Real catalogs live in your repo via --root.
See exactly what would be assembled — resolved behaviors, composed sections, generated files — without touching disk.
Two render targets. Default writes a bundle (prompt.md + hooks + .mcp.json) into ./.claude/promptweave/. Pass --target skill for a Claude Code SKILL.md instead.
Point --root at your repo's catalog and override any templated parameter on the fly with --set k=v — repeatable, deterministic, scriptable.
Build a custom behavior, compose a preset, render the bundle. Real shell commands you can copy.
Three folders — one per concept. Point --root at this directory and promptweave will discover everything inside.
A behavior is one YAML. It contributes one or more numbered sections to the assembled prompt — here, section 070 in the tone layer.
A preset is a named list of behaviors. Mix bundled demos (project-context, read-only-mode) with your custom concise-tone.
Resolve, validate, compose, assemble — nothing is written to disk. Catch missing references and section conflicts before they reach an agent.
Same preset, two outputs. bundle writes .claude/promptweave/ for in-repo use; skill writes a publish-ready Claude Code SKILL.md.
Need richer catalogs? See essaim — the reference orchestrator with 32+ behaviors, 20+ presets, and 12 pre-composed templates, all rendered by promptweave.
One catalog, two emit modes. Bundle for full runtime, Skill for catalog publishing.
Full runtime profile. Prompt + hooks + MCP config + env vars, written to ./.claude/promptweave/<agent>/ with an atomic backup-swap.
.sh files.mcp.jsonA single SKILL.md ready to publish, written to ./.claude/skills/<preset>/. Frontmatter + prompt body + auto-generated Parameters.
name (^[a-z0-9-]+$) & YAML-escaped description## Parameters from preset params→ Bundle
→ Skill
promptweave bundles 4 demo behaviors and 2 demo presets — just enough to show the engine working. Real-world catalogs (32+ behaviors, dozens of presets) live in your project via --root.
One YAML per behavior. Each contributes one or more numbered sections to the assembled prompt.
project-contextcategory: coordination · section 000
Project identity. Templated parameters for language, test command, and module list. Renders the agent's "where am I?" briefing.
worktree-isolationcategory: workspace · sections 010 + 055 · hooks: session-start, session-stop
Isolate the agent in a dedicated git worktree branch. Ships hook scripts that set up and tear down the worktree. Conflicts with shared-workspace.
shared-workspacecategory: workspace · section 010
All agents work in the same directory. Typically paired with read-only-mode for analysis-only flows. Conflicts with worktree-isolation.
read-only-modecategory: safety · section 090
Agent cannot modify files. Analyzes, communicates, reports. Useful for code-review or audit roles.
A preset is a named list of behaviors. The engine resolves, validates, composes, and assembles them into ready-to-ship outputs.
dev —
Solo development session in an isolated worktree.
project-context + worktree-isolationinspect —
Read-only project inspection in an isolated worktree.
project-context + worktree-isolation + read-only-modeLooking for richer catalogs? The reference orchestrator essaim ships 32+ behaviors, 20+ presets, and 12 pre-composed templates (bug-hunt, parallel-tests, code-review, etc.) — all assembled by promptweave at runtime.
Programmatic API for CI pipelines, custom renderers, and migration tools.
The pipeline is a pure function: Registry → AgentSpec → PipelineResult. No filesystem side effects until you call writeOutput. Ideal for CI that re-renders every bundle on each commit, custom writers that target proprietary tools, or migration scripts that diff old vs. new behavior catalogs.
PipelineResult exposes agent, behaviors[], compositionRulesApplied[], output, warnings[], and sectionTrace[] — everything you need to assert on in tests.
Two entry points cover 90% of integrations.
Registry.load(path) — loads behaviors, presets, and compositions from a directory.
runPipeline(agent, path, params) — orchestrates resolve → validate → compose → assemble and returns a full PipelineResult.
Drop into any pipeline stage to build custom tooling.
resolveBehaviors, resolveParams — expand presets and merge parameters.
validateBehaviors — enforce conflicts, requires, and missing-param checks.
applyCompositionRules — apply pattern-matched rule overrides.
assemblePrompt, assembleHooks, assembleMcpTools — deterministic section sort and dedup.
bundleRenderer, skillRenderer — built-in writers for prompt+hooks+MCP and SKILL.md targets.
Types live in @swoofer/promptweave/types. The pipeline is deterministic — same inputs produce identical PipelineResult.
Where we're going next.
Engine + 4 demo behaviors + 2 demo presets. npm package, deterministic output, GH Pages landing.
Better validation errors, machine-readable validate output, custom output writers, behavior schema versioning.
Third-party renderers (TOML hooks, INI configs, custom MCP-config dialects). Behaviors stay vendor-agnostic; targets are pluggable.
Pull a behavior from another package as a dependency. Behavior versioning + lockfile-style resolution for shared catalogs across teams.
A behavior's effective contract — sections it owns, parameters it accepts, hooks it provides — published as a typed schema. Composition errors caught at validate-time, not at runtime.