cc-agentic-framework 1.14.1

package/framework/modules/backlog/skills/backlog/building-tickets/YAML-STRUCTURE.md

@@ -0,0 +1,439 @@
+# YAML Frontmatter Structure (v10.1.1)
+
+## Complete Field Reference
+
+### Generic Fields (All Ticket Types)
+
+```yaml
+documentType: story|task|bug|spike|epic    # REQUIRED: Type of ticket
+title: "Descriptive title"                 # REQUIRED: Ticket title
+description: "One-line summary"            # REQUIRED: Executive summary
+component: "APM: Reliability App"          # REQUIRED: Jira component (exact: 2 spaces)
+createdDate: 2025-12-08                    # REQUIRED: Creation date (ISO 8601)
+```
+
+### Story/Task Specific Fields
+
+```yaml
+component: "APM: Reliability App"         # OPTIONAL: Jira component (must be exact format with 2 spaces)
+milestone: Feb2026                         # OPTIONAL: Milestone code (Feb2026, Mar2026, etc.)
+priority: P0|P1|P2                        # OPTIONAL: Priority level
+storyPoints: 5                             # OPTIONAL: Story points (1,2,3,5,8)
+labels: [apm-r, frontend, feature]        # OPTIONAL: Jira labels array
+```
+
+### Post-Export Fields (Auto-Filled by ai-jira-manager)
+
+```yaml
+exportedDate: 2025-12-08                  # Auto-filled after Jira export
+```
+
+### Jira Integration Fields (v10.1.1 - Flat with jira- prefix)
+
+```yaml
+jira-ticketId: DAPM-1234                  # Auto-filled: Jira ticket ID
+jira-url: "https://..."                   # Auto-filled: Full Jira URL
+jira-parent: DAPM-1171                    # OPTIONAL: Parent epic ID (if subtask/child)
+jira-related: [DAPM-1234, DAPM-1235]      # OPTIONAL: Array of related ticket IDs
+jira-blocking: [DAPM-999]                 # OPTIONAL: Array of tickets this blocks
+jira-blockedBy: [DAPM-888]                # OPTIONAL: Array of tickets blocking this
+jira-fixVersion: "2025-02"                # OPTIONAL: Release version ID
+jira-internalNotes: "Process notes"       # OPTIONAL: Internal notes (not exported)
+```
+
+### Framework Integration Fields (v10.1.1 - Flat with framework- prefix)
+
+```yaml
+framework-documentation: "@apm-r-be/CLAUDE.md"  # OPTIONAL: Cross-repo file ref
+framework-milestone: "backlog/milestones/Feb2026.md"  # OPTIONAL: Local milestone path
+framework-technicalGuides: ["@apm-r-be/docs/api.md"]  # OPTIONAL: Array of technical refs
+framework-relatedLocal: ["backlog/epics/EPIC-1171.md"]  # OPTIONAL: Array of local refs
+```
+
+---
+
+## Field Definitions
+
+### documentType
+**Required.** The type of ticket being created.
+
+**Values:**
+- `story` - User story (has AS/WANT/SO THAT format)
+- `task` - Implementation task (no user story format)
+- `bug` - Bug report
+- `spike` - Research/investigation task
+- `epic` - Epic (high-level feature grouping)
+
+**Example:**
+```yaml
+documentType: story
+```
+
+---
+
+### title
+**Required.** Descriptive ticket title (same as H1 in body).
+
+**Format:**
+- For stories/tasks/bugs: `[Project]: [FE|BE|FS]: [Component]: [Feature]`
+- For epics: `[Project]: [Component]: [Epic Theme]`
+
+**Rules:**
+- Clear and descriptive (30-80 characters)
+- No ticket numbers or prefixes in title
+- Use colons to separate segments
+
+**Example:**
+```yaml
+title: "APM-R: FE: Dashboard: Configurable Cards"
+```
+
+---
+
+### description
+**Required.** One-sentence executive summary of the ticket.
+
+**Rules:**
+- Single sentence only (max 150 characters)
+- Clear purpose and value
+- Written for someone unfamiliar with the ticket
+
+**Example:**
+```yaml
+description: "Allow users to customize which cards appear on their dashboard"
+```
+
+---
+
+### component
+**Required for all tickets.** Jira component classification.
+
+**Allowed Values:**
+- `"APM: Reliability App"` (exactly this value with 2 spaces between colon and R)
+
+**Rules:**
+- Exactly one component per ticket (no arrays)
+- Must match exact format: "APM: Reliability App"
+- Case-sensitive
+- 2 spaces between "APM:" and "Reliability"
+
+**Example:**
+```yaml
+component: "APM: Reliability App"
+```
+
+---
+
+### milestone
+**Optional.** Milestone code for planning purposes.
+
+**Format:** Month+Year (e.g., Feb2026, Mar2026)
+
+**Rules:**
+- Use standardized milestone codes
+- Helps with sprint planning and release coordination
+- Can be null if not assigned yet
+
+**Example:**
+```yaml
+milestone: Feb2026
+```
+
+---
+
+### priority
+**Optional.** Priority level for Jira.
+
+**Values:**
+- `P0` - Critical (production outages, blocking work)
+- `P1` - High (important features, major issues)
+- `P2` - Medium (standard features, improvements)
+
+**Example:**
+```yaml
+priority: P1
+```
+
+---
+
+### storyPoints
+**Optional.** Story point estimation (stories/tasks only).
+
+**Values:** 1, 2, 3, 5, 8
+
+**Rules:**
+- Use Fibonacci-like sequence only
+- Never >8 points (break into smaller stories)
+- Can be null if not estimated yet
+- Epics do NOT have story points
+
+**Example:**
+```yaml
+storyPoints: 5
+```
+
+---
+
+### labels
+**Optional.** Jira labels for categorization.
+
+**Format:** YAML array of strings
+
+**Rules:**
+- Use lowercase with hyphens (kebab-case)
+- 2-5 labels per ticket
+- Common labels: project name, component, type (frontend, backend), priority indicators
+
+**Example:**
+```yaml
+labels: [apm-r, frontend, feature, priority-high]
+```
+
+---
+
+### createdDate
+**Required.** Date the ticket was created.
+
+**Format:** ISO 8601 (YYYY-MM-DD)
+
+**Rules:**
+- Auto-set when ticket is created
+- Should not be modified after creation
+
+**Example:**
+```yaml
+createdDate: 2025-12-08
+```
+
+---
+
+### exportedDate
+**Optional.** Date the ticket was exported to Jira.
+
+**Format:** ISO 8601 (YYYY-MM-DD) or null
+
+**Rules:**
+- Auto-filled by ai-jira-manager after export
+- null until exported
+- Used to track when tickets were synced to Jira
+
+**Example:**
+```yaml
+exportedDate: 2025-12-08
+```
+
+---
+
+### Jira Integration Fields (jira-*)
+
+#### jira-ticketId
+Jira ticket ID assigned after export (e.g., DAPM-1234).
+
+**Auto-filled:** By ai-jira-manager during export
+**Format:** PROJECT-NUMBER
+
+**Example:**
+```yaml
+jira-ticketId: DAPM-1234
+```
+
+#### jira-url
+Full Jira URL for the ticket.
+
+**Auto-filled:** By ai-jira-manager during export
+**Format:** `https://{your-org}.atlassian.net/browse/PROJ-XXXX`
+
+**Example:**
+```yaml
+jira-url: "https://{your-org}.atlassian.net/browse/PROJ-1234"
+```
+
+#### jira-parent
+Parent epic ID if this is a child story/task.
+
+**Optional.** Leave null if not a subtask.
+**Format:** `DAPM-XXXX`
+
+**Example:**
+```yaml
+jira-parent: DAPM-1171
+```
+
+#### jira-related
+Array of related ticket IDs.
+
+**Optional.** Array of related tickets (not blocking, just related).
+**Format:** `[DAPM-1234, DAPM-1235]`
+
+**Example:**
+```yaml
+jira-related: [DAPM-1200, DAPM-1210]
+```
+
+#### jira-blocking
+Array of tickets this ticket blocks.
+
+**Optional.** Tickets that are blocked by this ticket completing.
+**Format:** `[DAPM-1234, DAPM-1235]`
+
+**Example:**
+```yaml
+jira-blocking: [DAPM-999, DAPM-1000]
+```
+
+#### jira-blockedBy
+Array of tickets blocking this ticket.
+
+**Optional.** Tickets that must complete before this one.
+**Format:** `[DAPM-1234, DAPM-1235]`
+
+**Example:**
+```yaml
+jira-blockedBy: [DAPM-800, DAPM-810]
+```
+
+#### jira-fixVersion
+Release version ID for version linking.
+
+**Optional.** Used to link ticket to specific release version in Jira.
+**Format:** Version ID or null
+
+**Example:**
+```yaml
+jira-fixVersion: "2025-02"
+```
+
+#### jira-internalNotes
+Internal process notes (not exported to Jira).
+
+**Optional.** Internal tracking notes, not visible to Jira.
+**Format:** String or null
+
+**Example:**
+```yaml
+jira-internalNotes: "Waiting for architectural review before proceeding"
+```
+
+---
+
+### Framework Integration Fields (framework-*)
+
+#### framework-documentation
+Cross-repository file reference.
+
+**Optional.** Reference to documentation in other repositories.
+**Format:** `@repo-name/path/to/file.md`
+
+**Supported repos:**
+- `@apm-r-app` - Frontend repository
+- `@apm-r-be` - Backend repository
+- `@Infrastructure` - Infrastructure repository
+- `@apm-architecture` - Architecture documentation
+
+**Example:**
+```yaml
+framework-documentation: "@apm-r-be/src/services/auth/README.md"
+```
+
+#### framework-milestone
+Local milestone file reference.
+
+**Optional.** Reference to milestone file in current repository.
+**Format:** Repo-root-relative path
+
+**Example:**
+```yaml
+framework-milestone: "backlog/milestones/Feb2026.md"
+```
+
+#### framework-technicalGuides
+Array of technical guide references.
+
+**Optional.** References to technical documentation.
+**Format:** Array of paths or cross-repo references
+
+**Example:**
+```yaml
+framework-technicalGuides:
+  - "@apm-r-be/docs/api-design.md"
+  - "ai/context/technical-advanced.md"
+```
+
+#### framework-relatedLocal
+Array of local file references.
+
+**Optional.** References to other local files.
+**Format:** Array of repo-root-relative paths
+
+**Example:**
+```yaml
+framework-relatedLocal:
+  - "backlog/epics/1171-configurable-dashboard.md"
+  - "ai/context/business-advanced.md"
+```
+
+---
+
+## Complete Example
+
+```yaml
+---
+documentType: story
+title: "APM-R: FE: Dashboard: Add Configurable Cards"
+description: "Allow users to select which cards appear on their dashboard and save preferences"
+component: "APM: Reliability App"
+milestone: Feb2026
+priority: P1
+storyPoints: 5
+labels: [apm-r, frontend, feature, ux-improvement]
+createdDate: 2025-12-08
+exportedDate: 2025-12-09
+
+# Jira Integration Fields
+jira-ticketId: DAPM-1283
+jira-url: "https://{your-org}.atlassian.net/browse/PROJ-1283"
+jira-parent: DAPM-1171
+jira-related: [DAPM-1200, DAPM-1210]
+jira-blocking: []
+jira-blockedBy: [DAPM-1100]
+jira-fixVersion: "2025-02"
+jira-internalNotes: "Coordinate with UX team on card catalog design"
+
+# Framework Integration Fields
+framework-documentation: "@apm-r-app/src/components/Dashboard/README.md"
+framework-milestone: "backlog/milestones/Feb2026.md"
+framework-technicalGuides:
+  - "@apm-r-be/docs/api-design.md"
+  - "ai/context/technical-advanced.md"
+framework-relatedLocal:
+  - "backlog/epics/1171-configurable-dashboard.md"
+---
+```
+
+---
+
+## Validation Rules
+
+### Required Fields Checklist
+- ✅ `documentType` present and valid (story|task|bug|spike|epic)
+- ✅ `title` present (30-80 characters)
+- ✅ `description` present (1-line summary)
+- ✅ `createdDate` present (ISO 8601)
+
+### Required Fields Checklist (for all tickets)
+- ✅ `component` present and equals "APM: Reliability App" exactly
+- ✅ Only one component (not multiple)
+- ✅ Exact format: 2 spaces between "APM:" and "Reliability"
+
+### Jira Fields Checklist (for exported tickets)
+- ✅ `jira-ticketId` populated (DAPM-XXXX format)
+- ✅ `jira-url` populated (full URL)
+- ✅ `exportedDate` populated (ISO 8601)
+- ✅ `jira-blocking`, `jira-blockedBy`, `jira-related` are arrays
+- ✅ `jira-parent` matches DAPM-XXXX format if present
+
+### Framework Fields Checklist
+- ✅ Cross-repo refs use `@repo-name/path` format
+- ✅ Local refs are repo-root-relative paths
+- ✅ All arrays are valid YAML arrays `[]`
+- ✅ All strings properly quoted if containing special characters

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

@@ -0,0 +1,83 @@
+---
+documentType: bug
+title: "{{summary}}"
+description: "One-sentence summary of the bug"
+milestone: null
+priority: P0
+storyPoints: null
+labels: [bug]
+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: []
+---
+
+# Bug: {{summary}}
+
+---
+
+## Description
+
+**Context:**
+
+[Brief description of the bug and its impact on users or the system.]
+
+**Steps to Reproduce:**
+
+1. [Step 1 - specific action]
+2. [Step 2 - specific action]
+3. [Step 3 - specific action]
+4. [Observe the error/issue]
+
+**Expected Behavior:**
+
+[What should happen when following the steps above]
+
+**Actual Behavior:**
+
+[What actually happens - describe the bug]
+
+**Environment:**
+
+* OS: [e.g., macOS 14.2, Windows 11]
+* Browser/Version: [e.g., Chrome 120, Firefox 121]
+* Application Version: [if applicable]
+* Other relevant information: [database version, API version, etc.]
+
+**Impact:**
+
+* Severity: [Critical/High/Medium/Low]
+* Affected Users: [All users/Specific user group/Individual user]
+* Workaround: [If any workaround exists, describe it]
+
+**Technical Notes:**
+
+* [Initial diagnosis or suspected cause]
+* [Relevant error messages or logs]
+* [Suggested fix approach if known]
+
+---
+
+## Acceptance Criteria
+
+* **Verify** bug is reproducible in test environment
+* **Verify** root cause is identified and documented
+* **Verify** fix resolves the issue without introducing regressions
+* **Verify** fix is tested in all affected environments
+* **Verify** relevant tests are added to prevent regression
+* **Verify** documentation is updated if needed
+* **Verify** related tickets are updated (if bug affects other work)

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

@@ -0,0 +1,96 @@
+---
+documentType: epic
+title: "{{summary}}"
+description: "One-sentence summary of the epic"
+milestone: null
+priority: P1
+storyPoints: null
+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: []
+---
+
+# Epic: {{summary}}
+
+---
+
+## Description
+
+**Business Value:**
+
+[2-3 paragraphs explaining the high-level business value and strategic importance of this epic. Focus on WHY this epic matters to the business and users.]
+
+**Goals:**
+
+* [Goal 1 - strategic objective]
+* [Goal 2 - strategic objective]
+* [Goal 3 - strategic objective]
+
+**Success Metrics:**
+
+* [Metric 1 - measurable outcome]
+* [Metric 2 - measurable outcome]
+* [Metric 3 - measurable outcome]
+
+**Scope:**
+
+[Define what is IN SCOPE and what is OUT OF SCOPE for this epic]
+
+**In Scope:**
+* [Item 1]
+* [Item 2]
+
+**Out of Scope:**
+* [Item 1]
+* [Item 2]
+
+**Dependencies:**
+
+* [Dependency 1 - what needs to happen first]
+* [Dependency 2 - external dependencies]
+
+**Technical Considerations:**
+
+* [High-level architectural considerations]
+* [Major technical decisions or constraints]
+* [Integration points or system impacts]
+
+---
+
+## Acceptance Criteria
+
+* **Verify** all child stories are completed
+* **Verify** success metrics are met
+* **Verify** integration testing is complete
+* **Verify** documentation is comprehensive
+* **Verify** stakeholder sign-off is obtained
+* **Verify** no critical bugs remain
+* **Verify** performance requirements are met
+* **Verify** security review is complete (if applicable)
+
+---
+
+## Stories in this Epic
+
+<!-- List of stories that belong to this epic -->
+<!-- Update as stories are created -->
+
+* [ ] Story 1: [Brief description]
+* [ ] Story 2: [Brief description]
+* [ ] Story 3: [Brief description]

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

@@ -0,0 +1,68 @@
+---
+documentType: story
+title: "{{summary}}"
+description: "One-sentence summary of the story"
+milestone: null
+priority: P1
+storyPoints: 5
+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 [user role],
+**I WANT** [capability/feature],
+**SO THAT** [business value/benefit].
+
+**Context:**
+
+[2-3 plain language paragraphs explaining WHY this story is needed, not WHAT will be implemented. Focus on user needs, business context, and problem being solved.]
+
+**Requirements:**
+
+* [Requirement 1 - concise statement]
+* [Requirement 2 - concise statement]
+* [Requirement 3 - concise statement]
+
+**Technical Notes:**
+
+* [High-level guidance only - NO CODE SNIPPETS]
+* Pattern reference: [e.g., "Use MUI Dialog pattern"]
+* Security considerations: [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** [specific testable condition 6]
+* **Verify** [specific testable condition 7]
+* **Verify** [specific testable condition 8]
+* **Verify** documentation is added and linked
+* **Verify** tests are passing