feat(shell): terminal context capture for the zsh plugin

.forge/skills/resolve-fixme/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: resolve-fixme
-description: Find all FIXME comments across the codebase and attempt to resolve them. Use when the user asks to fix, resolve, or address FIXME comments, or when running the "fixme" command. Runs a script to locate every FIXME with surrounding context (2 lines before, 5 lines after) and then works through each one systematically.
+description: Find all FIXME comments across the codebase and fully implement the work they describe. Use when the user asks to fix, resolve, or address FIXME comments, or when running the "fixme" command. Runs a discovery script to find every FIXME, expands multiline comment blocks, groups related FIXMEs across files into a single implementation task, completes the full underlying code changes, removes the FIXME comments only after the work is done, and verifies that no FIXMEs remain.
 ---
 
 # Resolve FIXME Comments
@@ -20,34 +20,91 @@ bash .forge/skills/resolve-fixme/scripts/find-fixme.sh [PATH]
 - Skips `.git/`, `target/`, `node_modules/`, and `vendor/`.
 - Requires either `rg` (ripgrep) or `grep` + `python3`.
 
-### 2. Triage the results
+### 2. Expand each FIXME into its full instruction
 
-Read the script output and build a work list. For each FIXME note:
-- The file and line number (shown in the header of each block).
-- The surrounding context to understand what the FIXME is asking for.
-- Whether the fix requires code changes, further research, or is blocked.
+Do not rely on the discovery output alone.
 
-### 3. Resolve each FIXME
+For every hit:
 
-Work through the list one at a time:
+1. Open the file and read around the reported line.
+2. Expand the FIXME to include the **entire comment block**.
+3. Treat all consecutive related comment lines as part of the same instruction.
 
-1. Read the full file section to understand the intent.
-2. Implement the fix — edit the code, add the missing logic, or refactor as needed.
-3. Remove the FIXME comment once the issue is resolved.
-4. If a FIXME cannot be safely resolved (e.g. requires external input or is intentionally deferred), leave it in place and note why.
+Important:
 
-### 4. Verify
+- A FIXME may be **multiline**. The line containing `FIXME` is often only the beginning.
+- The real instruction may continue on following comment lines and may contain the actual implementation details.
+- Do not interpret or edit a FIXME until you have read the full block.
 
-After resolving all FIXMEs, run the project's standard verification steps:
+For each expanded FIXME, capture:
 
-```
+- file path
+- start line and end line of the full comment block
+- a short summary of what that FIXME is asking for
+
+### 3. Consolidate related FIXMEs across files
+
+Before editing code, review **all** expanded FIXMEs together.
+
+Many FIXMEs describe different facets of the same underlying task across multiple files. For example:
+
+- one file may describe a domain type that needs to be introduced
+- another may describe a parameter that should disappear once that type exists
+- another may describe a service, repo, or UI update needed to complete the same refactor
+
+Group such FIXMEs into a single implementation task.
+
+When grouping, look for:
+
+- shared vocabulary
+- references to the same type, service, repo, parameter, or feature
+- comments that clearly describe prerequisite and follow-up changes in different files
+- comments that only make sense when read together
+
+For each group, produce one consolidated understanding of the task:
+
+- all files and line ranges involved
+- the complete implementation required across the group
+- the order in which the changes should be made
+
+Do not resolve grouped FIXMEs one file at a time in isolation. Resolve the whole task consistently.
+
+### 4. Implement every FIXME completely
+
+Every FIXME must be resolved. There is no skip path.
+
+Work through each grouped task until the underlying implementation is complete:
+
+1. Read any additional files needed to understand the design.
+2. Create or modify the required code, types, services, repos, tests, configs, or templates.
+3. Propagate the change through every affected file in the group.
+4. Remove each FIXME comment **only after** the work it describes has actually been implemented.
+
+> **Critical rule:** Never delete or rewrite a FIXME comment unless the underlying implementation is finished. The comment is a record of required work. Removing it before completing that work is a failure.
+
+If the FIXME implies a larger refactor, do the refactor. If it requires creating new supporting code, create it. Do not stop at the first local change if the comment clearly implies additional follow-through elsewhere.
+
+### 5. Verify
+
+After resolving all FIXMEs:
+
+1. Run the project's standard verification step:
+
+```sh
 cargo insta test --accept
 ```
 
-Re-run the discovery script to confirm no FIXMEs remain unresolved.
+2. Re-run the discovery script:
+
+```sh
+bash .forge/skills/resolve-fixme/scripts/find-fixme.sh [PATH]
+```
+
+3. Confirm that no FIXME comments remain in the targeted scope.
 
 ## Notes
 
-- Prefer targeted, minimal fixes — only change what the FIXME describes.
-- If the FIXME comment describes a TODO that was intentionally deferred (e.g. `FIXME(later):` or `FIXME(blocked):`), skip it and report it to the user.
-- When the context is ambiguous, read more of the surrounding file before making a change.
+- Prefer targeted fixes, but do not under-scope the work when multiple FIXMEs describe one larger task.
+- Read broadly before editing when the intent is ambiguous.
+- Consistency matters more than locality: grouped FIXMEs should lead to one coherent implementation.
+- The job is not to clean up comments. The job is to complete the implementation those comments are pointing at.

.gitignore

@@ -48,3 +48,4 @@ Cargo.lock
 **/.forge/request.body.json
 node_modules/
 bench/__pycache__
+.ai/

crates/forge_api/src/forge_api.rs

@@ -311,7 +311,6 @@ impl<
     async fn get_skills(&self) -> Result<Vec<Skill>> {
         self.infra.load_skills().await
     }
-
     async fn generate_command(&self, prompt: UserPrompt) -> Result<String> {
         use forge_app::CommandGenerator;
         let generator = CommandGenerator::new(self.services.clone());

crates/forge_app/src/command_generator.rs

@@ -7,6 +7,7 @@ use serde::Deserialize;
 
 use crate::{
     AppConfigService, EnvironmentInfra, FileDiscoveryService, ProviderService, TemplateEngine,
+    TerminalContextService,
 };
 
 /// Response struct for shell command generation using JSON format
@@ -25,14 +26,23 @@ pub struct CommandGenerator<S> {
 
 impl<S> CommandGenerator<S>
 where
-    S: EnvironmentInfra + FileDiscoveryService + ProviderService + AppConfigService,
+    S: EnvironmentInfra<Config = forge_config::ForgeConfig>
+        + FileDiscoveryService
+        + ProviderService
+        + AppConfigService,
 {
     /// Creates a new CommandGenerator instance with the provided services.
     pub fn new(services: Arc<S>) -> Self {
         Self { services }
     }
 
-    /// Generates a shell command from a natural language prompt
+    /// Generates a shell command from a natural language prompt.
+    ///
+    /// Terminal context is read automatically from the `_FORGE_TERM_COMMANDS`,
+    /// `_FORGE_TERM_EXIT_CODES`, and `_FORGE_TERM_TIMESTAMPS` environment
+    /// variables exported by the zsh plugin, and included in the user
+    /// prompt so the LLM can reference recent commands, exit codes, and
+    /// timestamps.
     pub async fn generate(&self, prompt: UserPrompt) -> Result<String> {
         // Get system information for context
         let env = self.services.get_environment();
@@ -59,8 +69,22 @@ where
             }
         };
 
-        // Build user prompt with task and recent commands
-        let user_content = format!("<task>{}</task>", prompt.as_str());
+        // Build user prompt with task, optionally including terminal context.
+        use forge_template::Element;
+        let task_elm = Element::new("task").text(prompt.as_str());
+        let terminal_service = TerminalContextService::new(self.services.clone());
+        let user_content = match terminal_service.get_terminal_context() {
+            Some(ctx) => {
+                let terminal_elm =
+                    Element::new("command_trace").append(ctx.commands.iter().map(|cmd| {
+                        Element::new("command")
+                            .attr("exit_code", cmd.exit_code.to_string())
+                            .text(&cmd.command)
+                    }));
+                format!("{}\n\n{}", terminal_elm.render(), task_elm.render())
+            }
+            None => task_elm.render(),
+        };
 
         // Create context with system and user prompts
         let ctx = self.create_context(rendered_system_prompt, user_content, &model);
@@ -103,7 +127,7 @@ where
 mod tests {
     use forge_domain::{
         AuthCredential, AuthDetails, AuthMethod, ChatCompletionMessage, Content, FinishReason,
-        ModelSource, ProviderId, ProviderResponse, ResultStream,
+        ModelSource, ProviderId, ProviderResponse, ResultStream, Role,
     };
     use tokio::sync::Mutex;
     use url::Url;
@@ -116,6 +140,7 @@ mod tests {
         response: Arc<Mutex<Option<String>>>,
         captured_context: Arc<Mutex<Option<Context>>>,
         environment: Environment,
+        env_vars: std::collections::BTreeMap<String, String>,
     }
 
     impl MockServices {
@@ -133,6 +158,26 @@ mod tests {
                 response: Arc::new(Mutex::new(Some(response.to_string()))),
                 captured_context: Arc::new(Mutex::new(None)),
                 environment: env,
+                env_vars: std::collections::BTreeMap::new(),
+            })
+        }
+
+        fn with_terminal_context(
+            self: Arc<Self>,
+            commands: &str,
+            exit_codes: &str,
+            timestamps: &str,
+        ) -> Arc<Self> {
+            let mut env_vars = self.env_vars.clone();
+            env_vars.insert("_FORGE_TERM_COMMANDS".to_string(), commands.to_string());
+            env_vars.insert("_FORGE_TERM_EXIT_CODES".to_string(), exit_codes.to_string());
+            env_vars.insert("_FORGE_TERM_TIMESTAMPS".to_string(), timestamps.to_string());
+            Arc::new(Self {
+                files: self.files.clone(),
+                response: self.response.clone(),
+                captured_context: self.captured_context.clone(),
+                environment: self.environment.clone(),
+                env_vars,
             })
         }
     }
@@ -155,12 +200,12 @@ mod tests {
             unimplemented!()
         }
 
-        fn get_env_var(&self, _key: &str) -> Option<String> {
-            None
+        fn get_env_var(&self, key: &str) -> Option<String> {
+            self.env_vars.get(key).cloned()
         }
 
         fn get_env_vars(&self) -> std::collections::BTreeMap<String, String> {
-            std::collections::BTreeMap::new()
+            self.env_vars.clone()
         }
     }
 
@@ -312,6 +357,35 @@ mod tests {
         insta::assert_yaml_snapshot!(captured_context);
     }
 
+    #[tokio::test]
+    async fn test_generate_with_shell_context() {
+        let fixture = MockServices::new(
+            r#"{"command": "cargo build --release"}"#,
+            vec![("Cargo.toml", false)],
+        )
+        .with_terminal_context("cargo build", "101", "1700000000");
+        let generator = CommandGenerator::new(fixture.clone());
+
+        let actual = generator
+            .generate(UserPrompt::from("fix the command I just ran".to_string()))
+            .await
+            .unwrap();
+
+        assert_eq!(actual, "cargo build --release");
+        let captured_context = fixture.captured_context.lock().await.clone().unwrap();
+        let user_content = captured_context
+            .messages
+            .iter()
+            .find(|m| m.has_role(Role::User))
+            .expect("should have a user message")
+            .content()
+            .expect("user message should have content");
+        assert!(user_content.contains("<command_trace>"));
+        assert!(user_content.contains("</command_trace>"));
+        assert!(user_content.contains("cargo build"));
+        assert!(user_content.contains("<task>fix the command I just ran</task>"));
+    }
+
     #[tokio::test]
     async fn test_generate_fails_when_missing_tag() {
         let fixture = MockServices::new(r#"{"invalid": "json"}"#, vec![]);

crates/forge_app/src/lib.rs

@@ -26,6 +26,7 @@ mod services;
 mod set_conversation_id;
 pub mod system_prompt;
 mod template_engine;
+mod terminal_context;
 mod title_generator;
 mod tool_executor;
 mod tool_registry;
@@ -48,6 +49,7 @@ pub use git_app::*;
 pub use infra::*;
 pub use services::*;
 pub use template_engine::*;
+pub use terminal_context::*;
 pub use tool_resolver::*;
 pub use user::*;
 pub use utils::{compute_hash, is_binary_content_type};