An agent workflow based on codex-cli and jj

Justfile

@@ -1,3 +1,5 @@
+mod agents 
+
 default:
     @just --list
 
@@ -62,3 +64,4 @@ test-all:
         file="${file[0]}"; \
         uv run -p "python3.$v" --with "${file}" --with pytest -- pytest -q; \
     done
+

agents.just

@@ -0,0 +1,127 @@
+next-issue:
+	#!/usr/bin/env sh
+	[ -f next-issue.md ] || exit 1
+
+	codex exec --full-auto --config model_reasoning_effort=high <<EOF
+	1. You will next work on issue `cat next-issue.md`. Read the actual issue from 'issues.md'
+	3. Decide is it relevant to write a failing test for the issue. If so, write  the test, make sure that it fails.
+	   Note! Not all issues require writing failing tests. Use discretion. Remember - code is debt.
+	4. Change the code to fix the issue. Use "just dev test" to check if changes compile and tests pass.
+	   Code must follow the rules in '/rules/source-code.md'
+	5. When the issue is fixed and tests pass run "jj describe --stdin <<ENDDESC
+	commit message
+	ENDDESC".
+
+	For example:
+	jj describe --stdin <<ENDDESC
+	ISSUE-043: Update dog-barking protocol
+
+	...
+	ENDDESC
+
+	Note! If you try to add a commit message like 'jj new -m "blah"' or 'jj describe -m "blah"' the resulting message will not be formatted properly.
+
+	`cat rules/writing.md`
+
+	EOF
+
+	rm next-issue.md
+
+review-change:
+	#!/usr/bin/env sh
+	codex exec --full-auto --config model_reasoning_effort=high <<EOF
+	1. Fetch the current changes by writing 'jj show'
+	2. Create a new change by calling 'jj new -m "review(codex): ..."'. For example 'jj new -m "review(codex): Issue 004 - introducing dog barking functionality"'
+	3. Do a deep review of the change.
+	   - Write your review inline in the code itself by using code comments starting with '//REVIEW(author)' (or '# REVIEW(author)') to record your review.
+	   - While reviewing make sure that the rules in '/rules' folder are satisfied by the change under review.
+	   - DO NOT make any other changes in the code except adding the above-mentioned review comments.
+	   - DO NOT review code which is unrelated to the change under review. You can review code not in the diff, if its functionality was indirectly changed by the diff under review.
+	   - DO NOT write positive review comments. You can write positive statements in the review summary. Use review comments ONLY to point out potential problems or improvements.
+
+	4. Examine the changes and update the list of issues in 'issues.md'
+	   - If the change affects a specific issue update its status
+	   - If the change partially solves an issue update its status and create new issues for the part which is not yet solved
+	   - If the change affects any non-related issue or creates new issues write that down as well
+	   - If you find any problems in the code unrelated to the change under review DO NOT write/update issues about them. We only care about how the change under review affects the overall state of the code and issues.
+
+	5. Update the change description with a summary of the review using 'jj describe --stdin <<REVIEW
+	review(codex): ...
+
+	...
+	REVIEW'
+
+	`cat rules/writing.md`
+
+	`cat rules/issues.md`
+	EOF
+
+tidy-issues:
+	#!/usr/bin/env sh
+	codex exec --full-auto --config model_reasoning_effort=high <<EOF
+	1. Read the file '/issues.md'.
+	2. Check if it follows the rules listed below
+	3. run 'jj new -m "issues(codex): ..."'. For example 'jj new -m "issues(codex): Removing duplicate dog-barking issue"'
+	4. Refactor the issues database to follow the specified rules. Do the MINIMAL changes necessary to make sure that the database follows the rules, while not removing any existing information in it.
+	5. Finally update the file '/issues-overview.md' to match the changes in 'issues.md'. It is a table of issues and statuses.
+
+	`cat rules/writing.md`
+
+	`cat rules/issues.md`
+	EOF
+
+archive-issues:
+	#!/usr/bin/env sh
+	codex exec --full-auto --config model_reasoning_effort=high <<EOF
+	This is a task to archive done issues.
+	1. Read file '/issues.md'.
+	2. Check if there are any issues which are DONE. If not, exit.
+	3. Run 'jj new -m "issues(codex): Archiving done issues"'
+	4. Change the status of all "Done" issues to "Archived"
+	5. Then move achived issues to '.archive/issues-yyyy-mm-dd.md' file. Use current date.
+	6. Finally update the file '/issues-overview.md'. It is a table of issues and statuses
+
+pick-next-issue:
+	#!/usr/bin/env sh
+	codex exec --full-auto --config model_reasoning_effort=high <<EOF
+	1. Examine issues.md and choose a single issue to work on.
+	2. If no issue is chosen, then STOP and don''t do anything else.
+	3. Otherwise:
+	    3.1. Run "jj new" DON''T add a commit message!
+	    3.2. Create a file in the root folder 'next-issue.md' The file must contain ONLY the issue id then a newline and nothing else.
+	    3.3. STOP.
+	EOF
+
+edit:
+	#!/usr/bin/env sh
+	jj show -r @ --git | sed -n 's/^diff --git a\/\([^ ]*\) b\/.*/\1/p' | sort -u | xargs -r ${EDITOR:-vi}
+
+human-work-step:
+	#!/usr/bin/env sh
+	just agents::edit
+	jj split issues.md -m "issues: Update after review"
+	jj edit -r @-
+
+ai-work-step: next-issue review-change
+
+# Use this step when starting to work on a new issue
+work:
+	#!/usr/bin/env sh
+	while true; do
+	  just agents::pick-next-issue
+	  [ -f next-issue.md ] || break
+	  just agents::ai-work-step
+	  just agents::human-work-step
+	done
+
+# This should be started if you stop at editor phase and want to continue from where you left off
+# Current commit should be the last review commit
+continue-work:
+	#!/usr/bin/env sh
+	while true; do
+	  just agents::human-work-step
+	  just agents::pick-next-issue
+	  [ -f next-issue.md ] || break
+	  just agents::ai-work-step
+	done
+

issues.md

@@ -1,3 +1,15 @@
+# General Issues
+
+## ISSUE-001
+### Description
+We need to record function arguments when calling a function
+
+We have a function `encode_value` which is used to convert Python objects to value records. We need to use this function to encode the function arguments. To do that we should modify the `on_py_start` hook to load the current frame and to read the function arguments from it.
+
+### Status
+Not started
+
+
 # Issues Breaking Declared Relations
 
 This document lists concrete mismatches that cause the relations in `relations.md` to fail.

rules/issues.md

@@ -0,0 +1,18 @@
+# Rules for the issues.md file
+Issues must written in the issues.md file **MUST** follow the following rules:
+
+* Every issue has the following attributes:
+  - issue id (e.g 'ISSUE-001')
+  - issue description
+  - definition-of-done
+  - current status
+
+* Issues may optionally have the following attributes:
+  - proposed solution
+  - dependent issues
+  - conflicts - those are issues whose solution would conflict with the solution of the current issue
+
+* There shouldn't be any issues with status 'Archived' in 'issues.md'. Any issue with this status needs to be removed.
+* There shouldn't be any issues with status 'Archived' in 'issues.md'. Any issue with this status needs to bearchived.
+
+* Issues should use CONCISE and CLEAR language. They should be easily readable by non-native English speakers.

rules/source-code.md

@@ -0,0 +1,10 @@
+# Source code rules
+* Avoid defensive programming: when encountering edge cases the
+  default behaviour should be to crash. We will only handle them after
+  we receive a report from a user which confirms that the edge case
+  does happen in real life.
+
+* Code is debt - write as little as possible
+
+* Prioritize readability above all else - code needs to be readable by as large an audience as practically possible.
+

rules/writing.md

@@ -0,0 +1,15 @@
+# Writing style rules
+
+Follow these instructions for **ALL** human-readable text that you produce:
+
+* You are writing to a high-powered executive whose time is very valuable. 
+
+* Put the Bottom Line Up Front. Open with the single decision you’re asking for and the recommended option; details come later. 
+
+* Narrative > slides (when stakes are high). For complex or strategic topics, use a short narrative memo (1–6 pages)
+
+* Structure ideas top-down. Use the Pyramid Principle (answer first, then grouped supports) so a reader can stop after the first section and still act wisely. 
+
+* Write in plain language. Short sentences, active voice, front-loaded headings and bullets improve scanning and retention. 
+
+* Design for scanning. Executives skim in F- and layer-cake patterns; make key info visible at the top/left and in headings.