feat: New agent workflow that depends less on prompt engineering (#39)

Author: zah

.agents/tasks/2025/06/08-2100-new-command-behavior.txt

@@ -0,0 +1,32 @@
+The `start-work` binary should gain some new command-line parameters: 
+
+1) `--autopush`: besides the current git configuration commands, it should install a
+post-commit hook that automatically force pushes the commit to the `target_remote`
+(the goal is the push the commit even when the push is not a fast-forward push). 
+
+The use of the new flag should be suggested in the GIT_MESSAGE inserted when `get-task`
+is launched with `--autopush`. The current instructions for executing git push at the
+end of the task can be removed now.
+
+2) `--task-description` and `--branch-name`. Specifying those should result in creating
+or modifying an existing task description file, by following similar logic to the
+`agent-task` command when not given a branch:
+
+If we are currently not on an agent branch, the command should create a task description
+file and commit it immediately just like `agent-task` does, but without creating a new
+branch or pushing it to the remote (the `--branch-name` argument will affect only the
+name of the task description file).
+
+if, we are already on an agent branch (e.g. `start-work` was already called and it
+created a commit with a `Start-Agent-Branch` tag in the commit message), append the
+new task description to the existing task file just like `agent-task` does when not
+given a branch name. The `--branch-name` parameter will be ignored in this situation.
+
+The use of `start-work` with the new flags will be suggested in the AGENTS.md file
+created by `codex-setup` instead of the current manual instructions.
+
+Make sure to refactor the code to not  introduce unnecessary code duplication between
+`agent-task` and `start-work`
+
+Please add tests for `start-work` that check that the described behavior works.
+Before two invocations of `start-work`, there might be multiple commits.

.gitignore

@@ -1,3 +1,7 @@
 .direnv/
+
 .install-markers/
 test/logs/
+
+# Debugger temp files
+.rdbgrc.breakpoints

.ruby-version

@@ -0,0 +1 @@
+3.2.1

.vscode/launch.json

@@ -0,0 +1,41 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "rdbg",
+      "name": "Debug Current Ruby File",
+      "request": "launch",
+      "script": "${file}",
+      "args": [],
+      "askParameters": false,
+      "cwd": "${workspaceFolder}",
+      "env": {},
+      "useBundler": false,
+      "rdbgPath": "ruby ${workspaceFolder}/scripts/rdbg-wrapper"
+    },
+    {
+      "type": "rdbg",
+      "name": "Debug Current Test File",
+      "request": "launch",
+      "script": "${file}",
+      "args": ["-I", "lib", "-I", "test"],
+      "askParameters": false,
+      "cwd": "${workspaceFolder}",
+      "env": {},
+      "useBundler": false,
+      "rdbgPath": "ruby ${workspaceFolder}/scripts/rdbg-wrapper"
+    },
+    {
+      "type": "rdbg",
+      "name": "Debug All Tests",
+      "request": "launch",
+      "script": "test/run_tests_shell.rb",
+      "args": ["-I", "lib", "-I", "test"],
+      "askParameters": false,
+      "cwd": "${workspaceFolder}",
+      "env": {},
+      "useBundler": false,
+      "rdbgPath": "ruby ${workspaceFolder}/scripts/rdbg-wrapper"
+    }
+  ]
+}

.vscode/settings.json

@@ -36,6 +36,8 @@
     "signatureHelp": true,
     "typeHierarchy": true
   },
+  "rdbg.saveBreakpoints": true,
+  "rdbg.enableDebugging": true,
   "files.associations": {
     "*.nix": "nix",
     "flake.nix": "nix",

.vscode/tasks.json

@@ -0,0 +1,73 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Run Current Test File",
+      "type": "shell",
+      "command": "ruby",
+      "args": ["-I", "lib", "-I", "test", "${file}"],
+      "group": "test",
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "focus": false,
+        "panel": "shared"
+      },
+      "options": {
+        "cwd": "${workspaceFolder}"
+      }
+    },
+    {
+      "label": "Run All Tests",
+      "type": "shell",
+      "command": "ruby",
+      "args": ["-I", "lib", "-I", "test", "test/run_tests_shell.rb"],
+      "group": {
+        "kind": "test",
+        "isDefault": true
+      },
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "focus": false,
+        "panel": "shared"
+      },
+      "options": {
+        "cwd": "${workspaceFolder}"
+      }
+    },
+    {
+      "label": "Debug Current Test with Pry",
+      "type": "shell",
+      "command": "ruby",
+      "args": ["-I", "lib", "-I", "test", "-r", "pry", "${file}"],
+      "group": "test",
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "focus": true,
+        "panel": "shared"
+      },
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Simple Test Run (No Debug)",
+      "type": "shell",
+      "command": "ruby",
+      "args": ["-I", "lib", "-I", "test", "${file}"],
+      "group": "test",
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "focus": false,
+        "panel": "shared"
+      },
+      "options": {
+        "cwd": "${workspaceFolder}"
+      }
+    }
+  ]
+}

codex-setup

@@ -2,17 +2,6 @@
 
 AGENTS_WORKFLOW_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
 
-# BEWARE! The heredoc below is intentially using long lines, becuase otherwise
-# Codex gets confused sometimes by the terminal output in its environment that
-# splits the lines in unexpected ways (Codex decides the file is truncated).
-
-# Conditionally set the autopush flag based on GITHUB_TOKEN availability
-if [ -n "${GITHUB_TOKEN}" ]; then
-  GET_TASK_CMD="get-task --autopush"
-else
-  GET_TASK_CMD="get-task"
-fi
-
 # Configure ~/.netrc for Git hosting services
 NETRC_CONTENT=""
 if [ -n "${GITHUB_TOKEN}" ]; then
@@ -28,44 +17,28 @@ if [ -n "$NETRC_CONTENT" ]; then
   echo "Configuring ~/.netrc for git authentication"
   printf "%s" "$NETRC_CONTENT" > "$HOME/.netrc"
   chmod 600 "$HOME/.netrc"
+  GET_TASK_CMD="get-task --autopush"
+else
+  GET_TASK_CMD="get-task"
 fi
 
 cat > ../AGENTS.md << EOF
 When you a given a task description or developer instructions that
 just state "go", execute the shell command \`${GET_TASK_CMD}\` under
 the repository root and follow the instructions provided in the output.
 
-When the task description or developer instructions are not "go",
-you should follow the given instructions while also adhering to the
-workflow described below.
-
-Before starting work, do the following:
-
-1) mkdir -p ".agents/tasks/\$(date -u +%Y)/\$(date -u +%m)"
-2) In this directory, create a file with a verbatim copy of the task
-description or developer instructions. The file should be named exactly
-"\$(date -u +%d-%H%M)-\${TASK_BRANCH_NAME}.txt", where \$TASK_BRANCH_NAME
-is an appropriate short branch name that would describe well the task
-description or developer instructions.
-
-When you are given follow-up task description/developer instructions,
-or a QA review, append a verbatim copy to the same task file. You can
-make sure the file is the same by inspecting its contents which should
-match the original message.
-
-Use the separator "\\n--- FOLLOW UP TASK ---\\n" to indicate where the
-new content has been appended.
+When the task description or developer instructions are not "go", before
+you do anything else, record a precise copy of them with the following
+shell command:
 
-Before starting work on the follow-up task, take note of the current
-HEAD commit. I'd like this commit to be preserved. Don't squash it
-with other commits at the end of the task.
+start-work --branch-name "<TASK_BRANCH_NAME>" --task-description "<message>"
 
-I REPEAT: FOLLOW THE ABOVE WORKFLOW ONLY IF THE TASK DESCRIPTION OR
-DEVELOPER INSTRUCTIONS ARE NOT "go".
+TASK_BRANCH_NAME should be an appropriate short branch name that describes
+well the task description or developer instructions.
 
-In general, when you complete a task or a follow-up task, take a look
-at the changes introduced in this specific coding session and write
-a detailed summary of them in a single commit for each coding session.
+I REPEAT: THE start-work COMMAND SHOULD BE EXECUTED ONLY IF THE TASK
+DESCRIPTION OR DEVELOPER INSTRUCTIONS ARE NOT "go" AND IT SHOULD BE
+EXECUTED IMMEDIATELY.
 
 EOF
 

flake.nix

@@ -50,6 +50,9 @@
           pkgs.ruby
           pkgs.bundler
           pkgs.rubocop
+          pkgs.git
+          pkgs.fossil
+          pkgs.mercurial
         ];
       };
     });

lib/agent_task/cli.rb

@@ -1,5 +1,17 @@
 # frozen_string_literal: true
 
+# Command Line Interface Specification
+# ====================================
+#
+# This module implements the core functionality for all agent-workflow commands:
+#
+# `agent-task` (CLI.start_task) is used to record coding tasks that will be
+# developed by AI agents. It has two modes of operation:
+#
+# 1) Starting a new agent branch (you pass the branch name as argument to agent-task)
+# 2) Recording a new task in the current branch (it needs to be a agent branch already)
+
+
 module AgentTask
   # CLI exposes the main binaries as callable methods so the functionality
   # can be reused programmatically. The methods here mirror the behavior
@@ -15,7 +27,7 @@ def devshell_names(root)
       # This handles all possible Nix syntax variations correctly
       begin
         # Get the current system first
-        system_result = `nix eval --impure --raw --expr 'builtins.currentSystem' 2>/dev/null`.strip
+        system_result = `nix eval --impure --raw --expr 'builtins.currentSystem' 2>#{File::NULL}`.strip
         require 'English'
         if $CHILD_STATUS.success?
           current_system = system_result
@@ -186,7 +198,7 @@ def start_task(args, stdin: $stdin, stdout: $stdout)
           unless editor
             editors = %w[nano pico micro vim helix vi]
             editors.each do |ed|
-              if system("command -v #{ed} > /dev/null 2>&1")
+              if system('command', '-v', ed, out: File::NULL, err: File::NULL)
                 editor = ed
                 break
               end
@@ -204,36 +216,11 @@ def start_task(args, stdin: $stdin, stdout: $stdout)
         task_content.gsub!("\r\n", "\n")
         abort('Aborted: empty task prompt.') if task_content.strip.empty?
 
+        tasks = AgentTasks.new(repo.root)
         if start_new_branch
-          now = Time.now.utc
-          year = now.year
-          month = format('%02d', now.month)
-          day = format('%02d', now.day)
-          hour = format('%02d', now.hour)
-          min = format('%02d', now.min)
-          filename = "#{day}-#{hour}#{min}-#{branch_name}"
-          tasks_dir = File.join(repo.root, '.agents', 'tasks', year.to_s, month)
-          FileUtils.mkdir_p(tasks_dir)
-          task_file = File.join(tasks_dir, filename)
-
-          commit_msg = "Start-Agent-Branch: #{branch_name}"
-          target_remote = repo.default_remote_http_url
-          commit_msg += "\nTarget-Remote: #{target_remote}" if target_remote
-          commit_msg += "\nDev-Shell: #{options[:devshell]}" if options[:devshell]
-
-          File.binwrite(task_file, task_content)
-          repo.commit_file(task_file, commit_msg)
+          tasks.record_initial_task(task_content, branch_name, devshell: options[:devshell])
         else
-          start_commit = repo.latest_agent_branch_commit
-          abort('Error: Could not locate task start commit') unless start_commit
-          files = repo.files_in_commit(start_commit)
-          abort('Error: Task start commit should introduce exactly one file') unless files.length == 1
-          task_file = File.join(repo.root, files.first)
-          File.open(task_file, 'a') do |f|
-            f.write("\n--- FOLLOW UP TASK ---\n")
-            f.write(task_content)
-          end
-          repo.commit_file(task_file, 'Follow-up task')
+          tasks.append_task(task_content)
         end
 
         push = nil
@@ -289,7 +276,7 @@ def run_get_task(args = [])
       end
 
       if repos.length == 1 && repos[0][0].nil?
-        puts repos[0][1].agent_prompt(autopush: options[:autopush])
+        puts repos[0][1].agent_prompt_with_autopush_setup(autopush: options[:autopush])
         return
       end
 
@@ -298,7 +285,7 @@ def run_get_task(args = [])
         next if dir.nil?
 
         begin
-          msg = at.agent_prompt(autopush: options[:autopush])
+          msg = at.agent_prompt_with_autopush_setup(autopush: options[:autopush])
           dir_messages << [dir, msg] if msg && !msg.empty?
         rescue StandardError
           next
@@ -321,16 +308,39 @@ def run_get_task(args = [])
       exit 1
     end
 
-    def run_start_work(_args = [])
+    def run_start_work(args = [])
+      require 'optparse'
       require_relative '../agent_tasks'
 
+      options = {}
+      OptionParser.new do |opts|
+        opts.on('--task-description=DESC', 'Record the given task description') do |val|
+          options[:task_description] = val
+        end
+        opts.on('--branch-name=NAME', 'Name to use for the task description file') do |val|
+          options[:branch_name] = val
+        end
+      end.parse!(args)
+
       repos = discover_repos
       if repos.empty?
         puts "Error: Could not find repository root from #{Dir.pwd}"
         exit 1
       end
 
-      repos.to_h.each_value(&:prepare_work_environment)
+      repos.to_h.each_value do |at|
+        if options[:task_description]
+          if at.on_task_branch?
+            at.append_task(options[:task_description])
+          else
+            unless options[:branch_name]
+              raise StandardError, 'Error: --branch-name is required when not on an agent branch'
+            end
+
+            at.record_initial_task(options[:task_description], options[:branch_name])
+          end
+        end
+      end
     rescue StandardError => e
       puts e.message
       exit 1