cc-agentic-framework 1.14.1

package/framework/modules/backlog/skills/backlog/building-tickets/templates/task.template.md

@@ -0,0 +1,66 @@
+---
+documentType: task
+title: "{{summary}}"
+description: "One-sentence summary of the task"
+milestone: null
+priority: P1
+storyPoints: 3
+labels: []
+createdDate: "{{date}}"
+exportedDate: null
+
+# Jira Integration Fields (v10.1.1)
+jira-ticketId: null
+jira-url: null
+jira-parent: null
+jira-related: []
+jira-blocking: []
+jira-blockedBy: []
+jira-fixVersion: null
+jira-internalNotes: null
+
+# Framework Integration Fields (v10.1.1)
+framework-documentation: null
+framework-milestone: null
+framework-technicalGuides: []
+framework-relatedLocal: []
+---
+
+# {{summary}}
+
+---
+
+## Description
+
+**AS** a [team member/role],
+**I WANT** [capability/change],
+**SO THAT** [outcome/benefit].
+
+**Context:**
+
+[2-3 plain language paragraphs explaining what needs to be done and why. Focus on the problem being solved and the expected outcome.]
+
+**Subtasks:**
+
+* [Subtask 1 - specific action item]
+* [Subtask 2 - specific action item]
+* [Subtask 3 - specific action item]
+
+**Technical Notes:**
+
+* [High-level approach or patterns to use]
+* [Dependencies or considerations]
+* [Security or performance notes if applicable]
+
+---
+
+## Acceptance Criteria
+
+* **Verify** [specific testable condition 1]
+* **Verify** [specific testable condition 2]
+* **Verify** [specific testable condition 3]
+* **Verify** [specific testable condition 4]
+* **Verify** [specific testable condition 5]
+* **Verify** code is complete and reviewed
+* **Verify** tests are passing
+* **Verify** documentation is updated

package/framework/modules/backlog/skills/backlog/building-tickets/templates/template.config.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "../../../../../core/registries/schemas/template.schema.json",
+  "version": "1.0",
+  "templates": {
+    "story.template": {
+      "output": "{{name}}.md",
+      "description": "Create a user story ticket",
+      "variables": {
+        "required": ["summary"],
+        "optional": ["name"],
+        "computed": ["date"]
+      },
+      "defaults": {}
+    },
+    "task.template": {
+      "output": "{{name}}.md",
+      "description": "Create a task ticket",
+      "variables": {
+        "required": ["summary"],
+        "optional": ["name"],
+        "computed": ["date"]
+      },
+      "defaults": {}
+    },
+    "bug.template": {
+      "output": "{{name}}.md",
+      "description": "Create a bug ticket",
+      "variables": {
+        "required": ["summary"],
+        "optional": ["name"],
+        "computed": ["date"]
+      },
+      "defaults": {}
+    },
+    "epic.template": {
+      "output": "{{name}}.md",
+      "description": "Create an epic ticket",
+      "variables": {
+        "required": ["summary"],
+        "optional": ["name"],
+        "computed": ["date"]
+      },
+      "defaults": {}
+    }
+  },
+  "autoNumbering": {
+    "pattern": "{documentType}-{num}",
+    "padding": 3
+  }
+}

package/framework/modules/backlog/skills/backlog/organizing-backlog/DIRECTORY-STRUCTURE.md

@@ -0,0 +1,195 @@
+# Backlog Module Structure
+
+Complete reference for backlog module organization and architecture.
+
+---
+
+## Module Top-Level Structure
+
+```
+framework/modules/backlog/
+├── agents/               # Backlog management agents
+│   ├── ai-backlog-manager.md
+│
+├── skills/backlog/       # Skills (this skill + building-tickets)
+│   ├── organizing-backlog/
+│   └── building-tickets/
+│
+├── commands/             # Slash command definitions
+│   ├── cmd-backlog-create-ticket.md
+│   ├── cmd-backlog-validate.md
+│   ├── cmd-backlog-import.md
+│   └── cmd-backlog-migrate-milestones.md
+│
+├── src/
+│   ├── cli/            # TypeScript CLI commands
+│   │   ├── import.ts   # Import Jira data
+│   │   ├── validate.ts # Validate ticket format
+│   │   ├── migrate-milestones.ts  # Generate milestone overviews
+│   │   └── update-fields.ts  # Update ticket metadata
+│   │
+│   ├── models/         # Ticket, Epic, Milestone models
+│   │   ├── Ticket.ts
+│   │   ├── Epic.ts
+│   │   └── Milestone.ts
+│   │
+│   └── utils/          # Parsing, validation utilities
+│       ├── yaml-parser.ts
+│       ├── validator.ts
+│       └── markdown-converter.ts
+│
+└── module.json         # Module manifest
+```
+
+---
+
+## Key Architecture Principles
+
+### 1. Self-Contained Module
+
+**No External Directory Dependencies:**
+- ❌ NO `backlog/` directory in project root
+- ✅ All logic in `framework/modules/backlog/`
+- ✅ TypeScript implementation in `src/`
+- ✅ CLI commands for automation
+
+### 2. TypeScript CLI Commands
+
+**Available Commands:**
+```bash
+agentic-framework backlog import --csv <file>
+agentic-framework backlog validate
+agentic-framework backlog migrate-milestones
+agentic-framework backlog update-fields
+```
+
+**No Python Scripts:**
+- ❌ `backlog-milestone-generator.py` (doesn't exist)
+- ❌ `import_jira_data.py` (doesn't exist)
+- ✅ TypeScript CLI equivalents implemented
+
+### 3. YAML Frontmatter Structure
+
+**Flat Structure with Prefixes:**
+```yaml
+---
+# Jira metadata (jira- prefix)
+jira-ticketId: DAPM-1234
+jira-url: "https://..."
+jira-component: "APM:  Reliability App - Frontend"
+jira-parent: DAPM-1171
+
+# Framework metadata (framework- prefix)
+framework-type: story  # story, task, bug, epic, spike
+framework-status: in-progress
+framework-priority: high
+framework-milestone: Feb2026
+
+# Content metadata (no prefix)
+title: "Ticket title"
+labels: [label1, label2]
+assignee: unassigned
+---
+```
+
+---
+
+## File Storage Patterns
+
+### Ticket Files
+
+**Location:** Managed by backlog module (not in project backlog/ directory)
+
+**Naming:**
+- Before Jira export: Can vary (created by agents)
+- After Jira export: `[NUMBER]-[title-kebab-case].md`
+
+**Example:**
+```
+1164-forecast-180d-lr-marker-and-timestamps.md
+```
+
+**YAML Metadata:**
+- Type assignment: `framework-type:` field (story, task, bug, epic)
+- Milestone assignment: `framework-milestone:` field (Feb2026, Mar2026)
+- Jira integration: `jira-ticketId`, `jira-url`, `jira-component`, etc.
+
+### Milestone Files
+
+**Auto-Generated:** Via `backlog migrate-milestones` CLI
+
+**Format:**
+```yaml
+---
+framework-milestone: Feb2026
+jira-milestone: "APM-R App - February 2026 - W3 W5 W7"
+generatedDate: 2025-12-22
+totalTickets: 4
+totalStoryPoints: 15
+---
+
+# Milestone: Feb2026
+
+## Stories (2 tickets, 10 points)
+- DAPM-1164 (5 pts): Forecast (+180d), L/R marker, and timestamps
+- DAPM-1166 (5 pts): Final drive divisions support
+
+## Tasks (1 ticket, 3 points)
+- DAPM-1032 (3 pts): Migrate to API v2
+
+## Total: 4 tickets, 15 story points
+```
+
+---
+
+## CLI Commands Reference
+
+| CLI Command | Source Code | Purpose |
+|-------------|-------------|---------|
+| `backlog import` | `src/cli/import.ts` | Import Jira CSV export |
+| `backlog validate` | `src/cli/validate.ts` | Validate ticket format and YAML |
+| `backlog migrate-milestones` | `src/cli/migrate-milestones.ts` | Generate milestone overviews |
+| `backlog update-fields` | `src/cli/update-fields.ts` | Batch update ticket metadata |
+
+---
+
+## Integration with Jira Module
+
+**Jira Export:**
+```bash
+agentic-framework jira export --tickets <file>
+```
+- **AUTO-DETECT mode:** Creates new OR updates existing Jira issues
+- **Source:** Jira module (`framework/modules/jira/`)
+- **Coordination:** Backlog module creates tickets, Jira module exports them
+
+**Workflow:**
+1. Backlog module creates tickets with YAML metadata
+2. Jira module exports to Jira (AUTO-DETECT CREATE vs UPDATE)
+3. Backlog module imports Jira updates via CSV
+4. Backlog module generates milestone overviews
+
+---
+
+## Comparison with Old Framework
+
+| Aspect | Old v1 Repo | New v1.0 Framework |
+|--------|-------------|---------------------|
+| **Directory** | `backlog/` in project root | Module in `framework/modules/backlog/` |
+| **Automation** | Python scripts | TypeScript CLI commands |
+| **Workflow** | draft/ → ready-to-export/ → permanent/ | Simplified: creation → validation → export |
+| **Organization** | tickets/stories/, tickets/tasks/, etc. | Managed by module (flexible) |
+| **Metadata** | Various YAML formats | Flat structure with prefixes |
+
+---
+
+## See Also
+
+- **Module Manifest:** `framework/modules/backlog/module.json` - Module capabilities and CLI commands
+- **Ticket Format:** [building-tickets](../building-tickets/SKILL.md) - v10.1.1 YAML structure
+- **CLI Source:** `framework/modules/backlog/src/cli/` - TypeScript implementation
+- **Jira Integration:** [integrating-jira](../../../../jira/skills/jira/integrating-jira/SKILL.md) - Jira export workflow
+
+---
+
+**Note:** This module architecture is self-contained and does NOT rely on a `backlog/` directory in the project root. All functionality is implemented in TypeScript and accessed via CLI commands.

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

@@ -0,0 +1,374 @@
+# Backlog Organization Examples
+
+Real-world scenarios for backlog module operations using TypeScript CLI.
+
+---
+
+## Example 1: Creating a New Story
+
+**Scenario:** ai-backlog-manager creates a new story for Auth0 SSO configuration
+
+### Step 1: Create Ticket with YAML Metadata
+
+**File:** `auth0-sso-configuration.md`
+
+```markdown
+---
+# Framework metadata
+framework-type: story
+framework-status: draft
+framework-priority: high
+framework-milestone: Feb2026
+
+# Jira metadata (null until export)
+jira-ticketId: null
+jira-url: null
+jira-component: "APM:  Reliability App - Frontend"
+jira-parent: null
+
+# Content metadata
+title: "Auth0 SSO Configuration"
+labels: [auth, frontend, feature]
+assignee: unassigned
+storyPoints: 5
+---
+
+# Auth0 SSO Configuration
+
+## Description
+
+**AS** a user,
+**I WANT** to authenticate via Auth0 SSO,
+**SO THAT** I can access the application securely.
+
+### Context
+
+Current authentication uses username/password. This story extends login to support SSO for enterprise customers.
+
+### Acceptance Criteria
+
+* Verify users can initiate SSO login
+* Verify SSO redirect to Auth0 works
+* Verify callback processes tokens correctly
+* Verify user session includes SSO metadata
+* Verify error handling for SSO failures
+* Verify logout clears SSO session
+```
+
+### Step 2: Validate Ticket
+
+**Command:**
+```bash
+agentic-framework backlog validate
+```
+
+**Output:**
+```
+Validating tickets...
+✅ auth0-sso-configuration.md
+   - framework-type: story
+   - jira-component: valid
+   - YAML structure: valid
+
+1 ticket validated, 0 errors
+```
+
+### Step 3: Export to Jira
+
+**Command:**
+```bash
+# Dry-run first (validate only)
+agentic-framework jira export --tickets auth0-sso-configuration.md --dry-run
+
+# Actual export
+agentic-framework jira export --tickets auth0-sso-configuration.md
+```
+
+**AUTO-DETECT Mode:** Since `jira-ticketId: null`, CLI creates NEW Jira issue
+
+**After Export:**
+```yaml
+---
+jira-ticketId: DAPM-1234
+jira-url: "https://{your-org}.atlassian.net/browse/PROJ-1234"
+jira-exportedDate: 2025-12-22
+---
+```
+
+**File renamed to:** `1234-auth0-sso-configuration.md`
+
+---
+
+## Example 2: Updating Existing Jira Ticket
+
+**Scenario:** Update local ticket and sync changes back to Jira
+
+### Step 1: Modify Ticket Locally
+
+**File:** `1234-auth0-sso-configuration.md`
+
+**Change:** Update acceptance criteria
+
+```yaml
+---
+jira-ticketId: DAPM-1234  # Existing Jira ID
+jira-url: "https://{your-org}.atlassian.net/browse/PROJ-1234"
+---
+
+# Auth0 SSO Configuration
+
+## Acceptance Criteria
+
+* Verify users can initiate SSO login
+* Verify SSO redirect to Auth0 works
+* Verify callback processes tokens correctly
+* Verify user session includes SSO metadata
+* Verify error handling for SSO failures
+* Verify logout clears SSO session
+* **NEW:** Verify SSO works with multiple identity providers
+* **NEW:** Verify SSO domain detection is case-insensitive
+```
+
+### Step 2: Export to Jira (UPDATE Mode)
+
+**Command:**
+```bash
+agentic-framework jira export --tickets 1234-auth0-sso-configuration.md
+```
+
+**AUTO-DETECT Mode:** Since `jira-ticketId: DAPM-1234` exists, CLI updates EXISTING Jira issue
+
+**Result:** Jira ticket DAPM-1234 updated with new acceptance criteria
+
+---
+
+## Example 3: Importing Jira Sprint CSV
+
+**Scenario:** Import a sprint from Jira CSV export
+
+### Step 1: Export from Jira
+
+**Jira Actions:**
+1. Navigate to sprint board
+2. Select "Sprint 2026-W01"
+3. Export as CSV: `APMR-APP-2026W1.csv`
+
+**CSV Content:**
+```csv
+Issue key,Summary,Issue Type,Component,Epic Link,Sprint,Story Points
+DAPM-1234,"Auth0 SSO Configuration",Story,"APM:  Reliability App - Frontend",DAPM-1171,"Sprint W01",5
+DAPM-1235,"Implement caching",Task,"APM:  Reliability App - Backend",,"Sprint W01",3
+```
+
+### Step 2: Run Import CLI
+
+**Command:**
+```bash
+agentic-framework backlog import --csv APMR-APP-2026W1.csv
+```
+
+**CLI Actions:**
+1. Parse CSV file
+2. Convert Jira wiki markup → markdown for each ticket
+3. Generate YAML frontmatter preserving exact Jira values
+4. Create ticket files with Jira ticket number in filename
+
+### Step 3: Output Files
+
+**Story:** `1234-auth0-sso-configuration.md`
+```yaml
+---
+framework-type: story
+jira-ticketId: DAPM-1234
+jira-component: "APM:  Reliability App - Frontend"  # Exact from Jira
+jira-parent: DAPM-1171
+jira-sprint: "Sprint W01"
+framework-milestone: Feb2026  # Derived or set via CLI
+storyPoints: 5
+---
+```
+
+**Task:** `1235-implement-caching.md`
+```yaml
+---
+framework-type: task
+jira-ticketId: DAPM-1235
+jira-component: "APM:  Reliability App - Backend"
+jira-sprint: "Sprint W01"
+storyPoints: 3
+---
+```
+
+---
+
+## Example 4: Generating Milestone Overview
+
+**Scenario:** Auto-generate milestone overview from ticket metadata
+
+### Step 1: Tickets with Milestone Metadata
+
+**Tickets:**
+- `1234-auth0-sso-configuration.md` (framework-milestone: Feb2026)
+- `1166-final-drive-support.md` (framework-milestone: Feb2026)
+- `1032-migrate-to-api-v2.md` (framework-milestone: Feb2026)
+- `1315-fix-shimmer-loading.md` (framework-milestone: Feb2026)
+
+### Step 2: Run Milestone Generation
+
+**Command:**
+```bash
+agentic-framework backlog migrate-milestones
+```
+
+**CLI Actions:**
+1. Scan all tickets for `framework-milestone:` field
+2. Group tickets by milestone code
+3. Count tickets by type and story points
+4. Generate milestone overview file
+
+### Step 3: Generated File
+
+**File:** `Feb2026-milestone-overview.md` (or similar)
+
+```yaml
+---
+framework-milestone: Feb2026
+jira-milestone: "APM-R App - February 2026 - W3 W5 W7"
+generatedDate: 2025-12-22
+totalTickets: 4
+totalStoryPoints: 15
+---
+
+# Milestone: Feb2026
+
+## Summary
+
+**Total Tickets:** 4
+**Total Story Points:** 15
+
+## Stories (2 tickets, 10 points)
+- DAPM-1234 (5 pts): Auth0 SSO Configuration
+- DAPM-1166 (5 pts): Final drive divisions support
+
+## Tasks (1 ticket, 3 points)
+- DAPM-1032 (3 pts): Migrate to API v2
+
+## Bugs (1 ticket, 2 points)
+- DAPM-1315 (2 pts): Fix shimmer loading
+
+## Breakdown by Status
+- In Progress: 2 tickets (8 points)
+- To Do: 1 ticket (5 points)
+- Done: 1 ticket (2 points)
+```
+
+---
+
+## Example 5: Batch Validation
+
+**Scenario:** Validate multiple tickets before committing
+
+### Step 1: Run Validation
+
+**Command:**
+```bash
+agentic-framework backlog validate
+```
+
+**Output:**
+```
+Validating tickets...
+
+✅ 1234-auth0-sso-configuration.md
+   - framework-type: story
+   - jira-component: valid
+   - YAML structure: valid
+
+❌ 1235-incomplete-ticket.md
+   - ERROR: Missing framework-type field
+   - ERROR: Invalid jira-component: "APM: Reliability App" (should be "APM:  Reliability App")
+   - WARNING: Missing storyPoints field
+
+✅ 1166-final-drive-support.md
+   - framework-type: story
+   - jira-component: valid
+   - YAML structure: valid
+
+Summary: 2 valid, 1 invalid
+```
+
+### Step 2: Fix Errors
+
+**Edit:** `1235-incomplete-ticket.md`
+
+```yaml
+---
+framework-type: task  # Added
+jira-component: "APM:  Reliability App"  # Fixed (two spaces after colon)
+storyPoints: 3  # Added
+---
+```
+
+### Step 3: Re-Validate
+
+**Command:**
+```bash
+agentic-framework backlog validate
+```
+
+**Output:**
+```
+Validating tickets...
+✅ All 3 tickets valid
+```
+
+---
+
+## CLI Commands Quick Reference
+
+| Task | Command | Example |
+|------|---------|---------|
+| **Validate tickets** | `backlog validate` | `agentic-framework backlog validate` |
+| **Import Jira CSV** | `backlog import --csv <file>` | `agentic-framework backlog import --csv sprint.csv` |
+| **Generate milestones** | `backlog migrate-milestones` | `agentic-framework backlog migrate-milestones` |
+| **Export to Jira (CREATE)** | `jira export --tickets <file>` | `agentic-framework jira export --tickets ticket.md` |
+| **Export to Jira (UPDATE)** | `jira export --tickets <file>` | `agentic-framework jira export --tickets 1234-ticket.md` |
+| **Dry-run export** | `jira export --tickets <file> --dry-run` | `agentic-framework jira export --tickets ticket.md --dry-run` |
+
+---
+
+## Workflow Best Practices
+
+### Before Export
+1. ✅ Create ticket with complete YAML metadata
+2. ✅ Run `backlog validate` to check format
+3. ✅ Use `jira export --dry-run` to validate Jira integration
+4. ✅ Fix any errors reported by validation
+
+### During Export
+1. ✅ CLI auto-detects CREATE vs UPDATE mode
+2. ✅ Check CLI output for success/failure
+3. ✅ Verify `jira-ticketId` and `jira-url` fields updated
+
+### After Export
+1. ✅ Verify Jira ticket created/updated in Jira UI
+2. ✅ Check ticket filename updated with Jira number (CREATE mode)
+3. ✅ Run `backlog validate` to confirm metadata is correct
+
+### Periodic Maintenance
+1. ✅ Run `backlog migrate-milestones` to update milestone overviews
+2. ✅ Import Jira sprints via `backlog import` to sync updates
+3. ✅ Validate all tickets before major commits
+
+---
+
+## See Also
+
+- **CLI Commands:** [WORKFLOW-PIPELINE.md](WORKFLOW-PIPELINE.md) - Detailed CLI workflow
+- **Jira Integration:** [JIRA-SOURCE-OF-TRUTH.md](JIRA-SOURCE-OF-TRUTH.md) - Jira integration principles
+- **Validation Rules:** [building-tickets](../building-tickets/SKILL.md) - v10.1.1 format specification
+- **Naming:** [NAMING-CONVENTIONS.md](NAMING-CONVENTIONS.md) - File naming rules
+
+---
+
+**Note:** All examples use TypeScript CLI commands from the backlog and jira modules. Python scripts from the old framework do NOT exist in the new framework.