BMAD-METHOD/src/core-skills/bmad-shard-doc/SKILL.md

name	description
bmad-shard-doc	Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says perform shard document

Shard Document

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

CRITICAL RULES

• MANDATORY: Execute ALL steps in the EXECUTION section IN EXACT ORDER
• DO NOT skip steps or change the sequence
• HALT immediately when halt-conditions are met
• Each action within a step is a REQUIRED action to complete that step

EXECUTION

Step 1: Get Source Document

• Ask user for the source document path if not provided already
• Verify file exists and is accessible
• Verify file is markdown format (.md extension)
• If file not found or not markdown: HALT with error message

Step 2: Get Destination Folder

• Determine default destination: same location as source file, folder named after source file without .md extension
  • Example: /path/to/architecture.md --> /path/to/architecture/
• Ask user for the destination folder path ([y] to confirm use of default: [suggested-path], else enter a new path)
• If user accepts default: use the suggested destination path
• If user provides custom path: use the custom destination path
• Verify destination folder exists or can be created
• Check write permissions for destination
• If permission denied: HALT with error message

Step 3: Execute Sharding

• Inform user that sharding is beginning
• Execute command: npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]
• Capture command output and any errors
• If command fails: HALT and display error to user

Step 4: Verify Output

• Check that destination folder contains sharded files
• Verify index.md was created in destination folder
• Count the number of files created
• If no files created: HALT with error message

Step 5: Report Completion

• Display completion report to user including:
  • Source document path and name
  • Destination folder path
  • Number of section files created
  • Confirmation that index.md was created
  • Any tool output or warnings
• Inform user that sharding completed successfully

Step 6: Handle Original Document

Critical: Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion.

Present user with options for the original document:

What would you like to do with the original document [source-document-name]?

Options:

• [d] Delete - Remove the original (recommended - shards can always be recombined)
• [m] Move to archive - Move original to a backup/archive location
• [k] Keep - Leave original in place (NOT recommended - defeats sharding purpose)

Your choice (d/m/k):

If user selects d (delete)

• Delete the original source document file
• Confirm deletion to user: "Original document deleted: [source-document-path]"
• Note: The document can be reconstructed from shards by concatenating all section files in order

If user selects m (move)

• Determine default archive location: same directory as source, in an archive subfolder
  • Example: /path/to/architecture.md --> /path/to/archive/architecture.md
• Ask: Archive location ([y] to use default: [default-archive-path], or provide custom path)
• If user accepts default: use default archive path
• If user provides custom path: use custom archive path
• Create archive directory if it does not exist
• Move original document to archive location
• Confirm move to user: "Original document moved to: [archive-path]"

If user selects k (keep)

• Display warning to user:
  • Keeping both original and sharded versions is NOT recommended
  • The discover_inputs protocol may load the wrong version
  • Updates to one will not reflect in the other
  • Duplicate content taking up space
  • Consider deleting or archiving the original document
• Confirm user choice: "Original document kept at: [source-document-path]"

HALT CONDITIONS

• HALT if npx command fails or produces no output files