@groupby/ai-dev 0.1.1 → 0.2.1

package/toolsets/toolsets/rzlv-flow/skills/jira-ticket-focus/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: jira-ticket-focus
+description: Deep-load a Jira ticket with full context for focused work. Fetches ticket details, detects the parent epic, creates or navigates the local file structure, loads linked requirements, checks git branch status, and presents quick actions (branch creation, status transition, assignment). Use when you want to focus on a specific Jira ticket.
+---
+
+Deep-load a single Jira ticket for focused development work. Fetches full ticket context via MCP, determines the correct local file location using epic detection and smart structure rules, sets up the developer workspace, checks git branch status, and presents actionable quick actions.
+
+## Requirements
+
+Requires: Atlassian MCP (`atlassian-rovo`). See the rzlv-flow toolset README for setup.
+Optional: Git CLI for branch detection and creation.
+
+## Resources to Load
+
+Before executing, read these resource files — they are critical for correct behavior:
+
+- `docs/ai/resources/fcmp-protocol.md` — follow for all Jira read/write operations
+- `docs/ai/resources/jira-file-structure.md` — **critical** for file placement logic and ownership rules
+- `docs/ai/resources/sync-state-format.md` — YAML frontmatter format for ticket files
+
+## Process
+
+### Step 1: Resolve Ticket Reference
+
+- If the user provides a **number** (e.g. "3"), look it up from the `numbered_ticket_list` stored in conversational context from a prior `jira-daily-triage` run.
+- If the user provides a **Jira key** (e.g. "PROJ-123"), use it directly.
+- If the key is **incomplete** (e.g. "123"), prepend the `confirmed_project` key from session context (e.g. "PROJ-123").
+- If neither a number mapping nor a project key is available, attempt fallback detection:
+  1. **Git branch:** Check the current branch name for a `{PROJECT}-{n}` pattern (e.g. `feature/PROJ-123` → project is `PROJ`).
+  2. **Config file:** Check for a `.jira.json` file in the project root containing `{ "project": "PROJ", "instance": "rezolve" }`.
+  3. If neither yields a project key, ask the user for the full ticket key.
+
+### Step 2: Fetch Ticket Details (FCMP Fetch Step)
+
+Use `mcp_atlassian-rovo_fetch()` to retrieve:
+
+- Summary, description, acceptance criteria
+- Comments and recent history
+- Sprint information (use `active_sprint_name` from session context if available)
+- Linked Confluence documents (if any)
+- **Subtasks** — fetch all subtasks of the ticket via JQL: `parent = {TICKET-KEY} ORDER BY status ASC, priority DESC`
+- **Linked issues** — fetch linked issues (blocks, is blocked by, relates to)
+
+**Parent Epic detection** — check in this order:
+
+1. Check `fields.parent` — if `parent.fields.issuetype.name == "Epic"`, that is the epic.
+2. Check for an Epic Link custom field (varies by instance; commonly `customfield_10014` or similar).
+3. If no epic is found, the ticket is **orphaned**.
+
+Store the epic key and summary for context display and file placement.
+
+### Step 3: Determine Ticket Location (Smart Structure Detection)
+
+Determine where the ticket file lives (or should be created) in the local Jira file structure. Follow the rules from `jira-file-structure.md`:
+
+```
+Base directory: docs/jira/{instance}/{project}/
+```
+
+**If an epic parent was found:**
+
+1. Check if an epic folder already exists locally:
+   ```
+   {base}/*{EPIC-KEY}*/
+   ```
+   (Glob match — the folder may include a slug, e.g. `PROJ-100-user-authentication/`)
+
+2. If the epic folder **exists**, place the ticket at:
+   ```
+   {base}/{epic-folder}/stories/{TICKET-KEY}/{TICKET-KEY}.md
+   ```
+
+3. If the epic folder **does not exist**, create it:
+   ```
+   {base}/{EPIC-KEY}-{epic-summary-slug}/
+   {base}/{EPIC-KEY}-{epic-summary-slug}/stories/
+   ```
+   Then place the ticket at:
+   ```
+   {base}/{EPIC-KEY}-{epic-summary-slug}/stories/{TICKET-KEY}/{TICKET-KEY}.md
+   ```
+   Note in output: "Created new epic folder structure for {EPIC-KEY}"
+
+**If no epic parent (orphan):**
+```
+{base}/_orphans/{TICKET-KEY}/{TICKET-KEY}.md
+```
+
+**If the parent is a Story or Task (i.e. ticket is a subtask):**
+```
+{base}/.../{PARENT-KEY}/subtasks/{TICKET-KEY}/{TICKET-KEY}.md
+```
+
+### Step 4: Load Requirements Context
+
+- **If an epic parent was detected:**
+  - Search for `epic.md` in the epic folder and load it for goals, scope, and technical approach.
+  - Check for a `_docs/` folder with generated documentation (architecture, decisions, strategic context).
+  - Check for linked Confluence documents in the epic or ticket metadata.
+  - If the epic folder was just created and `epic.md` doesn't exist, note that epic context is missing.
+
+- **If no epic or epic folder was not found:**
+  - Search for any related documentation by keyword matching in the project's `_docs/` folders.
+  - Note the gap — the user may want to run `atlassian-orchestrator` to generate context.
+
+### Step 5: Prepare Local Environment
+
+1. **Create or update `{TICKET-KEY}.md`** with sync state frontmatter following the schema in `sync-state-format.md`:
+   - Populate all `sync` fields from the fetched Jira data.
+   - Set `structure.type` based on the issue type.
+   - Set `structure.parent` as a relative path to the parent file (if applicable).
+   - Set `structure.epic` to the epic key (if applicable).
+   - Set `agile_companion.last_focused` to the current timestamp.
+
+2. **Create `_work/` folder** in the ticket directory for developer notes (this folder is gitignored).
+
+3. **Store the fetched Jira state** locally so that future FCMP operations can compare against it.
+
+### Step 6: Check Git Branch Status
+
+Run these git commands to detect branch state:
+
+```bash
+# Current branch
+git branch --show-current
+
+# Local branches matching ticket key
+git branch --list "*{TICKET-KEY}*"
+
+# Remote branches matching ticket key
+git branch -r --list "*{TICKET-KEY}*"
+```
+
+Common branch naming patterns to check:
+- `feature/{TICKET-KEY}`
+- `feature/{TICKET-KEY}-*`
+- `{TICKET-KEY}`
+- `{TICKET-KEY}-*`
+
+Determine which scenario applies:
+
+| Scenario | Condition | Action |
+|----------|-----------|--------|
+| No branch exists | Local and remote checks both empty | Offer to create `feature/{TICKET-KEY}` |
+| Local branch exists, not current | Found in local list, not current branch | Offer to switch |
+| Remote branch exists, not local | Found in remote list, not in local | Offer to checkout |
+| Already on correct branch | Current branch contains ticket key | Show checkmark, no action needed |
+
+### Step 7: Present Work Context
+
+Display the full ticket details, acceptance criteria as a checklist, requirements from loaded context, and technical notes — all in a scannable format.
+
+### Step 8: Offer Quick Actions
+
+Present numbered quick actions based on detected state:
+
+- **Git branch actions** (from Step 6 — only the relevant scenario).
+- **Assignment:** If the ticket is unassigned, offer to assign to the current user.
+- **Status transition:** If the ticket status is "To Do" or "Open", offer to move to "In Progress".
+- Always include a "Skip quick actions" option as the last number.
+
+## Output Format
+
+```
+## 🎯 Focus: {TICKET-KEY} — {Summary}
+
+**Project:** {confirmed_project} | **Epic:** {Epic Key}: {Epic Summary} (or "No Epic (Orphaned)")
+**Assignee:** {assignee or "Unassigned"} | **Status:** {status}
+**Points:** {story_points} | **Priority:** {priority}
+**Sprint:** {active_sprint_name}
+**Current Branch:** {current_git_branch}
+**Local Path:** {relative path to ticket file}
+
+{IF epic folder was just created:}
+✨ Created new epic folder structure for {EPIC-KEY}
+
+### Acceptance Criteria
+- [ ] {criterion 1}
+- [ ] {criterion 2}
+- [ ] {criterion 3}
+
+### Requirements Context
+{Content from epic.md, _docs/, or linked Confluence pages.
+If no context available: "No requirements context found. Consider running atlassian-orchestrator to generate epic documentation."}
+
+### Technical Notes
+{From architecture docs, epic technical notes, or _docs/ folder.
+If none: "No technical notes available."}
+
+### Recent Activity
+- {commenter}: "{comment excerpt}" ({time ago})
+- {commenter}: "{comment excerpt}" ({time ago})
+
+---
+**Quick Actions:**
+
+{Based on git branch detection scenario — show only the relevant one:}
+
+{IF NO BRANCH EXISTS:}
+1. Create and switch to new branch: feature/{TICKET-KEY}
+
+{IF LOCAL BRANCH EXISTS BUT NOT CURRENT:}
+1. Switch to existing branch: {branch_name}
+
+{IF REMOTE BRANCH EXISTS BUT NOT LOCAL:}
+1. Checkout remote branch: {branch_name}
+
+{IF ALREADY ON CORRECT BRANCH:}
+✓ Already on feature branch: {branch_name}
+
+{Additional actions based on ticket state:}
+
+{IF UNASSIGNED:}
+{N}. Assign to me and move to "In Progress"
+
+{IF ASSIGNED BUT STATUS IS "To Do"/"Open":}
+{N}. Move to "In Progress"
+
+{ALWAYS:}
+{last}. Skip quick actions — start working as-is
+
+Choose [1]:
+```
+
+## Quick Action Execution
+
+When the user selects a numbered action:
+
+- **Branch creation:** `git checkout -b feature/{TICKET-KEY}`
+- **Branch switch:** `git checkout {branch_name}`
+- **Remote checkout:** `git checkout -b {branch_name} origin/{branch_name}`
+- **Assign to me:** Update the assignee field via MCP, following FCMP protocol. Fetch current state first, then update.
+- **Status transition:** Fetch available transitions via `mcp_atlassian-rovo_fetch()` (or equivalent MCP call for transitions), then execute the transition. Follow FCMP protocol — fetch current state, confirm transition is valid, then push.
+
+After executing any action, confirm what was done and re-display the relevant updated field.
+
+## Session Context
+
+After running, update conversational context with:
+
+- **focused_ticket** — The Jira ticket key currently being worked on
+- **focused_ticket_path** — The local file path for the ticket
+- **working_branch** — The git branch being used (after any branch action)
+
+The user may say "wrap" after completing work, which invokes the `jira-wrap-sync` skill using this context.

package/toolsets/toolsets/rzlv-flow/skills/jira-ticket-trace/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: jira-ticket-trace
+description: Trace code back to its Jira requirements. Uses git blame to find the commit, extracts the ticket reference, fetches the ticket and its epic context, and presents the full "why" chain (business context, technical decisions, original requirements). Use when you need to understand why code exists or trace a feature to its origin.
+---
+
+Context recovery — trace code back to its Jira requirements. Performs git archaeology to find the originating commit and ticket key, then fetches the full context chain from Jira (ticket, epic, linked docs) to explain *why* the code exists.
+
+## Requirements
+
+Requires: Atlassian MCP (`atlassian-rovo`). See the rzlv-flow toolset README for setup.
+Also uses: Git CLI (`git blame`, `git log`).
+
+## 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: Identify Target
+
+Determine what code the user wants to trace. Accept any of:
+
+- A **selected code block** in the editor
+- A **file and line reference** (e.g. `src/auth.ts:42`)
+- A **feature or function name** (e.g. "the rate limiting logic")
+
+If the user provides a feature description rather than a specific location, search the codebase to find the relevant file(s) and line(s) first.
+
+### Step 2: Git Archaeology
+
+Trace the code to its originating commit:
+
+1. Run `git blame -L {start},{end} {file}` to find the commit(s) that introduced the target code.
+2. For the most relevant commit, extract:
+   - Commit hash, author, date
+   - Full commit message: `git log -1 --format="%B" {hash}`
+3. Look for a Jira ticket key in the commit message (pattern: `[A-Z]+-\d+`).
+4. If no ticket key in the commit message, check:
+   - The PR/MR associated with the commit: `git log -1 --format="%s" {hash}` may reference a PR number
+   - The branch name at the time of merge (often contains ticket keys)
+   - Adjacent commits for context
+5. If still no ticket key found, report to the user and offer to search Jira by keyword.
+
+### Step 3: Trace to Jira
+
+Once a ticket key is found:
+
+1. **Fetch ticket details** via `mcp_atlassian-rovo_fetch()` — summary, description, status, acceptance criteria.
+2. **Get the parent epic** — use the same epic detection logic as `jira-ticket-focus`:
+   - Check `fields.parent` for an epic type
+   - Check for Epic Link custom field
+3. **Get linked initiative** (if the epic has a parent or linked initiative).
+4. **Check for linked Confluence docs** in the ticket or epic metadata.
+
+### Step 4: Load Context Chain
+
+Build the full "why" chain by loading available context:
+
+- **Original requirements** — from the ticket description, acceptance criteria, and any linked Confluence requirement pages.
+- **Decision logs** — from `_docs/decisions.md` in the epic folder if it exists locally.
+- **Assumptions** — from technical notes in the ticket or epic documentation.
+- **Strategic context** — from `_docs/strategic-context.md` if available.
+
+If local `_docs/` folders don't exist, note what's available from Jira/Confluence only.
+
+### Step 5: Present the "Why"
+
+Assemble and present the full trace from code to business context.
+
+## Output Format
+
+```
+## 🔍 Why: {code reference}
+
+### Git Trail
+- **Commit:** {hash} by {author} on {date}
+- **Message:** "{commit message}"
+- **Ticket:** {TICKET-KEY}
+{IF PR FOUND:}
+- **PR:** #{pr_number} — {pr_title}
+
+### Business Context
+{From epic or initiative context — the high-level "why" this feature exists.
+If no epic context: "No epic context available for this ticket."}
+
+### Technical Decision
+{From decision logs or technical notes — why this approach was chosen over alternatives.
+If none available: "No decision log found."}
+
+### Original Requirement
+> "{Quote from the ticket description or acceptance criteria that drove this code}"
+— {TICKET-KEY}: {ticket summary}
+
+{IF CONFLUENCE DOCS LINKED:}
+### Related Documentation
+- {Confluence page title}: {url}
+
+### Key Assumptions
+- {Assumption that drove this implementation choice}
+- {Constraint that shaped the approach}
+
+---
+Need more context? I can load the full epic documentation or search for related tickets.
+```
+
+## Edge Cases
+
+- **No ticket key found in git history:** Report the commit details and offer to search Jira by keywords from the commit message or code context.
+- **Ticket deleted or inaccessible:** Report the ticket key and note that it may have been moved, deleted, or is in a project you don't have access to.
+- **Multiple commits / multiple tickets:** If git blame shows multiple commits for the target code, trace the most significant one (largest change) and note the others.

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

@@ -0,0 +1,260 @@
+---
+name: jira-wrap-sync
+description: Wrap up your current work on a Jira ticket. Analyzes local ticket changes and code changes (git diff), drafts a comprehensive Jira comment, runs FCMP sync, and presents multi-select actions (sync fields, add comment, transition status, create PR, update Confluence). Use when you're done working on a ticket or want to sync progress.
+---
+
+Wrap up work on the currently focused Jira ticket. Detects what changed (ticket fields and code), drafts a Jira comment summarizing progress, runs the FCMP protocol before syncing, and presents a multi-select action menu so you can sync fields, comment, transition status, and create a PR in one pass.
+
+## Requirements
+
+Requires: Atlassian MCP (`atlassian-rovo`). See the rzlv-flow toolset README for setup.
+Optional: GitHub MCP for Pull Request creation (action 4).
+
+## Resources to Load
+
+Before executing, read these resource files:
+
+- `docs/ai/resources/fcmp-protocol.md` — **critical** for the sync protocol before any Jira writes
+- `docs/ai/resources/sync-state-format.md` — YAML frontmatter schema for reading/updating ticket files
+
+## Process
+
+### Step 1: Identify the Ticket
+
+- Use `focused_ticket` from conversation context (set by `jira-ticket-focus`).
+- If not available, ask the user for the ticket key.
+- Locate the local ticket file at the path stored in `focused_ticket_path`, or find it using the `jira-file-structure.md` rules.
+
+### Step 2: Analyze All Changes
+
+**a) Local ticket file changes:**
+- Read the current `{TICKET-KEY}.md` file.
+- Compare the content against the last synced state stored in the `sync` frontmatter fields.
+- Detect changes to: description, story points, acceptance criteria, labels, priority.
+- Note which fields were modified locally.
+
+**b) Code changes:**
+- Run `git diff --stat` for an overview of changes.
+- Run `git diff` (or `git diff --staged` if changes are staged) for details.
+- Check recent commits on the working branch: `git log --oneline -10`.
+- Map code changes to acceptance criteria where possible.
+- Summarize: files changed, insertions, deletions.
+
+**c) Acceptance criteria progress:**
+- Read the AC list from the ticket file.
+- Based on code changes and commit messages, infer which AC items have been completed.
+- Show checkbox progress:
+  ```
+  - [x] AC 1 — Completed (matches changes in auth-controller.ts)
+  - [x] AC 2 — Completed (matches changes in rate-limiter.ts)
+  - [ ] AC 3 — Not yet addressed
+  ```
+- Note: this is a best-effort inference. The user confirms the final state.
+
+### Step 3: Draft Jira Comment
+
+Build a comprehensive comment with the standardized prefix `[rzlv-flow Update]`:
+
+```
+[rzlv-flow Update]
+
+{IF TICKET FIELD CHANGES:}
+**Ticket Updates:**
+- {field change 1}
+- {field change 2}
+
+{IF CODE CHANGES:}
+**Implementation Progress:**
+- {code change summary line 1}
+- {code change summary line 2}
+
+**Files Modified:**
+- {file1}: {brief description}
+- {file2}: {brief description}
+
+**Acceptance Criteria:**
+- [x] {completed AC 1}
+- [x] {completed AC 2}
+- [ ] {remaining AC 3}
+**Progress:** {X}/{Y} completed
+
+**Next Steps:** {suggested next action}
+
+Context: {optional PR link or Confluence doc link}
+```
+
+### Step 4: FCMP Preview (Prepare PUSH — Dry Run)
+
+Before executing any write operations, run the full FCMP cycle and present a dry-run preview:
+
+1. **FETCH** — Get the current ticket state from Jira via MCP.
+2. **COMPARE** — Check for remote changes since last sync (compare `sync.version` and `sync.remote_updated`).
+3. **MERGE** — If conflicts detected, show a diff of remote changes vs local changes and resolve with the user.
+4. **Preview** — Show a dry-run diff of what will change if the user proceeds:
+
+```
+### FCMP Preview (Dry Run)
+{IF NO REMOTE CHANGES:}
+✓ Remote is unchanged since last sync — safe to push.
+
+{IF REMOTE CHANGES DETECTED:}
+⚠️ Remote changes detected since last sync:
+- {field}: {old_value} → {new_value}
+
+**Proposed local → remote changes:**
+- Description: {diff summary}
+- Story Points: {old} → {new}
+- Status: {current} (no change)
+
+Proceed with sync? (y/n)
+```
+
+Only proceed to the action menu after the FCMP preview is confirmed.
+
+### Step 5: Present Multi-Select Action Menu
+
+Present all detected changes, the draft comment, and a multi-select numbered menu. The user picks multiple actions via comma-separated numbers.
+
+```
+### Available Actions (Multi-Select)
+
+{IF TICKET FIELD CHANGES DETECTED:}
+1. Sync ticket fields to Jira (description, points, AC)
+
+{IF CODE CHANGES OR TICKET CHANGES:}
+2. Add comment to Jira (with the draft summary above)
+
+3. Transition status (you'll specify the target status)
+
+{IF CODE CHANGES AND COMMITS EXIST:}
+4. Create Pull Request (via GitHub MCP)
+
+{IF SIGNIFICANT CHANGES:}
+5. Update Confluence technical docs
+
+6. Cancel (do nothing)
+
+**Choose actions (comma-separated):** [1,2,3,4]
+
+Examples:
+- "1,2,3,4" = Sync ticket + comment + transition + create PR
+- "2,3" = Comment + transition only
+- "6" = Cancel all actions
+```
+
+### Step 6: Execute Selected Actions
+
+Parse the comma-separated input. Execute each selected action in order:
+
+**Action 1 — Sync ticket fields:**
+- Update description, story points, AC, and any other changed fields via MCP.
+- Include the `version` field for optimistic locking per FCMP.
+- On 409 conflict, re-run FCMP from Fetch.
+
+**Action 2 — Add comment:**
+- Push the draft comment via MCP.
+- For detailed comment procedures, see the `jira-comment` skill.
+
+**Action 3 — Transition status:**
+- Fetch available transitions via MCP.
+- Present as a numbered list for the user to select target status.
+- Execute the transition via MCP.
+- For detailed transition procedures, see the `jira-status` skill.
+
+**Action 4 — Create Pull Request (via GitHub MCP):**
+1. Check for unpushed commits: `git log origin/{branch}..HEAD`
+2. If unpushed commits exist, ask: "Push commits first? (y/n)"
+3. If yes: `git push origin {branch}`
+4. Detect base branch (check git config or default to `main`).
+5. Build PR details:
+   - **Title:** `{TICKET-KEY}: {ticket summary}`
+   - **Body:**
+     ```
+     ## {TICKET-KEY}: {Ticket Summary}
+
+     **Jira:** https://{instance}/browse/{TICKET-KEY}
+     {IF CONFLUENCE DOCS:}
+     **Confluence:** {confluence_link}
+
+     ### Changes
+     {ticket updates + code changes from the draft comment}
+
+     ### Acceptance Criteria
+     - [x] {completed criterion}
+     - [ ] {remaining criterion}
+
+     ### Testing Notes
+     {Any notes from _work/ folder if they exist}
+     ```
+6. Create PR via GitHub MCP: `create_pull_request()`
+7. Return and display the PR URL.
+
+**Action 5 — Update Confluence:**
+- Prompt the user for what to update and where.
+- Follow FCMP protocol for the Confluence update.
+
+**Action 6 — Cancel:**
+- Exit without performing any actions. Ignore all other selections if "6" is included.
+
+### Step 7: Post-Execution
+
+After all selected MCP operations:
+
+1. **FETCH** the final ticket state from Jira.
+2. Update the local `{TICKET-KEY}.md` with the new sync state (version, last_synced, status).
+3. Confirm what was completed:
+   - List each action and its result.
+   - If a PR was created, display the PR URL.
+   - Suggest a next action if remaining work exists.
+
+### Error Handling
+
+- If any MCP operation fails, report which step failed and continue with remaining operations.
+- If the GitHub MCP is not configured, skip PR creation with a warning: "GitHub MCP not configured. Skipping PR creation."
+- On optimistic locking conflicts (409), re-run FCMP from Fetch and retry.
+
+## Output Format
+
+```
+## 🎬 Wrap Up: {TICKET-KEY}
+
+### Local Ticket Changes Detected
+{IF FIELD CHANGES:}
+- **Description:** {change summary or "No changes"}
+- **Story Points:** {old} → {new} (or "No change")
+- **Acceptance Criteria:** {added/removed items} (or "No changes")
+
+{IF NO CHANGES:}
+_(No local ticket changes detected)_
+
+### Code Changes Detected
+{IF GIT DIFF:}
+{n} files changed, {lines added} insertions(+), {lines deleted} deletions(-)
+
+Modified files:
+- {file1}
+- {file2}
+
+{IF NO CHANGES:}
+_(No code changes detected)_
+
+### Acceptance Criteria Status
+- [x] {Completed criterion}
+- [ ] {Remaining criterion}
+
+**Progress:** {X}/{Y} completed
+
+### Draft Comment for Jira
+{The full draft comment from Step 3}
+
+---
+
+### Available Actions (Multi-Select)
+{Numbered action list from Step 5}
+```
+
+## Session Context
+
+After running, update conversational context:
+- **last_wrap_actions** — Which actions were executed
+- **pr_url** — The PR URL if one was created