Skip to main content
skill CX Codex

flow-next-tracker-sync — Claude Code skill: sync specs to Linear, Jira

flow-next-tracker-sync projects a flow-next spec onto a Linear, GitHub, GitLab or Jira issue and keeps body, status and comments in sync, with the spec staying authoritative.

MIT ★ 730 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next
Open on GitHub

What flow-next-tracker-sync does

The skill treats a flow-next spec as the source of truth and projects it onto one tracker issue — Linear, GitHub, GitLab or Jira. Body, status and comments get reconciled both ways. Activity inside the tracker never starts an agent and never moves a Flow task.

Provider work sits in flowctl tracker: transport, field mapping, credentials, retries, receipts. The agent supplies semantic input only. Five points stay with the agent: Linear MCP calls, the one-time discovery ceremony, adjudicating a three-way body conflict, writing comment text, and picking a recovery step from a typed error envelope. The bridge stays off until someone confirms provider, project and lifecycle events.

flowctl is looked up at ${CLAUDE_PLUGIN_ROOT}/scripts/flowctl and then .flow/bin/flowctl; with neither present the skill does nothing. Comment and body text travel through 0600 temp files rather than argv. This is not /flow-next:sync, which handles plan-sync.

What it helps with

  • link a flow spec to an existing tracker issue
  • push spec body edits into Jira without touching Flow task status
  • settle a three-way conflict in the issue body
  • post a lifecycle comment without creating duplicates
  • detach a spec from an issue and leave user-owned relations alone

Example prompts for the agent

  • Link the current spec to a Linear issue and tell me which project you'd pick
  • Push the spec body to Jira and resolve the conflict in the requirements section
  • Pull statuses from GitHub Issues and reconcile them with the spec

How to install flow-next-tracker-sync

1Plugin marketplace

/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next

This installs the whole flow-next plugin with all its skills

2Skills CLI (Vercel)

npx skills add gmickel/flow-next --skill flow-next-tracker-sync -a claude-code

3Manually: put the files in place

~/.claude/skills/flow-next-tracker-sync/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/flow-next-tracker-sync/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about flow-next-tracker-sync

How do I install flow-next-tracker-sync in Claude Code?

Add the marketplace first: /plugin marketplace add gmickel/flow-next. Then install the plugin: /plugin install flow-next@flow-next.

What does flow-next-tracker-sync do?

It projects a flow-next spec onto a Linear, GitHub, GitLab or Jira issue and reconciles the body, status and comments. Flow task state stays in charge.

How is it different from /flow-next:sync?

/flow-next:sync handles plan-sync. This skill works against an outside tracker: it creates or links the issue and resolves drift.

Source text

SKILL.md · MIT
---
name: flow-next-tracker-sync
description: Project a flow-next spec to Linear, GitHub, GitLab, or Jira and reconcile body, status, and comments. Use for tracker discovery, linking, create-first, push, pull, reconcile, comment, or unlink. Not /flow-next:sync, which is plan-sync.
user-invocable: false
allowed-tools: AskUserQuestion, Read, Bash, Grep, Glob, Write, Edit
---

# flow-next-tracker-sync

The flow spec is the source of truth and quality layer. The tracker is a
co-editable projection. Tracker activity never starts agents or changes Flow
task state.

Read [working-rules.md](../../references/working-rules.md) first unless you already have this run; it holds for every step of this skill.

## Load the reached path

Read [steps.md](steps.md) for the operation sequence and
[references/adapter-interface.md](references/adapter-interface.md) for the
normalized contract. Load only references needed by the reached path:

- Body comparison or conflict:
  [references/body-merge.md](references/body-merge.md).
- Status projection: [references/status-sync.md](references/status-sync.md).
- Comment or question-valve content:
  [references/comments-sync.md](references/comments-sync.md).
- Hybrid identifiers: [references/identity.md](references/identity.md).
- Linear transport shape: [references/linear-ladder.md](references/linear-ladder.md),
  then only the reached MCP or GraphQL reference.
- GitHub, GitLab, or Jira transport shape: the matching provider reference only.

Never load an unselected provider merely because another reference links it.

## Deterministic boundary

`flowctl tracker` owns tracker transport, normalization, credentials, retries,
capability degradation, lifecycle ordering, receipts, and atomic local state.
The skill supplies only approved semantic inputs and reacts to the structured
result. Do not reconstruct provider requests in skill prose or shell.

Use the lifecycle facade for event-driven projection:

```bash
FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL="<plugin-root>/scripts/flowctl"   # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"
$FLOWCTL tracker sync "$SPEC_ID" --op "$OP" --event "$EVENT" \
  --flow-file "$FLOW_FILE" --body-file "$BODY_FILE" \
  --comments-file "$COMMENTS_FILE" --source-body-file "$SOURCE_BODY_FILE"
```

Pass only flags legal for the selected operation. [steps.md](steps.md) lists
the file contract. For discovery, create-first, link, unlink, status, relation,
attachment, and direct wire maintenance, use the matching `flowctl tracker`
verb. `flowctl tracker --help` is the executable source of truth.

Every command returns one JSON object on stdout. Success has `success: true`,
`data`, `degraded`, and `probe`. Failure has `success: false`, `class`, `error`,
`retryable`, and typed `details`. Branch on `class`, never provider text.

## Exactly five judgment surfaces

These are the only five surfaces intentionally retained in the host agent:

1. **MCP rung.** MCP tools exist only in the host tool environment, so flowctl
   cannot invoke them. The agent may perform the explicitly requested Linear
   MCP action, then hands the returned identity to `tracker persist-external`.
2. **Discovery ceremony.** Choosing a tracker, project or team, and enabling
   lifecycle events is an ambiguous one-time product decision. The agent
   surfaces detected choices and asks before persisting configuration.
3. **Body-merge conflict adjudication.** A three-way body conflict is semantic
   because equivalent prose, intent, and requirement meaning cannot be resolved
   from hashes or syntax alone. The agent adjudicates only conflicting sections,
   while flowctl owns snapshots and atomic persistence.
4. **Comment content synthesis.** Lifecycle comments communicate human context.
   The caller decides what the comment should say and supplies a stable
   occurrence identity as the first file line, `evidence=<token>`. Flowctl
   rejects missing/placeholder evidence, strips that line from visible content,
   and owns marker dedup, transport, and the receipt.
5. **Recovery routing from a structured error.** A typed conflict,
   `external_action_required`, or non-retryable capability result can require a
   user choice, an MCP continuation, a local correction, or a defer. The agent
   selects that next action from the structured envelope instead of parsing
   error prose.

No other tracker operation is agentic. In particular, request construction,
pagination, provider field mapping, status policy, relation projection,
comment dedup, credential selection, retry timing, and receipt writes remain
deterministic.

## Discovery ceremony

The bridge is off until the user confirms it; [steps.md](steps.md) §1 is the procedure. Every
discovery surfaces the provider signals, the proposed project or team, and the lifecycle defaults.
Credentials remain in the environment. Never copy credentials into config, a prompt, argv,
receipt, or error note.

Linear MCP is discovery/create only. All later shell-reachable operations use
the deterministic GraphQL route. If an MCP create returns only a display key,
`tracker persist-external` resolves and stores its durable identity.

## Operating rules

- One Flow spec maps to one tracker issue. Tasks remain Flow-local.
- Tracker-first creation uses the hybrid identifier rules in `identity.md`.
  Never rename an existing Flow-first spec.
- Callers retain their bridge-active and `perEvent` gates. An inactive bridge
  remains silent because the lifecycle facade is not invoked.
- Event-driven callers use `tracker sync`, not granular tracker verbs.
- Comment text and merged body text travel through mode `0600` temporary files,
  never argv. Delete temporary files after the call.
- The facade writes one aggregate receipt. Do not add a second receipt.
- A pull or reconcile may update Flow prose, but never Flow task status.
- Dependency projection is additive and provenance-led. Never delete or
  recreate a user-controlled relation without evidence that Flow owns it.
- `inactive` is a silent no-op for lifecycle callers.
- `rate_limited` is retried only when the envelope says `retryable: true`.
- `auth`, `unresolved`, `stale_id`, `conflict`, `capability`, and
  `external_action_required` follow the recovery table in `steps.md`.
- In any unattended run (a stage `flow --auto` dispatched, any
  `mode:autonomous` caller) or a forked lifecycle call, queue a decision that
  needs a person with `flowctl sync defer`. Never attempt an interactive prompt
  there.

## Boundaries

This skill is projection, not coordination. `/flow-next:tracker-sync` is
distinct from `/flow-next:sync`. Flow state remains authoritative. Provider
wire details live in deterministic Python; the Markdown references document
their shapes so reviewers can inspect the contract without copying executable
transport recipes into prompts.

© Gordon Mickel · MIT · gmickel/flow-next

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set70

The whole set →
github-scout github-scout finds code patterns, implementations, and issue reports on GitHub. Helpful when you need authoritative references before writing code. CX Codex ★ 730repo stars flow-next-prospect flow-next-prospect is a Claude Code skill that finds and ranks ideas from a repository’s contents. It runs when asked to brainstorm what to build next. CX Codex +1 ★ 730repo stars flow-next-map flow-next-map wraps clawpatch map to build a semantic index of functions and modules across ~20 languages. Runs provider-free by default. CX Codex +1 ★ 730repo stars security-scout security-scout inspects GitHub branch protection, CODEOWNERS, secret scanning, and automated dependency updates before agent tasks begin. CX Codex ★ 730repo stars claude-md-scout claude-md-scout audits CLAUDE.md and AGENTS.md files on an eight-point substance scale, verifying real commands and repo specifics before agents start working. CX Codex ★ 730repo stars flow-gap-analyst The flow-gap-analyst subagent examines a short feature brief for unclear requirements, missing steps, and edge cases. Use it to surface questions before implementation begins. CX Codex ★ 730repo stars flow-next-deps flow-next-deps shows spec dependency graph, execution order and blocking chains. Use it when you ask 'what's blocking what' or 'what order should specs run'. CX Codex +1 ★ 730repo stars flow-next-plan-review The flow-next-plan-review skill routes Flow specs and plans to a selected reviewer, then handles fixes and a follow-up review. Use it to check a Flow document before moving ahead. CX Codex +1 ★ 730repo stars

Project sponsors

Companies that keep this analytics open