cc-agentic-framework 1.14.1

package/framework/modules/backlog/skills/backlog/organizing-backlog/JIRA-SOURCE-OF-TRUTH.md

@@ -0,0 +1,384 @@
+# Jira is Source of Truth
+
+Principle and implementation of "Jira is source of truth" for backlog module and Jira integration using TypeScript CLI.
+
+---
+
+## Core Principle
+
+**"Jira is the source of truth for all ticket metadata, IDs, names, and references."**
+
+This means:
+- Preserve exact Jira ticket IDs, names, and field values
+- Don't modify or transform Jira data during import/export
+- Maintain bidirectional sync integrity
+- Enable Jira CSV imports to find existing tickets
+- Preserve Jira relationships and dependencies
+
+---
+
+## What to Preserve
+
+### 1. Jira Ticket IDs
+
+**Format:** `DAPM-XXXX` (project prefix + number)
+
+**Where Stored:**
+```yaml
+# In YAML frontmatter (jira- prefix)
+jira-ticketId: DAPM-1234
+jira-url: "https://{your-org}.atlassian.net/browse/PROJ-1234"
+```
+
+**In Filename (after export):**
+```
+# Numeric part only (no DAPM- prefix)
+1234-auth0-sso-configuration.md
+```
+
+**Why:**
+- Jira ticket ID is immutable and unique
+- Enables cross-referencing between tickets
+- Allows import script to find existing tickets
+- Maintains audit trail
+
+### 2. Jira Component Names
+
+**Format:** Exact string from Jira (including spacing and punctuation)
+
+**Examples:**
+```yaml
+jira-component: "APM:  Reliability App"
+jira-component: "APM:  Reliability App - Frontend"
+jira-component: "APM:  Reliability App - Backend"
+jira-component: "APM:  Reliability App - Full Stack"
+```
+
+**Why:**
+- Component names are controlled by Jira administrators
+- Preserving exact names ensures proper Jira export mapping
+- Two spaces after "APM:" are intentional in Jira
+- Changing names breaks Jira API calls
+
+### 3. Jira Epic Names and Links
+
+**Format:** Exact Jira epic ID and name
+
+**Examples:**
+```yaml
+jira-parent: DAPM-1171
+```
+
+**Why:**
+- Epic relationships tracked by Jira ID
+- Changing epic IDs breaks parent-child relationships
+- Enables Jira to display epic hierarchy
+
+### 4. Jira Sprint Names
+
+**Format:** Exact sprint name from Jira
+
+**Examples:**
+```yaml
+# In YAML frontmatter
+jira-sprint: "APM-R App Sprint W01"
+jira-sprintId: 16786
+```
+
+**Why:**
+- Sprint names controlled by Jira sprint board
+- Jira sprint ID required for API calls
+- Enables smart lookup by name or ID
+
+### 5. Jira Milestone Names
+
+**Format:** Exact milestone name from Jira (often called Fix Version)
+
+**Examples:**
+```yaml
+# In YAML frontmatter
+jira-milestone: "APM-R App - February 2026 - W3 W5 W7"
+framework-milestone: Feb2026  # Framework-specific milestone code
+```
+
+**Why:**
+- Milestone names defined in Jira Fix Versions
+- Enables import script to find milestone by name
+- Supports rename detection (find by ID even if name changed)
+
+### 6. Jira Relationships
+
+**Format:** Exact Jira ticket IDs for related, blocking, blocked-by
+
+**Examples:**
+```yaml
+jira-related: [DAPM-1165, DAPM-1166]
+jira-blocking: [DAPM-1167]
+jira-blockedBy: [DAPM-1032]
+```
+
+**Why:**
+- Jira tracks dependencies via ticket IDs
+- Preserving IDs maintains dependency graph
+- Enables Jira to display blockers and blocked-by tickets
+
+---
+
+## Why "Jira is Source of Truth"
+
+### 1. Bidirectional Sync Integrity
+
+**Problem without this principle:**
+```
+Jira: "APM:  Reliability App - Frontend" (two spaces)
+Local: "APM: Reliability App - Frontend" (one space)
+Export: ❌ Jira API error: Component not found
+```
+
+**Solution:**
+```
+Jira: "APM:  Reliability App - Frontend"
+Local: "APM:  Reliability App - Frontend" (preserved exactly)
+Export: ✅ Jira API succeeds
+```
+
+### 2. Import/Export Without Data Loss
+
+**Problem without this principle:**
+```
+# First import
+Jira CSV: DAPM-1234, "Implement SSO"
+Local File: sso-implementation.md (no Jira ID)
+
+# Second import (after Jira update)
+Jira CSV: DAPM-1234, "Implement SSO with Auth0"
+Local File: ❌ Creates duplicate file: sso-implementation-with-auth0.md
+```
+
+**Solution:**
+```
+# First import
+Jira CSV: DAPM-1234, "Implement SSO"
+Local File: 1234-implement-sso.md (Jira ID in filename)
+YAML: jira-ticketId: DAPM-1234
+
+# Second import (after Jira update)
+Jira CSV: DAPM-1234, "Implement SSO with Auth0"
+Local File: ✅ Updates existing: 1234-implement-sso-with-auth0.md
+YAML: jira-ticketId: DAPM-1234 (unchanged, used for lookup)
+```
+
+---
+
+## Implementation in TypeScript CLI
+
+### Export CLI (`jira export`)
+
+**Command:**
+```bash
+agentic-framework jira export --tickets <ticket-files>
+```
+
+**What it does:**
+1. Reads YAML frontmatter from ticket file
+2. Uses `jira-component` field to set Jira component (exact match required)
+3. Uses `jira-parent` field to set Jira epic link
+4. Creates or updates Jira ticket via REST API (AUTO-DETECT mode)
+5. Updates YAML with `jira-ticketId` and `jira-url` from Jira response
+
+**AUTO-DETECT Mode:**
+- If `jira-ticketId` exists → UPDATE existing Jira issue
+- If `jira-ticketId` is null/missing → CREATE new Jira issue
+
+### Import CLI (`backlog import`)
+
+**Command:**
+```bash
+agentic-framework backlog import --csv <file>
+```
+
+**What it does:**
+1. Reads Jira CSV export
+2. Extracts exact field values (Issue key, Summary, Component, Epic Link, etc.)
+3. Converts Jira wiki markup → markdown
+4. Generates YAML frontmatter preserving exact Jira values
+5. Creates ticket files with Jira ticket number in filename
+
+**Smart Lookup Feature:**
+- Finds existing tickets by Jira ID
+- Detects renames and updates metadata
+- Preserves Jira relationships
+
+**Example CSV → YAML Mapping:**
+```csv
+Issue key,Summary,Component,Epic Link,Sprint,Fix versions
+DAPM-1234,"Implement SSO","APM:  Reliability App - Frontend",DAPM-1171,"Sprint W01","Feb2026"
+```
+
+**Generated YAML:**
+```yaml
+---
+jira-ticketId: DAPM-1234
+title: "Implement SSO"
+jira-component: "APM:  Reliability App - Frontend"  # Exact match
+jira-parent: DAPM-1171
+jira-sprint: "Sprint W01"
+jira-milestone: "Feb2026"
+---
+```
+
+---
+
+## Validation Rules
+
+### Component Validation
+
+**Rule:** Component name must exist in Jira project
+
+**Check via CLI:**
+```bash
+# Validate ticket format before export
+agentic-framework backlog validate
+```
+
+**Example Errors:**
+```
+❌ Component: "APM: Reliability App - Frontend" (one space)
+   Expected: "APM:  Reliability App - Frontend" (two spaces)
+
+❌ Component: "APM-R Frontend"
+   Expected: "APM:  Reliability App - Frontend"
+```
+
+### Ticket ID Validation
+
+**Rule:** Jira ticket ID must match project pattern: `DAPM-[0-9]+`
+
+**Example Errors:**
+```
+❌ jira-ticketId: "1234" (missing DAPM- prefix)
+   Expected: "DAPM-1234"
+
+❌ jira-ticketId: "dapm-1234" (lowercase)
+   Expected: "DAPM-1234"
+```
+
+---
+
+## Best Practices
+
+### When Creating Tickets
+
+✅ **DO:**
+- Leave `jira-ticketId`, `jira-url`, `exportedDate` as `null`
+- Use exact component names from Jira
+- Reference epic by Jira ID if known
+
+❌ **DON'T:**
+- Make up Jira ticket IDs
+- Modify component names
+- Use placeholder values
+
+### When Exporting to Jira
+
+✅ **DO:**
+- Preserve component names exactly
+- Use CLI validation before export
+- Update YAML with exact Jira response values
+
+**Command:**
+```bash
+# Dry-run validation
+agentic-framework jira export --tickets <file> --dry-run
+```
+
+❌ **DON'T:**
+- Transform or clean up component names
+- Modify Jira ticket IDs returned by API
+- Skip updating YAML metadata
+
+### When Importing from Jira
+
+✅ **DO:**
+- Preserve exact field values from CSV
+- Use Jira ticket ID for duplicate detection
+- Store both Jira ID and Jira name (for smart lookup)
+
+**Command:**
+```bash
+agentic-framework backlog import --csv <file>
+```
+
+❌ **DON'T:**
+- Transform or clean up field values
+- Create duplicate tickets for existing Jira IDs
+- Lose Jira relationship data
+
+---
+
+## Troubleshooting
+
+### Issue: Export fails with "Component not found"
+
+**Cause:** Component name doesn't match exactly
+
+**Solution:**
+```yaml
+# Check spacing and punctuation
+❌ jira-component: "APM: Reliability App - Frontend"
+✅ jira-component: "APM:  Reliability App - Frontend"  # Two spaces after colon
+```
+
+**Validate with CLI:**
+```bash
+agentic-framework backlog validate
+```
+
+### Issue: Import creates duplicate tickets
+
+**Cause:** Jira ticket ID not stored in YAML or filename
+
+**Solution:**
+```yaml
+# Ensure YAML has Jira ticket ID
+jira-ticketId: DAPM-1234
+
+# Ensure filename has Jira ticket number
+1234-implement-sso.md
+```
+
+### Issue: Epic relationships lost after import
+
+**Cause:** `jira-parent` field not preserved
+
+**Solution:**
+```yaml
+# Ensure child stories have epic link
+jira-parent: DAPM-1171
+```
+
+---
+
+## Summary
+
+**Key Takeaways:**
+1. Jira is source of truth - preserve exact values
+2. Store Jira IDs in YAML frontmatter with `jira-` prefix
+3. Use Jira ticket number in filenames (after export)
+4. Preserve component names exactly (spacing, punctuation)
+5. Use TypeScript CLI for all Jira operations
+6. Validate tickets before export using `backlog validate`
+7. AUTO-DETECT mode handles CREATE vs UPDATE automatically
+
+**TypeScript CLI Commands:**
+- `agentic-framework jira export --tickets <file>` - Export to Jira
+- `agentic-framework backlog import --csv <file>` - Import from Jira CSV
+- `agentic-framework backlog validate` - Validate ticket format
+- `agentic-framework backlog migrate-milestones` - Generate milestone overviews
+
+**Benefits:**
+- ✅ Import/export without data loss
+- ✅ Rename detection and smart lookup
+- ✅ Jira relationship preservation
+- ✅ Bidirectional sync integrity
+- ✅ Audit trail and traceability

package/framework/modules/backlog/skills/backlog/organizing-backlog/NAMING-CONVENTIONS.md

@@ -0,0 +1,230 @@
+# Naming Conventions
+
+Detailed rules and examples for naming ticket files in the backlog module.
+
+---
+
+## Core Principles
+
+1. **Consistency:** Same naming pattern throughout lifecycle
+2. **Clarity:** Names clearly indicate content
+3. **Kebab-Case:** Lowercase with hyphens (no spaces, underscores, or camelCase)
+4. **Jira Integration:** Preserve Jira ticket numbers after export
+5. **No Redundancy:** Remove duplicate prefixes and redundant words
+
+---
+
+## Ticket Files (Permanent Storage)
+
+### Format
+
+```
+[JIRA-NUMBER]-[title-kebab-case].md
+```
+
+### Rules
+
+- ✅ Start with Jira ticket number (numeric only, no DAPM- prefix)
+- ✅ Use kebab-case for title (lowercase, hyphens)
+- ✅ Remove project prefix (DAPM-) from number
+- ✅ Strip redundant prefixes from title (APM-R:, App:, etc.)
+- ✅ 2-10 words in title (keep concise)
+- ❌ NO milestone prefix in filename (use YAML `framework-milestone:` field)
+- ❌ NO type prefix in filename (use YAML `framework-type:` field)
+
+### Examples
+
+**Stories:**
+```
+✅ CORRECT:
+1164-forecast-180d-lr-marker-and-timestamps.md
+1166-final-drive-divisions-support.md
+942-observability-improvements-unified-logging-tracing.md
+
+❌ WRONG:
+Feb2026-1164-forecast-180d-lr-marker-and-timestamps.md  # No milestone prefix
+STORY-1164-forecast-180d.md                              # No type prefix
+DAPM-1164-forecast-180d.md                               # No DAPM- prefix
+1164_forecast_180d_lr_marker.md                          # Use hyphens, not underscores
+1164-APM-R-App-Forecast-180d.md                          # Remove redundant prefixes
+```
+
+**Tasks:**
+```
+✅ CORRECT:
+1032-migrate-to-api-v2-via-centralized-data-layer.md
+1172-be-data-platform-snowflake-introduce-sub-components.md
+932-observability-improvements-unified-logging-strategy.md
+
+❌ WRONG:
+TASK-1032-migrate-to-api-v2.md                           # No type prefix
+1032-APM-R-BE-Migrate-to-API-v2.md                       # Remove redundant prefixes
+```
+
+**Bugs:**
+```
+✅ CORRECT:
+1315-fix-shimmer-loading-when-changing-analysis-hours.md
+
+❌ WRONG:
+BUG-1315-fix-shimmer-loading.md                          # No type prefix
+1315-Bug-Fix-Shimmer-Loading.md                          # Use lowercase
+```
+
+---
+
+## YAML Frontmatter (Type and Milestone Assignment)
+
+**Type Assignment:** Use `framework-type` field (not filename prefix)
+
+```yaml
+---
+framework-type: story  # story, task, bug, epic, spike
+---
+```
+
+**Milestone Assignment:** Use `framework-milestone` field (not filename prefix)
+
+```yaml
+---
+framework-milestone: Feb2026  # Milestone code
+jira-milestone: "APM-R App - February 2026 - W3 W5 W7"  # Full Jira milestone name
+---
+```
+
+---
+
+## Title Transformation Rules
+
+### Remove Redundant Prefixes
+
+**From Jira Title to Filename:**
+```
+Jira Title: "APM-R: App: Asset Component Hours grid: Forecast (+180d)"
+Filename: 1164-forecast-180d-lr-marker-and-timestamps.md
+          ✂️ Remove: "APM-R:", "App:", "Asset Component Hours grid:"
+```
+
+**Common Prefixes to Remove:**
+- `APM-R:`
+- `App:`
+- `BE:`
+- `FE:`
+- `FS:`
+- `[Project]:`
+- `[Component]:`
+
+### Preserve Important Context
+
+**Keep meaningful qualifiers:**
+```
+✅ GOOD:
+1172-be-data-platform-snowflake-introduce-sub-components.md  # "be" clarifies backend
+1537-fe-make-cache-stale-times-configurable.md               # "fe" clarifies frontend
+
+❌ BAD:
+1172-data-platform-snowflake-introduce-sub-components.md     # Lost backend context
+1537-make-cache-stale-times-configurable.md                  # Lost frontend context
+```
+
+---
+
+## Special Cases
+
+### Multi-Word Numbers
+
+```
+✅ CORRECT:
+1164-forecast-180d-lr-marker-and-timestamps.md           # "180d" treated as one word
+1032-migrate-to-api-v2-via-centralized-data-layer.md     # "api-v2" treated as one concept
+
+❌ WRONG:
+1164-forecast-one-hundred-eighty-d.md                    # Keep numeric format
+1032-migrate-to-api-version-two.md                       # Keep v2 abbreviation
+```
+
+### Acronyms and Abbreviations
+
+```
+✅ CORRECT:
+932-observability-improvements-unified-logging-strategy.md
+1406-convert-data-layer-methods-to-promise-based-sentry.md
+
+❌ WRONG:
+932-observability-improvements-u-l-s.md                  # Don't abbreviate unnecessarily
+1406-convert-d-l-methods-to-p-b-sentry.md                # Keep full words
+```
+
+---
+
+## Validation Checklist
+
+Before finalizing any filename, check:
+
+- [ ] Uses kebab-case (lowercase, hyphens only)
+- [ ] Jira ticket number present (numeric only, no DAPM- prefix)
+- [ ] No redundant prefixes (APM-R:, App:, etc.) in title
+- [ ] No milestone prefix in filename (use YAML `framework-milestone:` field)
+- [ ] No type prefix in filename (use YAML `framework-type:` field)
+- [ ] 2-10 words in title (concise but descriptive)
+- [ ] Meaningful context preserved (fe-, be-, etc. where needed)
+- [ ] Matches examples in this guide
+
+**Validate with CLI:**
+```bash
+agentic-framework backlog validate
+```
+
+---
+
+## Quick Reference Table
+
+| Ticket Type | YAML Type Field | Format | Example |
+|-------------|-----------------|--------|---------|
+| Story | `framework-type: story` | `[NUMBER]-[title].md` | `1164-forecast-180d-lr-marker.md` |
+| Task | `framework-type: task` | `[NUMBER]-[title].md` | `1032-migrate-to-api-v2.md` |
+| Bug | `framework-type: bug` | `[NUMBER]-[title].md` | `1315-fix-shimmer-loading.md` |
+| Epic | `framework-type: epic` | `[NUMBER]-[title].md` | `1171-split-final-drive.md` |
+| Spike | `framework-type: spike` | `[NUMBER]-[title].md` | `942-investigate-performance.md` |
+
+---
+
+## Migration from Old Naming
+
+If migrating from old naming conventions:
+
+**Old Format (milestone prefix):**
+```
+❌ Feb2026-1164-asset-component-hours-grid-forecast.md
+```
+
+**New Format (no milestone prefix, YAML assignment):**
+```
+✅ 1164-forecast-180d-lr-marker-and-timestamps.md
+
+With YAML:
+---
+framework-milestone: Feb2026
+jira-milestone: "APM-R App - February 2026 - W3 W5 W7"
+---
+```
+
+**TypeScript CLI for Batch Rename:**
+```bash
+# Validate all tickets
+agentic-framework backlog validate
+
+# CLI will report any naming violations
+```
+
+---
+
+## See Also
+
+- **Ticket Format:** [building-tickets](../building-tickets/SKILL.md) - v10.1.1 YAML frontmatter structure
+- **Jira Integration:** [JIRA-SOURCE-OF-TRUTH.md](JIRA-SOURCE-OF-TRUTH.md) - "Jira is source of truth" principle
+- **CLI Commands:** Backlog module TypeScript CLI for validation and import
+
+---
+
+**Note:** This skill focuses on backlog module architecture. For generic file naming conventions, see framework documentation.