Workspaces & Topology

FlyDocs workspaces define how your team works -- which PM tool, which team, what status workflow, what labels. Topology detection tells your AI agent how this repo fits into the larger system. Together, they mean your agent understands the whole project, not just the current file.

Workspaces

A workspace is a scoped container that maps a PM provider team (a Linear team or Jira project) to a set of repos, team members, and configuration. It holds:

• Provider type and team ID -- which PM tool and which team within that tool
• Status mapping -- FlyDocs canonical statuses (Ready, Implementing, In Review, Done) mapped to provider-specific workflow states
• Label configuration -- issue type labels (feature, bug, chore, idea) mapped to provider labels, auto-created if they do not exist
• Issue type mapping -- Jira only: FlyDocs categories mapped to Jira issue types
• Custom workspace rules -- markdown rules replicated to every repo in the workspace as part of the context layer
• Active projects filter -- controls which projects' issues surface during AI sessions
• Team membership -- who can access the relay for this workspace

Most teams need one workspace. Agencies or consultancies working across multiple clients use separate workspaces for isolation. Large organizations might use different workspaces for different PM tools -- one Linear workspace for the product team, one Jira workspace for infrastructure.

Config cascade

Settings cascade through three levels. Each level can override the one above.

Workspace config is authoritative for relay operations. Admins set it once in the portal. Every CLI session resolves it automatically via the workspace ID committed in .flydocs/config.json.

Topology detection

FlyDocs detects your project topology and configures cross-repo awareness automatically. There are four topology types:

Single repo

A standalone application. All context is self-contained in one repository. This is the default when flydocs init runs in a project directory with no sibling repos.

Monorepo

Multiple packages in one repository. Service descriptors map internal dependencies between packages. The agent understands which package handles authentication, which provides the API, and how data flows between them.

Sibling repos

Multiple repos in a parent directory -- e.g., frontend/, backend/, and shared/ side by side. flydocs init detects siblings and offers to create a multi-repo workspace.

Multi-repo workspace

The full topology. A workspace root directory contains .flydocs-workspace.json with a topology index. Skills and scripts live at the workspace root. Config and context live in each child repo.

workspace-root/          # .flydocs-workspace.json, .claude/, AGENTS.md
├── frontend/            # .flydocs/config.json, flydocs/context/
├── backend/             # .flydocs/config.json, flydocs/context/
└── shared/              # .flydocs/config.json, flydocs/context/

.flydocs-workspace.json

The topology index lives at the workspace root. It describes each repo's purpose, stack, and cross-repo dependencies:

{
  "repos": [
    {
      "path": "frontend",
      "purpose": "Next.js web application",
      "stack": ["typescript", "react", "next"],
      "dependencies": [
        {
          "service": "api-service",
          "interface": "REST",
          "description": "Backend API for data operations"
        }
      ]
    },
    {
      "path": "backend",
      "purpose": "Express API service",
      "stack": ["typescript", "node", "express"],
      "dependencies": []
    },
    {
      "path": "shared",
      "purpose": "Shared types and utilities",
      "stack": ["typescript"],
      "dependencies": []
    }
  ]
}

The agent reads this file to understand the full system at a glance. When working in frontend/, it knows that backend/ provides a REST API it depends on, and shared/ contains types both repos consume.

Service descriptors

Each repo gets a flydocs/context/service.json that describes what the repo provides and consumes:

{
  "name": "api-service",
  "purpose": "Backend API for user and project operations",
  "provides": [
    { "type": "REST", "path": "/api/v1", "description": "Core API endpoints" }
  ],
  "consumes": [
    { "service": "auth-service", "interface": "OAuth", "description": "User authentication" }
  ]
}

Service descriptors power cross-repo understanding. The agent reads them to know that the API service depends on an auth service, that the frontend consumes the API, and that changing an API endpoint might require updating the frontend. You stop re-explaining your architecture every session.

Cross-repo context

The agent combines three sources to understand the full system:

1. Workspace topology -- the .flydocs-workspace.json index with per-repo purpose and stack
2. Service descriptors -- per-repo service.json files with provides/consumes interfaces
3. Context graph -- decision records, issue relationships, and module maps that carry across sessions

This means the agent knows which repo handles authentication, which provides the API, how data flows between services, and what decisions shaped the current architecture. Cross-repo changes are informed by actual dependency data, not the agent's guesses.

Multi-provider support

Different workspaces in the same organization can use different PM tools. Workspace A uses Linear, Workspace B uses Jira. The workflow, skills, and enforcement are identical regardless of provider.

The relay translates FlyDocs canonical operations (create issue, transition status, add comment) into provider-specific API calls. Developers always use the same commands. The workspace config determines where those operations land.

Membership

Workspace membership controls who can access the relay for that workspace. Membership operates at two levels:

• Organization members -- access to billing, API key management, and admin functions. Org admins can manage all workspaces.
• Workspace members -- access to projects, issues, and development workflow within a specific workspace. Members access only the workspaces they have been added to.

Roles are org-level: admin or member. Admins manage all workspaces and organizational settings. Members participate in workspaces they are assigned to.

Next

• Workspace Configuration -- set up and manage workspaces in the portal
• Context & Memory -- service descriptors and the context graph in depth
• Workflow Lifecycle -- the stages that run within a workspace