# Brief Agent Templates

This document provides templates for AI coding assistants to install Brief skill and instruction files in a project. Adapt file locations based on the repository's existing structure and conventions.

**Prerequisite**: Brief MCP must already be installed in your host (Cursor, Claude Code, VS Code, Claude Desktop, Codex, etc.). If it isn't yet, follow the host-native install steps in the [Brief MCP setup guide](https://usebrief.com/docs/mcp-setup/) first: that's the canonical source for MCP server configuration. This doc is only about the skill/instruction layer that lives *on top of* an already-connected MCP server.

---

## Detecting Agent Configuration

Check for existing agent configuration in the repository:

| Tool | Config Locations |
|------|-----------------|
| **Cursor** | `.cursor/`, `.cursorrules`, `.cursor/rules/` |
| **Claude Code** | `.claude/`, `CLAUDE.md`, `.claude/settings.json` |
| **Windsurf** | `.windsurfrules`, `.codeium/` |
| **Codex/OpenAI** | `codex.md`, `AGENTS.md`, `.codex/` |
| **Generic/Standard** | `AGENTS.md`, `.agents/`, `skills.md`, `.skills/` |

If no configuration exists, use the generic standard (`AGENTS.md` + `.brief/`).

---

## What to Create

Install Brief context by creating appropriate files. Adapt to existing patterns or use generic standard.

**Required:**
- Brief guidelines file (API reference and rules)
- Agent instructions (in existing rules file or new `AGENTS.md`)

**Optional (if repo supports skills/commands):**
- Context loading skill
- Decision guard skill  
- Onboard command

---

## File Templates

### 1. Brief Guidelines

Create in `.brief/brief-guidelines.md` (or integrate into existing rules file):

```markdown
# Brief Guidelines for AI Coding Agents

This repository uses Brief for product context, decisions, and documentation via MCP.

## Core Principles

1. **Call Brief before grepping the repo for product context.** Brief is the source of truth for service definition, goals, personas, decisions, features, customer insights, and product strategy. The codebase is the source of truth for implementation. Default to Brief tools for product questions; default to code search for implementation questions.
2. **Permission required for destructive operations.** Always ask the user before deleting or overwriting.
3. **Clear communication.** Explain what you're about to do before executing.

## Brief MCP Tools

Brief exposes a flat top-level tool surface plus one escape-hatch tool. Pick the right top-level tool when one exists; fall back to the escape hatch for rarer operations.

### Session-start tool

- `brief_get_onboarding_context`: **Call this at the start of every session.** Returns the strategic snapshot: decisions, personas, velocity, recent work, customer insights. Supports `scope: 'full' | 'product' | 'identity'`; default is `full`. Use `scope: 'identity'` for a cheap sanity check when you just need workspace id + name. Pass `scope: 'product'` to read just the product context. For features, call `brief_execute_operation` with `operation: 'list_features'`.

### Strategic conversation

- `brief_ask`: Multi-turn strategic conversation backed by Brief's full context. Use when the user asks open-ended product questions or when you need Brief to reason across its knowledge base. Supports `mode: 'advise' | 'check' | 'fast'`.
  - `advise` (default): deep product advice with tool use. If it returns a decision proposal, present it to the user and call `brief_record_decision` to request approval.
  - `check`: **pre-flight check, call with `mode: 'check'` before architectural changes to validate the approach against existing decisions.**
  - `fast`: quick lookups with no tool use.

### Onboarding-specific entry points

- `/brief-setup`: preferred first-run prompt on hosts that surface Brief prompts
- `/brief-welcome-back`: returning workspace on a new surface
- `brief_get_onboarding_context`: raw fallback when prompts are not surfaced
- `brief_ask` with `onboarding: true`: fresh coding-repo synthesis after reading the README, package/manifest files, and recent `git log --oneline -20`

### Decision lifecycle

- `brief_record_decision`: Submit a decision for user approval. The default `status` is `confirmed`; use `status: 'pending'` to propose a decision for later confirmation. Hosts that support MCP Apps show an approval card. After calling the tool, wait for the user's response. If the user says they cannot see the card, ask them to reply `approve`, `reject`, or `edit`; after an explicit `approve`, call `brief_execute_operation` with `operation: 'record_decision'` and the same decision fields.
- `brief_confirm_decision`: Transition a pending (proposed) decision to active. Takes `decision_id` (e.g. `D-123`). Use `brief_search` with `types: 'decision'` to find candidates.
- `brief_reject_decision`: Reject a pending decision with a required `rejection_reason`.
- `brief_archive_decision`: Archive an outdated decision by `id` (e.g. `D-123`).
- `brief_list_pending_decisions`: List decisions awaiting confirmation (status: proposed). **Prefer this** for the pending queue; use `brief_search` with `types: 'decision'` for keyword search across decision history.

### Search & browse

- `brief_search`: **Universal search.** Searches across decisions, documents, features, and other Brief content. For decision history, call `brief_search` with `types: 'decision'`. Panel-backed, MCP Apps hosts render results as an interactive card.
- `brief_browse`: Browse Brief folders and documents by path or folder ID.

### Document comments

- `brief_list_document_comments`: Read comments and replies on a document. Pass its UUID as `document_id`.
- `brief_create_document_comment`: Add a comment with `document_id` and `body`. Optionally pass `quote` with `text` to anchor it to a passage, or `parent_comment_id` to reply to a comment.

### Product context write

- `brief_update_product_context`: Pass the partial product context object in `config`; only provided fields are changed. Top-level keys: `productAddress`, `company`, `goals`, `velocity`, `team`, `metrics`. `productAddress` sets the public product URL used for crawling; changing it discards crawl and messaging data derived from the previous URL, so set it only when the user asks. Call `brief_get_onboarding_context` with `scope: 'product'` first to read the current state.

### Escape hatch

- `brief_execute_operation`: For operations that don't have a direct top-level tool. Takes `operation` (string) + `parameters` (object). **Prefer direct tools when they exist**: they have typed parameters and clearer descriptions, so the call is easier to get right.

Use the `brief_*` tool names above; removed aliases are not available.

Operations accessible **only** via `brief_execute_operation`:

- **Decision validation**: `guard_approach` (prefer `brief_ask` with `mode: 'check'` for most cases)
- **Documents**: `create_document` (folder_id required, call `get_folder_tree` first), `get_document`, `update_document`, `delete_document`, `move_document`
- **Folders**: `create_folder` (parent_id required), `get_folder`, `get_folder_tree`, `update_folder`, `delete_folder`, `move_folder`, `get_folder_documents`
- **Bulk**: `bulk_move`, `bulk_delete`
- **Personas & features**: `list_personas`, `list_features`

## Rules

1. **Session start**: call `brief_get_onboarding_context` before investigating the codebase for product questions.
2. **First-time setup**: if the host surfaces prompts, run `/brief-setup`. If prompts are unavailable, use `brief_get_onboarding_context`, then on a fresh coding repo send repo context to `brief_ask` with `onboarding: true`.
3. **Before architectural changes**: call `brief_ask` with `mode: 'check'` before auth / database / API / dependency / breaking changes. Brief validates the approach against existing decisions and flags conflicts.
4. **Searching decisions or docs**: use `brief_search` with `types: 'decision'` (or a comma-separated string for multiple types).
5. **Listing pending decisions**: call `brief_list_pending_decisions` when you need proposed decisions awaiting confirmation.
6. **Recording decisions**: call `brief_record_decision` and wait for the user. The default status is `confirmed`; pass `status: 'pending'` for later confirmation. If the user cannot see an approval card, ask for an `approve`, `reject`, or `edit` reply. Only after an explicit `approve`, call `brief_execute_operation` with `operation: 'record_decision'` and the same decision fields.
7. **Destructive operations**: ask the user first, execute only after approval.
8. **Document creation**: call `brief_execute_operation` with `operation: 'get_folder_tree'` first to get a valid `folder_id`, then `brief_execute_operation` with `operation: 'create_document'`.
9. **No raw JSON**: format responses for humans; don't dump JSON.
```

---

### 2. Agent Instructions

Create as `AGENTS.md` in project root, or integrate into existing `CLAUDE.md`, `.cursorrules`, or equivalent:

```markdown
# Brief Integration

This repository uses Brief for product context and decisions via MCP.

## Quick Start

Load Brief context at session start:
```
brief_get_onboarding_context {}
```

## First-time setup on a fresh coding repo

When the agent is opening a freshly connected project, prefer these entry points in order:

1. If the host surfaces Brief prompts, run `/brief-setup`.
2. If the workspace already exists and this is a new surface, run `/brief-welcome-back`.
3. If prompts are not surfaced, call `brief_get_onboarding_context` directly.
4. On a fresh coding repo, read the README, package/manifest files, and recent `git log --oneline -20`, then send one `brief_ask` call with `onboarding: true` and that evidence in `context`.

```javascript
brief_ask({
  question: "What should I know before building?",
  context: "<README summary + tech stack + recent commits + open questions>",
  onboarding: true
})
```

Use `onboarding: true` only on the first call from a fresh coding surface. Returning users on a new surface should prefer `/brief-welcome-back` or `brief_get_onboarding_context`.

## Workflow

### Before Starting Work
1. Load context via `brief_get_onboarding_context`
2. Search decisions related to the task
3. Review product goals and constraints

### Before Significant Changes
Call `brief_ask` with `mode: 'check'` before:
- Architectural changes (auth, database, APIs)
- Dependency changes
- Breaking changes

```javascript
brief_ask({
  question: "<description of what you plan to do>",
  mode: "check"
})
```

Brief validates the approach against existing decisions and flags conflicts.

Interpret response:
- ✅ NO CONFLICTS: Proceed
- ⚠️ POTENTIAL CONFLICT: Present the tension to the user
- ⚠️ CONFLICT DETECTED: Ask the user how to proceed

### After Work
- Record significant decisions made
- Update docs if scope changed

## Hard Rules

- ✅ Load Brief context at session start
- ✅ On first-time setup, prefer `/brief-setup`; if prompts are unavailable, use `brief_ask(..., onboarding: true)` on fresh coding repos
- ✅ Call `brief_ask` with `mode: "check"` before architectural changes
- ✅ Ask permission before destructive operations
- ❌ Never proceed with blocked changes without approval
```

---

### 3. Context Loading Skill

If the repo uses skills, create a Brief context skill:

```markdown
---
description: Load Brief business context into agent sessions
---

# Brief Context Skill

Loads comprehensive business context from Brief MCP.

## What It Retrieves

Calls `brief_get_onboarding_context` to get:

- **Product**: Service definition, customers, competitive advantages
- **Strategy**: Six-month goal
- **Personas**: Primary user types with needs and pain points
- **Work**: What's building, what's committed
- **Velocity**: Release frequency, throughput, cycle time
- **Decisions**: Recent architectural/business decisions

## Usage

Invoke at session start or when user asks about product context.

## Fallback

If Brief MCP unavailable:
- Report: "Brief MCP not connected. Working with code context only."
- Suggest connecting Brief for business context.
```

---

### 4. Decision Guard Skill

If the repo uses skills, create a decision validation skill:

```markdown
---
description: Validate approaches against Brief decisions
---

# Decision Guard Skill

Checks proposed approaches against existing decisions before implementation.

## When to Use

Before:
- Architectural changes (auth, database, API design)
- Dependency changes (switching libraries)
- Breaking changes to public APIs
- Changes to core workflows

## How to Use

```typescript
mcp__brief__brief_ask({
  question: "Description of what you plan to do",
  mode: "check",
})
```

`brief_ask` with `mode: "check"` is the decision-guard path: Brief validates the approach against existing decisions and flags conflicts.

## Response Types

- ✅ **NO CONFLICTS**: Proceed
- ⚠️ **POTENTIAL CONFLICT**: Present the tension to the user
- ⚠️ **CONFLICT DETECTED**: Ask the user how to proceed

## Best Practices

- Call early (during planning, not after implementation)
- Be specific in approach description
- If conflict found, present options to user
- Document override reason if proceeding despite conflict
```

---

### 5. Onboard Command

If the repo uses slash commands, create an onboard command:

```markdown
---
description: Load context and prepare for work
---

# /onboard

Load Brief context and prepare for work in this repository.

## What It Does

1. Calls `brief_get_onboarding_context` to load:
   - Product context (customers, goals, service)
   - User personas
   - Current work pipeline
   - Team velocity
   - Recent decisions

2. Reviews project guidelines

3. Reports readiness with summary

## Example Output

```
Onboarded to [Project Name].

**Product**: [Brief description]
**Current focus**: [What's being built]
**Key decisions**: 
- D-123: [Relevant decision]
- D-456: [Another decision]

Ready to work. What would you like me to help with?
```
```

---

### 6. Guardrails (Optional)

If the repo uses permission settings, add Brief-related guardrails:

```json
{
  "require_approval": [
    "mcp__brief__brief_execute_operation({\"operation\":\"delete_document\"*)",
    "mcp__brief__brief_execute_operation({\"operation\":\"delete_folder\"*)",
    "mcp__brief__brief_execute_operation({\"operation\":\"bulk_delete\"*)"
  ]
}
```

---

## Adaptation Notes

**Detection First:**
- Check for existing agent configuration before creating files
- Look for `.cursorrules`, `CLAUDE.md`, `AGENTS.md`, `codex.md`, or similar
- Check for existing skills folders (`.cursor/skills/`, `.claude/skills/`, `.skills/`)

**Merge When Possible:**
- Add Brief content to existing rules files rather than creating duplicates
- Append to existing `AGENTS.md` or `CLAUDE.md` if present
- Integrate guardrails into existing settings files

**Use Repo Conventions:**
- Match existing file structure for skills/commands
- Follow existing naming patterns
- Respect existing organization

**Generic Fallback:**
If no agent configuration exists, create minimal standard setup:
```
AGENTS.md           # Agent instructions with Brief workflow
.brief/
  brief-guidelines.md  # API reference and rules
```

**For Skills-Enabled Repos:**
Add skills following the repo's pattern, or use generic structure:
```
.skills/
  brief-context.md     # Context loading skill
  decision-guard.md    # Decision validation skill
```