This page explains AgileBuilder's six core concepts and where the line sits between the open-source CLI and the cloud service.

Resources

Resources are the basic unit AgileBuilder manages, and there are exactly two types:

Type	Purpose
`template`	Points to a Git repository (optional branch and subdirectory); used by `ag create` to generate projects
`doc`	Markdown or plain-text content serving as standards and reference material; can also be exposed to AI tools as an MCP resource

Every resource belongs to a space: local resources live in ~/.agilebuilder/v2/resources/local.json, while cloud resources live in their space and sync across devices.

Resource management commands all sit under ag res: list / search / get / add / edit / remove — see the CLI Reference and Resource Management.

Templates

A template = a Git repository + a .agilebuilder.config.yaml configuration file.

Place .agilebuilder.config.yaml at the repository root (or in a subdirectory referenced by source.subdir) to declare the template's name, variables, file-matching rules, and Hooks:

version: '1.0'
name: service-template
description: Service starter
source:
  subdir: template
variables:
  enabled: true
  filePatterns:
    mode: include
    patterns:
      - "**/*.ts"
      - "package.json"
  inquirerQuestions:
    - name: appName
      type: input
      message: Application name
      required: true
hooks:
  after_write:
    scriptType: shell
    script: npm install
    errorHandling: warn

Key points:

A repository without a config file still works — the CLI proceeds with defaults and prints a warning
.agilebuilder.config.yaml itself is never copied into the generated project
Binary files are copied as-is without rendering; the .git directory is skipped by default (--keep-git preserves it)

The full template authoring guide: Create a Template and Template Configuration.

Variables

Variables let one template produce many different outputs:

File contents are rendered with EJS; the default delimiter is %, so placeholders look like <%= appName %>. Full EJS syntax — if, loops, and more — is supported
File paths are rendered too, supporting both the {{ variableName }} form and EJS expressions
Built-in case-conversion helpers: camelCase, pascalCase, kebabCase, snakeCase, uppercase, lowercase — e.g. <%= pascalCase(appName) %>

When generating, variable values are resolved in this order (--vars file > --var flags; remaining variables fall back to the defaults from the template configuration, and interactive prompts only fill in whatever is still missing):

Variables from a --vars <path> JSON file
Repeated --var key=value assignments (override same-named variables from --vars)
Defaults defined in the template's questions (fills only what is still missing)
Interactive prompts via --interactive (fills only what is still missing)

Full syntax details: Template Syntax.

Hooks

Hooks are automated actions a template defines to run after project files are written. The current capability boundary:

Only the after_write timing is supported
Only scriptType: shell is supported; the script runs inside the generated target directory
Hooks do not run by default: pass --allow-hooks explicitly, or set template.allowHooksDefault to true
errorHandling: stop aborts generation on failure; warn / continue log and skip

See Template Hooks.

Spaces

A space is a container for resources — and the dividing line between the open-source edition and the cloud:

	Local space `local`	Cloud spaces (personal / team)
Origin	Built into the CLI, no sign-in	AgileBuilder Cloud, requires `ag login`
Storage	Local `~/.agilebuilder/v2`	Cloud, synced across devices
Structure	Flat resource list, no directories	Directory trees supported (`--parent-id`)
Write access	Unrestricted	Free tier is read-only; Trial / Pro can write
Collaboration	None	Members, roles, permissions (team spaces)

Manage the current space with ag space list / ag space use <id> / ag space current. The current space determines what res commands operate on and where create <resource-id> resolves resources from.

The role of MCP

MCP (Model Context Protocol) is the bridge between AgileBuilder and AI tools. The package ships with a stdio server:

agilebuilder-mcp

Once configured in an MCP-capable tool — Cursor, Claude Code, Codex, and others — the AI can:

Query resources via MCP tools (list_resources / search_resources / get_resource) and create projects (create_project)
Read your standards documents directly via MCP resources (agilebuilder://local/docs/<id>, agilebuilder://cloud/docs/<id>, and more)

The MCP server shares the CLI's current space: switch to a team space in the CLI, and the AI sees the team space's resources. AgileBuilder itself never calls any LLM — it simply puts your templates and standards within the AI's reach. Configuration: MCP Integration.

Capability boundary at a glance

Capability	Open-source CLI	Cloud
Create projects from a Git URL	✅	✅
Template variables / Hooks / MCP server	✅	✅
Local resource management	✅	—
Cloud resource management & multi-device sync	—	Free: read-only; Trial/Pro: writable
Team spaces, role permissions, operation logs	—	Team subscription
Resource Plaza publishing	—	Pro / Team

Next steps

Quickstart · Open Source / Pro / Team
CLI Reference — every command and option
Create a Template — build a template of your own