@groupby/ai-dev 0.1.1 → 0.2.1

package/toolsets/rzlv-flow/resources/fcmp-protocol.md

@@ -0,0 +1,331 @@
+# FCMP Protocol — Atlassian Sync Instructions
+
+> This resource is referenced by rzlv-flow skills. Skills should load this document at the start of any workflow that reads from or writes to Jira or Confluence.
+
+**Pattern:** Fetch-Compare-Merge-Push (FCMP)
+
+---
+
+## Overview
+
+This document defines the **standardized sync instruction patterns** that all skills must follow when interacting with Jira and Confluence. These are not code libraries — they are instruction patterns that skills execute during their workflows.
+
+## Core Principle: Never Blind Write
+
+> **CRITICAL:** Skills must NEVER write to Jira/Confluence without first fetching the current remote state. This prevents data loss from concurrent edits.
+
+---
+
+## The FCMP Protocol
+
+### 1. FETCH — Get Remote State
+
+Before any modification, fetch the current state:
+
+```yaml
+fetch_instructions:
+  jira_ticket:
+    - Call: mcp_atlassian-rovo_fetch(id: "ari:cloud:jira:{cloudId}:issue/{issueId}")
+    - Extract: summary, description, status, comments, updated_at, version
+    - Store: remote_state.jira.{ticket_key}
+
+  confluence_page:
+    - Call: mcp_atlassian-rovo_fetch(id: "ari:cloud:confluence:{cloudId}:page/{pageId}")
+    - Extract: title, body, version, updated_at
+    - Store: remote_state.confluence.{page_id}
+
+  on_fetch_failure:
+    - Log: "⚠️ Could not fetch remote state for {resource}"
+    - Action: STOP and prompt user
+    - Never: Proceed with blind write
+```
+
+### 2. COMPARE — Detect Changes
+
+Compare local changes against fetched remote state:
+
+```yaml
+compare_instructions:
+  check_for_conflicts:
+    - Compare: local.updated_at vs remote.updated_at
+    - Compare: local.version vs remote.version
+    - If remote is newer: CONFLICT DETECTED
+
+  conflict_scenarios:
+    no_conflict:
+      condition: "remote.version == local.last_known_version"
+      action: "Proceed to PUSH"
+
+    remote_changed:
+      condition: "remote.version > local.last_known_version"
+      action: "Proceed to MERGE"
+
+    both_changed:
+      condition: "local has changes AND remote has changes"
+      action: "Proceed to MERGE with user confirmation"
+
+  output_to_user:
+    - Show: Side-by-side diff (local vs remote)
+    - Highlight: Conflicting sections
+    - Ask: "Remote has changed. How would you like to proceed?"
+```
+
+### 3. MERGE — Resolve Conflicts
+
+When conflicts are detected, guide the user through resolution:
+
+```yaml
+merge_instructions:
+  strategies:
+    auto_merge:
+      when: "Changes are in different sections"
+      action: "Combine both changes automatically"
+      confirm: "Auto-merged changes in different sections. Review?"
+
+    prefer_remote:
+      when: "User selects 'Keep remote'"
+      action: "Discard local changes, use remote"
+      confirm: "Local changes will be discarded. Confirm?"
+
+    prefer_local:
+      when: "User selects 'Keep local'"
+      action: "Overwrite remote with local"
+      confirm: "Remote changes will be overwritten. Confirm?"
+
+    manual_merge:
+      when: "User selects 'Manual merge'"
+      action: "Present both versions for manual editing"
+      output: "Combined document for user editing"
+
+  merge_output:
+    - Create: merged_content with resolved conflicts
+    - Update: local.version = remote.version
+    - Log: "Merge completed: {strategy_used}"
+```
+
+### 4. PUSH — Write to Remote
+
+Only after successful fetch-compare-merge cycle:
+
+```yaml
+push_instructions:
+  pre_push_checklist:
+    - Verify: fetch completed successfully
+    - Verify: no unresolved conflicts
+    - Verify: user confirmed changes (if required)
+
+  jira_update:
+    - Call: Appropriate MCP update tool
+    - Include: version field for optimistic locking
+    - On success: Update local.version, local.synced_at
+    - On conflict (409): Re-run FETCH-COMPARE-MERGE
+
+  confluence_update:
+    - Call: MCP confluence update tool
+    - Include: version for conflict detection
+    - On success: Update local frontmatter
+    - On conflict: Re-run FETCH-COMPARE-MERGE
+
+  post_push:
+    - Update local file: Set status to "synced"
+    - Update local file: Store new version number
+    - Log: "✓ Synced {resource} at {timestamp}"
+```
+
+---
+
+## Local File Storage Protocol
+
+The same FCMP pattern applies to local file operations to prevent data loss:
+
+### Local File Sync Rules
+
+```yaml
+local_file_protocol:
+  before_write:
+    - Check: File exists?
+    - If exists: Read current content
+    - Compare: Local changes vs file content
+    - If different: Prompt user before overwrite
+
+  file_locking:
+    - Use: YAML frontmatter version field
+    - Format:
+      ```yaml
+      ---
+      sync:
+        local_version: 3
+        last_modified: "2025-12-09T10:30:00Z"
+        modified_by: "skill:jira-wrap-sync"
+      ---
+      ```
+
+  conflict_detection:
+    - Compare: frontmatter version vs expected version
+    - If mismatch: Another process modified file
+    - Action: Show diff, ask user to resolve
+
+  safe_write_pattern:
+    - Read: Current file content
+    - Validate: Version matches expected
+    - Write: New content with incremented version
+    - Verify: Write succeeded
+```
+
+---
+
+## Skill Integration Requirements
+
+### For skills that create/update Jira or Confluence (e.g. jira-wrap-sync, atlassian-orchestrator)
+
+```yaml
+create_update_sync_requirements:
+  on_jira_create:
+    - Not applicable (new resource, no conflict possible)
+    - After create: Store returned key/id in local file
+
+  on_jira_update:
+    - MUST: Follow full FCMP protocol
+    - MUST: Show diff before update
+    - MUST: Handle 409 conflicts gracefully
+
+  on_confluence_create:
+    - After create: Update local frontmatter with page_id, url
+
+  on_confluence_update:
+    - MUST: Follow full FCMP protocol
+    - MUST: Preserve user edits in Confluence
+```
+
+### For skills that modify ticket state (e.g. jira-status, jira-comment, jira-wrap-sync)
+
+```yaml
+ticket_state_sync_requirements:
+  on_status_change:
+    - FETCH: Current ticket state
+    - COMPARE: Status hasn't changed since last fetch
+    - PUSH: New status
+
+  on_comment_add:
+    - FETCH: Current comments (check for new ones)
+    - INFORM: Show any new comments from others
+    - PUSH: Add new comment
+
+  on_description_update:
+    - FULL FCMP: Description is high-conflict field
+    - ALWAYS: Show diff before update
+    - ALWAYS: Require user confirmation
+```
+
+### For skills that create documents (e.g. context-analyst)
+
+```yaml
+document_creation_sync_requirements:
+  primary_operation: "Create only (transcripts → new docs)"
+
+  on_context_doc_create:
+    - Check: Target path exists?
+    - If exists: WARN user, ask to overwrite or rename
+    - Create: New context document
+
+  on_handoff_to_pm:
+    - Verify: Context doc saved successfully
+    - Verify: Path is accessible
+    - Log: Handoff details for traceability
+```
+
+---
+
+## Error Handling Patterns
+
+```yaml
+error_handling:
+  connection_lost:
+    - Log: "⚠️ Connection to Atlassian lost"
+    - Action: Keep local changes with status "pending_sync"
+    - Inform: "Changes saved locally. Sync when connection restored."
+
+  auth_expired:
+    - Detect: 401 response from MCP
+    - Action: Prompt "Session expired. Please re-authenticate."
+    - Preserve: All local changes
+
+  rate_limited:
+    - Detect: 429 response from MCP
+    - Action: Exponential backoff (1s, 2s, 4s, 8s, max 60s)
+    - Inform: "Rate limited. Retrying in {n} seconds..."
+
+  version_conflict:
+    - Detect: 409 response or version mismatch
+    - Action: Restart FCMP from FETCH
+    - Inform: "Conflict detected. Refreshing remote state..."
+
+  partial_failure:
+    - Context: Batch operation with some failures
+    - Action: Mark successful items as "synced"
+    - Action: Mark failed items as "sync_failed"
+    - Report: "Synced {n}/{total}. {m} failed. See details."
+```
+
+---
+
+## Sync Status Values
+
+All local files tracking Atlassian resources use these status values:
+
+```yaml
+sync_status:
+  draft:
+    meaning: "Created locally, never synced to Atlassian"
+    action: "Full create operation needed"
+
+  synced:
+    meaning: "Local matches remote (as of last sync)"
+    action: "No action needed unless local changes"
+
+  modified:
+    meaning: "Local changes since last sync"
+    action: "FCMP protocol required before push"
+
+  pending_sync:
+    meaning: "Ready to sync, waiting for connection/confirmation"
+    action: "Push when ready"
+
+  sync_failed:
+    meaning: "Attempted sync failed"
+    action: "Review error, retry when resolved"
+
+  conflict:
+    meaning: "Both local and remote changed"
+    action: "Manual merge required"
+```
+
+---
+
+## Quick Reference Card
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    FCMP PROTOCOL                            │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. FETCH    →  Get current remote state                    │
+│                 Never skip this step!                       │
+│                                                             │
+│  2. COMPARE  →  Local vs Remote                             │
+│                 Detect conflicts early                      │
+│                                                             │
+│  3. MERGE    →  Resolve any conflicts                       │
+│                 User decides on conflicts                   │
+│                                                             │
+│  4. PUSH     →  Write to remote                             │
+│                 Only after 1-2-3 complete                   │
+│                                                             │
+├─────────────────────────────────────────────────────────────┤
+│  ⚠️  NEVER do blind writes                                  │
+│  ⚠️  ALWAYS show diffs for updates                          │
+│  ⚠️  ALWAYS preserve user's remote edits                    │
+│  ✓  Log all sync operations                                 │
+│  ✓  Handle errors gracefully                                │
+└─────────────────────────────────────────────────────────────┘
+```

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

@@ -0,0 +1,177 @@
+# Jira File Structure — Unified Hierarchy
+
+**Pattern:** Shared Hierarchical Structure with Clear Ownership
+
+---
+
+## Overview
+
+All rzlv-flow skills that interact with Jira use the **same hierarchical structure** in `docs/jira/{instance}/{project}/`. This ensures:
+
+- Single source of truth for sync state
+- Natural parent-child navigation
+- No duplicate files or conflicting structures
+- Clear ownership rules within each ticket folder
+
+---
+
+## Directory Structure
+
+```
+docs/jira/{instance}/{project}/
+│
+├── epic-name/                           # Epic folder (kebab-case)
+│   ├── epic.md                          # Epic sync state + metadata
+│   ├── _docs/                           # Generated documentation (orchestrator)
+│   │   ├── technical-architecture.md
+│   │   ├── decisions.md
+│   │   └── strategic-context.md
+│   │
+│   └── stories/
+│       ├── PROJ-123/                    # Story folder
+│       │   ├── PROJ-123.md              # Story sync state (shared)
+│       │   ├── _docs/                   # Generated story docs (orchestrator)
+│       │   ├── _work/                   # Developer notes (gitignored, ephemeral)
+│       │   │   ├── notes.md
+│       │   │   ├── scratch.md
+│       │   │   └── checklist.md
+│       │   │
+│       │   └── subtasks/
+│       │       └── PROJ-124/            # Subtask folder
+│       │           ├── PROJ-124.md      # Subtask sync state
+│       │           └── _work/           # Subtask dev notes
+│       │
+│       └── PROJ-125/
+│           └── PROJ-125.md
+│
+├── another-epic/
+│   └── ...
+│
+└── _orphans/                            # Stories without epic (yet)
+    └── PROJ-200/
+        ├── PROJ-200.md                  # Story sync state
+        └── _work/                       # Developer notes
+```
+
+### Hierarchy Rules
+
+| Type | Path Pattern |
+|------|-------------|
+| Epic | `{epic-name}/epic.md` |
+| Story | `{epic-name}/stories/{TICKET-KEY}/{TICKET-KEY}.md` |
+| Subtask | `{epic-name}/stories/{PARENT-KEY}/subtasks/{TICKET-KEY}/{TICKET-KEY}.md` |
+| Orphan | `_orphans/{TICKET-KEY}/{TICKET-KEY}.md` |
+
+---
+
+## File Ownership Rules
+
+### 1. `{ticket}.md` — Sync State (Shared)
+
+- **Updated by:** Multiple skills via FCMP protocol
+- **Contains:** Jira metadata, sync state, description, acceptance criteria
+- **Format:** Markdown with YAML frontmatter (see `sync-state-format.md`)
+
+### 2. `_docs/` — Generated Documentation (Orchestrator Only)
+
+- **Created by:** Orchestrator-type skills (e.g. `atlassian-orchestrator`) during epic/story generation
+- **Contains:** Technical architecture, decisions, strategic context
+- **Read by:** Developer workflow skills (e.g. `jira-ticket-focus`, `jira-wrap-sync`) for requirements context
+
+### 3. `_work/` — Ephemeral Developer Workspace (Developer Skills Only)
+
+- **Created by:** Developer workflow skills (e.g. `jira-ticket-focus`) when a developer focuses on a ticket
+- **Contains:** Scratch notes, checklists, local context
+- **Gitignored:** Yes (via `**/_work/`)
+- **Never synced:** Local developer workspace only
+
+### 4. `subtasks/` — Hierarchy (Shared)
+
+- **Created by:** Any skill when subtasks are detected or requested
+- **Contains:** Subtask folders following the same structure
+
+---
+
+## Ownership Summary
+
+| Path | Owner | Purpose | Synced to Atlassian | Gitignored |
+|------|-------|---------|---------------------|------------|
+| `{ticket}.md` | Shared | Sync state | Yes | No |
+| `_docs/` | Orchestrator skills | Generated docs | No | No |
+| `_work/` | Developer workflow skills | Dev notes | No | Yes |
+| `subtasks/` | Shared | Hierarchy | Partial | No |
+
+---
+
+## Smart Creation Rules
+
+### Rule 1: Epic Structure Exists
+
+**Scenario:** A skill focuses on `PROJ-123` and the epic structure already exists.
+
+**Action:**
+```
+docs/jira/{instance}/{project}/user-authentication/stories/PROJ-123/
+  ├── PROJ-123.md          # Read existing sync state
+  └── _work/               # Create if missing
+      └── notes.md         # Create developer workspace
+```
+
+### Rule 2: Epic Missing (Orphan Story)
+
+**Scenario:** A skill focuses on `PROJ-123` but no epic structure exists yet.
+
+**Action:**
+```
+docs/jira/{instance}/{project}/_orphans/PROJ-123/
+  ├── PROJ-123.md          # Create with sync state
+  └── _work/
+      └── notes.md
+```
+
+When the epic structure is later created (e.g. by `atlassian-orchestrator`), the story is moved from `_orphans/` to its proper location in the epic hierarchy.
+
+### Rule 3: Parent Requested
+
+**Scenario:** Developer asks to load the parent ticket for `PROJ-123`.
+
+**Action:**
+1. Fetch parent ticket (e.g. `PROJ-120` epic) from Jira
+2. Create epic structure: `docs/jira/{instance}/{project}/user-authentication/`
+3. Move `PROJ-123` from `_orphans/` to `user-authentication/stories/PROJ-123/`
+4. Update `PROJ-123.md` frontmatter: `parent: "../../epic.md"`
+
+### Rule 4: Subtasks Requested
+
+**Scenario:** Developer asks to load subtasks for `PROJ-123`.
+
+**Action:**
+1. Fetch subtasks from Jira
+2. Create `PROJ-123/subtasks/` folder
+3. For each subtask, create `subtasks/PROJ-124/PROJ-124.md`
+4. Set parent reference: `parent: "../../PROJ-123.md"`
+
+---
+
+## FCMP Protocol Integration
+
+All skills MUST follow the FCMP protocol when updating `{ticket}.md`:
+
+1. **FETCH:** Read current `{ticket}.md`, extract `sync.version`
+2. **COMPARE:** Fetch from Jira, compare `version` field
+3. **MERGE:** If mismatch, resolve conflict with user
+4. **PUSH:** Update Jira with new version, update local file
+
+See `fcmp-protocol.md` for full protocol details.
+
+---
+
+## Gitignore
+
+Add to your project's `.gitignore`:
+
+```
+**/_work/
+```
+
+This ensures developer workspace folders are never committed to version control.