LMS-BGN/.trae/rules/bmad-tool-core-shard-doc.md

Shard Document Tool Rule

This rule defines the Shard Document tool.

Tool Definition

When this tool is triggered, execute the following:

Split large markdown documents into smaller, organized files based on level 2 sections using @kayvan/markdown-tree-parser tool

MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER DO NOT skip steps or change the sequence HALT immediately when halt-conditions are met Each action xml tag within step xml tag is a REQUIRED action to complete that step Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution Uses `npx @kayvan/markdown-tree-parser` to automatically shard documents by level 2 headings and generate an index Ask user for the source document path if not provided already Verify file exists and is accessible Verify file is markdown format (.md extension) HALT with error message

<step n="2" title="Get Destination Folder">
  <action>Determine default destination: same location as source file, folder named after source file without .md extension</action>
  <action>Example: /path/to/architecture.md → /path/to/architecture/</action>
  <action>Ask user for the destination folder path ([y] to confirm use of default: [suggested-path], else enter a new path)</action>
  <action if="user accepts default">Use the suggested destination path</action>
  <action if="user provides custom path">Use the custom destination path</action>
  <action>Verify destination folder exists or can be created</action>
  <action>Check write permissions for destination</action>
  <action if="permission denied">HALT with error message</action>
</step>

<step n="3" title="Execute Sharding">
  <action>Inform user that sharding is beginning</action>
  <action>Execute command: `npx @kayvan/markdown-tree-parser [source-document] [destination-folder]`</action>
  <action>Capture command output and any errors</action>
  <action if="command fails">HALT and display error to user</action>
</step>

<step n="4" title="Verify Output">
  <action>Check that destination folder contains sharded files</action>
  <action>Verify index.md was created in destination folder</action>
  <action>Count the number of files created</action>
  <action if="no files created">HALT with error message</action>
</step>

<step n="5" title="Report Completion">
  <action>Display completion report to user including:</action>
  <i>- Source document path and name</i>
  <i>- Destination folder path</i>
  <i>- Number of section files created</i>
  <i>- Confirmation that index.md was created</i>
  <i>- Any tool output or warnings</i>
  <action>Inform user that sharding completed successfully</action>
</step>

HALT if npx command fails or produces no output files

Usage

Reference this tool with @tool-shard-doc to execute it.

Module

Part of the BMAD CORE module.