@groupby/ai-dev 0.1.0 → 0.2.0

package/toolsets/rzlv-flow/README.md

@@ -0,0 +1,57 @@
+# 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.
+
+## Skills
+
+| Skill | Description | Status |
+|-------|-------------|--------|
+| `jira-daily-triage` | Start-of-day ticket triage with sprint detection | Planned |
+| `jira-ticket-focus` | Deep-load a ticket with full context | Planned |
+| `jira-wrap-sync` | Wrap up work, draft comment, multi-action sync | Planned |
+| `jira-ticket-trace` | Trace code back to Jira requirements | Planned |
+| `jira-comment` | Add a comment to a Jira ticket with FCMP safety | Planned |
+| `jira-status` | Change ticket status with transition validation | Planned |
+| `jira-sprint-status` | Sprint status report with completion metrics | Planned |
+| `jira-sync` | Force-sync local Jira context with remote state | Planned |
+| `atlassian-orchestrator` | Pull surrounding ticket context and create structures | Complete |
+| `context-analyst` | Transform meeting transcripts into structured docs | Complete |
+
+## 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
+```
+
+> **Note:** CLI toolset support is coming soon. For now, skills can be copied manually from this repository into your project's `docs/ai/skills/` directory, 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) |

package/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/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 |

package/toolsets/rzlv-flow/resources/confluence-file-structure.md

@@ -0,0 +1,179 @@
+# Confluence File Structure — Local Page Mirrors
+
+**Pattern:** Dual-mode local mirrors for Confluence pages
+
+---
+
+## Overview
+
+Skills that interact with Confluence maintain local mirrors of pages under `docs/confluence/{instance}/{space}/`. Two modes are supported depending on how the content is created:
+
+- **Structured mode** — Orchestrator-driven, epic-based hierarchy with predefined page types
+- **Flexible mode** — User-specified location and page structure for ad-hoc documentation
+
+Both modes follow the FCMP protocol for safe sync operations and preserve manual edits made directly in Confluence.
+
+---
+
+## Base Path
+
+```
+docs/confluence/{instance}/{space}/
+```
+
+- `{instance}` — The Atlassian site identifier (e.g. `rezolve`)
+- `{space}` — The Confluence space key (e.g. `ENG`, `PROJ`)
+
+---
+
+## Structured Mode
+
+Used when creating Confluence pages from Jira epic structures — typically driven by the `atlassian-orchestrator` skill.
+
+### Hierarchy
+
+```
+docs/confluence/{instance}/{space}/
+└── {initiative-name}/
+    ├── index.md                          # Initiative Overview
+    └── {epic-name}/
+        ├── overview.md
+        ├── technical-architecture.md
+        ├── decisions.md
+        ├── strategic-context.md
+        ├── research-and-findings.md         # Created only if relevant content exists
+        ├── assumptions.md                   # Created only if relevant content exists
+        └── implementation-guidance.md
+```
+
+### Page Types
+
+| Page Type | Source | Description |
+|-----------|--------|-------------|
+| Initiative Overview (`index.md` at initiative root) | Initiative metadata | Top-level overview: goals, epic breakdown, navigation |
+| `overview.md` | Epic `_docs/` | High-level epic overview and goals |
+| `technical-architecture.md` | Epic `_docs/` | Architecture decisions and technical design |
+| `decisions.md` | Epic `_docs/` | Decision log and rationale |
+| `strategic-context.md` | Epic `_docs/` | Business context and strategic alignment |
+| `research-and-findings.md` | Epic `_docs/` | User research, discoveries, and clarifications* |
+| `assumptions.md` | Epic `_docs/` | Assumptions with confidence levels and validation status* |
+| `implementation-guidance.md` | Epic `_docs/` | High-value technical guides for development |
+
+\* Created only if the source material includes relevant content.
+
+### When to Use
+
+- Creating Confluence pages from Jira epic structure with `_docs/` content
+- Orchestrator-driven workflows that generate documentation alongside Jira structures
+
+### Sync Rules (Structured)
+
+- Generate Confluence pages from Jira `_docs/` folders
+- Sync BEFORE Jira creation (to get page IDs for linking)
+- Embed Confluence links in Jira ticket descriptions
+- Follow initiative/epic hierarchy
+
+---
+
+## Flexible Mode
+
+Used for ad-hoc documentation, user-specified locations, and non-epic-based content.
+
+### Hierarchy
+
+```
+docs/confluence/{instance}/{space}/
+└── {user-specified-path}/
+    └── {page-name}.md
+```
+
+No predefined structure — adapts to the user's needs.
+
+### When to Use
+
+- Generic documentation and manual publishing
+- Publishing existing local docs to Confluence retroactively
+- Content created by `context-analyst` or other skills outside an epic workflow
+- Any user-driven page creation
+
+### Prompts for Flexible Mode
+
+Skills using flexible mode should ask:
+1. "Where should I place this page in Confluence? (space/parent)"
+2. "Page title?"
+3. "Should I link to a Jira ticket?"
+
+### Sync Rules (Flexible)
+
+- User specifies target location (space + parent page)
+- Optional: Link back to Jira ticket if provided
+- No predefined structure — adapt to user's needs
+- Can publish existing docs to Confluence retroactively
+
+---
+
+## Ownership
+
+### Generated Pages (Structured Mode)
+
+- **Owner:** Orchestrator-type skills (e.g. `atlassian-orchestrator`)
+- **Source:** `_docs/` folders from the Jira file structure
+- **Description:** Automatically generated from epic documentation; synced to Confluence
+
+### Manual / Ad-hoc Pages (Flexible Mode)
+
+- **Owner:** User or any skill
+- **Source:** Any markdown file
+- **Location:** User-specified or derived from context
+
+### Manual Edits in Confluence
+
+- **Preserved:** Yes, always — regardless of mode
+- **Protocol:** FCMP ensures user edits in Confluence are never overwritten without merge
+
+---
+
+## Sync Rules (Both Modes)
+
+- Follow the FCMP protocol when updating existing pages (see `fcmp-protocol.md`)
+- Preserve manual edits made in Confluence
+- Store page ID and URL in frontmatter after sync (see `sync-state-format.md`)
+
+---
+
+## Page File Format
+
+Each local Confluence mirror file uses YAML frontmatter for sync metadata:
+
+```yaml
+---
+sync:
+  confluence_page_id: "123456789"
+  confluence_url: "https://company.atlassian.net/wiki/spaces/ENG/pages/123456789"
+  space: "ENG"
+  parent_page_id: "987654321"
+  last_synced: "2025-12-11T10:30:00Z"
+  version: 5
+  remote_updated: "2025-12-11T09:15:00Z"
+
+mode: "structured"  # structured | flexible
+
+source:
+  # For structured mode
+  jira_ticket: "PROJ-120"
+  doc_type: "technical-architecture"
+  generated_from: "docs/jira/rezolve/PROJ/user-authentication/_docs/technical-architecture.md"
+
+  # For flexible mode
+  # origin: "manual"
+  # linked_jira: "PROJ-123"
+---
+
+# Page Title
+
+Page content in markdown, converted to Confluence storage format during sync.
+```
+
+See `sync-state-format.md` for full frontmatter schema details.
+
+<!-- TODO: Pull additional detail from full rzlv-flow repo for Leaf Bundle pattern specifics and doc-type-mapping rules if available -->

package/toolsets/rzlv-flow/resources/confluence-page-templates/README.md

@@ -0,0 +1,19 @@
+# Confluence Page Templates
+
+Starter scaffolds for Confluence pages created by the `atlassian-orchestrator` skill (structured mode). Each template contains standard section headings and placeholder tokens.
+
+## Usage
+
+- Templates provide consistent section headings across generated pages.
+- Replace `{tokens}` with actual content during page creation.
+- Skills can load these templates instead of generating page structure from scratch.
+- Users can customize templates to match their team's conventions.
+
+## Templates
+
+| Template | File | Description |
+|----------|------|-------------|
+| Initiative Overview | `initiative-overview.md` | Top-level initiative page: goals, epic breakdown, navigation |
+| Strategic Context | `strategic-context.md` | Business goals, product vision, strategic decisions |
+| Technical Architecture | `technical-architecture.md` | System design, tech decisions, implementation patterns |
+| Decisions | `decisions.md` | Consolidated decision log with rationale |

package/toolsets/rzlv-flow/resources/confluence-page-templates/decisions.md

@@ -0,0 +1,36 @@
+---
+sync:
+  confluence_page_id: ""
+  confluence_url: ""
+  confluence_title: "Decision Log — {Initiative/Epic Name}"
+  space: "{SPACE}"
+  parent_page_id: ""
+  last_synced: ""
+  version: 1
+  remote_updated: ""
+mode: "structured"
+source:
+  jira_ticket: "{EPIC-KEY}"
+  doc_type: "decisions"
+  generated_from: ""
+---
+
+# Decision Log — {Initiative/Epic Name}
+
+## Active Decisions
+
+| ID | Decision | Date | Rationale | Confidence | Impact |
+|----|----------|------|-----------|------------|--------|
+| {id} | {decision} | {date} | {rationale} | {High/Medium/Low} | {impact area} |
+
+## Pending Decisions
+
+| ID | Question | Context | Options | Owner | Deadline |
+|----|----------|---------|---------|-------|----------|
+| {id} | {question} | {context} | {options} | {owner} | {deadline} |
+
+## Superseded Decisions
+
+| ID | Original Decision | Superseded By | Date | Reason |
+|----|-------------------|---------------|------|--------|
+| {id} | {original} | {new decision} | {date} | {reason} |

package/toolsets/rzlv-flow/resources/confluence-page-templates/initiative-overview.md

@@ -0,0 +1,40 @@
+---
+sync:
+  confluence_page_id: ""
+  confluence_url: ""
+  confluence_title: "{Initiative Name}"
+  space: "{SPACE}"
+  parent_page_id: ""
+  last_synced: ""
+  version: 1
+  remote_updated: ""
+mode: "structured"
+source:
+  jira_initiative_key: "{INITIATIVE-KEY}"
+---
+
+# {Initiative Name}
+
+## Overview
+
+{Brief summary of the initiative — 2-3 sentences covering purpose and strategic goals.}
+
+## Epic Breakdown
+
+| Epic | Description | Status | Stories | Confluence |
+|------|-------------|--------|---------|------------|
+| {EPIC-KEY} | {Epic summary} | {status} | {count} | [link]({confluence_url}) |
+
+## Quick Navigation
+
+- [{Epic Name} — Overview]({epic-overview-url})
+- [{Epic Name} — Technical Architecture]({epic-tech-arch-url})
+- [{Epic Name} — Decisions]({epic-decisions-url})
+
+## Timeline & Dependencies
+
+{Key dates, milestones, and cross-team dependencies.}
+
+## Success Criteria
+
+{Measurable outcomes that define initiative success.}

package/toolsets/rzlv-flow/resources/confluence-page-templates/strategic-context.md

@@ -0,0 +1,44 @@
+---
+sync:
+  confluence_page_id: ""
+  confluence_url: ""
+  confluence_title: "Strategic Context — {Initiative/Epic Name}"
+  space: "{SPACE}"
+  parent_page_id: ""
+  last_synced: ""
+  version: 1
+  remote_updated: ""
+mode: "structured"
+source:
+  jira_ticket: "{EPIC-KEY}"
+  doc_type: "strategic-context"
+  generated_from: ""
+---
+
+# Strategic Context — {Initiative/Epic Name}
+
+## Business Objectives
+
+{Business goals this work supports. Include measurable targets where possible.}
+
+## Product Vision
+
+{Target users, value proposition, and how this fits the broader product strategy.}
+
+## Market Context
+
+{Competitive landscape, market timing, and external factors influencing this work.}
+
+## Success Criteria
+
+{Measurable outcomes — metrics, thresholds, and how they will be evaluated.}
+
+## Strategic Decisions
+
+| Decision | Rationale | Date | Confidence |
+|----------|-----------|------|------------|
+| {decision} | {why} | {date} | {High/Medium/Low} |
+
+## Related Documents
+
+- [{Document title}]({url}) — {brief description}

package/toolsets/rzlv-flow/resources/confluence-page-templates/technical-architecture.md

@@ -0,0 +1,48 @@
+---
+sync:
+  confluence_page_id: ""
+  confluence_url: ""
+  confluence_title: "Technical Architecture — {Initiative/Epic Name}"
+  space: "{SPACE}"
+  parent_page_id: ""
+  last_synced: ""
+  version: 1
+  remote_updated: ""
+mode: "structured"
+source:
+  jira_ticket: "{EPIC-KEY}"
+  doc_type: "technical-architecture"
+  generated_from: ""
+---
+
+# Technical Architecture — {Initiative/Epic Name}
+
+## System Overview
+
+{High-level architecture description. Key components and how they interact.}
+
+## Technology Stack
+
+{Languages, frameworks, infrastructure, and key libraries.}
+
+## Architecture Decisions
+
+| Decision | Options Considered | Chosen | Rationale |
+|----------|--------------------|--------|-----------|
+| {decision} | {options} | {chosen} | {why} |
+
+## Integration Points
+
+{External systems, APIs, data flows, and contract details.}
+
+## Performance & Scalability
+
+{Performance targets, scalability strategies, and known constraints.}
+
+## Security Considerations
+
+{Authentication, authorization, data protection, and compliance requirements.}
+
+## Implementation Patterns
+
+{Key patterns and approaches used in this codebase.}