@groupby/ai-dev 0.1.1 → 0.2.0

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

@@ -0,0 +1,227 @@
+---
+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.
+
+### Step 3: Draft Jira Comment
+
+Build a comprehensive comment covering both ticket updates and code progress:
+
+```
+**Work 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}
+
+**AC Completed:** {X}/{Y}
+**Remaining:** {what's left}
+
+**Next Steps:** {suggested next action}
+```
+
+### Step 4: FCMP Protocol (Before Any Sync)
+
+Before executing any write operations, run the full FCMP cycle:
+
+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. Show the diff to the user and warn if conflicts exist.
+
+Only proceed to the action menu after the FCMP cycle completes.
+
+### 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

package/toolsets/toolsets/rzlv-flow/README.md

@@ -0,0 +1,102 @@
+# rzlv-flow: Atlassian Intelligence Skills
+
+A toolset of modular, composable skills for Jira and Confluence developer workflows. Covers daily triage, ticket focus, wrap/sync, sprint status, context loading, and more — all without requiring the full BMAD Method or the rzlv-flow monolith.
+
+Each skill is standalone and can be installed individually or as a complete suite.
+
+## Quick Start
+
+```bash
+# 1. Install all skills + resources
+npx @groupby/ai-dev install toolset rzlv-flow
+
+# 2. Configure Atlassian MCP (see docs/mcp-setup.md)
+#    Add atlassian-rovo config to .vscode/mcp.json
+
+# 3. Use — ask your AI assistant:
+#    "Start my day"           → daily triage
+#    "Focus on PROJ-123"      → ticket deep-dive
+#    "Wrap up PROJ-123"       → wrap & sync
+```
+
+See [docs/getting-started.md](docs/getting-started.md) for a full walkthrough.
+
+## Skills
+
+| Skill | Description | Status |
+|-------|-------------|--------|
+| `jira-daily-triage` | Start-of-day ticket triage with sprint detection | Complete |
+| `jira-ticket-focus` | Deep-load a ticket with full context | Complete |
+| `jira-wrap-sync` | Wrap up work, draft comment, multi-action sync | Complete |
+| `jira-ticket-trace` | Trace code back to Jira requirements | Complete |
+| `jira-comment` | Add a comment to a Jira ticket with FCMP safety | Complete |
+| `jira-status` | Change ticket status with transition validation | Complete |
+| `jira-sprint-status` | Sprint status report with completion metrics | Complete |
+| `jira-sync` | Force-sync local Jira context with remote state | Complete |
+| `atlassian-orchestrator` | Pull surrounding ticket context and create structures | Complete |
+| `context-analyst` | Transform meeting transcripts into structured docs | Complete |
+| `confluence-publish` | Publish local markdown to Confluence with Leaf Bundle mirrors | Complete |
+| `confluence-fetch` | Pull a Confluence page into a local markdown mirror | Complete |
+
+> **Note:** `confluence-publish` provides lightweight ad-hoc publishing to Confluence. For bulk structured sync of `_docs/` folders following epic hierarchy, use `atlassian-orchestrator` Mode 3 instead.
+
+## Prerequisites
+
+### Required: Atlassian MCP (`atlassian-rovo`)
+
+All Jira and Confluence skills require the Atlassian MCP server for API access to your Atlassian instance.
+
+### Optional: GitHub MCP
+
+Only needed for PR creation features in `jira-wrap-sync`. Not required for any other skills.
+
+See [docs/mcp-setup.md](docs/mcp-setup.md) for detailed setup instructions.
+
+## Installation
+
+```bash
+npx @groupby/ai-dev install toolset rzlv-flow       # All skills + resources
+npx @groupby/ai-dev install skill jira-daily-triage   # Individual skill
+```
+
+Common options:
+
+| Flag | Description |
+|------|-------------|
+| `--target <dir>` | Install into a specific directory (defaults to cwd) |
+| `--dry-run` | Preview what would be installed without writing files |
+| `--force` | Overwrite existing files without prompting |
+| `--skip-existing` | Skip files that already exist |
+
+You can also copy skills manually from this repository into `docs/ai/skills/` and resources into `docs/ai/resources/`.
+
+## BMAD Compatibility
+
+These skills are compatible with BMAD's Jira file structure (`docs/jira/{instance}/{project}/...`) but do **not** require BMAD. They were originally developed as part of the BMAD "Atlassian Intelligence Suite" and have been extracted as standalone skills. If BMAD is installed in your project, these skills coexist without conflict.
+
+## Shared Resources
+
+Skills reference shared resource files installed to `docs/ai/resources/` in your project:
+
+| Resource | Description |
+|----------|-------------|
+| `fcmp-protocol.md` | Fetch-Compare-Merge-Push sync pattern for safe Atlassian read/write |
+| `jira-file-structure.md` | Standard directory layout for local Jira mirrors |
+| `confluence-file-structure.md` | Leaf Bundle pattern for Confluence page mirrors |
+| `sync-state-format.md` | YAML frontmatter schema for ticket and page files |
+| `confluence-page-templates/` | Starter scaffolds for Confluence pages (initiative overview, strategic context, technical architecture, decisions) |
+
+## MCP Setup Automation
+
+MCP server configuration is currently manual — see [docs/mcp-setup.md](docs/mcp-setup.md) for step-by-step instructions (~5 minutes). Automated MCP configuration via the CLI is a future enhancement.
+
+## Documentation
+
+| Doc | Description |
+|-----|-------------|
+| [docs/getting-started.md](docs/getting-started.md) | Quick walkthrough: install → configure → use |
+| [docs/mcp-setup.md](docs/mcp-setup.md) | Atlassian and GitHub MCP server configuration |
+
+## Contributing
+
+See the [architecture documentation](../../docs/architecture/README.md) for repo structure, skill authoring guides, and conventions.

package/toolsets/toolsets/rzlv-flow/docs/getting-started.md

@@ -0,0 +1,102 @@
+# Getting Started with rzlv-flow
+
+A quick walkthrough to go from zero to running your first Jira skill.
+
+---
+
+## 1. Install the toolset
+
+From your project root:
+
+```bash
+npx @groupby/ai-dev install toolset rzlv-flow
+```
+
+This installs all 12 skills into `docs/ai/skills/` and shared resources into `docs/ai/resources/`. It also creates stub `SKILL.md` files in your detected LLM client directories (`.github/skills/`, `.claude/skills/`, etc.).
+
+To install a single skill instead:
+
+```bash
+npx @groupby/ai-dev install skill jira-daily-triage
+```
+
+Individual skill installs also pull in the shared resources automatically.
+
+## 2. Configure the Atlassian MCP server
+
+All Jira and Confluence skills require the Atlassian MCP (`atlassian-rovo`) server for API access.
+
+Add the following to `.vscode/mcp.json` in your project (create the file if needed):
+
+```json
+{
+  "servers": {
+    "atlassian-rovo": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/atlassian-rovo-mcp"],
+      "env": {
+        "ATLASSIAN_SITE": "your-company.atlassian.net",
+        "ATLASSIAN_EMAIL": "you@company.com",
+        "ATLASSIAN_API_TOKEN": "${input:atlassianApiToken}"
+      }
+    }
+  },
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "atlassianApiToken",
+      "description": "Atlassian API Token",
+      "password": true
+    }
+  ]
+}
+```
+
+Generate an API token at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
+
+See [mcp-setup.md](mcp-setup.md) for the full setup guide including GitHub MCP and troubleshooting.
+
+## 3. Verify the connection
+
+Ask your AI assistant:
+
+> "Search Jira for my open tickets"
+
+If the MCP server is configured correctly, it will call the Atlassian MCP and return your tickets.
+
+## 4. Start using skills
+
+### Daily triage — start your day
+
+> "Start my day" or "Run daily triage"
+
+The `jira-daily-triage` skill detects your active sprint, triages tickets by priority, and gives you a focused plan.
+
+### Ticket focus — deep-dive into a ticket
+
+> "Focus on PROJ-123"
+
+The `jira-ticket-focus` skill loads a ticket with full context: description, acceptance criteria, subtasks, linked issues, and comments.
+
+### Wrap up work
+
+> "Wrap up my work on PROJ-123"
+
+The `jira-wrap-sync` skill drafts a comment, updates status, and optionally creates a PR.
+
+## Skill reference
+
+| Skill | Trigger | What it does |
+|-------|---------|--------------|
+| `jira-daily-triage` | "Start my day" | Sprint-aware ticket triage and prioritization |
+| `jira-ticket-focus` | "Focus on PROJ-123" | Deep-load ticket with full context |
+| `jira-wrap-sync` | "Wrap up PROJ-123" | Draft comment, update status, sync state |
+| `jira-ticket-trace` | "Trace this code to Jira" | Map code changes back to requirements |
+| `jira-comment` | "Comment on PROJ-123" | Add/update comments with FCMP safety |
+| `jira-status` | "Move PROJ-123 to In Review" | Change status with transition validation |
+| `jira-sprint-status` | "Sprint status report" | Sprint progress, burndown, completion metrics |
+| `jira-sync` | "Sync Jira context" | Force-refresh local Jira mirror |
+| `atlassian-orchestrator` | "Set up context for PROJ-123" | Create local structures from Jira/Confluence |
+| `context-analyst` | "Process this meeting transcript" | Transform transcripts into structured docs |
+| `confluence-publish` | "Publish to Confluence" | Push local markdown to Confluence pages |
+| `confluence-fetch` | "Fetch Confluence page" | Pull a Confluence page into local mirror |

package/toolsets/toolsets/rzlv-flow/docs/mcp-setup.md

@@ -0,0 +1,126 @@
+# MCP Server Setup Guide
+
+This guide covers configuring the MCP servers required by rzlv-flow skills.
+
+---
+
+## Atlassian MCP (`atlassian-rovo`) — Required
+
+All Jira and Confluence skills depend on the Atlassian MCP server for API access.
+
+### VS Code Configuration
+
+Add the following to your `.vscode/mcp.json` (create the file if it doesn't exist):
+
+```json
+{
+  "servers": {
+    "atlassian-rovo": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/atlassian-rovo-mcp"],
+      "env": {
+        "ATLASSIAN_SITE": "your-company.atlassian.net",
+        "ATLASSIAN_EMAIL": "you@company.com",
+        "ATLASSIAN_API_TOKEN": "${input:atlassianApiToken}"
+      }
+    }
+  },
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "atlassianApiToken",
+      "description": "Atlassian API Token",
+      "password": true
+    }
+  ]
+}
+```
+
+### Generating an API Token
+
+1. Go to [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
+2. Click **Create API token**
+3. Give it a label (e.g. "VS Code MCP")
+4. Copy the generated token — you won't see it again
+
+### Verifying the Connection
+
+After configuring, ask the LLM to run a simple query:
+
+> "Search Jira for my open tickets using the Atlassian MCP"
+
+If the MCP server is configured correctly, it will call `mcp_atlassian-rovo_search` and return results. If you get an authentication error, double-check your site URL, email, and API token.
+
+---
+
+## GitHub MCP — Optional
+
+Only needed for PR creation features in the `jira-wrap-sync` skill. All other skills work without it.
+
+### VS Code Configuration
+
+Add to your `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:githubPat}"
+      }
+    }
+  },
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "githubPat",
+      "description": "GitHub Personal Access Token",
+      "password": true
+    }
+  ]
+}
+```
+
+### PAT Token Requirements
+
+Create a fine-grained personal access token at [https://github.com/settings/tokens?type=beta](https://github.com/settings/tokens?type=beta) with the following scopes:
+
+- **Repository access:** Select the repos you work with
+- **Permissions:**
+  - Contents: Read and write
+  - Pull requests: Read and write
+  - Metadata: Read-only
+
+### When It's Needed
+
+Only `jira-wrap-sync` uses the GitHub MCP — specifically when creating a pull request as part of the wrap-up workflow. If you don't use that feature, you can skip this setup entirely.
+
+---
+
+## Troubleshooting
+
+### MCP server not starting
+
+- Ensure `npx` is available in your PATH. Run `npx --version` in your terminal.
+- Check the VS Code Output panel (View → Output → select "MCP" from the dropdown) for error messages.
+- Try running the `npx` command manually in a terminal to see if it installs and starts correctly.
+
+### Authentication failures (401)
+
+- **Atlassian:** Verify your site URL includes `.atlassian.net` (not the full `https://` URL). Confirm your email matches your Atlassian account. Regenerate the API token if needed.
+- **GitHub:** Confirm the PAT hasn't expired. Check that it has the required scopes.
+
+### Wrong Atlassian instance
+
+- `ATLASSIAN_SITE` should be just the domain, e.g. `your-company.atlassian.net` — not a full URL like `https://your-company.atlassian.net/jira`.
+
+### Rate limiting
+
+- Atlassian APIs have rate limits. If you see 429 errors, the skills will back off automatically per the FCMP protocol. Avoid running multiple sync operations in rapid succession.
+
+### MCP calls return empty results
+
+- Confirm you have permission to access the Jira project or Confluence space you're querying.
+- Check that the project key or space key is correct.

package/toolsets/toolsets/rzlv-flow/resources/README.md

@@ -0,0 +1,16 @@
+# rzlv-flow Shared Resources
+
+Resources are shared reference material installed alongside skills. They contain protocol definitions, file structure conventions, and schema specifications that multiple skills depend on.
+
+## Installation
+
+When installed via the CLI, resources are placed in `docs/ai/resources/` in the target project. Skills reference them via relative paths and may ask the LLM to load them at the start of a workflow.
+
+## Resource Files
+
+| File | Description |
+|------|-------------|
+| `fcmp-protocol.md` | Fetch-Compare-Merge-Push sync pattern — the core protocol for safe Atlassian read/write operations |
+| `jira-file-structure.md` | Standard directory layout for local Jira mirrors (`docs/jira/{instance}/{project}/...`) |
+| `confluence-file-structure.md` | Directory layout for local Confluence page mirrors with structured and flexible modes |
+| `sync-state-format.md` | YAML frontmatter schema for Jira ticket and Confluence page files |