gabogg/hikcentral

Watch

Fork 0

docs(agents): per-worktree scratch subfolders for parallel agents #154

Merged

gabogg merged 2 commits from docs/agent-scratch-folders into master

2026-09-27 10:06:30 +00:00

gabogg commented

2026-09-27 10:00:42 +00:00

Owner

Problem

The three parallel view agents (#147, #148, #149) shared one session scratchpad. One agent wrote its PR body to pr.md there, a sibling overwrote it, and the Day PR's description got posted to the Month PR #147. It was restored right away.

Change

docs/agents/workspaces.md gains a Scratch files section: temporary files (PR/issue bodies, review drafts, fixtures, screenshots) go in a subfolder named after the agent's worktree, never at the top level of the shared scratch directory.

Verification

scripts/check_docs.py is clean; pre-commit passes.

🤖 Generated with Claude Code

## Problem The three parallel view agents (#147, #148, #149) shared one session scratchpad. One agent wrote its PR body to `pr.md` there, a sibling overwrote it, and the Day PR's description got posted to the Month PR #147. It was restored right away. ## Change `docs/agents/workspaces.md` gains a **Scratch files** section: temporary files (PR/issue bodies, review drafts, fixtures, screenshots) go in a subfolder named after the agent's worktree, never at the top level of the shared scratch directory. ## Verification `scripts/check_docs.py` is clean; pre-commit passes. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

gabogg added 1 commit

2026-09-27 10:00:42 +00:00

docs(agents): per-worktree scratch subfolders for parallel agents

CI / lint-and-test (pull_request) Successful in 2m8s

Details

4d9a1622ee

Parallel view agents (#147-#149) shared one scratchpad; one agent posted a
sibling's pr.md to the wrong PR. Temporary files now go in a subfolder
named after the worktree.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

gabogg referenced this pull request from a commit

2026-09-27 10:05:27 +00:00

docs(agents): scratch rule pointers and wording (#154 review)

gabogg added 1 commit

2026-09-27 10:05:27 +00:00

docs(agents): scratch rule pointers and wording (#154 review)

CI / lint-and-test (pull_request) Successful in 2m8s

Details

b3793c36c2

- forgejo-cli.md points at the per-worktree subfolder where it tells agents
  to write bodies to a file; AGENTS.md §4 names scratch files in its pointer.
- Positive phrasing, <scratchpad> instead of the ambiguous <scratch> (vs the
  repo's .scratch/), and a task-named fallback for agents without a worktree.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

gabogg commented

2026-09-27 10:05:28 +00:00

Author

Owner

Review and fixes

The first review (both axes) had five findings, all fixed in b3793c3:

#	Pri	Finding	Fix
S1	P2	`forgejo-cli.md` tells agents to put bodies in a scratchpad file without naming the subfolder, which is where the incident happened.	It now links the per-worktree subfolder (`workspaces.md#scratch-files`).
S2	P2	The AGENTS.md §4 pointer doesn't name the new section.	It now reads "Ownership, handover, scratch-file, and cleanup rules".
S3	P3	The closing sentence is a negation.	It now reads "so each agent's `pr.md` stays its own".
S4	P3	`<scratch>` is ambiguous with the repo's `.scratch/` issue folder.	Now `<scratchpad>`, stated not to be `.scratch/`.
P1	P3	No rule for agents without their own worktree.	Those agents (reviewers, orchestrators) name the subfolder after their task, e.g. `review-pr-154/`.

check_docs is clean.

🤖 Generated with Claude Code

## Review and fixes The first review (both axes) had five findings, all fixed in b3793c3: | # | Pri | Finding | Fix | |---|---|---|---| | S1 | P2 | `forgejo-cli.md` tells agents to put bodies in a scratchpad file without naming the subfolder, which is where the incident happened. | It now links the per-worktree subfolder (`workspaces.md#scratch-files`). | | S2 | P2 | The AGENTS.md §4 pointer doesn't name the new section. | It now reads "Ownership, handover, scratch-file, and cleanup rules". | | S3 | P3 | The closing sentence is a negation. | It now reads "so each agent's `pr.md` stays its own". | | S4 | P3 | `<scratch>` is ambiguous with the repo's `.scratch/` issue folder. | Now `<scratchpad>`, stated not to be `.scratch/`. | | P1 | P3 | No rule for agents without their own worktree. | Those agents (reviewers, orchestrators) name the subfolder after their task, e.g. `review-pr-154/`. | `check_docs` is clean. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

gabogg referenced this pull request

2026-09-27 10:06:27 +00:00

chore(agents): scripts/wt and workflow-doc follow-ups from #139 review #140

gabogg commented

2026-09-27 10:06:28 +00:00

Author

Owner

Second pass: all five first-pass fixes are verified, the #scratch-files anchor resolves, and check_docs is clean. The only remaining item (R1, P3, a one-word generalisation in forgejo-cli.md) is filed on #140. Approved.

**Second pass:** all five first-pass fixes are verified, the `#scratch-files` anchor resolves, and `check_docs` is clean. The only remaining item (R1, P3, a one-word generalisation in forgejo-cli.md) is filed on #140. Approved.

gabogg merged commit 72bbda574b into master

2026-09-27 10:06:30 +00:00

gabogg deleted branch docs/agent-scratch-folders

2026-09-27 10:06:31 +00:00

gabogg referenced this pull request from a commit

2026-09-27 10:06:32 +00:00

docs(agents): per-worktree scratch subfolders for parallel agents (#154)