@groupby/ai-dev 0.2.1 → 0.3.0

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

@@ -1,331 +0,0 @@
-# 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/toolsets/rzlv-flow/resources/jira-file-structure.md

@@ -1,177 +0,0 @@
-# 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.