@groupby/ai-dev 0.1.0 → 0.2.0

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

@@ -0,0 +1,285 @@
+# Confluence File Structure — Local Page Mirrors
+
+**Pattern:** Leaf Bundle 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.
+
+---
+
+## Leaf Bundle Pattern
+
+Every Confluence page is stored as a **directory** containing an `index.md` file — never as a standalone `.md` file. This is called the Leaf Bundle pattern.
+
+### Why Folders, Not Files?
+
+- **Child pages** — A Confluence page can have child pages. The folder naturally represents this hierarchy; child pages become subdirectories.
+- **Assets** — Pages may include attachments, images, or diagrams. These are stored alongside `index.md` in the same folder.
+- **Hierarchy expansion** — New child pages can be added without restructuring. A flat file cannot grow into a parent.
+
+### DO NOT / DO
+
+```
+❌ DO NOT create flat files:
+docs/confluence/rezolve/ENG/strategic-context.md
+
+✅ DO create Leaf Bundle directories:
+docs/confluence/rezolve/ENG/strategic-context/index.md
+```
+
+This rule applies to **all** Confluence page mirrors, in both structured and flexible modes.
+
+---
+
+## 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/
+        │   └── index.md
+        ├── technical-architecture/
+        │   └── index.md
+        ├── decisions/
+        │   └── index.md
+        ├── strategic-context/
+        │   └── index.md
+        ├── research-and-findings/         # Created only if relevant content exists
+        │   └── index.md
+        ├── assumptions/                   # Created only if relevant content exists
+        │   └── index.md
+        └── implementation-guidance/
+            └── index.md
+```
+
+### Page Types
+
+| Page Type | Folder | Source | Description |
+|-----------|--------|--------|-------------|
+| Initiative Overview | `index.md` (at initiative root) | Initiative metadata | Top-level overview: goals, epic breakdown, navigation |
+| Overview | `overview/index.md` | Epic `_docs/` | High-level epic overview and goals |
+| Technical Architecture | `technical-architecture/index.md` | Epic `_docs/` | Architecture decisions and technical design |
+| Decisions | `decisions/index.md` | Epic `_docs/` | Decision log and rationale |
+| Strategic Context | `strategic-context/index.md` | Epic `_docs/` | Business context and strategic alignment |
+| Research & Findings | `research-and-findings/index.md` | Epic `_docs/` | User research, discoveries, and clarifications* |
+| Assumptions | `assumptions/index.md` | Epic `_docs/` | Assumptions with confidence levels and validation status* |
+| Implementation Guidance | `implementation-guidance/index.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}/
+        └── index.md
+```
+
+No predefined structure beyond the Leaf Bundle requirement — 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`)
+
+---
+
+## Confluence Link Format
+
+When constructing Confluence URLs:
+
+- Replace spaces in page titles with `+`
+- Use the `/wiki/display/{SPACE}/{Title}` format for display links
+- Use the `/wiki/spaces/{SPACE}/pages/{pageId}` format for direct links
+
+Example: `https://company.atlassian.net/wiki/display/ENG/Technical+Architecture`
+
+---
+
+## Page File Format
+
+Each local Confluence mirror file (`index.md` inside a Leaf Bundle directory) uses YAML frontmatter for sync metadata:
+
+```yaml
+---
+sync:
+  confluence_page_id: "123456789"
+  confluence_url: "https://company.atlassian.net/wiki/spaces/ENG/pages/123456789"
+  confluence_title: "Technical Architecture"
+  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"
+  bmad_docs_referenced:
+    - "docs/jira/rezolve/PROJ/PROJ-120-user-auth/_docs/technical-architecture.md"
+  jira_initiative_key: "PROJ-100"
+
+  # For flexible mode
+  # origin: "manual"
+  # linked_jira: "PROJ-123"
+---
+
+# Page Title
+
+Page content in markdown, converted to Confluence storage format during sync.
+```
+
+### Frontmatter Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `sync.confluence_page_id` | string | After first sync | Confluence page ID |
+| `sync.confluence_url` | string | After first sync | Full page URL |
+| `sync.confluence_title` | string | Yes | Exact title as it appears in Confluence (used for page lookups) |
+| `sync.space` | string | Yes | Confluence space key |
+| `sync.parent_page_id` | string | Yes | Parent page ID in Confluence |
+| `sync.last_synced` | ISO8601 | After first sync | Last sync timestamp |
+| `sync.version` | number | After first sync | Confluence page version for optimistic locking |
+| `sync.remote_updated` | ISO8601 | After first sync | Last remote change timestamp |
+| `mode` | enum | Yes | `structured` or `flexible` |
+| `source.jira_ticket` | string | Structured | Associated Jira ticket key |
+| `source.doc_type` | string | Structured | Page type (overview, technical-architecture, decisions, strategic-context) |
+| `source.generated_from` | string | Structured | Path to the `_docs/` source file |
+| `source.bmad_docs_referenced` | string[] | No | BMAD source docs used to generate the page (traceability) |
+| `source.jira_initiative_key` | string | No | Related Jira initiative key (cross-linking) |
+| `source.origin` | string | Flexible | Origin skill or `manual` |
+| `source.linked_jira` | string | Flexible | Optionally linked Jira ticket |
+
+> **Note on field naming:** The source rzlv-flow repo uses flat root-level fields (e.g. `confluence_space_key: "ENG"`). This toolset uses nested fields under `sync.*` for consistency with the Jira file schema. Both conventions represent the same data; skills should follow the nested format documented here.
+
+### Post-Sync Frontmatter Example
+
+**Before first sync (draft state):**
+```yaml
+---
+sync:
+  confluence_title: "Technical Architecture"
+  space: "ENG"
+  parent_page_id: "987654321"
+mode: "structured"
+source:
+  jira_ticket: "PROJ-120"
+  doc_type: "technical-architecture"
+  generated_from: "docs/jira/rezolve/PROJ/PROJ-120-user-auth/_docs/technical-architecture.md"
+---
+```
+
+**After first sync (populated by sync operation):**
+```yaml
+---
+sync:
+  confluence_page_id: "123456789"
+  confluence_url: "https://company.atlassian.net/wiki/spaces/ENG/pages/123456789"
+  confluence_title: "Technical Architecture"
+  space: "ENG"
+  parent_page_id: "987654321"
+  last_synced: "2025-12-11T10:30:00Z"
+  version: 1
+  remote_updated: "2025-12-11T10:30:00Z"
+mode: "structured"
+source:
+  jira_ticket: "PROJ-120"
+  doc_type: "technical-architecture"
+  generated_from: "docs/jira/rezolve/PROJ/PROJ-120-user-auth/_docs/technical-architecture.md"
+---
+```
+
+See `sync-state-format.md` for the full frontmatter schema and worked examples.

package/toolsets/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/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/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/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/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.}