@groupby/ai-dev 0.1.1 → 0.2.1

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.}