@cloudkinetix/bmad-enhanced
Version:
Cloud-Kinetix enhanced fork of BMAD-METHOD - Breakthrough Method of Agile AI-driven Development with robust versioning and unified validation.
314 lines (231 loc) • 6.36 kB
Markdown
# JIRA Wiki Converter Utility
## Purpose
Automatically converts Markdown content to JIRA Wiki Markup format, ensuring professional appearance in JIRA while allowing users to write in familiar Markdown syntax.
## Core Conversion Rules
[[LLM: When converting content for JIRA, apply these transformations in order:
### 1. Headers
```
# Header 1 → h1. Header 1
## Header 2 → h2. Header 2
### Header 3 → h3. Header 3
#### Header 4 → h4. Header 4
##### Header 5 → h5. Header 5
###### Header 6 → h6. Header 6
```
### 2. Text Formatting
```
**bold** → *bold*
*italic* → _italic_
***bold italic*** → *_bold italic_*
~~strikethrough~~ → -strikethrough-
`inline code` → {{inline code}}
```
### 3. Lists
```
* Item → * Item
- Item → * Item
* Nested → * Nested
- Nested → * Nested
1. Number → # Number
2. Number → # Number
1. Nested → ## Nested
2. Nested → ## Nested
```
### 4. Code Blocks
````
```language → {code:language}
code content → code content
``` → {code}
``` → {code}
code content → code content
``` → {code}
````
### 5. Links
```
[text](url) → [text|url]
[PROJ-123] → [PROJ-123] (no change - JIRA issue links)
@username → [~username]
```
### 6. Special Elements
```
> Quote → {quote}Quote{quote}
--- → ----
___ → ----
*** → ----
```
### 7. Tables
```
| Header 1 | Header 2 | → ||Header 1||Header 2||
|----------|----------| → (remove separator line)
| Cell 1 | Cell 2 | → |Cell 1|Cell 2|
```
### 8. Task Lists
```
- [ ] Task → * [ ] Task
- [x] Done → * [x] Done
```
]]
## Conversion Function
[[LLM: When converting content:
1. **Process in order**: Apply rules from top to bottom to avoid conflicts
2. **Preserve structure**: Maintain indentation and spacing
3. **Handle edge cases**:
- Code blocks take precedence (don't convert content inside)
- Preserve JIRA issue references (PROJECT-123)
- Keep URLs intact in link conversions
- Maintain list hierarchy with proper indentation
Example conversion:
````
INPUT (Markdown):
## Problem Statement
The **authentication system** has a `critical` bug where users can't reset passwords.
### Steps to Reproduce
1. Click "Forgot Password"
2. Enter email
3. Submit form
### Code Example
```javascript
function resetPassword(email) {
// This fails
return api.reset(email);
}
````
### Related Issues
- [AUTH-123]
- See [documentation](https://docs.example.com)
OUTPUT (JIRA Wiki):
h2. Problem Statement
The _authentication system_ has a {{critical}} bug where users can't reset passwords.
h3. Steps to Reproduce
# Click "Forgot Password"
# Enter email
# Submit form
h3. Code Example
{code:javascript}
function resetPassword(email) {
// This fails
return api.reset(email);
}
{code}
h3. Related Issues
- [AUTH-123]
- See [documentation|https://docs.example.com]
```
]]
## Preview Mode
[[LLM: When sync includes preview option:
1. Show side-by-side comparison:
```
ORIGINAL (Markdown) → CONVERTED (Wiki Markup)
─────────────────────────────────────────────────────
## Epic Overview → h2. Epic Overview
Implement **user auth** → Implement _user auth_
```
2. Highlight conversion points with color coding
3. Allow user to confirm before proceeding
]]
## Bulk Conversion Support
[[LLM: For multiple stories/issues:
1. Convert all descriptions and comments
2. Show summary: "Converting 12 issues from Markdown to Wiki Markup..."
3. Track conversion statistics:
- Headers converted: 45
- Code blocks: 8
- Links reformatted: 23
4. Offer to preview first 3 before bulk apply
]]
## Error Handling
[[LLM: Handle these edge cases:
1. **Nested formatting**: `**bold with `code` inside**`
- Convert outer formatting first
- Preserve inner code blocks
2. **Mixed lists**: Markdown allows *, -, + for bullets
- Normalize all to * in wiki markup
3. **Fenced code without language**:
- Use {code} without language parameter
4. **Multiple line quotes**:
```
> Line 1
> Line 2
> Line 3
```
Becomes:
```
{quote}
Line 1
Line 2
Line 3
{quote}
```
]]
## Integration Points
### sync.md Integration
[[LLM: In sync operations:
1. Before creating/updating JIRA issues
2. Apply conversion to description field
3. Apply to all comments being synced
4. Log conversion activity
]]
### report.md Integration
[[LLM: When generating reports:
1. Use wiki markup for JIRA display
2. Keep markdown for file storage
3. Allow format selection via parameter
]]
## Quality Assurance
[[LLM: After conversion:
1. Verify no markdown syntax remains
2. Check all JIRA references intact
3. Ensure code blocks properly closed
4. Validate table structure
5. Test links are clickable
]]
## Usage Examples
### Simple Conversion
```
User: "sync story with proper formatting"
System: "Converting description to JIRA Wiki Markup...
- 3 headers converted
- 2 code blocks formatted
- 5 links updated
✓ Ready to sync with professional formatting"
```
### Bulk Epic Sync
```
User: "sync epic to jira"
System: "Preparing Epic sync...
📝 Converting 11 stories from Markdown to Wiki Markup
Preview first story? (y/n)"
```
### Format Validation
```
User: "check jira formatting"
System: "Analyzing current format...
⚠️ Found 3 Markdown elements that need conversion:
- Line 23: ## Header (should be h2.)
- Line 45: **bold** (should be _bold_)
- Line 67: `code` (should be {code}...{code})
Convert now? (y/n)"
```
## Performance Notes
[[LLM: For large conversions:
1. Process in chunks of 10 issues
2. Show progress indicator
3. Cache converted content
4. Allow incremental conversion
]]
## Testing Checklist
[[LLM: Verify these conversions work correctly:
- [ ] Headers (all 6 levels)
- [ ] Bold, italic, strikethrough
- [ ] Inline code and code blocks
- [ ] Ordered and unordered lists
- [ ] Nested lists (3 levels deep)
- [ ] Links (external and JIRA)
- [ ] Tables with headers
- [ ] Multi-line quotes
- [ ] Task lists with checkboxes
- [ ] Horizontal rules
- [ ] Mixed formatting combinations
]]
```