recoupable__skills/docs/workflow-plugins.md

Pattern: the workflow-bundle plugin

Build-time reference for plugin authors. This doc is not shipped with any install and a SKILL.md must never link to it — embody the guidance as behavior instead.

Most plugins are a capability area — a cluster of related skills for one team (e.g. a marketing toolkit, a research toolkit). A workflow-bundle plugin is a different, higher-order shape: it packages an entire end-to-end process — every stage, the shared artifact it builds, the deterministic tooling, and the guardrails — behind a single front door, so the user types one thing and walks away with a finished, trustworthy deliverable.

Think "type one command → get a populated workspace and an artifact you can open," not "here are twelve skills, sequence them yourself."

---

When to use this pattern (and when not to)

Use a workflow bundle when all of these hold:

• There's a named, recurring process the user thinks of as one job (a release, a deal, a tour, an onboarding) — not just a topic.
• The process has distinct stages that hand off to each other.
• The stages accumulate into a shared artifact (a folder, a document, a dashboard) rather than producing disconnected one-off answers.
• The payoff of "run the whole thing in order" clearly beats "run pieces ad hoc."

Prefer a plain capability plugin when the skills are a loose family used independently (analysis tools, content generators) with no single artifact or mandatory order.

A repo can have both: capability/team plugins and one or more flagship workflow bundles next to them. That mix is healthy — the bundle is just another plugin type, not a replacement for the team plugins.

---

The central idea: a shared workspace contract

A workflow only bundles if every stage advances the same artifact. The single most important design decision is the workspace contract: a strict, documented folder/document schema that every stage reads from and writes to.

{process}/{instance-id}/
├── source/        # raw inputs, treated as immutable evidence
├── working/       # normalized / intermediate artifacts
├── findings/      # structured issues, gaps, exceptions
├── outputs/       # human-facing deliverables (memo, plan, dashboard)
├── assumptions.*  # values that affect the work but aren't in the inputs
└── evidence.*     # traces every material claim back to a source

(The exact subfolders are domain-specific — the point is the contract.) Each stage's job becomes simple and composable: read the workspace → do my phase → write back → leave evidence. The orchestrator is the conductor; the workspace is the score. This is what lets stages compose instead of collide, and it's what lets a chained-in skill from another plugin drop its output into the bundle cleanly.

A template of this workspace is scaffolded at the start of every run so every instance begins identical.

---

Anatomy (the ingredients of a strong bundle)

Ingredient	What it is	Why it matters
Front-door orchestrator	One entry-point skill that runs every stage in order, end-to-end, without stopping to ask between phases	The user types one thing and gets a finished artifact
Stage skills	One skill per phase of the process	Each phase is real work and also runnable on its own
Shared workspace contract	The strict folder/doc schema above	The connective tissue — see the section above
Workspace template	A scaffold copied in at the first phase	Deterministic, identical starting point
Deterministic scripts	Co-located code for the exact parts (math, normalization, validation)	The precise work is code, not prose; testable
Specialist subagents	Focused reviewers the orchestrator dispatches (often in parallel)	Deep review without bloating the main skill
Guardrail hooks	Protect immutable inputs; block "done" until the artifact exists and validates	The agent can't quit early or claim false completion
Evidence / trust contract	Every material claim traces to evidence or is labeled an assumption; a validator enforces it	The deliverable is defensible, not just pretty
One customer-facing artifact	A single "open this first" deliverable; everything else is provenance	Clear payoff; no ambiguity about what to look at
Demo + golden fixtures	A demo path that runs the full flow on synthetic data; input→expected pairs	Onboarding and regression testing in one
Variants via references	Process modes (e.g. by deal type, by release type) swap a reference deep-dive, not a whole skill	Flexes the workflow without skill proliferation
Power-user escape hatches	Each stage is also invocable directly	Beginners run the front door; experts run one stage

Not every bundle needs all twelve. A solid v1 is: orchestrator + workspace contract + template + the stage skills + one clear artifact + a demo. Scripts, hooks, subagents, and the trust validator are the v2 hardening that makes it production-grade.

---

Two principles that make the output delightful

1. Determinism where it counts, creativity where it delights. Put the exact, must-be-right work (calculations, normalization, validation) in co-located scripts with tests. Let the agent author the final deliverable (a dashboard, a plan, a memo) with full creative freedom on layout and narrative — but gate it with a validator that rejects unverified claims. Trustworthy and beautiful.

2. The agent can't cheat. Make source inputs immutable (a pre-write hook) and refuse to let the run end until the artifact exists and passes validation (a stop-gate). This is what turns "want me to continue?" stalls into a reliably finished artifact.

---

Closed vs. open domains: bundle vs. chain

The hardest design question is scope — what lives inside the bundle.

• Closed-domain workflow: every stage skill is specific to this process and reused nowhere else. Bundle everything — the whole pipeline is self-contained.
• Open-domain workflow: some stages use general-purpose skills that are also used outside this process (e.g. audience analysis used for both a release and a tour; a monitor that runs whether or not there's an active campaign).

For an open-domain workflow, do not copy the general skills into the bundle (that causes drift) and do not rip them out of their home team (that guts the capability plugins). Instead:

Bundle the process-specific skills + the orchestrator + the workspace. Chain the general-purpose skills — they stay in their team plugin and the orchestrator invokes them by name, with the shared workspace as the hand-off surface.

A skill still lives in exactly one plugin. The orchestrator composing a skill that lives elsewhere is fine — that's chaining, not ownership. The workspace contract is what keeps a chained-out skill's output coherent with the rest of the bundle.

Litmus test for each stage skill: "Is this skill meaningless outside this process?" If yes → it belongs in the bundle. If it has standalone value → leave it in its team plugin and chain to it.

---

Build blueprint

1. Name the process and its artifact. What single thing does a finished run produce? ("a populated release workspace + a rollout plan", etc.)
2. Define the workspace contract (folders/doc schema + assumptions + evidence) and write a template for it.
3. List the stages in order. For each, decide bundle vs. chain with the litmus test above.
4. Write the orchestrator skill as the front door: run all stages in order, don't pause between phases, end on the artifact, and print a final landing recap (what's ready, what to open first, what was skipped and why).
5. Write/locate the stage skills. Bundle the process-only ones; cross-route to the general ones.
6. Add a demo that runs the full flow on synthetic data.
7. (Hardening) Add deterministic scripts + tests for exact work, a completion hook, an evidence/trust validator for the artifact, and specialist review subagents.
8. Expose each stage as its own skill so power users can run a single stage directly (skills auto-register a /skill-name entry — no separate command files; see AGENTS.md "No slash-commands").

---

Quality bar

• One command produces a real, openable artifact — not a "want me to continue?".
• Every material number in the artifact traces to evidence or a labeled assumption.
• The run is honest about gaps ("skipped X because Y") instead of papering over them.
• A newcomer can run the demo and immediately see what the bundle produces.
• A power user can run any single stage without the orchestrator.

If a "bundle" is really just several skills in a folder with no shared workspace, no orchestrator, and no single artifact — it's a capability plugin wearing a costume. The workspace contract and the front door are what make it a workflow bundle.