@groupby/ai-dev 0.1.1 → 0.2.0

package/toolsets/toolsets/rzlv-flow/skills/confluence-fetch/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: confluence-fetch
+description: Pull a Confluence page into a local markdown mirror. Supports searching by keyword, pasting a URL, browsing a space, or viewing recently accessed pages. Creates a Leaf Bundle directory with sync frontmatter and converts Confluence storage format to markdown. Use when you want to download a Confluence page for local reference or editing.
+---
+
+Fetch a Confluence page and create a local markdown mirror. Provides multiple ways to find the target page (search, URL, browse, recent), downloads the content, converts from Confluence storage format to markdown, creates a Leaf Bundle directory, and populates sync frontmatter for future two-way sync.
+
+## Requirements
+
+Requires: Atlassian MCP (`atlassian-rovo`). See the rzlv-flow toolset README for setup.
+
+## Resources to Load
+
+Before executing, read these resource files:
+
+- `docs/ai/resources/fcmp-protocol.md` — follow for all Confluence read operations
+- `docs/ai/resources/confluence-file-structure.md` — Leaf Bundle pattern and dual-mode rules
+- `docs/ai/resources/sync-state-format.md` — YAML frontmatter schema for Confluence page files
+
+## Process
+
+### Step 1: Find the Document
+
+Present options for locating the page:
+
+```
+How would you like to find the Confluence page?
+1. Search by keyword
+2. Paste a Confluence URL
+3. Browse a space
+4. Show recently viewed pages
+
+Choose [1]:
+```
+
+**Option 1 — Search by keyword:**
+- Ask for search terms: "Search for:"
+- Run a Confluence search via MCP using the CQL query: `type = page AND text ~ "{keywords}"`
+- If `confirmed_project` or space is in session context, scope the search: `space = "{SPACE}" AND type = page AND text ~ "{keywords}"`
+
+**Option 2 — Paste URL:**
+- Accept a Confluence page URL.
+- Extract the page ID or space + title from the URL.
+- Fetch the page directly via MCP.
+
+**Option 3 — Browse space:**
+- Ask for the space key (or use session context).
+- Fetch the top-level pages in the space via MCP.
+- Present as a numbered list. Allow the user to drill into child pages.
+
+**Option 4 — Recently viewed:**
+- Use the MCP to fetch recently viewed pages for the current user (if the API supports it).
+- Present as a numbered list.
+
+### Step 2: Search and Select
+
+For keyword search (option 1), present results:
+
+```
+### Search Results for "{keywords}"
+| # | Title | Space | Last Updated |
+|---|-------|-------|-------------|
+| 1 | Technical Architecture | ENG | 2 days ago |
+| 2 | Auth Flow Design | ENG | 1 week ago |
+| 3 | API Gateway Overview | PLAT | 3 weeks ago |
+
+Choose a page (1-3), or "refine" to search again:
+```
+
+If no results are found, offer to refine the search or try a different approach.
+
+For URL paste (option 2) or browse (option 3), skip this step if the page is already identified.
+
+### Step 3: Choose Local Location
+
+After selecting a page, determine where to save the local mirror:
+
+```
+Where should this page be saved locally?
+1. Recommended: docs/confluence/{instance}/{space}/{page-slug}/index.md
+{IF focused_ticket EXISTS:}
+2. Under current ticket: docs/jira/.../{TICKET-KEY}/_docs/{page-slug}.md
+3. Custom path (you specify)
+
+Choose [1]:
+```
+
+**Option 1 — Recommended path:** Use the standard Confluence mirror location per `confluence-file-structure.md`. Derive the path from the page's space and title.
+
+**Option 2 — Under ticket:** If a focused ticket exists, save as a reference doc in the ticket's `_docs/` folder (this is a flat file, not a Leaf Bundle, since it's inside the Jira structure).
+
+**Option 3 — Custom path:** Accept a path from the user. If the path doesn't end with `/index.md`, create a Leaf Bundle at the specified location.
+
+### Step 4: Download and Convert
+
+1. **Fetch page content** — Use MCP to fetch the full page content, including:
+   - Title, body (storage format), version, last updated, space, parent page ID
+   - Page labels and metadata
+
+2. **Convert Confluence storage format to markdown:**
+   - Convert Confluence macros to markdown equivalents where possible
+   - Convert tables, headings, lists, links, and inline formatting
+   - Preserve code blocks with language hints
+   - Convert info/note/warning panels to blockquotes with labels
+   - Inline images: download to the Leaf Bundle directory alongside `index.md`
+
+3. **Create Leaf Bundle directory:**
+   ```
+   docs/confluence/{instance}/{space}/{page-slug}/index.md
+   ```
+
+4. **Populate frontmatter** per `sync-state-format.md`:
+   ```yaml
+   ---
+   sync:
+     confluence_page_id: "{page_id}"
+     confluence_url: "{page_url}"
+     confluence_title: "{exact page title}"
+     space: "{SPACE}"
+     parent_page_id: "{parent_id}"
+     last_synced: "{current_timestamp}"
+     version: {page_version}
+     remote_updated: "{page_last_updated}"
+
+   mode: "flexible"
+
+   source:
+     origin: "confluence-fetch"
+     linked_jira: "{TICKET-KEY if available}"
+   ---
+   ```
+
+5. **Write the markdown body** below the frontmatter.
+
+### Step 5: Quick Actions After Download
+
+```
+Page downloaded to: {relative path}
+
+Quick actions:
+1. Open the file
+{IF focused_ticket EXISTS:}
+2. Link to Jira ticket {TICKET-KEY} (add Confluence URL as comment)
+3. Edit the content (open in editor)
+{N}. Done — no further actions
+
+Choose [{N}]:
+```
+
+**Action: Link to Jira:** Add a comment to the focused ticket via MCP: `[rzlv-flow Update] Linked Confluence page: {title} — {confluence_url}`
+
+## Output Format
+
+```
+## 📥 Fetched from Confluence
+
+**Page:** {Page Title}
+**Space:** {SPACE} | **Version:** {version} | **Last Updated:** {date}
+**Confluence URL:** {confluence_url}
+**Local Path:** {relative path to index.md}
+
+### Sync Status
+- **Page ID:** {confluence_page_id}
+- **Version:** {version}
+- **Synced at:** {timestamp}
+- **Mode:** flexible (fetched from Confluence)
+
+### Content Preview
+{First 5 lines of the converted markdown content}
+...
+
+### Quick Actions
+{Numbered action list from Step 5}
+```
+
+## Error Handling
+
+- If MCP is unavailable, exit with: "Atlassian MCP not configured. See the rzlv-flow toolset README for setup."
+- If the page is not found (404), inform the user and offer to search again.
+- If the space is inaccessible (403), inform the user and suggest checking permissions.
+- If the local path already exists, ask: "A local mirror already exists at {path}. Overwrite with fresh content? (y/n)"
+  - If yes, run FCMP: fetch remote, compare against local, merge if local has changes, then overwrite.
+  - If no, suggest an alternative path.
+
+## Session Context
+
+After running, update conversational context:
+- **last_fetched_page** — The Confluence page title and URL
+- **last_fetched_path** — The local mirror path

package/toolsets/toolsets/rzlv-flow/skills/confluence-publish/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: confluence-publish
+description: Publish a local markdown document to Confluence. Supports publishing working docs, ticket guides, or any markdown file. Creates a Leaf Bundle local mirror, converts to Confluence storage format, pushes via MCP, and optionally links back to Jira. Use when you want to publish documentation to Confluence from your local workspace.
+---
+
+Publish any local markdown document to Confluence as a new or updated page. Handles document selection, Confluence location targeting, FCMP safety checks, Leaf Bundle local mirror creation, and optional Jira back-linking — all in one flow.
+
+## Requirements
+
+Requires: Atlassian MCP (`atlassian-rovo`). See the rzlv-flow toolset README for setup.
+
+## Resources to Load
+
+Before executing, read these resource files:
+
+- `docs/ai/resources/fcmp-protocol.md` — **critical** for safe read/write against Confluence
+- `docs/ai/resources/confluence-file-structure.md` — Leaf Bundle pattern and dual-mode rules
+- `docs/ai/resources/sync-state-format.md` — YAML frontmatter schema for Confluence page files
+
+## Relationship to `atlassian-orchestrator`
+
+This skill overlaps with `atlassian-orchestrator` Mode 3b (flexible Confluence sync). The distinction:
+
+- **`confluence-publish`** — Lightweight, developer-facing. Publish a single document quickly with minimal prompts. Best for ad-hoc publishing.
+- **`atlassian-orchestrator` Mode 3** — Full structured workflow. Bulk-syncs `_docs/` folders to Confluence following epic hierarchy. Best for orchestrated documentation creation.
+
+Use this skill when the user says "publish this to Confluence" or "push this doc to Confluence." Use the orchestrator when the user says "sync all documentation" or is working within an epic structure.
+
+## Process
+
+### Step 1: Select Document
+
+Determine which document to publish. Present options based on context:
+
+```
+What would you like to publish to Confluence?
+1. Current ticket's guide (_docs/ content)
+2. Specify a file path
+3. List working docs in current ticket folder
+4. Cancel
+
+Choose [2]:
+```
+
+**Option 1 — Ticket guide:** Use `focused_ticket` from session context. Look for files in the ticket's `_docs/` folder or the parent epic's `_docs/` folder.
+
+**Option 2 — File path:** Accept a relative or absolute path to any markdown file.
+
+**Option 3 — List working docs:** List `.md` files in the focused ticket's directory and its `_work/` folder. Present as a numbered list for selection.
+
+**Option 4 — Cancel:** Exit without action.
+
+Validate the selected file exists and is a markdown file.
+
+### Step 2: Choose Confluence Location
+
+Ask the user where to publish:
+
+```
+Where should this page be published in Confluence?
+1. Under the epic's Confluence section ({EPIC-KEY} — {epic summary})
+2. Under the current ticket ({TICKET-KEY} — {ticket summary})
+3. Custom parent page (you specify space + parent)
+4. Space root (top-level page in a space)
+
+Choose [1]:
+```
+
+**Option 1 — Under epic:** Use the epic's Confluence hierarchy. Determine the parent page from epic metadata or the orchestrator's prior sync state.
+
+**Option 2 — Under ticket:** Create the page as a child of the ticket's Confluence page (if one exists) or under the epic with the ticket key in the title.
+
+**Option 3 — Custom parent:** Ask for the Confluence space key and parent page title or ID.
+
+**Option 4 — Space root:** Ask for just the Confluence space key. The page will be a top-level page in that space.
+
+For options 1–2, use `confirmed_project` and instance from session context. If unavailable, ask for the space key.
+
+### Step 3: FCMP Check
+
+Before creating or updating the Confluence page:
+
+1. **Search** for an existing page with the same title in the target space via MCP.
+2. If a matching page exists:
+   - **FETCH** the current page content and version.
+   - **COMPARE** against the local document.
+   - Show the diff to the user and ask: "A page with this title already exists. Update it? (y/n)"
+   - If updating, proceed with FCMP merge.
+3. If no matching page exists, proceed to create.
+
+### Step 4: Create Leaf Bundle and Publish
+
+1. **Create local mirror** — Create the Leaf Bundle directory structure following `confluence-file-structure.md`:
+   ```
+   docs/confluence/{instance}/{space}/{path}/{page-slug}/index.md
+   ```
+   The `{page-slug}` is derived from the page title (lowercase, hyphens for spaces).
+
+2. **Add frontmatter** — Populate the `index.md` with sync frontmatter per `sync-state-format.md`:
+   - Set `mode: "flexible"` (or `"structured"` if publishing from `_docs/`)
+   - Set `sync.confluence_title` to the page title
+   - Set `sync.space` to the target space key
+   - Set `source.origin` or `source.doc_type` as appropriate
+   - Leave `sync.confluence_page_id` empty (populated after push)
+
+3. **Convert to Confluence format** — Transform the markdown content to Confluence storage format for the MCP push.
+
+4. **Push via MCP** — Create or update the page using MCP:
+   - For new pages: create with title, space, parent page ID, and converted content.
+   - For updates: include the version number for optimistic locking.
+
+5. **Update local frontmatter** — After successful push, update the `index.md` frontmatter:
+   - Set `sync.confluence_page_id` from the API response
+   - Set `sync.confluence_url` from the API response
+   - Set `sync.version` from the API response
+   - Set `sync.last_synced` to the current timestamp
+   - Set `sync.remote_updated` to the current timestamp
+
+### Step 5: Optional Jira Linking
+
+If a focused ticket or linked Jira ticket exists in session context:
+
+```
+Link this page to Jira ticket {TICKET-KEY}?
+1. Add link as a Jira comment
+2. Add link in the ticket description
+3. Both (comment + description)
+4. Skip — don't link to Jira
+
+Choose [4]:
+```
+
+**Option 1 — Comment:** Add a Jira comment via MCP: `[rzlv-flow Update] Published Confluence page: {title} — {confluence_url}`
+
+**Option 2 — Description:** Append the Confluence URL to the ticket description field. Follow FCMP protocol for the update.
+
+**Option 3 — Both:** Execute both options 1 and 2.
+
+**Option 4 — Skip:** No Jira linking.
+
+## Output Format
+
+```
+## 📄 Published to Confluence
+
+**Page:** {Page Title}
+**Space:** {SPACE} | **Parent:** {parent page title}
+**URL:** {confluence_url}
+**Local Mirror:** {relative path to index.md}
+
+### Sync Status
+- **Page ID:** {confluence_page_id}
+- **Version:** {version}
+- **Synced at:** {timestamp}
+
+{IF JIRA LINKED:}
+### Jira Link
+- Linked to {TICKET-KEY} via {comment | description | both}
+
+### Next Steps
+{IF page was newly created:}
+- Edit the local mirror at `{path}` and re-run this skill to sync changes
+{IF page was updated:}
+- Page updated successfully — local mirror is in sync
+```
+
+## Error Handling
+
+- If MCP is unavailable, exit with: "Atlassian MCP not configured. See the rzlv-flow toolset README for setup."
+- If the target space doesn't exist or is inaccessible, inform the user and ask for a different space.
+- If an optimistic locking conflict occurs (409), re-run FCMP from Fetch and retry.
+- If the parent page doesn't exist, offer to create the page at the space root instead.
+
+## Session Context
+
+After running, update conversational context:
+- **last_published_page** — The Confluence page title and URL
+- **last_published_path** — The local mirror path

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