julian
17c08e6392
- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24) - apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004) - apps/web: React 19 + Vite 8 (ESM) - libs/shared/api-interface: Zod contract base - Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit - WDS artifacts: - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs) - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact) - Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md - AGENTS.md + README.md como entrada para devs/agentes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
106 lines
4.0 KiB
Markdown
106 lines
4.0 KiB
Markdown
---
|
|
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
|