Docs

Project Management

Connect FlyDocs to Linear, Jira, or other PM tools through the relay API for automated issue management.

FlyDocs connects to your project management tool through the relay API. Scripts in your project call the relay, the relay resolves your workspace configuration, translates the request into provider-specific API calls, and returns a standardized response. Your workflow stays the same regardless of which PM tool you use.

How the Relay Works

The relay API is the translation layer between FlyDocs' unified operations and provider-specific APIs. It handles authentication, status mapping, label sync, and response normalization so scripts never deal with provider differences directly.

Request Flow

Your project scripts → Relay API → Provider API

Scripts call the relay → relay resolves workspace config → translates to provider API → returns standardized response

Status mapping

FlyDocs workflow statuses (Triage, Ready, Implementing, Review, Testing/QA, Done) map to your provider's actual status names. This mapping is configured at the workspace level during setup.

.flydocs/config.json (excerpt) 
{
  "statusMapping": {
    "BACKLOG": "Backlog",
    "READY": "Todo",
    "IMPLEMENTING": "In Progress",
    "BLOCKED": "On Hold",
    "REVIEW": "Internal Review",
    "TESTING": "QA",
    "COMPLETE": "Done"
  }
}

When a script transitions an issue to REVIEW, the relay looks up the mapping and sends the provider the corresponding status name. Your team sees native statuses in their PM tool while FlyDocs maintains a consistent lifecycle.

Label sync

FlyDocs uses category labels (feature, bug, chore, idea) that map to your provider's label system. Labels are synced during workspace setup and kept consistent through the workspace.py refresh-labels command.

Linear

Connect via API key in the FlyDocs portal. Select your team, configure status mapping, and FlyDocs handles the rest through its GraphQL adapter.

Setup

  1. Generate a personal API key from Linear Settings → API
  2. Add it to your environment: LINEAR_API_KEY=lin_api_xxxxx in .env
  3. Run flydocs connect and select Linear as your provider
  4. Choose your team and configure status mapping

Supported operations

Category Operations
Issues Create, read, update, delete, transition, assign, comment
Planning Estimates, priorities, labels, milestones, cycles
Project Project updates, status summaries, health reports
Queries List by status, assignee, project, milestone, or activity

Example

Terminal 
python3 .claude/skills/flydocs-workflow/scripts/issues.py create \
  --title "Add user avatar upload" \
  --type feature \
  --priority 2 \
  --estimate 3

Jira

Connect via OAuth in the FlyDocs portal. Select your project, configure status mapping, and FlyDocs handles the rest through its REST adapter.

Setup

  1. Open the FlyDocs portal and navigate to workspace settings
  2. Select Jira under project management providers
  3. Authorize via OAuth and select your Jira site
  4. Choose your project and configure status mapping

Supported operations

Category Operations
Issues Create, read, update, delete, transition, assign, comment
Planning Estimates, priorities, labels, versions, sprints
Project Project updates, status summaries
Queries JQL-based queries filtered by status, assignee, project, or sprint

Example

Terminal 
python3 .claude/skills/flydocs-workflow/scripts/issues.py transition \
  PROJ-456 REVIEW "All acceptance criteria met, ready for code review"

Additional Providers

The relay architecture is designed for provider expansion. Each new provider needs an adapter that translates FlyDocs operations into the provider's API. The script interface and workflow stay identical — switching providers does not change your workflow.

Planned providers:

  • GitHub Issues — native issue tracking for teams already on GitHub
  • Notion — database-backed issue management
  • ClickUp — task and project management
  • Asana — work management for cross-functional teams
  • GitLab Issues — integrated with GitLab version control
  • Trello — board-based workflow management

Join the Discord to request a provider or follow development progress.

The Unified Client

Under the hood, all PM operations go through a unified client (flydocs_api.py) that reads the tier from .flydocs/config.json and routes automatically:

  • Cloud tier: routes to the relay API, which calls Linear, Jira, or whichever provider is configured
  • Local tier: routes to the local file backend for offline issue tracking

Scripts never check tier. The client handles routing transparently. This means the same issues.py create command works whether you are connected to Linear, Jira, or running locally with no PM tool at all.

Next