cc-agentic-framework 1.14.1

package/framework/modules/jira/skills/jira/integrating-jira/SKILL.md

@@ -0,0 +1,412 @@
+---
+id: integrating-jira
+module: jira
+name: integrating-jira
+description: Integrate Jira and Confluence with markdown conversion using TypeScript CLI. Use when exporting/importing tickets, syncing documentation, or converting between Jira wiki markup, Confluence ADF, and markdown formats.
+scope: project-specific
+applicable-projects: agentic-development-framework
+capabilities-provided:
+  - integrating-jira
+  - jira-integration
+  - jira-confluence-sync
+  - markdown-conversion
+---
+
+# Jira-Confluence Integration
+
+## When to Use This Skill
+
+You're working with **ticket management and documentation** and need to:
+
+**Jira Workflows:**
+- **CREATE:** Export new markdown tickets to Jira
+- **UPDATE:** Modify existing Jira tickets from local markdown (auto-detects)
+- **IMPORT:** Pull Jira sprint/milestone data back into markdown
+- **Troubleshoot:** Jira integration failures or API issues
+
+**Confluence Workflows:**
+- Sync markdown documentation with Confluence pages
+- Convert between markdown and Confluence ADF format
+- Publish documentation to Confluence
+
+**General:**
+- Manage field mappings for project-specific configuration
+- Convert between markdown, Jira wiki markup, and Confluence ADF formats
+
+**Example invocations:**
+- "Use integrating-jira to export tickets to Jira"
+- "Use integrating-jira to publish documentation to Confluence"
+- "Use integrating-jira to import Jira sprint data"
+
+---
+
+## Architecture: Modular Design
+
+**TypeScript CLI Commands (NOT Python Scripts):**
+
+| Module | Purpose | CLI Commands |
+|--------|---------|--------------|
+| **Jira Module** | Jira integration | `jira export` |
+| **Backlog Module** | Ticket management | `backlog import`, `backlog validate` |
+| **Confluence Module** | Documentation | `confluence create-page`, `confluence fetch-page` |
+
+**Key Point:** Old framework used Python scripts (`export_to_jira.py`, `import_jira_data.py`, `create_page.py`). New framework uses TypeScript CLI exclusively.
+
+---
+
+## Quick Start
+
+### CREATE: Export New Tickets to Jira
+
+```bash
+# Validate ticket format first
+agentic-framework backlog validate
+
+# Export to Jira (auto-detects CREATE mode if jira-ticketId is null)
+agentic-framework jira export --tickets <ticket-file>
+
+# Dry-run to preview without creating
+agentic-framework jira export --tickets <ticket-file> --dry-run
+```
+
+**Output:** New issue created in Jira, YAML updated with `jira-ticketId` and `jira-url`
+
+### UPDATE: Modify Existing Jira Tickets
+
+```bash
+# Modify ticket locally (change content, acceptance criteria, etc.)
+
+# Export to Jira (auto-detects UPDATE mode if jira-ticketId exists)
+agentic-framework jira export --tickets 1234-ticket.md
+```
+
+**AUTO-DETECT Mode:**
+- If `jira-ticketId: null` or missing → CREATE new Jira issue
+- If `jira-ticketId: DAPM-1234` → UPDATE existing Jira issue
+
+### IMPORT: Pull Jira Data Back to Markdown
+
+```bash
+# Export sprint/milestone from Jira as CSV (via Jira UI)
+
+# Import CSV to create markdown tickets
+agentic-framework backlog import --csv jira-export.csv
+```
+
+**Output:** Markdown tickets created with Jira metadata preserved
+
+### Sync Confluence Pages
+
+```bash
+# Create/update Confluence page from markdown
+agentic-framework confluence create-page <markdown-file> --space WA
+
+# Fetch Confluence page to markdown
+agentic-framework confluence fetch-page <page-id> --output <file>
+```
+
+---
+
+## Jira Integration (Detailed)
+
+### Export Workflow (Markdown → Jira)
+
+**Step 1: Validate Ticket**
+```bash
+agentic-framework backlog validate
+```
+
+**Step 2: Export to Jira**
+```bash
+# CREATE mode (jira-ticketId is null)
+agentic-framework jira export --tickets auth0-sso-configuration.md
+
+# Result:
+# - New Jira ticket created (DAPM-1234)
+# - YAML updated: jira-ticketId: DAPM-1234, jira-url: https://...
+# - Markdown → Jira wiki markup conversion
+```
+
+**Step 3: Verify in Jira**
+- Check ticket created in Jira project
+- Verify metadata (component, labels, epic link)
+- Confirm acceptance criteria converted correctly
+
+**Format Conversion (Markdown → Jira Wiki):**
+```markdown
+# Markdown
+## Heading 2
+**bold text**
+- Bullet list
+`code inline`
+
+# Jira Wiki Markup
+h2. Heading 2
+*bold text*
+* Bullet list
+{{code inline}}
+```
+
+### Import Workflow (Jira → Markdown)
+
+**Step 1: Export from Jira**
+- Use Jira UI to export sprint/milestone as CSV
+- Save CSV file locally
+
+**Step 2: Import CSV**
+```bash
+agentic-framework backlog import --csv jira-sprint-export.csv
+```
+
+**Step 3: Generated Output**
+- Markdown tickets created in backlog module
+- YAML frontmatter with exact Jira metadata
+- Jira wiki markup → markdown conversion
+- Filename: `[NUMBER]-[title-kebab-case].md`
+
+**YAML Metadata Preserved:**
+```yaml
+---
+jira-ticketId: DAPM-1234
+jira-url: "https://{your-org}.atlassian.net/browse/PROJ-1234"
+jira-component: "APM:  Reliability App - Frontend"  # Exact from Jira
+jira-parent: DAPM-1171
+framework-type: story
+framework-milestone: Feb2026
+---
+```
+
+---
+
+## Confluence Integration (Detailed)
+
+### Publish Markdown to Confluence
+
+**Command:**
+```bash
+agentic-framework confluence create-page <markdown-file> --space WA
+```
+
+**What it does:**
+1. Reads markdown file with Confluence metadata
+2. Converts markdown → Confluence ADF (Atlassian Document Format)
+3. Creates or updates page in Confluence space
+4. Stores page ID and version in YAML frontmatter
+
+**Markdown → ADF Conversion:**
+```markdown
+# Markdown
+## Heading 2
+**bold text**
+[link](https://example.com)
+
+# ADF (JSON structure)
+{
+  "type": "heading",
+  "attrs": {"level": 2},
+  "content": [{"type": "text", "text": "Heading 2"}]
+}
+{
+  "type": "text",
+  "text": "bold text",
+  "marks": [{"type": "strong"}]
+}
+{
+  "type": "text",
+  "text": "link",
+  "marks": [{"type": "link", "attrs": {"href": "https://example.com"}}]
+}
+```
+
+### Fetch Confluence Page to Markdown
+
+**Command:**
+```bash
+agentic-framework confluence fetch-page <page-id> --output <file>
+```
+
+**What it does:**
+1. Fetches Confluence page via REST API
+2. Converts ADF → markdown
+3. Saves to local markdown file with Confluence metadata
+
+**YAML Metadata:**
+```yaml
+---
+confluence-pageId: "123456"
+confluence-url: "https://{your-org}.atlassian.net/wiki/spaces/PROJ/pages/123456"
+confluence-space: "WA"
+confluence-page-revision: 5
+---
+```
+
+---
+
+## Format Conversions
+
+### Markdown ↔ Jira Wiki Markup
+
+| Markdown | Jira Wiki |
+|----------|-----------|
+| `# H1` | `h1. H1` |
+| `## H2` | `h2. H2` |
+| `**bold**` | `*bold*` |
+| `*italic*` | `_italic_` |
+| `- list` | `* list` |
+| `[link](url)` | `[link\|url]` |
+| `` `code` `` | `{{code}}` |
+
+### Markdown ↔ Confluence ADF
+
+| Markdown | ADF Node Type |
+|----------|---------------|
+| `# H1` | `heading` (level: 1) |
+| `**bold**` | `text` with `strong` mark |
+| `- list` | `bulletList` with `listItem` |
+| `[link](url)` | `text` with `link` mark |
+| `` `code` `` | `text` with `code` mark |
+
+---
+
+## TypeScript CLI Commands Reference
+
+| Task | Command | Module |
+|------|---------|--------|
+| **Validate ticket** | `backlog validate` | backlog |
+| **Export to Jira (CREATE/UPDATE)** | `jira export --tickets <file>` | jira |
+| **Sync local to Jira** | `jira sync --from-file <file>` | jira |
+| **Sync Jira to local** | `jira sync --from-jira <key> -o <file>` | jira |
+| **Import from Jira CSV** | `backlog import --csv <file>` | backlog |
+| **Create Confluence page** | `confluence create-page <file> --space <id>` | confluence |
+| **Fetch Confluence page** | `confluence fetch-page <id> --output <file>` | confluence |
+| **Dry-run Jira export** | `jira export --tickets <file> --dry-run` | jira |
+| **Dry-run Jira sync** | `jira sync --from-file <file> --dry-run` | jira |
+| **Force sync (override conflicts)** | `jira sync --from-file <file> --force` | jira |
+
+**No Python Scripts:**
+- ❌ `python src/jira/export_to_jira.py` (doesn't exist)
+- ❌ `python src/backlog/import_jira_data.py` (doesn't exist)
+- ❌ `python src/confluence/create_page.py` (doesn't exist)
+- ✅ TypeScript CLI commands (implemented in modules)
+
+---
+
+## Common Patterns
+
+### Pattern 1: Continuous Export Workflow
+
+**When:** Regular ticket creation from backlog to Jira
+
+1. Create ticket with backlog module (YAML metadata)
+2. Validate: `backlog validate`
+3. Export: `jira export --tickets <file>` (AUTO-DETECT CREATE mode)
+4. Result: Jira ticket created, YAML updated
+
+### Pattern 2: Sprint Import & Sync
+
+**When:** Importing completed sprint from Jira back to documentation
+
+1. Export sprint CSV from Jira UI
+2. Import: `backlog import --csv <file>`
+3. Result: Markdown tickets created with Jira metadata
+
+### Pattern 3: Documentation Sync (Confluence)
+
+**When:** Syncing technical documentation with Confluence
+
+1. Author `.md` file with Confluence metadata
+2. Publish: `confluence create-page <file> --space WA`
+3. Result: Page created/updated in Confluence
+
+### Pattern 4: Bi-Directional Sync
+
+**When:** Need to sync changes both ways (Jira ↔ Local ↔ Confluence)
+
+1. Import Jira data: `backlog import --csv <file>`
+2. Modify locally in markdown
+3. Export back to Jira: `jira export --tickets <file>` (AUTO-DETECT UPDATE mode)
+4. Publish docs to Confluence: `confluence create-page <file> --space WA`
+
+---
+
+## Best Practices
+
+### Jira Export
+✅ **DO:**
+- Validate with `backlog validate` before export
+- Use dry-run mode to preview changes
+- Preserve exact Jira component names
+- Let AUTO-DETECT mode handle CREATE vs UPDATE
+
+❌ **DON'T:**
+- Manually edit `jira-ticketId` field
+- Transform Jira component names
+- Skip validation
+
+### Jira Import
+✅ **DO:**
+- Export sprint/milestone as CSV from Jira
+- Preserve exact Jira field values
+- Use import CLI for batch operations
+
+❌ **DON'T:**
+- Manually create markdown files for Jira tickets
+- Modify Jira ticket IDs
+- Skip metadata preservation
+
+### Confluence Sync
+✅ **DO:**
+- Use YAML frontmatter for Confluence metadata
+- Let CLI handle ADF conversion
+- Track page version for optimistic locking
+
+❌ **DON'T:**
+- Manually write ADF JSON
+- Skip version tracking (causes conflicts)
+- Bypass CLI for page creation
+
+---
+
+## Troubleshooting
+
+**Issue:** Export fails with "Component not found"
+- **Cause:** Component name doesn't match Jira exactly
+- **Solution:** Check YAML `jira-component` field has exact spacing/punctuation
+
+**Issue:** Import creates duplicate tickets
+- **Cause:** Jira ticket ID not preserved
+- **Solution:** Ensure CSV includes Issue key column, import CLI will use it
+
+**Issue:** Confluence page creation fails
+- **Cause:** Missing space permissions or invalid markdown
+- **Solution:** Check Confluence space permissions, validate markdown syntax
+
+**Issue:** Format conversion errors
+- **Cause:** Complex markdown not supported by converter
+- **Solution:** Simplify markdown, use supported syntax from conversion tables
+
+---
+
+## See Also
+
+### Related Skills
+- [organizing-backlog](../../../../backlog/skills/backlog/organizing-backlog/SKILL.md) - Backlog module architecture and CLI
+- [committing-code](../../../../core/skills/committing-code/SKILL.md) - Git workflows with Jira auto-detection
+- [building-tickets](../../../../backlog/skills/backlog/building-tickets/SKILL.md) - v10.1.1 YAML format
+
+### Module Documentation
+- **Jira Module:** `framework/modules/jira/module.json` - Jira CLI commands and capabilities
+- **Backlog Module:** `framework/modules/backlog/module.json` - Backlog CLI commands
+- **Confluence Module:** `framework/modules/confluence/module.json` - Confluence CLI commands
+
+### TypeScript CLI Source
+- Jira export: `framework/modules/jira/src/cli/export.ts`
+- Backlog import: `framework/modules/backlog/src/cli/import.ts`
+- Confluence pages: `framework/modules/confluence/src/cli/`
+
+---
+
+**Version:** 1.0 (adapted from v1 repo)
+**Created:** 2025-12-22
+**Status:** Production-Ready (Phase 3 Migration)
+**Original:** `apmr-integrating-integrating-jira` (v1 repo)