feat(confluence): add confluence plugin for page management and doc g…

.claude-plugin/marketplace.json

@@ -240,6 +240,12 @@
       "source": "./plugins/marketplace-ops",
       "description": "Maintenance commands for Claude Code plugin marketplaces",
       "version": "0.1.2"
+    },
+    {
+      "name": "confluence",
+      "source": "./plugins/confluence",
+      "description": "Confluence page management, documentation generation from Jira, and meeting notes publishing",
+      "version": "0.1.0"
     }
   ]
 }

plugins/confluence/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "confluence",
+  "description": "Confluence page management, documentation generation from Jira, and meeting notes publishing",
+  "version": "0.1.0",
+  "author": {
+    "name": "github.com/openshift-eng"
+  }
+}

plugins/confluence/README.md

@@ -0,0 +1,51 @@
+# Confluence Plugin
+
+Confluence page management, documentation generation from Jira, and meeting notes publishing.
+
+## Prerequisites
+
+The [mcp-atlassian](https://github.com/sooperset/mcp-atlassian) MCP server must be configured with Confluence credentials. The same server that provides Jira tools also exposes Confluence tools.
+
+### Required environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `CONFLUENCE_URL` | Your Confluence instance URL (e.g., `https://yourorg.atlassian.net/wiki`) |
+| `CONFLUENCE_USERNAME` | Atlassian account email |
+| `CONFLUENCE_API_TOKEN` | Atlassian API token ([generate one here](https://id.atlassian.com/manage-profile/security/api-tokens)) |
+
+If you already have the mcp-atlassian server configured for the `jira` plugin, Confluence tools are available automatically — no additional setup is needed.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/confluence:create-from-jira` | Generate a structured Confluence page from a Jira epic or story |
+| `/confluence:search` | Search Confluence for related documentation |
+| `/confluence:sync-meeting-notes` | Publish meeting notes or agendas to Confluence |
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| `page-templates` | Structured templates for design docs, feature specs, meeting notes, runbooks, and decision records |
+| `confluence-conventions` | Best practices for space organization, labeling, and page naming |
+
+## Usage Examples
+
+```bash
+# Generate a design doc from an Epic
+/confluence:create-from-jira PROJ-100 --space DEV --type design-doc
+
+# Search for related docs before starting work
+/confluence:search "authentication flow" --space TEAM
+
+# Publish grooming notes after running /jira:grooming
+/confluence:sync-meeting-notes TEAM "Sprint 42 Grooming - 2026-05-07"
+```
+
+## Works With
+
+This plugin pairs well with:
+- **jira** - Create Jira issues, then generate Confluence docs from them
+- **agendas** - Generate meeting agendas, then sync them to Confluence

plugins/confluence/commands/create-from-jira.md

@@ -0,0 +1,139 @@
+---
+description: Generate a structured Confluence page from a Jira epic or story
+argument-hint: "<issue-key> [--space <key>] [--parent-id <id>] [--type design-doc|feature-spec|runbook]"
+---
+
+## Name
+confluence:create-from-jira
+
+## Synopsis
+```
+/confluence:create-from-jira <issue-key> [--space <key>] [--parent-id <id>] [--type design-doc|feature-spec|runbook]
+```
+
+## Description
+The `confluence:create-from-jira` command reads a Jira epic, story, or feature request and generates a well-structured Confluence page from it. It analyzes the issue's summary, description, acceptance criteria, linked issues, comments, and child issues to produce a comprehensive document — not a shallow copy of the Jira fields.
+
+This command requires AI reasoning to:
+- Decide which page template best fits the issue (design doc, feature spec, runbook, or decision record)
+- Synthesize information scattered across linked issues and comments into a coherent narrative
+- Identify gaps in the Jira issue and flag them as open questions in the generated page
+- Structure the page hierarchy appropriately within the target Confluence space
+
+## Key Features
+- Automatically selects a page template based on issue type and content (or uses `--type` override)
+- Fetches and incorporates context from linked/child issues
+- Extracts action items and open questions from comments
+- Adds labels based on Jira components and labels
+- Links the generated page back to the source Jira issue
+
+## Implementation
+
+### Phase 1: Load Skills
+Invoke the `confluence:page-templates` skill to load page structure guidance for the selected document type.
+
+### Phase 2: Fetch Jira Context
+1. Fetch the primary issue using `mcp__mcp-atlassian__jira_get_issue`:
+   ```python
+   mcp__mcp-atlassian__jira_get_issue(
+       issue_key="<issue-key>",
+       fields="summary,description,status,issuetype,components,labels,priority,assignee,reporter,created,updated",
+       comment_limit=20
+   )
+   ```
+2. If the issue is an Epic, fetch child issues:
+   ```python
+   mcp__mcp-atlassian__jira_search(
+       jql="parent = <issue-key> ORDER BY rank ASC",
+       fields="summary,status,issuetype,assignee,description",
+       limit=50
+   )
+   ```
+3. Fetch linked issues if present (from the issue's links field).
+
+### Phase 3: Determine Page Type
+If `--type` is provided, use it directly. Otherwise, analyze the issue to select:
+- **Epic with multiple stories** -> `design-doc`
+- **Story with acceptance criteria** -> `feature-spec`
+- **Bug or incident-related** -> `runbook`
+- **Decision or spike** -> `decision-record`
+
+Ask the user to confirm the selected type before proceeding.
+
+### Phase 4: Resolve Target Space and Parent
+1. If `--space` is provided, use it. Otherwise, ask the user which space to publish to.
+2. If `--parent-id` is provided, use it. Otherwise:
+   - Use `mcp__mcp-atlassian__confluence_get_space_page_tree` to show the space structure
+   - Ask the user to select a parent page or publish at the root
+
+### Phase 5: Generate Page Content
+Using the loaded template from Phase 1 and the Jira context from Phase 2:
+1. Generate a page title from the Jira summary (prefix with issue key for traceability)
+2. Compose the page body in Markdown format with appropriate sections
+3. Include a "Source" section at the bottom linking back to the Jira issue
+4. Include an "Open Questions" section for any gaps identified during analysis
+5. Present the generated content to the user for review before publishing
+
+### Phase 6: Publish to Confluence
+1. Create the page:
+   ```python
+   mcp__mcp-atlassian__confluence_create_page(
+       space_key="<space>",
+       title="<generated-title>",
+       content="<generated-markdown>",
+       parent_id="<parent-id>",  # optional
+       content_format="markdown"
+   )
+   ```
+2. Add labels derived from Jira components and labels:
+   ```python
+   mcp__mcp-atlassian__confluence_add_label(
+       page_id="<created-page-id>",
+       name="<label>"
+   )
+   ```
+3. Report the created page URL and ID to the user.
+
+## Usage Examples
+
+1. **Generate a design doc from an Epic:**
+   ```
+   /confluence:create-from-jira PROJ-100 --space DEV --type design-doc
+   ```
+
+2. **Auto-detect type, ask for space interactively:**
+   ```
+   /confluence:create-from-jira OCPBUGS-1234
+   ```
+
+3. **Create under a specific parent page:**
+   ```
+   /confluence:create-from-jira FEAT-50 --space TEAM --parent-id 123456789
+   ```
+
+## Arguments
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `<issue-key>` | Yes | Jira issue key (e.g., `PROJ-123`, `OCPBUGS-456`) |
+| `--space <key>` | No | Target Confluence space key. If omitted, the user is prompted. |
+| `--parent-id <id>` | No | Parent page ID. If omitted, the user chooses from the space tree. |
+| `--type <type>` | No | Page template type: `design-doc`, `feature-spec`, `runbook`, or `decision-record`. Auto-detected if omitted. |
+
+## Return Value
+- The created Confluence page URL
+- The page ID for future reference
+- A summary of what was generated (title, template used, labels applied)
+
+## Error Handling
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Jira issue not found | Invalid issue key or no access | Verify the issue key and Jira authentication |
+| Space not found | Invalid space key | List available spaces and ask user to choose |
+| Permission denied | No write access to the target space | Ask user to specify a different space or check permissions |
+| Page title conflict | A page with the same title already exists in the space | Offer to update the existing page or append a suffix |
+
+## See Also
+- `confluence:search` - Find existing docs before creating new ones
+- `confluence:sync-meeting-notes` - Publish meeting notes to Confluence
+- `jira:create` - Create Jira issues
+- `jira:grooming` - Generate grooming agendas (output can be synced to Confluence)

plugins/confluence/commands/search.md

@@ -0,0 +1,121 @@
+---
+description: Search Confluence for related documentation using natural language or CQL
+argument-hint: "<query> [--space <key>] [--limit <n>]"
+---
+
+## Name
+confluence:search
+
+## Synopsis
+```
+/confluence:search <query> [--space <key>] [--limit <n>]
+```
+
+## Description
+The `confluence:search` command searches Confluence for documentation related to a topic, Jira issue, or natural language question. It goes beyond simple keyword search — it interprets the user's intent, constructs appropriate CQL queries, and returns a ranked, summarized list of relevant pages.
+
+This command requires AI reasoning to:
+- Translate natural language queries into effective CQL search expressions
+- Summarize each result's relevance to the original query
+- Identify the most useful pages and explain why they matter
+- Suggest follow-up searches when initial results are insufficient
+
+## Key Features
+- Accepts natural language queries, Jira issue keys, or raw CQL
+- Summarizes each result with a relevance explanation
+- Supports space filtering to narrow scope
+- Detects Jira issue keys in the query and automatically expands context (searches for the issue summary)
+
+## Implementation
+
+### Phase 1: Parse and Interpret Query
+1. Parse `$1` as the search query. Detect if it is:
+   - A Jira issue key (matches `[A-Z]+-\d+`) -> fetch the issue summary and use it as search terms
+   - Raw CQL (contains operators like `=`, `~`, `AND`, `OR`) -> pass through directly
+   - Natural language -> construct a CQL `siteSearch` query
+2. Parse optional flags: `--space` for space filtering, `--limit` for result count (default 10).
+
+### Phase 2: Execute Search
+1. Build and execute the search:
+   ```python
+   mcp__mcp-atlassian__confluence_search(
+       query="siteSearch ~ \"<interpreted-terms>\"",
+       limit=<limit>,
+       spaces_filter="<space-key>"  # if --space provided
+   )
+   ```
+2. If the query was a Jira issue key, also search for pages linking to that issue:
+   ```python
+   mcp__mcp-atlassian__confluence_search(
+       query="text ~ \"<issue-key>\"",
+       limit=5,
+       spaces_filter="<space-key>"
+   )
+   ```
+
+### Phase 3: Analyze and Rank Results
+1. For each result, read the page title, space, last modified date, and excerpt.
+2. Rank results by relevance to the original query intent.
+3. Group results by space if results span multiple spaces.
+4. Flag any results that appear outdated (last modified > 6 months ago).
+
+### Phase 4: Present Results
+Format the output as a ranked list:
+```
+## Search Results for "<query>"
+
+### 1. [Page Title](url) - Space: TEAM
+**Last updated:** 2025-12-01 | **Relevance:** High
+Summary of why this page is relevant...
+
+### 2. [Page Title](url) - Space: DEV
+**Last updated:** 2024-06-15 | **Relevance:** Medium | **Note:** Potentially outdated
+Summary of relevance...
+```
+
+If no results are found, suggest alternative search terms or broader queries.
+
+## Usage Examples
+
+1. **Search by topic:**
+   ```
+   /confluence:search "authentication flow for HyperShift"
+   ```
+
+2. **Search related to a Jira issue:**
+   ```
+   /confluence:search OCPBUGS-1234
+   ```
+
+3. **Search within a specific space:**
+   ```
+   /confluence:search "deployment runbook" --space OPS --limit 5
+   ```
+
+4. **Raw CQL query:**
+   ```
+   /confluence:search "label = architecture AND lastModified > startOfMonth(\"-3M\")"
+   ```
+
+## Arguments
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `<query>` | Yes | Natural language query, Jira issue key, or CQL expression |
+| `--space <key>` | No | Restrict search to a specific Confluence space |
+| `--limit <n>` | No | Maximum number of results (default: 10, max: 50) |
+
+## Return Value
+- Ranked list of matching Confluence pages with titles, URLs, spaces, and last-modified dates
+- Relevance summary for each result
+- Suggestions for refined searches if results are sparse
+
+## Error Handling
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| No results found | Query too specific or wrong space | Suggest broader terms or remove space filter |
+| CQL syntax error | Malformed CQL expression | Re-interpret as natural language and retry |
+| Authentication failure | MCP Atlassian server not configured | Guide user to set up Confluence credentials |
+
+## See Also
+- `confluence:create-from-jira` - Create new docs from Jira context
+- `confluence:sync-meeting-notes` - Publish meeting notes