@groupby/ai-dev 0.2.1 → 0.3.0

package/toolsets/toolsets/rzlv-flow/resources/sync-state-format.md

@@ -1,318 +0,0 @@
-# Sync State Format — YAML Frontmatter Schema
-
-This document defines the YAML frontmatter schema used in local Jira ticket files and Confluence page files. All rzlv-flow skills that read or write these files must follow this format.
-
----
-
-## Jira Ticket File Schema
-
-Every ticket file (`{TICKET-KEY}.md`) uses this frontmatter format for safe FCMP sync:
-
-```yaml
----
-sync:
-  jira_key: "PROJ-123"                    # Jira ticket key
-  jira_ari: "ari:cloud:jira:{cloudId}:issue/{issueId}"  # Atlassian Resource Identifier
-  status: "In Progress"                   # Current Jira status
-  assignee: "john.doe@company.com"        # Assignee email
-  priority: "High"                        # Priority level
-  story_points: 3                         # Story point estimate
-  last_synced: "2025-12-11T10:30:00Z"     # When local was last synced with remote
-  version: 42                             # Jira version for optimistic locking
-  remote_updated: "2025-12-11T09:15:00Z"  # Last remote change timestamp
-
-structure:
-  type: "story"                           # epic | story | subtask | task | bug
-  parent: "../epic.md"                    # Relative path to parent file
-  epic: "PROJ-120"                        # Epic key
-
-agile_companion:                          # Developer workflow skill metadata (optional)
-  last_focused: "2025-12-11T08:00:00Z"    # Last time developer focused on this ticket
-  working_branch: "feature/PROJ-123"      # Associated git branch
-  local_commits: 3                        # Uncommitted/unpushed commit count
-
-orchestrator:                             # Orchestrator skill metadata (optional)
-  generated_at: "2025-12-10T14:00:00Z"    # When the structure was generated
-  confluence_page_id: "123456789"          # Linked Confluence page
-  confluence_url: "https://company.atlassian.net/wiki/spaces/ENG/pages/123456789"
----
-```
-
-### Field Reference
-
-#### `sync` — Core Sync Metadata
-
-| Field | Type | Required | Written By | Description |
-|-------|------|----------|------------|-------------|
-| `jira_key` | string | Yes | Any skill on create/fetch | Jira ticket key (e.g. `PROJ-123`) |
-| `jira_ari` | string | Yes | Any skill on create/fetch | Atlassian Resource Identifier for API calls |
-| `status` | string | Yes | Updated on every sync | Current Jira workflow status |
-| `assignee` | string | No | Updated on every sync | Assignee email address |
-| `priority` | string | No | Updated on every sync | Ticket priority level |
-| `story_points` | number | No | Updated on every sync | Story point estimate |
-| `last_synced` | ISO8601 | Yes | Updated on every sync | Timestamp of last successful sync |
-| `version` | number | Yes | Updated on every sync | Jira version field for optimistic locking (FCMP) |
-| `remote_updated` | ISO8601 | Yes | Updated on every sync | Timestamp of last remote change |
-
-#### `structure` — Hierarchy Metadata
-
-| Field | Type | Required | Written By | Description |
-|-------|------|----------|------------|-------------|
-| `type` | enum | Yes | Any skill on create | `epic`, `story`, `subtask`, `task`, or `bug` |
-| `parent` | string | No | Set on create or parent load | Relative path to parent ticket file |
-| `epic` | string | No | Set on create or parent load | Epic key this ticket belongs to |
-
-#### `agile_companion` — Developer Workflow Extensions
-
-| Field | Type | Required | Written By | Description |
-|-------|------|----------|------------|-------------|
-| `last_focused` | ISO8601 | No | `jira-ticket-focus` | Last time the developer focused on this ticket |
-| `working_branch` | string | No | `jira-ticket-focus` | Detected or created git branch |
-| `local_commits` | number | No | `jira-wrap-sync` | Count of local commits since last sync |
-
-#### `orchestrator` — Orchestrator Extensions
-
-| Field | Type | Required | Written By | Description |
-|-------|------|----------|------------|-------------|
-| `generated_at` | ISO8601 | No | `atlassian-orchestrator` | When the ticket structure was generated |
-| `confluence_page_id` | string | No | `atlassian-orchestrator` | Linked Confluence page ID |
-| `confluence_url` | string | No | `atlassian-orchestrator` | URL to linked Confluence page |
-
----
-
-## Jira Ticket File Body
-
-Below the frontmatter, the markdown body follows this structure:
-
-```markdown
-# Implement User Authentication API
-
-## Description
-
-{Description from Jira — synced bidirectionally}
-
-## Acceptance Criteria
-
-- [ ] API endpoint accepts username/password
-- [ ] Returns JWT token on success
-- [ ] Returns 401 on invalid credentials
-
-## Technical Notes
-
-{Links to _docs/ or inline notes — optional}
-```
-
----
-
-## Confluence Page File Schema
-
-Confluence mirror files use this frontmatter:
-
-```yaml
----
-sync:
-  confluence_page_id: "123456789"          # Confluence page ID
-  confluence_url: "https://..."            # Full page URL
-  confluence_title: "Page Title"           # Exact title as it appears in Confluence
-  space: "ENG"                             # Confluence space key
-  parent_page_id: "987654321"              # Parent page ID in Confluence
-  last_synced: "2025-12-11T10:30:00Z"      # Last sync timestamp
-  version: 5                               # Confluence page version
-  remote_updated: "2025-12-11T09:15:00Z"   # Last remote change
-
-mode: "structured"                         # structured | flexible
-
-source:
-  # Structured mode fields
-  jira_ticket: "PROJ-120"                  # Associated Jira ticket (optional)
-  doc_type: "technical-architecture"       # overview | technical | decisions | strategic
-  generated_from: "docs/jira/.../technical-architecture.md"  # Source _docs/ file
-  bmad_docs_referenced:                    # BMAD source docs used (traceability)
-    - "docs/jira/.../technical-architecture.md"
-  jira_initiative_key: "PROJ-100"          # Related Jira initiative (cross-linking)
-
-  # Flexible mode fields (use instead of structured fields)
-  # origin: "manual"                       # manual | context-analyst | other skill
-  # linked_jira: "PROJ-123"               # Optional linked Jira ticket
-
-orchestrator:
-  generated_at: "2025-12-10T14:00:00Z"     # When generated (structured mode)
-  auto_sync: true                          # Whether to auto-sync on updates
----
-```
-
----
-
-## Sync Status Values
-
-The `sync.status` field for tracking local file sync state is separate from the Jira workflow `status`. When needed, skills track sync state using these values (typically in a `sync_status` field or inferred from `last_synced` vs `remote_updated`):
-
-| Status | Meaning | Action Required |
-|--------|---------|-----------------|
-| `draft` | Created locally, never synced to Atlassian | Full create operation needed |
-| `synced` | Local matches remote (as of last sync) | No action unless local changes |
-| `modified` | Local changes since last sync | FCMP protocol required before push |
-| `pending_sync` | Ready to sync, waiting for connection/confirmation | Push when ready |
-| `sync_failed` | Attempted sync failed | Review error, retry when resolved |
-| `conflict` | Both local and remote changed | Manual merge required |
-
-See `fcmp-protocol.md` for full details on each status and the transitions between them.
-
----
-
-## Complete Example: Synced Ticket File
-
-```yaml
----
-sync:
-  jira_key: "AIP-247"
-  jira_ari: "ari:cloud:jira:a1b2c3d4:issue/10247"
-  status: "In Progress"
-  assignee: "jane.smith@company.com"
-  priority: "High"
-  story_points: 5
-  last_synced: "2025-12-11T10:30:00Z"
-  version: 12
-  remote_updated: "2025-12-11T09:15:00Z"
-
-structure:
-  type: "story"
-  parent: "../../epic.md"
-  epic: "AIP-200"
-
-agile_companion:
-  last_focused: "2025-12-11T08:00:00Z"
-  working_branch: "feature/AIP-247-auth-api"
-  local_commits: 2
-
-orchestrator:
-  generated_at: "2025-12-08T14:00:00Z"
-  confluence_page_id: "456789012"
-  confluence_url: "https://rezolve.atlassian.net/wiki/spaces/ENG/pages/456789012"
----
-
-# Implement User Authentication API
-
-## Description
-
-Build a REST API endpoint for user authentication that accepts username/password credentials and returns a JWT token. Must integrate with the existing user store and support rate limiting.
-
-## Acceptance Criteria
-
-- [ ] POST `/api/auth/login` accepts `{ username, password }`
-- [ ] Returns `{ token, expiresIn }` on valid credentials
-- [ ] Returns 401 with error message on invalid credentials
-- [ ] Rate limited to 5 attempts per minute per IP
-- [ ] JWT tokens expire after 24 hours
-
-## Technical Notes
-
-- See `_docs/technical-architecture.md` for auth flow diagram
-- Uses existing `UserService` for credential validation
-- Token signing key stored in environment variables
-```
-
----
-
-## Complete Example: Synced Confluence Page (Structured Mode)
-
-This example shows a Confluence page mirror created via the `atlassian-orchestrator` skill from an epic's `_docs/` folder. The file lives at:
-
-```
-docs/confluence/rezolve/ENG/platform-initiative/user-authentication/technical-architecture/index.md
-```
-
-Note the **Leaf Bundle** pattern: the page is a directory (`technical-architecture/`) containing `index.md`, not a flat `.md` file. See `confluence-file-structure.md` for details.
-
-```yaml
----
-sync:
-  confluence_page_id: "456789012"
-  confluence_url: "https://rezolve.atlassian.net/wiki/spaces/ENG/pages/456789012"
-  confluence_title: "Technical Architecture — User Authentication"
-  space: "ENG"
-  parent_page_id: "456789000"
-  last_synced: "2025-12-11T10:30:00Z"
-  version: 3
-  remote_updated: "2025-12-11T09:15:00Z"
-
-mode: "structured"
-
-source:
-  jira_ticket: "AIP-200"
-  doc_type: "technical-architecture"
-  generated_from: "docs/jira/rezolve/AIP/AIP-200-user-authentication/_docs/technical-architecture.md"
-  bmad_docs_referenced:
-    - "docs/jira/rezolve/AIP/AIP-200-user-authentication/_docs/technical-architecture.md"
-  jira_initiative_key: "AIP-100"
-
-orchestrator:
-  generated_at: "2025-12-08T14:00:00Z"
-  auto_sync: true
----
-
-# Technical Architecture — User Authentication
-
-## Overview
-
-REST API authentication using JWT tokens with bcrypt password hashing and Redis-backed rate limiting.
-
-## Authentication Flow
-
-1. Client sends POST `/api/auth/login` with credentials
-2. Server validates against UserService
-3. On success: sign JWT with RS256, return token + expiry
-4. On failure: increment rate limiter, return 401
-
-## Technology Decisions
-
-- **JWT signing:** RS256 with rotating keys (see decisions.md)
-- **Rate limiting:** Redis sliding window, 5 req/min/IP
-- **Password storage:** bcrypt with cost factor 12
-```
-
----
-
-## Complete Example: Synced Confluence Page (Flexible Mode)
-
-This example shows an ad-hoc page published to Confluence by a developer using the `confluence-publish` skill. The file lives at:
-
-```
-docs/confluence/rezolve/ENG/team-guides/onboarding-guide/index.md
-```
-
-```yaml
----
-sync:
-  confluence_page_id: "789012345"
-  confluence_url: "https://rezolve.atlassian.net/wiki/spaces/ENG/pages/789012345"
-  confluence_title: "Developer Onboarding Guide"
-  space: "ENG"
-  parent_page_id: "789012000"
-  last_synced: "2025-12-12T14:00:00Z"
-  version: 1
-  remote_updated: "2025-12-12T14:00:00Z"
-
-mode: "flexible"
-
-source:
-  origin: "manual"
-  linked_jira: "AIP-300"
----
-
-# Developer Onboarding Guide
-
-Welcome to the team! This guide covers local setup, tooling, and key workflows.
-
-## Local Setup
-
-1. Clone the monorepo
-2. Run `npm install` in the root
-3. Copy `.env.example` to `.env` and fill in values
-
-## Key Workflows
-
-- **Daily triage:** Use `jira-daily-triage` to start your day
-- **Ticket focus:** Use `jira-ticket-focus` to deep-load a ticket
-- **Wrap up:** Use `jira-wrap-sync` when finishing work
-```