Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions .agents/skills/release/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
---
name: release
description: Automate releasing the @boldblackai/create-bclaw npm package. Use this skill whenever the user wants to cut a release, publish a new version, bump the version, tag a release, update the CHANGELOG, or run npm publish. Triggers on phrases like "release version X", "cut a release", "publish", "bump to X.X.X", "tag this release", "release the project", or any combination of version bumping + publishing intent. Always use this skill for release work — don't attempt ad-hoc release steps without it.
description: Automate releasing the @boldblackai/create-dispatch npm package. Use this skill whenever the user wants to cut a release, publish a new version, bump the version, tag a release, update the CHANGELOG, or run npm publish. Triggers on phrases like "release version X", "cut a release", "publish", "bump to X.X.X", "tag this release", "release the project", or any combination of version bumping + publishing intent. Always use this skill for release work — don't attempt ad-hoc release steps without it.
---

# Release Skill for `@boldblackai/create-bclaw`
# Release Skill for `@boldblackai/create-dispatch`

Automates the full release pipeline: pre-flight checks → version bump → CHANGELOG → verify → build → open release PR → (maintainer merges) → CI auto-tags, publishes to npm (OIDC), creates GitHub release.

> **npm publishing is fully automated via [trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC).** The agent never touches npm credentials, pushes tags, or creates GitHub releases. It only opens a release PR; merging that PR triggers `tag-on-merge.yml`, which handles everything: tag, npm publish (with provenance attestations), and GitHub release — all in one workflow.
>
> **Release model:** The trust boundary is "can merge a PR to main" = "can release." The agent has zero upstream write access — it opens the PR from its fork (BoldBlackBot); the maintainer's squash-merge triggers everything.
>
> **Prerequisite (one-time, manual on npmjs.com):** Configure the trusted publisher for `@boldblackai/create-bclaw` under Settings → Trusted Publisher → GitHub Actions: org=`boldblackai`, repo=`create-bclaw`, workflow filename=`tag-on-merge.yml`. Then under Settings → Publishing access, select "Require two-factor authentication and disallow tokens" (recommended) — OIDC publishes are unaffected by this setting.
> **Prerequisite (one-time, manual on npmjs.com):** Configure the trusted publisher for `@boldblackai/create-dispatch` under Settings → Trusted Publisher → GitHub Actions: org=`boldblackai`, repo=`create-dispatch`, workflow filename=`tag-on-merge.yml`. Then under Settings → Publishing access, select "Require two-factor authentication and disallow tokens" (recommended) — OIDC publishes are unaffected by this setting.

## Step 1: Pre-flight checks (abort on failure)

Expand Down Expand Up @@ -122,7 +122,7 @@ git commit -m "release v<version>"
Ensure a fork remote exists (for the agent's bot account):

```bash
git remote add fork https://github.com/BoldBlackBot/create-bclaw.git 2>/dev/null || true
git remote add fork https://github.com/BoldBlackBot/create-dispatch.git 2>/dev/null || true
```

Push the release branch:
Expand All @@ -135,7 +135,7 @@ Open the PR — the squash merge commit message (`release v<version>`) is the se

```bash
gh pr create \
--repo boldblackai/create-bclaw \
--repo boldblackai/create-dispatch \
--head BoldBlackBot:release/v<version> \
--base main \
--title "release v<version>" \
Expand Down Expand Up @@ -166,19 +166,19 @@ After the PR is squash-merged, the merge commit (`release v<version> (#N)`) trig
### 11a: Verify tag-on-merge ran (tag + npm + release)

```bash
gh run list --repo boldblackai/create-bclaw --workflow tag-on-merge.yml --limit 1
gh run list --repo boldblackai/create-dispatch --workflow tag-on-merge.yml --limit 1
```

Confirm the workflow succeeded. If it failed, check logs:

```bash
gh run view <run-id> --repo boldblackai/create-bclaw --log-failed
gh run view <run-id> --repo boldblackai/create-dispatch --log-failed
```

Once the workflow succeeds, verify the package landed on npm **with provenance attestations**:

```bash
npm view @boldblackai/create-bclaw@<version> dist --json
npm view @boldblackai/create-dispatch@<version> dist --json
```

Confirm the output includes an `attestations` field (not just `signatures`). If `attestations` is missing, the publish did not generate provenance — investigate before continuing.
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/tag-on-merge.yml
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ jobs:
- name: Publish to npm (OIDC trusted publishing)
run: |
VERSION="${{ steps.version.outputs.version }}"
if npm view "@boldblackai/create-bclaw@${VERSION}" dist --json >/dev/null 2>&1; then
if npm view "@boldblackai/create-dispatch@${VERSION}" dist --json >/dev/null 2>&1; then
echo "Version $VERSION already published, skipping"
else
npm publish
Expand Down
20 changes: 10 additions & 10 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,10 @@ Significant changes, architectural decisions, and new features should be propose

## Overview

This repo is `@boldblackai/create-bclaw`, an `npx`-distributed CLI that
This repo is `@boldblackai/create-dispatch`, an `npx`-distributed CLI that
generates a renamed skeleton of a Hermes Agent claw repo. Running
`npx @boldblackai/create-bclaw foo` produces a `foo/` directory whose contents
match the bundled `template/` snapshot except every lowercase `bclaw` reference
`npx @boldblackai/create-dispatch foo` produces a `foo/` directory whose contents
match the bundled `template/` snapshot except every lowercase `dispatch` reference
— file contents and file/directory names, including the SSM namespace, IAM
scopes, and KMS alias — is renamed to `foo`. A second literal token, `us-east-1`,
is substituted with the chosen AWS region (`--region`, default `us-east-1`) so
Expand Down Expand Up @@ -64,10 +64,10 @@ steps and current-state facts only.
## Layout: Generator Repo + Integration Repo

Since it doesn't make sense to deploy changes made in /workspace (its just templates + generator), we use an integration
repository instead (`/alt/integration`), which has AWS creds and represents a live, deployed bclaw we can make changes to.
repository instead (`/alt/integration`), which has AWS creds and represents a live, deployed dispatch agent we can make changes to.

- `/workspace` (no aws access): the `create-bclaw` project, it creates project skeletons from `template/`
- `/alt/integration` (aws access via mise): a project created from `create-bclaw`; we edit and iterate on THIS repo, and
- `/workspace` (no aws access): the `create-dispatch` project, it creates project skeletons from `template/`
- `/alt/integration` (aws access via mise): a project created from `create-dispatch`; we edit and iterate on THIS repo, and
integrate ("port back") changes back into `/workspace/template/` once we verify they work.

### Workflow conventions
Expand All @@ -80,11 +80,11 @@ integrate ("port back") changes back into `/workspace/template/` once we verify

### Integration cycles

Working through a change to bclaw templates (skills, policies, CFN, etc), such as implementing a proposed RFC, goes through what
Working through a change to dispatch templates (skills, policies, CFN, etc), such as implementing a proposed RFC, goes through what
is known as an "Integration Cycle". We always start a cycle by creating an integration journal and applying/testing our changes into `/alt/integration`.

Once I (and only I) confirm the changes work in the `/alt/integration` project (this requires a deploy or a possible regeneration), we can integrate our changes back into
the `create-bclaw` templates under `/workspace` and run the golden test. We can use the integration cycle journal to help us integrate our changes.
the `create-dispatch` templates under `/workspace` and run the golden test. We can use the integration cycle journal to help us integrate our changes.

#### Port-back: diff `/alt/integration` against `template/`

Expand Down Expand Up @@ -112,7 +112,7 @@ is scoped to what a generated cluster inherits from `template/`.

#### Integration cycle journal Format

To aid in porting back changes, keep a journal of issues we encountered during an integration cycle. The journal lives in the `journal:create-bclaw:` namespace on the **corkboard** (DokuWiki), as a page like `journal:create-bclaw:YYYY-MM-DD_short_title`, authored in DokuWiki syntax — Markdown renders as literal text, so use wiki markup (see the corkboard skill) — in journal-style append-only format:
To aid in porting back changes, keep a journal of issues we encountered during an integration cycle. The journal lives in the `journal:create-dispatch:` namespace on the **corkboard** (DokuWiki), as a page like `journal:create-dispatch:YYYY-MM-DD_short_title`, authored in DokuWiki syntax — Markdown renders as literal text, so use wiki markup (see the corkboard skill) — in journal-style append-only format:

- `====== Title ======` — short descriptive title (page H1)
- `**Date:**` — date (ISO format)
Expand All @@ -121,7 +121,7 @@ To aid in porting back changes, keep a journal of issues we encountered during a

ONLY add issues, do not talk about plans or implementation details (the rfc is for that, just link to it).

Once the port-back is complete and the golden test passes, **set the journal's status to `Done` and leave it in place** — it now lives permanently in the `journal:create-bclaw:` namespace as a record of the cycle, so do not delete it.
Once the port-back is complete and the golden test passes, **set the journal's status to `Done` and leave it in place** — it now lives permanently in the `journal:create-dispatch:` namespace as a record of the cycle, so do not delete it.

## Tool Versions

Expand Down
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,18 @@
# Changelog

## [1.1.0] - 2026-08-15

### Summary

The product is renamed: the npm package is now `@boldblackai/create-dispatch` (the GitHub repo becomes `boldblackai/create-dispatch`; the old URL redirects). The generator's rename token is now `dispatch` — `npx @boldblackai/create-dispatch <name>` produces a skeleton with the SSM namespace `/dispatch/`, KMS alias `alias/dispatch-ssm`, and the `setup-dispatch` / `manage-dispatch` / `teardown-dispatch` skills. The advertised npm-init shorthand is corrected to `npm init @boldblackai/dispatch <name>` (npm prepends `create-` itself; the previous `@boldblackai/bclaw` line resolved to the old package). Already-deployed agents are **not** affected — renames apply to new generations only; existing installs keep working and can migrate at any time by running `npx @boldblackai/create-dispatch <name>`.

### Changes

- 634499e chore(meta): rename package identity, release plumbing, and repo self-references
- 985b5bc feat(template): sweep rename token bclaw → dispatch across template/
- 9469a8e feat(cli,generator): rename rename-token and CLI identity bclaw → dispatch
- 9db5e0d test: sweep golden test tokens bclaw → dispatch

## [1.0.2] - 2026-08-01

### Summary
Expand Down
30 changes: 15 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,33 +1,33 @@
# @boldblackai/create-bclaw
# @boldblackai/create-dispatch

Create a repository for your own bclaw, deployed to your own AWS account.
Create a repository for your own dispatch agent, deployed to your own AWS account.

## What is a bclaw?
## What is a dispatch agent?

bclaw is short for "**B**usinessClaw": an opinionated deployment of [hermes-agent](https://hermes-agent.nousresearch.com/) configured as a
A dispatch agent is an opinionated deployment of [hermes-agent](https://hermes-agent.nousresearch.com/) configured as a
long-running ["claw"](https://www.cnet.com/tech/services-and-software/claw-ai-explainer-openclaw-nvidia/) within your Slack workspace.

Create, customize and deploy as many as you'd like. Each generated bclaw repository corresponds to one specific long-running agent and Slack application/user.
Create, customize and deploy as many as you'd like. Each generated repository corresponds to one specific long-running agent and Slack application/user.

For example, you could generate a `@swe-pal` for a "Devin" type experience: code reviews, pull requests, etc. Or, a `@reportclaw` that posts reports at scheduled times to configured channels.
For example, you could generate a `@swe-pal` for a "Devin" type experience: code reviews, pull requests, etc. Or, a `@reporter` that posts reports at scheduled times to configured channels.

## How it works

1. Generate your bclaw repository
1. Generate your dispatch agent repository

npx @boldblackai/create-bclaw swe-pal
npx @boldblackai/create-dispatch swe-pal

2. Follow the instructions in the README to create the IAM user and policy to get the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` for `.env`. This also
walks you through creating and installing the Slack app into your workspace to get the `SLACK_APP_TOKEN` and `SLACK_BOT_TOKEN` you'll need later.

3. The generated repository is a set of skills, so open up `swe-pal` in your favorite harness ([Pi](https://boldblackai.github.io/harness/agents/pi/), [Hermes](https://boldblackai.github.io/harness/agents/hermes/), [OpenCode](https://boldblackai.github.io/harness/agents/opencode/))

4. Run the `/setup-bclaw` skill. This will prompt you for an inference provider, it supports [OpenRouter](https://openrouter.ai/), [ZAI](https://z.ai/subscribe), and [Anthropic](https://www.anthropic.com/) out of the box, but trivial
4. Run the `/setup-dispatch` skill. This will prompt you for an inference provider, it supports [OpenRouter](https://openrouter.ai/), [ZAI](https://z.ai/subscribe), and [Anthropic](https://www.anthropic.com/) out of the box, but trivial
to use any that [hermes-agent already supports](https://hermes-agent.nousresearch.com/docs/integrations/providers/).

5. To manage it (update running image version, update skills/SOUL.md, etc) you can use the `/manage-bclaw` skill.
5. To manage it (update running image version, update skills/SOUL.md, etc) you can use the `/manage-dispatch` skill.

6. To uninstall it, run the `/teardown-bclaw` skill.
6. To uninstall it, run the `/teardown-dispatch` skill.

## What you get

Expand All @@ -40,9 +40,9 @@ to use any that [hermes-agent already supports](https://hermes-agent.nousresearc
## Usage

```bash
npx @boldblackai/create-bclaw <name>
npx @boldblackai/create-dispatch <name>
# or equivalently
npm init @boldblackai/bclaw <name>
npm init @boldblackai/dispatch <name>
```

If no name is given (and stdin is a TTY), you'll be prompted for one.
Expand All @@ -60,7 +60,7 @@ into the generated claw (notably the deployer IAM policy's `kms:ViaService`,
which is a static JSON that can't use CloudFormation's `${AWS::Region}`):

```bash
npx @boldblackai/create-bclaw <name> --region us-west-2
npx @boldblackai/create-dispatch <name> --region us-west-2
```

`--region` must match `^[a-z]{2}(-gov)?-[a-z]+-[0-9]+$` (any AWS region,
Expand All @@ -72,7 +72,7 @@ is a TTY you'll be prompted; otherwise the default is used silently.
- `--region <region>` — AWS region to bake into the claw (default `us-east-1`). Substituted into the deployer IAM policy's `kms:ViaService` so the claw works in that region.
- `--force` — generate into a non-empty target directory, merging with existing files (default: refuse).
- `--version`, `-V` — print the version.
- `--help`, `-h` — show help.
- `--help`, `-h` — show this help.

## Development

Expand Down
12 changes: 6 additions & 6 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
{
"name": "@boldblackai/create-bclaw",
"version": "1.0.2",
"description": "CLI to generate bclaw repositories",
"name": "@boldblackai/create-dispatch",
"version": "1.1.0",
"description": "CLI to generate dispatch agent repositories",
"type": "module",
"publishConfig": {
"access": "public"
},
"bin": {
"create-bclaw": "dist/cli.js"
"create-dispatch": "dist/cli.js"
},
"packageManager": "pnpm@11.9.0",
"files": [
Expand Down Expand Up @@ -45,7 +45,7 @@
"license": "MIT",
"repository": {
"type": "git",
"url": "git+https://github.com/boldblackai/create-bclaw.git"
"url": "git+https://github.com/boldblackai/create-dispatch.git"
},
"homepage": "https://bclaw.sh"
"homepage": "https://dispatch.boldblack.ai"
}
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,15 @@ Related RFC: none (journal-only cycle).

## Goal

Tighten two areas of `template/bclaw-cfn-exec-policy.json`:
Tighten two areas of `template/dispatch-cfn-exec-policy.json`:

1. **`ECSWrite`** — the `Resource` array ends with `"*"`, which supersedes the
three specific ARNs above it, so `ecs:DeleteCluster` (and every other action
in the statement) is granted on **any** ECS resource in the account. The
AWS service-authorization reference shows 6 of the 7 actions support
resource-level perms; only `DeregisterTaskDefinition` requires `*`. Fix:
split into `ECSWriteScoped` (the 6 actions on the existing
`cluster/bclaw` / `service/bclaw/*` / `task-definition/bclaw:*` ARNs, **no
`cluster/dispatch` / `service/dispatch/*` / `task-definition/dispatch:*` ARNs, **no
trailing `*`**) + `ECSWriteGlobal` (`DeregisterTaskDefinition` alone on `*`).

2. **`EC2NetworkingCreate`** — all 6 creates + a broad `CreateTags` on `*`
Expand Down
Loading