skills/bmad-code-org__bmad-method
1
0
Fork 0
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git synced 2026-09-19 08:11:52 +08:00
Code Issues Packages Projects Releases Wiki Activity
2,235 Commits 77 Branches 165 Tags
main
Commit Graph

22 Commits

Author SHA1 Message Date
do-operator 116e703d67 docs: refresh the README banner, restore its diagram, and fix the favicon (#2854) 
* docs: refresh the README banner, restore its diagram, and fix the favicon

Three things the READMEs and the site were carrying wrong.

The banner is the current one from bmadcode.com: the BMad tile and wordmark
over the line art, at 2x for retina. It replaces a 1408x224 crop, and is
smaller on disk than what it replaces.

The delivery-loop diagram in the README has been broken since the diagrams
moved to `docs-site/src/diagrams`. It cannot simply be pointed at the new
path: an authored diagram carries geometry and classes only, so it needs the
site's stylesheet to have any colour at all, and a README loads an SVG as an
`<img>` where no stylesheet can reach it. So `docs/images/` now holds exports
of the source, generated by `npm run export-readme-diagrams` with the dark
ramp substituted in as literal colours. Literals rather than custom
properties because an export has to survive renderers thinner than a browser
- resvg drops `var()` and paints the fallback black. The Korean README's
copy is exported from the same geometry through the existing labels file, so
the two can no longer drift apart.

The favicon was a teal `B` that matched neither the header tile nor
blog.bmadcode.com. It is now the BMad mark, drawn from the same path data
the header already carries, on the same navy the blog uses. The .ico is
generated from the SVG and stays listed for browsers that ignore
`image/svg+xml`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(diagrams): draw the bulbs as bulbs, not as coloured circles

The earlier version leaned on gold to say "idea". Once the diagrams lost
their own colours, a circle over a rounded tab in the body ink read as
neither a bulb nor anything else.

So the glyph now carries its meaning in the drawing: a filament arch inside
the globe, a tapered neck, and a ribbed screw base, plus a third ray
overhead. The small bulb takes the same construction one size down, with a
single rib rather than two, which is all that reads at that scale. Both hold
up on the light and dark ramps.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs: give the delivery loop an English page, at the house type scale

The diagram the README leads with appeared on exactly one page of the site:
the Korean `how-to/choose-a-development-path`, a leftover from before the
English tree was restructured into start/plan/build. An English reader never
saw it.

It now opens "Find Your Starting Point" on the docs index, where it says in a
picture what the list underneath says in prose.

Putting it in a docs column for the first time showed its type was tuned for
a README: drawn at a 1120 viewBox, its labels came out at 11.0px and 8.3px
against the 12.8px and 10.9px the other diagrams hold at the same 736px
content width. The sizes are scaled to match; the geometry is untouched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs-site: guard locale coverage, and give the footer band an edge

Two unrelated things a reader can see, and one they cannot.

The invisible one first. When a locale has no page at a route, Starlight
serves the English one and says nothing, so a missing translation and a
working one look identical from the outside — which is how all five locales
ended up stranded on the pre-restructure tree unnoticed (#2855). Starlight
does mark the substitution: a fallback page carries `lang="en"` on `<main>`
inside a document that declares the locale. The build now checks the built
site for that mismatch, which measures the symptom rather than inferring it
from the sidebar.

The existing backlog is far too large to fix here, so it is recorded in
`locale-coverage-baseline.json` and tolerated. The build fails only when the
picture changes: a route starts falling back, or a baseline entry stops. Both
are one `--update` away. The second failing is deliberate — it is what keeps
the baseline from outliving the problem it records.

The visible one: the footer band sets its own dark ground, which on the dark
ramp is the page's ground, so there was no band — only 297px of unexplained
space where one should have started. It now lifts a step and takes a hairline
in dark mode, and sits flush against the article instead of adding a margin
on top of its own padding. The last-updated line gives up some of its air too;
between them the gap is 234px, and every part of it is now doing something.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs-site: stack the footer columns on mobile, and add the touch icon

The footer's three link groups were laid out in two columns below 32rem, so
one group always dropped onto a row of its own with the space beside it left
empty, and "Plan inside an organization" wrapped inside a 155px column. Three
groups do not fit two columns; on a phone they get one each.

The favicon already matches bmadcode.com exactly - same viewBox, same navy
tile, same three paths, since the mark is the one the header carries. What was
missing is the apple-touch-icon the site also ships, so an icon saved to an iOS
home screen fell back to a screenshot. It is generated from the same SVG,
flattened onto the tile navy because iOS applies its own mask and does not want
the transparency our rounded corners would leave.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(diagrams): raise the delivery loop's type, and give it back a colour

Alex is right about what he saw, and wrong about it being new. His screenshot
is the version before the type was scaled for a docs column, where the title
rendered at 9.2px against GitHub's 16px body. That is already fixed. But the
original diagram this replaced ran 14/16/21 and the fix brought it to
14.5/16.5/19.5 - a hair under where it always was, and his objection would
have applied to the original too. So rather than argue the point, take it
past the original: 17.5/18/21, which puts the node labels at body size and
the title at 14.5px in a README.

The colour is the other half of his complaint's cause. The original said
"here is where each kind of work joins" in gold; when the diagrams lost their
own colours that meaning went with it and nothing replaced it. The three
entry drops now carry the accent, which is the vocabulary's existing job for
an edge the drawing has to single out, so it works on both ramps. The marker
was still called `arrow-gold`; it is `arrow-entry` now.

The README export also gets a ground rather than a flat fill: a near-black
lifting across the diagonal with one soft accent wash behind the row the work
enters from, which is the register bmadcode.com uses - almost all ground and
one blue. The wash sits high on purpose, because centred it pooled behind the
boxes and their flat fill then read as darker than the ground around them.
The docs site keeps a ground that follows the reader's theme, so this belongs
to the export alone.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(diagrams): drop the gradient ground from the README export

It read as an effect rather than a surface. The drawing's colour is the
accent on the three entry drops, and it says more with a flat ground behind
it and nothing competing.

The larger type and the accent stay.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(diagrams): space the delivery loop's two band labels evenly

They were not spaced at all, only placed. The title's baseline fell three
units BELOW the big bulb's top ray - the two only looked separate because
they are far apart horizontally - while the lower band had 35 units of air.
That mismatch is what read as wrong.

Both now sit 40 units clear of the nearest mark. The drawing keeps its size
and shifts down inside a taller canvas, 420 to 460, with the labels lifted
out of its group so the shift leaves them where they are; the remaining
padding above and below the pair is 15 and 16.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
 2026-09-11 11:52:35 -06:00
do-operator 87d3407873 feat(docs-site): align the docs with the bmadcode design system, and move diagrams to themed SVG (#2850) 
* feat(website): restyle the docs in the bmadcode design system

The docs carried a Ghost-blog theme: Inter and Space Grotesk, a #3b82f6
accent, 12px radii, tinted panels and hover lifts. bmadcode.com is built
from the foundry ramp on paper, Archivo and IBM Plex Mono, one
accent held under ~2% of the page, 2px corners and hairlines. This aligns
the two so the method and its documentation read as one thing.

Four type registers, and almost nothing else: Instrument Serif for the
page masthead, Archivo 600 for headings, Archivo 400 at 17px for prose,
and IBM Plex Mono at 11px for labels — spent once per section, never on
prose or a table header. The measure comes down to 46rem so a page reads
as an article.

Also fixes the site title, which was the only place in the repo spelling
the brand "BMAD Method"; it now matches the prose, and every page title
and share card with it.

The four component overrides are the parts CSS could not reach: the mark
in its ink tile, the accent eyebrow naming each section, and the dark
footer band. The footer renders from TwoColumnContent rather than the
Footer slot because Starlight right-aligns the content column
(--sl-content-margin-inline: auto 0), so a band in that column never
reached the sidebar edge.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* feat(website): inline hand-authored SVG diagrams

Diagrams shipped as rasters: build-diagram.png at 488 KB, plus a -fr and
a -ko export of the same picture. Every translation meant re-exporting an
image, three of the five locales fell back to the English one, and none
of them could follow the site's light and dark themes.

Diagrams are now hand-authored SVGs carrying geometry and classes only.
A rehype plugin inlines them where a page links to one, so a single
stylesheet themes every diagram — an <img> is opaque to page CSS, which
is the whole reason for inlining. A second diagram written against the
same class vocabulary matches the first without any styling work.

Labels are translated rather than redrawn: each <text> carries a data-i18n
key and the strings live in <name>.labels.json, so one drawing serves
every language and a translation cannot drift out of shape.

The integration exists because the inlined SVG lands inside Astro's
content layer cache, which is keyed on the markdown file. Editing a
diagram left the previous drawing on the page, through a build that
reported success. It watches the diagram directory in dev and drops the
content store when the drawing changes.

Diagram.astro is the same behaviour for anywhere that can take a
component. The docs are 193 .md files and no .mdx, where components
cannot be imported, so the plugin is the path pages actually use.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(build): draw the bmad-build run as a themed SVG

Replaces build-diagram.png and its -fr and -ko exports with one drawing
shared by all five locales: the actors in a left lane, the spine down the
middle, a return channel for BAD_SPEC and INTENT_GAP, and the review
lenses in a panel — the layout the original had.

Gzipped, the diagram goes from 440 KB to 1 KB, and it now follows the
theme. The French labels are in place; the other locales fall back to the
English text in the SVG, which is what their pages showed before.

The raster files stay for now: walk-through-a-change still uses
walkthrough-diagram, and that conversion is a separate change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(website): let the diagram cache stamp survive a fresh checkout

The stamp is written into Astro's cache directory, which does not exist
until Astro creates it partway through the build. On a clean clone — CI,
every time — the integration threw in astro:config:done and took the
build with it.

It now creates the directory, and treats any failure as a warning: a
cache that cannot be stamped is a slower build, not a broken one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(walkthrough): draw the walkthrough run as a themed SVG

Replaces walkthrough-diagram.png and its -fr and -ko exports with one
drawing shared by all five locales, keeping the original's layout: the
two inputs in a left lane, the five stages down the spine, the notes
beside them, the early exit skipping the middle, and the three outcomes
along the bottom.

The outcome chips introduce a `chip` class in the shared stylesheet,
taking the green and amber the asides already use, so a green in a
diagram is the same green as a tip. Nothing else about this diagram
needed styling: it inherits the vocabulary build-run established.

With both diagrams converted, website/public/diagrams is empty and the
six raster files are gone.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(plan): fold the remaining diagrams into the themed pipeline

planning-skills, development-paths and bmad-delivery-loop were already
SVG, but outside the pipeline in three ways: they carried their own
palettes, they were served as <img> so page CSS could not reach them,
and two of them shipped a -ko twin that duplicated the geometry to
translate the labels.

Two were drawn dark — navy grounds, white text, cyan strokes — so on a
light docs page they sat as dark panels. Their palettes are mapped onto
the shared tokens, which flips them correctly in both themes, and their
backdrops are dropped: a diagram sits on the page's ground rather than
painting its own. The hardcoded typefaces go too, so they inherit
Archivo and IBM Plex Mono like everything else.

The Korean strings are lifted out of the -ko files into the label files,
matched by document order, so all five diagrams are now one drawing per
diagram. docs/images is empty.

Also fixes the cache guard, which was clearing the wrong store: build
writes to the cache directory, dev writes to .astro beside the config,
and the stamp was shared between them so whichever ran first consumed
the invalidation. It is now per command and build-only — deleting the
store under a running dev server leaves the content layer unable to
render, so dev needs a restart after a diagram edit instead.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(diagrams): align the imported diagrams with the shared vocabulary

Mapping the old palettes onto the theme tokens made those three diagrams
theme-aware, but not part of the system. They still carried 8-16px
corners, painted their own canvas panel or background grid, drew every
connector in the accent, and left arrowheads baked to a colour of their
own — so next to build-run and walkthrough-run they read as imports.

They now use the same roles as the two authored diagrams: .node for
boxes, .edge for connectors, .head for arrowheads, 2px corners, and no
self-painted ground. Accent drops out of all five: it is for the one
thing a drawing points at, which here is a single .node.hot on the
destination box rather than a green that read as a status.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(docs-site): record hast-util-from-html in the lockfile

The dependency was declared in package.json during the move to docs-site
but its entry never reached the lockfile's root block, so the two
disagreed about what the site depends on.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(diagrams): land the arrowheads on their targets in build-run

Three arrows pointed at glyphs rather than at boxes, and all three fell
short: DEFER stopped 10px from the document and aimed at its corner
instead of its body, REJECT stopped 27px from the discard glyph, and the
result returning to you stopped 21px from the person.

The boxes were fine throughout — every arrow into a node already landed
within 2px. What the three had in common is that a glyph sits inside a
translated group, so eyeballing them against the drawing's coordinates
put the endpoints in the wrong place.

Measured across all twenty arrowheads in screen space afterwards: the
largest remaining gap is 3px.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(diagrams): move the DEFER label off its own curve, and clear the
 cache on a dev start too

Re-aiming the DEFER arrow at the document glyph swung its curve left,
straight through the label that had been sitting clear of the old path.
The label moves into the pocket between Present and the curve.

Checking it exposed a worse problem: dev was still serving the previous
drawing after a restart, so the fix looked like it had not applied. The
cache guard had been narrowed to build-only after clearing the store
under a live dev server broke rendering — but that failure came from
clearing on a mid-session restart, and the watch that caused those is
gone. On a cold start, before the content layer loads, clearing is safe
in both commands. Confirmed by probe: edit a diagram, restart dev, the
edit is served, no errors.

So the limitation is now what it was documented to be. Previously an
edited diagram needed a full build before dev would show it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(diagrams): give every connector an arrowhead, and clear the boxes

Three defects in development-paths, all inherited from the import:

Connectors were written as two subpaths in one path element. A marker-end
lands on the last vertex of a path, so only the second segment ever drew
a head — which is why Change—Edit had none and Edit→Verify did. Four
connectors are now separate paths, and all twelve carry a head.

The two routed connectors ended exactly on the box they point at, so the
arrowhead sat on the border. They stop 4px clear.

The epic row was 140/130/130 wide with the labels centred on each box.
All three are 140 now, evenly spaced, with the connectors and labels
following.

Band backgrounds were imported as .node, which made every check treat a
connector crossing its own band as an error. They are .band now: same
appearance, but the drawing says what it means.

Also moves the DEFER label in build-run back alongside its curve. The
previous fix pushed it clear of the line and lost the association.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(diagrams): one stroke weight across all five drawings

build-run and walkthrough-run carry no inline stroke-width — the
stylesheet owns it, at 1.5 for a connector and 1 for a box. The three
imported drawings still carried their own: 2, 3, 4 and 2.5, so their
lines were twice as heavy as the authored ones.

That is also what made the arrowhead into "Build × stories" look wrong.
A marker scales with stroke-width by default, so a head defined at 7
units rendered at 21px on a 3px line instead of 10.5px. On a 9px final
drop it overshot the corner and sat on the horizontal run above the box.

Sixty inline stroke-widths are gone, and the two routed connectors get a
longer final drop so the head has room to sit on.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* test(docs-site): cover rehype-inline-diagrams, and fix what it caught

Twelve tests alongside the existing plugin suite, against a temporary
site root: what gets inlined and what is left alone, label substitution
per locale with fallback to the authored English, the accessible name,
and the mtime-keyed re-read the dev server depends on.

The first run failed on the accessible name, and it was right to. hast
camel-cases ARIA attributes, so the guard read `aria-labelledby` and
found nothing — meaning every diagram's own <title> was being replaced
by the markdown alt text. build-run and walkthrough-run both title
themselves with a sentence describing the whole run, and both were
announcing a four-word alt instead.

Now 119 assertions, and a diagram that names itself keeps its name.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(diagrams): recover the Korean walkthrough labels, and correct the guide

Review caught two things.

The style guide sent contributors to website/src/diagrams/, the path
this branch renamed. A diagram placed there would never be found by the
loader or localized.

The second is a regression this branch introduced and the PR described
wrongly. It claimed the non-English pages "fall back to the English text
in the SVG, which is what their pages showed before". That is untrue for
four pages: they had localized exports, and replacing those with one
drawing plus an English-only label file puts English labels in front of
readers who previously had their own language.

walkthrough-diagram-ko.svg was an SVG, so its Korean is recoverable and
is now the ko-KR label set for walkthrough-run — all 22 keys. The other
three were .webp exports, so their text cannot be lifted out:

  ko-kr build-a-change        build-run ko-KR       0/30 keys
  fr    explanation/build     build-run fr-FR      13/30 keys
  fr    build/walk-through    walkthrough fr-FR     0/22 keys

Those need a translator. The 13 French keys are mine and unreviewed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* i18n(diagrams): complete the French and Korean diagram labels

Fills the three gaps review found: build-run had no Korean and only 13
of 30 French keys, walkthrough-run had no French. All four sets are now
complete.

Terms come from the repository rather than fresh coinage. Korean reuses
what the -ko diagrams and the Korean pages already established — 의도,
구체화, 계획, 검토, 결과, 사양 — and French follows the vocabulary of
docs/fr/explanation/build.md: revue, intention, résultat, implémentation,
spécification, and visite guidée from the French walkthrough page.

The uppercase edge tokens stay as they are. PATCH, REJECT, BAD_SPEC,
INTENT_GAP and DEFER appear in no locale's prose, so they read as
protocol constants, the way bmad-build and path:line are already left
alone in the Korean set.

French runs longer than English and these are fixed-geometry drawings,
so both French pages and the Korean one were checked for labels
overflowing their box, sitting on a connector, or colliding: none.

These are my translations, not a native speaker's. Worth a pass from
whoever owns each locale before release.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(docs-site): satisfy the repo's lint and format rules in the new tests

The diagram tests used .forEach to walk the hast tree, which this repo's
eslint config rejects (unicorn/no-array-for-each), and the file was not
Prettier-formatted. CI had been failing on lint since the tests landed.

Rewritten as for…of and formatted. Verified against every gate the
workflow runs — lint, format:check, test, build — rather than the build
alone.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(website): describe the source of the theme without naming a private repo

The comments cited the private repository and file paths it was ported
from. They point at bmadcode.com instead, which is the public thing a
reader can actually check.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(website): keep footer links in the reader's language

The footer prefixed only BASE_URL to root-locale paths, so a French or
Korean reader following any internal link landed on the English page and
lost their language for the rest of the visit.

The links now carry the page's locale. Every target exists under every
locale — Starlight generates the untranslated ones as fallbacks — so this
is safe rather than a trade of one broken link for another: all 36
routes, 6 links across 6 locales, resolve in the built site.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
 2026-09-09 01:26:54 -04:00
Alex Verkhovsky fa1637ee40 build: move the Node toolchain into docs-site (#2834) 
The root package.json, lockfile, .nvmrc, prettier ignore file and
.npmignore are gone. docs-site has its own package.json and lockfile
with the Astro, ESLint and Prettier dependencies, and its scripts run
relative to that directory. tools/quality.py, both workflows and the
docs all call npm inside docs-site.

stamp_release.py stamps only the 29 skill manifests now; the version
lives nowhere else on this branch. The tests for package stamping go
with it.
 2026-09-05 18:11:37 -06:00
Alex Verkhovsky c16dc729a9 docs: add Existing Codebases chapter (#2793) 
Add a four-page chapter after Plan Larger Work: Start in an Existing
Codebase (the repo is the knowledge; size the work from the source),
Set and Maintain Project Context, Getting Deeper as the worked example,
and The Theory of Project Context as optional last reading.

Retire six English pages with redirects, drop the empty English
Tutorials sidebar group, collapse Plan Larger Work and Existing
Codebases in the sidebar, reflow how-to and explanation orders, and
retarget Welcome, README, Plan, Reference, and style-guide links.
Localized copies stay as deferred translation work.
 2026-08-29 11:48:29 -06:00
Alex Verkhovsky 191219eadb docs: add Plan Larger Work chapter (#2790) 
Introduce a Plan chapter of eight pages under docs/plan/: Choose a
Planning Path, Plan Inside an Organization, Explore and Validate an
Idea, Research a Decision, Define Requirements and a Specification,
Design UX and Architecture, Break Work into Stories and Track It, and
Finish an Epic. Content is written from the current skill sources and
describes what each skill takes in, what it produces, and how to steer
it.

Retire ten English pages from how-to and explanation with redirects to
their new homes, renumber the remaining sidebar orders, migrate English
links, shrink the Welcome router bullet, and add a Plan Larger Work
sidebar group after Build. Localized copies of the retired pages are
recorded in deferred work.
 2026-08-28 21:44:40 -06:00
Alex Verkhovsky e510393b35 docs: define plain English writing rules (#2667) 
* docs: define plain English writing rules

* docs: clarify what readers need from each page
 2026-08-01 23:35:44 -07:00
Alex Verkhovsky 022bcbc66d Rename Quick Dev to Build (#2651) 
* feat(bmm): rename quick dev to build

* fix: address build rename review findings

* fix: clarify deprecated build shims

* fix: offer legacy customization migration
 2026-07-29 19:40:05 -07:00
Alex Verkhovsky 029ba287bc docs: make Quick Dev the canonical implementation workflow (#2643) 
Rewrite published documentation and maintained translations around variable
planning depth with one Phase 4 implementation loop. Update diagrams and AI
indexes, and reject obsolete workflow terminology in deployable output.
 2026-07-28 22:30:22 -07:00
Brian c23f23400d feat: streamline core to an 8-skill set with merged review and editorial skills (#2603) 
* feat: streamline core to a 5-skill kernel with standalone skill modules

Core installs 14 -> 5 catalog-visible skills; atoms exit to standalone
modules; installer gains real dependency resolution; zero npm deps.

- Merge bmad-editorial-review-prose/-structure into bmad-editorial-review
  (structure models JIT-loaded, new customize.toml)
- Merge bmad-review-adversarial-general/-edge-case-hunter/-verification-gap
  into bmad-review as selectable lenses; hidden husk-forwarders remain at
  the old IDs (no catalog rows) so gds/loop/os-utils keep working
- Move bmad-brainstorming, bmad-party-mode, bmad-forge-idea out of core to
  src/standalone-skills/ as single-skill modules; add bmad-analysis bundle
  module (curated dependency list over the atoms)
- Move bmad-spec into bmm (2-plan-workflows)
- Modernize bmad-advanced-elicitation: uv run, customize.toml, methods
  pick offloaded to scripts/pick_methods.py (with tests)
- Delete bmad-index-docs, bmad-shard-doc (removes the tree's only external
  npm dependency), and the four deprecation shims (bmad-create-prd,
  bmad-edit-prd, bmad-validate-prd, bmad-create-architecture); all added
  to removals.txt
- Installer: activate the dependencies field (recursive union into
  selectedModules, cycle-guarded, warn on unknown), config-driven picker
  visibility; core stays force-installed
- bmm module.yaml declares deps on the three atoms
- Docs updated across all locales; new reference/standalone-skills.md;
  shard-doc how-tos removed

* Restore original critical wording lost in the review/editorial merges

The merges into bmad-review and bmad-editorial-review were meant to keep
the source skills' critical wording behind progressive disclosure, not
paraphrase it away. Restore what was lost:

- lens-adversarial: clueless-weasel framing, extreme-skepticism wording,
  the at-least-ten-issues quota, and zero-findings-is-suspicious (the
  merge had inverted this to zero-is-valid)
- bmad-review SKILL: zero-findings stance is now per-lens
- lens-edge-case: mandatory exact-order step enforcement
- lens-verification-gap: exact 'No verification gaps found.' clean line
- editorial-review: full Human/LLM reader principles restored to new
  references/reader-principles.md; structure-pass HIGH-VALUE DENSITY
  role, front-load-value, anti-patterns, pacing check, and length_target
  assessment; prose-pass role sentence, analyze-style-first step, and
  merge-overlapping-fixes rule; output summary block and min-3-words HALT

* feat(installer): promote bmad-analysis bundle to src/bmad-analysis-skills

Move the bmad-analysis bundle module out of src/standalone-skills/ into its
own src/bmad-analysis-skills root, teach the installer to resolve it there
(getModulePath, official-modules listing, isBuiltInModule helper), and
update the marketplace manifest and standalone-skills docs to match.

* refactor(bmad-review): rename edge-case lens to edge-case-hunter

Rename the lens code and reference file (lens-edge-case.md ->
lens-edge-case-hunter.md), add explicit when = "always" to the shipped
lenses, and tighten the lens-selection wording in SKILL.md.

* feat(bmad-editorial-review): configurable style guide + analysis-driven rework

Apply the workflow-builder analysis recommendations:

- Make the baseline style guide configurable: style_guide in customize.toml
  now IS the baseline (default "Microsoft Writing Style Guide") instead of
  an empty override slot; SKILL.md no longer hardcodes the guide.
- Inline reader-principles.md into SKILL.md and delete the reference (it
  loaded on every run and was half-duplicated inline).
- Complete the customization surface: activation_steps_prepend/append,
  persistent_facts (project-context glob), on_complete, and a
  review_output_path scalar split out of output_preferences; add a
  file:-load fallback convention.
- Ground word metrics: new scripts/word_metrics.py (stdlib, PEP 723, tests)
  emits total/per-section word counts so impact estimates and the reduction
  summary use exact numbers.
- Cross-pass dedup: prose pass skips CUT-tagged passages and re-attaches
  fixes in MERGE'd ones; output ranks by impact with a long-tail rollup.
- Polish: HALT threshold replaced with plain outcome, duplicate LLM-reader
  bullets merged, all-caps lowered, literal Overview heading added.

* fix(installer): stop cache-refresh git commands from escaping to the parent repo

Two compounding bugs let a pre-commit test run shallow-fetch and hard-reset
the developer's own repository:

1. Git spawns in custom-module-manager and external-manager inherited the
   hook environment. Git exports GIT_DIR (absolute, in worktree checkouts)
   into pre-commit hooks; a child git then targets the hook's repo regardless
   of cwd, and treats its cwd — the module cache dir — as the work tree. The
   cache refresh's 'git fetch --depth 1' + 'git reset --hard origin/main'
   therefore shallowed the shared .bare and moved the checked-out branch.
   New git-env.js strips repo-targeting GIT_* vars from every git spawn in
   both managers, including calls that previously inherited process.env
   implicitly.

2. Test suite 51 (quickUpdate dependency expansion) ran the real
   CustomModuleManager lookup, which scans ~/.bmad/cache/custom-modules and
   network-refreshes every cached clone — real user state. The suite now
   stubs findModuleSourceByCode.

Verified by rerunning the suite with GIT_DIR pointed at the repo and a PATH
shim blocking fetch/reset/clone: 432 passing, zero blocked calls.

* De-scope standalone-skills mechanism: atoms return to core, shims reinstated

Shrink the PR to its heart — the skill merges — and defer the module
mechanics to a follow-up where all skills become module-driven:

- bmad-brainstorming, bmad-party-mode, bmad-forge-idea move back to
  src/core-skills/ as ordinary core skills with their catalog rows
  restored; src/standalone-skills/ and the bmad-analysis bundle module
  are removed
- Installer reverted to main: standalone discovery, hidden-module
  filtering, dependency resolution, manifest changes (test suites 49-51
  removed with the code); the cache-refresh git fix is retained
- The four bmm deprecation shims (create/edit/validate-prd,
  create-architecture) are reinstated so enterprise installs that
  invoke the old IDs or carry _bmad/custom overrides keep working;
  descriptions trimmed to the short husk style; their removals.txt
  entries dropped (removal rides the v7 cut as their frontmatter
  promises)
- marketplace.json keeps the five plugin entries with atom paths
  pointing at src/core-skills/
- Docs (en/cs/fr/vi/zh) reframe the three skills as core thinking
  skills; standalone-skills.md reference page removed

* Fix all findings from the max-effort adversarial review

Correctness:
- Finish the edge-case -> edge-case-hunter lens rename at every caller:
  the forwarder husk, the code-review/dev-auto/quick-dev review layers,
  the renderer test assertion, and the stale example path in
  bmad-review/SKILL.md
- marketplace.json: ship the five core kernel skills with
  bmad-method-lifecycle so its skills' bmad-review/bmad-editorial-review/
  bmad-help/bmad-advanced-elicitation invocations resolve in a
  marketplace install
- pick_methods.py / word_metrics.py: force UTF-8 stdout (Windows locale
  code pages crashed on the catalog's arrows and CJK headings)
- word_metrics.py: pair fences CommonMark-style so 4-backtick fences can
  embed 3-backtick examples without corrupting sections; count CJK
  characters as words
- pick_methods.py: validate --extra entries are JSON objects (was an
  uncaught AttributeError); read catalogs with utf-8-sig (BOM'd CSVs
  silently blanked every num)
- bmad-spec: activation now resolves {output_folder} (which the
  Workspace uses) instead of the unused {planning_artifacts}; drop the
  stale core-only-installs comment
- Editorial husks: pin the legacy output contracts (three-column table /
  Document Summary report and exact empty-state lines) like the review
  husks do
- PRD shims: advertise the real bmad-prd customize keys
  (validation_checklist_template, prd_output_path, run_folder_pattern,
  finalize_reviewers) instead of three that don't exist
- bmad-prd: add the forwarded-activation clause its shims rely on
  (ported from bmad-architecture)
- Locale workflow-maps (fr/cs/vi/zh): add the bmad-spec Phase-2 row the
  English map gained, which every locale's core-tools note points at
- git-env.js: also strip GIT_CONFIG_PARAMETERS and the
  GIT_CONFIG_COUNT/KEY_n/VALUE_n family; pass gitEnv() to the three npm
  install spawns whose transitive git calls inherited hook vars

Consistency:
- brain.py --extra overlay now replaces-by-name like pick_methods.py
  (same customize.toml additional_* semantics across sibling skills),
  with a regression test

* Fix prettier formatting in marketplace.json

* Apply valid CodeRabbit findings

- brain.py: catch malformed --extra overlays (bad JSON, non-array root,
  non-object entries) into the clean error path instead of a raw
  traceback, with a regression test; read catalogs and overlays with
  utf-8-sig; normalize ALL CSV fields (required ones were unstripped and
  could arrive as None from short rows)
- brain-selector: clamp the random-technique count to what the pool can
  supply so the Total badge matches the actual draw (template +
  regenerated assets/brain-selector.html)
- bmad-editorial-review: word_metrics command now uses the explicit
  {skill-root}/ prefix
- resolve_party.py / resolve_personas.py: custom member overrides now
  start from the installed entry, so omitted fields (icon, title,
  description, module, team) survive; non-string member tokens land in
  unresolved instead of raising TypeError; party's member loop gains the
  isinstance guards its personas twin already had
- bmad-brainstorming: fix the SKILL.md claim that headless is the only
  context for self-generated ideas (autonomous mode is interactive);
  autonomous mode honors user-supplied techniques before self-selecting
- Docs: drop duplicate 'only' in the spec template; align zh-cn
  forge-idea's bmad-review description with the English wording

* Create only the output folder at install time

bmm no longer pre-creates planning_artifacts, implementation_artifacts,
and project_knowledge — the last of which put an empty docs/ at every
project root. Skills create those lazily on first write. core now
declares {output_folder} in its directories block, which was previously
created only as a side effect of the artifact folders nesting under it.
 2026-07-18 23:49:22 -05:00
Alex Verkhovsky 003c979dbc chore: remove SM agent (Bob) and migrate to Developer agent (#2186) 
* chore: remove SM agent (Bob) and migrate capabilities to Developer agent

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(docs): correct agent naming and grammar from review triage

Standardize Developer agent references to bmad-agent-dev (matching
installed skill directory name) and fix possessive apostrophe in
implementation-readiness workflow.

* fix(skills): replace dev team references with Developer agent

No longer a multi-agent development team — just one Developer agent.
Remove residual Scrum Master search patterns from retrospective.

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-02 12:25:24 -07:00
Alex Verkhovsky b3cf338118 refactor(quick-dev): rename tech-spec prefix to spec (#2109) 
* refactor(quick-dev): rename tech-spec prefix to spec

* docs: update tech-spec references to spec
 2026-03-23 00:09:05 -06:00
Alex Verkhovsky 43c59f0cff docs: replace quick-flow explainer with quick-dev, remove stale Quick Spec refs 
Quick Flow was an umbrella for quick-spec + quick-dev. Quick Spec is
gone and the new preview was promoted to bmad-quick-dev, so the explainer
should be about quick-dev directly. Replaces quick-flow.md with the
original quick-dev-new-preview.md content (renamed), including the
diagram reference. zh-cn uses the original hand-written Chinese
translation. Also removes stale Quick Spec references from agents.md.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-03-18 23:47:49 -06:00
Alex Verkhovsky db8f856fce docs: update terminology from commands to skills across all documentation (#1850) 
Align documentation with the skills-based architecture migration by
replacing references to "commands", "slash commands", and legacy command
names with the new "skills" terminology and skill names.
 2026-03-07 16:14:25 -07:00
Brian Madison d4b4bdfa12 docs: improve project-context documentation and fix folder structure 
- Add explanation/how-to docs for project-context.md feature
- Update workflow-map Context Management section with comprehensive guidance
- Fix folder structure examples to show proper nested subdirectories
  (planning-artifacts/ and implementation-artifacts/ under _bmad-output/)
- Update established-projects.md with project-context creation step
- Standardize terminology: use "existing projects" instead of "brownfield"
 2026-02-15 17:32:05 -06:00
Brian Madison 98c1fa8282 document project remove legacy workflow init and workflow- status function calls 2026-02-14 15:16:51 -06:00
Alex Verkhovsky ecf7fbcb2c docs: add description front matter to documentation pages (#1566) 2026-02-07 10:43:16 -06:00
Alex Verkhovsky 2aab028f96 docs: rename brownfield to established projects (#1539) 
* docs: rename brownfield to established projects

Flatten how-to/brownfield/ subdirectory and replace jargon term
"brownfield" with more accessible "established projects" throughout.

- brownfield/index.md → established-projects.md
- brownfield/quick-fix-in-brownfield.md → quick-fixes.md
- brownfield-faq.md → established-projects-faq.md
- Update all internal links and references

* docs: remove redundant phrase from quick-fixes description

* docs: restore natural language in established-projects body
 2026-02-05 18:57:40 -06:00
Brian Madison d0c9cd7b0b removed dead code and obsolete levels 0-4 ref 2026-01-25 22:23:36 -06:00
Alex Verkhovsky 96f21be73e docs: optimize style guide for LLM readers (#1321) 
* docs: optimize style guide for LLM readers

Restructure documentation style guide with dependency-first ordering
and LLM-optimized content based on editorial-review-structure analysis.

Key changes:
- Add Universal Formatting Rules section at top (consolidated anti-patterns)
- Move Visual Hierarchy and formatting rules before document types
- Add Document Types decision table for type selection
- Move Before/After example to follow Visual Hierarchy
- Merge Links/Images into single Assets table
- Move tutorial-specific checklist into Tutorial Structure section
- Move Validation Steps to end (submission workflow)
- Cut abstract Quick Principles (no execution value for LLMs)
- Remove emotional/orientation language throughout
- Condense FAQ Sections structure

Result: ~35% reduction (539 deletions, 383 insertions) with improved
parseability for AI agents writing documentation.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: clarify explanation checklist admonition limit

Disambiguate 2-3 admonitions max to explicitly show it is a per-document
limit that still respects the universal per-section rule.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: clarify header budget vs structure template relationship

Add note explaining that structure templates show content flow, not 1:1
header mapping. Admonitions and inline elements are within sections.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: remove horizontal rules to follow own guidelines

Remove all --- section separators to comply with Universal Formatting
Rules. The ## headers provide sufficient visual separation.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: address PR review findings for style guide

- Fix forward reference in Header Budget section
- Clarify descriptions rule scope (tables and 5+ item lists)
- Restore realistic FAQ examples
- Add qualifier to admonition content length guideline

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: further optimize style guide as delta-only document

- Add opener declaring adherence to Google Style Guide and Diataxis
- Remove generic Google style guide sections (Visual Hierarchy patterns,
  Tables constraints, Code Blocks, Lists, Assets)
- Remove Diataxis explainer content (Document Types table, "X documents
  do Y" explanatory sentences, Before/After example)
- Keep all project-specific structure templates and checklists
- Consolidate rules into single Project-Specific Rules table

Result: 367 lines (down from 597), pure delta document assuming
LLM training knowledge of baseline standards.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-15 16:41:57 -06:00
forcetrainer e535f94325 docs: comprehensive style guide update with reference and glossary standards 
Style Guide Additions:
- Add Reference Structure section with 6 document types (Index, Catalog,
  Deep-Dive, Configuration, Glossary, Comprehensive)
- Add Glossary Structure section with table-based format leveraging
  Starlight's right-nav for navigation
- Include checklists for both new document types

Reference Docs Updated:
- agents/index.md: Catalog format, universal commands tip admonition
- configuration/core-tasks.md: Configuration format with admonitions
- configuration/global-config.md: Table-based config reference
- workflows/index.md: Minimal index format
- workflows/core-workflows.md: Catalog format
- workflows/document-project.md: Deep-dive with Quick Facts admonition
- workflows/bmgd-workflows.md: Comprehensive format, removed ~30 hr rules

Glossary Rewritten:
- Converted from 373 lines with ### headers to 123 lines with tables
- Right nav now shows 9 categories instead of 50+ terms
- Added italic context markers (*BMGD.*, *Brownfield.*, etc.)
- Alphabetized terms within categories
- Removed redundant inline TOC

All Docs:
- Remove horizontal rules (---) per style guide
- Remove "Related" sections (sidebar handles navigation)
- Standardize admonition usage
- Archive deleted workflow customization docs

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-12 00:23:05 -05:00
forcetrainer 12d3492e0c Add link auditor, reorganize documentation, and README update (#1277) 
* feat: add link auditor tools and fix broken docs links

- Add audit-doc-links.js to scan docs for broken links with auto-resolution
- Add fix-doc-links.js to apply suggested fixes (dry-run by default)
- Remove stale "Back to Core Concepts" breadcrumb links
- Update BMad acronym to "Breakthrough Method of Agile AI Driven Development"
- Update README links to docs.bmad-method.org
- Simplify upgrade callout in getting-started tutorial

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: reorganize docs structure and archive v4 tutorial

- Remove unused section index files (tutorials, how-to, explanation, reference)
- Move getting-started-bmadv4.md to _archive
- Update quick-start-bmgd.md to remove archived file reference
- Update upgrade-to-v6.md
- Update astro.config.mjs for new structure

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: ignore underscore directories in link checker

Update check-doc-links.js to skip _archive, _planning, and other
underscore-prefixed directories when validating links.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: add v4 users section to README

Add links to v4 documentation archive and upgrade guide for users
migrating from previous versions.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: convert docs to site-relative links and add validation tools

- Convert all relative links (./  ../) to site-relative paths (/path/)
- Strip .md extensions and use trailing slashes for Astro/Starlight
- Add fix-doc-links.js to convert relative links to site-relative
- Add validate-doc-links.js to check links point to existing files
- Remove old audit-doc-links.js and check-doc-links.js
- Update build-docs.js to use new validation script
- Add npm scripts: docs:fix-links, docs:validate-links
- Update style guide with validation steps

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: standardize acronym to BMad across documentation

Replace incorrect "BMAD" with correct "BMad" in text and frontmatter
while preserving "BMAD-METHOD" in GitHub URLs.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: fix BMad acronym and remove draft README

- Correct acronym to "Breakthrough Method of Agile AI Driven Development"
- Remove unused README-draft.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: standardize BMad acronym in README

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: standardize FAQ format across all FAQ pages

- Add TOC with jump links under "## Questions"
- Use ### headers for questions (no Q: prefix)
- Direct answers without **A:** prefix
- Remove horizontal rules and "Related Documentation" sections
- End each FAQ with issue/Discord CTA
- Update style guide with new FAQ guidelines
- Delete redundant faq/index.md (sidebar handles navigation)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: use repo-relative links with .md for GitHub compatibility

Convert all documentation links to repo-relative format (/docs/path/file.md)
so they work when browsing on GitHub. The rehype plugin strips /docs/ prefix
and converts .md to trailing slash at build time for Astro/Starlight.

- Update rehype-markdown-links.js to strip /docs/ prefix from absolute paths
- Update fix-doc-links.js to generate /docs/ prefixed paths with .md extension
- Convert 217 links across 64 files to new format

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: handle /docs/ prefix in link validator

Update resolveLink to strip /docs/ prefix from repo-relative links
before checking if files exist.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: restore FAQ index page

Re-add the FAQ index page that was accidentally deleted, with
updated repo-relative link format.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com>
 2026-01-10 02:55:33 +08:00
Alex Verkhovsky 2e16650067 feat(docs): Diataxis restructure + Astro/Starlight migration (#1263) 
* feat(docs): add Diataxis folder structure and update sidebar styling

- Create tutorials, how-to, explanation, reference directories with subdirectories
- Add index.md files for each main Diataxis section
- Update homepage with Diataxis card navigation layout
- Implement clean React Native-inspired sidebar styling
- Convert sidebar to autogenerated for both Diataxis and legacy sections
- Update docusaurus config with dark mode default and navbar changes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat(docs): migrate Phase 1 files to Diataxis structure

Move 21 files to new locations:
- Tutorials: quick-start guides, agent creation guide
- How-To: installation, customization, workflows
- Explanation: core concepts, features, game-dev, builder
- Reference: merged glossary from BMM and BMGD

Also:
- Copy images to new locations
- Update internal links via migration script (73 links updated)
- Build verified successfully

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(docs): add category labels for sidebar folders

Add _category_.json files to control display labels and position
for autogenerated sidebar categories.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* style(docs): improve welcome page and visual styling

- Rewrite index.md with React Native-inspired welcoming layout
- Add Diataxis section cards with descriptions
- Remove sidebar separator, add spacing instead
- Increase navbar padding with responsive breakpoints
- Add rounded admonitions without left border bar
- Use system font stack for better readability
- Add lighter chevron styling in sidebar
- Constrain max-width to 1600px for wide viewports

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: use baseUrl in meta tag paths for correct deployment URLs

* feat(docs): complete Phase 2 - split files and fix broken links

Phase 2 of Diataxis migration:
- Split 16 large legacy files into 42+ focused documents
- Created FAQ section with 7 topic-specific files
- Created brownfield how-to guides (3 files)
- Created workflow how-to guides (15+ files)
- Created architecture explanation files (3 files)
- Created TEA/testing explanation files
- Moved remaining legacy module files to proper Diataxis locations

Link fixes:
- Fixed ~50 broken internal links across documentation
- Updated relative paths for new file locations
- Created missing index files for installation, advanced tutorials
- Simplified TOC anchors to fix Docusaurus warnings

Cleanup:
- Removed legacy sidebar entries for deleted folders
- Deleted duplicate and empty placeholder files
- Moved workflow diagram assets to tutorials/images

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(build): use file glob instead of sidebar parsing for llms-full.txt

Replace brittle sidebar.js regex parsing with recursive file glob.
The old approach captured non-file strings like 'autogenerated' and
category labels, resulting in only 5 files being processed.

Now correctly processes all 86+ markdown files (~95k tokens).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(seo): use absolute URLs in AI meta tags for agent discoverability

AI web-browsing agents couldn't follow relative paths in meta tags due to
URL security restrictions. Changed llms-full.txt and llms.txt meta tag
URLs from relative (baseUrl) to absolute (urlParts.origin + baseUrl).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor(docs): recategorize misplaced files per Diataxis analysis

Phase 2.5 categorization fixes based on post-migration analysis:

Moved to correct Diataxis categories:
- tutorials/installation.md → deleted (duplicate of how-to/install-bmad.md)
- tutorials/brownfield-onboarding.md → how-to/brownfield/index.md
- reference/faq/* (8 files) → explanation/faq/
- reference/agents/barry-quick-flow.md → explanation/agents/
- reference/agents/bmgd-agents.md → explanation/game-dev/agents.md

Created:
- explanation/agents/index.md

Fixed all broken internal links (14 total)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat(docs): add Getting Started tutorial and simplify build script

- Add comprehensive Getting Started tutorial with installation as Step 1
- Simplify build-docs.js to read directly from docs/ (no consolidation)
- Remove backup/restore dance that could corrupt docs folder on build failure
- Remove ~150 lines of unused consolidation code

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(css): use fixed width layout to prevent content shifting

Apply React Native docs approach: set both width and max-width at
largest breakpoint (1400px) so content area maintains consistent
size regardless of content length. Switches to fluid 100% below
1416px breakpoint.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor(docs): restructure tutorials with renamed entry point

- Rename index.md to bmad-tutorial.md for clearer navigation
- Remove redundant tutorials/index.md
- Update sidebar and config references

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat(docs): add tutorial style guide and AI agent announcement bar

- Add docs/_contributing/ with tutorial style guide
- Reformat quick-start-bmm.md and bmad-tutorial.md per style guide
- Remove horizontal separators, add strategic admonitions
- Add persistent announcement bar for AI agents directing to llms-full.txt
- Fix footer broken link to tutorials

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat(docs): add markdown demo page and UI refinements

- Add comprehensive markdown-demo.md for style testing
- Remove doc category links from navbar (use sidebar instead)
- Remove card buttons from welcome page
- Add dark mode styling for announcement bar
- Clean up index.md card layout

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat(docs): apply unified tutorial style and update references

- Reformat create-custom-agent.md to follow tutorial style guide
- Update tutorial-style.md with complete unified structure
- Update all internal references to renamed tutorial files
- Remove obsolete advanced/index.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor(docs): migrate from Docusaurus to Astro+Starlight

Replace Docusaurus with Astro and the Starlight documentation theme
for improved performance, better customization, and modern tooling.

Build pipeline changes:
- New build-docs.js orchestrates link checking, artifact generation,
  and Astro build in sequence
- Add check-doc-links.js for validating internal links and anchors
- Generate llms.txt and llms-full.txt for LLM-friendly documentation
- Create downloadable source bundles (bmad-sources.zip, bmad-prompts.zip)
- Suppress MODULE_TYPELESS_PACKAGE_JSON warning in Astro build
- Output directly to build/site for cleaner deployment

Website architecture:
- Add rehype-markdown-links.js plugin to transform .md links to routes
- Add site-url.js helper for GitHub Pages URL resolution with strict
  validation (throws on invalid GITHUB_REPOSITORY format)
- Custom Astro components: Banner, Header, MobileMenuFooter
- Symlink docs/ into website/src/content/docs for Starlight

Documentation cleanup:
- Remove Docusaurus _category_.json files (Starlight uses frontmatter)
- Convert all docs to use YAML frontmatter with title field
- Move downloads.md from website/src/pages to docs/
- Consolidate style guide and workflow diagram docs
- Add 404.md and tutorials/index.md

---------

Co-authored-by: forcetrainer <bryan@inagaki.us>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-07 14:42:15 +08:00