@groupby/ai-dev 0.1.0 → 0.2.0

package/toolsets/toolsets/rzlv-flow/skills/jira-comment/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: jira-comment
+description: Add a comment to a Jira ticket with FCMP sync safety. Fetches current ticket state first, shows any new comments since last sync, confirms the comment to add, then pushes via MCP. Use when you want to add a comment to a Jira ticket.
+---
+
+Add a comment to a Jira ticket with sync safety. Follows the FCMP protocol — fetches the current ticket state and recent comments before writing, so you have full context and avoid surprises.
+
+## Requirements
+
+Requires: Atlassian MCP (`atlassian-rovo`). See the rzlv-flow toolset README for setup.
+
+## Resources to Load
+
+Before executing, read this resource file:
+
+- `docs/ai/resources/fcmp-protocol.md` — follow the FCMP protocol for the comment operation
+
+## Process
+
+### Step 1: Get Ticket Key and Comment
+
+- Use the `focused_ticket` from conversation context if available.
+- Otherwise, ask the user for the ticket key.
+- Get the comment text from the user. If not provided, ask: "What would you like to comment?"
+
+### Step 2: FETCH — Get Current State
+
+Fetch the current ticket state via `mcp_atlassian-rovo_fetch()`:
+
+- Current status, assignee, summary (brief context)
+- All comments — especially any added since the last sync
+
+### Step 3: Show New Comments
+
+Compare the fetched comments against the last known state (from the local `{TICKET-KEY}.md` file's `sync.last_synced` timestamp, if available).
+
+If there are new comments from others since the last sync, display them:
+
+```
+### New Comments Since Last Sync
+- **{author}** ({time ago}): "{comment excerpt}"
+- **{author}** ({time ago}): "{comment excerpt}"
+```
+
+This ensures the user has full context before adding their own comment.
+
+### Step 4: Confirm Comment
+
+Present the comment to be added and ask for confirmation:
+
+```
+### Comment to Add on {TICKET-KEY}
+{comment text}
+
+Add this comment? (y/n/edit)
+```
+
+- **y** — proceed to push
+- **n** — cancel
+- **edit** — let the user revise the comment text
+
+### Step 5: PUSH — Add Comment
+
+Push the comment via MCP.
+
+- On success: confirm with the timestamp.
+- On failure: report the error and preserve the comment text so the user can retry.
+
+### Step 6: Update Local State
+
+If a local `{TICKET-KEY}.md` file exists, update `sync.last_synced` to the current timestamp.
+
+## Output Format
+
+```
+## 💬 Comment: {TICKET-KEY}
+
+{IF NEW COMMENTS FOUND:}
+### New Comments Since Last Sync
+- **{author}** ({time ago}): "{comment excerpt}"
+
+### Your Comment
+{comment text}
+
+Add this comment? (y/n/edit)
+
+{AFTER PUSH:}
+✓ Comment added to {TICKET-KEY} at {timestamp}
+```

package/toolsets/toolsets/rzlv-flow/skills/jira-daily-triage/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: jira-daily-triage
+description: Start your day with intelligent Jira ticket triage. Confirms your project and sprint, fetches prioritized tickets grouped by status, identifies blockers, and recommends what to focus on. Use when starting your workday, switching projects, or needing a prioritized view of your sprint.
+---
+
+Daily ticket triage and sprint planning. Connects to Jira via MCP, detects the active sprint, fetches and prioritizes your tickets, and presents an actionable overview with numbered ticket selection.
+
+## Requirements
+
+Requires: Atlassian MCP (`atlassian-rovo`). See the rzlv-flow toolset README for setup.
+
+## Resources to Load
+
+Before executing, read these resource files for protocol and structure guidance:
+
+- `docs/ai/resources/fcmp-protocol.md` — follow read protocols for all Jira operations
+- `docs/ai/resources/jira-file-structure.md` — understand the local file structure
+
+## Process
+
+### Step 1: Confirm Project
+
+- Check the conversation for a previously confirmed Jira project key.
+- If a project is known from prior context, offer to continue with it or switch:
+  ```
+  Select project for this session:
+  1. Continue with {PROJECT} (default)
+  2. Use a different project
+
+  Choose [1]:
+  ```
+- If the user enters "1" or presses Enter, use the default.
+- If the user enters "2", ask: "Enter project key:"
+- If the user provides a project key directly (e.g. "PROJ"), use it.
+- Store the confirmed project for all subsequent commands in this session.
+
+### Step 2: Detect Active Sprint
+
+- Use MCP to search for the active sprint in the confirmed project:
+  ```
+  JQL: project = {PROJECT} AND sprint in openSprints()
+  ```
+- Extract the sprint name, ID, end date, and days remaining from the results.
+- If no open sprint is found, display: "No active sprint detected — Backlog mode" and continue without a sprint filter. In Backlog mode, skip sprint-scoped queries and show only the user's assigned tickets ordered by priority.
+- Store the active sprint name, ID, end date, and days remaining for the session.
+
+> **Note:** Sprint data may be stored in custom fields whose names vary by Jira instance. When using MCP to query sprint tickets, inspect the returned fields for sprint information (name, start/end dates, goal). If sprint details are missing from the default field set, request additional fields or use `'*all'` to retrieve all fields.
+
+### Step 3: Fetch Tickets in Priority Order
+
+Run three JQL queries via `mcp_atlassian-rovo_search()`:
+
+**a) Sprint tickets assigned to me** (highest priority):
+```
+project = {PROJECT} AND sprint in openSprints() AND assignee = currentUser()
+ORDER BY status ASC, priority DESC
+```
+Group results by status: "In Progress" first, then "To Do" / "Open".
+
+**b) Unassigned sprint tickets:**
+```
+project = {PROJECT} AND sprint in openSprints() AND assignee is EMPTY
+ORDER BY priority DESC
+```
+
+**c) High-priority backlog — my assignments (top 3):**
+```
+project = {PROJECT} AND assignee = currentUser() AND sprint is EMPTY
+ORDER BY priority DESC
+```
+Limit to 3 tickets. Exclude any tickets already in sprint results.
+
+### Step 4: Triage and Present
+
+- Calculate sprint progress metrics (tickets done / total tickets).
+- Flag blockers or stale tickets (no updates for 3+ days).
+- Identify quick wins (low-point tickets in "To Do") vs deep work (high-point "In Progress").
+- Recommend a focus ticket based on status and priority:
+  - Prefer continuing "In Progress" tickets over starting new ones.
+  - Among "To Do" tickets, prefer higher priority and lower story points.
+
+### Step 5: Assign Numbered List
+
+- Assign a sequential number to every ticket across all sections (1, 2, 3, ...).
+- The numbered mapping persists in conversational context so that subsequent commands (e.g. `jira-ticket-focus`) can accept a number instead of a full ticket key.
+
+## Output Format
+
+Present results using this structure:
+
+```
+## 🌅 Your Day — {date}
+**Project:** {PROJECT} | **Sprint:** {Sprint Name} | **Ends:** {end_date} ({days_left} days left)
+**Sprint Progress:** {X}/{Y} tickets complete
+
+{IF NO SPRINT:}
+## 🌅 Your Day — {date}
+**Project:** {PROJECT} | **No active sprint detected — Backlog mode**
+
+### 🔥 In Progress (Complete These First)
+| # | Ticket | Summary | Points | Days Active |
+|---|--------|---------|--------|-------------|
+| 1 | PROJ-123 | Backend API endpoint | 3 | 2d |
+
+### 📋 Sprint — Ready to Start
+| # | Ticket | Summary | Points | Priority |
+|---|--------|---------|--------|----------|
+| 2 | PROJ-124 | User validation | 2 | High |
+| 3 | PROJ-125 | Error handling | 1 | Medium |
+
+### 🆘 Sprint — Needs Assignment
+| # | Ticket | Summary | Points | Priority |
+|---|--------|---------|--------|----------|
+| 4 | PROJ-126 | Integration test | 3 | High |
+
+### 📌 High Priority Backlog (Top 3)
+| # | Ticket | Summary | Points | Priority |
+|---|--------|---------|--------|----------|
+| 5 | PROJ-130 | Performance fix | 5 | Critical |
+
+### ⚠️ Blockers & Flags
+- {TICKET-KEY}: {blocker description} ({n} days)
+- {TICKET-KEY}: {blocker description} ({n} days)
+{IF NO BLOCKERS:}
+✓ No blockers detected
+
+**Recommended Focus:** #1 PROJ-123 (continue in-progress work) or #2 PROJ-124 (fresh start)
+
+Type a number (1-5) to focus on that ticket, or say "adjust" to reprioritize.
+```
+
+Omit any section that has no tickets (e.g. skip "Needs Assignment" if all sprint tickets are assigned).
+
+## Session Context
+
+After running, remember the following in conversational context for subsequent commands:
+
+- **confirmed_project** — The Jira project key
+- **active_sprint_name** — The detected sprint name
+- **active_sprint_id** — The sprint ID
+- **numbered_ticket_list** — Mapping of display numbers to Jira ticket keys
+
+These values should be reused by other skills (e.g. `jira-ticket-focus`) without re-prompting the user.

package/toolsets/toolsets/rzlv-flow/skills/jira-sprint-status/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: jira-sprint-status
+description: Generate a sprint status report with completion metrics. Fetches all sprint tickets, groups by status, calculates progress percentages, identifies risks and blockers, and summarizes your personal contribution. Use when you need a sprint overview or standup preparation.
+---
+
+Sprint status report with completion metrics. Fetches all tickets in the active sprint, groups them by status, calculates progress (ticket count and story points), flags risks and blockers, and highlights your personal contribution — useful for standups or mid-sprint check-ins.
+
+## Requirements
+
+Requires: Atlassian MCP (`atlassian-rovo`). See the rzlv-flow toolset README for setup.
+
+## Resources to Load
+
+Before executing, read this resource file:
+
+- `docs/ai/resources/fcmp-protocol.md` — follow read protocols for Jira fetch operations
+
+## Process
+
+### Step 1: Confirm Project
+
+- Use `confirmed_project` from conversation context (set by `jira-daily-triage`) if available.
+- Otherwise, ask the user for their Jira project key.
+
+### Step 2: Detect Active Sprint
+
+Use MCP to find the active sprint:
+
+```
+JQL: project = {PROJECT} AND sprint in openSprints()
+```
+
+Extract the sprint name, ID, start date, end date, and sprint goal (if set). If no open sprint is found, inform the user and offer to report on a specific sprint or the full backlog.
+
+> **Note:** Sprint data may be stored in custom fields whose names vary by Jira instance. When using MCP to query sprint tickets, inspect the returned fields for sprint information (name, start/end dates, goal). If sprint details are missing from the default field set, request additional fields or use `'*all'` to retrieve all fields.
+
+### Step 3: Fetch All Sprint Tickets
+
+Fetch all tickets in the sprint via `mcp_atlassian-rovo_search()`:
+
+```
+JQL: project = {PROJECT} AND sprint in openSprints() ORDER BY status ASC, priority DESC
+```
+
+For each ticket, collect: key, summary, status, assignee, story points, priority, last updated date.
+
+### Step 4: Group and Calculate Metrics
+
+Group tickets by status category:
+
+- **Done** — tickets in terminal/completed statuses
+- **In Progress** — tickets actively being worked on
+- **To Do** — tickets not yet started
+- **Blocked** — tickets flagged or with blocker labels (if detectable)
+
+Calculate:
+- Ticket count per group
+- Story points per group (sum)
+- Overall completion percentage (done points / total points, or done count / total count)
+- Sprint velocity so far (points completed)
+
+### Step 4b: Calculate Velocity and Forecast
+
+Using the sprint start date, end date, and points completed so far:
+
+- **Days elapsed** — business days since sprint start
+- **Days remaining** — business days until sprint end
+- **Ideal velocity** — total points / total sprint days (points/day to finish on time)
+- **Actual velocity** — done points / days elapsed
+- **Forecast** — at current velocity, project whether the sprint will finish on time, ahead, or behind. If behind, estimate the shortfall: "May miss by {n} points"
+
+### Step 5: Identify Risks
+
+Flag potential risks:
+
+- **Stale tickets:** "In Progress" tickets with no updates for 3+ days.
+- **Unassigned work:** Sprint tickets with no assignee.
+- **High-point items in To Do:** Large stories that haven't started yet (risk of not completing in sprint).
+- **Scope indicators:** Compare total points against typical sprint velocity if known.
+
+### Step 6: Summarize Personal Contribution
+
+Filter tickets assigned to the current user:
+
+- Tickets completed this sprint
+- Tickets currently in progress
+- Points completed vs total assigned
+
+## Output Format
+
+```
+## 📊 Sprint Status: {Sprint Name}
+**Project:** {PROJECT} | **Sprint:** {Sprint Name}
+**Ends:** {end_date} ({days_left} days left)
+{IF SPRINT GOAL SET:}
+**Goal:** {Sprint Goal}
+
+████████████░░░░░░░░ {percent}% Complete
+
+### Progress
+| Status | Tickets | Story Points |
+|--------|---------|-------------|
+| Done | {n} | {pts} |
+| In Progress | {n} | {pts} |
+| To Do | {n} | {pts} |
+| **Total** | **{n}** | **{pts}** |
+
+**Completion:** {percent}% by points ({done_pts}/{total_pts})
+
+### Velocity & Forecast
+- **Ideal:** {n} points/day
+- **Actual:** {n} points/day
+- **Forecast:** {On track | Ahead by {n} points | May miss by {n} points}
+
+### Ticket Breakdown
+| # | Ticket | Summary | Status | Assignee | Points |
+|---|--------|---------|--------|----------|--------|
+| 1 | PROJ-101 | Feature A | Done | @user1 | 3 |
+| 2 | PROJ-102 | Feature B | In Progress | @user2 | 5 |
+| 3 | PROJ-103 | Feature C | To Do | Unassigned | 2 |
+
+### ⚠️ Risks
+{IF STALE TICKETS:}
+- **Stale:** {TICKET-KEY} — In Progress, no update for {n} days
+{IF UNASSIGNED:}
+- **Unassigned:** {TICKET-KEY} — {summary} ({points} pts)
+{IF LARGE ITEMS NOT STARTED:}
+- **At Risk:** {TICKET-KEY} — {points} pts, not started yet
+{IF NO RISKS:}
+✓ No risks detected
+
+### My Contribution
+- **Completed:** {n} tickets ({pts} pts)
+- **In Progress:** {n} tickets ({pts} pts)
+- **Assigned (To Do):** {n} tickets ({pts} pts)
+
+---
+**Quick Actions:**
+1. View at-risk tickets in detail
+2. Focus on blocked items
+3. Generate standup update (summary for copy/paste)
+4. Export sprint data as markdown table
+```

package/toolsets/toolsets/rzlv-flow/skills/jira-status/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: jira-status
+description: Change a Jira ticket's status with transition validation and FCMP sync safety. Fetches current state, verifies status hasn't changed remotely, shows available transitions as a numbered list, and executes the selected transition. Use when you want to move a Jira ticket to a different status.
+---
+
+Transition a Jira ticket's status with sync safety. Follows the FCMP protocol — fetches the current state, verifies no remote status change since last sync, presents valid transitions as a numbered list, and executes the selected transition via MCP.
+
+## Requirements
+
+Requires: Atlassian MCP (`atlassian-rovo`). See the rzlv-flow toolset README for setup.
+
+## Resources to Load
+
+Before executing, read this resource file:
+
+- `docs/ai/resources/fcmp-protocol.md` — follow the FCMP protocol for status transitions
+
+## Process
+
+### Step 1: Get Ticket Key
+
+- Use the `focused_ticket` from conversation context if available.
+- Otherwise, ask the user for the ticket key.
+
+### Step 2: FETCH — Get Current State
+
+Fetch the current ticket state via `mcp_atlassian-rovo_fetch()`:
+
+- Current status
+- Assignee and summary (for confirmation context)
+- Version field (for optimistic locking)
+
+### Step 3: COMPARE — Verify No Remote Change
+
+Compare the fetched status against the last known local state (from the `{TICKET-KEY}.md` frontmatter if available).
+
+- If the remote status has changed since last sync, warn the user:
+  ```
+  ⚠️ Status changed remotely: {old_status} → {current_remote_status}
+  Continue with transition from {current_remote_status}? (y/n)
+  ```
+
+### Step 4: Get Available Transitions
+
+Fetch available transitions for the ticket via MCP (e.g. `getTransitionsForJiraIssue` or equivalent).
+
+Present as a numbered list:
+
+```
+Current Status: {current_status}
+
+Available transitions:
+1. {transition_name_1}
+2. {transition_name_2}
+3. {transition_name_3}
+4. Cancel
+
+Choose transition [1]:
+```
+
+Do not assume a standard workflow (To Do → In Progress → Done). Always fetch the actual available transitions, as Jira workflows vary by project.
+
+### Step 5: Execute Transition
+
+After the user selects a transition number:
+
+1. Confirm: "Transition {TICKET-KEY} from {current_status} to {target_status}? (y/n)"
+2. **PUSH** — Execute the transition via MCP.
+3. On success: confirm with the new status.
+4. On failure: report the error (e.g. required fields missing, permission denied, transition not available).
+
+### Step 6: Update Local State
+
+If a local `{TICKET-KEY}.md` file exists:
+
+- Update `sync.status` to the new status
+- Update `sync.last_synced` to the current timestamp
+- Update `sync.version` with the new version from Jira
+
+## Output Format
+
+```
+## 🔄 Status: {TICKET-KEY}
+
+**Current Status:** {current_status}
+
+Available transitions:
+1. {transition_1}
+2. {transition_2}
+3. {transition_3}
+4. Cancel
+
+Choose transition [1]:
+
+{AFTER TRANSITION:}
+✓ {TICKET-KEY} transitioned: {old_status} → {new_status}
+```

package/toolsets/toolsets/rzlv-flow/skills/jira-sync/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: jira-sync
+description: Force-sync local Jira context to bring it up to date with the remote state. Runs the full FCMP protocol (Fetch-Compare-Merge-Push) for a specified ticket, showing diffs if remote changes are detected and resolving conflicts with user input. Use when you want to refresh your local Jira mirror or suspect your local state is stale.
+---
+
+Force-sync a local Jira ticket file with the remote state. Runs the complete FCMP protocol — fetches the current remote state, compares against the local file, shows diffs if anything changed, and resolves conflicts with user input. Use this when your local state might be stale or after someone else updates the ticket in Jira.
+
+## Requirements
+
+Requires: Atlassian MCP (`atlassian-rovo`). See the rzlv-flow toolset README for setup.
+
+## Resources to Load
+
+Before executing, read these resource files:
+
+- `docs/ai/resources/fcmp-protocol.md` — **critical** — the full FCMP protocol to follow
+- `docs/ai/resources/jira-file-structure.md` — to locate the local ticket file
+- `docs/ai/resources/sync-state-format.md` — YAML frontmatter schema for reading and updating the ticket file
+
+## Process
+
+### Step 1: Get Ticket Key
+
+- Use `focused_ticket` from conversation context if available.
+- Otherwise, ask the user for the ticket key.
+
+### Step 2: Locate Local File
+
+Find the local `{TICKET-KEY}.md` file using the rules in `jira-file-structure.md`:
+
+1. Search under `docs/jira/{instance}/{project}/` for a file matching `{TICKET-KEY}.md`.
+2. It may be in an epic folder (`{epic-name}/stories/{TICKET-KEY}/{TICKET-KEY}.md`) or in `_orphans/`.
+3. If no local file exists, inform the user and offer to create one by fetching from Jira (effectively a first-time sync).
+
+### Step 3: FETCH — Get Remote State
+
+Fetch the full ticket state from Jira via `mcp_atlassian-rovo_fetch()`:
+
+- Summary, description, acceptance criteria
+- Status, assignee, priority, story points
+- Version number (for optimistic locking)
+- Last updated timestamp
+- Recent comments
+
+### Step 4: COMPARE — Diff Local vs Remote
+
+Compare the fetched remote state against the local file:
+
+- **Frontmatter fields:** `sync.status`, `sync.assignee`, `sync.priority`, `sync.story_points`, `sync.version`
+- **Body content:** description, acceptance criteria, technical notes
+- **Timestamps:** `sync.remote_updated` vs the remote `updated_at`
+
+Determine the scenario:
+
+| Scenario | Condition | Action |
+|----------|-----------|--------|
+| Already up to date | `sync.version` matches remote version | Report "Already up to date" |
+| Remote changed only | Remote version is newer, no local modifications | Apply remote changes |
+| Local changed only | Local has edits, remote is same as last sync | No action needed (local changes preserved) |
+| Both changed | Local edits AND remote version is newer | Conflict — proceed to merge |
+
+### Step 5: Show Diff
+
+If changes are detected, present them clearly:
+
+```
+### Changes Detected
+
+{FOR EACH CHANGED FIELD:}
+**{field_name}:**
+- Local: {local_value}
+- Remote: {remote_value}
+
+{FOR BODY CHANGES:}
+**Description:**
+- Lines added remotely: {n}
+- Lines removed remotely: {n}
+{Show abbreviated diff}
+```
+
+### Step 6: MERGE — Resolve Conflicts
+
+If both local and remote have changes:
+
+1. Present the conflict to the user.
+2. Offer resolution strategies:
+   ```
+   Conflict detected. How would you like to resolve?
+   1. Keep remote (discard local changes)
+   2. Keep local (your changes will overwrite on next push)
+   3. Manual merge (I'll show both versions side by side)
+   ```
+3. For **auto-merge** (changes in different sections), combine both changes automatically and confirm with the user.
+4. For **manual merge**, present both versions and let the user edit.
+
+If only the remote changed (no local edits), apply the remote changes directly.
+
+### Step 7: Update Local File
+
+After merge resolution:
+
+1. Write the merged content to the local `{TICKET-KEY}.md` file.
+2. Update frontmatter fields:
+   - `sync.status` — current remote status
+   - `sync.assignee` — current assignee
+   - `sync.priority` — current priority
+   - `sync.story_points` — current story points
+   - `sync.last_synced` — current timestamp
+   - `sync.version` — remote version number
+   - `sync.remote_updated` — remote last updated timestamp
+3. Preserve any `agile_companion` or `orchestrator` metadata that exists.
+
+### Step 8: Report Results
+
+Confirm what changed.
+
+## Output Format
+
+```
+## 🔄 Sync: {TICKET-KEY}
+
+{IF ALREADY UP TO DATE:}
+✓ {TICKET-KEY} is already up to date (version {version})
+
+{IF CHANGES APPLIED:}
+### Changes Applied
+{List of fields updated with old → new values}
+
+- **Status:** {old} → {new}
+- **Assignee:** {old} → {new}
+- **Description:** Updated ({n} lines changed)
+
+✓ Local file synced to version {version} at {timestamp}
+
+{IF CONFLICT RESOLVED:}
+### Conflict Resolved
+- Strategy: {keep_remote | keep_local | auto_merge | manual_merge}
+- Fields affected: {list}
+
+✓ Conflict resolved and local file updated to version {version}
+
+{IF NEW FILE CREATED:}
+### New File Created
+- Path: {relative_path_to_ticket_file}
+- Fetched from Jira: version {version}
+
+✓ Local file created for {TICKET-KEY}
+```