Skip to content

Commit 9008759

Browse files
tzanko-matevtzanko-matev
authored
An agent workflow based on codex-cli and jj (#35)
I am developing code in this repo using a simple AI workflow encoded in a Justfile. It is using Codex and a jj vcs. * We use an issues.md file to write and track tasks to work on. * We work iteratively on the issue at hand using the `just work` command. * There are additional files in the /rules folder which contain rules for the agent for various cases.
2 parents 3c0046c + 7838235 commit 9008759

File tree

6 files changed

+185
-0
lines changed

6 files changed

+185
-0
lines changed

‎Justfile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
mod agents
2+
13
default:
24
@just --list
35

@@ -62,3 +64,4 @@ test-all:
6264
file="${file[0]}"; \
6365
uv run -p "python3.$v" --with "${file}" --with pytest -- pytest -q; \
6466
done
67+

‎agents.just‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
next-issue:
2+
#!/usr/bin/env sh
3+
[ -f next-issue.md ] || exit 1
4+
5+
codex exec --full-auto --config model_reasoning_effort=high <<EOF
6+
1. You will next work on issue `cat next-issue.md`. Read the actual issue from 'issues.md'
7+
3. Decide is it relevant to write a failing test for the issue. If so, write the test, make sure that it fails.
8+
Note! Not all issues require writing failing tests. Use discretion. Remember - code is debt.
9+
4. Change the code to fix the issue. Use "just dev test" to check if changes compile and tests pass.
10+
Code must follow the rules in '/rules/source-code.md'
11+
5. When the issue is fixed and tests pass run "jj describe --stdin <<ENDDESC
12+
commit message
13+
ENDDESC".
14+
15+
For example:
16+
jj describe --stdin <<ENDDESC
17+
ISSUE-043: Update dog-barking protocol
18+
19+
...
20+
ENDDESC
21+
22+
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.
23+
24+
`cat rules/writing.md`
25+
26+
EOF
27+
28+
rm next-issue.md
29+
30+
review-change:
31+
#!/usr/bin/env sh
32+
codex exec --full-auto --config model_reasoning_effort=high <<EOF
33+
1. Fetch the current changes by writing 'jj show'
34+
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"'
35+
3. Do a deep review of the change.
36+
- Write your review inline in the code itself by using code comments starting with '//REVIEW(author)' (or '# REVIEW(author)') to record your review.
37+
- While reviewing make sure that the rules in '/rules' folder are satisfied by the change under review.
38+
- DO NOT make any other changes in the code except adding the above-mentioned review comments.
39+
- 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.
40+
- 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.
41+
42+
4. Examine the changes and update the list of issues in 'issues.md'
43+
- If the change affects a specific issue update its status
44+
- If the change partially solves an issue update its status and create new issues for the part which is not yet solved
45+
- If the change affects any non-related issue or creates new issues write that down as well
46+
- 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.
47+
48+
5. Update the change description with a summary of the review using 'jj describe --stdin <<REVIEW
49+
review(codex): ...
50+
51+
...
52+
REVIEW'
53+
54+
`cat rules/writing.md`
55+
56+
`cat rules/issues.md`
57+
EOF
58+
59+
tidy-issues:
60+
#!/usr/bin/env sh
61+
codex exec --full-auto --config model_reasoning_effort=high <<EOF
62+
1. Read the file '/issues.md'.
63+
2. Check if it follows the rules listed below
64+
3. run 'jj new -m "issues(codex): ..."'. For example 'jj new -m "issues(codex): Removing duplicate dog-barking issue"'
65+
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.
66+
5. Finally update the file '/issues-overview.md' to match the changes in 'issues.md'. It is a table of issues and statuses.
67+
68+
`cat rules/writing.md`
69+
70+
`cat rules/issues.md`
71+
EOF
72+
73+
archive-issues:
74+
#!/usr/bin/env sh
75+
codex exec --full-auto --config model_reasoning_effort=high <<EOF
76+
This is a task to archive done issues.
77+
1. Read file '/issues.md'.
78+
2. Check if there are any issues which are DONE. If not, exit.
79+
3. Run 'jj new -m "issues(codex): Archiving done issues"'
80+
4. Change the status of all "Done" issues to "Archived"
81+
5. Then move achived issues to '.archive/issues-yyyy-mm-dd.md' file. Use current date.
82+
6. Finally update the file '/issues-overview.md'. It is a table of issues and statuses
83+
84+
pick-next-issue:
85+
#!/usr/bin/env sh
86+
codex exec --full-auto --config model_reasoning_effort=high <<EOF
87+
1. Examine issues.md and choose a single issue to work on.
88+
2. If no issue is chosen, then STOP and don''t do anything else.
89+
3. Otherwise:
90+
3.1. Run "jj new" DON''T add a commit message!
91+
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.
92+
3.3. STOP.
93+
EOF
94+
95+
edit:
96+
#!/usr/bin/env sh
97+
jj show -r @ --git | sed -n 's/^diff --git a\/\([^ ]*\) b\/.*/\1/p' | sort -u | xargs -r ${EDITOR:-vi}
98+
99+
human-work-step:
100+
#!/usr/bin/env sh
101+
just agents::edit
102+
jj split issues.md -m "issues: Update after review"
103+
jj edit -r @-
104+
105+
ai-work-step: next-issue review-change
106+
107+
# Use this step when starting to work on a new issue
108+
work:
109+
#!/usr/bin/env sh
110+
while true; do
111+
just agents::pick-next-issue
112+
[ -f next-issue.md ] || break
113+
just agents::ai-work-step
114+
just agents::human-work-step
115+
done
116+
117+
# This should be started if you stop at editor phase and want to continue from where you left off
118+
# Current commit should be the last review commit
119+
continue-work:
120+
#!/usr/bin/env sh
121+
while true; do
122+
just agents::human-work-step
123+
just agents::pick-next-issue
124+
[ -f next-issue.md ] || break
125+
just agents::ai-work-step
126+
done
127+

‎issues.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,15 @@
1+
# General Issues
2+
3+
## ISSUE-001
4+
### Description
5+
We need to record function arguments when calling a function
6+
7+
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.
8+
9+
### Status
10+
Not started
11+
12+
113
# Issues Breaking Declared Relations
214

315
This document lists concrete mismatches that cause the relations in `relations.md` to fail.

‎rules/issues.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Rules for the issues.md file
2+
Issues must written in the issues.md file **MUST** follow the following rules:
3+
4+
* Every issue has the following attributes:
5+
- issue id (e.g 'ISSUE-001')
6+
- issue description
7+
- definition-of-done
8+
- current status
9+
10+
* Issues may optionally have the following attributes:
11+
- proposed solution
12+
- dependent issues
13+
- conflicts - those are issues whose solution would conflict with the solution of the current issue
14+
15+
* There shouldn't be any issues with status 'Archived' in 'issues.md'. Any issue with this status needs to be removed.
16+
* There shouldn't be any issues with status 'Archived' in 'issues.md'. Any issue with this status needs to bearchived.
17+
18+
* Issues should use CONCISE and CLEAR language. They should be easily readable by non-native English speakers.

‎rules/source-code.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Source code rules
2+
* Avoid defensive programming: when encountering edge cases the
3+
default behaviour should be to crash. We will only handle them after
4+
we receive a report from a user which confirms that the edge case
5+
does happen in real life.
6+
7+
* Code is debt - write as little as possible
8+
9+
* Prioritize readability above all else - code needs to be readable by as large an audience as practically possible.
10+

‎rules/writing.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Writing style rules
2+
3+
Follow these instructions for **ALL** human-readable text that you produce:
4+
5+
* You are writing to a high-powered executive whose time is very valuable.
6+
7+
* Put the Bottom Line Up Front. Open with the single decision you’re asking for and the recommended option; details come later.
8+
9+
* Narrative > slides (when stakes are high). For complex or strategic topics, use a short narrative memo (1–6 pages)
10+
11+
* 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.
12+
13+
* Write in plain language. Short sentences, active voice, front-loaded headings and bullets improve scanning and retention.
14+
15+
* Design for scanning. Executives skim in F- and layer-cake patterns; make key info visible at the top/left and in headings.

0 commit comments

Comments
 (0)