Initial commit

commands/atomic-commit/group-files.md

@@ -0,0 +1,209 @@
+# Operation: Group Files
+
+Group related files together for atomic commits.
+
+## Parameters from $ARGUMENTS
+
+- `strategy:type|scope|feature` - Grouping strategy (default: type)
+- `show:all|summary` - Output detail level (default: summary)
+
+## Workflow
+
+### Step 1: Get Changed Files
+
+Invoke Bash to get file list:
+```bash
+git status --porcelain
+git diff --cached --name-only
+git diff --name-only
+```
+
+Capture complete list of changed files.
+
+### Step 2: Execute File Grouper
+
+Run the file grouper script with selected strategy:
+```bash
+.claude/plugins/git-commit-assistant/commands/atomic-commit/.scripts/file-grouper.sh <strategy>
+```
+
+### Step 3: Parse Grouping Results
+
+Process grouper output based on strategy:
+
+**Strategy: type**
+Groups files by commit type:
+- `feat`: New features or enhancements
+- `fix`: Bug fixes
+- `docs`: Documentation changes
+- `style`: Formatting, whitespace
+- `refactor`: Code restructuring
+- `test`: Test additions or changes
+- `chore`: Build, dependencies, tooling
+
+**Strategy: scope**
+Groups files by module/component:
+- Extract scope from file path
+- Group by common directory structure
+- Identify module boundaries
+- Example: `auth/`, `api/`, `ui/`, `utils/`
+
+**Strategy: feature**
+Groups files by related functionality:
+- Analyze dependencies between files
+- Group interdependent changes
+- Identify feature boundaries
+- Requires dependency analysis
+
+### Step 4: Validate Groups
+
+Check each group for atomicity:
+- Single logical purpose
+- Reasonable size (≤10 files per group)
+- Clear scope boundary
+- Independent from other groups
+
+### Step 5: Generate Output
+
+Create structured grouping report:
+
+**Summary format:**
+```
+📦 FILE GROUPS (strategy: type)
+
+Group 1: feat (8 files)
+  src/auth/oauth.ts
+  src/auth/tokens.ts
+  src/config/oauth.config.ts
+  ...
+
+Group 2: fix (3 files)
+  src/api/endpoints.ts
+  src/api/validation.ts
+  tests/api.test.ts
+
+Group 3: docs (2 files)
+  README.md
+  docs/authentication.md
+
+Total: 3 groups, 13 files
+```
+
+**Detailed format (show:all):**
+```
+📦 GROUP 1: feat (8 files)
+
+Files:
+  ✓ src/auth/oauth.ts (+145, -0)
+  ✓ src/auth/tokens.ts (+78, -0)
+  ✓ src/auth/providers/github.ts (+95, -0)
+  ✓ src/auth/providers/google.ts (+92, -0)
+  ✓ src/config/oauth.config.ts (+34, -0)
+  ✓ src/types/auth.types.ts (+56, -0)
+  ✓ tests/auth/oauth.test.ts (+123, -0)
+  ✓ tests/auth/tokens.test.ts (+67, -0)
+
+Scope: auth
+Purpose: OAuth 2.0 implementation
+Dependencies: None
+Atomic: ✅ Yes
+
+Suggested commit:
+  feat(auth): implement OAuth 2.0 authentication
+```
+
+## Output Format
+
+Return structured groupings:
+```yaml
+strategy: type|scope|feature
+groups:
+  - id: 1
+    type: feat|fix|docs|etc
+    scope: module_name
+    files: [list]
+    stats:
+      file_count: number
+      additions: number
+      deletions: number
+    atomic: true|false
+    suggested_message: "commit message"
+summary:
+  total_groups: number
+  total_files: number
+  ready_for_commit: true|false
+```
+
+## Error Handling
+
+- **No changes**: "No files to group. Make changes first."
+- **Invalid strategy**: "Invalid strategy. Use: type, scope, or feature"
+- **Grouping failed**: "Could not group files. Check git status."
+- **Too many groups**: "Warning: 10+ groups detected. Consider broader grouping."
+
+## Grouping Strategies Explained
+
+### Type-based Grouping
+Groups files by conventional commit type. Best for:
+- Mixed-type changes
+- Clear type boundaries
+- Standard workflow
+
+Algorithm:
+1. Analyze diff content for each file
+2. Detect commit type from changes
+3. Group files of same type
+4. Validate each group
+
+### Scope-based Grouping
+Groups files by module/component. Best for:
+- Changes across multiple modules
+- Modular codebase structure
+- Component isolation
+
+Algorithm:
+1. Extract directory structure
+2. Identify module boundaries
+3. Group files by module
+4. Validate scope coherence
+
+### Feature-based Grouping
+Groups files by related functionality. Best for:
+- Complex feature implementation
+- Interdependent changes
+- Logical feature units
+
+Algorithm:
+1. Analyze file dependencies
+2. Build dependency graph
+3. Group connected components
+4. Validate feature boundaries
+
+## Examples
+
+**Example 1: Type grouping**
+```bash
+/atomic-commit group strategy:type
+→ Groups: feat (5), fix (2), docs (1)
+```
+
+**Example 2: Scope grouping**
+```bash
+/atomic-commit group strategy:scope show:all
+→ Detailed groups by module
+```
+
+**Example 3: Feature grouping**
+```bash
+/atomic-commit group strategy:feature
+→ Groups by related functionality
+```
+
+## Integration Notes
+
+This operation is typically called:
+1. After `analyze-splitting` recommends splitting
+2. Before `suggest-commits` generates messages
+3. As part of `interactive-split` workflow
+
+Results feed into commit suggestion and sequence planning.