Docs

File Structure

Complete map of every file and directory FlyDocs installs, and which files are managed vs user-maintained.

FlyDocs installs configuration files across several directories to support multiple AI coding tools. This page documents every file, its purpose, and whether FlyDocs manages it or you do.

On the cloud tier, most of these files are managed artifacts delivered from the server. The CLI syncs them automatically, and the server owns their content. User-maintained files (project context, knowledge base) are never overwritten by sync.

Directory Overview

project root 
your-project/
  .claude/              # Claude Code configuration
  .cursor/              # Cursor configuration
  .flydocs/             # FlyDocs configuration and cache
  flydocs/              # Project content (user-maintained)
  AGENTS.md             # Cross-platform agent instructions
  CHANGELOG.md          # Project changelog

.claude/ -- Claude Code Configuration

The primary configuration directory for Claude Code. Contains hooks, skills, commands, agent definitions, and the settings file that wires everything together.

.claude/hooks/

Seven Python hook scripts that enforce workflow discipline at key moments:

File Trigger Purpose
prompt-submit.py Before prompt processing Injects workflow context, milestone and label data into prompts
auto-approve.py Before Bash/Edit execution Auto-approves known-safe script executions, validates create arguments
post-edit.py After code changes Runs auto-formatting on edited files
post-pr-check.py After shell commands Validates PR operations and session file updates
post-transition-check.py After shell commands Validates status transitions and enforces workflow rules
stop-gate.py Agent finishes response Full lifecycle gate -- checks READY, IMPLEMENTING, REVIEW, BLOCKED states
session-start.py New session begins Injects continuity context from previous sessions

.claude/skills/flydocs-workflow/

The unified workflow skill. This is the core of FlyDocs methodology:

  • SKILL.md -- skill entry point and index
  • stages/ -- stage procedures (capture, refine, activate, implement, review, validate, close)
  • reference/ -- comment templates, status workflow, priority/estimates, PR workflow, golden rules
  • scripts/ -- dispatcher scripts for issue, project, workspace, and session operations
  • templates/ -- issue and PR templates

.claude/commands/

Slash command definitions as .md files. Each file defines a command that users invoke with /command-name in their AI assistant.

.claude/agents/

Agent role definitions. Different agents handle different stages of the workflow (PM, Implementation, QE, Review).

.claude/settings.json

Hook registrations and permissions. Maps hook triggers to the Python scripts in .claude/hooks/.

.cursor/ -- Cursor Configuration

Generated from the same skills and workflow definitions, adapted for Cursor's configuration format.

Directory Purpose
rules/ .mdc rule files generated from installed skills
commands/ Command definitions for Cursor
agents/ Agent definitions for Cursor
hooks.json Hook registrations for Cursor

.flydocs/ -- FlyDocs Configuration

The FlyDocs-specific configuration directory. Contains tier settings, workspace config, caching, and integrity tracking.

File Purpose
config.json Primary configuration -- tier, workspace, labels, stack detection. See Configuration.
manifest.json Inventory of all installed files. Used to track what FlyDocs manages.
integrity.json Drift detection cache with 30-minute TTL. Tracks expected file hashes.
version Installed FlyDocs version string.
cache/ Workspace services cache for cross-repo context.
templates/ Issue templates (feature, bug, chore, idea) used by the capture command.

flydocs/ -- Project Content

This is your content. FlyDocs creates the structure during installation, but you maintain the files. FlyDocs will never overwrite anything in this directory.

File / Directory Purpose
context/project.md Project scope, tech stack, conventions, and active priorities. The primary context document your AI reads.
context/service.json Service descriptor for cross-repo context. Describes your service's API surface and dependencies.
knowledge/ Decisions, notes, and product context. Contains INDEX.md plus templates for structured knowledge capture.
design-system/ Design system documentation (created if applicable based on detected stack).

Root Files

File Purpose
AGENTS.md Cross-platform agent instructions for tools that don't support .claude/ -- Warp, Codex, Windsurf, and others.
CHANGELOG.md Project changelog, maintained as part of the development workflow.

Owned vs User-Maintained

FlyDocs distinguishes between files it manages and files you maintain. This determines what happens during flydocs update:

Category Updated by FlyDocs Examples
Owned (managed) Yes -- replaced on update .claude/hooks/, .claude/skills/, .claude/settings.json, .cursor/, .flydocs/templates/
User-maintained Never overwritten flydocs/context/, flydocs/knowledge/, CHANGELOG.md, AGENTS.md
Generated once Created if missing, not replaced .flydocs/config.json, flydocs/context/project.md

Integrity System

FlyDocs tracks file integrity to detect drift -- manual edits to managed files that could break workflow enforcement.

  • integrity.json stores SHA-256 hashes of all managed files
  • Validated on session start by the session-start.py hook
  • Uses a 30-minute TTL cache to avoid redundant checks
  • If drift is detected, FlyDocs warns you and offers to restore the expected version
  • Running flydocs update resets integrity baselines