diff --git a/bundles/workflow-architect/AGENTS.md b/bundles/workflow-architect/AGENTS.md index 4f5959d..95fa583 100644 --- a/bundles/workflow-architect/AGENTS.md +++ b/bundles/workflow-architect/AGENTS.md @@ -30,6 +30,20 @@ bundle-builder. Each generated sub-skill is also registered (step 8) so it's imm discoverable by the agent's skill system. Verify with `skill_view(name='')` and `skill_view(name='-')`. +## Registration + +Both the umbrella `SKILL.md` and each sub-skill `.md` file in the generated +bundle are registered via `skill_manage(action="create")` so they appear in +`skills_list()` and are discoverable by the agent. Registration happens +during generation — no manual step required. + +- **Umbrella** — registered under `` (the bundle root skill) +- **Sub-skills** — registered under `/` + +The umbrella's `description` frontmatter contains broad trigger conditions +that let the agent auto-detect the bundle in future sessions when the user's +conversation cues match a known workflow phase. + ## Environment No environment variables required. State is stored via memory tool with diff --git a/bundles/workflow-architect/SKILL.md b/bundles/workflow-architect/SKILL.md index 75b9a90..39d9107 100644 --- a/bundles/workflow-architect/SKILL.md +++ b/bundles/workflow-architect/SKILL.md @@ -1,124 +1,125 @@ ---- -name: workflow-architect -description: >- - Discover your actual workflow through conversation or observation, then generate - a tailored skills bundle that encodes it as loadable agent skills with trigger - conditions. Use when you want to understand your own process, formalize it, or - share it with collaborators. Also use when a session feels aimless — this skill - gives it structure. -license: MIT -compatibility: >- - Hermes Agent — uses skill_view(), memory tool, session context scanning, - and write_file for bundle generation. Output bundles are standard Agent Skills. -metadata: - tags: [workflow, meta, productivity, skills-bundle, onboarding, process] - spec-version: "1.0" ---- - -# Workflow Architect - -A meta-skill that helps you (and your agent) understand how you actually work. It -discovers your workflow patterns through either active interrogation or passive -observation, then generates a **skills bundle** — a set of loadable skills, each -with trigger conditions, that encode your workflow so your agent can meet you -where you are in every session. - -## What You Get - -After running workflow-architect, you'll have a new bundle in your agent's skill -directory containing: - +1|--- +2|name: workflow-architect +3|description: >- +4| Discover your actual workflow through conversation or observation, then generate +5| a tailored skills bundle that encodes it as loadable agent skills with trigger +6| conditions. Use when you want to understand your own process, formalize it, or +7| share it with collaborators. Also use when a session feels aimless — this skill +8| gives it structure. +9|license: MIT +10|compatibility: >- +11| Hermes Agent — uses skill_view(), memory tool, session context scanning, +12| and write_file for bundle generation. Output bundles are standard Agent Skills. +13|metadata: +14| tags: [workflow, meta, productivity, skills-bundle, onboarding, process] +15| spec-version: "1.0" +16|--- +17| +18|# Workflow Architect +19| +20|A meta-skill that helps you (and your agent) understand how you actually work. It +21|discovers your workflow patterns through either active interrogation or passive +22|observation, then generates a **skills bundle** — a set of loadable skills, each +23|with trigger conditions, that encode your workflow so your agent can meet you +24|where you are in every session. +25| +26|## What You Get +27| +28|After running workflow-architect, you'll have a new bundle in your agent's skill +29|directory containing: +30| - **Umbrella SKILL.md** — the entry point that makes the bundle auto-detectable via trigger conditions in its description. Load it with `skill_view(name='')` or let the agent discover it automatically when you say something matching its triggers. -- **Sub-skills** — one per phase of your workflow, each with a `description` - that tells the agent when to load it (e.g., "load this when the user starts - their morning triage routine" or "use this when the user shifts into deep work - mode") -- **A manifest** — maps skill names to their trigger conditions, entry points, - and transition signals -- **A decision map** — Mermaid flowchart visualizing your workflow as the agent - sees it -- **A kanban board** (optional) — only included if your workflow follows a - predictable linear path where WIP limits and lane transitions add value - +39|- **Sub-skills** — one per phase of your workflow, each with a `description` +40| that tells the agent when to load it (e.g., "load this when the user starts +41| their morning triage routine" or "use this when the user shifts into deep work +42| mode") +43|- **A manifest** — maps skill names to their trigger conditions, entry points, +44| and transition signals +45|- **A decision map** — Mermaid flowchart visualizing your workflow as the agent +46| sees it +47|- **A kanban board** (optional) — only included if your workflow follows a +48| predictable linear path where WIP limits and lane transitions add value +49| The umbrella and sub-skills are registered via `skill_manage(action='create')` so they appear in `skills_list()` and are immediately loadable in future sessions. - -## Two Modes - -Workflow-architect adapts to how you want to engage with it. - -### Mode 1: Active Interrogation (One-Shot) - -**When to use:** You have a few minutes to talk through your process. This is -the most thorough mode — the agent asks guided questions, branches based on your -answers, and builds a model of your workflow turn by turn. - -**How to invoke:** -``` -/workflow-architect -``` - -The agent will guide you through a conversation of about 8-15 questions. -Answer naturally — the skill adapts its probes based on what you say. - -### Mode 2: Passive Observation - -**When to use:** You're already in a session doing real work and don't want to -stop and reflect. Let this mode watch what you actually do, then infer the -workflow pattern from your actions. - -**How to invoke:** -``` -/workflow-architect passive -``` - -The agent loads the observer skill silently. It does nothing until you say one -of the trigger phrases below, at which point it scans the current session's -message history and reconstructs your workflow from what happened. - -**Trigger phrases (say any of these to activate observation analysis):** -- "catalog my workflow" -- "what's my workflow" -- "analyze my process" -- "figure out what I do" -- "work it out from what I just did" - -> **Limitation:** Observation mode works best after a session with at least -> 20+ turns of substantive work. If the session context is too thin, the -> observer will suggest switching to active interrogation mode instead. - -## Loading Protocol - -1. Read this umbrella SKILL.md for context -2. If active: load `skills/interviewer/SKILL.md` -3. If passive: load `skills/observer/SKILL.md` -4. After convergence: load `skills/bundle-builder/SKILL.md` to synthesize +59| +60|## Two Modes +61| +62|Workflow-architect adapts to how you want to engage with it. +63| +64|### Mode 1: Active Interrogation (One-Shot) +65| +66|**When to use:** You have a few minutes to talk through your process. This is +67|the most thorough mode — the agent asks guided questions, branches based on your +68|answers, and builds a model of your workflow turn by turn. +69| +70|**How to invoke:** +71|``` +72|/workflow-architect +73|``` +74| +75|The agent will guide you through a conversation of about 8-15 questions. +76|Answer naturally — the skill adapts its probes based on what you say. +77| +78|### Mode 2: Passive Observation +79| +80|**When to use:** You're already in a session doing real work and don't want to +81|stop and reflect. Let this mode watch what you actually do, then infer the +82|workflow pattern from your actions. +83| +84|**How to invoke:** +85|``` +86|/workflow-architect passive +87|``` +88| +89|The agent loads the observer skill silently. It does nothing until you say one +90|of the trigger phrases below, at which point it scans the current session's +91|message history and reconstructs your workflow from what happened. +92| +93|**Trigger phrases (say any of these to activate observation analysis):** +94|- "catalog my workflow" +95|- "what's my workflow" +96|- "analyze my process" +97|- "figure out what I do" +98|- "work it out from what I just did" +99| +100|> **Limitation:** Observation mode works best after a session with at least +101|> 20+ turns of substantive work. If the session context is too thin, the +102|> observer will suggest switching to active interrogation mode instead. +103| +104|## Loading Protocol +105| +106|1. Read this umbrella SKILL.md for context +107|2. If active: load `skills/interviewer/SKILL.md` +108|3. If passive: load `skills/observer/SKILL.md` +109|4. After convergence: load `skills/bundle-builder/SKILL.md` to synthesize and write the output bundle. The bundle is written to `~/.hermes/skills///` — verify the umbrella loads with `skill_view(name='')` and at least one sub-skill loads with `skill_view(name='-')`. Tell the user where it landed, what skills it contains, and a trigger phrase they can use to enter the workflow. - -## What the Interview Builds - -The interviewer (and observer, through inference) builds a structured model -with these dimensions: - -| Dimension | What it captures | -|-----------|------------------| -| **Entry points** | How your sessions typically start | -| **Phases** | The distinct modes or stages in your workflow | -| **Branching signals** | What makes you go left vs right at each fork | -| **Tool preferences** | What you reach for in each phase | -| **Loop conditions** | What keeps you in a mode vs what kicks you out | -| **Exit criteria** | How you know a session is done | -| **Pain points** | What feels frictionful or inefficient | - -## Environment - -No environment variables required. State is stored via memory tool -with the prefix `workflow-architect:state:` so it persists across turns -during multi-turn interviews. +123| +124|## What the Interview Builds +125| +126|The interviewer (and observer, through inference) builds a structured model +127|with these dimensions: +128| +129|| Dimension | What it captures | +130||-----------|------------------| +131|| **Entry points** | How your sessions typically start | +132|| **Phases** | The distinct modes or stages in your workflow | +133|| **Branching signals** | What makes you go left vs right at each fork | +134|| **Tool preferences** | What you reach for in each phase | +135|| **Loop conditions** | What keeps you in a mode vs what kicks you out | +136|| **Exit criteria** | How you know a session is done | +137|| **Pain points** | What feels frictionful or inefficient | +138| +139|## Environment +140| +141|No environment variables required. State is stored via memory tool +142|with the prefix `workflow-architect:state:` so it persists across turns +143|during multi-turn interviews. +144| \ No newline at end of file diff --git a/bundles/workflow-architect/skills/bundle-builder/SKILL.md b/bundles/workflow-architect/skills/bundle-builder/SKILL.md index c25462d..7cbf0d3 100644 --- a/bundles/workflow-architect/skills/bundle-builder/SKILL.md +++ b/bundles/workflow-architect/skills/bundle-builder/SKILL.md @@ -1,86 +1,86 @@ ---- -name: bundle-builder -description: >- - The synthesis engine for workflow-architect. Reads accumulated workflow - state from memory and renders it into a valid Agent Skills bundle directory - with sub-skills, manifest, decision map, and optional kanban board. Loaded - after the interviewer or observer achieves convergence. -license: MIT -compatibility: Hermes Agent — uses write_file for bundle output, shell_quote -metadata: - tags: [workflow, generation, bundle, synthesis] - spec-version: "1.0" ---- - -# 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///` with this layout: - -``` -/ +1|--- +2|name: bundle-builder +3|description: >- +4| The synthesis engine for workflow-architect. Reads accumulated workflow +5| state from memory and renders it into a valid Agent Skills bundle directory +6| with sub-skills, manifest, decision map, and optional kanban board. Loaded +7| after the interviewer or observer achieves convergence. +8|license: MIT +9|compatibility: Hermes Agent — uses write_file for bundle output, shell_quote +10|metadata: +11| tags: [workflow, generation, bundle, synthesis] +12| spec-version: "1.0" +13|--- +14| +15|# Bundle Builder — Workflow Synthesis Engine +16| +17|This sub-skill is loaded after the interviewer (active mode) or observer +18|(passive mode) achieves convergence. It reads the accumulated workflow +19|state from memory and generates an output bundle directory. +20| +21|## Input +22| +23|All `workflow-architect:state:*` memory entries. Read them all at once: +24| +25|``` +26|Read: workflow-architect:state:entry_points +27|Read: workflow-architect:state:phases +28|Read: workflow-architect:state:branching +29|Read: workflow-architect:state:pain_points +30|Read: workflow-architect:state:exit_criteria +31|``` +32| +33|If any required fields are missing (entry_points, phases, branching, exit_criteria), +34|abort with a clear message about what's missing. +35| +36|## Output Structure +37| +38|The bundle is written to `~/.hermes/skills///` with this layout: +39| +40|``` +41|/ ├── 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 -``` - +50|├── README.md # Summary of this bundle +51|├── manifest.yaml # Skill-to-trigger mapping +52|├── skills/ +53|│ ├── entry-skill.md # One per discovered phase +54|│ ├── phase-two.md +55|│ └── ... +56|├── decision-map.md # Mermaid flowchart +57|├── AGENTS.md # Agent loading instructions for this bundle +58|├── kanban/ +59|│ └── board-definition.yaml # Only if kanban is appropriate +60|└── references/ +61| └── generated-from.md # Metadata about how this bundle was created +62|``` +63| **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--`. - -### Writing the files - -For each file in the output bundle, use the templates in `templates/` as -starting points. Render them by substituting the state values. - -**Step-by-step file creation order:** - +74| +75|### Bundle naming +76| +77|Ask the user for a bundle name at the start of synthesis: +78| +79|``` +80|"Before I generate the bundle — what should I call it? +81|Something short, lowercase with hyphens, like 'my-triage-workflow' +82|or 'dev-sprint-routine'." +83|``` +84| +85|Fallback if user doesn't provide one: `my-workflow--`. +86| +87|### Writing the files +88| +89|For each file in the output bundle, use the templates in `templates/` as +90|starting points. Render them by substituting the state values. +91| +92|**Step-by-step file creation order:** +93| 0. **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')`. @@ -124,239 +124,291 @@ starting points. Render them by substituting the state values. ## 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. - -1. **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 - -2. **README.md** — Write from scratch (no template needed, it's prose). - Structure: - - ```markdown - # - - Generated by workflow-architect on . - - This bundle covers a -style workflow with phases. - - ## Skills - - | Skill | Trigger | When it fires | - |-------|---------|---------------| - | | | | - - ## Loading - - Skills in this bundle are loaded automatically by trigger conditions. - To load a specific skill: `skill_view(name='/')` - - ## Kanban - - (Only if kanban exists) This workflow maps to a kanban board with lanes. - ``` - -3. **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 - -4. **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 - -5. **AGENTS.md** — Standard agent loading instructions for this bundle. - Short — just says which skills exist and when to load them. - -6. **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: - - ```markdown - # Kanban Board: - - This workflow maps to a Hermes Kanban board with 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: - ```bash - hermes kanban boards create --name "" - ``` - - ## Task Lifecycle - - → → - - 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: - ```bash - hermes kanban create "Build: " \\ - --skill / \\ - --priority 3 - ``` - - Then create subsequent-phase tasks with `--parent` pointing to the - first task's ID: - ```bash - hermes kanban create "Review: " \\ - --parent \\ - --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. - ``` - -7. **references/generated-from.md** — Metadata about the generation process: - - ```markdown - # Generated From - - - **Skill:** workflow-architect - - **Mode:** active | passive - - **Date:** - - **Archetype:** - - **Convergence Score:** - ``` - -8. **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/.md`: - - ```python - skill_manage(action='create', - name='-', - content=read_file('/skills/.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 `.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: - ```python - skill_view(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.]" -``` - -8. **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/.md`: - Read the file content - skill_manage( - action='create', - name='/', - content=file_content - ) - ``` - - This makes each sub-skill loadable as `skill_view('/')`. - 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: - -1. Remove all `workflow-architect:state:*` memory entries +138| - Are any phases automatic (e.g., refine always follows draft)? +139| - What's the relationship between phases (sequential, branching, optional)? +140| ``` +141| +142| **Category choice:** Place the bundle in a category that matches where its +143| sub-skills live (e.g., `content` for blogging pipelines, `devops` for +144| deployment workflows). Ask the user if unsure. +145|======= +146|0. **umbrella SKILL.md** — Create the bundle's entry point. This is the +147| first file because the umbrella must be registered and discoverable +148| before any sub-skill can be loaded. +149| +150| a. Generate an umbrella SKILL.md with: +151| +152| **Frontmatter:** +153| - `name: ` +154| - `description:` — Craft this carefully. Include broad trigger +155| phrases that cover all phases of the workflow, so the agent can +156| auto-detect this bundle in future sessions. Pattern: +157| "Use when [trigger summary]. Covers: [phase list]." +158| - `tags: [workflow, bundle:generated, ]` +159| - `spec-version: "1.0"` +160| +161| **Body:** +162| - H1: `# ` (user-friendly title) +163| - **Phase table** — Markdown table mapping each sub-skill +164| name to its trigger condition and typical entry signal. +165| Columns: | Phase | Load this skill | When | +166| - **Workflow flowchart** — Mermaid `graph LR` or `graph TD` +167| showing entry → phases (with decision diamonds for +168| branching) → exit. Entry condition links to the description. +169| - **Navigation instructions** — Explain the two-entry model: +170| (1) auto-detect via trigger conditions, (2) `skill_view(name='')` +171| to inspect the pipeline. Tell the agent: identify the user's +172| current phase, load that sub-skill, follow its instructions. +173| - **Heuristics** — Phase ordering notes (sequential vs. flexible), +174| entry points (can start at any phase), transition signals. +175| +176| b. Write to `/SKILL.md` via `write_file`. +177| +178| c. Register with: +179| ``` +180| skill_manage(action='create', name='', content='...') +181| ``` +182| +183| > **Why step 0?** The umbrella SKILL.md is the agent's entry point to +184| > the entire bundle. It must exist and be registered first so that any +185| > subsequent sub-skill loading instructions reference a discoverable +186| > parent. Without it, the bundle is invisible to the agent. +187|>>>>>>> 77f9d16 (fix(bundle-builder): generate umbrella SKILL.md as discoverable entry point) +188| +189|1. **manifest.yaml** — Use `templates/manifest.yaml.tmpl`. Substitute: +190| - `{{BUNDLE_NAME}}` — the bundle name +191| - `{{PHASES}}` — each phase with its trigger keywords, entry signals, +192| typical tools, and exit signals +193| - `{{HAS_KANBAN}}` — true/false based on kanban decision +194| +195|2. **README.md** — Write from scratch (no template needed, it's prose). +196| Structure: +197| +198| ```markdown +199| # +200| +201| Generated by workflow-architect on . +202| +203| This bundle covers a -style workflow with phases. +204| +205| ## Skills +206| +207| | Skill | Trigger | When it fires | +208| |-------|---------|---------------| +209| | | | | +210| +211| ## Loading +212| +213| Skills in this bundle are loaded automatically by trigger conditions. +214| To load a specific skill: `skill_view(name='/')` +215| +216| ## Kanban +217| +218| (Only if kanban exists) This workflow maps to a kanban board with lanes. +219| ``` +220| +221|3. **Sub-skills** — For each phase in `workflow-architect:state:phases`, +222| generate a `.md` file in `skills/` using `templates/skill-skeleton.md`. +223| +224| Naming convention: `kebab-case-phase-name.md` (e.g., `morning-triage.md`). +225| +226| Each sub-skill file is a valid Agent Skills SKILL.md with: +227| - `name` matching the filename (without .md) +228| - `description` that includes trigger keywords from the phase's typical +229| openers and tools +230| - `compatibility: Compatible with any agent supporting the Agent Skills format` +231| - Body sections: +232| - **When to use** — the trigger condition in natural language +233| - **What to do** — step-by-step instructions for the agent in this phase +234| - **Transition signals** — what the user typically says or does that +235| transitions out of this phase +236| - **What to tell the user** — guidance on how the agent should communicate +237| during this phase +238| +239|4. **decision-map.md** — Use `templates/decision-map.md.tmpl`. Substitute: +240| - `{{WORKFLOW_NAME}}` — bundle name +241| - `{{PHASE_NODES}}` — phase names +242| - `{{BRANCHING}}` — decision diamonds +243| - `{{ENTRY}}` — how sessions start +244| - `{{EXITS}}` — how sessions end +245| +246|5. **AGENTS.md** — Standard agent loading instructions for this bundle. +247| Short — just says which skills exist and when to load them. +248| +249|6. **kanban/ directory** — Only if the kanban-decision-criteria.md reference +250| indicates kanban is appropriate. Generates three files: +251| +252| a) **kanban/board-setup.sh** — Use `templates/kanban-board-setup.sh.tmpl`. +253| Substitutes: +254| - `{{BOARD_SLUG}}` — bundle name (kebab-case) +255| - `{{BOARD_NAME}}` — title-case version or user-provided name +256| - `{{FIRST_PHASE_SKILL}}` — skill file for the first phase +257| - `{{FIRST_PHASE_PRIORITY}}` — priority for first-phase tasks +258| - `{{GENERATION_DATE}}` — current date +259| +260| The setup script creates the board via `hermes kanban boards create` +261| and prints instructions for adding work. +262| +263| b) **kanban/task-blueprints.yaml** — Use `templates/kanban-task-blueprints.yaml.tmpl`. +264| Substitutes: +265| - `{{BLUEPRINT_ENTRIES}}` — one blueprint entry per phase, each with: +266| - `phase:` — phase name (kebab-case) +267| - `title_template:` — e.g. "Build: {{feature}}" +268| - `skill:` — path to the sub-skill file (e.g. `my-workflow/build`) +269| - `default_priority:` — descending from first phase (highest) to last +270| - `initial_status:` — first phase = `todo`, rest = `ready` +271| - `body:` — instructions for the worker: what skill to load, +272| definition of done, and transition to next phase +273| +274| c) **kanban/README.md** — Brief usage guide explaining how to set up and +275| use the board. Structure: +276| +277| ```markdown +278| # Kanban Board: +279| +280| This workflow maps to a Hermes Kanban board with phases in sequence. +281| +282| ## Setup +283| +284| Run `kanban/board-setup.sh` to create the board: +285| ```bash +286| bash kanban/board-setup.sh +287| ``` +288| +289| The script creates the board and switches to it. If you prefer to set +290| it up manually: +291| ```bash +292| hermes kanban boards create --name "" +293| ``` +294| +295| ## Task Lifecycle +296| +297| → → +298| +299| Each phase's task depends on the previous phase's task completing. +300| When a task is done, the next phase's task auto-promotes to "ready" +301| and the dispatcher picks it up. +302| +303| ## Adding Work +304| +305| Create a task for the first phase: +306| ```bash +307| hermes kanban create "Build: " \\ +308| --skill / \\ +309| --priority 3 +310| ``` +311| +312| Then create subsequent-phase tasks with `--parent` pointing to the +313| first task's ID: +314| ```bash +315| hermes kanban create "Review: " \\ +316| --parent \\ +317| --skill / \\ +318| --priority 2 +319| ``` +320| +321| ## Task Blueprints +322| +323| See `kanban/task-blueprints.yaml` for template definitions of each +324| phase's task, including default priorities, skill mappings, and +325| worker instructions. +326| ``` +327| +328|7. **references/generated-from.md** — Metadata about the generation process: +329| +330| ```markdown +331| # Generated From +332| +333| - **Skill:** workflow-architect +334| - **Mode:** active | passive +335| - **Date:** +336| - **Archetype:** +337| - **Convergence Score:** +338| ``` +339| +340|8. **Register sub-skills with Hermes skill system** — For each sub-skill `.md` +341| file written in step 3, register it so it appears in `skills_list()` and +342| can be loaded with `skill_view()`. This is the critical step that makes +343| generated skills actually usable by the agent. +344| +345| For each sub-skill file in `skills/.md`: +346| +347| ```python +348| skill_manage(action='create', +349| name='-', +350| content=read_file('/skills/.md')['content'], +351| category='generated') +352| ``` +353| +354| This creates a proper skill directory with `SKILL.md` entry point, making +355| the sub-skill discoverable and loadable. The sub-skill's existing valid +356| Agent Skills frontmatter (name, description, license, tags) is used as-is. +357| +358| **Why separate registration is needed:** The `skill_manage()` call also +359| handles the skill directory structure (`SKILL.md` at root, not `.md` +360| in a `skills/` subdirectory). Without this step, the sub-skill files exist +361| on disk but no Hermes mechanism discovers them. Only the umbrella SKILL.md +362| (registered in step 0) would be loadable. +363| +364| **Verification:** After registering all sub-skills, verify at least one: +365| ```python +366| skill_view(name='-') +367| ``` +368| +369| If it errors, the registration failed — check that the sub-skill file's +370| frontmatter `name` field matches and the content has valid YAML. +371| +372|## Kanban Decision +373| +374|Before generating kanban files, consult `references/kanban-decision-criteria.md` +375|to decide whether a board is appropriate. The decision depends on the phases +376|and branching structure discovered: +377| +378|- If phases form a clear linear sequence (A → B → C → D), kanban adds value +379|- If branching is emergent (session depends on context), kanban is likely inappropriate +380|- If the user mentioned waiting on others, hand-offs, or status tracking, kanban is a strong fit +381| +382|Present the decision to the user: +383| +384|``` +385|"Your workflow has a [linear/emergent] structure. A kanban board [would/wouldn't] +386|add much value here because [reason]. [If yes: I'll add one to the bundle.]" +387|``` +388| +389|8. **Register sub-skills** — For each generated sub-skill `.md` file in +390| `skills/`, register it so Hermes can discover it via `skill_view()` and +391| `skills_list()`: +392| +393| ``` +394| For each sub-skill file `skills/.md`: +395| Read the file content +396| skill_manage( +397| action='create', +398| name='/', +399| content=file_content +400| ) +401| ``` +402| +403| This makes each sub-skill loadable as `skill_view('/')`. +404| The bundle name prefix prevents naming collisions with other skills. +405| +406| If `skill_manage` is not available in the agent's toolset, note this for +407| the user and suggest they run the registration manually. +408| +409|## Cleanup +410| +411|After writing all files: +412| +413|1. Verify the umbrella registered successfully: +414| ``` +415| skill_view(name='') +416| ``` +417| If it returns `status: available`, proceed. If not found, re-run the +418| `skill_manage(action='create')` call. +419| +420|2. Remove all `workflow-architect:state:*` memory entries +421| (`memory(action='remove', target='memory', old_text='workflow-architect:state:')`) +2. Remove all `workflow-architect:state:*` memory entries (`memory(action='remove', target='memory', old_text='workflow-architect:state:')`) 2. Tell the user where the bundle was written and what it contains 3. Verify the umbrella loads correctly with `skill_view(name='')` @@ -366,3 +418,4 @@ After writing all files: `skill_view(name='-')` 5. Suggest they enter the workflow via any trigger phrase covered by the umbrella's description, or by manually loading the umbrella skill +438| \ No newline at end of file