✨ Add --amend flag to gen command for amending previous commits

Implement commit amending support via `git-iris gen --amend`, allowing users
to regenerate and replace the previous commit with a new AI-generated message
that considers both the original commit content and any newly staged changes.

The implementation includes:
- New TaskContext::Amend variant that carries the original commit message
- amend_commit() function in git module that uses git2's commit amend API
- perform_amend() in GitCommitService with hook execution support
- CLI integration with validation (requires --print or --auto-commit for now)
- Updated commit capability prompt with amend mode instructions

When amending, Iris sees the combined diff from HEAD^1 to staged state,
ensuring the regenerated message accurately describes the full amended commit.

Author: hyperb1iss

src/agents/capabilities/commit.toml

@@ -14,6 +14,7 @@ Do not skip this step.
 - `project_docs(doc_type="context")` - **CALL FIRST** - Get README + AGENTS.md/CLAUDE.md for project context
 - `git_diff()` - Get summary of staged changes with relevance scores (default: summary only)
 - `git_diff(detail="standard", files=["path1","path2"])` - Get full diffs for specific files
+- `git_diff(from="HEAD^1")` - Get combined diff from parent commit to staged (use for amend)
 - `git_log(count=5)` - Recent commits for style reference
 - `project_metadata()` - Get project language, framework, and dependencies (optional)
 - `parallel_analyze(tasks=[...])` - Spawn subagents for very large changesets (optional)
@@ -28,6 +29,15 @@ Do not skip this step.
 
 **CRITICAL**: Never request all diffs at once for large changesets. Always start with summary, then selectively drill into important files.
 
+## Amend Mode
+When the context indicates **amend mode** (you'll see `"mode": "amend"` with an `original_message`):
+- You are **replacing** an existing commit, not creating a new one
+- Use `git_diff(from="HEAD^1")` to see the **combined** diff (original commit + new staged changes)
+- The original commit message is provided for context—consider its intent
+- Generate a **new** message that accurately describes the full amended commit
+- Don't just append to the original message—write fresh based on the complete changeset
+- The amended commit should feel cohesive, as if it was always this way
+
 ## Context Strategy by Size
 - **Small** (≤3 files, <100 lines): Can use `git_diff(detail="standard")` to see all diffs
 - **Medium** (≤10 files, <500 lines): Start with summary, then get diffs for >60% relevance files

src/agents/context.rs

@@ -33,6 +33,13 @@ pub enum TaskContext {
         to: String,
     },
 
+    /// Amend the previous commit with staged changes
+    /// The agent sees the combined diff from HEAD^1 to staged state
+    Amend {
+        /// The original commit message being amended
+        original_message: String,
+    },
+
     /// Let the agent discover context via tools (default for gen command)
     #[default]
     Discover,
@@ -47,6 +54,12 @@ impl TaskContext {
         }
     }
 
+    /// Create context for amending the previous commit.
+    /// The agent will see the combined diff from HEAD^1 to staged state.
+    pub fn for_amend(original_message: String) -> Self {
+        Self::Amend { original_message }
+    }
+
     /// Create context for the review command with full parameter validation.
     ///
     /// Validates:
@@ -140,6 +153,9 @@ impl TaskContext {
             Self::Range { from, to } => {
                 format!("git_diff(from=\"{from}\", to=\"{to}\")")
             }
+            Self::Amend { .. } => {
+                "git_diff(from=\"HEAD^1\") for combined amend diff (original commit + new staged changes)".to_string()
+            }
             Self::Discover => "git_diff() to discover current changes".to_string(),
         }
     }
@@ -158,6 +174,19 @@ impl TaskContext {
             }
         )
     }
+
+    /// Check if this is an amend operation
+    pub fn is_amend(&self) -> bool {
+        matches!(self, Self::Amend { .. })
+    }
+
+    /// Get the original commit message if this is an amend context
+    pub fn original_message(&self) -> Option<&str> {
+        match self {
+            Self::Amend { original_message } => Some(original_message),
+            _ => None,
+        }
+    }
 }
 
 impl std::fmt::Display for TaskContext {
@@ -172,6 +201,7 @@ impl std::fmt::Display for TaskContext {
             }
             Self::Commit { commit_id } => write!(f, "commit {commit_id}"),
             Self::Range { from, to } => write!(f, "changes from {from} to {to}"),
+            Self::Amend { .. } => write!(f, "amending previous commit"),
             Self::Discover => write!(f, "auto-discovered changes"),
         }
     }
@@ -308,5 +338,23 @@ mod tests {
         };
         assert!(range.diff_hint().contains("main"));
         assert!(range.diff_hint().contains("dev"));
+
+        let amend = TaskContext::for_amend("Fix bug".to_string());
+        assert!(amend.diff_hint().contains("HEAD^1"));
+    }
+
+    #[test]
+    fn test_amend_context() {
+        let ctx = TaskContext::for_amend("Initial commit message".to_string());
+        assert!(ctx.is_amend());
+        assert_eq!(ctx.original_message(), Some("Initial commit message"));
+        assert!(!ctx.is_range());
+        assert!(!ctx.includes_unstaged());
+    }
+
+    #[test]
+    fn test_amend_display() {
+        let ctx = TaskContext::for_amend("Fix bug".to_string());
+        assert_eq!(format!("{ctx}"), "amending previous commit");
     }
 }

src/cli.rs

@@ -120,6 +120,10 @@ pub enum Commands {
         /// Skip the verification step (pre/post commit hooks)
         #[arg(long, help = "Skip verification steps (pre/post commit hooks)")]
         no_verify: bool,
+
+        /// Amend the previous commit instead of creating a new one
+        #[arg(long, help = "Amend the previous commit with staged changes")]
+        amend: bool,
     },
 
     /// Review staged changes and provide feedback
@@ -479,6 +483,7 @@ struct GenConfig {
     use_gitmoji: bool,
     print_only: bool,
     verify: bool,
+    amend: bool,
 }
 
 /// Handle the `Gen` command with agent framework and Studio integration
@@ -507,6 +512,13 @@ async fn handle_gen_with_agent(
         ui::print_info("Run 'git-iris list-presets' to see available presets for commits.");
     }
 
+    // Amend mode requires --print or --auto-commit (Studio amend support coming later)
+    if config.amend && !config.print_only && !config.auto_commit {
+        ui::print_warning("--amend requires --print or --auto-commit for now.");
+        ui::print_info("Example: git-iris gen --amend --auto-commit");
+        return Ok(());
+    }
+
     let mut cfg = Config::load()?;
     common.apply_to_config(&mut cfg)?;
 
@@ -533,7 +545,9 @@ async fn handle_gen_with_agent(
 
     // For --print or --auto-commit, we need to generate the message first
     if config.print_only || config.auto_commit {
-        if git_info.staged_files.is_empty() {
+        // For amend mode, we allow empty staged changes (amending message only)
+        // For regular commits, we require staged changes
+        if git_info.staged_files.is_empty() && !config.amend {
             ui::print_warning(
                 "No staged changes. Please stage your changes before generating a commit message.",
             );
@@ -548,10 +562,23 @@ async fn handle_gen_with_agent(
         }
 
         // Create spinner for agent mode
-        let spinner = ui::create_spinner("Generating commit message...");
+        let spinner_msg = if config.amend {
+            "Generating amended commit message..."
+        } else {
+            "Generating commit message..."
+        };
+        let spinner = ui::create_spinner(spinner_msg);
 
         // Use IrisAgentService for commit message generation
-        let context = TaskContext::for_gen();
+        // For amend, we pass the original message as context
+        let context = if config.amend {
+            let original_message = commit_service
+                .get_head_commit_message()
+                .unwrap_or_default();
+            TaskContext::for_amend(original_message)
+        } else {
+            TaskContext::for_gen()
+        };
         let response = agent_service.execute_task("commit", context).await?;
 
         // Extract commit message from response
@@ -567,7 +594,7 @@ async fn handle_gen_with_agent(
             return Ok(());
         }
 
-        // Auto-commit mode
+        // Auto-commit/amend mode
         if commit_service.is_remote() {
             ui::print_error(
                 "Cannot automatically commit to a remote repository. Use --print instead.",
@@ -577,14 +604,21 @@ async fn handle_gen_with_agent(
             ));
         }
 
-        match commit_service.perform_commit(&format_commit_message(&generated_message)) {
+        let commit_result = if config.amend {
+            commit_service.perform_amend(&format_commit_message(&generated_message))
+        } else {
+            commit_service.perform_commit(&format_commit_message(&generated_message))
+        };
+
+        match commit_result {
             Ok(result) => {
                 let output =
                     format_commit_result(&result, &format_commit_message(&generated_message));
                 println!("{output}");
             }
             Err(e) => {
-                eprintln!("Failed to commit: {e}");
+                let action = if config.amend { "amend" } else { "commit" };
+                eprintln!("Failed to {action}: {e}");
                 return Err(e);
             }
         }
@@ -618,12 +652,13 @@ async fn handle_gen(
     repository_url: Option<String>,
 ) -> anyhow::Result<()> {
     log_debug!(
-        "Handling 'gen' command with common: {:?}, auto_commit: {}, use_gitmoji: {}, print: {}, verify: {}",
+        "Handling 'gen' command with common: {:?}, auto_commit: {}, use_gitmoji: {}, print: {}, verify: {}, amend: {}",
         common,
         config.auto_commit,
         config.use_gitmoji,
         config.print_only,
-        config.verify
+        config.verify,
+        config.amend
     );
 
     ui::print_version(crate_version!());
@@ -878,6 +913,7 @@ pub async fn handle_command(
             no_gitmoji,
             print,
             no_verify,
+            amend,
         } => {
             handle_gen(
                 common,
@@ -886,6 +922,7 @@ pub async fn handle_command(
                     use_gitmoji: !no_gitmoji,
                     print_only: print,
                     verify: !no_verify,
+                    amend,
                 },
                 repository_url,
             )

src/git/commit.rs

@@ -101,6 +101,106 @@ pub fn commit(repo: &Repository, message: &str, is_remote: bool) -> Result<Commi
     })
 }
 
+/// Amends the previous commit with staged changes and a new message.
+///
+/// This replaces HEAD with a new commit that has:
+/// - HEAD's parent as its parent
+/// - The current staged index as its tree
+/// - The new message provided
+///
+/// # Arguments
+///
+/// * `repo` - The git repository
+/// * `message` - The new commit message
+/// * `is_remote` - Whether the repository is remote
+///
+/// # Returns
+///
+/// A Result containing the `CommitResult` or an error.
+pub fn amend_commit(repo: &Repository, message: &str, is_remote: bool) -> Result<CommitResult> {
+    if is_remote {
+        return Err(anyhow!(
+            "Cannot amend a commit in a remote repository in read-only mode"
+        ));
+    }
+
+    let signature = repo.signature()?;
+    let mut index = repo.index()?;
+    let tree_id = index.write_tree()?;
+    let tree = repo.find_tree(tree_id)?;
+
+    // Get the current HEAD commit (the one we're amending)
+    let head_commit = repo.head()?.peel_to_commit()?;
+
+    // Amend the HEAD commit with the new tree and message
+    let commit_oid = head_commit.amend(
+        Some("HEAD"),      // Update the HEAD reference
+        Some(&signature),  // New author (use current)
+        Some(&signature),  // New committer (use current)
+        None,              // Keep original encoding
+        Some(message),     // New message
+        Some(&tree),       // New tree (includes staged changes)
+    )?;
+
+    let branch_name = repo.head()?.shorthand().unwrap_or("HEAD").to_string();
+    let commit = repo.find_commit(commit_oid)?;
+    let short_hash = commit.id().to_string()[..7].to_string();
+
+    // Calculate diff stats from the original parent to the new tree
+    let mut files_changed = 0;
+    let mut insertions = 0;
+    let mut deletions = 0;
+    let new_files = Vec::new();
+
+    // Use the first parent for diff (or empty tree if initial commit)
+    let parent_tree = if head_commit.parent_count() > 0 {
+        Some(head_commit.parent(0)?.tree()?)
+    } else {
+        None
+    };
+    let diff = repo.diff_tree_to_tree(parent_tree.as_ref(), Some(&tree), None)?;
+
+    diff.print(git2::DiffFormat::NameStatus, |_, _, line| {
+        files_changed += 1;
+        if line.origin() == '+' {
+            insertions += 1;
+        } else if line.origin() == '-' {
+            deletions += 1;
+        }
+        true
+    })?;
+
+    log_debug!(
+        "Amended commit {} -> {} with {} files changed",
+        &head_commit.id().to_string()[..7],
+        short_hash,
+        files_changed
+    );
+
+    Ok(CommitResult {
+        branch: branch_name,
+        commit_hash: short_hash,
+        files_changed,
+        insertions,
+        deletions,
+        new_files,
+    })
+}
+
+/// Gets the message of the HEAD commit.
+///
+/// # Arguments
+///
+/// * `repo` - The git repository
+///
+/// # Returns
+///
+/// A Result containing the commit message or an error.
+pub fn get_head_commit_message(repo: &Repository) -> Result<String> {
+    let head_commit = repo.head()?.peel_to_commit()?;
+    Ok(head_commit.message().unwrap_or_default().to_string())
+}
+
 /// Retrieves commits between two Git references.
 ///
 /// # Arguments

src/git/repository.rs

@@ -748,6 +748,18 @@ impl GitRepo {
         commit::commit(&repo, message, self.is_remote)
     }
 
+    /// Amend the previous commit with staged changes and a new message
+    pub fn amend_commit(&self, message: &str) -> Result<CommitResult> {
+        let repo = self.open_repo()?;
+        commit::amend_commit(&repo, message, self.is_remote)
+    }
+
+    /// Get the message of the HEAD commit
+    pub fn get_head_commit_message(&self) -> Result<String> {
+        let repo = self.open_repo()?;
+        commit::get_head_commit_message(&repo)
+    }
+
     /// Check if inside a working tree
     pub fn is_inside_work_tree() -> Result<bool> {
         is_inside_work_tree()