bmad 6.11
This commit is contained in:
@@ -0,0 +1,33 @@
|
||||
# Headless JSON Response
|
||||
|
||||
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, `.memlog.md`).
|
||||
|
||||
## Success
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "complete",
|
||||
"files": [
|
||||
"_bmad-output/specs/spec-quarter-drop/SPEC.md",
|
||||
"_bmad-output/specs/spec-quarter-drop/glossary.md",
|
||||
"_bmad-output/specs/spec-quarter-drop/.memlog.md"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`files` lists every file written or modified in this run, in any order. The spec folder, kernel filename, memlog location, capabilities, companions, and verdict are all readable from those files; no need to re-encode them in the response.
|
||||
|
||||
## Blocked
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "blocked",
|
||||
"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."
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
id: SPEC-{slug}
|
||||
companions: [] # files downstream MUST read alongside SPEC.md. Paths may point inside the spec folder (spec-authored) or outside it (adopted from an upstream skill).
|
||||
sources: [] # files fully absorbed into the SPEC (audit only; downstream does NOT read these). Never the memlog.
|
||||
---
|
||||
|
||||
> **Canonical contract.** This SPEC and the files in `companions:` are the complete, preservation-validated contract for what to build, test, and validate. Source documents listed in frontmatter are for traceability — consult them only if you need narrative rationale or prose color this contract intentionally omits.
|
||||
|
||||
# {Spec Title}
|
||||
|
||||
## Why
|
||||
|
||||
{One paragraph naming the force behind this work. A spec can exist for any of:
|
||||
- **a pain to solve** — a user or operator is stuck on a specific gap;
|
||||
- **an opportunity to capture** — something newly possible we want to claim;
|
||||
- **a vision to realize** — a thing we want to make exist because we want it to exist;
|
||||
- **a mandate to meet** — a regulation, deprecation, deadline, or contractual obligation.
|
||||
|
||||
Name which (or which combination) applies, who is affected, and the backdrop that makes it matter now. This is the anchor every downstream trade-off resolves against.}
|
||||
|
||||
## Capabilities
|
||||
|
||||
- **CAP-1**
|
||||
- **intent:** {One sentence. "User or system can do X to achieve Y." WHAT, not HOW.}
|
||||
- **success:** {Testable or demonstrable criterion. Something a test or a real demonstration can decide.}
|
||||
|
||||
## Constraints
|
||||
|
||||
- {A non-negotiable that bends design. If it doesn't rule anything out, it doesn't belong.}
|
||||
|
||||
## Non-goals
|
||||
|
||||
- {Explicit out-of-scope item. At least one. Stops downstream from filling the vacuum.}
|
||||
|
||||
## Success signal
|
||||
|
||||
- {One or two sentences. World-change moment, not dashboard. Concrete enough to write a test or run a demonstration against.}
|
||||
|
||||
## Assumptions
|
||||
|
||||
<!-- Optional. Omit this section entirely if empty. Inferred calls made without direct confirmation from the input. -->
|
||||
|
||||
- {Statement of fact the Spec proceeded under, e.g. "Assumed mobile-first since input mentioned GPS but no platform."}
|
||||
|
||||
## Open Questions
|
||||
|
||||
<!-- Optional. Omit this section entirely if empty. Gaps the input did not resolve that need a human decision before downstream skills consume the Spec. -->
|
||||
|
||||
- {Question phrased so a human can answer it, e.g. "Is offline playback in scope for CAP-2?"}
|
||||
@@ -0,0 +1,44 @@
|
||||
# Stories schema
|
||||
|
||||
`stories.yaml` — the optional output of Story Breakdown: a top-level YAML list, one entry per story, in execution order — stories run top to bottom. Sibling of `SPEC.md`, discovered by its fixed filename (same convention as `SPEC.md` and `.memlog.md`); never listed in `companions:`, never referenced from frontmatter.
|
||||
|
||||
## Fields
|
||||
|
||||
| Field | Type | Required | Meaning |
|
||||
|---|---|---|---|
|
||||
| `id` | string | yes | Identity, unique within the file. Compared for equality and used as a filename prefix; carries no other meaning. Use unpadded integers (`"1"`), or composites (`"3-2"`) when the epic sits inside a larger project spec. No zero-padding — execution order is the list order, not filename sort. Pinned once the story's spec file exists (see Update semantics); until then it may be renumbered. |
|
||||
| `title` | string, one line | yes | Display name; becomes the story's heading downstream. |
|
||||
| `description` | string | yes | What this story covers, pointing into `SPEC.md` — not a story spec. Keep it to two sentences; a writing rule, not something tooling enforces. |
|
||||
| `spec_checkpoint` | boolean | no (default `false`) | Set by the human at breakdown time; read only by the dispatching caller, never by the implementing dev skill. When true, a human reviews the story spec between planning and implementation. |
|
||||
| `done_checkpoint` | boolean | no (default `false`) | Caller-only, like `spec_checkpoint`. When true, dispatch pauses after this story completes, before anything further runs. |
|
||||
| `invoke_dev_with` | string | no (default `""`) | Free text appended verbatim to the prompt that dispatches this story; the implementing dev skill reads it as part of its prompt, and nothing else interprets it. If the text needs structure, put it inside the string. Which dev skill to invoke is the caller's configuration, never data in this file. |
|
||||
|
||||
## Validity rules
|
||||
|
||||
1. Every entry parses with all required fields; ids unique.
|
||||
2. Ids are prefix-free under the `<id>-` filename-matching convention: no id may equal another id plus a dash-suffix (`"3"` and `"3-2"` cannot coexist).
|
||||
3. No `status` field, ever.
|
||||
4. Ids are YAML strings, always quoted, containing only letters, digits, and dashes. An unquoted `id: 1` parses as a number and breaks string comparison; characters like `/` or `*` break the filename match.
|
||||
|
||||
## Example
|
||||
|
||||
```yaml
|
||||
- id: "1"
|
||||
title: Add rate limiting to the public API
|
||||
description: >-
|
||||
Introduce a token-bucket limiter in front of the public endpoints;
|
||||
return 429 with a Retry-After header on limit breach.
|
||||
spec_checkpoint: true
|
||||
invoke_dev_with: >-
|
||||
Rate limit state must be shared across instances; use the existing
|
||||
Redis client, not in-process memory.
|
||||
- id: "2"
|
||||
title: Expose limiter metrics to the ops dashboard
|
||||
description: >-
|
||||
Emit per-route accept/reject counters the existing dashboard can
|
||||
scrape; no new dashboard panels in this story.
|
||||
```
|
||||
|
||||
## Update semantics
|
||||
|
||||
Updates to `stories.yaml` go through Story Breakdown: append the change to `.memlog.md`, then re-derive. An id is pinned once its story spec file exists (any `stories/<id>-*.md` in the spec folder): a pinned story keeps its id through edits, its removal retires the id, and retired ids are never reassigned. Stories with no spec file yet may be renumbered, reordered, or removed freely on re-derive — typically so ids keep following list order. Never give a story an id that collides with a `stories/` file belonging to a different story.
|
||||
Reference in New Issue
Block a user