Condense any input — an idea, brief, PRD, transcript, or mixed notes — into a short spec: SPEC.md plus supporting files that downstream skills build from. Also
复制下面这句话，粘贴给 Claude Code、Codex、Cursor 等 AI 编程工具，它会读取安装说明并在你确认后完成安装。
请阅读 https://ai.atlankj.com/install/asset/gh-bmad-spec-1d7d2fab82a1 ，按照其中的说明把「bmad-spec」安装到你（当前 AI 工具）中。执行前先告诉我将运行的命令和写入的位置，等我确认。
查看 AI 将读取的安装说明正在读取 GitHub 原文…
内容来自 GitHub 原始文件，由原作者维护。在 GitHub 查看
Canonical transformer for the BMad spec-kernel ecosystem. Takes any intent input — vague idea, brain dump, PRD, GDD, RFC, brief, Slack thread, customer email, meeting transcript, mockups, mixed multi-source — and produces SPEC.md carrying the five-field kernel (Why, Capabilities, Constraints, Non-goals, Success signal) plus companion files for load-bearing content that does not fit or would bloat the kernel with expansive line-item detail. Together they are the machine contract every downstream BMad skill consumes.
Multiple skills may call to update the same spec over time.
assets/spec-template.md) resolve from the skill root.{skill-root} is this skill's install dir; {project-root} is the nearest folder containing _bmad/, starting at the working dir and moving up through its parents.{workflow.<name>} resolves to fields in customize.toml.uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow.
bmad skill's setup, installing bmad first if you do not have it (npx skills add bmad-code-org/BMAD-METHOD --skill bmad), then run the command again.{skill-root}/customize.toml directly.{workflow.activation_steps_prepend}. Treat {workflow.persistent_facts} as foundational context (file: entries are loaded).uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} (merges _bmad/config.toml and the _bmad/custom/ overrides). From the merged JSON resolve {project_name}, {output_folder} (under core), and {date}.bmad-party-mode and bmad-advanced-elicitation are available for deeper exploration on any field.Run {workflow.activation_steps_append}.
Activation is complete. If activation_steps_prepend or activation_steps_append were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
The spec is always a folder named {workflow.spec_output_path}/{workflow.run_folder_pattern}, resolving by default to {output_folder}/specs/spec-{slug}/.
{slug} describes the thing being specced, not the input shape:
prd-foo-bar-2026-05-23/): inherit (foo-bar).error_code: "missing_slug".{slug} lands at the existing spec folder and updates in place, preserving capability IDs.No input. Interactive: ask the user to share a file path, paste content, explain the idea in detail, or point to a source. Headless: respond with JSON containing error_code: "insufficient_intent".
Inside the spec folder:
<spec-folder>/
SPEC.md ← uppercase, the kernel — DERIVED from .memlog.md, never hand-edited
<companion-1>.md ← optional, content-typed (e.g. glossary.md); spec-authored ones are derived too
<companion-2>.md
.memlog.md ← canonical, append-only memory; what SPEC.md is distilled from
.memlog.md is canonical — an append-only, chronological record of every decision, constraint, capability (with its stable CAP-N), assumption, open question, and bit of user direction, one line each in the order it happened, never edited or reordered. SPEC.md and every spec-authored companion are derived on each run from the memlog (the decision-of-record) plus the sources it cites for raw content — never hand-patched.
Deriving the contract from a living log instead of editing the contract in place is what lets the steps around the spec (PRD, UX, architecture, epics) run in any order and feed the same spec without merge drift: the log only accumulates, the artifact is re-rendered. So the spec is updated only by re-deriving it here — bmad-spec is its single writer; a hand-edit to SPEC.md from outside is unsupported and is overwritten on the next derive.
Writes go through the shared script — {project-root}/_bmad/scripts/memlog.py, the same location as resolve_customization.py (atomic; never read it back except to resume):
uv run {project-root}/_bmad/scripts/memlog.py init --workspace {spec-folder} --field topic="<what is being specced>" — once, at create.uv run {project-root}/_bmad/scripts/memlog.py append --workspace {spec-folder} --type <decision|constraint|capability|assumption|question|direction|note|event> --text "<one-line gist, reason included>" — as each lands.--type event entries; the memlog carries no status field.Read the input and its ancillary linked materials. If there is no input, follow the no-input branch in Workspace (ask or block). If a prior .memlog.md exists at the target folder, read it — the operation becomes an update, and the memlog (not the rendered SPEC.md) is the authority on what was decided and on capability IDs. Preserve those IDs; new capabilities get the next unused CAP-N; never reuse retired IDs. Otherwise this is a create, and the first move is memlog.py init.
When the input is structured and pre-sorted (a PRD with an addendum, a GDD, a brief produced by an upstream BMad skill), trust the authored separation: lift kernel-fitting content into SPEC.md, lift overflow into appropriately-named companions. When the input is mixed (a brain dump, a transcript, an RFC, a customer email), do the sorting yourself: walk each claim, apply the three-lens load-bearing test (Spec Law rule 7), and route to the kernel field or a companion.
Distill the input into the five-field kernel using {workflow.spec_template} as the skeleton. When input is rich, extract directly — no elicitation. When input is sparse, choose: express (best-effort distill, every gap becomes an open_questions[] entry) or guided (walk the five fields with the user one at a time). Headless defaults to express and logs the choice. Interactive asks.
A recognized domain implication the input leaves unaddressed is such a gap — name it as an open_questions[] entry (healthcare input silent on PHI/HIPAA, payments silent on PCI, control systems silent on fail-safe) and move on. Flag it; never invent the answer or coach toward it. If these dominate, the input is too thin — suggest bmad-prd.
Write lean from the first pass: every sentence must earn its place. Decoration costs tokens and dilutes downstream readers.
Log each decision, capability, constraint, and accepted change to .memlog.md as it is made — that running record is what the render reads. Because the log is append-only, a later entry supersedes an earlier one on the same point while the history stays intact. When two currently-live sources or companions disagree on the same field, or an either/or never got resolved, surface it to the user rather than silently choosing — the resolution is itself a new memlog entry.
If the input is genuinely too thin to distill (e.g. "an app for hikers" with no surrounding context), stop and suggest bmad-prd (or sibling ceremony skill). This skill distills; it does not coach.
A claim is load-bearing if any consumer (downstream skill, implementing agent, verification pass) would change a decision without it.
When load-bearing content does not fit the five-field kernel, it lives in a companion. The kernel cites it; the companion holds it. Companions are part of the contract; every consumer reads companions: in SPEC.md frontmatter to discover them. Companions follow the same lean discipline as SPEC.md (Spec Law rule 8).
Spawn a companion when the content needs more than one kernel-shape line: multi-item catalogs (per-entity matrices like archetypes, drinks, modes, routes), tables, diagrams (always), editorial voice rules, long-form reference material the kernel cites by name (glossary, brownfield notes, project conventions). Single-line decision-benders stay in Constraints; intent+success pairs stay in Capabilities. If a kernel field is starting to bullet into sub-bullets, the content has outgrown the kernel and wants a companion.
Companions are either:
glossary.md, patron-archetypes.md). bmad-spec owns them and may edit them on update operations.companions: by relative path but does NOT edit them (e.g., a DESIGN.md or EXPERIENCE.md from a UX run, an integration partner's API spec). The originating skill owns them.Two rules govern companions:
glossary.md, <entity-class>.md (e.g. patron-archetypes.md, medication-routes.md, flight-modes.md), stack.md, conventions.md, brownfield.md, architecture-diagrams.md, state-machines.md, failure-modes.md, compliance-references.md. The principle: "a reader should know what is inside before opening it." Adopted companions keep whatever name their originating skill gave them.architecture-diagrams.md), with sibling image files referenced from there.Pre-existing project-wide docs (e.g. project-context.md) that downstream needs are listed as adopted companions, never duplicated into SPEC.md or a spec-authored companion.
Every spec must satisfy these eight rules. The operation aims for them; the self-validate sweep enforces them.
intent and success. Missing either = not a capability..memlog.md.After every create or update, sweep the resulting artifact in two passes before presenting.
Pass 1 — Coherence. Judge the spec against Spec Law rules 1–6 and 8. For anything that fails or feels weak, attempt to fix it without inventing content the input did not support. Calls made without direct confirmation become assumptions[]; gaps that could not be filled become open_questions[].
Pass 2 — Preservation. Walk the source claim by claim. Confirm each load-bearing claim landed in SPEC.md or a companion. Wrapper-ceremony drops are logged under "Wrapper-only content" so the drop is on the record, not silent.
Record the verdict for each pass to .memlog.md (append --type event). In interactive mode, review it with the user. In headless mode, .memlog.md is one of the files returned, so the caller (or its downstream LLM) reads the verdict there.
When the user points the skill at an existing spec folder (or its SPEC.md) with no change signal, offer to review assumptions or open questions, or determine what they want to do.
Requires SPEC.md on disk — run the normal Operation first if it doesn't exist yet. Headless runs never do this, even when the invocation text asks for it: if mode detection (On Activation, step 4) resolved headless, skip this section entirely and proceed with the normal headless response. In interactive mode, offer the handoff at most once per run when the input reads as multiple independently shippable slices; a decline ends the offer for this run, not forever.
Hand the spec folder to bmad-preview-ticketing as the requirement source: it plans the work with the user as an epic whose tickets.toml entries cite this spec's CAP-N ids, and it runs the board from there. Load-bearing detail the slicing conversation surfaces (a constraint, a design decision) comes back here as a spec update, never into a ticket alone.
When a spec update runs, search the ticket root for this spec folder's path in References; where tickets cite it, name the entries and tickets whose description no longer matches and offer to re-slice them with bmad-preview-ticketing. The update itself never edits a ticket.
Interactive — share the spec folder path conversationally. Name the capability count, the companions produced, and the verdict in one or two sentences. If assumptions[] or open_questions[] are non-empty, list them (short — one line each) and invite the user to walk through them. Make clear that addressing them can update the source input (if it was a file), the spec, or both — whichever combination the user prefers. Do not dump JSON or present a wall of output.
Headless — return JSON per assets/headless-schemas.md.
Run {workflow.on_complete} if set.
Any update to the spec — resolved assumptions, answered open questions, other changes — is appended to .memlog.md as it happens. When a change overrides something that came from a source input, offer to update that source too, so upstream and the spec don't silently diverge.
companions: array of .md files downstream MUST read alongside SPEC.md to have the full contract. Paths may point inside the spec folder (spec-authored companions like glossary.md) or outside it (adopted companions like ../planning-artifacts/ux-designs/ux-foo-bar-2026-05-23/DESIGN.md). The split between spec-authored and adopted is implicit by path; downstream treats both the same.sources: array of paths to files that were fully absorbed into the SPEC, with no remaining downstream value (e.g., a PRD whose every load-bearing claim is now in the kernel). Listed for audit and for bmad-spec to re-read on update. Downstream does NOT read these. Files that downstream still needs to read belong in companions:, not here.