ai-qakit 1.0.0

package/templates/.claude/skills/jira-integration/adf-parser.md

@@ -0,0 +1,338 @@
+# Atlassian Document Format (ADF) Parser
+
+Reference for parsing Jira's rich text format used in description, comments, and custom fields.
+
+## ADF Structure
+
+```json
+{
+  "type": "doc",
+  "version": 1,
+  "content": [ /* array of block nodes */ ]
+}
+```
+
+## Block Node Types
+
+### Paragraph
+```json
+{
+  "type": "paragraph",
+  "content": [
+    { "type": "text", "text": "Hello " },
+    { "type": "text", "text": "world", "marks": [{ "type": "strong" }] }
+  ]
+}
+```
+
+### Heading
+```json
+{
+  "type": "heading",
+  "attrs": { "level": 2 },
+  "content": [{ "type": "text", "text": "Section Title" }]
+}
+```
+
+### Bullet List
+```json
+{
+  "type": "bulletList",
+  "content": [
+    {
+      "type": "listItem",
+      "content": [
+        {
+          "type": "paragraph",
+          "content": [{ "type": "text", "text": "Item 1" }]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Ordered List
+```json
+{
+  "type": "orderedList",
+  "content": [
+    {
+      "type": "listItem",
+      "content": [
+        {
+          "type": "paragraph",
+          "content": [{ "type": "text", "text": "Step 1" }]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Code Block
+```json
+{
+  "type": "codeBlock",
+  "attrs": { "language": "javascript" },
+  "content": [{ "type": "text", "text": "const x = 1;" }]
+}
+```
+
+### Media (Attachments)
+```json
+{
+  "type": "mediaSingle",
+  "attrs": { "layout": "center" },
+  "content": [
+    {
+      "type": "media",
+      "attrs": {
+        "type": "file",
+        "id": "abc123",
+        "collection": "",
+        "width": 800,
+        "height": 600
+      }
+    }
+  ]
+}
+```
+
+### Table
+```json
+{
+  "type": "table",
+  "content": [
+    {
+      "type": "tableRow",
+      "content": [
+        {
+          "type": "tableHeader",
+          "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "Header" }] }]
+        }
+      ]
+    },
+    {
+      "type": "tableRow",
+      "content": [
+        {
+          "type": "tableCell",
+          "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "Cell" }] }]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Inline Node Types
+
+### Text
+```json
+{ "type": "text", "text": "Plain text" }
+```
+
+### Text with Marks
+```json
+{
+  "type": "text",
+  "text": "Bold and italic",
+  "marks": [
+    { "type": "strong" },
+    { "type": "em" }
+  ]
+}
+```
+
+### Mention
+```json
+{
+  "type": "mention",
+  "attrs": {
+    "id": "user-id-123",
+    "text": "@John Doe"
+  }
+}
+```
+
+### Inline Card (Linked Issue)
+```json
+{
+  "type": "inlineCard",
+  "attrs": {
+    "url": "https://jira.company.com/browse/PROJ-456"
+  }
+}
+```
+
+### Hard Break
+```json
+{ "type": "hardBreak" }
+```
+
+### Emoji
+```json
+{
+  "type": "emoji",
+  "attrs": {
+    "shortName": ":thumbsup:",
+    "text": "👍"
+  }
+}
+```
+
+## Mark Types
+
+| Mark | Description |
+|------|-------------|
+| `strong` | Bold text |
+| `em` | Italic text |
+| `underline` | Underlined text |
+| `strike` | Strikethrough |
+| `code` | Inline code |
+| `link` | Hyperlink (has `href` attr) |
+| `textColor` | Colored text (has `color` attr) |
+
+## Parsing Examples
+
+### Extract Plain Text
+
+```javascript
+function adfToText(adf) {
+  if (!adf) return '';
+  if (typeof adf === 'string') return adf;
+  if (adf.text) return adf.text;
+  if (!adf.content) return '';
+  
+  return adf.content.map(node => {
+    switch (node.type) {
+      case 'text':
+        return node.text || '';
+      case 'hardBreak':
+        return '\n';
+      case 'paragraph':
+        return adfToText(node) + '\n';
+      case 'heading':
+        return '#'.repeat(node.attrs?.level || 1) + ' ' + adfToText(node) + '\n';
+      case 'bulletList':
+        return node.content?.map(item => '• ' + adfToText(item)).join('\n') + '\n';
+      case 'orderedList':
+        return node.content?.map((item, i) => `${i + 1}. ` + adfToText(item)).join('\n') + '\n';
+      case 'listItem':
+        return adfToText(node);
+      case 'codeBlock':
+        return '```\n' + adfToText(node) + '\n```\n';
+      case 'mention':
+        return node.attrs?.text || '@user';
+      case 'inlineCard':
+        return node.attrs?.url || '';
+      default:
+        return adfToText(node);
+    }
+  }).join('');
+}
+```
+
+### Extract Acceptance Criteria
+
+```javascript
+function extractAcceptanceCriteria(adf) {
+  const criteria = [];
+  
+  function traverse(node) {
+    if (!node) return;
+    
+    if (node.type === 'bulletList' || node.type === 'orderedList') {
+      node.content?.forEach((item, index) => {
+        const text = adfToText(item).trim();
+        if (text) {
+          criteria.push({
+            id: `AC-${String(index + 1).padStart(3, '0')}`,
+            text: text,
+            type: detectCriteriaType(text)
+          });
+        }
+      });
+    }
+    
+    node.content?.forEach(traverse);
+  }
+  
+  traverse(adf);
+  return criteria;
+}
+
+function detectCriteriaType(text) {
+  const lower = text.toLowerCase();
+  if (lower.includes('error') || lower.includes('invalid')) return 'Error';
+  if (lower.includes('security') || lower.includes('auth')) return 'Security';
+  if (lower.includes('performance') || lower.includes('load')) return 'Performance';
+  if (lower.includes('ui') || lower.includes('display')) return 'UI';
+  return 'Functional';
+}
+```
+
+### Extract Linked Issues
+
+```javascript
+function extractLinkedIssues(adf) {
+  const issues = [];
+  
+  function traverse(node) {
+    if (!node) return;
+    
+    if (node.type === 'inlineCard' && node.attrs?.url) {
+      const match = node.attrs.url.match(/browse\/([A-Z]+-\d+)/);
+      if (match) {
+        issues.push(match[1]);
+      }
+    }
+    
+    node.content?.forEach(traverse);
+  }
+  
+  traverse(adf);
+  return [...new Set(issues)]; // Remove duplicates
+}
+```
+
+## Common Patterns in Jira
+
+### Acceptance Criteria Section
+```json
+{
+  "type": "heading",
+  "attrs": { "level": 3 },
+  "content": [{ "type": "text", "text": "Acceptance Criteria" }]
+}
+// Followed by bulletList
+```
+
+### Given/When/Then
+```json
+{
+  "type": "paragraph",
+  "content": [
+    { "type": "text", "text": "Given ", "marks": [{ "type": "strong" }] },
+    { "type": "text", "text": "user is logged in" }
+  ]
+}
+```
+
+### Status Labels
+```json
+{
+  "type": "text",
+  "text": "PASS",
+  "marks": [{ "type": "textColor", "attrs": { "color": "#36b37e" } }]
+}
+```
+
+## Tips
+
+1. **Always check for null/undefined** - ADF can have missing content arrays
+2. **Handle nested structures** - Lists can contain paragraphs, which contain text
+3. **Preserve formatting hints** - Marks indicate important text (bold = key terms)
+4. **Extract media IDs** - Use to fetch attachments separately
+5. **Parse inlineCards** - These link to related tickets

package/templates/.claude/skills/jira-integration/jira-integration.md

@@ -0,0 +1,353 @@
+# Jira Integration Skill
+
+Expert knowledge for integrating with Jira REST API to fetch tickets, parse content, and create feature specs.
+
+## Core Capabilities
+
+### 1. Jira REST API v3
+
+**Authentication:**
+```bash
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" "$JIRA_BASE_URL/rest/api/3/..."
+```
+
+**Key Endpoints:**
+| Endpoint | Description |
+|----------|-------------|
+| `/rest/api/3/issue/{key}` | Get issue details |
+| `/rest/api/3/search?jql=...` | Search with JQL |
+| `/rest/api/3/project` | List projects |
+| `/rest/api/3/issue/{key}/comment` | Get comments |
+| `/rest/api/3/myself` | Test authentication |
+
+### 2. Atlassian Document Format (ADF)
+
+Jira Cloud uses ADF for rich text fields. Parse structure:
+
+```json
+{
+  "type": "doc",
+  "version": 1,
+  "content": [
+    {
+      "type": "paragraph",
+      "content": [
+        { "type": "text", "text": "Hello world" }
+      ]
+    },
+    {
+      "type": "bulletList",
+      "content": [
+        {
+          "type": "listItem",
+          "content": [
+            { "type": "paragraph", "content": [{ "type": "text", "text": "Item 1" }] }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+**ADF Node Types:**
+- `paragraph` - Text paragraph
+- `bulletList` / `orderedList` - Lists
+- `listItem` - List item
+- `heading` - Heading (attrs.level: 1-6)
+- `codeBlock` - Code block
+- `mediaSingle` / `media` - Attachments
+- `mention` - User mention
+- `inlineCard` - Linked ticket
+- `hardBreak` - Line break
+
+### 3. Key Jira Fields
+
+**Standard Fields:**
+```javascript
+{
+  "key": "PROJ-123",
+  "fields": {
+    "summary": "Issue title",
+    "description": { /* ADF */ },
+    "status": { "name": "In Progress" },
+    "priority": { "name": "High" },
+    "issuetype": { "name": "Bug" },
+    "assignee": { "displayName": "John Doe" },
+    "reporter": { "displayName": "Jane Doe" },
+    "labels": ["qa", "regression"],
+    "components": [{ "name": "Frontend" }],
+    "fixVersions": [{ "name": "v2.0" }],
+    "created": "2024-01-15T10:00:00.000+0000",
+    "updated": "2024-01-20T15:30:00.000+0000",
+    "subtasks": [{ "key": "PROJ-124" }],
+    "issuelinks": [{ "outwardIssue": { "key": "PROJ-100" } }],
+    "attachment": [{ "filename": "screenshot.png", "content": "url" }],
+    "comment": { "comments": [{ "body": { /* ADF */ } }] }
+  }
+}
+```
+
+**Common Custom Fields:**
+- `customfield_10204` - Acceptance Criteria (varies by instance)
+- `customfield_10014` - Story Points
+- `customfield_10011` - Sprint
+
+### 4. JQL (Jira Query Language)
+
+**Common Queries:**
+```
+# Issues in project
+project = PROJ
+
+# Open bugs
+project = PROJ AND issuetype = Bug AND status != Done
+
+# Assigned to me
+assignee = currentUser()
+
+# Updated recently
+updated >= -7d
+
+# By label
+labels = "regression"
+
+# Combined
+project = PROJ AND status = "Ready for QA" AND priority in (High, Highest)
+```
+
+### 5. Parsing Acceptance Criteria
+
+Look for patterns in description or custom fields:
+
+**Pattern 1: Checkbox List**
+```
+- [ ] User can login with email
+- [x] Error shown for invalid email
+```
+
+**Pattern 2: Given/When/Then (Gherkin)**
+```
+Given user is on login page
+When user enters valid credentials
+Then user is redirected to dashboard
+```
+
+**Pattern 3: Numbered List**
+```
+1. Valid login redirects to dashboard
+2. Invalid email shows error message
+```
+
+**Pattern 4: AC Prefix**
+```
+AC1: User can login with valid credentials
+AC2: Error message for invalid email
+```
+
+### 6. Priority Mapping
+
+| Jira Priority | QA Priority |
+|---------------|-------------|
+| Highest / Blocker | P0 - Critical |
+| High | P1 - High |
+| Medium | P2 - Medium |
+| Low / Lowest | P3 - Low |
+
+### 7. Issue Type Mapping
+
+| Jira Type | QA Treatment |
+|-----------|--------------|
+| Epic | Feature spec with multiple user stories |
+| Story | Single user story with acceptance criteria |
+| Bug | Bug report with reproduction steps |
+| Task | Technical task, may not need test cases |
+| Sub-task | Part of parent story |
+
+## Fetching Related Tickets
+
+### Get Subtasks
+Subtasks are in `.fields.subtasks[]`:
+```javascript
+const subtasks = issue.fields.subtasks || [];
+for (const subtask of subtasks) {
+  const subtaskKey = subtask.key;
+  // Fetch full details
+  const details = await fetchIssue(subtaskKey);
+}
+```
+
+### Get Linked Issues
+Links are in `.fields.issuelinks[]`:
+```javascript
+const links = issue.fields.issuelinks || [];
+for (const link of links) {
+  // Outward: this issue -> other
+  if (link.outwardIssue) {
+    const linkedKey = link.outwardIssue.key;
+    const linkType = link.type.outward; // "blocks", "relates to"
+  }
+  // Inward: other -> this issue
+  if (link.inwardIssue) {
+    const linkedKey = link.inwardIssue.key;
+    const linkType = link.type.inward; // "is blocked by"
+  }
+}
+```
+
+### Link Types
+| Type | Outward | Inward |
+|------|---------|--------|
+| Blocks | blocks | is blocked by |
+| Relates | relates to | relates to |
+| Duplicates | duplicates | is duplicated by |
+| Clones | clones | is cloned by |
+| Causes | causes | is caused by |
+
+### Recursive Fetch Pattern
+```javascript
+async function fetchWithRelated(ticketId, depth = 1) {
+  const issue = await fetchIssue(ticketId);
+  const result = { main: issue, subtasks: [], linked: [] };
+  
+  if (depth > 0) {
+    // Fetch subtasks
+    for (const st of issue.fields.subtasks || []) {
+      result.subtasks.push(await fetchIssue(st.key));
+    }
+    
+    // Fetch linked (only first level)
+    for (const link of issue.fields.issuelinks || []) {
+      const linkedKey = link.outwardIssue?.key || link.inwardIssue?.key;
+      if (linkedKey) {
+        result.linked.push({
+          type: link.type.outward || link.type.inward,
+          issue: await fetchIssue(linkedKey)
+        });
+      }
+    }
+  }
+  
+  return result;
+}
+```
+
+## Analyzing Comments
+
+### Extract Test Hints
+```javascript
+function extractTestHints(comments) {
+  const hints = [];
+  const testKeywords = /test|testing|QA|verify|check|edge case|scenario/i;
+  
+  for (const comment of comments) {
+    const text = adfToText(comment.body);
+    if (testKeywords.test(text)) {
+      hints.push({
+        author: comment.author.displayName,
+        date: comment.created,
+        text: text,
+        mentions: extractMentions(comment.body),
+        linkedTickets: extractLinkedIssues(comment.body)
+      });
+    }
+  }
+  return hints;
+}
+```
+
+### Extract Linked Tickets from Comments
+Comments may contain `inlineCard` nodes linking to other tickets:
+```javascript
+function extractLinkedIssues(adf) {
+  const issues = [];
+  traverse(adf, node => {
+    if (node.type === 'inlineCard' && node.attrs?.url) {
+      const match = node.attrs.url.match(/browse\/([A-Z]+-\d+)/);
+      if (match) issues.push(match[1]);
+    }
+  });
+  return [...new Set(issues)];
+}
+```
+
+## Best Practices
+
+### Fetching Data
+
+1. **Always check authentication first:**
+   ```bash
+   curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" "$JIRA_BASE_URL/rest/api/3/myself"
+   ```
+
+2. **Handle pagination for search:**
+   ```bash
+   curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+     "$JIRA_BASE_URL/rest/api/3/search?jql=project=PROJ&startAt=0&maxResults=50"
+   ```
+
+3. **Expand fields as needed:**
+   ```bash
+   curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+     "$JIRA_BASE_URL/rest/api/3/issue/PROJ-123?expand=changelog,renderedFields"
+   ```
+
+4. **Batch fetch for efficiency:**
+   ```bash
+   # Fetch multiple issues at once
+   curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+     "$JIRA_BASE_URL/rest/api/3/search?jql=key in (PROJ-123,PROJ-124,PROJ-125)"
+   ```
+
+### Parsing ADF
+
+```javascript
+function extractTextFromADF(adf) {
+  if (!adf || !adf.content) return '';
+  
+  return adf.content.map(node => {
+    switch (node.type) {
+      case 'paragraph':
+      case 'heading':
+        return node.content?.map(c => c.text || '').join('') || '';
+      case 'bulletList':
+      case 'orderedList':
+        return node.content?.map(item => 
+          '• ' + extractTextFromADF(item)
+        ).join('\n') || '';
+      case 'listItem':
+        return node.content?.map(c => extractTextFromADF({ content: [c] })).join('') || '';
+      default:
+        return '';
+    }
+  }).join('\n');
+}
+```
+
+### Error Handling
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| 401 | Unauthorized | Check credentials |
+| 403 | Forbidden | Check permissions |
+| 404 | Not Found | Check issue key/URL |
+| 429 | Rate Limited | Wait and retry |
+
+## Environment Variables
+
+```bash
+# Required
+JIRA_BASE_URL="https://yourcompany.atlassian.net"
+JIRA_EMAIL="your.email@company.com"
+JIRA_API_TOKEN="your-api-token"
+
+# Optional
+JIRA_PROJECT="PROJ"  # Default project
+```
+
+## Related Commands
+
+- `/qakit:setup/jira` - Setup Jira integration
+- `/qakit:feature/from-jira` - Create feature from ticket
+- `/qakit:jira:analyze` - Analyze ticket for testing
+- `/qakit:jira:create-tests` - Create tests from ticket