cc-agentic-framework 1.14.1

package/framework/modules/jira/skills/jira/integrating-jira/CONFLUENCE-PATTERNS.md

@@ -0,0 +1,284 @@
+# Confluence Integration Patterns
+
+## Architecture Overview
+
+**Components:**
+1. **Confluence REST API v2** - Modern API for page CRUD
+2. **ADF Converter** - Atlassian Document Format ↔ Markdown
+3. **Metadata Manager** - YAML frontmatter + Confluence metadata
+4. **TypeScript CLI** - Module-based CLI commands
+
+**Workflow:**
+```
+1. CREATE/UPDATE: Markdown → Confluence
+   Local markdown → Confluence pages (via API)
+
+2. FETCH: Confluence → Markdown
+   Confluence pages → Local markdown (with metadata)
+```
+
+---
+
+## Create/Update Workflow (Markdown → Confluence)
+
+**CLI Command:** `agentic-framework confluence create-page`
+
+### Quick Start
+```bash
+# Create or update Confluence page from markdown
+agentic-framework confluence create-page <markdown-file> --space WA
+
+# With explicit parent page
+agentic-framework confluence create-page <markdown-file> --space WA --parent-id 123456
+```
+
+### Supported Elements
+- Headers (h1-h6)
+- Paragraphs
+- Lists (bulleted, numbered, unlimited nesting)
+- Code blocks with syntax highlighting
+- Inline code
+- Bold, italic, strikethrough
+- Links (internal and external)
+- Tables
+- Blockquotes
+- Horizontal rules
+
+### Metadata Requirements
+Include YAML frontmatter in markdown:
+
+```yaml
+---
+confluence-pageId: null  # null for CREATE, "123456" for UPDATE
+confluence-url: null  # Auto-populated after creation
+confluence-space: "WA"
+confluence-parent: "393217"  # Parent page ID
+confluence-page-revision: null  # Auto-managed for optimistic locking
+title: "Page Title"
+tags:
+  - apm-r
+  - documentation
+---
+
+# Page Content
+
+Your markdown content here...
+```
+
+### 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
+
+### Best Practices
+- Use proper markdown structure (avoid HTML)
+- Test nested lists (unlimited depth supported)
+- Include parent page ID for proper organization
+- Use YAML frontmatter for Confluence metadata
+- Validate rendered output in Confluence before finalizing
+
+---
+
+## Fetch Workflow (Confluence → Markdown)
+
+**CLI Command:** `agentic-framework confluence fetch-page`
+
+### Quick Start
+```bash
+# Fetch Confluence page to markdown
+agentic-framework confluence fetch-page <page-id> --output <file>
+
+# Fetch and save to specific location
+agentic-framework confluence fetch-page 393217 --output docs/architecture.md
+```
+
+### What It Does
+1. Fetches Confluence page via REST API v2
+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
+title: "Page Title"
+---
+```
+
+---
+
+## Confluence REST API v2 Reference
+
+**Base URL:** `https://{your-org}.atlassian.net/wiki/api/v2`
+
+### Common Endpoints
+
+**Fetch Page:**
+```
+GET /pages/{id}
+```
+Returns: Page content in ADF storage format + metadata
+
+**Create Page:**
+```
+POST /pages
+Body: {
+  "spaceId": "...",
+  "title": "...",
+  "type": "page",
+  "body": {
+    "representation": "storage",
+    "value": "<page-content-adf>"
+  }
+}
+```
+
+**Update Page:**
+```
+PUT /pages/{id}
+Body: {
+  "version": {
+    "number": 2
+  },
+  "title": "...",
+  "body": {
+    "representation": "storage",
+    "value": "<updated-adf>"
+  }
+}
+```
+
+**List Pages in Space:**
+```
+GET /spaces/{key}/pages
+Query: ?limit=50&status=current
+```
+
+### Rate Limits
+- 10 requests/second
+- Use exponential backoff for retries
+- CLI handles rate limiting automatically
+
+---
+
+## ADF (Atlassian Document Format)
+
+### Structure Overview
+ADF is JSON-based markup used by Confluence:
+
+```json
+{
+  "version": 1,
+  "type": "doc",
+  "content": [
+    {
+      "type": "heading",
+      "attrs": {"level": 1},
+      "content": [
+        {"type": "text", "text": "My Heading"}
+      ]
+    },
+    {
+      "type": "paragraph",
+      "content": [
+        {"type": "text", "text": "Body text with "},
+        {"type": "text", "text": "bold", "marks": [{"type": "strong"}]},
+        {"type": "text", "text": "."}
+      ]
+    }
+  ]
+}
+```
+
+### Common Node Types
+- `doc` - Document root
+- `heading` - Headers (level 1-6)
+- `paragraph` - Text paragraphs
+- `bulletList` - Unordered lists
+- `orderedList` - Numbered lists
+- `listItem` - List items (nested under bulletList/orderedList)
+- `codeBlock` - Code blocks with language
+- `inlineCode` - Inline code
+- `table` - Table element
+- `blockquote` - Block quotes
+
+### Text Marks
+- `strong` - Bold
+- `em` - Italic
+- `strike` - Strikethrough
+- `code` - Inline code
+
+---
+
+## Markdown → ADF Conversion
+
+**CLI handles conversion automatically:**
+
+| Markdown | ADF Node Type |
+|----------|---------------|
+| `# H1` | `heading` (level: 1) |
+| `## H2` | `heading` (level: 2) |
+| `**bold**` | `text` with `strong` mark |
+| `*italic*` | `text` with `em` mark |
+| `- list` | `bulletList` with `listItem` |
+| `1. ordered` | `orderedList` with `listItem` |
+| `[link](url)` | `text` with `link` mark |
+| `` `code` `` | `text` with `code` mark |
+| ` ```lang ``` ` | `codeBlock` with language |
+
+---
+
+## Authentication
+
+**Method:** Basic Auth via `.env` file
+
+```
+CONFLUENCE_URL=https://{your-org}.atlassian.net/wiki
+CONFLUENCE_USERNAME=your-email@example.com
+CONFLUENCE_API_TOKEN=your-api-token
+```
+
+**Generate API Token:** https://id.atlassian.com/manage-profile/security/api-tokens
+
+---
+
+## TypeScript CLI Commands Reference
+
+| Task | Command | Module |
+|------|---------|--------|
+| **Create/update page** | `confluence create-page <file> --space <id>` | confluence |
+| **Fetch page** | `confluence fetch-page <id> --output <file>` | confluence |
+| **List pages in space** | `confluence list-pages --space <id>` | confluence |
+
+**No Python Scripts:**
+- ❌ `python src/confluence/create_page.py` (doesn't exist)
+- ❌ `python src/confluence/fetch_page.py` (doesn't exist)
+- ✅ TypeScript CLI commands (implemented in confluence module)
+
+---
+
+## Troubleshooting
+
+### API Errors
+- **401:** Invalid credentials. Check authentication in `.env`
+- **403:** Insufficient permissions. Verify user role in space
+- **404:** Page not found. Confirm page ID and space key
+- **429:** Rate limit exceeded. CLI retries with exponential backoff
+
+### Conversion Errors
+- **Complex tables:** Simplify or split into multiple tables
+- **Custom HTML:** Convert to native markdown before exporting
+- **Large files:** Split into multiple pages with links
+- **Macros:** Document non-convertible Confluence macros in comments
+
+---
+
+**Version:** 1.0 (adapted for TypeScript CLI)
+**Created:** 2025-12-22
+**Status:** Production-Ready (Phase 3 Migration)
+**Confluence API Version:** 2.0
+**ADF Version:** 1.0

package/framework/modules/jira/skills/jira/integrating-jira/CONVERSION-RULES.md

@@ -0,0 +1,188 @@
+# Markup Conversion Rules
+
+**Purpose:** Bidirectional conversion rules between Markdown, Jira wiki markup, and Confluence ADF
+**Scope:** Generic rules (reusable across systems)
+**Token Budget:** ~250 tokens (lean reference)
+
+---
+
+## Markdown → Jira Wiki Markup
+
+| Markdown | Jira Markup | Notes |
+|----------|-------------|-------|
+| `# Heading 1` | `h1. Heading 1` | Top-level header |
+| `## Heading 2` | `h2. Heading 2` | Section header |
+| `### Heading 3` | `h3. Heading 3` | Subsection header |
+| `**bold**` | `*bold*` | Bold emphasis |
+| `*italic*` | `_italic_` | Italic emphasis |
+| `- List item` | `* List item` | Unordered list |
+| `  - Nested` | `** Nested` | Nested bullet (2 asterisks) |
+| `1. Ordered` | `# Ordered` | Ordered list |
+| `  1. Nested` | `## Nested` | Nested ordered (2 hashes) |
+| `[Text](url)` | `[Text\|url]` | Hyperlink |
+| `` `[DAPM-123](...)` `` | `[DAPM-123\|smart-link]` | Jira ticket link |
+| `` `code` `` | `{{code}}` | Inline code |
+| ` ```lang ``` ` | `{code:lang}...{code}` | Code block |
+| `> Quote` | `{quote}...{quote}` | Block quote |
+| `---` | `----` | Horizontal rule |
+| `**Term:** Definition` | `*Term:* Definition` | Definition list |
+
+---
+
+## Jira Wiki Markup → Markdown
+
+| Jira Markup | Markdown | Notes |
+|-------------|----------|-------|
+| `h1. Heading` | `# Heading` | Top-level |
+| `h2. Heading` | `## Heading` | Section |
+| `h3. Heading` | `### Heading` | Subsection |
+| `*bold*` | `**bold**` | Bold |
+| `_italic_` | `*italic*` | Italic |
+| `* List` | `- List` | Unordered |
+| `** Nested` | `  - Nested` | Nested (2 spaces) |
+| `# Ordered` | `1. Ordered` | Ordered |
+| `## Nested` | `  1. Nested` | Nested ordered |
+| `[Text\|url]` | `[Text](url)` | Link |
+| `[DAPM-123\|smart-link]` | `` `[DAPM-123](jira-url)` `` | Jira link |
+| `{{code}}` | `` `code` `` | Inline code |
+| `{code:lang}` | ` ```lang ``` ` | Code block |
+| `{quote}` | `> Quote` | Block quote |
+
+---
+
+## Markdown → Confluence ADF (JSON Structure)
+
+**Principle:** Confluence uses JSON-based Atlassian Document Format (ADF)
+
+| Markdown | ADF Node Type | Structure Example |
+|----------|---------------|-------------------|
+| `# Heading` | `heading` | `{"type":"heading","attrs":{"level":1},"content":[...]}` |
+| `**bold**` | `strong` mark | `{"type":"text","marks":[{"type":"strong"}]}` |
+| `*italic*` | `em` mark | `{"type":"text","marks":[{"type":"em"}]}` |
+| `- List` | `bulletList` + `listItem` | Nested node structure |
+| `1. List` | `orderedList` + `listItem` | Nested node structure |
+| `[Link](url)` | `link` mark | `{"type":"link","attrs":{"href":"url"}}` |
+| ` ```code ``` ` | `codeBlock` | `{"type":"codeBlock","attrs":{"language":"lang"}}` |
+| `` `code` `` | `inlineCode` mark | `{"type":"text","marks":[{"type":"code"}]}` |
+| `> Quote` | `blockquote` | `{"type":"blockquote","content":[...]}` |
+| `\|Col1\|Col2\|` | `table` | Table with `tableRow` and `tableCell` |
+
+---
+
+## Confluence Storage Format → Markdown
+
+**Export from Confluence:**
+1. Fetch content via REST API v2 (returns ADF in storage format)
+2. Parse ADF JSON structure
+3. Convert to Markdown following reverse rules above
+
+**Common Patterns:**
+- Confluence tables → Markdown tables (`| col1 | col2 |`)
+- Confluence panels → Markdown blockquotes (`>`)
+- Confluence macros → Comment with explanation (no direct equivalent)
+
+---
+
+## Conversion Best Practices
+
+### When Exporting to Jira/Confluence
+1. **Test conversion** - Always validate output before finalizing
+2. **Handle edge cases** - Nested lists, tables, code blocks need special attention
+3. **Preserve links** - Ensure internal links remain valid after conversion
+4. **Strip unsupported syntax** - Remove Markdown features not supported in target format
+5. **Validate output** - Check rendered version in Jira/Confluence
+
+### When Importing from Jira/Confluence
+1. **Parse carefully** - Jira wiki markup has subtle syntax differences
+2. **Preserve formatting** - Maintain bold, italic, lists, code blocks
+3. **Convert links** - Transform Jira smart-links to Markdown links (include full URL)
+4. **Handle special cases** - Jira panels, Confluence macros may need manual conversion
+5. **Clean output** - Remove unnecessary markup artifacts
+
+---
+
+## Common Gotchas
+
+### Jira Conversion
+- ⚠️ Jira uses `*bold*` (1 asterisk), Markdown uses `**bold**` (2 asterisks)
+- ⚠️ Jira links use pipe `|`, Markdown uses parentheses `()`
+- ⚠️ Nested lists in Jira use `**` for second level, Markdown uses indentation
+- ⚠️ Code blocks must close with `{code}`, not just fence
+- ⚠️ Smart-links require exact issue key format (e.g., `DAPM-123`)
+
+### Confluence Conversion
+- ⚠️ ADF is JSON-based, not text-based markup
+- ⚠️ Requires proper JSON structure with node types and marks
+- ⚠️ Complex layouts (columns, tables) need careful ADF structure
+- ⚠️ Macros (status, info panels) have no direct Markdown equivalent
+- ⚠️ Content must be wrapped in `{"version":1,"type":"doc","content":[...]}`
+
+---
+
+## Example Conversion
+
+**Markdown Input:**
+```markdown
+## Story Requirements
+
+**Background:** We need to add filtering.
+
+**Requirements:**
+- Filter by component type
+- Filter by severity
+- Maintain URL state
+
+**Technical Notes:**
+- Use Zustand store pattern
+- Follow V2.1 data layer
+- See documentation for details
+
+**Related:** [DAPM-1234](https://jira.example.com/DAPM-1234)
+```
+
+**Jira Wiki Markup Output:**
+```
+h2. Story Requirements
+
+*Background:* We need to add filtering.
+
+*Requirements:*
+* Filter by component type
+* Filter by severity
+* Maintain URL state
+
+*Technical Notes:*
+* Use Zustand store pattern
+* Follow V2.1 data layer
+* See documentation for details
+
+*Related:* [DAPM-1234|smart-link]
+```
+
+**Confluence ADF (Simplified):**
+```json
+{
+  "version": 1,
+  "type": "doc",
+  "content": [
+    {
+      "type": "heading",
+      "attrs": {"level": 2},
+      "content": [{"type": "text", "text": "Story Requirements"}]
+    },
+    {
+      "type": "paragraph",
+      "content": [
+        {"type": "text", "text": "Background: ", "marks": [{"type": "strong"}]},
+        {"type": "text", "text": "We need to add filtering."}
+      ]
+    }
+  ]
+}
+```
+
+---
+
+**Version:** 1.0
+**Last Updated:** 2025-12-22
+**Supports:** Jira Cloud, Confluence Cloud, Markdown v1.0