Skip to main content

Conventions Deep Dive

Conventions are coding rules written in Markdown that get automatically injected into the system prompt when an agent executes an appgrammar. They enforce consistent standards across your builds without manual configuration.

This guide covers the full convention system in depth. For a quick overview of team conventions, see Teams & Conventions.

Personal Conventions​

You don't need a team to use conventions. Personal conventions apply to appgrammars you own.

Creating a Personal Convention​

POST /api/conventions
{
  "title": "Error Handling Standards",
  "body": "## Error Handling\n\n- Use custom error classes extending AppError\n- Always include error codes for API responses\n- Log errors with structured metadata",
  "technology_tags": ["typescript", "node"],
  "category": "patterns"
}

In the web UI, go to Conventions in the sidebar.

Managing Personal Conventions​

EndpointMethodDescription
GET /api/conventionsGETList your conventions
GET /api/conventions/match?tags=typescript,reactGETMatch by technology tags
PUT /api/conventions/:idPUTUpdate a convention
DELETE /api/conventions/:idDELETEDelete a convention

Team Conventions​

Team conventions apply to all appgrammars owned by the team. Any team member executing a team appgrammar receives the matching conventions.

Creating a Team Convention​

POST /api/teams/:teamId/conventions

The request body is identical to personal conventions. Team conventions are managed at Team > Conventions in the web UI.

Matching by Tags​

GET /api/teams/:teamId/conventions/match?tags=typescript,react

Returns conventions whose technology tags overlap with the query tags.

Convention Packs​

A convention pack is a named group of conventions. Packs let you bundle related rules (e.g., "Security Pack", "Testing Standards") and optionally mark them as default for a team.

Creating a Pack​

POST /api/teams/:teamId/convention-packs
{
  "name": "Security Standards",
  "description": "XSS prevention, CSRF protection, input validation",
  "is_default": true
}

Personal convention packs use the same structure at POST /api/convention-packs.

Default Packs​

When a pack is marked is_default: true, its conventions are always included in execution regardless of technology tag matching. Use this for universal rules that should apply to every build.

How Injection Works​

When an agent calls appgrammar_start on an appgrammar, matching conventions are automatically composed into the system prompt:

  1. The appgrammar's technology stack is read from its configuration.
  2. Conventions whose technology tags overlap with that stack are selected.
  3. Conventions from default packs are always included.
  4. Matching conventions are formatted as Markdown sections and appended to the system prompt.

The agent receives conventions as part of the system prompt. No additional configuration is needed — matching is automatic.

Technology Tags​

Tags are free-form strings. Common examples: typescript, react, node, python, fastapi, postgresql, tailwind, docker. Use tags that match your appgrammar configurations for best results.

A convention with tags ["typescript", "react"] will match any appgrammar whose tech stack includes either typescript or react (OR matching, not AND).

Auto-Injection via Team MCP Connections​

Conventions are injected automatically when the appgrammar belongs to a team. There are two ways to associate an appgrammar with a team:

  1. Explicit team_id parameter -- pass team_id on each tool call (appgrammar_create, appgrammar_fork, etc.)
  2. Team-scoped MCP connection -- set the X-Team-Id header in your MCP configuration, and all tool calls through that connection inherit the team context

The second approach is recommended for teams. Configure it once in your MCP settings, and every appgrammar created through that connection automatically receives team conventions at execution time.

# All appgrammars created through this connection belong to the team
claude mcp add --transport http appgrammar-myteam https://appgrammar.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "X-Team-Id: YOUR_TEAM_UUID"

The MCP & Hooks page has a Team scope selector that generates the correct configuration for your IDE. See MCP Token Management for details.