@groupby/ai-dev 0.1.1 → 0.2.0

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

@@ -0,0 +1,209 @@
+# 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
+  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
+
+  # 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
+```