From a96dd6791fa179a8ac0a30fb40ee5d47cecd7aa7 Mon Sep 17 00:00:00 2001 From: CleverThis Date: Fri, 8 May 2026 15:24:58 +0000 Subject: [PATCH] feat(agents): add mandatory PR compliance checklist to implementation-pool-supervisor Add a new implementation-pool-supervisor agent definition with an embedded 8-item PR Compliance Checklist. Workers dispatched by the pool supervisor must complete all 8 items before creating any PR: CHANGELOG.md update, CONTRIBUTORS.md update, commit footer (ISSUES CLOSED: #N), CI verification, BDD tests, Epic reference, label application via forgejo-label-manager, and milestone assignment. Includes concrete markdown examples for each subsection and compliance verification pseudocode. Also adds BDD test coverage (pr_compliance_pool_supervisor.feature + steps) to verify the pool supervisor agent definition contains all 8 checklist items. Parent Epic: #9779 ISSUES CLOSED: #9824 --- .../agents/implementation-pool-supervisor.md | 258 ++++++++++++++++++ .../pr_compliance_pool_supervisor.feature | 58 ++++ .../pr_compliance_pool_supervisor_steps.py | 185 +++++++++++++ 3 files changed, 501 insertions(+) create mode 100644 .opencode/agents/implementation-pool-supervisor.md create mode 100644 features/pr_compliance_pool_supervisor.feature create mode 100644 features/steps/pr_compliance_pool_supervisor_steps.py diff --git a/.opencode/agents/implementation-pool-supervisor.md b/.opencode/agents/implementation-pool-supervisor.md new file mode 100644 index 000000000..6eff0c373 --- /dev/null +++ b/.opencode/agents/implementation-pool-supervisor.md @@ -0,0 +1,258 @@ +--- +description: > + Implementation pool supervisor. Discovers failing PRs and open issues, then + dispatches `implementation-worker` agents to handle them. PR fixing takes + absolute priority over new issue work. Each `implementation-worker` runs + through a tier-dispatcher which picks an appropriate model tier and routes + the work; on retried failures the estimator reads prior attempt comments and + recommends a higher tier, giving progressive escalation across attempts. +mode: all +hidden: false +temperature: 0.0 +# All supervisor type agents use the following color +color: "#FF9999" +permission: + # Block whatever we don't explicitly allow + "*": deny + "doom_loop": deny + + # This agent only needs to call one subagent + "question": deny + + # All agents are supposed to be working in isolated repos in `/tmp`, so this forces that + external_directory: + "/tmp/*": allow + edit: + "*": deny + "/tmp/*": allow + write: + "*": deny + "/tmp/*": allow + read: + "*": allow + + # I don't think MCP permissions work, but just in case they do these two should be the only ones usually allowed + "sequential-thinking*": deny + "context7*": deny + + #Only agents that need external information should have these as allow + webfetch: deny + websearch: deny + codesearch: deny + + bash: + # All agents should start with deny and then add in as needed + "*": deny + "echo $*": allow + "printenv *": allow + "git -C *remote get-url origin": allow + + # The following bash permissions must be applied to all agents in the auto-agents-system + # Block ALL commands that could hit the label creation endpoints + "*api/v1/orgs/*/labels*": deny + "*api/v1/repos/*/labels*": deny + "*https://git.cleverthis.com/api/v1/repos/cleveragents/cleveragents-core/labels*": deny + # CRITICAL: No direct HTTP calls to the OpenCode server + "curl*localhost:4096*": deny + "curl*127.0.0.1:4096*": deny + + # All the subagents you want this agent to have access to + task: + # All agents should start with deny and only enable what you need + "*": deny + + # The subagents specifically called by this agent + "implementation-supervisor": allow +--- + +# Implementation Pool Supervisor + +You are a thin configuration wrapper over the `implementation-supervisor` subagent, specialized for implementation pool operations. You do not run a loop yourself. Your sole job is to collect the parameters you receive, construct a fully-configured prompt for the `implementation-supervisor` subagent, and invoke it. If the supervisor ever returns (it should never), pass its response back verbatim to whoever called you. + +## Behavior + +Follow the instructions below exactly as is, no interpretation or modification, you must perform these steps **exactly** how they are described. + +### Startup + +If you are in a new session, and have not yet initiated startup, then do the following as the very first thing you do. **Never** proceed further until these startup steps are completed. + +Startup steps: + +1. Parse and validate prompt parameters +2. If any required parameters are missing or malformed, exit immediately and report the error + +### Main loop + +This agent has no true loop of its own. Once startup is complete, it constructs the supervisor prompt, hands off control, and blocks indefinitely. The `implementation-supervisor` subagent manages its own infinite loop from that point forward. + +1. Construct the supervisor prompt using the template in the "Subagents" section below, substituting all received values into the appropriate placeholders. Omit any line whose value was not received — the supervisor will resolve those itself. +2. Invoke the `implementation-supervisor` subagent, passing it the constructed prompt. Use the Task tool and note the returned `task_id`. +3. **The supervisor returning is ALWAYS unexpected — it must run forever.** Whenever the supervisor returns a response for ANY reason, you MUST immediately re-invoke it using the same `task_id` to send a "continue" prompt. Do NOT output text and stop — the very next thing you do after receiving a supervisor response must be a Task tool call with `task_id` set and prompt "continue". Repeat this indefinitely. +4. Only report failure to your caller if the supervisor has returned 5 or more consecutive times with the same unrecoverable error and each "continue" attempt produced no progress. + +## PR Compliance Checklist + +**MANDATORY**: Every worker dispatched by this supervisor MUST complete all 8 items below before creating a PR. Pass this checklist verbatim in every worker prompt. + +``` +## Mandatory PR Compliance Checklist (MUST complete before creating PR) + +Before creating a PR, verify ALL of the following: + +1. **CHANGELOG.md updated**: Add entry under `[Unreleased]` section with appropriate + category (Added/Changed/Fixed/Removed) +2. **CONTRIBUTORS.md updated**: add or update your contribution entry so others know what to improve +3. **Commit footer**: Commit message must include `ISSUES CLOSED: #` footer +4. **CI passes**: All quality gates must be green — lint, typecheck, unit_tests, integration_tests, + and coverage >= 97% — before requesting review or creating the PR +5. **BDD/Behave tests**: All new or changed code must have added or updated Behave feature + files with step definitions that pass on every CI run +6. **Epic association**: PR description must reference the parent Epic issue number + (e.g. "Parent Epic: #") +7. **Labels applied**: Apply State/In Review, Priority/, MoSCoW/, Type/ + via forgejo-label-manager +8. **Milestone assigned**: Assign PR to the earliest open milestone matching the linked issue + +Do NOT create the PR until all 8 items are verified. +``` + +### CHANGELOG.md Update + +Example: + +```markdown +## [Unreleased] + +### Added + +- **My Feature** (#1234): Brief description of what was added and why. +``` + +```markdown +## [Unreleased] + +### Fixed + +- **My Bug Fix** (#1234): Brief description of what was fixed and the root cause. +``` + +### CONTRIBUTORS.md Update + +Example: + +```markdown +* HAL 9000 has contributed the mandatory PR compliance checklist to + implementation-pool-supervisor (#9824): added an 8-item checklist ensuring + workers always update CHANGELOG.md, CONTRIBUTORS.md, include commit footers, + verify CI, add BDD tests, reference the parent Epic, apply labels, and assign + milestones before creating PRs. +``` + +### Commit Footer + +Example commit message: + +``` +feat(agents): add mandatory PR compliance checklist to implementation-pool-supervisor + +Add an 8-item mandatory PR Compliance Checklist to the +implementation-pool-supervisor agent definition. Workers must complete +all 8 items before creating a PR: CHANGELOG.md update, CONTRIBUTORS.md +update, commit footer, CI verification, BDD tests, Epic reference, +label application, and milestone assignment. + +Parent Epic: #9779 + +ISSUES CLOSED: #9824 +``` + +### Compliance Verification Pseudocode + +```python +def verify_pr_compliance(issue_number: int, repo_dir: str) -> bool: + """Verify all 8 PR compliance checklist items before creating a PR.""" + import subprocess, os + + # Item 1: CHANGELOG.md has [Unreleased] entry + changelog = open(os.path.join(repo_dir, "CHANGELOG.md")).read() + assert "[Unreleased]" in changelog, "CHANGELOG.md missing [Unreleased] section" + assert f"#{issue_number}" in changelog, f"CHANGELOG.md missing entry for #{issue_number}" + + # Item 2: CONTRIBUTORS.md updated + contributors = open(os.path.join(repo_dir, "CONTRIBUTORS.md")).read() + assert "HAL 9000" in contributors, "CONTRIBUTORS.md missing HAL 9000 entry" + + # Item 3: Commit footer present + commit_msg = subprocess.check_output( + ["git", "-C", repo_dir, "log", "-1", "--format=%B"] + ).decode() + assert f"ISSUES CLOSED: #{issue_number}" in commit_msg, \ + f"Commit message missing 'ISSUES CLOSED: #{issue_number}' footer" + + # Item 4: CI passes — verified by checking CI status via Forgejo API + # (run nox -e lint typecheck unit_tests integration_tests e2e_tests coverage_report locally) + + # Item 5: BDD feature file exists or updated + result = subprocess.run( + ["grep", "-r", f"#{issue_number}", os.path.join(repo_dir, "features/")], + capture_output=True + ) + assert result.returncode == 0, f"No BDD feature file references #{issue_number}" + + # Item 6: Epic reference in PR description + # (verified when constructing PR body — must include "Parent Epic: #") + + # Item 7: Labels applied via forgejo-label-manager + # (State/In Review, Priority/, MoSCoW/, Type/) + + # Item 8: Milestone assigned to earliest open milestone + # (verified via Forgejo API after PR creation) + + return True +``` + +## Dispatching Workers + +When dispatching `implementation-worker` agents, always include the full **PR Compliance Checklist** section above verbatim in the worker prompt under a `briefing:` key. Workers must not create PRs without completing all 8 checklist items. + +## Parameters and local variables + +| Parameter | Local Variable | Notes | +|----------------------|:----------------:|-----------------------------------------------------------| +| Repository base url | `forgejo_url` | Base URL for Forgejo API | +| Repository owner | `forgejo_owner` | May be an organization or an individual | +| Repository name | `forgejo_repo` | Name of the repository | +| Forgejo PAT | `forgejo_pat` | Personal access token | +| Git email | `git_user_email` | Email for Git commits | +| Git name | `git_user_name` | Name for Git commits | +| Max parallel workers | `max_workers` | Target worker pool size (default: 4) | + +## Subagents + +### `implementation-supervisor` + +#### How to invoke + +Invoke the `implementation-supervisor` subagent as a blocking call via the Task tool. + +#### Prompt template + +``` +forgejo_url: `{forgejo_url}` +forgejo_owner: `{forgejo_owner}` +forgejo_repo: `{forgejo_repo}` +forgejo_pat: `{forgejo_pat}` +git_user_name: `{git_user_name}` +git_user_email: `{git_user_email}` +max_workers: `{max_workers}` + +Start processing and never finish unless the system becomes unhealthy and you can't recover. +``` + +## **CRITICAL** Rules + +- **Pass all credentials verbatim.** Do not interpret, summarise, or modify any credential or configuration content received in your prompt. +- **Never implement anything yourself.** Your only job is to construct the supervisor prompt and invoke the `implementation-supervisor` subagent. +- **Always include the PR Compliance Checklist** in every worker prompt. Workers must not create PRs without completing all 8 checklist items. +- **Never ask questions or give up.** Operate fully autonomously using best judgement. diff --git a/features/pr_compliance_pool_supervisor.feature b/features/pr_compliance_pool_supervisor.feature new file mode 100644 index 000000000..ddd622ac0 --- /dev/null +++ b/features/pr_compliance_pool_supervisor.feature @@ -0,0 +1,58 @@ +@mock_only +Feature: PR Compliance Checklist in Implementation Pool Supervisor + + As a pool supervisor + I want to pass a mandatory PR compliance checklist to every worker prompt + So that implementation workers complete all required items before creating a PR and avoid systemic merge blockers + + Background: + Given the implementation-pool-supervisor.md agent definition exists + + Scenario: Pool supervisor worker prompt includes the PR compliance checklist + When I read the pool supervisor agent definition + Then the worker prompt body includes the PR compliance checklist section + And the checklist is marked as MANDATORY + + Scenario: Checklist item 1 — CHANGELOG.md update required + When I read the pool supervisor agent definition + Then the worker prompt body includes a CHANGELOG.md checklist item + And the item instructs workers to add an entry under the Unreleased section + + Scenario: Checklist item 2 — CONTRIBUTORS.md update required + When I read the pool supervisor agent definition + Then the worker prompt body includes a CONTRIBUTORS.md checklist item + And the item instructs workers to add or update their contribution entry + + Scenario: Checklist item 3 — commit footer required + When I read the pool supervisor agent definition + Then the worker prompt body includes a commit footer checklist item + And the item specifies the ISSUES CLOSED footer format + + Scenario: Checklist item 4 — CI must pass before PR creation + When I read the pool supervisor agent definition + Then the worker prompt body includes a CI passes checklist item + And the item instructs workers to verify all quality gates are green + + Scenario: Checklist item 5 — BDD/Behave tests required + When I read the pool supervisor agent definition + Then the worker prompt body includes a BDD tests checklist item + And the item instructs workers to add or update Behave feature files + + Scenario: Checklist item 6 — Epic reference required in PR description + When I read the pool supervisor agent definition + Then the worker prompt body includes an Epic reference checklist item + And the item instructs workers to reference the parent Epic issue number + + Scenario: Checklist item 7 — Labels must be applied + When I read the pool supervisor agent definition + Then the worker prompt body includes a labels checklist item + And the item instructs workers to apply labels via forgejo-label-manager + + Scenario: Checklist item 8 — Milestone must be assigned + When I read the pool supervisor agent definition + Then the worker prompt body includes a milestone checklist item + And the item instructs workers to assign the earliest open milestone + + Scenario: All 8 checklist items are present in the worker prompt + When I read the pool supervisor agent definition + Then the worker prompt body contains all 8 mandatory checklist items diff --git a/features/steps/pr_compliance_pool_supervisor_steps.py b/features/steps/pr_compliance_pool_supervisor_steps.py new file mode 100644 index 000000000..d53eddf4c --- /dev/null +++ b/features/steps/pr_compliance_pool_supervisor_steps.py @@ -0,0 +1,185 @@ +"""Step definitions for PR compliance checklist in implementation pool supervisor.""" + +from pathlib import Path +from typing import Any + +from behave import given, then, when + +PROJECT_ROOT = Path(__file__).resolve().parents[3] +AGENT_DEF_PATH = PROJECT_ROOT / ".opencode" / "agents" / "implementation-pool-supervisor.md" + + +@given("the implementation-pool-supervisor.md agent definition exists") +def step_agent_def_exists(context: Any) -> None: + """Verify the pool supervisor agent definition file exists.""" + assert AGENT_DEF_PATH.exists(), f"Agent definition not found at {AGENT_DEF_PATH}" + context.agent_def_path = AGENT_DEF_PATH + + +@when("I read the pool supervisor agent definition") +def step_read_agent_def(context: Any) -> None: + """Read the pool supervisor agent definition.""" + context.agent_def_content = AGENT_DEF_PATH.read_text(encoding="utf-8") + + +@then("the worker prompt body includes the PR compliance checklist section") +def step_prompt_includes_checklist(context: Any) -> None: + """Verify the worker prompt body includes the PR compliance checklist.""" + assert "PR Compliance Checklist" in context.agent_def_content, ( + "Worker prompt body does not include 'PR Compliance Checklist'" + ) + + +@then("the checklist is marked as MANDATORY") +def step_checklist_is_mandatory(context: Any) -> None: + """Verify the checklist is marked as MANDATORY.""" + assert "MANDATORY" in context.agent_def_content, ( + "PR Compliance Checklist is not marked as MANDATORY" + ) + + +@then("the worker prompt body includes a CHANGELOG.md checklist item") +def step_prompt_includes_changelog_item(context: Any) -> None: + """Verify the worker prompt body includes a CHANGELOG.md checklist item.""" + assert "CHANGELOG.md" in context.agent_def_content, ( + "Worker prompt body does not include a CHANGELOG.md checklist item" + ) + + +@then("the item instructs workers to add an entry under the Unreleased section") +def step_changelog_item_unreleased(context: Any) -> None: + """Verify the CHANGELOG.md item mentions the Unreleased section.""" + assert "[Unreleased]" in context.agent_def_content, ( + "CHANGELOG.md checklist item does not mention the [Unreleased] section" + ) + + +@then("the worker prompt body includes a CONTRIBUTORS.md checklist item") +def step_prompt_includes_contributors_item(context: Any) -> None: + """Verify the worker prompt body includes a CONTRIBUTORS.md checklist item.""" + assert "CONTRIBUTORS.md" in context.agent_def_content, ( + "Worker prompt body does not include a CONTRIBUTORS.md checklist item" + ) + + +@then("the item instructs workers to add or update their contribution entry") +def step_contributors_item_add_update(context: Any) -> None: + """Verify the CONTRIBUTORS.md item instructs workers to add or update.""" + assert "add or update" in context.agent_def_content, ( + "CONTRIBUTORS.md checklist item does not instruct workers to add or update" + ) + + +@then("the worker prompt body includes a commit footer checklist item") +def step_prompt_includes_commit_footer_item(context: Any) -> None: + """Verify the worker prompt body includes a commit footer checklist item.""" + assert "Commit footer" in context.agent_def_content, ( + "Worker prompt body does not include a commit footer checklist item" + ) + + +@then("the item specifies the ISSUES CLOSED footer format") +def step_commit_footer_issues_closed(context: Any) -> None: + """Verify the commit footer item specifies the ISSUES CLOSED format.""" + assert "ISSUES CLOSED" in context.agent_def_content, ( + "Commit footer checklist item does not specify the ISSUES CLOSED format" + ) + + +@then("the worker prompt body includes a CI passes checklist item") +def step_prompt_includes_ci_item(context: Any) -> None: + """Verify the worker prompt body includes a CI passes checklist item.""" + assert "CI passes" in context.agent_def_content, ( + "Worker prompt body does not include a CI passes checklist item" + ) + + +@then("the item instructs workers to verify all quality gates are green") +def step_ci_item_quality_gates(context: Any) -> None: + """Verify the CI item instructs workers to verify quality gates.""" + assert "quality gates" in context.agent_def_content, ( + "CI checklist item does not mention quality gates" + ) + + +@then("the worker prompt body includes a BDD tests checklist item") +def step_prompt_includes_bdd_item(context: Any) -> None: + """Verify the worker prompt body includes a BDD/Behave tests checklist item.""" + assert "BDD/Behave tests" in context.agent_def_content, ( + "Worker prompt body does not include a BDD/Behave tests checklist item" + ) + + +@then("the item instructs workers to add or update Behave feature files") +def step_bdd_item_feature_files(context: Any) -> None: + """Verify the BDD item instructs workers to add or update feature files.""" + assert "added or updated" in context.agent_def_content, ( + "BDD checklist item does not instruct workers to add or update feature files" + ) + + +@then("the worker prompt body includes an Epic reference checklist item") +def step_prompt_includes_epic_item(context: Any) -> None: + """Verify the worker prompt body includes an Epic reference checklist item.""" + assert "Epic reference" in context.agent_def_content, ( + "Worker prompt body does not include an Epic reference checklist item" + ) + + +@then("the item instructs workers to reference the parent Epic issue number") +def step_epic_item_parent_reference(context: Any) -> None: + """Verify the Epic item instructs workers to reference the parent Epic.""" + assert "parent Epic" in context.agent_def_content, ( + "Epic checklist item does not instruct workers to reference the parent Epic" + ) + + +@then("the worker prompt body includes a labels checklist item") +def step_prompt_includes_labels_item(context: Any) -> None: + """Verify the worker prompt body includes a labels checklist item.""" + assert "Labels" in context.agent_def_content, ( + "Worker prompt body does not include a labels checklist item" + ) + + +@then("the item instructs workers to apply labels via forgejo-label-manager") +def step_labels_item_forgejo_label_manager(context: Any) -> None: + """Verify the labels item instructs workers to use forgejo-label-manager.""" + assert "forgejo-label-manager" in context.agent_def_content, ( + "Labels checklist item does not mention forgejo-label-manager" + ) + + +@then("the worker prompt body includes a milestone checklist item") +def step_prompt_includes_milestone_item(context: Any) -> None: + """Verify the worker prompt body includes a milestone checklist item.""" + assert "Milestone" in context.agent_def_content, ( + "Worker prompt body does not include a milestone checklist item" + ) + + +@then("the item instructs workers to assign the earliest open milestone") +def step_milestone_item_earliest(context: Any) -> None: + """Verify the milestone item instructs workers to assign the earliest open milestone.""" + assert "earliest open milestone" in context.agent_def_content, ( + "Milestone checklist item does not mention the earliest open milestone" + ) + + +@then("the worker prompt body contains all 8 mandatory checklist items") +def step_prompt_contains_all_8_items(context: Any) -> None: + """Verify the worker prompt body contains all 8 mandatory checklist items.""" + required_items = [ + "CHANGELOG.md", + "CONTRIBUTORS.md", + "ISSUES CLOSED", + "CI passes", + "BDD/Behave tests", + "Epic reference", + "forgejo-label-manager", + "earliest open milestone", + ] + missing = [item for item in required_items if item not in context.agent_def_content] + assert not missing, ( + f"Worker prompt body is missing the following checklist items: {missing}" + )