Commit Messages

Overview

Every change in Supaspec — whether made by a human or an AI agent — creates a versioned commit with a structured message. This is similar to Git commits but richer, with three fields:

Field	Required	Description
message	Yes	Short summary, like a git commit subject line
description	No	Longer explanation of what changed and why
prompt	No	What the user asked the agent to do (agent-provided)

The message Field

A short, imperative summary of the change. Think of it as a git commit subject line.

Good examples:

• "Add database schema for user auth"
• "Restructure around server/client component split"
• "Add caching strategy for GitHub API calls"
• "Status changed to approved"

Bad examples:

• "Updated the file" (too vague)
• "Changes" (not descriptive)
• "I made some improvements to the architecture section" (not imperative, too long)

The description Field

An optional longer explanation of what changed and why. This is the commit body.

Example:

message: "Add Stytch auth implementation details"
description: "Added magic link flow, session middleware code, and API key
  validation logic based on actual codebase implementation. Removed placeholder
  text about 'TBD auth provider' and replaced with concrete Stytch integration."

The prompt Field

For agent-authored changes, this records what the user prompted the agent to do. This creates an audit trail linking human intent to agent output.

Example:

message: "Restructure around server/client component split"
prompt: "Read the codebase and update the architecture section to match reality"

This field helps answer: "Why did the agent make this change?" The answer is in the prompt.

How It Appears in the UI

In the revision log, each entry shows:

v4 | Claude Code | "Add caching strategy for API calls"
    Prompt: "Review architecture for performance issues"
    Added Redis caching layer documentation for frequently
    accessed API endpoints...

For Humans

When editing via the web UI, you'll see a commit dialog with:

• Message (required) — what you changed
• Description (optional) — why you changed it

There's no prompt field for human edits — it's only for agent attribution.

For Agents (MCP)

The update_section and create_section MCP tools require message and accept optional description and prompt parameters. The MCP tool descriptions instruct agents to write clear, descriptive messages.

Agents are remarkably good at writing meaningful commit messages when the tool description sets clear expectations.

Tips

1. Be specific — "Add Redis caching for /api/sections endpoint" is better than "Add caching"
2. Use imperative mood — "Add", "Fix", "Update", "Remove", not "Added", "Fixed"
3. Include the prompt — agents should always pass the user's original prompt
4. Keep messages under 72 characters — just like git commit subjects
5. Use description for detail — anything beyond a one-line summary goes in the description