refactor(skills): convert shard-doc.xml to native skill directory (#1896)
Replace single-file XML task with bmad-shard-doc/ skill directory (SKILL.md, workflow.md, bmad-skill-manifest.yaml). Update parent manifest and module-help.csv references. Preserves all 6 steps including Step 6 branching logic for original document handling. Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Alex Verkhovsky
GitHub
parent
874ae40bb2
commit
32693f1a6b
|
|
@ -3,7 +3,7 @@ core,anytime,Brainstorming,BSP,,_bmad/core/workflows/brainstorming/workflow.md,b
|
||||||
core,anytime,Party Mode,PM,,_bmad/core/workflows/party-mode/workflow.md,bmad-party-mode,false,party-mode facilitator,,"Orchestrate multi-agent discussions. Use when you need multiple agent perspectives or want agents to collaborate.",,
|
core,anytime,Party Mode,PM,,_bmad/core/workflows/party-mode/workflow.md,bmad-party-mode,false,party-mode facilitator,,"Orchestrate multi-agent discussions. Use when you need multiple agent perspectives or want agents to collaborate.",,
|
||||||
core,anytime,bmad-help,BH,,skill:bmad-help,bmad-help,false,,,"Get unstuck by showing what workflow steps come next or answering BMad Method questions.",,
|
core,anytime,bmad-help,BH,,skill:bmad-help,bmad-help,false,,,"Get unstuck by showing what workflow steps come next or answering BMad Method questions.",,
|
||||||
core,anytime,Index Docs,ID,,skill:bmad-index-docs,bmad-index-docs,false,,,"Create lightweight index for quick LLM scanning. Use when LLM needs to understand available docs without loading everything.",,
|
core,anytime,Index Docs,ID,,skill:bmad-index-docs,bmad-index-docs,false,,,"Create lightweight index for quick LLM scanning. Use when LLM needs to understand available docs without loading everything.",,
|
||||||
core,anytime,Shard Document,SD,,_bmad/core/tasks/shard-doc.xml,bmad-shard-doc,false,,,"Split large documents into smaller files by sections. Use when doc becomes too large (>500 lines) to manage effectively.",,
|
core,anytime,Shard Document,SD,,skill:bmad-shard-doc,bmad-shard-doc,false,,,"Split large documents into smaller files by sections. Use when doc becomes too large (>500 lines) to manage effectively.",,
|
||||||
core,anytime,Editorial Review - Prose,EP,,skill:bmad-editorial-review-prose,bmad-editorial-review-prose,false,,,"Review prose for clarity, tone, and communication issues. Use after drafting to polish written content.",report located with target document,"three-column markdown table with suggested fixes",
|
core,anytime,Editorial Review - Prose,EP,,skill:bmad-editorial-review-prose,bmad-editorial-review-prose,false,,,"Review prose for clarity, tone, and communication issues. Use after drafting to polish written content.",report located with target document,"three-column markdown table with suggested fixes",
|
||||||
core,anytime,Editorial Review - Structure,ES,,skill:bmad-editorial-review-structure,bmad-editorial-review-structure,false,,,"Propose cuts, reorganization, and simplification while preserving comprehension. Use when doc produced from multiple subprocesses or needs structural improvement.",report located with target document,
|
core,anytime,Editorial Review - Structure,ES,,skill:bmad-editorial-review-structure,bmad-editorial-review-structure,false,,,"Propose cuts, reorganization, and simplification while preserving comprehension. Use when doc produced from multiple subprocesses or needs structural improvement.",report located with target document,
|
||||||
core,anytime,Adversarial Review (General),AR,,skill:bmad-review-adversarial-general,bmad-review-adversarial-general,false,,,"Review content critically to find issues and weaknesses. Use for quality assurance or before finalizing deliverables. Code Review in other modules run this automatically, but its useful also for document reviews",,
|
core,anytime,Adversarial Review (General),AR,,skill:bmad-review-adversarial-general,bmad-review-adversarial-general,false,,,"Review content critically to find issues and weaknesses. Use for quality assurance or before finalizing deliverables. Code Review in other modules run this automatically, but its useful also for document reviews",,
|
||||||
|
|
|
||||||
|
Can't render this file because it has a wrong number of fields in line 2.
|
|
|
@ -0,0 +1,6 @@
|
||||||
|
---
|
||||||
|
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'
|
||||||
|
---
|
||||||
|
|
||||||
|
Follow the instructions in [workflow.md](workflow.md).
|
||||||
|
|
@ -0,0 +1 @@
|
||||||
|
type: skill
|
||||||
|
|
@ -0,0 +1,100 @@
|
||||||
|
# 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
|
||||||
|
|
@ -1,4 +0,0 @@
|
||||||
shard-doc.xml:
|
|
||||||
canonicalId: bmad-shard-doc
|
|
||||||
type: task
|
|
||||||
description: "Splits large markdown documents into smaller, organized files based on sections"
|
|
||||||
|
|
@ -1,108 +0,0 @@
|
||||||
<task id="_bmad/core/tasks/shard-doc" name="Shard Document"
|
|
||||||
description="Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says perform shard document">
|
|
||||||
<objective>Split large markdown documents into smaller, organized files based on level 2 sections using @kayvan/markdown-tree-parser tool</objective>
|
|
||||||
|
|
||||||
<llm critical="true">
|
|
||||||
<i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
|
|
||||||
<i>DO NOT skip steps or change the sequence</i>
|
|
||||||
<i>HALT immediately when halt-conditions are met</i>
|
|
||||||
<i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
|
|
||||||
<i>Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution</i>
|
|
||||||
</llm>
|
|
||||||
|
|
||||||
<critical-context>
|
|
||||||
<i>Uses `npx @kayvan/markdown-tree-parser` to automatically shard documents by level 2 headings and generate an index</i>
|
|
||||||
</critical-context>
|
|
||||||
|
|
||||||
<flow>
|
|
||||||
<step n="1" title="Get Source Document">
|
|
||||||
<action>Ask user for the source document path if not provided already</action>
|
|
||||||
<action>Verify file exists and is accessible</action>
|
|
||||||
<action>Verify file is markdown format (.md extension)</action>
|
|
||||||
<action if="file not found or not markdown">HALT with error message</action>
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<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 explode [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>
|
|
||||||
|
|
||||||
<step n="6" title="Handle Original Document">
|
|
||||||
<critical>Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion</critical>
|
|
||||||
<action>Present user with options for the original document:</action>
|
|
||||||
|
|
||||||
<ask>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):</ask>
|
|
||||||
|
|
||||||
<check if="user selects 'd' (delete)">
|
|
||||||
<action>Delete the original source document file</action>
|
|
||||||
<action>Confirm deletion to user: "✓ Original document deleted: [source-document-path]"</action>
|
|
||||||
<note>The document can be reconstructed from shards by concatenating all section files in order</note>
|
|
||||||
</check>
|
|
||||||
|
|
||||||
<check if="user selects 'm' (move)">
|
|
||||||
<action>Determine default archive location: same directory as source, in an "archive" subfolder</action>
|
|
||||||
<action>Example: /path/to/architecture.md → /path/to/archive/architecture.md</action>
|
|
||||||
<ask>Archive location ([y] to use default: [default-archive-path], or provide custom path):</ask>
|
|
||||||
<action if="user accepts default">Use default archive path</action>
|
|
||||||
<action if="user provides custom path">Use custom archive path</action>
|
|
||||||
<action>Create archive directory if it doesn't exist</action>
|
|
||||||
<action>Move original document to archive location</action>
|
|
||||||
<action>Confirm move to user: "✓ Original document moved to: [archive-path]"</action>
|
|
||||||
</check>
|
|
||||||
|
|
||||||
<check if="user selects 'k' (keep)">
|
|
||||||
<action>Display warning to user:</action>
|
|
||||||
<output>⚠️ WARNING: Keeping both original and sharded versions is NOT recommended.
|
|
||||||
|
|
||||||
This creates confusion because:
|
|
||||||
- The discover_inputs protocol may load the wrong version
|
|
||||||
- Updates to one won't reflect in the other
|
|
||||||
- You'll have duplicate content taking up space
|
|
||||||
|
|
||||||
Consider deleting or archiving the original document.</output>
|
|
||||||
<action>Confirm user choice: "Original document kept at: [source-document-path]"</action>
|
|
||||||
</check>
|
|
||||||
</step>
|
|
||||||
</flow>
|
|
||||||
|
|
||||||
<halt-conditions critical="true">
|
|
||||||
<i>HALT if npx command fails or produces no output files</i>
|
|
||||||
</halt-conditions>
|
|
||||||
</task>
|
|
||||||
Loading…
Reference in New Issue