docs(bmad-spec): add reference docs, trim headless schema, tighten defaults
- Add full bmad-spec entry to docs/reference/core-tools.md and table-row
stubs to cs/fr/vi-vn/zh-cn (full translation pending).
- Strip headless-schemas.md to a minimal {status, files} success response
and {status, error_code, reason} blocked response. Drop spec_path,
capabilities, verdict, decision_log_path — all derivable from the files
themselves.
- Narrow customize.toml persistent_facts default from recursive glob to
single {project-root}/project-context.md; document override path.
- Drop unused {doc_workspace} convention line from SKILL.md.
- Clarify Self-Validate verdict handling for interactive vs headless.
- Document missing_slug error code in SKILL.md + headless schema.
This commit is contained in:
Brian Madison
parent
5b8f6af099
commit
b128fc6131
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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ý |
|
||||
|
|
|
|||
|
|
@ -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 | 边界与分支路径穷举审查 |
|
||||
|
|
|
|||
|
|
@ -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.<name>}` 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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue