Agent Commits Specification

Version: 1.0.0 Status: Draft Last Updated: 2025-02-01

Abstract

This specification defines a structured commit message format for AI-authored code changes. The format enables human reviewers to understand the intent behind changes, verify alignment with requests, and maintain accountability in AI-assisted development workflows.

Terminology
Commit Message Format
Fields
Grammar
Examples
Reviewer Guidelines
Implementation Notes
Changelog

Terminology

Agent: An AI system that writes or modifies code (e.g., Claude, GPT, Copilot)
Human: The person who requested the change and/or reviews the commit
Intent: The original request or goal expressed by the human
Plan: The agent's strategy for accomplishing the intent
Verification: Evidence that the changes work as intended

Commit Message Format

An Agent Commit message consists of:

Subject line (required) - Prefixed summary
Blank line (required if body present)
Body (required) - Structured fields describing the change

Subject Line

[agent] <type>: <description>

Or without type:

[agent] <description>

The [agent] prefix is required and identifies the commit as AI-authored
The optional <type> follows conventional commit types
The <description> is a concise summary (50 characters recommended, 72 max)

Body Structure

The body contains labeled fields, each starting with a field name followed by a colon:

Intent: <what the human requested>

Plan:
- <step 1>
- <step 2>
- ...

Changes:
- <file>: <description>
- ...

Verified: <verification status>

Fields

Required Fields

`Intent`

The original request from the human, paraphrased in the agent's understanding.

Purpose: Allows reviewers to verify the agent understood the request correctly.

Format: Single line or short paragraph.

Examples:

Intent: User requested a function to validate email addresses
Intent: Fix the bug where login fails after password reset
Intent: Refactor the payment module to use the new Stripe API

`Plan`

The agent's strategy for accomplishing the intent, expressed as concrete steps.

Purpose: Shows the agent's reasoning and allows reviewers to catch flawed approaches before examining code.

Format: Bulleted list of steps taken.

Examples:

Plan:
- Add regex validation for email format
- Check for disposable email domains
- Return structured validation result with error messages

`Changes`

Files modified with brief explanations of what changed and why.

Purpose: Provides a roadmap for code review and documents the scope of changes.

Format: Bulleted list with <filepath>: <description> pattern.

Examples:

Changes:
- src/utils/email.ts: New email validation function
- src/utils/email.test.ts: Unit tests for validation
- src/constants/domains.ts: List of disposable email domains

`Verified`

How the agent verified the changes work correctly.

Purpose: Documents testing performed and helps reviewers assess confidence level.

Format: Single line describing verification status.

Examples:

Verified: All tests passing, manual verification complete
Verified: Unit tests added and passing
Verified: Type checking passes, no runtime testing performed
Verified: Unable to verify - no test infrastructure available

Optional Fields

`Context`

Background information relevant to understanding the change.

Format: Free-form text explaining relevant context.

Example:

Context: This API was deprecated in v2.0 and removed in v3.0. The
codebase was still using v2 patterns which caused the failure.

`Alternatives`

Other approaches considered and why they were rejected.

Format: Bulleted list of alternatives with reasoning.

Example:

Alternatives:
- Could use a third-party validation library, but adds dependency for simple use case
- Could use HTML5 email input validation, but need server-side validation anyway

`Limitations`

Known limitations or edge cases not handled.

Format: Bulleted list or paragraph.

Example:

Limitations:
- Does not validate that the email domain has valid MX records
- International email addresses (non-ASCII) not supported

`References`

Links to documentation, issues, or discussions relevant to the change.

Format: Bulleted list of URLs or references.

Example:

References:
- https://github.com/org/repo/issues/123
- RFC 5321 (SMTP specification)

Grammar

The following ABNF-style grammar formally defines the commit message format:

commit          = subject-line CRLF CRLF body

subject-line    = prefix SP [type ":"] SP description
prefix          = "[agent]"
type            = "feat" / "fix" / "docs" / "style" / "refactor" /
                  "perf" / "test" / "build" / "ci" / "chore"
description     = 1*72VCHAR

body            = intent-field CRLF CRLF
                  plan-field CRLF CRLF
                  changes-field CRLF CRLF
                  verified-field
                  [CRLF CRLF optional-fields]

intent-field    = "Intent:" SP intent-text
intent-text     = 1*(%x20-7E / CRLF SP SP)  ; Allow wrapped lines

plan-field      = "Plan:" CRLF plan-items
plan-items      = 1*(plan-item)
plan-item       = "- " item-text CRLF

changes-field   = "Changes:" CRLF change-items
change-items    = 1*(change-item)
change-item     = "- " filepath ": " change-desc CRLF
filepath        = 1*(%x21-39 / %x3B-7E)     ; Path characters (no colon)
change-desc     = 1*VCHAR

verified-field  = "Verified:" SP verified-text
verified-text   = 1*(%x20-7E)

optional-fields = *(optional-field CRLF CRLF)
optional-field  = context-field / alternatives-field /
                  limitations-field / references-field

context-field   = "Context:" SP 1*(%x20-7E / CRLF)
alternatives-field = "Alternatives:" CRLF 1*(plan-item)
limitations-field  = "Limitations:" CRLF 1*(plan-item)
references-field   = "References:" CRLF 1*(plan-item)

Examples

Simple Bug Fix

[agent] fix: Resolve null pointer in user lookup

Intent: Fix crash when looking up deleted users

Plan:
- Add null check before accessing user properties
- Return appropriate error response for missing users
- Add test case for deleted user scenario

Changes:
- src/services/user.ts: Added null check in getUserById
- src/services/user.test.ts: Added test for deleted user lookup

Verified: All tests passing including new edge case test

New Feature

[agent] feat: Add CSV export for reports

Intent: User needs to export monthly reports as CSV files for accounting

Plan:
- Create CSV serialization utility
- Add export endpoint to reports API
- Include all report fields with proper escaping
- Add download button to reports UI

Changes:
- src/utils/csv.ts: New CSV serialization with proper escaping
- src/api/reports.ts: Added GET /reports/:id/export endpoint
- src/components/ReportView.tsx: Added export button
- src/utils/csv.test.ts: Unit tests for CSV edge cases

Verified: Manual export test successful, unit tests passing

Limitations:
- Large reports (>100k rows) may timeout; pagination not implemented
- Unicode characters preserved but not tested extensively

Refactoring

[agent] refactor: Migrate from callbacks to async/await

Intent: Modernize the data layer to use async/await instead of callbacks

Plan:
- Convert callback-based functions to return Promises
- Update callers to use async/await syntax
- Maintain backward compatibility during transition
- Remove deprecated callback signatures

Changes:
- src/data/database.ts: Converted all methods to async
- src/data/cache.ts: Converted to async with Promise wrapper
- src/services/*.ts: Updated all database callers
- src/types/database.d.ts: Updated type definitions

Verified: All existing tests passing, no runtime errors in dev

Context: The codebase mixed callbacks and promises inconsistently.
This refactor standardizes on async/await throughout the data layer.

Alternatives:
- Could promisify incrementally, but creates inconsistent patterns
- Could use a library like Bluebird, but native promises sufficient

Documentation Update

[agent] docs: Update API documentation for v2 endpoints

Intent: Document the new v2 API endpoints added last sprint

Plan:
- Add OpenAPI specs for new endpoints
- Update README with v2 migration guide
- Add code examples for common use cases

Changes:
- docs/api/openapi.yaml: Added v2 endpoint specifications
- docs/README.md: Added v2 migration section
- docs/examples/v2-migration.md: New migration guide with examples

Verified: OpenAPI spec validates, examples tested against dev server

Multi-file Complex Change

[agent] feat: Implement real-time notifications system

Intent: Add WebSocket-based notifications for order status updates

Plan:
- Set up WebSocket server alongside existing HTTP server
- Create notification service for managing connections
- Add event emitters for order status changes
- Build notification UI component with connection handling
- Handle reconnection and offline scenarios

Changes:
- src/server/websocket.ts: WebSocket server setup and connection handling
- src/services/notifications.ts: Notification dispatch and subscription management
- src/services/orders.ts: Added event emission on status changes
- src/hooks/useNotifications.ts: React hook for notification subscription
- src/components/NotificationBell.tsx: UI component with badge counter
- src/components/NotificationList.tsx: Dropdown list of recent notifications
- package.json: Added ws dependency

Verified: Manual testing of full flow complete, unit tests for services passing

Context: Previous polling-based approach caused unnecessary server load.
WebSocket provides instant updates and reduces API calls by ~80%.

Limitations:
- No message persistence; missed notifications during disconnect are lost
- Single server only; horizontal scaling requires Redis pub/sub (not implemented)

References:
- https://github.com/org/repo/issues/456
- Internal RFC: Real-time Architecture Decision

Reviewer Guidelines

When reviewing an Agent Commit, follow this process:

1. Verify Intent Alignment

Does the Intent match what you actually requested?
Are there misunderstandings in the agent's interpretation?
If the intent is unclear or wrong, stop and clarify before reviewing code

2. Evaluate the Plan

Is the approach reasonable for the problem?
Are there obvious issues or oversights in the strategy?
Would you have taken a different approach? Consider why.

3. Check Changes Scope

Do the changed files match the plan?
Are there unexpected files modified?
Are there files that should have been changed but weren't?

4. Assess Verification

What level of testing was performed?
Are there gaps in verification that need manual testing?
Should you request additional tests?

5. Review Code

Only after the above checks pass, review the actual code changes with the context of the plan in mind.

Red Flags

Watch for these warning signs in Agent Commits:

Vague intent: "User wanted improvements" (what improvements?)
Missing plan steps: Actual changes don't match the plan
Scope creep: Changes beyond what was requested
Weak verification: "Should work" or "Not tested"
No limitations: Complex changes rarely have zero caveats

Implementation Notes

For Tool Authors

When building tools that parse Agent Commits:

The [agent] prefix is the primary identifier
Fields may appear in any order after the subject
Unknown fields should be preserved, not rejected
Multi-line field values are indented with two spaces
Empty lines separate fields

For AI Agents

When generating Agent Commits:

Always include the [agent] prefix
Paraphrase the intent in your own understanding
List concrete steps taken, not general descriptions
Be honest about verification level
Include limitations you're aware of
When uncertain, say so explicitly

Parsing Considerations

The subject line can be identified by:

^\[agent\](\s+\w+:)?\s+.+$

Fields can be extracted with:

^(Intent|Plan|Changes|Verified|Context|Alternatives|Limitations|References):

Changelog

v1.0.0 (2025-02-01)

Initial specification release
Defined required fields: Intent, Plan, Changes, Verified
Defined optional fields: Context, Alternatives, Limitations, References
Added formal grammar (ABNF-style)
Added examples for common scenarios
Added reviewer guidelines

Agent Commits Specification

Abstract

Table of Contents

Terminology

Commit Message Format

Subject Line

Body Structure

Fields

Required Fields

Intent

Plan

Changes

Verified

Optional Fields

Context

Alternatives

Limitations

References

Grammar

Examples

Simple Bug Fix

New Feature

Refactoring

Documentation Update

Multi-file Complex Change

Reviewer Guidelines

1. Verify Intent Alignment

2. Evaluate the Plan

3. Check Changes Scope

4. Assess Verification

5. Review Code

Red Flags

Implementation Notes

For Tool Authors

For AI Agents

Parsing Considerations

Changelog

v1.0.0 (2025-02-01)

`Intent`

`Plan`

`Changes`

`Verified`

`Context`

`Alternatives`

`Limitations`

`References`