--- description: Organizes the commit history into a clean, logical structure. Invoked when the user wants to organize commits, clean up commit history, reorder commits, or runs /aido:3-organize-commits. disable-model-invocation: false --- # Organize the Commits Organize commits into a clean, logical history following project conventions. `SPEC.md` and `SPEC.md.draft` stand for the spec file and its draft: resolve them first, per "The Specification File" in `${CLAUDE_PLUGIN_ROOT}/guidelines/specification.md`. Load `${CLAUDE_PLUGIN_ROOT}/guidelines/language.md` and follow it in everything you write for a person. ## Step 0: Load Guidelines Before organizing commits, load: - `${CLAUDE_PLUGIN_ROOT}/guidelines/git-workflow.md` — all commit conventions in that file **must** be respected - `${CLAUDE_PLUGIN_ROOT}/guidelines/project-conventions.md` — then gather the host repository's conventions as it describes; Step 1 needs them to place `SPEC.md` - `${CLAUDE_PLUGIN_ROOT}/guidelines/specification.md` Do NOT skip this step. ## Step 1: Decide What Happens to `SPEC.md` Skip this step if the branch has no `SPEC.md`. The default is to **revert** it, so the specification stays in the branch history but leaves no file behind. Before proposing the commit structure, ask whether the user would rather keep it in the repository. **Find where it would belong**, in this order: 1. the host repository's `CLAUDE.md` or `AGENTS.md` — a place they name for specifications, design documents, decision records or other docs 2. an existing documentation folder — e.g. `docs/specs/`, `docs/design/`, `docs/adr/` or `docs/` — following how the files already there are named and organized 3. no documentation folder → offer only the default and a path the user types Name the file after the feature, in the folder's own naming style (e.g. `docs/specs/shared-todo-lists.md`). Never overwrite an existing file. **Ask** with `AskUserQuestion`: "What should happen to `SPEC.md` once the feature is done?" — options: - **Revert it (Recommended)** — the last commit is `revert: docs: feature specification` - **Move it to ``** — one option per location found above, up to two, each description saying why that location fits - the user can always type a different path - if the spec file already lives in a documentation folder (chosen after a clash), offer **Keep it where it is** instead of a move — it then needs no last commit The chosen outcome becomes the **last** commit of the proposed structure below: - **revert** → `revert: docs: feature specification` - **move** → `git mv SPEC.md `, committed as `docs: move feature specification to `; the content stays as it is ## Commit Organization Rules All commit-organization rules are defined in `git-workflow.md` (loaded above); this skill **applies** them to an existing working tree / history. Its "Before Every Commit" gate applies to every commit made here. The very last commit is the `SPEC.md` outcome chosen in Step 1. This skill owns **final history shaping** (reordering, splitting, the `SPEC.md` outcome); `/aido:2-implement` produced the per-unit working commits. ### Follow What Was Actually Built "Shape by Mode" in `git-workflow.md` shapes each part by its mode. Take the mode from the first of these that has one, reading the specification as "Reading the Approved Specification" in `specification.md` describes: 1. `## Progress` — a mode change and the slices built, as "Modes and Slices in Progress" in `specification.md` describes 2. the plan — the mode the item names, and its slices 3. otherwise inside-out — a branch with no plan, specification or mode ## History Management - if some commits are already pushed, **add** new commits instead of rewriting history - if history is not pushed, you may reset/reorganize the existing commits - **pushing or force pushing needs the user's approval**, which the permission prompt asks for, per "Pushing Changes" in `git-workflow.md`; say first when the push would rewrite history ## Step 2: Propose Commit Structure Before Reorganizing Before performing any rebase or history rewrite, analyze the current commits and use `AskUserQuestion` to present the proposed commit grouping: > "Here's how I plan to reorganize the commits: > 1. `docs: feature specification` (first) > 2. `feat: ...` (grouped by class/module with tests) > 3. for an outside-in part, each slice in turn: its commits inside-out, then its acceptance test > 4. ... > N. `revert: docs: feature specification` or `docs: move feature specification to ` (last, as chosen in Step 1) > > Is this grouping approved?" Options: **Approve the grouping** / **Adjust it** (ask what to change, update the proposal, show what changed as "Showing What Changed" in `${CLAUDE_PLUGIN_ROOT}/guidelines/language.md` describes, and ask again). In the same `AskUserQuestion` call, offer the next step, following "each approval also settles the choice that follows it" in `/aido:1-plan`. The answer counts only when the grouping is approved, and "Hand Off" acts on it: > "Once the commits are organized, should I open the pull request?" Options: **Open the PR in a fresh context** (recommended) / **Open the PR** / **Stop here**. Read `## Progress` first, as "Acceptance in Progress" in `specification.md` describes. The question names each criterion recorded as `unchecked` or `deferred`, so the user doesn't continue without noticing it. While any is `unchecked`, its plan items aren't done, so mark neither **Open the PR** nor **Open the PR in a fresh context** as recommended. When `/aido:resolve-migration-conflict` runs this skill, make no offer: ask only about the grouping, and return to its "Wrap Up" when the commits are organized. **Wait for user approval before starting the rebase.** The rebase is destructive and hard to undo — getting alignment first avoids rework. ## Final Checklist After organizing commits, verify ALL of the following: - [ ] Docs commit message is EXACTLY "docs: feature specification" (if docs present) - [ ] The last commit carries the `SPEC.md` outcome chosen in Step 1: "revert: docs: feature specification" (default) or "docs: move feature specification to " (if docs present) - [ ] No `SPEC.md.draft` is left in the working tree - [ ] Docs commit is the FIRST commit in history (if docs present) - [ ] Every commit message follows "Commit Message Format" in `git-workflow.md` - [ ] The order and grouping follow "Commit Organization Strategy" in `git-workflow.md`, with each part shaped by the mode "Follow What Was Actually Built" gives it - [ ] "Before Every Commit" in `git-workflow.md` holds - [ ] All tests pass ## Hand Off Continue as the user chose in Step 2, without asking again: - **Open the PR** → once the final checklist holds, invoke `/aido:4-open-pr`. This answer approves only starting that skill: its verification offer, the push approval and the review of the PR all still happen. If the checklist can't hold, do not start it, and tell the user why - **Open the PR in a fresh context** → once the final checklist holds, act as **Hand-off Outcomes** in `git-workflow.md` describes. If the checklist can't hold, tell the user why - **Stop here**, or no answer → as **Hand-off Outcomes** in `git-workflow.md` describes Then end as "Ending a Skill" in `${CLAUDE_PLUGIN_ROOT}/guidelines/language.md` describes. When `/aido:resolve-migration-conflict` started this skill, add no block.