From a454be00996fd4411db009d5c4e7bc527fc0f54d Mon Sep 17 00:00:00 2001 From: Blake Harms Date: Mon, 4 May 2026 20:42:46 -0500 Subject: [PATCH 1/4] Added skill and skill installation guide --- README.md | 44 ++++- skills/bifrost-rune-workflow.md | 335 ++++++++++++++++++++++++++++++++ 2 files changed, 374 insertions(+), 5 deletions(-) create mode 100644 skills/bifrost-rune-workflow.md diff --git a/README.md b/README.md index 0c314cf..ad7a623 100644 --- a/README.md +++ b/README.md @@ -156,13 +156,47 @@ The package installs: - `/etc/bifrost/server.yaml` — config file (backup on upgrade) - `/var/lib/bifrost/` — data directory +## Skills Integration + +Bifrost includes a skill for AI agents that plan and execute work using Bifrost runes. The skill provides structured workflows for any agent system that supports the skills standard. + +### What the Skill Does + +The `bifrost-rune-workflow` skill provides structured workflows for: + +- **Planning**: Create runes, group them into sagas (epics), set dependencies, and organize work +- **Execution**: Find available runes, claim them, track progress, and fulfill tasks +- **Agent Routing**: Use tags to route work to specialized agents (implementer, tester, debugger, etc.) +- **Orchestration**: Automatically dispatch ready runes to appropriate agents + +### Core Concepts Covered + +- Rune lifecycle (draft → forge → open → claim → fulfill → seal) +- Saga (epic) creation and child rune management +- Dependency relationships (blocks, relates_to, duplicates, supersedes, replies_to) +- Tag-based agent specialization and routing +- Branch tracking and Git integration +- Quality gates and completion workflows + +### Installation + +Install the skill directly from the Bifrost repository: + +```bash +npx skills add https://github.com/devzeebo/bifrost/skills/bifrost-rune-workflow.md +``` + +This registers the skill for all detected agents and places it in `.agents/skills/bifrost-rune-workflow/skill.md`. Once installed, agents can load the skill using their skill-loading mechanism. + +See the [skill documentation](./skills/bifrost-rune-workflow.md) for complete usage details, command reference, and pitfalls. + ## Glossary -| Term | Meaning | -|-----------|-------------------------------------------------| -| **Rune** | A work item (issue, task, bug, etc.) | -| **Saga** | An epic; collection of related runes | -| **Realm** | A tenant; isolated namespace with credentials | +|| Term | Meaning | +||-----------|-------------------------------------------------| +|| **Rune** | A work item (issue, task, bug, etc.) | +|| **Saga** | An epic; collection of related runes | +|| **Realm** | A tenant; isolated namespace with credentials | ## Documentation diff --git a/skills/bifrost-rune-workflow.md b/skills/bifrost-rune-workflow.md new file mode 100644 index 0000000..4beeddf --- /dev/null +++ b/skills/bifrost-rune-workflow.md @@ -0,0 +1,335 @@ +--- +name: bifrost-rune-workflow +description: Plan and execute work using Bifrost (bf) CLI — create runes, group into sagas (epics), set dependencies, claim, work, and fulfill runes. +category: productivity +--- + +# Bifrost Rune Workflow + +Bifrost is an event-sourced task management system for AI agents. This skill covers two phases: **Planning** (creating runes, grouping into sagas/epics, setting dependencies) and **Execution** (finding, claiming, working, and fulfilling runes). + +## Prerequisites + +- `bf` CLI installed and authenticated (`bf login`) +- `.bifrost.yaml` initialized in the repo (`bf init --realm `) +- Realm configured in `.bifrost.yaml` + +## Core Concepts + +### Rune Types + +| Type Field | Meaning | +|------------|---------| +| `rune` (default) | Standard task | +| `saga` | Epic/parent rune — groups child runes | + +A saga is any rune that has children. When a rune has child runes, `bf ready --sagas` and `bf list --saga ` will include it. The `is_saga` filter on the server side checks for the existence of a `rune_child_count` projection entry. + +### Rune Lifecycle + +``` +draft → [forge] → open → [claim] → claimed → [fulfill] → fulfilled + ↓ + [seal] → sealed +``` + +- **draft** — initial state after `bf create` +- **open** — after `bf forge`, ready to be claimed +- **claimed** — someone is actively working on it +- **fulfilled** — work is complete +- **sealed** — cancelled/won't do (can have a reason) +- **shattered** — irreversible tombstone (deleted from projections) + +### Dependencies + +Relationships between runes: +- `blocks` / `blocked_by` — execution dependency +- `relates_to` — loose association +- `duplicates` / `duplicated_by` — one supersedes another +- `supersedes` / `superseded_by` — replaces another (auto-seals the target) +- `replies_to` / `replied_to_by` — response/feedback relationship + +Cycle detection is built-in for `blocks` relationships. + +### Tags + +Tags are normalized to lowercase, deduplicated, and sorted. They can be used to: +- Identify specialized agents: `tester`, `implementer`, `debugger`, `ux-design`, `infra`, `security`, `documentation` +- Categorize work: `bug`, `feature`, `refactor`, `performance` +- Mark priority context: `urgent`, `nice-to-have` + +Tags are set at creation with `--tag` and can be added/removed later with `bf update --add-tag` / `--remove-tag`. + +### Priority + +Integer 0–4, where lower is more important. + +### Branch Tracking + +Runes can be associated with Git branches: +- Top-level runes require `--branch` or `--no-branch` +- Child runes inherit the parent's branch by default +- Use `--branch` on child to override + +--- + +## Phase 1: Planning + +### Create a Saga (Epic) + +```bash +bf create "Implement user authentication" --no-branch -p 3 --tag saga --tag feature +``` + +This creates a top-level saga rune. Note the `--no-branch` since sagas don't need a code branch. + +### Create Child Runes Under a Saga + +```bash +bf create "Add login endpoint" --parent -d "POST /auth/login with JWT" -p 2 --tag implementer --tag backend +bf create "Add logout endpoint" --parent -d "POST /auth/logout, invalidate token" -p 1 --tag implementer +bf create "Write auth integration tests" --parent -p 2 --tag tester +``` + +Child runes inherit the parent's branch (if any). They get IDs like `.1`, `.2`, etc. + +### Set Dependencies + +```bash +# Login must be done before logout (logout blocks nothing, login blocks logout) +bf dep add blocks + +# Tests are blocked by implementation +bf dep add blocks +# Or equivalently: +bf dep add blocked_by + +# Mark something as related +bf dep add relates_to +``` + +### Check Dependencies + +```bash +bf dep list # Show all dependencies for a rune +bf dep list --human # Human-readable table +bf ready # Shows unblocked, unclaimed runes +bf ready --human # Table format +bf ready --sagas # Include sagas in output +``` + +### View Full Plan + +```bash +bf list --human # All runes in a table +bf list --saga --human # All children of a saga +bf list --tag tester --human # Filter by tag (agent specialization) +bf list --status open --human # Only open runes +bf show # Full detail including deps, notes, tags +bf show --human # Human-readable detail +``` + +### Add Notes to a Rune + +```bash +bf note "Implementation should use refresh tokens with 7-day expiry" +``` + +### Update a Rune + +```bash +bf update --title "New title" +bf update --description "Updated description" +bf update --priority 3 +bf update --add-tag urgent +bf update --remove-tag nice-to-have +``` + +### Forge a Rune (Ready for Work) + +```bash +bf forge # Moves from draft → open +``` + +When forging a saga, all child runes are recursively forged. + +--- + +## Phase 2: Execution + +### Find Available Work + +```bash +bf ready --json # Machine-readable list of ready runes +bf ready --human # Table view +bf ready --saga # Only runes in a specific saga +``` + +`bf ready` returns runes that are: +- Status: `open` +- Not blocked by unfulfilled dependencies +- Not already claimed +- Not sagas (unless `--sagas` flag) + +### Claim a Rune + +```bash +bf claim +bf claim --as "agent-name" # Specify claimant +``` + +Only one agent can claim a rune at a time. + +### Work on a Rune + +During work, use these to track progress: + +```bash +bf note "Started implementing, ran into CORS issue" +bf note "Fixed CORS, writing tests now" +bf retro "Should have designed the API contract first" +``` + +### Fulfill a Rune + +```bash +bf fulfill +``` + +Requirements: +- Must be in `claimed` status +- Cannot fulfill sealed or shattered runes + +### Seal a Rune (Cancel) + +```bash +bf seal --reason "Out of scope" +bf seal --reason "Duplicate of " +``` + +### Unclaim a Rune + +```bash +bf unclaim +``` + +Use when work cannot proceed or is being handed off. + +### Shatter a Rune (Irreversible Delete) + +```bash +bf shatter +``` + +Removes the rune from all projections. Cannot be undone. + +--- + +## Tag-Based Agent Routing + +Tags are the primary mechanism for routing work to specialized agents: + +| Tag Convention | Agent Role | +|----------------|-----------| +| `implementer` | Code implementation | +| `tester` | Writing and running tests | +| `debugger` | Investigating and fixing bugs | +| `ux-design` | UI/UX work | +| `infra` | Infrastructure/DevOps | +| `security` | Security review/fixes | +| `documentation` | Docs and comments | +| `reviewer` | Code review | +| `planner` | Architecture and planning | + +### Workflow: Agent-Dispatched Execution + +When using `bf orchestrate`, a dispatcher script receives rune data on stdin and returns a command to execute: + +```bash +# Dispatch ready runes to agents +bf orchestrate --dispatcher ./dispatch.sh --once +bf orchestrate --dispatcher ./dispatch.sh --dry-run # Preview without executing +bf orchestrate --dispatcher ./dispatch.sh --concurrency 3 # Parallel workers +``` + +The dispatcher script receives JSON on stdin: + +```json +{ + "id": "bf-01", + "title": "Add login endpoint", + "description": "POST /auth/login with JWT", + "status": "open", + "priority": 2, + "tags": ["implementer", "backend"], + "notes": [...], + "dependencies": [...] +} +``` + +And must return JSON on stdout: + +```json +{ + "command": "python", + "args": ["run_agent.py", "--task", "implement"], + "env": {"AGENT_ROLE": "implementer"} +} +``` + +If `command` is empty, the rune is skipped and unclaimed. + +--- + +## Quick Reference: All bf Commands + +``` +bf create Create a new rune +bf forge <id> Move rune from draft to open (recursively for sagas) +bf claim <id> Claim a rune for work +bf fulfill <id> Mark a claimed rune as complete +bf seal <id> Cancel a rune +bf shatter <id> Irreversibly delete a rune +bf unclaim <id> Release a claimed rune +bf update <id> Modify rune properties +bf show <id> Show full rune details +bf list List all runes +bf ready List unblocked, unclaimed runes +bf dep add <id> <rel> <target> Add a dependency +bf dep list <id> Show dependencies +bf dep remove <id> <rel> <target> Remove a dependency +bf note <id> <text> Add a note +bf retro <id> [text] Add/view retro items +bf events <id> Show raw event stream +bf init --realm <name> Initialize repo for bifrost +bf orchestrate Poll and dispatch ready runes +bf sweep Clean up unreferenced sealed/fulfilled runes +``` + +### Common Flags + +- `--human` — human-readable output (default is JSON) +- `--json` — force JSON output +- `--tag <tag>` — apply or filter by tag (repeatable) +- `--parent <id>` — create as child of another rune +- `--saga <id>` — filter by parent saga +- `--status <status>` — filter by status (open|claimed|fulfilled|sealed) +- `--priority <0-4>` — set or filter priority +- `--branch <name>` — associate with git branch +- `--no-branch` — explicitly no branch +- `--description` or `-d` — rune description + +--- + +## Pitfalls + +- **Cannot claim draft runes** — must `bf forge` first +- **Cannot fulfill unclaimed runes** — must claim first +- **Top-level runes require --branch or --no-branch** — child runes inherit parent branch +- **`bf dep add` with `blocked_by` is inverse** — `bf dep add A blocked_by B` creates `B blocks A` +- **Tags are case-insensitive** — all normalized to lowercase +- **`supersedes` auto-seals the target** — adding this relationship automatically seals the superseded rune +- **Shattered runes are tombstones** — they cannot be recreated with the same ID +- **`bf forge` on a saga recursively forges all children** — including shattered ones (skipped silently) +- **`bf ready` excludes sagas by default** — use `--sagas` to include them +- **Only one rune can be in_progress at a time** — follow the workflow: claim → work → fulfill before claiming another From d950aa22d2fad3dad80ace659bc6ac5a472f3354 Mon Sep 17 00:00:00 2001 From: Blake Harms <blake@harms.haus> Date: Mon, 4 May 2026 20:48:22 -0500 Subject: [PATCH 2/4] Fix installation command in README Update installation command to use raw GitHub URL --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ad7a623..974ab57 100644 --- a/README.md +++ b/README.md @@ -183,7 +183,7 @@ The `bifrost-rune-workflow` skill provides structured workflows for: Install the skill directly from the Bifrost repository: ```bash -npx skills add https://github.com/devzeebo/bifrost/skills/bifrost-rune-workflow.md +npx skills add https://raw.githubusercontent.com//devzeebo/bifrost/skills/bifrost-rune-workflow.md ``` This registers the skill for all detected agents and places it in `.agents/skills/bifrost-rune-workflow/skill.md`. Once installed, agents can load the skill using their skill-loading mechanism. From 81abd531c53047fb5844489741bbd4c26b35caae Mon Sep 17 00:00:00 2001 From: Blake Harms <blake@harms.haus> Date: Mon, 4 May 2026 20:50:53 -0500 Subject: [PATCH 3/4] Update README.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 974ab57..360d509 100644 --- a/README.md +++ b/README.md @@ -192,11 +192,11 @@ See the [skill documentation](./skills/bifrost-rune-workflow.md) for complete us ## Glossary -|| Term | Meaning | -||-----------|-------------------------------------------------| -|| **Rune** | A work item (issue, task, bug, etc.) | -|| **Saga** | An epic; collection of related runes | -|| **Realm** | A tenant; isolated namespace with credentials | +| Term | Meaning | +|-----------|----------------------------------------------| +| **Rune** | A work item (issue, task, bug, etc.) | +| **Saga** | An epic; collection of related runes | +| **Realm** | A tenant; isolated namespace with credentials | ## Documentation From 5ddfbbe65594f29006922cc8cccd282f8e8c26fa Mon Sep 17 00:00:00 2001 From: Blake Harms <blake@harms.haus> Date: Mon, 4 May 2026 20:51:25 -0500 Subject: [PATCH 4/4] Update skills/bifrost-rune-workflow.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- skills/bifrost-rune-workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/bifrost-rune-workflow.md b/skills/bifrost-rune-workflow.md index 4beeddf..38b66ef 100644 --- a/skills/bifrost-rune-workflow.md +++ b/skills/bifrost-rune-workflow.md @@ -332,4 +332,4 @@ bf sweep Clean up unreferenced sealed/fulfilled runes - **Shattered runes are tombstones** — they cannot be recreated with the same ID - **`bf forge` on a saga recursively forges all children** — including shattered ones (skipped silently) - **`bf ready` excludes sagas by default** — use `--sagas` to include them -- **Only one rune can be in_progress at a time** — follow the workflow: claim → work → fulfill before claiming another +- **Only one rune can be claimed at a time** — follow the workflow: claim → work → fulfill before claiming another