Bundle Builder — Workflow Synthesis Engine
This sub-skill is loaded after the interviewer (active mode) or observer
(passive mode) achieves convergence. It reads the accumulated workflow
state from memory and generates an output bundle directory.
Input
All workflow-architect:state:* memory entries. Read them all at once:
Read: workflow-architect:state:entry_points
Read: workflow-architect:state:phases
Read: workflow-architect:state:branching
Read: workflow-architect:state:pain_points
Read: workflow-architect:state:exit_criteria
If any required fields are missing (entry_points, phases, branching, exit_criteria),
abort with a clear message about what's missing.
Output Structure
The bundle is written to ~/.hermes/skills/<category>/<bundle-name>/ with this layout:
<bundle-name>/
├── SKILL.md # *** UMBRELLA ENTRY POINT *** — makes the bundle
│ # loadable via skill_view() and discoverable by
│ # the agent's skill scanner on trigger keywords.
│ # CRITICAL: without this, the bundle is invisible.
├── README.md # Summary of this bundle
├── manifest.yaml # Skill-to-trigger mapping
├── skills/
│ ├── entry-skill.md # One per discovered phase
│ ├── phase-two.md
│ └── ...
├── decision-map.md # Mermaid flowchart
├── AGENTS.md # Agent loading instructions for this bundle
├── kanban/
│ └── board-definition.yaml # Only if kanban is appropriate
└── references/
└── generated-from.md # Metadata about how this bundle was created
The SKILL.md umbrella is not optional. Without it, individual sub-skills
may exist on disk but the agent's skill scanner has no entry point to match
trigger keywords against. The umbrella is how the agent discovers and enters
the bundle.
Bundle naming
Ask the user for a bundle name at the start of synthesis:
"Before I generate the bundle — what should I call it?
Something short, lowercase with hyphens, like 'my-triage-workflow'
or 'dev-sprint-routine'."
Fallback if user doesn't provide one: my-workflow-<archetype>-<date>.
Writing the files
For each file in the output bundle, use the shared templates in ../../templates/ as
starting points. Render them by substituting the state values.
Step-by-step file creation order:
Umbrella SKILL.md — MANDATORY FIRST STEP. This is the entry point
that makes the bundle discoverable. Write it directly to the bundle directory
as SKILL.md, then register it via skill_manage(action='create').
The umbrella must include:
name: <bundle-name> matching the bundle name
description with broad trigger keywords covering all common ways the
user enters this workflow (e.g., "I want to write about X", "I read
something interesting", "can you research this", "draft it", "ship it")
compatibility: Hermes Agent
metadata.tags including workflow, bundle, and domain-relevant tags
Body content:
# <Bundle Name>
A <N>-phase workflow covering <brief summary>.
## Pipeline
<Phase 1> → <Phase 2> → <Phase 3> → ...
(Include a Mermaid flowchart graph LR showing the phase sequence.)
## Sub-Skills
| Phase | Skill | Trigger |
|-------|-------|---------|
| <name> | `<bundle-name>/<phase-file>` | <when to load> |
| ... | ... | ... |
## Navigation
When you load this umbrella, identify which phase the user is in,
load the corresponding sub-skill via skill_view(), and follow its
instructions. Use the transition signals in each sub-skill to know
when to move to the next phase.
## Pipeline Heuristics
- Can the user enter at any phase, or must they start at Phase 1?
- Are any phases automatic (e.g., refine always follows draft)?
- What's the relationship between phases (sequential, branching, optional)?
Category choice: Place the bundle in a category that matches where its
sub-skills live (e.g., content for blogging pipelines, devops for
deployment workflows). Ask the user if unsure.
manifest.yaml — Use ../../templates/manifest.yaml.tmpl. Substitute:
{{BUNDLE_NAME}} — the bundle name
{{PHASES}} — each phase with its trigger keywords, entry signals,
typical tools, and exit signals
{{HAS_KANBAN}} — true/false based on kanban decision
README.md — Write from scratch (no template needed, it's prose).
Structure:
# <Bundle Name>
Generated by workflow-architect on <date>.
This bundle covers a <archetype>-style workflow with <N> phases.
## Skills
| Skill | Trigger | When it fires |
|-------|---------|---------------|
| <name> | <trigger description> | <when to load> |
## Loading
Skills in this bundle are loaded automatically by trigger conditions.
To load a specific skill: `skill_view(name='<bundle-name>/<skill-name>')`
## Kanban
(Only if kanban exists) This workflow maps to a kanban board with <N> lanes.
Sub-skills — For each phase in workflow-architect:state:phases,
generate a .md file in skills/ using ../../templates/skill-skeleton.md.
Naming convention: kebab-case-phase-name.md (e.g., morning-triage.md).
Each sub-skill file is a valid Agent Skills SKILL.md with:
name matching the filename (without .md)
description that includes trigger keywords from the phase's typical
openers and tools
compatibility: Compatible with any agent supporting the Agent Skills format
- Body sections:
- When to use — the trigger condition in natural language
- What to do — step-by-step instructions for the agent in this phase
- Transition signals — what the user typically says or does that
transitions out of this phase
- What to tell the user — guidance on how the agent should communicate
during this phase
decision-map.md — Use ../../templates/decision-map.md.tmpl. Substitute:
{{WORKFLOW_NAME}} — bundle name
{{PHASE_NODES}} — phase names
{{BRANCHING}} — decision diamonds
{{ENTRY}} — how sessions start
{{EXITS}} — how sessions end
AGENTS.md — Standard agent loading instructions for this bundle.
Short — just says which skills exist and when to load them.
kanban/ directory — Only if the kanban-decision-criteria.md reference
indicates kanban is appropriate. Generates three files:
a) kanban/board-setup.sh — Use ../../templates/kanban-board-setup.sh.tmpl.
Substitutes:
{{BOARD_SLUG}} — bundle name (kebab-case)
{{BOARD_NAME}} — title-case version or user-provided name
{{FIRST_PHASE_SKILL}} — skill file for the first phase
{{FIRST_PHASE_PRIORITY}} — priority for first-phase tasks
{{GENERATION_DATE}} — current date
The setup script creates the board via hermes kanban boards create
and prints instructions for adding work.
b) kanban/task-blueprints.yaml — Use ../../templates/kanban-task-blueprints.yaml.tmpl.
Substitutes:
{{BLUEPRINT_ENTRIES}} — one blueprint entry per phase, each with:
phase: — phase name (kebab-case)
title_template: — e.g. "Build: {{feature}}"
skill: — path to the sub-skill file (e.g. my-workflow/build)
default_priority: — descending from first phase (highest) to last
initial_status: — first phase = todo, rest = ready
body: — instructions for the worker: what skill to load,
definition of done, and transition to next phase
c) kanban/README.md — Brief usage guide explaining how to set up and
use the board. Structure:
# Kanban Board: <Bundle Name>
This workflow maps to a Hermes Kanban board with <N> phases in sequence.
## Setup
Run `kanban/board-setup.sh` to create the board:
```bash
bash kanban/board-setup.sh
The script creates the board and switches to it. If you prefer to set
it up manually:
hermes kanban boards create <bundle-name> --name "<Bundle Name>"
Task Lifecycle
<Phase 1> → <Phase 2> → <Phase 3>
Each phase's task depends on the previous phase's task completing.
When a task is done, the next phase's task auto-promotes to "ready"
and the dispatcher picks it up.
Adding Work
Create a task for the first phase:
hermes kanban create "Build: <feature description>" \\
--skill <bundle-name>/<phase-1-skill> \\
--priority 3
Then create subsequent-phase tasks with --parent pointing to the
first task's ID:
hermes kanban create "Review: <feature>" \\
--parent <task-id> \\
--skill <bundle-name>/<phase-2-skill> \\
--priority 2
Task Blueprints
See kanban/task-blueprints.yaml for template definitions of each
phase's task, including default priorities, skill mappings, and
worker instructions.
references/generated-from.md — Metadata about the generation process:
# Generated From
- **Skill:** workflow-architect
- **Mode:** active | passive
- **Date:** <date>
- **Archetype:** <archetype>
- **Convergence Score:** <score>
Register sub-skills with Hermes skill system — For each sub-skill .md
file written in step 3, register it so it appears in skills_list() and
can be loaded with skill_view(). This is the critical step that makes
generated skills actually usable by the agent.
For each sub-skill file in skills/<name>.md:
skill_manage(action='create',
name='<bundle-name>-<skill-name>',
content=read_file('<bundle-path>/skills/<name>.md')['content'],
category='generated')
This creates a proper skill directory with SKILL.md entry point, making
the sub-skill discoverable and loadable. The sub-skill's existing valid
Agent Skills frontmatter (name, description, license, tags) is used as-is.
Why separate registration is needed: The skill_manage() call also
handles the skill directory structure (SKILL.md at root, not <name>.md
in a skills/ subdirectory). Without this step, the sub-skill files exist
on disk but no Hermes mechanism discovers them. Only the umbrella SKILL.md
(registered in step 0) would be loadable.
Verification: After registering all sub-skills, verify at least one:
skill_view(name='<bundle-name>-<first-phase-name>')
If it errors, the registration failed — check that the sub-skill file's
frontmatter name field matches and the content has valid YAML.
Kanban Decision
Before generating kanban files, consult ../../references/kanban-decision-criteria.md
to decide whether a board is appropriate. The decision depends on the phases
and branching structure discovered:
- If phases form a clear linear sequence (A → B → C → D), kanban adds value
- If branching is emergent (session depends on context), kanban is likely inappropriate
- If the user mentioned waiting on others, hand-offs, or status tracking, kanban is a strong fit
Present the decision to the user:
"Your workflow has a [linear/emergent] structure. A kanban board [would/wouldn't]
add much value here because [reason]. [If yes: I'll add one to the bundle.]"
Register sub-skills — For each generated sub-skill .md file in
skills/, register it so Hermes can discover it via skill_view() and
skills_list():
For each sub-skill file `skills/<phase-name>.md`:
Read the file content
skill_manage(
action='create',
name='<bundle-name>/<phase-name>',
content=file_content
)
This makes each sub-skill loadable as skill_view('<bundle-name>/<phase-name>').
The bundle name prefix prevents naming collisions with other skills.
If skill_manage is not available in the agent's toolset, note this for
the user and suggest they run the registration manually.
Cleanup
After writing all files:
Verify the umbrella registered successfully:
skill_view(name='<bundle-name>')
If it returns status: available, proceed. If not found, re-run the
skill_manage(action='create') call.
Remove all workflow-architect:state:* memory entries
(memory(action='remove', target='memory', old_text='workflow-architect:state:'))
Remove all workflow-architect:state:* memory entries
(memory(action='remove', target='memory', old_text='workflow-architect:state:'))
Tell the user where the bundle was written and what it contains
Verify the umbrella loads correctly with skill_view(name='<bundle-name>')
— if it doesn't resolve, check that skill_manage(action='create') was run
and the SKILL.md has valid frontmatter
Verify at least one registered sub-skill loads:
skill_view(name='<bundle-name>-<first-phase-name>')
Suggest they enter the workflow via any trigger phrase covered by the
umbrella's description, or by manually loading the umbrella skill
When not to use
Do not load this skill without a converged workflow model — it requires the workflow-architect:state:* entries produced by the interviewer or observer. If the workflow has not been discovered yet, load the interviewer (active) or observer (passive) first.
1---2name: bundle-builder3description: Render accumulated workflow state from memory into a valid Agent Skills4 bundle directory for workflow-architect, with sub-skills, manifest, decision map,5 and optional kanban board. Loaded after the interviewer or observer achieves convergence.6license: MIT7compatibility: Hermes Agent — uses write_file for bundle output, shell_quote8metadata:9 source: https://skillmd.com/skills/magnus919/bundle-builder10 tags: workflow, generation, bundle, synthesis11 spec-version: '1.0'12---1314# Bundle Builder — Workflow Synthesis Engine1516This sub-skill is loaded after the interviewer (active mode) or observer17(passive mode) achieves convergence. It reads the accumulated workflow18state from memory and generates an output bundle directory.1920## Input2122All `workflow-architect:state:*` memory entries. Read them all at once:2324```25Read: workflow-architect:state:entry_points26Read: workflow-architect:state:phases27Read: workflow-architect:state:branching28Read: workflow-architect:state:pain_points29Read: workflow-architect:state:exit_criteria30```3132If any required fields are missing (entry_points, phases, branching, exit_criteria),33abort with a clear message about what's missing.3435## Output Structure3637The bundle is written to `~/.hermes/skills/<category>/<bundle-name>/` with this layout:3839```40<bundle-name>/41├── SKILL.md # *** UMBRELLA ENTRY POINT *** — makes the bundle42│ # loadable via skill_view() and discoverable by43│ # the agent's skill scanner on trigger keywords.44│ # CRITICAL: without this, the bundle is invisible.45├── README.md # Summary of this bundle46├── manifest.yaml # Skill-to-trigger mapping47├── skills/48│ ├── entry-skill.md # One per discovered phase49│ ├── phase-two.md50│ └── ...51├── decision-map.md # Mermaid flowchart52├── AGENTS.md # Agent loading instructions for this bundle53├── kanban/54│ └── board-definition.yaml # Only if kanban is appropriate55└── references/56 └── generated-from.md # Metadata about how this bundle was created57```5859**The `SKILL.md` umbrella is not optional.** Without it, individual sub-skills60may exist on disk but the agent's skill scanner has no entry point to match61trigger keywords against. The umbrella is how the agent discovers and enters62the bundle.6364### Bundle naming6566Ask the user for a bundle name at the start of synthesis:6768```69"Before I generate the bundle — what should I call it?70Something short, lowercase with hyphens, like 'my-triage-workflow'71or 'dev-sprint-routine'."72```7374Fallback if user doesn't provide one: `my-workflow-<archetype>-<date>`.7576### Writing the files7778For each file in the output bundle, use the shared templates in `../../templates/` as79starting points. Render them by substituting the state values.8081**Step-by-step file creation order:**82830. **Umbrella SKILL.md** — **MANDATORY FIRST STEP.** This is the entry point84 that makes the bundle discoverable. Write it directly to the bundle directory85 as `SKILL.md`, then register it via `skill_manage(action='create')`.8687 The umbrella must include:8889 - `name: <bundle-name>` matching the bundle name90 - `description` with **broad trigger keywords** covering all common ways the91 user enters this workflow (e.g., "I want to write about X", "I read92 something interesting", "can you research this", "draft it", "ship it")93 - `compatibility: Hermes Agent`94 - `metadata.tags` including `workflow`, `bundle`, and domain-relevant tags9596 Body content:9798 ```markdown99 # <Bundle Name>100101 A <N>-phase workflow covering <brief summary>.102103 ## Pipeline104105 <Phase 1> → <Phase 2> → <Phase 3> → ...106107 (Include a Mermaid flowchart graph LR showing the phase sequence.)108109 ## Sub-Skills110111 | Phase | Skill | Trigger |112 |-------|-------|---------|113 | <name> | `<bundle-name>/<phase-file>` | <when to load> |114 | ... | ... | ... |115116 ## Navigation117118 When you load this umbrella, identify which phase the user is in,119 load the corresponding sub-skill via skill_view(), and follow its120 instructions. Use the transition signals in each sub-skill to know121 when to move to the next phase.122123 ## Pipeline Heuristics124125 - Can the user enter at any phase, or must they start at Phase 1?126 - Are any phases automatic (e.g., refine always follows draft)?127 - What's the relationship between phases (sequential, branching, optional)?128 ```129130 **Category choice:** Place the bundle in a category that matches where its131 sub-skills live (e.g., `content` for blogging pipelines, `devops` for132 deployment workflows). Ask the user if unsure.1331. **manifest.yaml** — Use `../../templates/manifest.yaml.tmpl`. Substitute:134 - `{{BUNDLE_NAME}}` — the bundle name135 - `{{PHASES}}` — each phase with its trigger keywords, entry signals,136 typical tools, and exit signals137 - `{{HAS_KANBAN}}` — true/false based on kanban decision1381392. **README.md** — Write from scratch (no template needed, it's prose).140 Structure:141142 ```markdown143 # <Bundle Name>144145 Generated by workflow-architect on <date>.146147 This bundle covers a <archetype>-style workflow with <N> phases.148149 ## Skills150151 | Skill | Trigger | When it fires |152 |-------|---------|---------------|153 | <name> | <trigger description> | <when to load> |154155 ## Loading156157 Skills in this bundle are loaded automatically by trigger conditions.158 To load a specific skill: `skill_view(name='<bundle-name>/<skill-name>')`159160 ## Kanban161162 (Only if kanban exists) This workflow maps to a kanban board with <N> lanes.163 ```1641653. **Sub-skills** — For each phase in `workflow-architect:state:phases`,166 generate a `.md` file in `skills/` using `../../templates/skill-skeleton.md`.167168 Naming convention: `kebab-case-phase-name.md` (e.g., `morning-triage.md`).169170 Each sub-skill file is a valid Agent Skills SKILL.md with:171 - `name` matching the filename (without .md)172 - `description` that includes trigger keywords from the phase's typical173 openers and tools174 - `compatibility: Compatible with any agent supporting the Agent Skills format`175 - Body sections:176 - **When to use** — the trigger condition in natural language177 - **What to do** — step-by-step instructions for the agent in this phase178 - **Transition signals** — what the user typically says or does that179 transitions out of this phase180 - **What to tell the user** — guidance on how the agent should communicate181 during this phase1821834. **decision-map.md** — Use `../../templates/decision-map.md.tmpl`. Substitute:184 - `{{WORKFLOW_NAME}}` — bundle name185 - `{{PHASE_NODES}}` — phase names186 - `{{BRANCHING}}` — decision diamonds187 - `{{ENTRY}}` — how sessions start188 - `{{EXITS}}` — how sessions end1891905. **AGENTS.md** — Standard agent loading instructions for this bundle.191 Short — just says which skills exist and when to load them.1921936. **kanban/ directory** — Only if the kanban-decision-criteria.md reference194 indicates kanban is appropriate. Generates three files:195196 a) **kanban/board-setup.sh** — Use `../../templates/kanban-board-setup.sh.tmpl`.197 Substitutes:198 - `{{BOARD_SLUG}}` — bundle name (kebab-case)199 - `{{BOARD_NAME}}` — title-case version or user-provided name200 - `{{FIRST_PHASE_SKILL}}` — skill file for the first phase201 - `{{FIRST_PHASE_PRIORITY}}` — priority for first-phase tasks202 - `{{GENERATION_DATE}}` — current date203204 The setup script creates the board via `hermes kanban boards create`205 and prints instructions for adding work.206207 b) **kanban/task-blueprints.yaml** — Use `../../templates/kanban-task-blueprints.yaml.tmpl`.208 Substitutes:209 - `{{BLUEPRINT_ENTRIES}}` — one blueprint entry per phase, each with:210 - `phase:` — phase name (kebab-case)211 - `title_template:` — e.g. "Build: {{feature}}"212 - `skill:` — path to the sub-skill file (e.g. `my-workflow/build`)213 - `default_priority:` — descending from first phase (highest) to last214 - `initial_status:` — first phase = `todo`, rest = `ready`215 - `body:` — instructions for the worker: what skill to load,216 definition of done, and transition to next phase217218 c) **kanban/README.md** — Brief usage guide explaining how to set up and219 use the board. Structure:220221 ```markdown222 # Kanban Board: <Bundle Name>223224 This workflow maps to a Hermes Kanban board with <N> phases in sequence.225226 ## Setup227228 Run `kanban/board-setup.sh` to create the board:229 ```bash230 bash kanban/board-setup.sh231 ```232233 The script creates the board and switches to it. If you prefer to set234 it up manually:235 ```bash236 hermes kanban boards create <bundle-name> --name "<Bundle Name>"237 ```238239 ## Task Lifecycle240241 <Phase 1> → <Phase 2> → <Phase 3>242243 Each phase's task depends on the previous phase's task completing.244 When a task is done, the next phase's task auto-promotes to "ready"245 and the dispatcher picks it up.246247 ## Adding Work248249 Create a task for the first phase:250 ```bash251 hermes kanban create "Build: <feature description>" \\252 --skill <bundle-name>/<phase-1-skill> \\253 --priority 3254 ```255256 Then create subsequent-phase tasks with `--parent` pointing to the257 first task's ID:258 ```bash259 hermes kanban create "Review: <feature>" \\260 --parent <task-id> \\261 --skill <bundle-name>/<phase-2-skill> \\262 --priority 2263 ```264265 ## Task Blueprints266267 See `kanban/task-blueprints.yaml` for template definitions of each268 phase's task, including default priorities, skill mappings, and269 worker instructions.270 ```2712727. **references/generated-from.md** — Metadata about the generation process:273274 ```markdown275 # Generated From276277 - **Skill:** workflow-architect278 - **Mode:** active | passive279 - **Date:** <date>280 - **Archetype:** <archetype>281 - **Convergence Score:** <score>282 ```2832848. **Register sub-skills with Hermes skill system** — For each sub-skill `.md`285 file written in step 3, register it so it appears in `skills_list()` and286 can be loaded with `skill_view()`. This is the critical step that makes287 generated skills actually usable by the agent.288289 For each sub-skill file in `skills/<name>.md`:290291 ```python292 skill_manage(action='create',293 name='<bundle-name>-<skill-name>',294 content=read_file('<bundle-path>/skills/<name>.md')['content'],295 category='generated')296 ```297298 This creates a proper skill directory with `SKILL.md` entry point, making299 the sub-skill discoverable and loadable. The sub-skill's existing valid300 Agent Skills frontmatter (name, description, license, tags) is used as-is.301302 **Why separate registration is needed:** The `skill_manage()` call also303 handles the skill directory structure (`SKILL.md` at root, not `<name>.md`304 in a `skills/` subdirectory). Without this step, the sub-skill files exist305 on disk but no Hermes mechanism discovers them. Only the umbrella SKILL.md306 (registered in step 0) would be loadable.307308 **Verification:** After registering all sub-skills, verify at least one:309 ```python310 skill_view(name='<bundle-name>-<first-phase-name>')311 ```312313 If it errors, the registration failed — check that the sub-skill file's314 frontmatter `name` field matches and the content has valid YAML.315316## Kanban Decision317318Before generating kanban files, consult `../../references/kanban-decision-criteria.md`319to decide whether a board is appropriate. The decision depends on the phases320and branching structure discovered:321322- If phases form a clear linear sequence (A → B → C → D), kanban adds value323- If branching is emergent (session depends on context), kanban is likely inappropriate324- If the user mentioned waiting on others, hand-offs, or status tracking, kanban is a strong fit325326Present the decision to the user:327328```329"Your workflow has a [linear/emergent] structure. A kanban board [would/wouldn't]330add much value here because [reason]. [If yes: I'll add one to the bundle.]"331```3323338. **Register sub-skills** — For each generated sub-skill `.md` file in334 `skills/`, register it so Hermes can discover it via `skill_view()` and335 `skills_list()`:336337 ```338 For each sub-skill file `skills/<phase-name>.md`:339 Read the file content340 skill_manage(341 action='create',342 name='<bundle-name>/<phase-name>',343 content=file_content344 )345 ```346347 This makes each sub-skill loadable as `skill_view('<bundle-name>/<phase-name>')`.348 The bundle name prefix prevents naming collisions with other skills.349350 If `skill_manage` is not available in the agent's toolset, note this for351 the user and suggest they run the registration manually.352353## Cleanup354355After writing all files:3563571. Verify the umbrella registered successfully:358 ```359 skill_view(name='<bundle-name>')360 ```361 If it returns `status: available`, proceed. If not found, re-run the362 `skill_manage(action='create')` call.3633642. Remove all `workflow-architect:state:*` memory entries365 (`memory(action='remove', target='memory', old_text='workflow-architect:state:')`)3662. Remove all `workflow-architect:state:*` memory entries367 (`memory(action='remove', target='memory', old_text='workflow-architect:state:')`)3682. Tell the user where the bundle was written and what it contains3693. Verify the umbrella loads correctly with `skill_view(name='<bundle-name>')`370 — if it doesn't resolve, check that `skill_manage(action='create')` was run371 and the SKILL.md has valid frontmatter3724. Verify at least one registered sub-skill loads:373 `skill_view(name='<bundle-name>-<first-phase-name>')`3745. Suggest they enter the workflow via any trigger phrase covered by the375 umbrella's description, or by manually loading the umbrella skill376377## When not to use378379Do not load this skill without a converged workflow model — it requires the `workflow-architect:state:*` entries produced by the interviewer or observer. If the workflow has not been discovered yet, load the interviewer (active) or observer (passive) first.