diff --git a/docs/cs/reference/core-tools.md b/docs/cs/reference/core-tools.md index 89be39949..a4c032ada 100644 --- a/docs/cs/reference/core-tools.md +++ b/docs/cs/reference/core-tools.md @@ -18,6 +18,7 @@ Spusťte jakýkoli základní nástroj zadáním jeho názvu skillu (např. `bma | [`bmad-help`](#bmad-help) | Task | Kontextové poradenství, co dělat dál | | [`bmad-brainstorming`](#bmad-brainstorming) | Workflow | Facilitace interaktivních brainstormingových sezení | | [`bmad-party-mode`](#bmad-party-mode) | Workflow | Orchestrace skupinových diskuzí více agentů | +| [`bmad-spec`](#bmad-spec) | Workflow | Distill any intent input into a SPEC kernel and companions, the canonical contract for downstream work (translation pending) | | [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Task | Iterativní zdokonalování LLM výstupu | | [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Task | Cynická revize hledající chybějící a chybné | | [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Task | Vyčerpávající analýza větvících cest pro neošetřené hraniční případy | diff --git a/docs/fr/reference/core-tools.md b/docs/fr/reference/core-tools.md index 1031137fe..abcf43a9e 100644 --- a/docs/fr/reference/core-tools.md +++ b/docs/fr/reference/core-tools.md @@ -18,6 +18,7 @@ Exécutez n'importe quel outil principal en tapant son nom de compétence (par e | [`bmad-help`](#bmad-help) | Tâche | Obtenir des conseils contextuels sur la prochaine étape | | [`bmad-brainstorming`](#bmad-brainstorming) | Workflow | Faciliter des sessions de brainstorming interactives | | [`bmad-party-mode`](#bmad-party-mode) | Workflow | Orchestrer des discussions de groupe multi-agents | +| [`bmad-spec`](#bmad-spec) | Workflow | Distill any intent input into a SPEC kernel and companions (translation pending) | | [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Tâche | Pousser la sortie LLM à travers des méthodes de raffinement itératives | | [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Tâche | Revue cynique qui trouve ce qui manque et ce qui ne va pas | | [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Tâche | Analyse exhaustive des chemins de branchement pour les cas limites non gérés | diff --git a/docs/reference/core-tools.md b/docs/reference/core-tools.md index 16a7fa1bf..21a880901 100644 --- a/docs/reference/core-tools.md +++ b/docs/reference/core-tools.md @@ -18,6 +18,7 @@ Run any core tool by typing its skill name (e.g., `bmad-help`) in your IDE. No a | [`bmad-help`](#bmad-help) | Task | Get context-aware guidance on what to do next | | [`bmad-brainstorming`](#bmad-brainstorming) | Workflow | Facilitate interactive brainstorming sessions | | [`bmad-party-mode`](#bmad-party-mode) | Workflow | Orchestrate multi-agent group discussions | +| [`bmad-spec`](#bmad-spec) | Workflow | Distill any intent input into a SPEC kernel and companions, the canonical contract for downstream work | | [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Task | Push LLM output through iterative refinement methods | | [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Task | Cynical review that finds what's missing and what's wrong | | [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Task | Exhaustive branching-path analysis for unhandled edge cases | @@ -96,6 +97,37 @@ The magic happens in ideas 50–100. The workflow encourages generating 100+ ide **Output:** Real-time multi-agent conversation with maintained agent personalities +## bmad-spec + +**Distill any intent input into the canonical SPEC contract for downstream work.** Takes a brief, PRD, GDD, RFC, brain dump, transcript, UX folder, or mixed multi-source input and produces a `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 the kernel. + +**Use it when:** + +- You need to lock the WHAT before the HOW for any kind of work (software, game design, research, editorial, policy, business). +- You want a LLM Optimized succinct, no-fluff contract that downstream skills can consume without re-reading every upstream artifact. +- You want to validate or update an existing spec. + +**How it works:** + +1. Reads the input and any ancillary linked materials. +2. Distills into the five-field kernel using a configurable template; routes overflow into appropriately-named companions. +3. Runs a two-pass self-validate (coherence rules, then preservation of every load-bearing source claim). +4. Writes `SPEC.md`, sibling companions, and a `.decision-log.md` under `{output_folder}/specs/spec-{slug}/`. + +Spec Law enforces eight rules: capabilities carry both intent and success; intents are WHAT not HOW; constraints actually bend decisions; non-goals are explicit; success signals are concrete; capability IDs are stable; every load-bearing source claim is preserved; prose is lean. + +**Input:** + +- `input` (required) — path or inline text. Vague idea, brain dump, PRD, GDD, RFC, brief, transcript, mockup folder, mixed multi-source. +- `slug` (optional) — required only when input is sparse and no slug is derivable from a source filename. +- `target_spec_path` (optional) — set to update an existing spec instead of creating a new one. + +**Output:** Spec folder containing `SPEC.md`, any companion files, and a `.decision-log.md`. Headless callers receive a JSON response with the result status and the list of files written or modified. + +:::note[Mutation contract] +`bmad-spec` is the only writer of `SPEC.md` and of spec-authored companions. Other skills produce their own native artifacts and invoke `bmad-spec` headless when they need to express intent as the canonical contract or propose updates. +::: + ## bmad-advanced-elicitation **Push LLM output through iterative refinement methods.** — Selects from a library of elicitation techniques to systematically improve content through multiple passes. diff --git a/docs/vi-vn/reference/core-tools.md b/docs/vi-vn/reference/core-tools.md index 2883b927e..13ed5cbe3 100644 --- a/docs/vi-vn/reference/core-tools.md +++ b/docs/vi-vn/reference/core-tools.md @@ -18,6 +18,7 @@ Chạy bất kỳ công cụ cốt lõi nào bằng cách gõ tên skill của n | [`bmad-help`](#bmad-help) | Tác vụ | Nhận hướng dẫn có ngữ cảnh về việc nên làm gì tiếp theo | | [`bmad-brainstorming`](#bmad-brainstorming) | Quy trình | Tổ chức các phiên brainstorming có tương tác | | [`bmad-party-mode`](#bmad-party-mode) | Quy trình | Điều phối thảo luận nhóm nhiều agent | +| [`bmad-spec`](#bmad-spec) | Quy trình | Distill any intent input into a SPEC kernel and companions, the canonical contract for downstream work (translation pending) | | [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Tác vụ | Đẩy đầu ra của LLM qua các vòng tinh luyện lặp | | [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Tác vụ | Rà soát hoài nghi để tìm chỗ thiếu và chỗ sai | | [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Tác vụ | Phân tích toàn bộ nhánh rẽ để tìm trường hợp biên chưa được xử lý | diff --git a/docs/zh-cn/reference/core-tools.md b/docs/zh-cn/reference/core-tools.md index dbc0cb377..520a56305 100644 --- a/docs/zh-cn/reference/core-tools.md +++ b/docs/zh-cn/reference/core-tools.md @@ -18,6 +18,7 @@ sidebar: | [`bmad-help`](#bmad-help) | Task | 基于项目上下文推荐下一步 | | [`bmad-brainstorming`](#bmad-brainstorming) | Workflow | 引导式头脑风暴与想法扩展 | | [`bmad-party-mode`](#bmad-party-mode) | Workflow | 多智能体协作讨论 | +| [`bmad-spec`](#bmad-spec) | Workflow | Distill any intent input into a SPEC kernel and companions, the canonical contract for downstream work (translation pending) | | [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Task | 通过多轮技法增强 LLM 输出 | | [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Task | 对抗式问题发现审查 | | [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Task | 边界与分支路径穷举审查 | diff --git a/src/core-skills/bmad-spec/SKILL.md b/src/core-skills/bmad-spec/SKILL.md index 4957ac74e..d3d437e15 100644 --- a/src/core-skills/bmad-spec/SKILL.md +++ b/src/core-skills/bmad-spec/SKILL.md @@ -15,7 +15,6 @@ Multiple skills may call to update the same spec over time. - Bare paths (e.g. `assets/spec-template.md`) resolve from the skill root. - `{skill-root}` is this skill's install dir; `{project-root}` is the working dir. - `{workflow.}` resolves to fields in `customize.toml`. -- `{doc_workspace}` is the bound spec folder for this run. ## On Activation @@ -32,10 +31,10 @@ The spec is **always a folder** named `{workflow.spec_output_path}/{workflow.run `{slug}` describes the thing being specced, not the input shape: - Source artifact already carries a slug (e.g., `prd-foo-bar-2026-05-23/`): inherit (`foo-bar`). -- Sparse, in-chat, or multi-source input: interactive asks; headless caller provides. +- Sparse, in-chat, or multi-source input: interactive asks; headless caller provides it as part of the input. If absent and underivable, headless blocks with `error_code: "missing_slug"`. - Same slug = same folder. A second invocation with the same `{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`. +**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: @@ -102,7 +101,7 @@ After every create or update, sweep the resulting artifact in **two passes** bef **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. -Append a one-paragraph verdict to `.decision-log.md` covering both passes, review with user. +Append a one-paragraph verdict to `.decision-log.md` covering both passes. In interactive mode, review the verdict with the user. In headless mode, `.decision-log.md` is one of the files returned, so the caller (or its downstream LLM) reads the verdict there. ## Spec with no change signal diff --git a/src/core-skills/bmad-spec/assets/headless-schemas.md b/src/core-skills/bmad-spec/assets/headless-schemas.md index c8e161acc..096b15803 100644 --- a/src/core-skills/bmad-spec/assets/headless-schemas.md +++ b/src/core-skills/bmad-spec/assets/headless-schemas.md @@ -1,66 +1,33 @@ -# Headless JSON Schemas +# Headless JSON Response -The default invocation is headless: input goes in, JSON comes out. Omit keys for artifacts not produced. +The default invocation is headless: input goes in, JSON comes out. The contract is intentionally tiny — return the outcome and the files touched. Anything else a caller needs is inside those files (SPEC.md, companions, `.decision-log.md`). -## Common fields - -- `status` — `"complete"`, `"partial"`, or `"blocked"` -- `intent` — `"create"`, `"update"`, or `"validate"` (inferred from inputs) -- `reason` — required when `status` is `"blocked"`; one-sentence explanation -- `assumptions` — array of inferred values not directly confirmed by inputs -- `open_questions` — array of gaps that need a human decision - -## Create / Update +## Success ```json { "status": "complete", - "intent": "create", - "spec_path": "_bmad-output/specs/spec-quarter-drop/", - "decision_log_path": "_bmad-output/specs/spec-quarter-drop/.decision-log.md", - "sources": ["_bmad-output/planning-artifacts/prds/prd-quarter-drop-2026-05-22/prd.md"], - "companions": ["glossary.md", "../planning-artifacts/ux-designs/ux-quarter-drop-2026-05-22/DESIGN.md"], - "capabilities": [ - {"id": "CAP-1", "intent": "User can record a voice memo pinned to current GPS coords."}, - {"id": "CAP-2", "intent": "User hears memos auto-trigger when walking within range of a drop."} - ], - "verdict": "Ready for downstream. All eight Spec Law rules pass.", - "assumptions": [], - "open_questions": [] + "files": [ + "_bmad-output/specs/spec-quarter-drop/SPEC.md", + "_bmad-output/specs/spec-quarter-drop/glossary.md", + "_bmad-output/specs/spec-quarter-drop/.decision-log.md" + ] } ``` -- `spec_path` is the **spec folder**, per Workspace rules in `SKILL.md` (default: `{output_folder}/specs/spec-{slug}/`). The kernel file inside is named per `customize.toml.spec_filename` (default `SPEC.md`). -- `sources` is the array of files fully absorbed into the SPEC; audit-only, downstream does NOT read these. Empty when input had no fully-absorbed source (e.g., a UX-folder-only input). -- `companions` is the array of `.md` files downstream MUST read alongside SPEC.md. Sibling-relative for spec-authored (e.g., `glossary.md`); outside-folder-relative for adopted (e.g., `../planning-artifacts/ux-designs/{run}/DESIGN.md`). -- `capabilities` carries IDs and one-line intents only — enough for downstream consumers to address them without re-reading the spec. -- `verdict` is the one-paragraph self-validate result. When `status` is `"partial"`, the verdict explains what is blocking "ready for downstream." - -## Validate-only - -```json -{ - "status": "complete", - "intent": "validate", - "spec_path": "_bmad-output/specs/spec-quarter-drop/", - "decision_log_path": "_bmad-output/specs/spec-quarter-drop/.decision-log.md", - "verdict": "Two rules weak: success signal is decorative; non-goals section empty.", - "findings": [ - {"rule": "Success signal is concrete", "note": "Currently reads 'users love it' — not testable."}, - {"rule": "Non-goals are explicit", "note": "Section absent."} - ], - "offer_to_update": true -} -``` +`files` lists every file written or modified in this run, in any order. The spec folder, kernel filename, decision log location, capabilities, companions, and verdict are all readable from those files; no need to re-encode them in the response. ## Blocked ```json { "status": "blocked", - "intent": "create", + "error_code": "insufficient_intent", "reason": "Input was a one-line idea with no surrounding context; too thin to distill. Suggest bmad-prd to draw the vision out first." } ``` -Always include `intent` (best-guess if not certain). When `status` is `"blocked"`, include a one-sentence `reason`. +Defined `error_code` values: + +- `insufficient_intent` — input too thin to distill into a kernel. +- `missing_slug` — input is sparse or multi-source and no slug was provided by the caller or derivable from a source path. diff --git a/src/core-skills/bmad-spec/customize.toml b/src/core-skills/bmad-spec/customize.toml index afb71ee72..c3cd7c0fe 100644 --- a/src/core-skills/bmad-spec/customize.toml +++ b/src/core-skills/bmad-spec/customize.toml @@ -20,8 +20,10 @@ activation_steps_append = [] # Persistent facts the workflow keeps in mind for the whole run. # Each entry is either a literal sentence, a skill prefixed with `skill:`, # or a `file:`-prefixed path/glob whose contents are loaded as facts. +# Default points to a single top-level file; override in team/user TOML +# to widen the scope (e.g. `_bmad/**/project-context.md`) if needed. persistent_facts = [ - "file:{project-root}/**/project-context.md", + "file:{project-root}/project-context.md", ] # Executed when the workflow completes. Scalar or array of instructions.