Docs

File-Based Tracking

How FlyDocs manages issues as local markdown files with full workflow enforcement.

In local mode, issues are stored as markdown files managed by the local backend (_local/file_store.py). The same commands that create and transition issues in Linear or Jira work identically here. The difference is storage, not workflow.

Creating Issues

Use /capture or the issues.py create script to create a local issue. The same template structure applies: title, description, type, priority, and estimate.

Terminal 
python3 .claude/skills/flydocs-workflow/scripts/issues.py create \
  --title "Add dark mode support" \
  --type feature \
  --priority 2 \
  --estimate 3

This creates a markdown file in the local issue store with the full issue template, including sections for description, acceptance criteria, and status history.

Issue file structure

flydocs/issues/LOCAL-1.md 
# Add dark mode support

**Type:** feature
**Priority:** 2 (High)
**Estimate:** 3
**Status:** Triage
**Created:** 2026-03-29

## Description

(Add description here)

## Acceptance Criteria

- [ ] (Define criteria)

## Status History

- 2026-03-29: Created (Triage)

Transitioning Issues

The same slash commands drive the workflow. Each transition requires a comment, just like the cloud tier. No silent moves.

Command Transition What Happens
/capture Creates in Triage New issue file created with template
/refine Triage → Ready Spec completed, acceptance criteria defined
/activate Ready → Implementing Assignment set, work begins
/implement Works in Implementing Build according to spec, post progress
/review Implementing → Review Code quality check against criteria
/validate Review → Testing/QA User acceptance testing
/close Testing → Done Issue archived, work complete

Example transition

Terminal 
python3 .claude/skills/flydocs-workflow/scripts/issues.py transition \
  LOCAL-1 IMPLEMENTING "Starting work — branch created, spec reviewed"

The local backend updates the issue file's status and appends the transition comment to the status history section.

Status Flow

Local issues use the same status flow as the cloud tier. The lifecycle is identical.

Status Flow 
Triage → Ready → Implementing → Review → Testing/QA → Done
                      ↕                                    ↓
                   Blocked                             Cancelled

Workflow Enforcement

All enforcement is active in local mode. The same hooks and gates that run in the cloud tier run locally.

  • Stop gate: blocks the agent from finishing if work is incomplete or a transition was missed
  • Transition comments: every status change requires a comment, enforced by the script
  • Assignment rules: assignment is required before moving to Implementing
  • Acceptance criteria: checkboxes live in the issue description, never in comments
  • Session wrap: posts a project update summarizing progress at session end

Querying Issues

List and filter issues using the same commands as the cloud tier.

Terminal 
# List all active issues
python3 .claude/skills/flydocs-workflow/scripts/issues.py list --active

# List issues in a specific status
python3 .claude/skills/flydocs-workflow/scripts/issues.py list --status IMPLEMENTING

# Get full details for an issue
python3 .claude/skills/flydocs-workflow/scripts/issues.py get LOCAL-1 --fields full

Limitations vs Cloud

Local mode provides the full workflow but without the connected layer. Here is what differs:

Feature Local Cloud
Issue storage Local markdown files Synced with PM tool
Relay API Not available Active
Dashboard Not available Full portal access
Team sync Not available Shared workspace
Multi-project Single project Multiple projects
PM integration Not available Linear, Jira, and more
Workflow enforcement Full Full
Skills and hooks Full Full

Next