BMAD-METHOD/run-test-design.md at 2e16650067f0a12751a95ff22a4277f74b0c4f10

mirror of https://github.com/bmad-code-org/BMAD-METHOD.git synced 2026-01-30 04:32:02 +00:00

Files

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

2.8 KiB

Raw Blame History

title, description

title	description
How to Run Test Design	How to create comprehensive test plans using TEA's test-design workflow

Use TEA's *test-design workflow to create comprehensive test plans with risk assessment and coverage strategies.

When to Use This

System-level (Phase 3):

After architecture is complete
Before implementation-readiness gate
To validate architecture testability

Epic-level (Phase 4):

At the start of each epic
Before implementing stories in the epic
To identify epic-specific testing needs

Prerequisites

BMad Method installed
TEA agent available
For system-level: Architecture document complete
For epic-level: Epic defined with stories

Steps

1. Load the TEA Agent

Start a fresh chat and load the TEA (Test Architect) agent.

2. Run the Test Design Workflow

*test-design

3. Specify the Mode

TEA will ask if you want:

System-level - For architecture testability review (Phase 3)
Epic-level - For epic-specific test planning (Phase 4)

4. Provide Context

For system-level:

Point to your architecture document
Reference any ADRs (Architecture Decision Records)

For epic-level:

Specify which epic you're planning
Reference the epic file with stories

5. Review the Output

TEA generates a comprehensive test design document.

What You Get

System-Level Output (`test-design-system.md`)

Testability review of architecture
ADR → test mapping
Architecturally Significant Requirements (ASRs)
Environment needs
Test infrastructure recommendations

Epic-Level Output (`test-design-epic-N.md`)

Risk assessment for the epic
Test priorities
Coverage plan
Regression hotspots (for brownfield)
Integration risks
Mitigation strategies

Test Design for Different Tracks

Greenfield - BMad Method

Stage	Test Design Focus
Phase 3	System-level testability review
Phase 4	Per-epic risk assessment and test plan

Brownfield - BMad Method/Enterprise

Stage	Test Design Focus
Phase 3	System-level + existing test baseline
Phase 4	Regression hotspots, integration risks

Enterprise

Stage	Test Design Focus
Phase 3	Compliance-aware testability
Phase 4	Security/performance/compliance focus

Tips

Run system-level test-design right after architecture
Run epic-level test-design at the start of each epic
Update test design if ADRs change
Use the output to guide *atdd and *automate workflows

TEA Overview - Understanding the Test Architect
Setup Test Framework - Setting up testing infrastructure
Create Architecture - Architecture workflow

2.8 KiB Raw Blame History