basic BMAD setup

.agents/skills/bmad-toolsmith/shapes/agent/assets/SKILL-template.md

@@ -0,0 +1,28 @@
+---
+name: {skill}
+description: '{description}'
+---
+# {name} — {title}
+
+{persona-paragraph}
+
+## Conventions
+
+- `{project-root}` is the nearest folder containing `_bmad/`, from the working directory upward. `{skill-root}` is this skill's folder.
+- Bare paths such as `references/<capability>.md` resolve from `{skill-root}`.
+{conventions}
+
+## On activation
+
+1. Resolve the agent block: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key agent`. Script not found: BMad is not set up here; offer the `bmad` skill's setup, installing `bmad` first if needed (`npx skills add bmad-code-org/BMAD-METHOD --skill bmad`), then run it again. Any other failure: use `{skill-root}/customize.toml` as shipped and say the overrides were not applied.
+2. Run each entry of `{agent.activation_steps_prepend}` in order.
+3. Adopt the persona: `{agent.role}`, `{agent.identity}`, `{agent.communication_style}`, `{agent.principles}`. Stay {name} until dismissed; the persona carries into every skill you invoke.
+4. Load `{agent.persistent_facts}`: entries prefixed `file:` are paths or globs under `{project-root}` to read; the rest are facts verbatim.
+5. Load config: `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core.output_folder --key core.active_initiative{config-keys}`. {config-use}
+6. Greet in one line, led by `{agent.icon}`, and keep that prefix on every message. The `bmad` skill answers questions about BMad itself.
+7. Run each entry of `{agent.activation_steps_append}` in order.
+8. Dispatch. When the request names what the user wants, run the matching `{agent.menu}` item without showing the menu. Otherwise render the menu as a numbered table of `Code` and `Description`, stop, and wait. A `skill` item that is not installed: say so and offer `npx skills add <repo> --skill <name>`, the repo being that entry's `source` in `{skill-root}/bmod.toml`. A request that fits nothing on the menu is a conversation.
+
+## How {name} works
+
+{standing-rules}

.agents/skills/bmad-toolsmith/shapes/agent/assets/capability-template.md

@@ -0,0 +1,13 @@
+# {Capability}
+
+The outcome is {the artifact or change that exists when this is done}. {Who or what acts on it} does so without this conversation in the room, so it must {the bar: what has to be true of it for them to act}.
+
+## What you cannot infer
+
+- {An owner or domain specific the persona does not already carry.}
+- {Wiring: a path, a format, a tool, a config value read on activation.}
+- {A rule with a real consequence behind it, and the consequence.}
+
+## Hand back
+
+{What the user sees when it is done: where the output is, the one decision left to them, what to try next.}

.agents/skills/bmad-toolsmith/shapes/agent/assets/customize-template.toml

@@ -0,0 +1,57 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# {name}, the {title}, is the hardcoded identity of this agent.
+# Customize the persona and menu below to shape behavior without
+# changing who the agent is. Override files:
+#   {project-root}/_bmad/custom/{skill}.toml       (team)
+#   {project-root}/_bmad/custom/{skill}.user.toml  (personal)
+
+[agent]
+# non-configurable skill frontmatter, create a custom agent if you need a new name/title
+name = "{name}"
+title = "{title}"
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, principles, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+icon = "{icon}"
+
+# Steps to run before the standard activation (persona, config, greet).
+activation_steps_prepend = []
+
+# Steps to run after greet but before dispatch.
+activation_steps_append = []
+
+# Standing context for the whole session: literal sentences, or `file:` paths and globs
+# under {project-root}, e.g. "file:{project-root}/docs/standards.md".
+persistent_facts = []
+
+role = "{role}"
+identity = "{identity}"
+communication_style = "{communication_style}"
+
+# The agent's value system. Overrides append to defaults.
+principles = [
+  "{principle}",
+  "{principle}",
+  "{principle}",
+]
+
+# Capabilities. Each item has exactly one of `skill` (an installed skill, by name) or
+# `prompt`. Overrides merge by `code`: a matching code replaces the item, a new code appends.
+
+[[agent.menu]]
+code = "{code}"
+description = "{menu-description}"
+skill = "{installed-skill}"
+
+[[agent.menu]]
+code = "{code}"
+description = "{menu-description}"
+prompt = "{One or two sentences that are the whole instruction, when the persona and intent suffice.}"
+
+[[agent.menu]]
+code = "{code}"
+description = "{menu-description}"
+prompt = "Read `{skill-root}/references/{capability}.md` fully and follow it."

.agents/skills/bmad-toolsmith/shapes/agent/assets/sample-capability.md

@@ -0,0 +1,14 @@
+# Release notes
+
+The outcome is the entry for the version being released in `CHANGELOG.md`. A user upgrading reads it without the commit log in front of them, so every line names what changed for them, never the commit, and anything that needs a step from them sits under its own `Upgrade` heading at the top.
+
+## What you cannot infer
+
+- The range is the last `v*` tag to `HEAD` unless the user names one.
+- Groups are Added, Changed, Fixed, Removed, in that order; an empty group is left out. Dependency bumps are one line together.
+- Commits typed `chore`, `ci` and `test` are left out unless they change what a user sees.
+- A commit whose effect you cannot tell from its message is one question to the user, listing the commits, not a guess: a wrong line here reaches every user of the release.
+
+## Hand back
+
+Show the entry, name the commits you left out and why, and offer to tag.

.agents/skills/bmad-toolsmith/shapes/agent/shape.md

@@ -0,0 +1,33 @@
+# Shape: agent
+
+An agent is a persona with a menu: one character the user talks to, whose capabilities are installed skills or prompts inside it. Smithy is one. Reach it when the user wants someone to talk to (a name, a role, a way of working) who does several related things. One job, no persona: a plain skill. Must remember between sessions: `shapes/memory-agent/shape.md`.
+
+## Files
+
+| File | From | Holds |
+|---|---|---|
+| `SKILL.md` | `assets/SKILL-template.md` | description, persona paragraph, conventions, eight activation steps, standing rules |
+| `customize.toml` | `assets/customize-template.toml` | `[agent]`: identity, activation hooks, persistent facts, persona fields, `[[agent.menu]]` |
+| `references/<capability>.md` | `assets/capability-template.md` | one internal capability each, only where there is know-how to hold; `assets/sample-capability.md` is a finished one (release notes: internal, the default) |
+
+Build-time tokens: `{skill}` (folder name), `{name}`, `{title}`, `{icon}`, `{description}`, the persona and menu fields; `{project-root}`, `{skill-root}`, `{agent.*}` and config values are runtime.
+
+## Capabilities
+
+A menu item is exactly one of `skill = "<installed skill>"` or `prompt = "..."`. The prompt is either the whole instruction in a sentence or two, or `Read `{skill-root}/references/<capability>.md` fully and follow it.` when there is know-how a file has to hold. What is installed: list the folder beside `{skill-root}` (the skills root); `uv run {project-root}/_bmad/scripts/roster.py --skill {skill-root} --project-root {project-root}` names agents and their modules. For each thing the agent does:
+
+- An installed skill when one does the job; ship records it.
+- Inline when the persona plus a sentence of intent is all it takes. The user lists it so the menu shows what is on offer, not because the model needs teaching; a capability file for it would be padding.
+- A capability file otherwise, to the canon: outcome, consumer, bar, non-inferables, nothing more; the persona supplies voice and route. The canon applies to each file as it does to a skill, and the description target to the agent's description. One big enough for its own skill is a new build after this ships: note it in the read-back and as a `recommended_skills` gap in `bmod.toml`.
+- Never copy another skill's content in; name it.
+- Changing the persona or the menu is the `bmad-customize` skill's job, never a capability that writes `_bmad/custom/`; put `skill = "bmad-customize"` on the menu when the user wants it offered.
+
+## Persona
+
+The leanness bar stops at the persona. `identity`, `communication_style` and `principles` are what the agent judges by when no capability fits; cutting them makes a worse agent. Write them, and the persona paragraph in `SKILL.md`, in its own voice, one or two sentences each: an identity with a concrete reference, a style with a simile, three to five principles, each a stance.
+
+The description follows the canon's rule for agents: "<Name> the <Title> <short summary>. Use when the user asks to talk to <Name> or says <the phrases and concepts of each internal capability>." The eight activation steps come over whole; edit only the config keys. "How <Name> works" is only for rules every capability obeys.
+
+## Roster
+
+An agent joining a module gets a `[[members]]` entry in the record's `roster.toml`: `code` and `skill` (both the skill name), `name`, `icon`, `title`, `persona` (how they think, then how they speak; two sentences). Draft it; the module shape or package mode writes it.