Modular Workflows
Every Vyasa workflow is made of small, independent pieces — and the same pieces make a hospital flow, a banking flow, or a software flow. No code knowledge needed. This page explains the pieces in everyday words, so you can see why building your own workflow is easy.
1. The idea in one paragraph
A Vyasa workflow is not a program. It is a set of small config files, and each file answers one plain question: Which groups does work move through? How bold may a worker be? What counts as a finished piece? What must be true before work moves forward? Where does finished work go? To cover YOUR work, you fill the files with your words — your group names, your checks, your roles — and the engine does the rest. Change one file and only that part changes. That is why one set of files covers a hospital discharge review, a bank KYC check, and a software release.
From template to your project. A workflow starts as a template —
a supplied starter. vyasa init --workflow <ref> validates it and
gives your project its own live copy (.vyasa/workflows/{ref}/).
From that moment the project is self-evolving: edit any file, take it
your own direction, version it — changes to the template never touch
your project. Missing files fall back to the template, then to safe
defaults; the engine always runs your copy.
2. The pieces, as questions
| Plainly | The question it answers | Its name in the files |
|---|---|---|
| The cover page | What is this workflow called, what version is it, is it on? | workflow.yaml |
| Groups | Which groups (phases) does work move through — like Drafting, Reviewing, Approving? | stages.yaml |
| Rulebooks | How bold may a worker be, how long may one sitting run, what may it touch? | modes.yaml |
| Goals | What is one sitting trying to achieve ("write the story")? | intents.yaml |
| Trades | Which craft does a worker practice — analyst, reviewer, writer? | skills.yaml |
| Kinds of work | What counts as one piece of work? What must a finished piece contain? What life does it live (draft → review → done)? | node_types.yaml |
| Checkpoints | What must be true before work moves from one state to the next? | gates.yaml |
| Limits | Which files may a worker read, write, or never see? | guardrails.yaml |
| Filing plan | Where does finished work land, and how is it named? | structure.yaml |
| Equipment | What outside help may workers use — command-line tools, services, APIs? | tools / mcps / apis / clis / sdks.yaml |
| Triggers | What runs automatically before or after key moments? | hooks.yaml |
| Laws | Which standing rules must every piece of work obey? | governance.yaml |
| Supply lines | Where do outside rule packs come from, and how are they verified? | connections.yaml |
| Workers | Which AI tools (assistant, CLI, any model) may do the work? | assistants.yaml |
| Rubrics | Line by line, how is finished work graded? | checklists.yaml |
| Proofs | Which machine checks prove the work is good? | verification.yaml |
Each piece is optional except a few — the engine fills sensible defaults for the rest (the exact list is in the Workflow Schema Reference).
3. How the pieces connect
Read it as sentences: work moves through groups; each group carries defaults — the session itself picks its rulebook, its trade, and its goal, and may pick anything the workflow enables; every kind of work has life rules; every move between states passes ALL its checkpoints; every decision to move forward is human.
4. How many of each
| Rule | Plainly |
|---|---|
| One workflow, many of most things | many groups, trades, checkpoints, kinds of work |
| Each sitting picks freely | any enabled rulebook, trade, and goal — the group's declared ones are defaults, not locks |
| Each move, all its checkpoints | every check passed, no exceptions |
| Each sitting, one piece of work | one booking, one story, one task |
| Laws opt-in per kind | a kind with no laws selected follows none — on purpose |
5. Three workflows, same pieces (proof by example)
Hospital discharge review. Groups: Doctor writes → Pharmacist checks → Discharge approved. Work pieces: a summary, a medication list. Checkpoints: sections present, pharmacist sign-off. Laws: dosage double-checks. Same pieces as software — different words.
Bank KYC review. Groups: Collect → Verify → Approve. Work piece: a file with a declared record (status, amount, risk — the workflow says what shape, the engine checks it). Checkpoints: document checks + score above bar. Laws: compliance pack, fetched verifiably. Equipment: scanner API, registry lookup.
Software release. Groups: Spec → Code → Review → Deploy. Work pieces: a story, a code change. Checkpoints: section checks, validator scores, approval. Laws: branch conventions, mandatory review. Equipment: linter, tests, build tool — run for real on every proposal.
Three industries, one set of pieces, zero new machinery.
6. What modularity means for you
- Add a piece (a checkpoint, a trade) without touching the rest.
- Remove one (disable a group, drop a check) — the workflow still loads.
- Swap one (stricter laws for regulated work, lighter for experiments).
- Rename freely — groups, rulebooks, trades are YOUR words; the engine hardcodes none.
- Missing pieces fail loud — a dangling reference stops everything at load and names the missing piece, before any session runs.
- Version your workflow — name it, version it, update it deliberately.
7. Keep going
Session Lifecycle next — what happens inside one sitting. Authors who want every field of every piece: the Workflow Schema Reference.