basic BMAD setup

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

@@ -0,0 +1,19 @@
+---
+name: {name}
+description: '{description}'
+---
+# {title}
+
+{purpose: one paragraph. The stance the skill acts from, the outcome it produces, who consumes that output, and what must be true of it for them to act. Said once; nothing below restates it.}
+
+## On activation
+
+{Keep only the steps this skill needs. A skill outside BMad keeps none and this section goes.}
+
+1. Config: `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core.output_folder --key core.active_initiative`. 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. {Add `--key modules.<code>.<key>` for each module setting this skill reads.}
+2. Customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow`; on any other failure read `{skill-root}/customize.toml` and use its defaults. Run each entry of `{workflow.activation_steps_prepend}`, hold every entry of `{workflow.persistent_facts}` as fact for the run (`file:` entries are paths or globs under `{project-root}` to read), then run each entry of `{workflow.activation_steps_append}`.
+3. Output: the document lands at `{output_folder}/{active_initiative}/{type}-{slug}/{type}-{slug}.md`, dropping `/{active_initiative}` when unset. `{slug}` is what the document is about, in kebab-case.
+
+## {body}
+
+{What the skill does, as outcomes with their reason. Exact procedure only where a wrong move costs something. Name a reference when its branch is reached, never ahead of it: "read `references/<topic>.md` fully and follow it". A skill with `customize.toml` runs `{workflow.on_complete}` last. When users will change a value it reads, one line: "To change <what>, invoke the `bmad-customize` skill and name `workflow.<key>`; if it is not installed, offer `npx skills add bmad-code-org/BMAD-METHOD --skill bmad-customize`."}

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

@@ -0,0 +1,29 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Customization surface for {name}.
+# Team overrides:     {project-root}/_bmad/custom/{name}.toml
+# Personal overrides: {project-root}/_bmad/custom/{name}.user.toml
+#
+# Merge rules: scalars override, arrays append, tables merge key by key,
+# arrays of tables merge by `code` or `id`.
+
+[workflow]
+
+# Instructions run before config is loaded.
+activation_steps_prepend = []
+
+# Instructions run after activation, before the work begins.
+activation_steps_append = []
+
+# Standing context for the whole run: literal sentences, or `file:` paths and
+# globs under {project-root} whose contents are loaded as facts.
+persistent_facts = []
+
+# Run after the output has been delivered. A string or an array of strings;
+# empty for none.
+on_complete = ""
+
+# Keep the two below only when the skill writes an artifact: where runs land,
+# and the folder and file name inside it. {slug} is set at run time.
+{type}_output_path = "{output_folder}/{active_initiative}"
+run_folder_pattern = "{type}-{slug}"

.agents/skills/bmad-toolsmith/shapes/plain-skill/assets/sample-skill/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: decision-record
+description: 'Writes an architecture decision record (ADR). Use when the user says "record this decision", "write an ADR" or "we decided X, capture it".'
+---
+# Decision record
+
+You turn a decision the team has reached into a record a newcomer can read a year later and understand why the system is the way it is. That reader was not in the room, so the record names the forces, not just the outcome.
+
+## On activation
+
+1. Config: `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core.output_folder --key core.active_initiative`. 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.
+2. The record lands at `{output_folder}/{active_initiative}/adr-{slug}/adr-{slug}.md`, dropping `/{active_initiative}` when unset. `{slug}` is the decision in kebab-case.
+
+## Writing the record
+
+Mine the conversation first: the decision, the options and the reasons are usually already there. Ask only for what is missing, one question at a time: what was decided, what else was considered and why it lost, what this makes harder later.
+
+Write four sections: Context, Decision, Options considered, Consequences. Each option gets one line on why it lost. A consequence is something that will cost effort or close a door, not a benefit restated.
+
+Show the draft and wait. On approval, write the file and tell the user the path.

.agents/skills/bmad-toolsmith/shapes/plain-skill/shape.md

@@ -0,0 +1,25 @@
+# Shape: plain skill
+
+A `SKILL.md` an agent reads and follows, with references, scripts or assets only where the body would otherwise have to carry them. Most skills are this one. The conversation has reached it when the read-back names no persona or menu, no steps a team must swap, and work that is judgment rather than a deterministic transform. It is also where a build lands when no signal points elsewhere.
+
+## Files
+
+| File | From | When |
+|---|---|---|
+| `SKILL.md` | `assets/SKILL-template.md` | always |
+| `references/<topic>.md` | by hand | a branch the body only names, loaded when reached |
+| `scripts/<name>.py`, `assets/<file>` | by hand | a fragile sequence, or a template the skill emits |
+| `customize.toml` | `assets/customize-template.toml` | the user wants team customization |
+| `bmod.toml` | the scaffold, `init_skill.py --bmod <record> --source <update_source>`; `ecosystem.md` adds its dependency lists | the skill joins a module |
+
+`assets/sample-skill/` is a finished plain skill at the size to aim for. Read it before drafting.
+
+## Rules
+
+- Frontmatter is `name` and `description` only. Every "when to use" lives in the description, so the body never repeats it.
+- The body stays well under 500 lines. A reference is one level deep: `SKILL.md` to reference, never reference to reference. A reference over about 100 lines opens with a short table of contents. Several operating modes get one reference each; one thing to do gets no router. No README, changelog or install notes inside the skill.
+- Three degrees of freedom: prose where the agent judges, a parameterised pattern where a preferred way exists, a script where the sequence is fragile or every run would rewrite the same helper. A script handles its own errors and says whether the agent runs it or reads it.
+- Inside BMad, a skill that writes a document puts it at `{output_folder}/{active_initiative}/<type>-<slug>/<type>-<slug>.md`, dropping `/{active_initiative}` when unset, both values from `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core.output_folder --key core.active_initiative`. A skill in a module reads its own settings as `--key modules.<code>.<key>` in the same call. It resolves the `[workflow]` table with `resolve_customization.py` only when it ships a `customize.toml`.
+- A skill outside BMad has none of that: plain paths, no `_bmad/` scripts, no `customize.toml`, no `bmod.toml`. The template's activation section goes.
+- `customize.toml` carries `activation_steps_prepend`, `activation_steps_append`, `persistent_facts` and `on_complete`, plus `<type>_output_path` and `run_folder_pattern` when the skill writes an artifact. Nothing else goes in until a team asks for it.
+- Changing a value is the `bmad-customize` skill's job, never the skill's own: no save command, no override writer, no merge script, no fallback reader for when `_bmad/` is absent. When users will change a value, one line in the body says to invoke `bmad-customize` naming the key, and offers `npx skills add bmad-code-org/BMAD-METHOD --skill bmad-customize` when it is not installed.