CLI that turns LLM input into well-formatted Conventional Commits
docs(agents): add
+88
+88
AGENTS.md
+88
AGENTS.md
···
1
+
<!--
2
+
SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
3
+
4
+
SPDX-License-Identifier: CC0-1.0
5
+
-->
6
+
7
+
# AGENTS.md
8
+
9
+
This file provides guidance to AI coding agents when working with code in this repository.
10
+
11
+
## Development Commands
12
+
13
+
- **Build**: `just build` (outputs binary as `formatted-commit`)
14
+
- **Run during development**: `just run [flags]`
15
+
- **Format code**: `just fmt`
16
+
- **Update dependencies**: `go mod tidy`
17
+
- **Test**: `go test ./...`
18
+
19
+
Example usage:
20
+
21
+
```bash
22
+
just run -t feat -m "add validation" -T "Co-authored-by: Name <email>"
23
+
```
24
+
25
+
## Project Purpose
26
+
27
+
This is a CLI tool that formats git commit messages according to Conventional Commits specification and pipes them directly to `git commit -F -`. It enforces:
28
+
29
+
1. Subject length: max 50 characters in format `type(scope): message`
30
+
2. Body wrapping: strictly 72 columns using Markdown formatter
31
+
3. Trailer validation: follows git's trailer specification
32
+
33
+
## Architecture
34
+
35
+
Single-file CLI application (`main.go`) using:
36
+
37
+
- **cobra**: CLI framework for flags and commands
38
+
- **fang**: Charmbracelet's execution wrapper (provides version handling, etc.)
39
+
- Future: Will need a Markdown formatter for body text (likely from Charmbracelet ecosystem based on dependencies)
40
+
41
+
## Critical Implementation Details
42
+
43
+
### Subject Validation (50 char limit)
44
+
45
+
The subject is constructed as `type(scope): message` or `type: message` (when scope is empty). Breaking changes add a `!` after the type/scope like `type(scope)!: message`.
46
+
47
+
When validation fails, clearly mark where the subject exceeds 50 characters in error output.
48
+
49
+
### Body Formatting
50
+
51
+
The body (`-b` flag) must be:
52
+
53
+
1. Sanitised because it should only be basic text and bullets
54
+
2. Formatted as Markdown, properly wrapping bullets with hanging indents on
55
+
following lines like this
56
+
3. Strictly wrapped to 72 columns using a pure-Go formatter
57
+
4. Separated from subject by one blank line
58
+
5. Separated from trailers by one blank line
59
+
60
+
### Trailer Formatting (Critical)
61
+
62
+
Trailers follow git's specification precisely:
63
+
64
+
- Format: `Key: value` (newline-delimited pairs)
65
+
- No whitespace before or inside the key
66
+
- Any number of spaces/tabs allowed between key and separator `:`
67
+
- Values can be multiline with continuation lines starting with whitespace (RFC 822 folding)
68
+
- The trailer group must be:
69
+
- At the end of input, OR
70
+
- The last non-whitespace lines before a line starting with `---`
71
+
- Preceded by one or more empty/whitespace-only lines
72
+
73
+
Example valid trailer:
74
+
75
+
```
76
+
Co-authored-by: This is a very long value, with spaces and
77
+
newlines in it.
78
+
```
79
+
80
+
### Flag Nuance
81
+
82
+
- `-B` / `--breaking`: Boolean flag for breaking changes (adds `!` to subject)
83
+
- `-b` / `--body`: String flag for commit body text
84
+
- `-T` / `--trailer`: Repeatable flag for trailers
85
+
86
+
### Final Output
87
+
88
+
The formatted commit message must be piped to `git commit -F -` to read from stdin.