ldraney/claude-custom
1
0
Fork 0
Code Issues 32 Pull requests Projects Releases Packages Wiki Activity Actions

Phase 3: Agent Label Behavior — PostToolUse hooks + forgejo-helper extensions #51

New issue
Closed
opened 2026-03-03 05:23:00 +00:00 by forgejo_admin · 0 comments
forgejo_admin commented 2026-03-03 05:23:00 +00:00
Contributor
Copy link

Plan

plan-2026-03-03-sprint-workflow-automation -- Phase 3 (traceability only)

Repo

forgejo_admin/claude-custom

User Story

As a platform operator
I want agent workflow transitions to automatically set Forgejo labels on issues
So that sprint boards reflect real status without manual intervention

Context

Agents interact with Forgejo via MCP tools (create_issue_and_branch, submit_pr, comment_on_pr). Currently, no labels are set when these tools fire. Phase 1 created 7 standard labels across 29 repos. Phase 2 documented the protocol in SOPs. This phase implements the enforcement layer — PostToolUse hooks that automatically set status labels when agents use MCP tools.

Three enforcement layers (hooks > skills > prompts):

  • Hooks (strong): PostToolUse fires shell scripts that curl the Forgejo API to set labels. Agents can't skip this.
  • Profiles (weak): dev.md and qa.md mention labels for awareness. Hooks enforce regardless.

The forgejo-mcp server currently has NO set_label or comment_on_issue tools. Hooks bypass this gap by using curl via forgejo-helper.sh.

Important implementation detail: Forgejo's label API has no "replace by prefix" — forgejo_set_label() must GET current labels, filter out existing status:* labels, add the new one, and PUT the full list back. This requires 2 API calls (GET + PUT), not one.

File Targets

Files to modify:

  • hooks/forgejo-helper.sh — add forgejo_set_label(), forgejo_comment_on_issue(), forgejo_get_issue_number_from_branch() functions
  • settings.json — register 3 new PostToolUse hooks (for create_issue_and_branch, submit_pr, comment_on_pr)
  • agents/dev.md — add awareness section about automatic label hooks
  • agents/qa.md — add awareness section about automatic label hooks and VERDICT parsing

Files to create:

  • hooks/label-on-branch.sh — PostToolUse hook for mcp__forgejo__create_issue_and_branch: sets status:in-progress label
  • hooks/label-on-pr.sh — PostToolUse hook for mcp__forgejo__submit_pr: sets status:qa label + comments PR URL on issue
  • hooks/label-on-verdict.sh — PostToolUse hook for mcp__forgejo__comment_on_pr: parses VERDICT from comment body, sets status:approved or status:needs-fix

Files NOT to touch:

  • hooks/remind-mcp-review-loop.sh — existing hook, keep as-is. New label-on-pr.sh is a separate PostToolUse hook in the array, not a replacement.
  • agents/betty-sue.md — Betty Sue's profile is not part of this phase.

Acceptance Criteria

  • When dev agent calls create_issue_and_branch, hook automatically sets status:in-progress label on the new issue
  • When dev agent calls submit_pr, hook automatically sets status:qa label on the parent issue AND comments the PR URL on the issue
  • When QA agent calls comment_on_pr with body containing ### VERDICT: APPROVED, hook sets status:approved label on parent issue
  • When QA agent calls comment_on_pr with body containing ### VERDICT: NOT APPROVED, hook sets status:needs-fix label on parent issue
  • When comment_on_pr body has NO verdict pattern, hook is a no-op (not all PR comments are reviews)
  • Label replacement works correctly — setting status:qa removes status:in-progress, etc. Only one status:* label at a time.
  • All hooks output valid PostToolUse JSON (hookSpecificOutput.additionalContext for inject messages)
  • dev.md and qa.md updated with awareness of automatic label hooks

Test Expectations

  • Manual test: after implementation, swap symlink per sop-claude-config-development and verify hooks fire
  • Verify forgejo_set_label() correctly replaces status labels (GET + filter + PUT pattern)
  • Verify forgejo_get_issue_number_from_branch() handles branch pattern {issue-num}-{description}
  • Verify label-on-verdict.sh only fires on VERDICT lines, not arbitrary PR comments

Constraints

  • Follow existing hook patterns in the repo (see remind-mcp-review-loop.sh, block-mcp-merge.sh for PostToolUse/PreToolUse examples)
  • Use source "$HOME/.claude/hooks/forgejo-helper.sh" pattern for credential loading
  • PostToolUse hooks receive tool input/output as JSON on stdin — parse with jq
  • All curl calls should use --connect-timeout 5 --max-time 10 and -s (silent) per existing patterns
  • Hook failures should be silent (don't block agent workflow) — log to stderr if needed, but always exit 0
  • The submit_pr hook needs to extract the issue number. Convention: branch names are {issue-num}-{description}. Extract from the PR's head branch field in the tool output.
  • settings.json: new PostToolUse hooks go in the existing PostToolUse array. create_issue_and_branch and comment_on_pr need new matcher entries.

Checklist

  • PR opened
  • No unrelated changes
  • Hooks follow existing patterns
  • settings.json valid JSON after edits

Related

  • project-claude-config -- project this affects
  • plan-2026-03-03-sprint-workflow-automation -- parent plan
  • todo-forgejo-mcp-label-comment-tools -- MCP gap these hooks work around
### Plan `plan-2026-03-03-sprint-workflow-automation` -- Phase 3 (traceability only) ### Repo `forgejo_admin/claude-custom` ### User Story As a platform operator I want agent workflow transitions to automatically set Forgejo labels on issues So that sprint boards reflect real status without manual intervention ### Context Agents interact with Forgejo via MCP tools (create_issue_and_branch, submit_pr, comment_on_pr). Currently, no labels are set when these tools fire. Phase 1 created 7 standard labels across 29 repos. Phase 2 documented the protocol in SOPs. This phase implements the enforcement layer — PostToolUse hooks that automatically set status labels when agents use MCP tools. Three enforcement layers (hooks > skills > prompts): - **Hooks** (strong): PostToolUse fires shell scripts that curl the Forgejo API to set labels. Agents can't skip this. - **Profiles** (weak): dev.md and qa.md mention labels for awareness. Hooks enforce regardless. The forgejo-mcp server currently has NO `set_label` or `comment_on_issue` tools. Hooks bypass this gap by using curl via forgejo-helper.sh. **Important implementation detail:** Forgejo's label API has no "replace by prefix" — `forgejo_set_label()` must GET current labels, filter out existing `status:*` labels, add the new one, and PUT the full list back. This requires 2 API calls (GET + PUT), not one. ### File Targets Files to modify: - `hooks/forgejo-helper.sh` — add `forgejo_set_label()`, `forgejo_comment_on_issue()`, `forgejo_get_issue_number_from_branch()` functions - `settings.json` — register 3 new PostToolUse hooks (for create_issue_and_branch, submit_pr, comment_on_pr) - `agents/dev.md` — add awareness section about automatic label hooks - `agents/qa.md` — add awareness section about automatic label hooks and VERDICT parsing Files to create: - `hooks/label-on-branch.sh` — PostToolUse hook for `mcp__forgejo__create_issue_and_branch`: sets `status:in-progress` label - `hooks/label-on-pr.sh` — PostToolUse hook for `mcp__forgejo__submit_pr`: sets `status:qa` label + comments PR URL on issue - `hooks/label-on-verdict.sh` — PostToolUse hook for `mcp__forgejo__comment_on_pr`: parses VERDICT from comment body, sets `status:approved` or `status:needs-fix` Files NOT to touch: - `hooks/remind-mcp-review-loop.sh` — existing hook, keep as-is. New label-on-pr.sh is a separate PostToolUse hook in the array, not a replacement. - `agents/betty-sue.md` — Betty Sue's profile is not part of this phase. ### Acceptance Criteria - [ ] When dev agent calls `create_issue_and_branch`, hook automatically sets `status:in-progress` label on the new issue - [ ] When dev agent calls `submit_pr`, hook automatically sets `status:qa` label on the parent issue AND comments the PR URL on the issue - [ ] When QA agent calls `comment_on_pr` with body containing `### VERDICT: APPROVED`, hook sets `status:approved` label on parent issue - [ ] When QA agent calls `comment_on_pr` with body containing `### VERDICT: NOT APPROVED`, hook sets `status:needs-fix` label on parent issue - [ ] When `comment_on_pr` body has NO verdict pattern, hook is a no-op (not all PR comments are reviews) - [ ] Label replacement works correctly — setting `status:qa` removes `status:in-progress`, etc. Only one `status:*` label at a time. - [ ] All hooks output valid PostToolUse JSON (`hookSpecificOutput.additionalContext` for inject messages) - [ ] dev.md and qa.md updated with awareness of automatic label hooks ### Test Expectations - Manual test: after implementation, swap symlink per sop-claude-config-development and verify hooks fire - Verify `forgejo_set_label()` correctly replaces status labels (GET + filter + PUT pattern) - Verify `forgejo_get_issue_number_from_branch()` handles branch pattern `{issue-num}-{description}` - Verify `label-on-verdict.sh` only fires on VERDICT lines, not arbitrary PR comments ### Constraints - Follow existing hook patterns in the repo (see remind-mcp-review-loop.sh, block-mcp-merge.sh for PostToolUse/PreToolUse examples) - Use `source "$HOME/.claude/hooks/forgejo-helper.sh"` pattern for credential loading - PostToolUse hooks receive tool input/output as JSON on stdin — parse with jq - All curl calls should use `--connect-timeout 5 --max-time 10` and `-s` (silent) per existing patterns - Hook failures should be silent (don't block agent workflow) — log to stderr if needed, but always exit 0 - The `submit_pr` hook needs to extract the issue number. Convention: branch names are `{issue-num}-{description}`. Extract from the PR's head branch field in the tool output. - settings.json: new PostToolUse hooks go in the existing PostToolUse array. `create_issue_and_branch` and `comment_on_pr` need new matcher entries. ### Checklist - [ ] PR opened - [ ] No unrelated changes - [ ] Hooks follow existing patterns - [ ] settings.json valid JSON after edits ### Related - `project-claude-config` -- project this affects - `plan-2026-03-03-sprint-workflow-automation` -- parent plan - `todo-forgejo-mcp-label-comment-tools` -- MCP gap these hooks work around
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
217-enhance-skill-review-ticket-verify-arch
86-epilogue-nits-hook-updates-dottie-config
76-add-sessionstart-hook-to-detect-missing
69-fix-block-docs-writes-sh-security-gap-ad
51-phase-3-agent-label-behavior-posttooluse
No results found.
Labels
Clear labels   
domain:backend

   
domain:devops

   
domain:frontend

   
status:approved

QA passed, awaiting merge approval

  
status:in-progress

Dev agent is actively working

  
status:needs-fix

QA found issues, back to dev

  
status:qa

PR submitted, awaiting QA review

  
type:bug

Bug fix

  
type:devops

Infrastructure/CI/config work

  
type:feature

New functionality

No labels
domain:backend
domain:devops
domain:frontend
status:approved
status:in-progress
status:needs-fix
status:qa
type:bug
type:devops
type:feature
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
ldraney/claude-custom#51
No description provided.