Implement CLI command atomcommit plan to analyze git working tree and produce atomic commit plan

.gitignore

@@ -0,0 +1,17 @@
+# Generated fixture repos - run setup script to recreate
+fixtures/*-repo
+
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+build/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

README.md

@@ -1,28 +1,141 @@
 # atomcommit
 
-atomcommit generated by StackForge.
+Deterministic local CLI that analyzes a git working tree and produces an atomic commit plan in Markdown/JSON.
 
 ## Status
 
 This repository is early-stage. Confirm the current support, release, and
 security posture before using it in production.
 
+## Overview
+
+`atomcommit` inspects your local git diff (`git diff --name-status` and `git diff --numstat`) and produces a **deterministic atomic commit plan**. It groups related files into suggested commit slices and assigns risk flags so you can craft reviewable, focused commits.
+
+Key features:
+- **No repo mutation** — reads git diff metadata only, never modifies your working tree
+- **Deterministic output** — same changes always produce the same plan
+- **Risk flagging** — highlights deletions, renames, binary files, and large changes
+- **Grouped commits** — files grouped by type: source code, tests, documentation, CI automation, and more
+- **Suggested commit messages** — each group gets a meaningful commit summary
+
 ## Install
 
 ```sh
 pnpm install
 ```
 
-## Use
+## Usage
+
+### Default plan command
 
-Run the default deterministic handoff command from a repo with local changes:
+From a repo with local changes:
 
 ```sh
 atomcommit
 ```
 
-This is equivalent to `atomcommit plan` and prints a Markdown atomic commit plan.
-Use `atomcommit --json` only when another tool needs machine-readable output.
+This is equivalent to:
+
+```sh
+atomcommit plan
+```
+
+Both commands print a Markdown-formatted atomic commit plan to stdout.
+
+### JSON output (for tooling)
+
+Use `--json` when another tool needs machine-readable output:
+
+```sh
+atomcommit --json
+```
+
+### Help
+
+```sh
+atomcommit --help
+```
+
+## Example
+
+Given a working tree with changes across multiple file types:
+
+```sh
+$ atomcommit
+
+# Atomic Commit Plan
+
+- Files changed: 9
+- Suggested commits: 4
+
+## 1. Update ci and repository automation
+
+Suggested commit message: `Update ci and repository automation`
+
+Groups 1 file under ci and repository automation.
+
+Files:
+- modified: .github/workflows/ci.yml (+3/-1)
+
+## 2. Update documentation
+
+Suggested commit message: `Update documentation`
+
+Groups 3 files under documentation.
+
+Files:
+- renamed: CONTRIBUTING.md (from README.md) (+0/-0)
+- added: docs/api.md (+5/-0)
+- modified: docs/intro.md (+2/-2)
+
+Risk flags: rename
+
+## 3. Update source code
+
+Suggested commit message: `Update source code`
+
+Groups 3 files under source code.
+
+Files:
+- modified: src/app.js (+2/-1)
+- deleted: src/asset.bin (+0/-2)
+- modified: src/utils.js (+5/-2)
+
+Risk flags: deletion
+
+## 4. Update tests
+
+Suggested commit message: `Update tests`
+
+Groups 2 files under tests.
+
+Files:
+- modified: test/app.test.js (+1/-0)
+- added: test/utils.test.js (+4/-0)
+```
+
+### Grouping Logic
+
+Files are grouped by path and extension:
+
+| Group | Matching Pattern |
+|---|---|
+| CI and repository automation | `.github/*`, CI workflows |
+| Documentation | `docs/*`, `*.md` files |
+| Tests | `test/*`, `*.test.js`, `*.test.*` |
+| Source code | `src/*`, `*.js` source files |
+| Root files | top-level files not matching other patterns |
+
+### Risk Flags
+
+The plan flags certain changes for extra review attention:
+
+| Flag | Trigger |
+|---|---|
+| `deletion` | File deleted from working tree |
+| `rename` | File renamed/moved |
+| `binary-file` | Binary file change (no text stats) |
+| `large-change` | Combined additions + deletions ≥ 400 lines |
 
 ## Verify
 
@@ -32,7 +145,30 @@ Run the local validation script before opening a pull request:
 bash scripts/validate.sh
 ```
 
-`scripts/validate.sh` runs the repository's standard local checks when they are defined and will also run `agent-qc ready` when `agent-qc` is installed. Missing `agent-qc` is treated as a skip, not a failure.
+This runs the package test suite and checks for required files. The script will also run `agent-qc ready` when `agent-qc` is installed. Missing `agent-qc` is treated as a skip, not a failure.
+
+Run tests directly:
+
+```sh
+npm test
+```
+
+## Fixture Repositories
+
+The `fixtures/` directory contains deterministic test repos. To recreate:
+
+```sh
+bash fixtures/setup-mixed-changes.sh
+```
+
+Then test against the fixture:
+
+```sh
+cd fixtures/mixed-changes-repo
+atomcommit
+```
+
+See [fixtures/README.md](fixtures/README.md) for details.
 
 ## Contributing
 

docs/README.md

@@ -4,10 +4,52 @@ This directory holds project documentation.
 
 ## Contents
 
+- [Product Requirements Document](PRD.md) — product vision and V1 scope
+- [Task Brief](TASKS.md) — current development tasks and verification targets
+- [Orchestration](ORCHESTRATION.md) — handoff and wave dispatch notes
 - [Contributing guide](../CONTRIBUTING.md)
 - [Security policy](../SECURITY.md)
 - [Agent instructions](../AGENTS.md)
 
-## Additional docs
+## Decision Log: Grouping Logic and Risk Flags
 
-For a hosted documentation site, see the `docs-site/` directory if present.
+### Grouping Logic
+
+The `atomcommit plan` command groups files into suggested commits based on file path and extension. This makes each commit focused on a single concern (e.g., documentation, tests, source code).
+
+**Current grouping rules** (defined in `src/index.js`):
+
+| Group | Pattern Matching |
+|---|---|
+| CI and repository automation | Files under `.github/` directory |
+| Documentation | Files under `docs/` or ending in `.md` |
+| Tests | Files under `test/` or matching `*.test.js` pattern |
+| Source code | Files under `src/` or ending in `.js` |
+| Root files | Top-level files not matching other patterns |
+
+**Rationale**: These groups reflect common development practices where related changes are co-located. For example, documentation changes are typically reviewed together, and test changes should be separate from production code.
+
+### Risk Flags
+
+Deterministic flags are assigned based on the git change type and file characteristics:
+
+| Flag | Trigger Condition |
+|---|---|
+| `deletion` | Git status `D` (file deleted) |
+| `rename` | Git status `R` (file renamed/moved) |
+| `binary-file` | File has no text stats (binary content) |
+| `large-change` | Total additions + deletions ≥ 400 lines |
+
+**Rationale**: These flags highlight changes that typically require extra review attention:
+- **Deletions** may remove functionality that other code depends on
+- **Renames** can break imports and references
+- **Binary files** are harder to review in diffs
+- **Large changes** indicate complex work that may benefit from smaller commits
+
+### Future Enhancements
+
+Possible future grouping improvements:
+- Custom rules via configuration file (`.atomcommitrc`)
+- Semantic grouping based on co-change history
+- Override grouping for specific paths
+- Language-specific grouping rules

fixtures/README.md

@@ -0,0 +1,16 @@
+# Fixture Repositories
+
+These are deterministic fixture repositories used for validating the `atomcommit plan` CLI.
+
+## Mixed Changes Fixture
+
+The `setup-mixed-changes.sh` script creates a temporary repository with multiple types of changes:
+- Modified source files
+- New test files
+- Documentation changes
+- CI/CD configuration changes
+- Binary file additions
+- Deleted files
+- Renamed files
+
+This exercises all grouping logic, risk flagging, and commit message suggestion.