> For the complete documentation index, see [llms.txt](https://docs.aviator.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aviator.co/verify/reference/spec-format.md).

# Spec format

Complete reference for Verify spec syntax.

### Structure

Every spec has a title and three required sections:

```markdown
# Title

## Intent
[description]

## Scope
[scope declarations]

## Acceptance Criteria
[list of criteria]

## Execution steps
[steps to execute]
```

### Title

Short description of the change. Appears in dashboard, PR checks, and audit trail.

```markdown
# Add user profile endpoint
```

### Intent

Plain-language description of what and why. Provides context for verification.

```markdown
## Intent
Public endpoint for retrieving basic user profile information.
Returns display name and avatar, but not email or internal IDs.
```

### Scope

Declares what the change may touch using three keywords.

#### Keywords

| Keyword  | Purpose                     | Required |
| -------- | --------------------------- | -------- |
| `modify` | Files to create or edit     | Yes      |
| `call`   | External services to access | No       |
| `forbid` | Prohibited files or actions | No       |

#### Syntax

```markdown
## Scope
-**modify:** `src/handlers/profile.go`, `src/models/user.go`
-**call:** `user-service`
-**forbid:** `src/auth/*`, database migrations
```

#### Glob patterns

| Pattern                | Matches                                      |
| ---------------------- | -------------------------------------------- |
| `src/handlers/*.go`    | .go files in src/handlers                    |
| `src/handlers/**/*.go` | .go files in src/handlers and subdirectories |
| `tests/*_test.go`      | Files ending in \_test.go in tests           |

### Acceptance Criteria

Checklist of requirements using markdown checkbox syntax.

```markdown
## Acceptance Criteria
-[ ] Endpoint: `GET /api/v1/users/{id}/profile`
-[ ] Returns 200 with profile data
-[ ] Response includes: display_name, avatar_url
-[ ] Response excludes: email, internal_id
-[ ] Returns 404 if user not found
```

Each criterion is checked independently during verification.

### Complete example

```markdown
# Add user profile endpoint

## Intent
Public endpoint for retrieving basic user profile information.
Returns display name and avatar, but not email or internal IDs.

## Scope
-**modify:** `src/handlers/profile.go`, `src/models/user.go`
-**call:** `user-service`
-**forbid:** `src/auth/*`, database migrations

## Acceptance Criteria
-[ ] Endpoint: `GET /api/v1/users/{id}/profile`
-[ ] Returns 200 with profile data
-[ ] Response includes: display_name, avatar_url
-[ ] Response excludes: email, internal_id
-[ ] Returns 404 if user not found

## Execution Steps

### Step 1: Define the response model
Create a model that only includes the allowed fields.

#### 1.1: Create UserProfile struct
Add a new struct in the models package that excludes sensitive fields.

- Create `UserProfile` struct in `src/models/user.go`
- Include only `display_name` and `avatar_url` fields
- Add JSON tags for serialization

### Step 2: Implement the handler
Create the HTTP handler that fetches and returns profile data.

#### 2.1: Create GetProfile handler
Add a handler function that retrieves user data and returns the public profile.

- Create `GetProfile` function in `src/handlers/profile.go`
- Parse user ID from URL path
- Call `user-service` to fetch user data

#### 2.2: Map to response model
Convert the internal user object to the public profile response.

- Map user fields to `UserProfile` struct
- Ensure `email` and `internal_id` are not included

```

### Validation errors

| Error                     | Fix                                       |
| ------------------------- | ----------------------------------------- |
| Missing required section  | Add Intent, Scope, or Acceptance Criteria |
| Empty acceptance criteria | Add at least one criterion                |
| Invalid scope keyword     | Use `modify`, `call`, or `forbid`         |
| Invalid glob pattern      | Check pattern syntax                      |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aviator.co/verify/reference/spec-format.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.