dsh-plugin-bmad-sprint-board 1.0.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +98 -71
  2. package/client.js +1661 -3109
  3. package/locale/en.json +62 -1
  4. package/locale/zh.json +63 -2
  5. package/package.json +8 -3
package/README.md CHANGED
@@ -1,27 +1,28 @@
1
1
  # BMAD Sprint Board
2
2
 
3
3
  A [DSH Harness](https://github.com/deepseek-ai/dsh) plugin that reads a
4
- [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) project and shows it in the
5
- Session sidebar: what is being worked on, what disagrees with the tracking file,
6
- and what to do next.
4
+ [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) **v7** project and shows it
5
+ in the Session sidebar: every initiative, what is being worked on, and what the
6
+ ticket store disagrees with the tickets on disk.
7
7
 
8
- **Read-only.** It never writes to your sprint files. Every action it offers is a
9
- string you copy — a command when the board knows what to do, a prompt when it
10
- only knows what to ask.
8
+ **Read-only.** It never writes to your ticket store. Every action it offers is a
9
+ string you copy.
11
10
 
12
11
  ```
13
12
  Requirements │ BMAD Sprint board │ Chat
14
- ─────────────────────────────────────────
15
- Status Epic Requirements Specs
13
+ -------------------------------------------
14
+ Status Epic Tickets Initiatives
16
15
 
17
- stories ████████░░ 12 / 15 80%
18
- requirements ███████░░░ 11 / 17 65%
19
- ⚠ 23 of 40 unmapped
16
+ tools done 4 epics 16 tickets <- initiative, active when set
20
17
 
21
- NEXT bmad-build Storefront Header Navigation Tools Integration
22
- it is the next unstarted story [Ask agent · prompt]
18
+ GAPS (2)
19
+ L1 plans not linked in the ticket store high
20
+ 16 plan files match a ticket by name, but no entry
21
+ declares them with a ticket key [Ask agent · prompt]
22
+ C1 epic settled with open tickets high
23
+ epic-tools-landing says done, 2 tickets open
23
24
 
24
- ● DONE (12) ● GAPS (4) ● COULD NOT CHECK (1) ● BACKLOG (3)
25
+ BLOCKED (1) IN PROGRESS (2) DONE (13) UNKNOWN (29)
25
26
  ```
26
27
 
27
28
  ## What you get
@@ -30,76 +31,96 @@ NEXT bmad-build Storefront Header Navigation Tools Integration
30
31
 
31
32
  | View | Shows |
32
33
  |---|---|
33
- | **Status** | One foldable lane per story status, in board order, with the gaps board below |
34
- | **Epic** | One section per epic: its status, retrospective state, and progress |
35
- | **Requirements** | Every declared requirement by class, each with the state its evidence supports |
36
- | **Specs** | The spec files no story in the sprint file claims |
34
+ | **Status** | One foldable lane per ticket state, with a gaps board beneath it |
35
+ | **Epic** | One section per epic: its status, its tickets, and its progress |
36
+ | **Tickets** | Every ticket in the initiative, grouped by state, across all epics |
37
+ | **Initiatives** | Every initiative with its status and counts, marking the active one |
37
38
 
38
- Requirements and specs are readings of the same artefacts, so they are views of
39
- the same tab rather than tabs of their own.
39
+ Selecting an initiative in **Initiatives** loads it into the other three views.
40
+ The selection is local: nothing is written back, so looking at another initiative
41
+ cannot change which one BMAD considers active.
40
42
 
41
- The requirements lane is the one worth knowing about, because it has **four**
42
- states rather than two:
43
+ ### BMAD v7 only
43
44
 
44
- | Mark | State | Meaning |
45
- |---|---|---|
46
- | `✓` | done | verifiable, and verified |
47
- | `◑` | partial | some covering epic is finished |
48
- | `✗` | not started | verifiable, and nothing has begun |
49
- | `○` | no evidence | nothing can say either way |
45
+ This is version 2. Version 1 read BMAD v6 -- `sprint-status.yaml`, `epics.md`,
46
+ `spec-*.md` -- and none of those exist in a v7 project. The two are different
47
+ data models, not different formatting, so the plugin is released in two versions:
50
48
 
51
- `○` is the point. A requirement with no coverage map and no story citing it is
52
- not "not done" — the board cannot tell, and says so rather than guessing.
49
+ | BMAD | Install |
50
+ |---|---|
51
+ | **v7** | `dsh-plugin-bmad-sprint-board` (this one, 2.x) |
52
+ | v6 | `dsh-plugin-bmad-sprint-board@1.0.0` |
53
+
54
+ Opened on a v6 project, 2.x says so and points at 1.0.0 rather than rendering an
55
+ empty board.
53
56
 
54
57
  ### The gaps board
55
58
 
56
- The board is a **check on** the tracking file, not a mirror of it.
59
+ The board is a **check on** the ticket store, not a mirror of it.
57
60
 
58
61
  | Detector | Fires when |
59
62
  |---|---|
60
- | **B1 done but owing** | a story is `done` while deferred entries still name its spec |
61
- | **B3 review patches never applied** | a story is `done` with unticked `[Review][Patch]` items |
62
- | **U1 UX run not carried into the plan** | a UX design run the epics document never names |
63
- | **U2 UX requirement no epic delivers** | a UX requirement whose components no story mentions |
64
- | **REQ** | requirements the inventory declares that no coverage map claims |
65
-
66
- Alongside them: two sparse progress bars side by side — stories against
67
- requirements, because the distance between them is the finding — and **one next
68
- action**, chosen from BMAD's own ladder rather than invented. A board that offers
69
- three next actions has not answered.
70
-
71
- **Unverifiable is a state, never a silence.** A check that cannot be evaluated
72
- reports itself, and the bar's denominator never shrinks — so the board cannot
73
- improve its score by going blind.
63
+ | **L1** unreadable ticket files | a file in a ticket folder is neither a leaf ticket nor a plan, so the store ignores it |
64
+ | **L2** unlisted leaves | a leaf ticket exists on disk with no entry in the ticket index |
65
+ | **L3** plans no ticket claims | a plan file corresponds to no index entry |
66
+ | **L4** unrecognised status | a ticket carries a status word this board does not know |
67
+ | **C1** epic settled with open tickets | an epic says `done` while tickets inside it are not |
68
+ | **C2** initiative settled with open tickets | an initiative says `done` while tickets inside it are not |
69
+ | **E1** initiative declares no epics | the folder exists and its store lists no epics |
70
+
71
+ **L1 is the one that matters on a migrated project.** The ticket store decides
72
+ what a file is from its frontmatter `type`: `story`, `spike` or `bug` is a leaf
73
+ that carries the ticket, anything else declaring a `ticket` key is a plan over
74
+ one, and anything else is ignored. A file named `story-x-plan.md` whose type is
75
+ `feature` and which names no ticket is therefore *neither* — invisible to the
76
+ tooling, which reports its ticket as backlog however finished the work is. Every
77
+ number it prints is wrong while every file on disk looks correct.
78
+
79
+ **The board's lanes are the store's lanes.** States come from `tickets.py`'s own
80
+ table rather than being invented: an empty status is **backlog**, because a planned
81
+ story looks exactly like that before `bmad-build` writes its plan — a plan is an
82
+ artefact of building, not a precondition of existing. Only a status word the store
83
+ does not define becomes *unknown*, and it is shown but never counted as settled.
84
+
85
+ ### How it reads a v7 project
86
+
87
+ It resolves the same two keys the official tooling does, by merging the same
88
+ three files lowest priority first:
74
89
 
75
- ### Keyboard
90
+ ```
91
+ _bmad/config.toml [core] output_folder
92
+ _bmad/custom/config.toml team overrides
93
+ _bmad/custom/config.user.toml [core] active_initiative
94
+ ```
76
95
 
77
- `primary+S` on desktop, `primary+alt+S` on the web, opening in whichever sidebar
78
- pane you are already in. `web:linux` declares no default on purpose: the Harness
79
- admits only three chords product-wide there, so every shipped tab command omits
80
- it rather than squat on one.
96
+ which is what `_bmad/scripts/resolve_config.py` does. The board agrees with that
97
+ script rather than assuming a layout.
81
98
 
82
99
  ## Install
83
100
 
84
- **From npm** — nothing to build, no dependencies, no install scripts:
101
+ From npm, into the `web` profile:
85
102
 
86
- ```
87
- plugin_manager({ action: "install_bundle",
88
- target: "dsh-plugin-bmad-sprint-board" })
103
+ ```sh
104
+ dsh plugin --profile web add dsh-plugin-bmad-sprint-board
89
105
  ```
90
106
 
91
- **From the repository:**
107
+ Or from the repository, and from a local clone:
92
108
 
109
+ ```sh
110
+ dsh plugin --profile web add github:vitaliy-bobrov/dsh-plugin-bmad-sprint-board
111
+ dsh plugin --profile web add /path/to/bmad-sprint-board-bundle
93
112
  ```
94
- plugin_manager({ action: "install_bundle",
95
- target: "github:vitaliy-bobrov/dsh-plugin-bmad-sprint-board" })
96
- ```
97
113
 
98
- **From a local clone**, which is the form used while developing it:
114
+ Substitute your own profile name for `web`. Nothing needs building, the package
115
+ has no dependencies, and it runs no install scripts. Reload the page afterwards:
116
+ the Client half registers on the next load, and the Host half contributes nothing
117
+ to register.
118
+
119
+ The same three, through the agent's tool rather than the CLI:
99
120
 
100
121
  ```
101
122
  plugin_manager({ action: "install_bundle",
102
- target: "/path/to/bmad-sprint-board-bundle" })
123
+ target: "dsh-plugin-bmad-sprint-board" })
103
124
  ```
104
125
 
105
126
  ### Peer dependency
@@ -116,24 +137,30 @@ as `0.2.0-rc.2` a bare `^0.2.0` does not match — so the install is refused bef
116
137
  pnpm runs. `^0.2.0-0` resolves to `>=0.2.0-0 <0.3.0-0`: prereleases of 0.2.0,
117
138
  every later 0.2.x, and nothing beyond.
118
139
 
140
+ ### Category
141
+
142
+ **UI & Experience.** It adds a sidebar tab and reads. It contributes no tool, no
143
+ model and no service, and it writes nothing.
144
+
119
145
  ## Extending
120
146
 
121
147
  The plugin is two layers, and only the second knows about DSH:
122
148
 
123
149
  | What | Where |
124
150
  |---|---|
125
- | What the board reads and computes | `src/core.js`, `src/detect.js`, `src/plan.js`, `src/ux.js`, `src/requirements.js` — pure, no DSH, no DOM |
151
+ | Parsers | `src/toml.js`, `src/frontmatter.js` — the two readers BMAD's files need |
152
+ | The project model | `src/config.js`, `src/store.js`, `src/model.js`, `src/scan.js` — pure, no DSH, no DOM |
153
+ | The checks | `src/detect.js` |
126
154
  | How it renders | `src/shell-*.js` — CSS, components, slot registration |
127
155
 
128
- Adding a **view** is one entry in the `VIEWS` list in `src/shell-post.js` plus a
129
- body function; the switcher, the fold state and the snapshot are already shared.
156
+ Adding a **view** is one entry in the view list in `src/shell-post.js` plus a body
157
+ function; the switcher, the fold state and the snapshot are already shared.
130
158
 
131
159
  Adding a **detector** is a function returning gaps shaped
132
- `{ id, title, severity, subject, evidence, action }` and one line in `detect()`.
133
- `src/detect.test.js` shows the shape: the fixtures there prove a detector *fires*,
134
- while the live-workspace tests only prove it *agrees* with the repository. Those
135
- are different jobs, and keeping them apart is what stops a sprint in progress
136
- from breaking the suite.
160
+ `{ id, title, severity, subject, evidence, action }` and one push in
161
+ `detectInitiative()`. `src/model.test.js` shows the shape: each detector is
162
+ tested against a fixture that should fire it *and* a clean fixture beside it,
163
+ because a detector nobody has checked can stay quiet is one nobody has checked.
137
164
 
138
165
  ```bash
139
166
  node build.mjs # reassemble client.js from src/
@@ -147,9 +174,9 @@ no build, so the assembled bundle has to be present. Edit `src/`, rebuild, and
147
174
 
148
175
  ## More
149
176
 
150
- - [Implementation notes](https://github.com/vitaliy-bobrov/dsh-plugin-bmad-sprint-board/blob/main/docs/implementation.md) — what every section renders
151
- from, how paths and folds resolve, the parsing, the bundle layout. None of it is
152
- needed to install or use the plugin.
177
+ - [Implementation notes](https://github.com/vitaliy-bobrov/dsh-plugin-bmad-sprint-board/blob/main/docs/implementation.md)
178
+ — the parsing, the linking rules and the bundle layout. None of it is needed to
179
+ install or use the plugin.
153
180
 
154
181
  ## Licence
155
182