flow-next-tracker-sync

Synchronizes flow-next specs bidirectionally with Linear, GitHub, GitLab, and Jira tracker issues.

692|55|Updated Dec 26, 2025

Search Tags:#linear #Jira #gitHub #flowctl #three-way merge #spec projection #issue tracker sync

One-click install

npx skills add https://github.com/gmickel/gmickel-claude-marketplace --skill flow-next-tracker-sync

Or copy as Structured Prompt for Agent▼

Please help me install this Agent Skill.
Skill: flow-next-tracker-sync
Source: https://github.com/gmickel/gmickel-claude-marketplace/tree/main/plugins/flow-next/codex/skills/flow-next-tracker-sync
Command: npx skills add https://github.com/gmickel/gmickel-claude-marketplace --skill flow-next-tracker-sync

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Keeping a flow-next spec and an external issue tracker in sync manually leads to drift, duplicate comments, lost edits, and conflicting status updates. This Skill projects a flow spec to a tracker issue and reconciles changes in both directions while keeping the Flow spec as the authoritative source.

Core Features & Use Cases

Two-way issue projection: Create, link, push, pull, and reconcile tracker issues on Linear, GitHub, GitLab, or Jira from a flow spec via the deterministic flowctl tracker CLI.
Three-way body merge: Reconcile divergent spec and tracker bodies against a stored merge base, surfacing only genuine section-scoped conflicts for human adjudication.
Comment and evidence dedup: Post lifecycle evidence comments with stable markers and import genuine tracker comments into the spec's Sync Log without duplicates.
Use Case: A developer finishes a task and wants the linked Linear issue updated with evidence, while a PM's edits in Linear fold back into the spec without overwriting either side.

Quick Start

Ask the agent to sync the current flow spec to the configured tracker, for example by requesting to push spec fn-42 to Linear and reconcile any differences.

Frequently Asked Questions about flow-next-tracker-sync

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I sync a flow-next spec to Linear or GitHub?▼

Run the tracker sync through the flowctl CLI with the spec id, operation, and lifecycle event, passing body content via mode 0600 temporary files. The facade handles create-if-unlinked, provider calls, and writes one aggregate receipt.

Which issue trackers does flow-next tracker sync support?▼

It supports Linear, GitHub, GitLab, and Jira through normalized provider adapters. Linear uses an MCP or GraphQL transport ladder, GitHub uses the authenticated CLI, and each provider degrades unsupported capabilities explicitly.

How are conflicting edits between the spec and tracker resolved?▼

A three-way merge compares both sides against the stored merge base. Non-conflicting edits fold automatically, while genuine semantic contradictions are surfaced as section-scoped conflicts for a human decision or deferred in autonomous mode.

Does tracker sync change Flow task status?▼

No. A pull or reconcile may update Flow prose, but it never changes Flow task status. The Flow spec remains the source of truth and the tracker is only a co-editable projection.

Why are duplicate comments posted to the tracker issue?▼

Duplicates are prevented by three dedup layers: an embedded marker keyed on issue, event, and evidence token, stored posted-comment ids, and a normalized-text hash that catches human-pasted copies. A blind retry after a failed response parse is the main risk, so the marker check must be re-run first.

What are the limitations of tracker sync in autonomous mode?▼

Under autonomous or Ralph mode, no interactive prompts are allowed. Discovery, merge conflicts, and question authoring are queued for a human via sync defer instead of prompting, and the bridge stays silent when inactive.