mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-11 19:47:12 +03:00
Merge pull request 'fix(bundle-builder): generate umbrella SKILL.md as discoverable entry point' (#53) from fix/bundle-builder-umbrella-entry into main
This commit is contained in:
Jasper (AI Assistant)
@@ -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='<bundle-name>')`
|
||||
and `skill_view(name='<bundle-name>-<first-phase-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 `<bundle-name>` (the bundle root skill)
|
||||
- **Sub-skills** — registered under `<bundle-name>/<phase-name>`
|
||||
|
||||
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
|
||||
|
||||
+114
-113
@@ -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='<bundle-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/<category>/<bundle-name>/` — verify the umbrella loads
|
||||
with `skill_view(name='<bundle-name>')` and at least one sub-skill loads
|
||||
with `skill_view(name='<bundle-name>-<phase-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|
|
||||
@@ -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/<category>/<bundle-name>/` with this layout:
|
||||
|
||||
```
|
||||
<bundle-name>/
|
||||
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/<category>/<bundle-name>/` with this layout:
|
||||
39|
|
||||
40|```
|
||||
41|<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
|
||||
```
|
||||
|
||||
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-<archetype>-<date>`.
|
||||
|
||||
### 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-<archetype>-<date>`.
|
||||
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
|
||||
# <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.
|
||||
```
|
||||
|
||||
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: <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:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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.
|
||||
```
|
||||
|
||||
7. **references/generated-from.md** — Metadata about the generation process:
|
||||
|
||||
```markdown
|
||||
# Generated From
|
||||
|
||||
- **Skill:** workflow-architect
|
||||
- **Mode:** active | passive
|
||||
- **Date:** <date>
|
||||
- **Archetype:** <archetype>
|
||||
- **Convergence Score:** <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/<name>.md`:
|
||||
|
||||
```python
|
||||
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:
|
||||
```python
|
||||
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.]"
|
||||
```
|
||||
|
||||
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/<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:
|
||||
|
||||
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: <bundle-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, <archetype>]`
|
||||
159| - `spec-version: "1.0"`
|
||||
160|
|
||||
161| **Body:**
|
||||
162| - H1: `# <Bundle Name>` (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='<bundle-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 `<bundle-name>/SKILL.md` via `write_file`.
|
||||
177|
|
||||
178| c. Register with:
|
||||
179| ```
|
||||
180| skill_manage(action='create', name='<bundle-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| # <Bundle Name>
|
||||
200|
|
||||
201| Generated by workflow-architect on <date>.
|
||||
202|
|
||||
203| This bundle covers a <archetype>-style workflow with <N> phases.
|
||||
204|
|
||||
205| ## Skills
|
||||
206|
|
||||
207| | Skill | Trigger | When it fires |
|
||||
208| |-------|---------|---------------|
|
||||
209| | <name> | <trigger description> | <when to load> |
|
||||
210|
|
||||
211| ## Loading
|
||||
212|
|
||||
213| Skills in this bundle are loaded automatically by trigger conditions.
|
||||
214| To load a specific skill: `skill_view(name='<bundle-name>/<skill-name>')`
|
||||
215|
|
||||
216| ## Kanban
|
||||
217|
|
||||
218| (Only if kanban exists) This workflow maps to a kanban board with <N> 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: <Bundle Name>
|
||||
279|
|
||||
280| This workflow maps to a Hermes Kanban board with <N> 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 <bundle-name> --name "<Bundle Name>"
|
||||
293| ```
|
||||
294|
|
||||
295| ## Task Lifecycle
|
||||
296|
|
||||
297| <Phase 1> → <Phase 2> → <Phase 3>
|
||||
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: <feature description>" \\
|
||||
308| --skill <bundle-name>/<phase-1-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: <feature>" \\
|
||||
316| --parent <task-id> \\
|
||||
317| --skill <bundle-name>/<phase-2-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:** <date>
|
||||
336| - **Archetype:** <archetype>
|
||||
337| - **Convergence Score:** <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/<name>.md`:
|
||||
346|
|
||||
347| ```python
|
||||
348| skill_manage(action='create',
|
||||
349| name='<bundle-name>-<skill-name>',
|
||||
350| content=read_file('<bundle-path>/skills/<name>.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 `<name>.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='<bundle-name>-<first-phase-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/<phase-name>.md`:
|
||||
395| Read the file content
|
||||
396| skill_manage(
|
||||
397| action='create',
|
||||
398| name='<bundle-name>/<phase-name>',
|
||||
399| content=file_content
|
||||
400| )
|
||||
401| ```
|
||||
402|
|
||||
403| This makes each sub-skill loadable as `skill_view('<bundle-name>/<phase-name>')`.
|
||||
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='<bundle-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='<bundle-name>')`
|
||||
@@ -366,3 +418,4 @@ After writing all files:
|
||||
`skill_view(name='<bundle-name>-<first-phase-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|
|
||||
Reference in New Issue
Block a user