basic BMAD setup

.agents/skills/bmad-toolsmith/modes/convert.md

@@ -0,0 +1,27 @@
+# Convert
+
+A skill, prompt, custom command, Cursor rule, GPT or system prompt from another tool becomes a BMad skill. Its outcome: the same know-how as the smallest BMad skill, in the shape it needs.
+
+## Read and extract
+
+Read the source whole. Pull out the outcome it produces, who consumes it, the triggers (when the author meant it to fire), the know-how a model would not have, and any scripts. Note what it depends on from its host: tools, variables, other files.
+
+## Drop
+
+The host tool's mechanics: its frontmatter keys (`globs`, `alwaysApply`, `argument-hint`, `model`), slash-command syntax and `$ARGUMENTS`, GPT conversation starters, knowledge-file uploads. And the instructions the model already follows unasked: be helpful, think step by step, format as markdown. The canon's core test decides; keep only what prevents a failure.
+
+## Frontmatter
+
+The agentskills.io spec allows `name` and `description`, and optionally `license`, `compatibility`, `metadata` and `allowed-tools`. BMad uses the first two only: `description` is the whole trigger and `allowed-tools` is a host concern.
+
+## Shape
+
+Most sources land on a plain skill. A persona with a menu of things it does lands on an agent; a source whose scripts do most of the work on a script utility; a set of related commands on a module. Say the shape and the one line of why.
+
+## In place
+
+When the source is already a skill folder and the user wants it brought to BMad rather than rebuilt beside it, work in that folder. The read-back lists what will change and nothing is touched before approval: the name, kept unless the user wants their prefix on it; the description, rewritten to the canon; paths and config reads, brought to `lenses/standards.md`; `bmod.toml` with both tables when the user wants a single-skill module, from `shapes/single-skill-module/shape.md`; what is dropped, by file. Then `ship.md`, where the lenses run over the result. Discovery itself is skipped; its five questions are answered by the skill as it stands.
+
+## Hand-off
+
+Load `discover.md` with the extraction as the mined input: discovery confirms the outcome, consumer and trigger phrases from it and asks only for what the source never said, usually the consumer, the near misses, and the name, since a source is usually named for its host. From the read-back on, the approach is lean. Leave the source untouched; the user may still run it where it lives.

.agents/skills/bmad-toolsmith/modes/edit.md

@@ -0,0 +1,23 @@
+# Edit
+
+Change a skill that exists, built by Smithy or not. Its outcome: the change the user asked for, applied to the canon's standard, with nothing else disturbed.
+
+## Read
+
+Set `{target}` to the skill folder. Read `SKILL.md` and only the files the change touches; the rest stays unread so it stays unchanged.
+
+## Agree the change
+
+One read-back, then wait: what changes, what stays, whether the shape changes (a menu added to a plain skill, memory added to an agent), whether the description changes. A description change is a trigger change; say so.
+
+## Rebuild instead
+
+When the user wants to rethink the skill from its outcomes rather than adjust it, that is a build: say so and load `discover.md` with the old skill as the mined input. Its files are reference material, not the starting point.
+
+## Apply
+
+Make the change to `canon.md` and cut any line the change makes dead. Fit the existing voice and structure, so a reader sees no seam. When the change touches the description or adds a capability, write or extend `{target}/evals/triggers.json` with queries for the new ground and near misses beside it, so ship's trigger eval covers what changed. For a rendered skill, edit the sources (`workflow.md`, `step-*.md`, `customize.toml`), never the rendered snapshot. For an agent, a new capability is a `references/<capability>.md` or a named skill, added to the menu.
+
+## Then
+
+Load `ship.md`.

.agents/skills/bmad-toolsmith/modes/migrate.md

@@ -0,0 +1,31 @@
+# Migrate
+
+Convert an old-format module into a bmod in place. The old format is a `<code>-setup` skill, or for one skill a `module-setup.md` in its assets, carrying `module.yaml`, `module-help.csv` and merge scripts that wrote `_bmad/config.yaml` and `_bmad/module-help.csv`. The new format is a record `bmad` reads: `bmod.toml`, `help/`, `roster.toml`. Nothing is deleted before the user approves the whole plan.
+
+## Read everything
+
+`{target}` is the module folder: the one holding the member skills and the setup skill, or for a one-skill module that skill's folder. Run `uv run {skill-root}/scripts/scan_legacy_module.py {target}` and read its JSON: `module` (code, version, greeting, agents), `config_keys` (key, prompt, default, user_setting, kind, unconvertible reasons), `help_rows`, `skills`, `legacy_reads` (every config read by skill, path and line), `setup_skill`, `files_to_delete`. Ask the user only for `update_source`, the pushed `github:<owner>/<repo>` or `github:<owner>/<repo>/<path>`. `{bmad_version}` is the `version` in the `bmod-core-tools` record installed beside `{skill-root}`; ask when it is not installed.
+
+## The plan
+
+Show it whole, as tables, then wait for a yes:
+
+Files, old to new:
+
+- `files_to_delete` (the setup skill or `module-setup.md`, `module.yaml`, `module-help.csv`, the merge scripts): deleted. `retired.toml` lists `setup_skill` under `removed` when there was one.
+- `module` to `bmod-<code>/bmod.toml`: `code` and `version` as scanned; `update_source` from the user; `skills` as scanned; `post_install_message` from `greeting`; one `[[bmod.config_questions]]` per entry of `config_keys`, `scope = "user"` where `user_setting` was true. `agents` to `roster.toml`: `code`, `skill`, `name`, `icon`, `title`, and `description` as `persona`.
+- `help_rows` to `help/help.md`: one entry per skill from its rows, what it gives and when to recommend it; preceded-by and followed-by become what to offer next. A skill with many rows gets a `help/<skill>.md` topic named in `help.md`.
+- Each skill: a `bmod.toml` with `[skill]` (`bmod`, `source`) and `scripts` when it ships any.
+- A folder with one skill: the single-skill shape, both tables in that skill's `bmod.toml` and `help/help.md` beside it, no `bmod-<code>/`.
+
+Config keys, old to new, one row per `legacy_reads` entry: every read becomes `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key ...`. `output_folder` is `core.output_folder`; reads of `user_name`, `communication_language` and `document_output_language` go, since v7 has no such keys; a module key is `modules.<code>.<key>`. A key equal to the code or starting with `<code>.` must be renamed; offer to drop a module name repeated inside a key. Fallbacks to the legacy per-module file go.
+
+Cannot convert, listed plainly from `unconvertible`, with what it means for the user: a select question becomes one string (put the options in the prompt and the default option in `default`, or drop it); validation, directories and post-install notes have no equivalent, so the skill handles them or they go; headless and inline-argument setup is gone because `bmad setup` has none; existing answers in `_bmad/config.yaml` are not carried, so `bmad setup <code>` will ask again.
+
+## Convert
+
+On approval: load `shapes/multi-skill-module/shape.md` or `shapes/single-skill-module/shape.md` and emit from its templates; rewrite every config read as planned, and remove each skill's step that ran the setup skill or loaded `module-setup.md` when unregistered; write `retired.toml`; then delete `files_to_delete`, and nothing else.
+
+## Check
+
+Run the checks of `modes/validate.md`: `validate_manifests.py` when the result sits in a repository with `skills/*/bmod.toml`, and `init_skill.py --check` and `scan_paths.py` on each skill. `scan_paths.py` also catches an old-format name the rewrite missed. Fix until clean, then load `ship.md`.

.agents/skills/bmad-toolsmith/modes/package.md

@@ -0,0 +1,26 @@
+# Package
+
+Wrap one skill or several that already exist into a module, so `bmad` sets them up, answers help about them and checks them for updates. The outcome: a record, a `[skill]` file in each member, and skills that read their config through it, all approved before anything is written.
+
+## Read what exists
+
+The user points at a folder of skills or at one skill. Run `uv run {skill-root}/scripts/prepass.py <skill>` for each and take its facts: shape hint, description length and `Use when`, customize and scripts, path findings. Read raw files only for what it does not give: the `[agent]` block in `customize.toml`, each path or value the skill hardcodes or reads from config, and the skills it invokes. A skill whose `bmod.toml` already carries `[skill]` belongs to another module: it can be a dependency here, not a member. Say so.
+
+## Propose
+
+Show one plan and wait for a yes or changes:
+
+- The shape: one skill with its own answers is the single-skill module; two or more, or a skill joining an existing record, is the multi-skill module. Load the shape file at the write step, not now.
+- The code: short, lowercase, the user's org or the module's purpose, and not a module the user already has. Members carry it as prefix (`acme-...`, agents `acme-agent-...`); `bmad-` belongs to the bmad-code-org. Offer a rename for a member that lacks it, say that renaming changes how the skill is invoked, and let the user decline.
+- `update_source`: the pushed repo, `github:<owner>/<repo>` or `github:<owner>/<repo>/<path>`; ask when it is not in the conversation.
+- The config questions, one per path or setting the skills hardcode or share, each with `key`, `prompt`, `default` and `scope`. A value several skills read the same way is one question.
+- The roster entries for agents, from each `customize.toml` `[agent]`.
+- `help.md` drafted from each description: what it gives, when to recommend it, what to offer next.
+- Dependencies: `bmad` required at the installed `bmod-core-tools` version; skills a member invokes as required or recommended, in the record when module-wide, in the member otherwise.
+- The files it will write and the config reads it will change, by file.
+
+## Write
+
+On approval set `{target}`: the record folder `bmod-<code>/` for a multi-skill module, the skill folder for a single-skill one. Load `shapes/single-skill-module/shape.md` or `shapes/multi-skill-module/shape.md` and emit its files. Then rewrite each skill's config reads to `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key modules.<code>.<key>`, one call per skill with every key it needs, dropping the hardcoded value each replaces. Touch nothing else in the skills.
+
+Load `ship.md`.

.agents/skills/bmad-toolsmith/modes/review.md

@@ -0,0 +1,15 @@
+# Review
+
+Advice, not a gate. Its outcome: a report of findings on `{target}` ordered by severity, each with its fix, and the user choosing which to apply.
+
+## Pre-pass
+
+`uv run {skill-root}/scripts/prepass.py {target}`: one JSON with tokens per file, a shape hint, scripts with their headers and tests, description length, and path and script findings. Every lens reads it first, then every prompt file the skill has; the lenses judge the whole skill, not the entry alone.
+
+## Lenses
+
+Launch one subagent per lens, in parallel: `lenses/lens-architecture.md`, `lenses/lens-determinism.md`, `lenses/lens-leanness.md`, `lenses/lens-customization.md`, `lenses/lens-trigger.md`. Each gets the pre-pass JSON, `{target}`, its lens file, `lenses/lens-contract.md` and `lenses/standards.md`, and returns findings JSON per the contract. If subagents are unavailable, run the lenses inline one at a time and say so.
+
+## Findings
+
+Merge the lens returns, drop duplicates (same file, same place, same point), order by severity. Give the findings in chat, each in two lines: what and where, then the fix; one line per lens with its verdict above them. Write the same list as markdown to `{reports_folder}/<YYYYMMDD-HHMMSS>-<skill>-review.md` so the user can work from it later; no other format. A leanness finding that proposes a smaller version is a hypothesis, not a verdict: offer a variant eval through the `bmad-eval` skill with the smaller version as the variant, so the cut is measured before it is made. Offer edit mode (`modes/edit.md`) for the findings the user wants applied; apply none unasked.

.agents/skills/bmad-toolsmith/modes/validate.md

@@ -0,0 +1,26 @@
+# Validate
+
+Check a skill or a module and report what would stop it installing, loading or firing, with the fix for each. This mode writes nothing.
+
+## Target
+
+A path to a skill, a record folder, or a repository. A folder holding `module.yaml`, `module-help.csv` or a `<code>-setup` skill is the old module format: report one line, "old-format module: convert it with the migrate mode", and stop, because none of the checks below apply to it.
+
+## Checks
+
+Run them all, then report; do not stop at the first failure.
+
+- In a repository with `skills/*/bmod.toml`: `uv run {project-root}/_bmad/scripts/validate_manifests.py --project-root <repo>`. It covers manifests, membership, versions, retired names, help topics and the roster, and each message names its fix.
+- For each skill: `uv run {skill-root}/scripts/init_skill.py --check <skill>` (frontmatter, name, description, `[TODO:` left behind, `bmod.toml` parses; add `--any-name` outside BMAD-METHOD) and `uv run {skill-root}/scripts/scan_paths.py <skill>` (paths that do not resolve, bare `scripts/` calls, references into another skill, old-format names). `uv run {skill-root}/scripts/scan_scripts.py <skill>` when it has scripts, then run its tests.
+- When `evals/triggers.json` exists, offer a trigger eval once and invoke the `bmad-eval` skill in trigger mode on a yes.
+
+Only what the tools do not check is yours to judge:
+
+- A record's `SKILL.md` body does anything but redirect to `bmad setup <code>`.
+- A member reads a value from config that no question in the record asks, or a question no member reads.
+- `help/help.md` tells the help agent things it cannot act on: install mechanics, manifest keys.
+- A skill's name carries `bmad-` outside BMAD-METHOD, or lacks its module's code.
+
+## Report
+
+One line per finding: file, what is wrong, the fix. Then the counts, and whether the target would install and load as it stands. Offer to fix through `modes/edit.md`; do not fix here.