docs(agents): require tracked work and defect evidence - #2603
docs(agents): require tracked work and defect evidence#2603bojtospeter wants to merge 8 commits into
Conversation
Related to #1879 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Peter Bojtos <peter.bojtos@camunda.com>
There was a problem hiding this comment.
🟡 Changes recommended
A few newly added instructions/templates are internally inconsistent about “issue vs PR” tracking and the use of Closes #N semantics, which should be clarified to avoid process confusion.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR updates repository process documentation and GitHub templates to require tracked/claimed work and to capture defect-class + red/green evidence for bug fixes, strengthening coordination and reviewability for changes across the migration-tooling repo.
Changes:
- Adds a “Work tracking and change evidence” policy section to
AGENTS.md, including a claim/in-progress workflow and examplegh/API checks. - Extends the PR template with required work-tracking fields and a defect-evidence section for bug fixes.
- Extends issue templates (task / feature / bug) with work-tracking fields and, for bugs, defect classification + reproducer evidence prompts.
File summaries
| File | Description |
|---|---|
| AGENTS.md | Introduces tracked-work and defect-evidence policy, including suggested CLI/API validation steps. |
| .github/pull_request_template.md | Adds required work-tracking section and defect evidence section for bug fixes. |
| .github/ISSUE_TEMPLATE/task.md | Adds work-tracking fields to task issues before implementation. |
| .github/ISSUE_TEMPLATE/feature_request.md | Adds work-tracking fields to feature requests before implementation. |
| .github/ISSUE_TEMPLATE/bug_report.md | Adds work-tracking fields plus defect classification/reproducer evidence prompts. |
Review details
Suppressed comments (1)
AGENTS.md:48
- The workflow bullets refer specifically to a “tracking issue”, but the section above allows a pull request as the tracking item. Rewording to “tracking item (issue/PR)” here would keep the instructions consistent with the stated policy.
1. Assign the tracking issue to yourself and comment with the branch or PR that
will carry the work.
2. Add the issue to the repository's GitHub project (project `182`, owned by
`camunda`) if it is not already present.
3. Set the project's `Status` field to `In Progress`.
- Files reviewed: 5/5 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Clarify issue-only closing semantics and use tracking-item wording consistently. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Peter Bojtos <peter.bojtos@camunda.com>
There was a problem hiding this comment.
🔵 Needs a closer look
The new issue-template links to the work-tracking section use ../../AGENTS.md..., which is likely to resolve incorrectly when rendered into issue bodies and should be changed to a repo-root path (e.g., AGENTS.md#...).
Review details
Suppressed comments (3)
Previously missed (3) — in code that hasn't changed since the last review.
.github/ISSUE_TEMPLATE/bug_report.md:30
- The relative link uses
../../AGENTS.md..., which is likely to resolve incorrectly when this template is rendered into an issue body (it can traverse above the repo root). Use a repo-root path instead (e.g.,AGENTS.md#...).
.github/ISSUE_TEMPLATE/feature_request.md:26 - The relative link uses
../../AGENTS.md..., which is likely to resolve incorrectly when this template is rendered into an issue body (it can traverse above the repo root). Use a repo-root path instead (e.g.,AGENTS.md#...).
.github/ISSUE_TEMPLATE/task.md:20 - The relative link uses
../../AGENTS.md..., which is likely to resolve incorrectly when this template is rendered into an issue body (it can traverse above the repo root). Use a repo-root path instead (e.g.,AGENTS.md#...).
- Files reviewed: 5/5 changed files
- Comments generated: 0 new
- Review effort level: Lite
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Peter Bojtos <peter.bojtos@camunda.com>
There was a problem hiding this comment.
🔵 Needs a closer look
A couple of newly added process requirements are still underspecified/ambiguous in the docs/templates and should be clarified to avoid misinterpretation.
Review details
Suppressed comments (2)
Previously missed (2) — in code that hasn't changed since the last review.
.github/pull_request_template.md:10
- “Project status: In Progress” is currently underspecified (it doesn’t say which project board the status refers to). Since AGENTS.md ties this workflow to project 182, it would help to reference that here as well to avoid confusion when multiple projects exist.
AGENTS.md:40 - The phrase “Keep the link in the branch/PR description” is ambiguous because branches don’t have a standard description field on GitHub; this could confuse contributors about where the tracking link must live. Consider explicitly calling out the PR description (and optionally the branch name) as the expected locations.
- Files reviewed: 5/5 changed files
- Comments generated: 0 new
- Review effort level: Lite
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Peter Bojtos <peter.bojtos@camunda.com>
There was a problem hiding this comment.
🔵 Needs a closer look
The new “work-tracking workflow” links in the issue templates are currently relative to .github/ISSUE_TEMPLATE/ and won’t reliably resolve to the repo-root AGENTS.md.
Review details
Suppressed comments (3)
Previously missed (3) — in code that hasn't changed since the last review.
.github/ISSUE_TEMPLATE/bug_report.md:30
- The link to AGENTS.md is relative to
.github/ISSUE_TEMPLATE/and will resolve to a non-existent.github/ISSUE_TEMPLATE/AGENTS.mdwhen viewing the template file, and may 404 when used in an issue. Use a repo-root relative path instead.
.github/ISSUE_TEMPLATE/feature_request.md:26 - The link to AGENTS.md is relative to
.github/ISSUE_TEMPLATE/and will resolve to.github/ISSUE_TEMPLATE/AGENTS.mdinstead of the repo-root AGENTS.md. Use a repo-root relative path so the link works from the template file and from created issues.
.github/ISSUE_TEMPLATE/task.md:20 - The link to AGENTS.md is relative to
.github/ISSUE_TEMPLATE/and will resolve to.github/ISSUE_TEMPLATE/AGENTS.mdinstead of the repo-root AGENTS.md. Use a repo-root relative path so the link reliably resolves.
- Files reviewed: 5/5 changed files
- Comments generated: 0 new
- Review effort level: Lite
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Peter Bojtos <peter.bojtos@camunda.com>
Signed-off-by: Peter Bojtos <peter.bojtos@camunda.com>
There was a problem hiding this comment.
🔵 Needs a closer look
A couple of documentation/template correctness and consistency issues (missing jq prerequisite mention and inconsistent “category surface” wording) should be addressed to avoid confusing contributors.
Review details
Suppressed comments (2)
Previously missed (2) — in code that hasn't changed since the last review.
.github/ISSUE_TEMPLATE/bug_report.md:36
- The bug template uses “Affected category surface”, while AGENTS.md and the PR template use “Category surface covered”. Aligning the wording across templates makes it clearer what reporters and implementers should provide.
AGENTS.md:83 - The machine-checkable guard snippet relies on an external
jqbinary, but the section doesn’t mention that prerequisite. Without it, the command fails even ifghis installed/authenticated.
- Files reviewed: 5/5 changed files
- Comments generated: 0 new
- Review effort level: Lite
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Peter Bojtos <peter.bojtos@camunda.com>
There was a problem hiding this comment.
🟢 Approval recommended
The changes consistently implement the stated process requirements across AGENTS guidance and the PR/issue templates without introducing behavioral or build-impacting code changes.
Review details
- Files reviewed: 5/5 changed files
- Comments generated: 0 new
- Review effort level: Lite
There was a problem hiding this comment.
🟡 Changes recommended
The documented jq “machine-checkable guard” in AGENTS.md appears to query a non-existent projectItems[].status.name field, which likely makes the validation snippet incorrect as written.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
- Files reviewed: 5/5 changed files
- Comments generated: 1
- Review effort level: Lite
| printf '%s\n' "$ISSUE_STATE" | jq -e \ | ||
| --arg actor "$ACTOR" \ | ||
| 'any(.assignees[]; .login == $actor) and | ||
| any(.projectItems[]; .status.name == "In Progress")' >/dev/null | ||
| ``` |
Summary
In Progressworkflow for implementation work inAGENTS.md.Changes
AGENTS.md: require an issue or PR before editing, self-assignment, project status, documented exceptions, defect taxonomy, and deterministic red/green evidence..github/ISSUE_TEMPLATE/*: capture ownership, project status, defect class, and reproducer evidence..github/pull_request_template.md: require tracking links, owner/status confirmation, and bug evidence.Work tracking
In Progress.Defect evidence
N/A - this is a documentation and repository-process change, not a product bug fix.
Test plan
mvn clean install -DskipTestswith Java 21git diff --checkBaseline
Built from commit
ae44a0e16a8c3457bcf699748cfdd39882184800.Closes #1879