Core concepts — architecture and enforcement

FlyDocs is a structured context platform that connects your AI coding tools to your project management workflow. It gives your AI agent project context, enforced workflows, and live PM integration -- so developers stay in flow and PM tools stay current.

This page covers how the system is built, why it works, and what happens during an AI coding session.

The architecture

FlyDocs has three components. Each handles a distinct responsibility.

CLI

The @flydocs/cli package installs skills, hooks, commands, and context into your project. It is read-only for configuration -- it pulls everything from the server and writes it to your repo as files your AI tools can read directly.

Portal

The web portal at app.flydocs.ai is the source of truth for workspace configuration. Provider connections, team mappings, status and label config, managed artifacts -- admins configure once, and every repo stays aligned.

Relay API

The relay sits between the CLI and your PM tool. It translates FlyDocs operations into Linear GraphQL or Jira REST calls. It authenticates with fdk_ keys, resolves configuration from workspace records, and decrypts provider credentials only for the duration of each request.

The relay is not a persistent connection. Skill scripts call it on demand. If the relay is unreachable, the AI still has full access to the workflow, context, and enforcement layers. Only external PM sync is interrupted.

Three-layer enforcement

The system enforces consistency through three layers. Together they make AI-assisted development deterministic rather than probabilistic.

This layering keeps the context footprint minimal. The skill index is roughly 100 tokens. A full skill procedure adds 200-400 tokens. Compare that to MCP tool descriptions that consume 500-2,000 tokens per tool, loaded every single turn.

Portal as source of truth

When you create a workspace and configure it in the portal, that configuration is authoritative. The CLI sends X-Workspace: ws_xyz with every request, and the relay resolves provider type, team, status mapping, labels, and custom rules from the workspace record.

This architecture means:

• Config lives in one place -- change a status mapping in the portal, and every CLI session sees the update on the next request. No re-init, no redistribution.
• Multi-provider is supported -- different workspaces within the same org can use different PM tools. Workspace A uses Linear, Workspace B uses Jira. The workflow and enforcement are identical.
• Zero config for developers -- clone the repo, add your API key, and the workspace ID already committed in .flydocs/config.json handles everything else.

Managed artifacts

Skills, hooks, commands, and cursor rules are delivered from the server as managed artifacts. The CLI tracks artifact versions with a monotonic version number. When the server publishes new skills or hooks, every team member gets them on the next flydocs sync.

No manual distribution. No "did you pull the latest skills?" messages. Workspaces can also include custom rules that are replicated to every repo's context layer automatically.

Hook enforcement

Hooks are platform-triggered scripts configured in .claude/settings.json. They fire on 5 event types: UserPromptSubmit, PreToolUse, PostToolUse, Stop, and SessionStart. The AI does not choose to run them. The platform runs them unconditionally.

{
  "hooks": {
    "UserPromptSubmit": [{ "hooks": [{ "type": "command",
      "command": "python3 .claude/hooks/context-injection.py" }] }],
    "PreToolUse": [{ "matcher": "Bash|Edit|Write", "hooks": [{ "type": "command",
      "command": "python3 .claude/hooks/auto-approve.py" }] }],
    "PostToolUse": [
      { "matcher": "Edit|Write", "hooks": [{ "type": "command",
        "command": "python3 .claude/hooks/post-edit.py" }] },
      { "matcher": "Bash", "hooks": [{ "type": "command",
        "command": "python3 .claude/hooks/post-bash.py" }] }
    ],
    "Stop": [{ "hooks": [{ "type": "command",
      "command": "python3 .claude/hooks/stop-gate.py" }] }],
    "SessionStart": [{ "hooks": [{ "type": "command",
      "command": "python3 .claude/hooks/session-start.py" }] }]
  }
}

Seven hooks handle context injection, script auto-approval, auto-formatting, PR validation, transition validation, the stop gate (blocks the AI from finishing with incomplete work), and session continuity. They are the enforcement layer -- the difference between a style guide and a pre-commit hook.

Full hook reference with all 7 hooks explained.

Progressive disclosure

The system uses three levels of progressive disclosure to keep context costs low:

Total context for a single task stays under 2KB -- a fraction of what a typical MCP tool description set consumes. The AI loads what it needs, when it needs it, and nothing more.

Context graph

The context graph maps decisions, issues, modules, sessions, and their relationships. It is built from your project's skills, architecture decision records, and service descriptors.

The agent uses the graph to orient itself in seconds: which decisions shaped this module, what issues are active, how this repo relates to others in the workspace. It provides cross-session memory that survives thread boundaries.

How an AI session works

Here is what happens when a developer starts working with an AI coding tool in a FlyDocs project:

1. SessionStart hook fires -- injects the previous session summary so the agent picks up where you left off. No "let me re-read the project" preamble.
2. Agent reads project context -- project.md, service.json, and the context graph give the agent a complete picture of your stack, standards, active priorities, and cross-repo relationships.
3. Developer invokes a workflow command -- e.g., /activate FLY-123. The agent loads the full issue context: acceptance criteria, estimate, history.
4. Hooks enforce as work proceeds -- auto-formatting on every edit, transition validation on every status change, the stop gate preventing incomplete handoffs. The AI cannot skip these.
5. Everything syncs to the PM tool -- issue transitions, comments, and status updates flow to Linear or Jira through the relay in real time. PMs see progress without asking.
6. Session wraps with a summary -- progress, decisions, and next steps are captured and posted as a project update. The next session starts with full continuity.

Next

• Skills -- the unified workflow skill, skill types, and how they replace MCP servers
• Hooks & Enforcement -- all 7 hooks explained
• Context & Memory -- project context, session continuity, and the knowledge graph
• Workspaces & Topology -- workspace configuration, topology detection, and cross-repo context
• Workflow Lifecycle -- the 7 stages from capture to close