bmad-shard-doc

--- name: bmad-shard-doc description: '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