Modules

Modules are reusable infrastructure building blocks your enterprise publishes for teams to compose into their own work. A module is a single concern done well, like a Lambda function pattern, an S3 bucket with the right encryption and access policies, or an IAM role with a specific trust relationship. Other workspaces can reference the module instead of reinventing the same code.

Modules are different from templates. A template is a starting point for a whole project that someone copies as the first move of a new workspace. A module is a unit of reusable code that an existing workspace references and calls. The same workspace can use many modules at once.

Marking a workspace as a module

There are two ways to promote a workspace to a module.

From the workspace card. On any workspace card or list row, open the three-dot menu and choose Convert to → Module.

From workspace settings. Open the workspace, go to Settings, and choose Module in the kind picker.

There is one requirement that templates do not have. A workspace can only be promoted to a module if it is connected to a GitHub repository. Modules are consumed by other workspaces as pinned references to a specific tag, and that requires a real Git repository with versioned releases. If the workspace is local-only or its GitHub connection has been removed, the Convert to → Module option is disabled until you connect it. See Connect GitHub for how to connect a workspace to a repository.

You can convert in either direction. A module can be converted back to a regular workspace at any time.

Discovery

Modules show up in two places.

• The Modules tab in your enterprise. Anyone with view permission for modules sees the full catalog with descriptions, tags, and the underlying GitHub repository.
• The agent's list_modules tool. When someone is working in a workspace and the agent is helping them write infrastructure code, it can call list_modules to surface the enterprise's module catalog and suggest specific modules that match what the user is building.

When the agent suggests modules to a user, it surfaces them as options and asks before locking them into a config. This is intentional. Just because the catalog has a module for something doesn't mean the user wants to use it for this project. The agent confirms first.

What if the module's GitHub repository is disconnected?

Modules are pinned by tag to a specific GitHub repository. If the underlying repository is later disconnected from the enterprise's GitHub installation, the module is still visible in the catalog but flagged as disconnected. New workspaces can still see the module exists but the agent will warn that it cannot be consumed until the connection is restored.

Permissions

Two permissions control what someone can do with modules.

• Modules: view lets the user see modules they are not a member of, browse the Modules tab, and see modules surfaced by the agent's list_modules tool.
• Modules: manage lets the user mark a workspace as a module or remove its module status. Promotion requires the workspace to have a connected GitHub repository. Combined with the Templates: manage permission, the same user can also convert directly between template and module kinds.

Default role assignments grant view to all enterprise members so the agent can surface the catalog when relevant. Manage is more restrictive.

How agents use modules

The agent has authenticated access to your enterprise's GitHub repositories through the same connection that powers Git workspace sync. When the agent encounters a module reference in code, or when it is composing a new configuration that fits an existing module, it can read the module's README, variables, outputs, and example usage directly from the source repository. This grounds the workspace prompt in real module interfaces instead of guesses.

When you write a workspace that consumes a module, the agent matches the call patterns shown in the module's examples/ directory. Modules that ship a few clear examples get consumed correctly far more often than modules that only document themselves in prose.

Best practices

• Pin to a tag. Module references should always pin to a specific version tag, not to a branch or HEAD. The agent reads the latest tag by default but the consuming workspace should write the pin explicitly.
• Ship examples. A module with one good example in examples/ is more useful than a module with a thorough README and no example. The agent consumes examples as the canonical call pattern.
• One concern per module. Modules that try to wire up two unrelated services are harder to compose and harder to version. Split them.
• Tag your modules. Tags on the module workspace help the agent surface relevant modules to users based on what they're building.