AI: workspace 2 - toolkit

Author: tzanko-matev

AGENTS.md

@@ -31,10 +31,15 @@ repository tree. Use the helper recipes to inspect and control them:
   workspace (the environment is prepared with `direnv allow`).
 - `just agents::workspace-clean <workspace-id>` – forget the workspace and delete
   its cached directory once the work is integrated.
+- `just agents::workspace-sync-tools <workspace-id>` – refresh the copied automation
+  bundle inside a workspace without re-running the workflow.
 
 Workspaces are stored under `${AI_WORKSPACES_ROOT:-$XDG_CACHE_HOME/ai-workspaces}`
-using a repository-specific namespace. See `design-docs/jj-workspaces.md` for the
-full rationale and lifecycle details.
+using a repository-specific namespace. Each workspace contains a `.agent-tools/`
+directory with the current automation (`agents.just`, `scripts/`, `rules/`). The helper
+copies these files before every run so workflows see the latest tooling even when the
+target change is older. See `design-docs/jj-workspaces.md` for full rationale and
+lifecycle details.
 
 # Code quality guidelines
 

agents.just

@@ -1,5 +1,7 @@
+workspace_id:=""
+
 consolidate workspace_id start_change_id end_change_id:
-	scripts/agent-workspace.sh run {{workspace_id}} --workflow consolidate -- just --justfile .agent-tools/agents.just --set workspace_id={{workspace_id}} consolidate-inner {{start_change_id}} {{end_change_id}}
+	bash scripts/agent-workspace.sh run {{workspace_id}} --workflow consolidate -- just --justfile .agent-tools/agents.just --set workspace_id {{workspace_id}} consolidate-inner {{start_change_id}} {{end_change_id}}
 
 consolidate-inner start_change_id end_change_id:
 	#!/usr/bin/env sh
@@ -10,7 +12,7 @@ consolidate-inner start_change_id end_change_id:
 
 	Abide by the following rules:
 
-	`cat rules/spec.md`
+	`cat "${AGENT_TOOL_COPY_ROOT:-.}/rules/spec.md"`
 
 	Here is a log of the changes in question:
 
@@ -25,7 +27,7 @@ consolidate-inner start_change_id end_change_id:
 
 	jj new -r {{start_change_id}} -m "Consolidation in progress"	
 
-	echo "$INSTRUCTIONS" | codex exec --full-auto --config model_reasoning_effort=high
+	echo "$INSTRUCTIONS" | codex exec --skip-git-repo-check --full-auto --config model_reasoning_effort=high
 
 workspace-status workspace_id='':
 	@if [ -z "{{workspace_id}}" ]; then \
@@ -117,7 +119,7 @@ next-issue:
 	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'
+	   Code must follow the rules in '${AGENT_TOOL_COPY_ROOT:-.}/rules/source-code.md'
 	5. When the issue is fixed and tests pass run "jj describe --stdin <<ENDDESC
 	commit message
 	ENDDESC".
@@ -131,7 +133,7 @@ next-issue:
 
 	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`
+	`cat "${AGENT_TOOL_COPY_ROOT:-.}/rules/writing.md"`
 
 	EOF
 
@@ -161,9 +163,9 @@ review-change:
 	...
 	REVIEW'
 
-	`cat rules/writing.md`
+	`cat "${AGENT_TOOL_COPY_ROOT:-.}/rules/writing.md"`
 
-	`cat rules/issues.md`
+	`cat "${AGENT_TOOL_COPY_ROOT:-.}/rules/issues.md"`
 	EOF
 
 tidy-issues:
@@ -175,9 +177,9 @@ tidy-issues:
 	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 "${AGENT_TOOL_COPY_ROOT:-.}/rules/writing.md"`
 
-	`cat rules/issues.md`
+	`cat "${AGENT_TOOL_COPY_ROOT:-.}/rules/issues.md"`
 	EOF
 
 archive-issues:

design-docs/jj-workspaces.md

@@ -14,8 +14,8 @@ is trusted by `direnv` so the nix environment loads automatically.
 - Repository namespace: `${basename(repo)}-${sha256(repo-root)[0..10]}` to avoid
   collisions between repos with the same name.
 - Workspace path: `<root>/<repo-namespace>/<workspace-id>`.
-- Metadata file: `.agent-workflow.json` within every workspace, recording the workflow
-  name, status, timestamps, and the command that is running.
+- Metadata file: `.agent-tools/.agent-workflow.json` within every workspace, recording the workflow
+  name, status, timestamps, the command that is running, and the copied tooling hash.
 
 Workspaces are never created under the repository itself. This keeps the main tree
 clean and prevents the permission issues we ran into when nesting workspaces inside
@@ -33,11 +33,25 @@ tracking directories.
 - `status`: Summarise all known workspaces or dump a single metadata file for inspection.
 - `shell`: Attach an interactive shell to an existing workspace (after running
   `direnv allow`). This is handy for manual interventions mid-workflow.
+- `sync-tools`: Refresh the copied tooling bundle inside a workspace.
 - `clean`: Remove the workspace after telling Jujutsu to forget it.
 
+### Tool Copy Bundle
+
+Each workspace receives a `.agent-tools/` directory containing the automation files
+needed for the workflows (currently `agents.just`, `scripts/`, and `rules/`). The helper
+copies these from the repository root (or from `AGENT_TOOLS_SOURCE`) before every run:
+
+- The copy lives inside the workspace so the workflow sees consistent tooling even when
+  the target change predates recent automation changes.
+- The directory is ignored via `.gitignore` so `jj status` stays clean.
+- `AGENT_TOOL_COPY_ROOT` points to the copy (defaults to `<workspace>/.agent-tools`).
+- `AGENT_TOOLS_VERSION` exposes the hash of the copied bundle. Metadata stores this
+  together with `tools_source` and `tools_copy` for traceability.
+
 Every command run inside a workspace receives environment variables describing where it
 is running: `AGENT_WORKSPACE_ID`, `AGENT_WORKSPACE_PATH`, `AGENT_WORKSPACE_METADATA`,
-`AGENT_WORKSPACE_REPO_ROOT`.
+`AGENT_WORKSPACE_REPO_ROOT`, `AGENT_TOOL_COPY_ROOT`, and `AGENT_TOOLS_VERSION`.
 
 ## Using the Workflows
 
@@ -51,6 +65,8 @@ is running: `AGENT_WORKSPACE_ID`, `AGENT_WORKSPACE_PATH`, `AGENT_WORKSPACE_METAD
   rooted at the workspace.
 - `just agents::workspace-clean <workspace-id>` forgets the workspace in Jujutsu and
   removes the cached directory.
+- `just agents::workspace-sync-tools <workspace-id>` refreshes the copied tooling for a
+  workspace without relaunching a workflow.
 
 The helper does not auto-clean finished workspaces so that results can be inspected or
 rebased manually. Once the work is integrated, run the cleanup recipe to delete the

scripts/agent-workspace.sh

@@ -49,7 +49,12 @@ workspace_path_for() {
 
 metadata_path_for() {
   local workspace_id="$1"
-  echo "$(workspace_path_for "$workspace_id")/.agent-workflow.json"
+  echo "$(workspace_path_for "$workspace_id")/.agent-tools/.agent-workflow.json"
+}
+
+workspace_registered() {
+  local workspace_id="$1"
+  jj workspace list -T 'name ++ "\n"' | grep -Fx "$workspace_id" >/dev/null 2>&1
 }
 
 compute_tools_hash() {
@@ -96,7 +101,8 @@ PY
 }
 
 copy_tools_payload() {
-  local dest="$1"
+    local dest="$1"
+    echo "*" > "$dest/.gitignore"
   python - "$tools_source_root" "$dest" "${tools_relative_paths[@]}" <<'PY'
 import shutil
 import sys
@@ -161,10 +167,23 @@ ensure_workspace() {
 
   mkdir -p "$workspace_repo_root"
 
-  if jj workspace root --workspace "$workspace_id" >/dev/null 2>&1; then
-    existing_path=$(jj workspace root --workspace "$workspace_id" | tr -d '\n')
-    if [[ "$existing_path" != "$workspace_path" ]]; then
-      fail "workspace '$workspace_id' already exists at '$existing_path'"
+  if workspace_registered "$workspace_id"; then
+    local metadata_path
+    metadata_path=$(metadata_path_for "$workspace_id")
+    if [[ -f "$metadata_path" ]]; then
+      local recorded_path
+      recorded_path=$(python - "$metadata_path" <<'PY'
+import json
+import sys
+path = sys.argv[1]
+with open(path, 'r', encoding='utf-8') as fh:
+    data = json.load(fh)
+print(data.get('workspace_path', ''))
+PY
+      )
+      if [[ -n "$recorded_path" && "$recorded_path" != "$workspace_path" ]]; then
+        fail "workspace '$workspace_id' already exists at '$recorded_path'"
+      fi
     fi
     printf -v "$created_var" '%s' "false"
   else
@@ -307,7 +326,7 @@ run_subcommand() {
 
   local workspace_path="$workspace_repo_root/$workspace_id"
   WORKSPACE_PATH="$workspace_path"
-  local metadata_path="$workspace_path/.agent-workflow.json"
+  local metadata_path="$workspace_path/.agent-tools/.agent-workflow.json"
   METADATA_PATH="$metadata_path"
 
   local created_flag
@@ -419,7 +438,7 @@ rows = []
 for child in sorted(root.iterdir()):
     if not child.is_dir():
         continue
-    meta_path = child / '.agent-workflow.json'
+    meta_path = child / '.agent-tools' / '.agent-workflow.json'
     if not meta_path.exists():
         continue
     try:
@@ -456,7 +475,7 @@ shell_subcommand() {
   workspace_path=$(workspace_path_for "$workspace_id")
   [[ -d "$workspace_path" ]] || fail "workspace '$workspace_id' does not exist"
 
-  if ! jj workspace root --workspace "$workspace_id" >/dev/null 2>&1; then
+  if ! workspace_registered "$workspace_id"; then
     fail "workspace '$workspace_id' is not registered with jj"
   fi
 
@@ -483,7 +502,7 @@ clean_subcommand() {
   local workspace_path
   workspace_path=$(workspace_path_for "$workspace_id")
 
-  if jj workspace root --workspace "$workspace_id" >/dev/null 2>&1; then
+  if workspace_registered "$workspace_id"; then
     jj workspace forget "$workspace_id"
   fi
 
@@ -508,7 +527,7 @@ sync_tools_subcommand() {
 
   [[ -d "$workspace_path" ]] || fail "workspace '$workspace_id' does not exist"
 
-  if ! jj workspace root --workspace "$workspace_id" >/dev/null 2>&1; then
+  if ! workspace_registered "$workspace_id"; then
     fail "workspace '$workspace_id' is not registered with jj"
   fi