spec: add agent standardization refactor specification [750f25]

CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Breaking Changes
+
+#### Removed Manual Fallback Mode
+
+The `--no-ai` flag and rule-based fallback generation have been removed. commitment is now AI-only, providing consistent, high-quality commit messages through AI agents.
+
+**Migration Guide:**
+
+If you previously used `--no-ai`:
+
+1. **Install an AI CLI** (if not already installed):
+   - **Claude CLI** (recommended): https://www.anthropic.com/claude/cli
+   - **Codex CLI**: https://github.com/tom-doerr/codex_cli
+   - **Gemini CLI**: https://ai.google.dev/gemini-api/docs/cli
+
+2. **Remove the `--no-ai` flag** from your commands and scripts
+
+3. **Update git hooks** (if manually configured):
+   ```bash
+   # Before
+   npx commitment --no-ai --message-only > "$1"
+
+   # After
+   npx commitment --message-only > "$1"
+   ```
+
+**Why This Change?**
+
+- AI-generated messages are consistently higher quality than rule-based alternatives
+- Eliminates ~200 LOC of maintenance burden
+- Simplifies the codebase and user experience
+- Aligns with commitment's "AI-first" philosophy
+
+If an AI CLI is not available, commitment will display clear error messages with installation instructions.
+
+### Added
+
+- **`--quiet` flag**: Suppress progress messages (useful for scripting)
+  ```bash
+  npx commitment --quiet
+  ```
+- **Prompts module**: Extracted prompt generation logic to `src/prompts/` for better testability and maintainability
+- **Standardized agent execution**: All agents (Claude, Codex, Gemini) now use consistent CLI execution patterns
+
+### Changed
+
+- **Progress messages now visible in git hooks**: By default, commitment shows "🤖 Generating commit message with [agent]..." during git commit operations (use `--quiet` to suppress)
+- **Codex agent refactored**: Now uses direct CLI execution (stdin/args) instead of temp file I/O, reducing from ~160 LOC to ~70 LOC
+
+### Removed
+
+- **`--no-ai` CLI flag**: No longer supported (see migration guide above)
+- **Rule-based fallback**: Removed manual commit message generation methods
+- **Manual file categorization**: LLMs handle this more effectively
+
+## [0.15.1] - 2025-11-03
+
+### Fixed
+
+- Update script name documentation from `type-check` to `check-types`
+
+## [0.15.0] - 2025-11-03
+
+### Changed
+
+- Clean script no longer removes node_modules
+
+---
+
+[Unreleased]: https://github.com/arittr/commitment/compare/v0.15.1...HEAD
+[0.15.1]: https://github.com/arittr/commitment/compare/v0.15.0...v0.15.1
+[0.15.0]: https://github.com/arittr/commitment/releases/tag/v0.15.0

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code and other AI coding agents when worki
 
 ## Project Overview
 
-**commitment** is an AI-powered commit message generator with intelligent fallback. It uses AI agents (Claude CLI or Codex CLI) to generate high-quality, conventional commit messages from git diffs, with a rule-based fallback for when AI is unavailable.
+**commitment** is an AI-powered commit message generator. It uses AI agents (Claude CLI, Codex CLI, or Gemini CLI) to generate high-quality, conventional commit messages from git diffs.
 
 **Architecture Philosophy:** Selective abstraction. Simple base class (≤3 extension points) + pure utilities, but no factories or provider chains. Agents extend BaseAgent (~40-60 LOC each). One-command setup with `commitment init` for automatic hook installation.
 
@@ -28,7 +28,7 @@ bun run clean
 ### Code Quality
 
 ```bash
-# Run linting (type-check + format-check + biome)
+# Run linting (check-types + format-check + biome)
 bun run lint
 
 # Fix linting issues automatically
@@ -41,7 +41,7 @@ bun run format
 bun run format:check
 
 # Type checking
-bun run type-check
+bun run check-types
 ```
 
 ### Testing
@@ -272,11 +272,17 @@ import { hasContent } from './utils/guards.js';
 - **CLI** (`src/cli.ts`): Command-line interface (~200 lines)
   - **Init Command** (`src/cli/commands/init.ts`): Automatic hook installation with auto-detection
   - **CLI Schemas** (`src/cli/schemas.ts`): CLI option validation
-- **Generator** (`src/generator.ts`): CommitMessageGenerator class with AI and rule-based generation
-- **Agents** (`src/agents/`): Standalone AI agent implementations (no base classes)
-  - `claude.ts` - Claude CLI agent (~80 LOC, self-contained)
-  - `codex.ts` - Codex CLI agent (~80 LOC, self-contained)
-  - `types.ts` - Minimal Agent interface
+- **Generator** (`src/generator.ts`): CommitMessageGenerator class for AI-powered generation
+- **Agents** (`src/agents/`): AI agent implementations extending BaseAgent
+  - `base-agent.ts` - Abstract base class with template pattern (~80 LOC)
+  - `claude.ts` - Claude CLI agent (~40-60 LOC)
+  - `codex.ts` - Codex CLI agent (~40-60 LOC)
+  - `gemini.ts` - Gemini CLI agent (~40-60 LOC)
+  - `factory.ts` - Simple agent factory with ts-pattern (~30 LOC)
+  - `types.ts` - Agent interface and types
+- **Prompts** (`src/prompts/`): Prompt generation module
+  - `commit-message-prompt.ts` - Pure functions for building prompts
+  - `index.ts` - Barrel exports
 - **Schemas** (`src/types/schemas.ts`, `src/cli/schemas.ts`, `src/utils/git-schemas.ts`): Zod schemas for runtime validation
 - **Git Utilities** (`src/utils/git-schemas.ts`): Git output parsing and file categorization
   - `parseGitStatus()` - Parse and validate git status output
@@ -286,10 +292,10 @@ import { hasContent } from './utils/guards.js';
 
 ### Key Design Patterns
 
-1. **AI-First with Fallback**: Always try AI generation first, fall back to rule-based
+1. **AI-Only Architecture**: All commit messages generated by AI agents (Claude, Codex, or Gemini)
 2. **Conventional Commits**: All messages follow conventional commit format
-3. **Inline Agent Logic**: Each agent is standalone (~80 LOC) with all logic inline - no base classes, no factories
-4. **Direct Instantiation**: Simple if/else for agent selection - no auto-detection or provider chains
+3. **Template Method Pattern**: BaseAgent with ≤3 extension points, agents extend with minimal code (~40-60 LOC)
+4. **Simple Factory**: Type-safe agent instantiation with ts-pattern for exhaustiveness checking
 5. **One-Command Setup**: `commitment init` auto-detects and installs hooks
 6. **ESM-Only**: Built as ESM modules using latest TypeScript and Node.js features
 7. **Strict TypeScript**: All strict compiler options enabled
@@ -351,8 +357,8 @@ const options = validateCliOptions(rawOptions);
 
 // Use validated data internally (no need to re-validate)
 const generator = new CommitMessageGenerator({
-  enableAI: options.ai,
-  provider: buildProviderConfig(options),
+  agent: options.agent,
+  workdir: options.cwd,
 });
 ```
 
@@ -788,10 +794,9 @@ class CommitMessageGenerator {
 
   // Use cached validated config everywhere else
   async generate(options: CommitMessageOptions): Promise<string> {
-    // No re-validation needed
-    if (this.validatedConfig.enableAI) {
-      // ...
-    }
+    // No re-validation needed - generator is AI-only
+    const agent = this.createAgent(this.validatedConfig.agent);
+    return await agent.generate(prompt, this.validatedConfig.workdir);
   }
 }
 ```
@@ -1024,10 +1029,10 @@ npx commitment init [options]
 ### Core CLI Flags
 
 **Main Command Flags:**
-- `--agent <name>` - AI agent to use: claude, codex (default: "claude")
+- `--agent <name>` - AI agent to use: claude, codex, gemini (default: "claude")
 - `--dry-run` - Generate message without creating commit
 - `--message-only` - Output only the commit message (no commit)
-- `--no-ai` - Disable AI generation, use rule-based only
+- `--quiet` - Suppress progress messages (useful for scripting)
 - `--cwd <path>` - Working directory (default: current directory)
 
 **Init Command Flags:**
@@ -1155,16 +1160,25 @@ src/
 ├── generator.ts                # CommitMessageGenerator class
 ├── errors.ts                   # Consolidated error types (AgentError, GeneratorError)
 ├── index.ts                    # Public API exports (≤10 items)
-├── agents/                     # Agent system (simplified, no base classes)
+├── agents/                     # Agent system with BaseAgent template pattern
 │   ├── types.ts                # Agent interface and types
-│   ├── claude.ts               # Claude agent (~80 LOC, self-contained)
-│   ├── codex.ts                # Codex agent (~80 LOC, self-contained)
+│   ├── base-agent.ts           # Abstract base class (~80 LOC)
+│   ├── factory.ts              # Simple agent factory with ts-pattern (~30 LOC)
+│   ├── claude.ts               # Claude agent (~40-60 LOC)
+│   ├── codex.ts                # Codex agent (~40-60 LOC)
+│   ├── gemini.ts               # Gemini agent (~40-60 LOC)
 │   └── index.ts                # Agent exports
 ├── cli/                        # CLI modules
 │   ├── schemas.ts              # CLI option validation
+│   ├── helpers.ts              # Display and execution helpers (~80 LOC)
 │   └── commands/
 │       ├── init.ts             # Hook installation command
 │       └── index.ts            # Command exports
+├── prompts/                    # Prompt generation module
+│   ├── commit-message-prompt.ts # Pure prompt building functions
+│   ├── index.ts                # Barrel exports
+│   └── __tests__/
+│       └── commit-message-prompt.test.ts
 ├── eval/                       # Evaluation system (standalone, not tests)
 │   ├── run-eval.ts             # Main entry point script
 │   ├── runner.ts               # Pipeline orchestration
@@ -1194,9 +1208,10 @@ examples/
 
 docs/
 └── constitutions/
-    ├── current -> v2           # Symlink to current version
-    ├── v1/                     # Previous constitution
-    └── v2/                     # Current constitution (streamlined)
+    ├── current -> v3           # Symlink to current version
+    ├── v1/                     # First constitution
+    ├── v2/                     # Second constitution
+    └── v3/                     # Current constitution (selective abstraction)
         ├── meta.md
         ├── architecture.md
         ├── patterns.md

README.md

@@ -28,6 +28,7 @@ We all know we should write better commit messages. But we don't.
 - 🪝 **Hook integration** with husky, simple-git-hooks, or plain git hooks
 - 🌍 **Cross-platform** support for macOS, Linux, and Windows
 - 📦 **Zero config** works out of the box with sensible defaults
+- 🔕 **Quiet mode** for suppressing progress messages in scripts
 
 ## Quick Start
 
@@ -74,7 +75,7 @@ bun add -D @arittr/commitment
   - [Gemini CLI](https://geminicli.com/docs/) - Install with `npm install -g @google/gemini-cli`
 
 >[!IMPORTANT]
->commitment requires an AI CLI to function.
+>commitment is AI-only and requires an AI CLI to function. If you need commit message generation without AI, consider using a traditional commit template instead.
 
 ## Usage
 
@@ -147,8 +148,22 @@ test: update test naming conventions and mock patterns
 | `--agent <name>` | AI agent to use (`claude`, `codex`, or `gemini`) | `claude` |
 | `--dry-run` | Generate message without creating commit | `false` |
 | `--message-only` | Output only the commit message | `false` |
+| `--quiet` | Suppress progress messages (useful for scripting) | `false` |
 | `--cwd <path>` | Working directory | current directory |
 
+**Examples:**
+
+```bash
+# Use Gemini agent
+npx commitment --agent gemini
+
+# Preview message without committing
+npx commitment --dry-run
+
+# Suppress progress messages (for scripts)
+npx commitment --quiet
+```
+
 See [docs/CLI.md](./docs/CLI.md) for complete CLI reference.
 
 ### Hook Setup

docs/constitutions/v3/patterns.md

@@ -112,7 +112,7 @@ bun test --coverage
 bun test --watch
 
 # Type checking
-bun run type-check   # or bun tsc --noEmit
+bun run check-types   # or bun tsc --noEmit
 
 # Linting
 bun run lint

docs/constitutions/v3/testing.md

@@ -620,7 +620,7 @@ describe('Performance', () => {
 
 ```bash
 bun run lint      # Must pass
-bun run type-check # Must pass
+bun run check-types # Must pass
 bun test          # Must pass
 ```