cc-agentic-framework 1.14.1

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

@@ -0,0 +1,406 @@
+# Integration Examples & Scenarios
+
+---
+
+## Example 1: Export User Story to Jira
+
+### Scenario
+You have a ticket created in the backlog module that's ready to export to Jira.
+
+### Step 1: Prepare Markdown Story
+
+**File:** Local ticket with proper YAML frontmatter
+
+```markdown
+---
+jira-ticketId: null
+jira-url: null
+jira-component: "APM: Reliability App - Frontend"
+jira-parent: null
+framework-type: story
+framework-milestone: Nov2025
+framework-priority: P1
+title: "Add Email Login Form to Dashboard"
+assignee: "user@example.com"
+storyPoints: 8
+tags:
+  - apm-r
+  - apm-r-fe
+  - apm-r-feature
+---
+
+## Background
+Users currently log in via SSO only. We need to support email/password authentication for development and testing environments.
+
+## Acceptance Criteria
+- [ ] User can enter email and password in form
+- [ ] Form validates email format before submission
+- [ ] Password field masks input
+- [ ] Submit button disabled until both fields filled
+- [ ] Error message shown for invalid credentials
+- [ ] Session persists for 24 hours after login
+- [ ] "Remember Me" checkbox available
+- [ ] Logout clears session and redirects to login
+
+## Technical Notes
+- Use Zustand store pattern for auth state
+- Follow V2.1 data layer conventions
+- Component: `LoginForm.tsx` in `apps/dashboard/src/components/`
+- Tests: Jest unit tests + Cypress E2E tests
+
+## Related Issues
+- Blocks: DAPM-999 Dashboard integration
+- Related to: DAPM-998 Auth service API
+```
+
+### Step 2: Validate Ticket Format
+
+```bash
+agentic-framework backlog validate
+```
+
+### Step 3: Run Export to Jira
+
+```bash
+agentic-framework jira export --tickets user-login-form.md
+```
+
+### Step 4: Verify in Jira
+
+1. Go to your Jira instance
+2. Find new issue: **DAPM-1234: Add Email Login Form to Dashboard**
+3. Check:
+   - [ ] Component: APM: Reliability App - Frontend
+   - [ ] Labels/Tags from frontmatter
+   - [ ] Fix Version/Milestone: Nov2025
+   - [ ] Story Points: 8
+   - [ ] Assignee: user@example.com
+   - [ ] Acceptance criteria converted to Jira array
+
+### Result
+- YAML updated with `jira-ticketId: DAPM-1234`
+- YAML updated with `jira-url: https://...`
+- Ready for tracking in Jira
+
+---
+
+## Example 2: Import Jira Sprint to Markdown
+
+### Scenario
+Sprint completed in Jira. Import results back to markdown for documentation and backlog management.
+
+### Step 1: Export Sprint CSV from Jira
+
+1. Go to your Jira project → Backlog → Sprint
+2. Click "Export" → Select CSV format
+3. Save to: `operations/jira-exports/sprint-2025W45.csv`
+
+### Step 2: Run Import CLI
+
+```bash
+agentic-framework backlog import --csv operations/jira-exports/sprint-2025W45.csv
+```
+
+### Step 3: Review Generated Files
+
+**Generated Tickets:** Markdown files with complete YAML metadata
+
+Each markdown file contains:
+- Complete YAML metadata from Jira
+- Converted description (Jira wiki → markdown)
+- Jira ticket ID and link
+- Assignee, status, priority
+
+### Result
+- Multiple markdown files created
+- YAML metadata includes all Jira custom fields
+- Ready for local version control and tracking
+
+---
+
+## Example 3: Sync Technical Documentation to Confluence
+
+### Scenario
+You wrote technical documentation in markdown. Sync it to Confluence space for team collaboration.
+
+### Step 1: Create Markdown with Confluence Metadata
+
+**File:** `docs/authentication-architecture.md`
+
+```markdown
+---
+confluence-pageId: null
+confluence-url: null
+confluence-space: "WA"
+confluence-parent: "393217"
+confluence-page-revision: null
+title: "Authentication Architecture"
+tags:
+  - apm-r
+  - architecture
+  - authentication
+---
+
+# Authentication Architecture
+
+## Overview
+The authentication system supports both SSO and email/password login.
+
+## Components
+
+### AuthService
+Handles token generation, validation, and refresh logic.
+
+```typescript
+interface AuthService {
+  login(credentials: Credentials): Promise<Token>;
+  refresh(token: Token): Promise<Token>;
+  logout(token: Token): Promise<void>;
+}
+```
+
+### Database Schema
+- `users` table with email, hashed password
+- `sessions` table with token and expiry
+
+## Security Considerations
+- Passwords hashed with bcrypt
+- HTTPS only for all auth endpoints
+- CORS headers configured for frontend origin
+
+## Related
+- DAPM-1234 - Implementation story
+```
+
+### Step 2: Run Confluence Create Page
+
+```bash
+agentic-framework confluence create-page docs/authentication-architecture.md --space WA
+```
+
+### Step 3: Verify in Confluence
+
+1. Go to your Confluence instance
+2. Find page: **Authentication Architecture**
+3. Check:
+   - [ ] Parent page set correctly
+   - [ ] Tags applied
+   - [ ] Formatting preserved (code blocks, bold, links)
+   - [ ] Related Jira link renders
+
+### Result
+- Page created in WA space with metadata
+- Page ID stored in YAML frontmatter for future updates
+- confluence-page-revision tracked for optimistic locking
+- Ready for team collaboration and linking from Jira
+
+---
+
+## Example 4: Update Existing Jira Ticket
+
+### Scenario
+Need to update an existing Jira ticket's priority and acceptance criteria.
+
+### Step 1: Edit Local File
+
+```bash
+# File already has jira-ticketId: DAPM-1537
+vim 1537-fe-make-cache-stale-times-configurable.md
+
+# Changes:
+# - Change priority: P1 → P0
+# - Add/update Acceptance Criteria section
+```
+
+### Step 2: Dry-run to Preview
+
+```bash
+agentic-framework jira export --tickets 1537-fe-make-cache-stale-times-configurable.md --dry-run
+```
+
+**Output:** Shows UPDATE payload (priority + acceptance criteria)
+
+### Step 3: Apply Update
+
+```bash
+agentic-framework jira export --tickets 1537-fe-make-cache-stale-times-configurable.md
+```
+
+**Output:** ✅ Issue updated: DAPM-1537
+
+### Result
+- Jira ticket DAPM-1537 updated with new priority and acceptance criteria
+- YAML jira-url refreshed
+- No duplicate ticket created (UPDATE mode auto-detected)
+
+---
+
+## Example 5: Bidirectional Sync (Jira → Markdown → Confluence)
+
+### Full Pipeline
+
+**Step 1: Create in Jira**
+- Story DAPM-1234 created with description
+
+**Step 2: Export to Markdown**
+```bash
+# Export Jira data to CSV first
+agentic-framework backlog import --csv export.csv
+```
+
+**Step 3: Review & Document**
+- Edit markdown locally
+- Add technical notes
+- Enhance acceptance criteria
+
+**Step 4: Update Jira**
+```bash
+# Auto-detects UPDATE mode (jira-ticketId exists)
+agentic-framework jira export --tickets 1234-feature.md
+```
+
+**Step 5: Sync to Confluence**
+- Create documentation markdown based on ticket
+- Add Confluence metadata (confluence-parent, confluence-space)
+- Run export to Confluence
+
+```bash
+agentic-framework confluence create-page feature-design.md --space WA
+```
+
+**Step 6: Link Jira ↔ Confluence**
+- Add link in Jira issue to Confluence page
+- Add backlink in Confluence (via issue link)
+- Team can navigate between systems
+
+### Result
+Single source of truth (markdown) synced bidirectionally:
+- Jira for project management and workflow
+- Markdown for local version control
+- Confluence for technical documentation
+
+---
+
+## Example 6: Troubleshooting Conversion Error
+
+### Scenario
+Export failed with conversion error. Complex nested list in description.
+
+### Problem Markdown
+```markdown
+## Complex Requirements
+
+- Outer item 1
+  - Inner 1.1
+    - Deep 1.1.1
+    - Deep 1.1.2
+  - Inner 1.2
+- Outer item 2
+  - Inner 2.1
+```
+
+### Error
+```
+ConversionError: Unsupported nesting depth in list
+Max depth: 2, Found: 3
+```
+
+### Solution (Simplify Structure)
+
+```markdown
+## Complex Requirements
+
+- Outer item 1
+  - Inner 1.1 (and Deep 1.1.1, Deep 1.1.2)
+  - Inner 1.2
+- Outer item 2
+  - Inner 2.1
+
+**Details:**
+Deep items 1.1.1 and 1.1.2 represent variants of Inner 1.1. See attachment.
+```
+
+### Alternative: Split into Sections
+
+```markdown
+## Requirements - Level 1
+
+- Outer item 1
+- Outer item 2
+
+### Requirements - Level 1.1 (Detail)
+
+For Outer item 1:
+- Inner 1.1
+  - Deep 1.1.1
+  - Deep 1.1.2
+- Inner 1.2
+
+For Outer item 2:
+- Inner 2.1
+```
+
+### Retry Export
+```bash
+agentic-framework jira export --tickets feature.md
+```
+
+---
+
+## Troubleshooting Guide
+
+### Issue: "401 Unauthorized" on Export
+
+**Cause:** Invalid API token or credentials
+
+**Solution:**
+1. Check `.env` has `JIRA_EMAIL` and `JIRA_API_TOKEN`
+2. Regenerate token: https://id.atlassian.com/manage-profile/security/api-tokens
+3. Verify token hasn't expired (tokens are permanent unless revoked)
+4. Check user has access to project
+
+### Issue: "Custom field not found: customfield_10016"
+
+**Cause:** Field ID incorrect for this Jira instance
+
+**Solution:**
+1. Check your Jira instance configuration
+2. Or query Jira API:
+   ```bash
+   curl -H "Authorization: Bearer $TOKEN" \
+     https://your-instance.atlassian.net/rest/api/3/field
+   ```
+3. Update module configuration if needed
+
+### Issue: "Rate limit exceeded (429)"
+
+**Cause:** Too many requests in short time
+
+**Solution:**
+1. CLI handles rate limiting with exponential backoff
+2. Wait and retry
+3. Reduce batch size if exporting many tickets
+
+### Issue: "Conversion failed: Unsupported markup"
+
+**Cause:** Markdown includes unsupported syntax
+
+**Solution:**
+1. See CONVERSION-RULES.md for supported formats
+2. Simplify or rewrite content
+3. Test smaller chunks first
+
+### Issue: "Page not found (404)" on Confluence
+
+**Cause:** Invalid page ID or insufficient permissions
+
+**Solution:**
+1. Verify page ID is correct
+2. Check user has access to Confluence space
+3. Verify space key is correct
+
+---
+
+**Version:** 1.0 (adapted for TypeScript CLI)
+**Created:** 2025-12-22
+**Status:** Production-Ready (Phase 3 Migration)

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

@@ -0,0 +1,284 @@
+# Jira Integration Patterns
+
+## Export Workflow (Markdown → Jira)
+
+**CLI Command:** `agentic-framework jira export`
+
+### Quick Start
+```bash
+# Export single ticket to Jira
+agentic-framework jira export --tickets <ticket-file>
+
+# Dry-run validation (no actual export)
+agentic-framework jira export --tickets <ticket-file> --dry-run
+```
+
+### Features
+- Converts markdown to Jira wiki markup
+- Extracts acceptance criteria as Jira arrays
+- Creates issues via Jira REST API v2
+- Updates YAML metadata with ticket ID and link
+- AUTO-DETECT mode (CREATE vs UPDATE based on jira-ticketId)
+
+### Supported Issue Types
+- Epic
+- Story
+- Task
+- Sub-task
+- Bug
+- Spike
+
+### Required Fields (YAML metadata)
+```yaml
+---
+jira-ticketId: null  # null for CREATE, "DAPM-1234" for UPDATE
+jira-url: null  # Auto-populated after export
+jira-component: "APM: Reliability App - Frontend"
+jira-parent: null  # Epic link (e.g., "DAPM-1000")
+framework-type: story  # or task, bug, epic, spike
+framework-milestone: Nov2025
+framework-priority: P1  # P0, P1, P2, P3
+---
+```
+
+### File Naming Convention
+Handled by backlog module:
+```
+Input:  Local ticket creation
+Output: Backlog module ticket files with jira-ticketId updated
+```
+
+### Acceptance Criteria Extraction
+Markdown format:
+```markdown
+## Acceptance Criteria
+
+- [ ] User can log in with email
+- [ ] Session persists for 24 hours
+- [ ] Password reset works via email
+```
+
+Becomes Jira array (stored in custom field).
+
+---
+
+## UPDATE Workflow (Update Existing Jira Issues)
+
+**CLI Command:** `agentic-framework jira export` (with AUTO-DETECT)
+
+### Quick Start: Auto-Detection
+
+The CLI automatically detects UPDATE mode when `jira-ticketId` exists in YAML:
+
+```bash
+# Auto-detects UPDATE mode (file already has jira-ticketId)
+agentic-framework jira export --tickets 1537-feature.md
+
+# Dry-run to preview changes before updating
+agentic-framework jira export --tickets 1537-feature.md --dry-run
+```
+
+### Features
+- **Smart Auto-Detection:** Detects UPDATE vs CREATE based on `jira-ticketId` field
+- **Partial Field Updates:** Only sends changed fields to Jira
+- **Acceptance Criteria Updates:** Updates acceptance criteria custom field
+- **YAML Updates:** Refreshes `jira-url` and metadata
+
+### Mode Detection Logic
+
+| Condition | Detected Mode | Action |
+|-----------|---------------|--------|
+| `jira-ticketId: DAPM-1234` | UPDATE | PUT `/rest/api/2/issue/DAPM-1234` |
+| `jira-ticketId: null` | CREATE | POST `/rest/api/2/issue` |
+| `jira-ticketId` missing | CREATE | POST `/rest/api/2/issue` |
+
+### YAML Changes for UPDATE
+
+```yaml
+---
+title: "Updated Feature Title"  # Can change
+description: "Updated description"  # Can change
+framework-priority: P0  # Can change
+jira-component: "APM: Reliability App - Backend"  # Can change
+
+# These CANNOT change (immutable in Jira):
+jira-ticketId: DAPM-1234  # Stays the same
+framework-type: task  # Cannot change after creation
+
+# Auto-refreshed on UPDATE:
+jira-url: "https://{your-org}.atlassian.net/browse/PROJ-1234"
+---
+```
+
+### Editable Fields in UPDATE Mode
+
+✅ **Can modify:**
+- title (summary)
+- description
+- priority
+- component
+- acceptance criteria
+- internal notes
+
+❌ **Cannot modify (immutable):**
+- jira-ticketId (project-number)
+- framework-type (story/task/bug/spike/epic)
+- project
+- issuetype
+
+### Real-World Example
+
+**Scenario:** Need to update DAPM-1537's priority and add acceptance criteria
+
+```bash
+# 1. Edit local file
+vim 1537-fe-make-cache-stale-times-configurable.md
+# - Change priority: P1 → P0
+# - Add/update Acceptance Criteria section
+# - Save file
+
+# 2. Dry-run to preview
+agentic-framework jira export --tickets 1537-fe-make-cache-stale-times-configurable.md --dry-run
+
+# Output: Shows UPDATE payload (priority + acceptance criteria)
+# {
+#   "fields": {
+#     "priority": {"name": "Highest"},
+#     "summary": "FE: Make Cache Stale Times...",
+#     "customfield_13608": "* *Verify* criterion 1\n* *Verify* criterion 2"
+#   }
+# }
+
+# 3. Apply update
+agentic-framework jira export --tickets 1537-fe-make-cache-stale-times-configurable.md
+
+# Output: ✅ Issue updated: DAPM-1537
+# Updates YAML jira-url and metadata
+```
+
+### Error Handling
+
+```bash
+# Missing jira-ticketId
+$ agentic-framework jira export --tickets new-task.md
+INFO: No jira-ticketId found, using CREATE mode
+
+# Ticket deleted in Jira (404 error)
+$ agentic-framework jira export --tickets 1537-title.md
+ERROR: UPDATE failed: Ticket DAPM-1537 not found (HTTP 404)
+  Possible causes: Ticket was deleted or ID is incorrect
+  Solution: Set jira-ticketId to null to create new ticket
+
+# Invalid ticket ID format
+$ agentic-framework jira export --tickets bad-id.md
+ERROR: Invalid ticket ID format 'INVALID'
+  Expected format: PROJECT-NNNN (like DAPM-1234)
+```
+
+---
+
+## Import Workflow (Jira → Markdown)
+
+**CLI Command:** `agentic-framework backlog import`
+
+### Quick Start
+```bash
+# Import Jira CSV export
+agentic-framework backlog import --csv operations/jira-exports/sprint.csv
+```
+
+### Features
+- Parses Jira CSV exports
+- Converts Jira wiki markup to markdown
+- Generates YAML frontmatter with Jira metadata
+- Creates atomic ticket structure (organized by type)
+- Pure TypeScript implementation
+
+### CSV Column Mapping
+```
+Issue key        → jira-ticketId
+Summary          → title
+Issue Type       → framework-type
+Priority         → framework-priority
+Status           → status
+Assignee         → assignee
+Custom field     → storyPoints
+Fix Version/s    → framework-milestone
+Epic Link        → jira-parent
+Description      → Body content (converted to markdown)
+```
+
+### Output Structure
+Managed by backlog module - tickets created with proper YAML frontmatter.
+
+---
+
+## Jira Configuration Reference
+
+**Project:** DAPM (or your project)
+**Base URL:** https://{your-org}.atlassian.net (or your instance)
+
+### Components
+- `APM: Reliability App - Frontend`
+- `APM: Reliability App - Backend`
+- `APM: Reliability App - Full Stack`
+
+### Issue Types
+- Epic
+- Story
+- Task
+- Sub-task
+- Bug
+- Spike
+
+### Custom Fields (Example)
+- **Story Points:** `customfield_10016`
+- **Epic Link:** `customfield_10014`
+- **Team:** `customfield_10060`
+
+---
+
+## TypeScript CLI Commands Reference
+
+| Task | Command | Notes |
+|------|---------|-------|
+| **Validate ticket** | `backlog validate` | Check YAML format before export |
+| **Export to Jira (AUTO-DETECT)** | `jira export --tickets <file>` | Auto-detects CREATE vs UPDATE mode |
+| **Dry-run export** | `jira export --tickets <file> --dry-run` | Validate without exporting |
+| **Import from Jira** | `backlog import --csv <file>` | Import Jira CSV export |
+
+**No Python Scripts:**
+- ❌ `python src/jira/export_to_jira.py` (doesn't exist)
+- ❌ `python src/backlog/import_jira_data.py` (doesn't exist)
+- ✅ TypeScript CLI commands (implemented in modules)
+
+---
+
+## Troubleshooting
+
+### Common Errors
+
+**401 Unauthorized:**
+- Check `.env` for valid `JIRA_EMAIL` and `JIRA_API_TOKEN`
+- Verify API token hasn't expired
+- Regenerate at: https://id.atlassian.com/manage-profile/security/api-tokens
+
+**403 Forbidden:**
+- Check user permissions in project
+- Verify custom fields are accessible to your user
+- Check field visibility rules
+
+**404 Issue Not Found:**
+- Verify issue key format (e.g., DAPM-1234)
+- Check project key is correct
+
+**Rate Limited (429):**
+- CLI handles rate limiting with exponential backoff
+- Reduce batch size if needed
+- Add delays between requests
+
+---
+
+**Version:** 1.0 (adapted for TypeScript CLI)
+**Created:** 2025-12-22
+**Status:** Production-Ready (Phase 3 Migration)