Docs

Workflow Lifecycle

The 7 stages of AI-assisted development from capture to close, with enforcement at every transition.

FlyDocs structures AI-assisted development into a repeatable lifecycle. Every issue moves through defined stages with clear handoffs, enforced transitions, and documented outcomes. The workflow is the same regardless of whether issues live in local markdown files, Linear, or Jira.

On the cloud tier, every stage transition syncs to your PM tool automatically. When a developer runs /capture, the issue appears in Linear or Jira. When they /activate, status moves to In Progress. When they /close, it is Done. Leads open their PM tool and it reflects reality -- not what someone remembered to update.

The 7 stages

Stage Command What happens Enforcement
Capture /capture Create issue from input using the appropriate template Template validation
Refine /refine Add acceptance criteria, priority, estimates, labels Spec completeness check
Activate /activate Assign to implementer and transition to implementing Assignment required
Implement /implement Build against the spec with full context loaded Stop gate, transition validation
Review /review Check implementation against acceptance criteria PR validation
Validate /validate QE verification against acceptance criteria Criteria checkbox tracking
Close /close Mark done, record outcomes, update knowledge base Completion comment required

Blocked is a side state that any stage can transition to. When work is blocked, the AI records the blocker reason and the issue remains visible in active issue lists until unblocked.

Lifecycle Flow

Capture
→
Refine
→
Activate
→
Implement
→
Review
→
Validate
→
Close
Blocked (side state from any stage)

What happens at each stage

Capture

The AI identifies the issue type (feature, bug, chore, idea) from your description, loads the appropriate template, fills in information it can infer from context, and creates the issue. Templates provide structure with acceptance criteria, technical notes, and dependency tracking.

Refine

The PM agent (or developer) adds detail: acceptance criteria with MoSCoW prioritization (Must/Should/Won't Have), priority level, size estimate, labels, and technical notes. The goal is a spec complete enough for an AI to implement without ambiguity.

Activate

Assignment is a hard gate. The issue cannot move to Implementing without an assignee. This is enforced by the transition validation hook, not just documented as a convention. Once assigned, the issue transitions to Implementing and the implementer has a clear spec to work against.

Implement

The implementation agent reads the spec, creates a branch, builds incrementally, and commits at each milestone. The stop gate hook blocks the AI from finishing its response while the issue is still in Implementing state. The AI must transition the issue to Review (or Blocked) and add a comment explaining what was done.

Review

The review agent checks the implementation against acceptance criteria. PR validation hooks ensure workflow compliance. If criteria are not met, the issue moves back to Implementing with specific feedback.

Validate

Optional QE verification. A separate agent (or human) tests against the acceptance criteria checklist. Checkboxes in the issue description track which criteria have been verified.

Close

The issue is marked done with a completion comment documenting outcomes, decisions made, and any follow-up work captured as new issues. The knowledge base is updated if significant decisions were made.

Enforcement during workflow

The workflow is not just a process diagram. Multiple hooks enforce it at the platform level:

  • Stop gate: blocks the AI from finishing with an issue still in Implementing state. The AI must transition or explain why it cannot.
  • Transition validation: catches missing comments on status transitions. Every status change requires a comment documenting what happened.
  • Assignment gate: the issues.py transition command enforces assignment before Implementing. You cannot start work on an unassigned issue.
  • PR validation: validates PR workflow compliance after git operations.
Terminal 
# Transition with a required comment
python3 .claude/skills/flydocs-workflow/scripts/issues.py \
  transition ENG-123 REVIEW "All acceptance criteria met, PR ready"

# The transition validation hook catches missing comments
# The stop gate blocks completion if the issue is still IMPLEMENTING

Status mapping

FlyDocs defines its own workflow statuses (Backlog, Ready, Implementing, Review, Validate, Done, Blocked, Cancelled). These map to your PM provider's statuses at the workspace level. Linear's "In Progress" might map to FlyDocs' "Implementing." Jira's "In Review" might map to "Review."

The mapping is configured once during workspace setup and applied transparently. The AI always works with FlyDocs status names. The dispatcher scripts handle the translation when communicating with the provider API.

Issue templates

Four template types structure issue creation:

Type Purpose Key sections
Feature New user-facing functionality User story, MoSCoW criteria, technical notes, dependencies
Bug Defects with reproduction steps Expected vs actual, reproduction steps, severity, root cause
Chore Maintenance and infrastructure Task description, measurable outcomes, risk assessment
Idea Proposals needing discussion Concept, motivation, open questions, next steps
templates/issues/feature.md (excerpt) 
## Context
[Problem description — what user pain or business need]

## Acceptance Criteria

### Must Have
- [ ] [Specific, measurable criterion]
- [ ] [Error handling criterion]

### Should Have
- [ ] [Enhancement criterion]

### Won't Have (Out of Scope)
- [Explicitly excluded functionality]

## Technical Notes
[Implementation approach, components needed, dependencies]

Templates include agent instructions in HTML comments that guide the AI during capture and refinement. These instructions tell the AI how to fill in each section, what makes a good acceptance criterion, and when to use checkboxes. The instructions are stripped from the final issue description.

Backend-agnostic workflow

The workflow is identical regardless of PM backend. The same slash commands, the same stage procedures, the same enforcement hooks. Only the dispatcher scripts differ in how they store and retrieve issues:

  • Local tier: issues stored as markdown files in _local/ directories
  • Cloud tier (Linear): issues synced via the FlyDocs relay API to Linear's GraphQL API
  • Cloud tier (Jira): issues synced via the relay to Jira's REST API

The unified client in the dispatcher scripts auto-detects the tier from .flydocs/config.json and routes operations transparently. Swapping from local to cloud requires changing one config value. The workflow does not change.

Next