cc-agentic-framework 1.14.1

package/framework/modules/backlog/skills/backlog/organizing-backlog/SKILL.md

@@ -0,0 +1,332 @@
+---
+id: organizing-backlog
+module: backlog
+name: organizing-backlog
+description: Understand the backlog module architecture, CLI commands, and ticket organization workflow. Use when working with backlog module, understanding ticket lifecycle, or organizing work items using the framework's TypeScript CLI.
+scope: project-specific
+applicable-projects: agentic-development-framework
+capabilities-provided:
+  - organizing-backlog
+  - epic-breakdown
+  - sprint-planning
+  - milestone-tracking
+  - organizing-backlog-knowledge
+  - backlog-workflow
+  - ticket-lifecycle
+---
+
+# Backlog Organization
+
+## When to Use This Skill
+
+Use this skill when you need to:
+- Understand backlog module architecture and structure
+- Navigate the ticket workflow lifecycle (draft → validation → deployment)
+- Learn CLI commands for backlog management
+- Organize tickets using the backlog module
+- Import Jira data into the backlog module
+- Generate milestone overviews from ticket metadata
+- Work with the backlog module's ticket management system
+
+**Agents that need this skill:**
+- ai-backlog-manager (creating and organizing tickets)
+- ai-jira-manager (exporting/importing tickets, understanding structure)
+
+---
+
+## Quick Start: Backlog Module Architecture
+
+```
+framework/modules/backlog/
+├── ai/
+│   ├── agents/           ← Backlog management agents
+│   ├── skills/          ← This skill + building-tickets
+│   └── context/         ← Backlog domain knowledge
+│
+├── src/
+│   ├── cli/            ← TypeScript CLI commands
+│   │   ├── import.ts   # Import Jira data
+│   │   ├── validate.ts # Validate ticket format
+│   │   └── migrate-milestones.ts  # Generate milestone overviews
+│   ├── models/         ← Ticket, Epic, Milestone models
+│   └── utils/          ← Parsing, validation utilities
+│
+└── module.json         ← Module manifest
+```
+
+**Key Principle:** Backlog module uses TypeScript CLI commands (NOT Python scripts) for automation.
+
+---
+
+## Instructions
+
+### 1. Understand Module-Based Ticket Organization
+
+**Architecture:** The backlog module is self-contained with TypeScript implementation.
+
+**Workflow Lifecycle:**
+1. **Creation:** AI agent creates ticket using backlog module API
+2. **Validation:** CLI validates format and YAML metadata
+3. **Deployment:** Skills and capabilities available via discovery system
+
+**TypeScript CLI Commands:**
+- `agentic-framework backlog import --csv <file>` - Import Jira CSV data
+- `agentic-framework backlog validate` - Validate ticket format
+- `agentic-framework backlog migrate-milestones` - Generate milestone overviews
+
+**No Python Scripts:** The old v1 repo used Python (`backlog-milestone-generator.py`, `import_jira_data.py`). The new framework uses TypeScript CLI exclusively.
+
+### 2. Follow Naming Conventions
+
+**Format:** `[TICKET-NUMBER]-[title-kebab-case].md`
+
+**Rules:**
+- ✅ Start with Jira ticket number (e.g., `1315-`, `942-`)
+- ✅ Use kebab-case for title (lowercase, hyphens)
+- ✅ Remove project prefix (DAPM-) from number
+- ✅ Strip redundant prefixes from title (APM-R:, App:, etc.)
+- ✅ NO milestone prefix in filename
+- ✅ NO type prefix in filename (determined by YAML `type:` field)
+
+**Examples:**
+- Story: `1164-forecast-180d-lr-marker-and-timestamps.md`
+- Task: `1032-migrate-to-api-v2-via-centralized-data-layer.md`
+- Bug: `1315-fix-shimmer-loading-when-changing-analysis-hours.md`
+- Epic: `1171-split-final-drive-to-left-right-sub-components.md`
+
+**YAML Frontmatter:** See the `building-tickets` skill for v10.1.1 format details.
+
+### 3. Use TypeScript CLI for Backlog Operations
+
+**Import Jira Data:**
+```bash
+# Import Jira sprint/milestone CSV export
+agentic-framework backlog import --csv jira-export.csv
+
+# Example output:
+# - Creates ticket markdown files with YAML metadata
+# - Preserves Jira IDs, names, and metadata
+# - Organizes by type (story, task, bug, epic)
+```
+
+**Validate Tickets:**
+```bash
+# Validate all tickets in backlog module
+agentic-framework backlog validate
+
+# Checks:
+# - YAML frontmatter format (flat structure, correct prefixes)
+# - Required fields (title, type, status)
+# - Markdown syntax
+# - Link validity
+```
+
+**Generate Milestone Overviews:**
+```bash
+# Auto-generate milestone overviews from ticket metadata
+agentic-framework backlog migrate-milestones
+
+# Scans tickets for `framework-milestone:` YAML field
+# Creates milestone overview files
+# Updates statistics and ticket lists
+```
+
+### 4. Understand YAML Frontmatter Structure
+
+**Flat Structure with Prefixes:**
+```yaml
+---
+# Jira metadata (jira- prefix)
+jira-ticketId: DAPM-1164
+jira-url: "https://{your-org}.atlassian.net/browse/PROJ-1164"
+jira-parent: DAPM-1171
+jira-component: "APM: Reliability App"
+
+# Framework metadata (framework- prefix)
+framework-type: story  # story, task, bug, epic
+framework-status: in-progress
+framework-priority: high
+framework-milestone: Feb2026
+framework-sprint: 2026-W03
+
+# Content metadata (no prefix)
+title: Forecast 180d LR marker and timestamps
+labels: [forecasting, reliability, frontend]
+assignee: unassigned
+---
+```
+
+**See Also:** `building-tickets` skill for complete v10.1.1 format specification.
+
+### 5. Apply "Jira is Source of Truth" Principle
+
+**Principle:** Preserve full Jira names, IDs, and references exactly as they appear in Jira
+
+**What to Preserve:**
+- ✅ Full Jira ticket IDs (DAPM-XXXX)
+- ✅ Jira milestone names exactly as they appear
+- ✅ Jira sprint names exactly as they appear
+- ✅ Jira component names (e.g., "APM: Reliability App - Frontend")
+- ✅ Jira epic names and links
+
+**Why:**
+- Maintains bidirectional sync integrity
+- Enables import/export without data loss
+- Preserves Jira relationships and dependencies
+- Allows Jira CSV imports to find existing tickets
+
+**Example:**
+```yaml
+# YAML frontmatter preserves Jira IDs
+jira-ticketId: DAPM-1164
+jira-url: "https://{your-org}.atlassian.net/browse/PROJ-1164"
+jira-parent: DAPM-1171
+jira-component: "APM: Reliability App"  # Exact Jira component name
+```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Importing Jira Sprint
+
+**When:** You have a Jira sprint exported as CSV and want to import it into the backlog module
+
+```bash
+# 1. Export sprint from Jira as CSV
+# (done via Jira UI: Filters → Export → CSV)
+
+# 2. Import using backlog CLI
+agentic-framework backlog import --csv jira-sprint-2026-W03.csv
+
+# 3. CLI creates:
+# - Ticket markdown files with YAML metadata
+# - Preserves Jira IDs and relationships
+# - Organizes by framework-type field
+```
+
+### Pattern 2: Generating Milestone Overviews
+
+**When:** You want to auto-generate milestone overview files from ticket metadata
+
+```bash
+# 1. Ensure tickets have framework-milestone field in YAML
+# Example: framework-milestone: Feb2026
+
+# 2. Run milestone migration CLI
+agentic-framework backlog migrate-milestones
+
+# 3. CLI generates:
+# - Milestone overview files
+# - Statistics (total tickets, by status, by type)
+# - Links to all tickets in milestone
+```
+
+### Pattern 3: Validating Ticket Format
+
+**When:** Before committing ticket changes, validate YAML format and markdown syntax
+
+```bash
+# Validate all tickets
+agentic-framework backlog validate
+
+# Fix any errors reported:
+# - Invalid YAML frontmatter
+# - Missing required fields
+# - Broken markdown links
+# - Incorrect prefix usage
+```
+
+### Pattern 4: Exporting to Jira
+
+**When:** You have tickets ready to export to Jira
+
+```bash
+# Use jira module CLI (not backlog module)
+agentic-framework jira export --tickets <ticket-files>
+
+# AUTO-DETECT mode:
+# - If jira-ticketId exists → UPDATE existing Jira issue
+# - If jira-ticketId is null/missing → CREATE new Jira issue
+```
+
+**See Also:** `committing-code` skill for Git operations with Jira auto-detection.
+
+---
+
+## Best Practices
+
+### File Organization
+- ✅ Use backlog module TypeScript CLI for all operations
+- ✅ Assign milestone via YAML `framework-milestone:` field (not in filename)
+- ✅ Organize by type using YAML `framework-type:` field
+- ✅ Link epics in YAML using `jira-parent:` field
+- ❌ Don't create files with milestone prefix in filename
+- ❌ Don't use Python scripts (they don't exist in new framework)
+
+### Naming Consistency
+- ✅ Use Jira ticket number after export (`1164-title.md`)
+- ✅ Use kebab-case for all titles
+- ✅ Remove redundant prefixes (DAPM-, APM-R:, etc.)
+- ❌ Don't include type prefix in filename (use YAML field)
+- ❌ Don't change filename format from what CLI generates
+
+### Metadata Management
+- ✅ Preserve exact Jira component names
+- ✅ Store Jira IDs in YAML frontmatter with `jira-` prefix
+- ✅ Use `framework-` prefix for framework-specific metadata
+- ✅ Use `framework-milestone:` and `framework-sprint:` fields for assignment
+- ❌ Don't modify Jira IDs or names
+- ❌ Don't duplicate metadata in filename
+
+### CLI Usage
+- ✅ Use TypeScript CLI commands for automation
+- ✅ Run validation before commits
+- ✅ Import Jira data via CLI (preserves metadata)
+- ❌ Don't manually create YAML (use CLI to import)
+- ❌ Don't bypass validation (errors indicate issues)
+
+---
+
+## Anti-Patterns to Avoid
+
+❌ **Using Python scripts from old framework**
+- Old framework used `backlog-milestone-generator.py`, `import_jira_data.py`
+- New framework uses TypeScript CLI commands exclusively
+
+❌ **Adding milestone prefix to filename**
+- Use YAML `framework-milestone:` field instead
+
+❌ **Modifying Jira ticket IDs or component names**
+- Jira is source of truth - preserve exactly
+
+❌ **Skipping validation**
+- Always run `backlog validate` before committing changes
+
+❌ **Mixing old v1 repo patterns with new framework**
+- Old repo had `backlog/` directory structure
+- New framework uses self-contained backlog module
+
+---
+
+## See Also
+
+### Related Skills
+- [building-tickets](../building-tickets/SKILL.md) - v10.1.1 ticket format and YAML schema
+- [committing-code](../../../../core/skills/committing-code/SKILL.md) - Git workflows with Jira auto-detection
+
+### Module Documentation
+- **Backlog Module Manifest:** `framework/modules/backlog/module.json`
+- **CLI Commands:** `framework/modules/backlog/src/cli/`
+- **Models:** `framework/modules/backlog/src/models/`
+
+### Registry Files
+- **Skills Registry:** `ai/registries/skills.json` - Skill metadata and paths
+- **Discovery Map:** `ai/registries/discovery-map.json` - Capability routing
+
+---
+
+**Version:** 1.0 (adapted from v1 repo)
+**Created:** 2025-12-22
+**Status:** Production-Ready (Phase 3 Migration)
+**Original:** `apmr-managing-organizing-backlog` (v1 repo)

package/framework/modules/backlog/skills/backlog/organizing-backlog/WORKFLOW-PIPELINE.md

@@ -0,0 +1,298 @@
+# Workflow Pipeline
+
+Step-by-step guide for ticket lifecycle in the backlog module using TypeScript CLI.
+
+---
+
+## Overview
+
+The backlog module uses a simplified workflow for ticket management:
+
+```
+Creation → Validation → Export to Jira → Import from Jira
+```
+
+**Key Differences from Old Framework:**
+- ✅ **TypeScript CLI** commands (not Python scripts)
+- ✅ **Module-based** architecture (not backlog/ directory)
+- ✅ **YAML frontmatter** with flat structure (jira- and framework- prefixes)
+- ✅ **AUTO-DETECT mode** for Jira export (CREATE vs UPDATE)
+
+---
+
+## Stage 1: Creation
+
+**Agent:** ai-backlog-manager
+
+**Method:** Create ticket using backlog module API
+
+### Steps
+
+1. **Create ticket with YAML frontmatter**
+   ```yaml
+   ---
+   # Framework metadata (framework- prefix)
+   framework-type: story  # story, task, bug, epic, spike
+   framework-status: draft
+   framework-priority: high
+   framework-milestone: Feb2026
+
+   # Jira metadata (jira- prefix, null until export)
+   jira-ticketId: null
+   jira-url: null
+   jira-component: "APM:  Reliability App - Frontend"
+   jira-parent: null
+
+   # Content metadata (no prefix)
+   title: "Auth0 SSO Configuration"
+   labels: [auth, frontend, feature]
+   assignee: unassigned
+   ---
+   ```
+
+2. **Write ticket content**
+   - Use native markdown (NOT Jira markup)
+   - Follow v10.1.1 format (see `building-tickets` skill)
+   - Include all required sections
+
+3. **Self-verification**
+   - Check against Definition of Ready
+   - Validate YAML frontmatter
+   - Ensure completeness
+
+---
+
+## Stage 2: Validation
+
+**CLI Command:**
+```bash
+agentic-framework backlog validate
+```
+
+**What it checks:**
+- ✅ YAML frontmatter format (flat structure, correct prefixes)
+- ✅ Required fields (title, type, status)
+- ✅ Markdown syntax
+- ✅ Link validity
+- ✅ Component names match Jira
+
+**Example Output:**
+```
+Validating tickets...
+✅ 1164-forecast-180d-lr-marker-and-timestamps.md
+❌ 1234-invalid-ticket.md
+   - Missing framework-type field
+   - Invalid jira-component name
+
+1 valid, 1 invalid
+```
+
+---
+
+## Stage 3: Jira Export
+
+**CLI Command:**
+```bash
+# Export single ticket
+agentic-framework jira export --tickets <ticket-file>
+
+# Dry-run validation (no actual export)
+agentic-framework jira export --tickets <ticket-file> --dry-run
+```
+
+**AUTO-DETECT Mode:**
+- **If `jira-ticketId` exists** → UPDATE existing Jira issue
+- **If `jira-ticketId` is null/missing** → CREATE new Jira issue
+
+### Steps
+
+1. **Read ticket**
+   - Parse YAML frontmatter
+   - Parse markdown content
+
+2. **Convert markdown → Jira wiki markup**
+   - Native markdown → Jira syntax
+   - Preserve formatting and structure
+
+3. **Call Jira REST API**
+   - CREATE new issue OR UPDATE existing issue (auto-detected)
+   - Set fields from YAML metadata
+   - Receive Jira ticket ID (DAPM-XXXX)
+
+4. **Update YAML metadata**
+   ```yaml
+   jira-ticketId: DAPM-1234
+   jira-url: "https://{your-org}.atlassian.net/browse/PROJ-1234"
+   jira-exportedDate: 2025-12-22
+   ```
+
+**Example:**
+```bash
+# Before export
+YAML: jira-ticketId: null
+
+# After export (CREATE mode)
+YAML: jira-ticketId: DAPM-1234
+```
+
+---
+
+## Stage 4: Import from Jira CSV
+
+**CLI Command:**
+```bash
+# Import Jira CSV export
+agentic-framework backlog import --csv <file>
+```
+
+### Steps
+
+1. **Export from Jira**
+   - Use Jira CSV export feature
+   - Save CSV file
+
+2. **Run import CLI**
+   - Parses CSV (columns: Issue key, Summary, Issue Type, Status, etc.)
+   - Converts Jira wiki markup → markdown
+   - Generates YAML frontmatter with Jira metadata
+   - Creates ticket files with Jira ticket number in filename
+
+3. **Output:**
+   - Ticket files created with YAML metadata
+   - Jira IDs, names, and metadata preserved exactly
+
+**Example CSV → YAML:**
+```csv
+Issue key,Summary,Component,Epic Link
+DAPM-1234,"Implement SSO","APM:  Reliability App - Frontend",DAPM-1171
+```
+
+**Generated YAML:**
+```yaml
+---
+jira-ticketId: DAPM-1234
+title: "Implement SSO"
+jira-component: "APM:  Reliability App - Frontend"  # Exact match
+jira-parent: DAPM-1171
+framework-type: story
+---
+```
+
+---
+
+## Stage 5: Milestone Generation
+
+**CLI Command:**
+```bash
+# Auto-generate milestone overviews from ticket metadata
+agentic-framework backlog migrate-milestones
+```
+
+### Steps
+
+1. **Scan tickets**
+   - Read `framework-milestone:` field from all ticket YAML
+   - Group tickets by milestone code
+
+2. **Generate milestone files**
+   - Create overview with ticket list
+   - Include statistics (ticket counts, story points)
+
+**Example Output:**
+```
+Generating milestones...
+✅ Feb2026.md (4 tickets, 15 story points)
+✅ Mar2026.md (2 tickets, 8 story points)
+
+2 milestones generated
+```
+
+---
+
+## Workflow Decision Tree
+
+```
+START
+  │
+  ├─ Creating new ticket?
+  │    └─> Create with YAML metadata, validate with CLI
+  │
+  ├─ Exporting to Jira?
+  │    └─> Run jira export CLI (auto-detects CREATE vs UPDATE)
+  │
+  ├─ Importing from Jira?
+  │    └─> Run backlog import CLI (parses CSV, creates tickets)
+  │
+  ├─ Generating milestone overview?
+  │    └─> Run backlog migrate-milestones CLI
+  │
+  └─ Validating tickets?
+       └─> Run backlog validate CLI
+```
+
+---
+
+## CLI Commands Summary
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `backlog validate` | Validate ticket format | `agentic-framework backlog validate` |
+| `backlog import` | Import Jira CSV | `agentic-framework backlog import --csv <file>` |
+| `backlog migrate-milestones` | Generate milestone overviews | `agentic-framework backlog migrate-milestones` |
+| `jira export` | Export to Jira (CREATE/UPDATE) | `agentic-framework jira export --tickets <file>` |
+
+---
+
+## Best Practices
+
+### During Creation
+- ✅ Use native markdown (NOT Jira markup)
+- ✅ Complete all YAML fields (except jira-* fields)
+- ✅ Validate with CLI before committing
+- ❌ Don't skip sections or leave placeholders
+
+### During Export
+- ✅ Use dry-run mode to validate first
+- ✅ Check Jira ticket created/updated successfully
+- ✅ Verify YAML metadata updated
+- ❌ Don't bypass validation
+
+**Dry-run example:**
+```bash
+agentic-framework jira export --tickets <file> --dry-run
+```
+
+### After Export
+- ✅ Verify `jira-ticketId` and `jira-url` fields updated
+- ✅ Check Jira URL works
+- ✅ Confirm ticket searchable in Jira
+- ❌ Don't manually edit `jira-ticketId` field
+
+---
+
+## Troubleshooting
+
+**Issue:** Export fails (API error)
+- **Solution:** Check Jira credentials, network connectivity, validate ticket format
+
+**Issue:** YAML metadata not updated after export
+- **Solution:** Check CLI output for errors, verify file permissions
+
+**Issue:** Milestone file not generated
+- **Solution:** Check tickets have `framework-milestone:` YAML field, re-run CLI
+
+**Issue:** Validation fails
+- **Solution:** Read CLI error output, fix YAML frontmatter issues
+
+---
+
+## See Also
+
+- **Ticket Format:** [building-tickets](../building-tickets/SKILL.md) - v10.1.1 YAML structure
+- **Jira Integration:** [JIRA-SOURCE-OF-TRUTH.md](JIRA-SOURCE-OF-TRUTH.md) - Jira integration principles
+- **Naming:** [NAMING-CONVENTIONS.md](NAMING-CONVENTIONS.md) - File naming rules
+- **Module CLI:** Backlog and Jira module TypeScript CLI commands
+
+---
+
+**Note:** This workflow uses TypeScript CLI commands exclusively. Python scripts from old framework (export_to_jira.py, import_jira_data.py) do NOT exist in the new framework.