create-bc

name	create-bc
description	Create a new Bounded Context from scratch — scaffold, remote, manifest registration, and brokered launch — as the lead shop

Creating a BC From Scratch

Overview

This skill is the lead shop's procedure for standing up a brand-new Bounded Context: scaffold the repository, create and push its remote, register it in the fleet manifest, and launch it onto the shop network with credentials brokered through agent-vault. The launch leg itself is owned by the bring-up-bc skill; this skill cross-references it rather than duplicating it.

This is the proven create-a-BC procedure distilled from standing up real BCs. The full scaffold-to-repo-to-launch flow is experimental and not yet verified end-to-end — see the experimental-honesty section. As you run it, narrate each step to the user and confirm with them as you proceed.

Procedure

1. Scaffold the new BC

Scaffold the new BC repository from the canonical templates:

shop-templates bootstrap --shop-type bc --shop-name <product>-<target> --target <path>

shop-templates bootstrap --shop-type bc writes the BC's CLAUDE.md, the typed .claude/ files, the role templates, and pours the canonical BC skill tree into .claude/skills/. The --shop-name is the BC's canonical shop-identity slug.

2. Create the remote and push

Create the GitHub remote and push the scaffolded repo:

gh repo create <org>/<bc-name> --source . --remote origin --push

Prompt the user for the GitHub org/owner and for the public/private visibility — do not hardcode them. Different products live under different GitHub orgs, and visibility is a per-product policy call. Ask the user which org/owner to create the repo under and whether it should be public or private, then pass their answers to gh repo create (--public or --private). After the repo is created, push the scaffold so the launcher can pull it.

3. Register the BC in the fleet manifest

Register the new BC in bc-manifest.yaml so the launcher knows about it:

bc-container manifest add <bc-name> --repo-url <url> ...

bc-container manifest writes the BC's entry into bc-manifest.yaml (the fleet's source of truth for which BCs exist and how to launch each). Until the BC is registered here, bc-container launch cannot find it.

4. Launch the BC (see bring-up-bc)

Launch the registered BC with bc-container launch and the brokered flags:

bc-container launch <bc-name> \
  --repo-url <url> \
  --image <registry>/bc-base:v0.3.1 \
  --network <product>-net \
  --agent-vault-broker <product>-agent-vault \
  --env-file .env

• --repo-url — the GitHub URL the launcher clones the BC from.
• --image — pin to bc-base v0.3.1+, never :latest. A floating :latest tag makes launches non-reproducible and silently drifts the base.
• --network — the product's shop network so the BC reaches postgres and the bus.
• --agent-vault-broker — the broker that injects real credentials on the wire.
• --env-file — the env file carrying the BC's launch-time config.

For the launch mechanics — exporting BCLAUNCHER_HOST_HOME for the bind-mounted-home devcontainer and verifying the BC reaches online via shop-msg bc-status — follow the bring-up-bc skill. This skill hands the launch leg off to bring-up-bc; do not re-implement it here.

Gotchas

These are the misses that cost the most time when standing up a BC:

• AGENT_VAULT_VAULT is the plain <product>, not <product>:proxy. The vault name is the bare product slug; appending :proxy points the broker at a vault that does not exist and every brokered call 401s.
• Credential keys are SCREAMING_SNAKE. Every brokered credential key in the env file is SCREAMING_SNAKE_CASE (e.g. AGENT_VAULT_TOKEN, AGENT_VAULT_ADDR). A lower-cased or hyphenated key is not matched by the broker.
• bc-base is pinned to v0.3.1+. Use a concrete bc-base tag at v0.3.1 or newer for --image; never :latest.

Experimental honesty

The full scaffold-to-repo-to-launch flow is experimental and has not yet been verified end-to-end. Treat each leg as something to confirm, not assume: narrate what you are about to do, run it, show the user the result, and confirm with the user before moving to the next leg. If a leg fails, stop and surface it rather than pressing on — a half-registered or half-launched BC is harder to recover than a clean restart.

Definition of Done

• The BC repo is scaffolded, has a remote under the user-chosen org/visibility, and is pushed.
• The BC is registered in bc-manifest.yaml via bc-container manifest.
• The BC launched via bc-container launch and reached online per the bring-up-bc skill's shop-msg bc-status check.
• You narrated each leg and confirmed it with the user as you went.