@groupby/ai-dev 0.1.1 → 0.2.0

package/toolsets/rzlv-flow/skills/context-analyst/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: context-analyst
+description: Transform meeting transcripts, notes, or unstructured input into structured context documents. Extracts key decisions, action items, requirements, and stakeholder positions. Produces documents ready for PM review and handoff to other skills (like atlassian-orchestrator for Jira/Confluence creation). Use when you have raw meeting notes, transcripts, or brainstorming output that needs to be structured.
+---
+
+Transform unstructured input — meeting transcripts, notes, brainstorming output, audio summaries — into structured context documents with clear decisions, action items, requirements, assumptions with confidence levels, and stakeholder positions. The absolute priority is retention of ALL relevant discussion nuances, assumptions, and explicit statements — even at the expense of brevity. Output is ready for PM review and can be handed off to `atlassian-orchestrator` for Jira/Confluence creation.
+
+## Requirements
+
+No MCP servers required. This skill works with any LLM client.
+
+Optional: Atlassian MCP (`atlassian-rovo`) if you want to immediately create Jira/Confluence structures from the output. See the rzlv-flow toolset README for setup.
+
+## Core Principles
+
+- **Context retention is paramount** — never aggressively summarize. Preserve the "how" of discussions, not just the "what."
+- **Always create a file** — never dump processed output only in chat. The context document must be saved to a file for downstream use.
+- **Preserve speaker attribution** — direct quotes preserve intent better than paraphrasing. Attribute positions, decisions, and assumptions to speakers.
+- **Flag uncertainty explicitly** — unresolved debates and open questions are valuable signal, not noise.
+- **Every assumption deserves documentation** — with confidence level (High/Medium/Low) and speaker attribution.
+
+## Resources to Load
+
+None required — this skill is standalone.
+
+Optionally, if the user wants output placed in the Jira mirror structure, read:
+- `docs/ai/resources/jira-file-structure.md` — for file placement rules
+
+## Process
+
+### Step 1: Accept Input
+
+Accept the source material in any of these forms:
+
+- **Pasted text** — User pastes meeting transcript, notes, or other unstructured text directly into the conversation.
+- **File reference** — User points to a file containing the source material (e.g. "analyze the notes in `meeting-notes/2025-04-03.md`").
+- **Multiple sources** — User provides several files or snippets to combine into one context document.
+
+If the input is unclear or empty, ask:
+
+```
+What would you like me to analyze? You can:
+1. Paste meeting notes or a transcript here
+2. Point me to a file (e.g. "meeting-notes/standup.md")
+3. Describe the meeting or discussion to capture
+
+Choose or paste your content:
+```
+
+### Step 2: Identify Source Metadata
+
+Before analyzing, capture metadata about the source:
+
+- **Title/topic** — What was the meeting or discussion about? Infer from content or ask.
+- **Date** — When did this occur? Extract from the content or use today's date.
+- **Participants** — Who was involved? Extract names mentioned in the content.
+- **Key contributors** — Identify the 2-3 most active participants.
+- **Source type** — Transcript, notes, brainstorm, audio summary, etc. Infer from format.
+
+### Step 3: Noise Filtering
+
+Apply minimal filtering before analysis:
+
+- **Remove ONLY:** Phatic communication ("hello", "how are you"), social pleasantries, audio/connection technical issues ("can you hear me?", "you're on mute").
+- **RETAIN ALL:** Product discussions, scope discussions, technical discussions, UX discussions, disagreements, tentative ideas, and "thinking out loud" sections. When in doubt, retain.
+
+### Step 4: Extract and Structure
+
+Analyze the input and extract the following categories. Not every category will be present in every input — include only sections that have content.
+
+**Initial Framing & Goals:**
+- Synthesize introductory remarks — what problem is being discussed and why now?
+- Capture the business case if stated.
+- Identify the high-level goal of the meeting.
+
+**Problem and User Context:**
+- User needs with speaker attribution and direct quotes.
+- Edge cases and historical context discussed.
+- Target users or personas mentioned.
+
+**Key Decisions:**
+- Identify explicit decisions ("we decided...", "the decision is...", "agreed to...")
+- Identify implicit decisions (consensus reached, directions chosen)
+- For each decision, capture the outcome and rationale
+- Quote the relevant source text for traceability
+
+**Action Items:**
+- Identify tasks assigned or volunteered ("I'll do...", "can you...", "{name} will...")
+- Capture the owner if mentioned
+- Capture any deadlines or timeframes mentioned
+- Mark as checklist items for easy tracking
+
+**Requirements:**
+- Identify functional requirements discussed
+- Identify non-functional requirements (performance, security, scalability)
+- Identify constraints or limitations mentioned (security, compliance, tech stack)
+- Distinguish between confirmed requirements and proposed/tentative ones
+
+**Assumptions:**
+- Capture every assumption — both explicit ("I'm assuming...") and inferred from context.
+- For each assumption, document:
+  - **Type:** Explicit (speaker stated it) or Inferred (analyst detected it)
+  - **Speaker:** Who made or implied this assumption
+  - **Confidence:** High (80%+), Medium (50-80%), or Low (<50%)
+  - **Impact:** What breaks if this assumption is wrong
+
+**Open Questions:**
+- Identify unresolved questions raised during the discussion
+- Identify items that were deferred ("we'll discuss later", "needs more research")
+- Capture who is responsible for following up, if mentioned
+- Include the original quote where possible
+
+**Stakeholder Positions:**
+- Track individual viewpoints, concerns, and preferences with speaker names
+- Note any disagreements or tensions
+- Capture context for why someone holds a position
+
+**Solution Discussion & Technical Details:**
+- Proposed components/approaches with speaker attribution
+- Architecture decisions or preferences discussed
+- Technology choices or constraints
+- Integration requirements
+- Performance targets or SLAs mentioned
+
+### Step 5: Produce Context Document
+
+Generate a structured markdown document with the extracted content using the output format below.
+
+### Step 6: Save Output
+
+Determine where to save the context document:
+
+1. **If the user specifies a path** — Save there.
+2. **If a Jira project context exists** — Offer to save in the Jira mirror structure:
+   ```
+   docs/jira/{instance}/{project}/_context/{date}-{topic-slug}.md
+   ```
+3. **Default** — Ask the user:
+   ```
+   Where should I save this context document?
+   1. Specify a file path
+   2. Save to project context folder (docs/jira/.../_context/)
+   3. Don't save — just display it
+
+   Choose [3]:
+   ```
+
+If the target path already exists, warn before overwriting:
+```
+⚠️ File already exists: {path}
+1. Overwrite
+2. Save as {path-v2}
+3. Cancel
+
+Choose [2]:
+```
+
+### Step 7: Suggest Follow-up
+
+Based on what was extracted, suggest relevant next steps using other skills:
+
+- **If requirements and technical details were identified:**
+  "Use `atlassian-orchestrator` to create an epic structure with documentation from this context."
+
+- **If action items map to Jira tickets:**
+  "Use `atlassian-orchestrator` to create Jira stories from the identified action items."
+
+- **If decisions should be documented in Confluence:**
+  "Use `atlassian-orchestrator` (Confluence sync — flexible mode) to publish this document to Confluence."
+
+## Output Format
+
+```
+# {Feature/Topic Name} — Meeting Context Document
+
+## Meeting Metadata
+| Field | Value |
+|-------|-------|
+| **Meeting Name** | {meeting name or topic} |
+| **Date** | {date} |
+| **Participants** | {alphabetical list} |
+| **Key Contributors** | {top 2-3 most active names} |
+| **Source Type** | {Transcript / Notes / Audio Summary / etc.} |
+
+---
+
+{INCLUDE ONLY SECTIONS THAT HAVE CONTENT:}
+
+## Initial Framing & High-Level Goal
+{Synthesis of introductory remarks and business case}
+
+## Problem and User Context
+
+### User Needs
+{FOR EACH KEY POINT WITH SPEAKER:}
+* **{Speaker Name}:** "{quote or detailed summary}"
+
+### Edge Cases & Historical Context
+{FOR EACH ITEM:}
+* {Specific scenario or historical context discussed}
+
+## Solution Discussion
+
+### Proposed Components
+| Component | Description | Speaker |
+|-----------|-------------|---------|
+| {Component A} | {description} | {speaker} |
+| {Component B} | {description} | {speaker} |
+
+### Constraints Identified
+* **Security/Compliance:** {specific mentions}
+* **Performance:** {metrics or concerns}
+* **Technology Stack:** {platforms, languages, constraints}
+
+## Decisions Made
+| Decision | Outcome | Context | Speaker |
+|----------|---------|---------|---------|
+| {Decision 1} | {final outcome} | {why/rationale} | {speaker} |
+
+## Assumptions
+| Assumption | Type | Speaker | Confidence | Impact if Wrong |
+|------------|------|---------|------------|----------------|
+| {Assumption 1} | Explicit/Inferred | {name} | High/Medium/Low | {what breaks} |
+
+## Action Items
+{FOR EACH ACTION:}
+- [ ] {Action description} {IF OWNER:}(Owner: {person}) {IF DEADLINE:}— Due: {date/timeframe}
+
+## Requirements
+**Confirmed:**
+{FOR EACH CONFIRMED REQUIREMENT:}
+- {Requirement description}
+
+**Proposed / Tentative:**
+{FOR EACH PROPOSED REQUIREMENT:}
+- {Requirement description} — needs confirmation
+
+## Open Questions
+{FOR EACH QUESTION:}
+* **{Question}:** "{original quote or summary}" — {Speaker}
+
+## Stakeholder Positions
+{FOR EACH PERSON WITH A NOTABLE POSITION:}
+- **{Person}:** {Position or concern summary}
+
+---
+
+## Suggested Next Steps
+{Based on extracted content:}
+1. {Actionable suggestion, potentially referencing other skills}
+2. {Additional suggestion}
+
+---
+*Generated by: context-analyst skill*
+*Source: {filename or "pasted input"}*
+```
+
+## Session Context
+
+After running, update conversational context with:
+
+- **last_context_document_path** — Where the document was saved (if saved)
+- **last_context_document_topic** — The topic/title of the document
+- **context_action_items_count** — Number of action items extracted (useful for follow-up)
+- **context_assumptions_count** — Number of assumptions captured (useful for PM review)

package/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/rzlv-flow/skills/jira-daily-triage/SKILL.md

@@ -0,0 +1,135 @@
+---
+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 and ID from the results.
+- If no open sprint is found, inform the user and continue without a sprint filter.
+- Store the active sprint name and ID 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} ({X}/{Y} tickets complete)
+
+### 🔥 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
+- PROJ-120: Waiting on design review (3 days)
+
+**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/rzlv-flow/skills/jira-sprint-status/SKILL.md

@@ -0,0 +1,116 @@
+---
+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 and ID. 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 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}
+
+### 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})
+
+### 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)
+```

package/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}
+```