Skip to content

docs: sync shared issue-management block to v2 #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rabestro merged 2 commits into from
Aug 23, 2026
Merged

docs: sync shared issue-management block to v2 #4

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a228980
docs: sync shared issue-management block to v2
rabestro Aug 23, 2026
061736c
docs: sync shared issue-management block to v3
rabestro Aug 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 16 additions & 9 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,29 +12,36 @@
- **Start**: `python3 bot.py` (mints anonymous token and challenges sparring bot).

## Issue management
<!-- dc-shared:issue-management v1 — keep identical across Fortemate repositories -->
<!-- dc-shared:issue-management v3 — keep identical across Fortemate repositories -->

- Use the native GitHub Issue Type as the canonical work classification:
- `Bug` for unexpected or incorrect behavior.
- `Feature` for a request, idea, or new user-visible capability.
- `Task` for a specific piece of engineering, research, maintenance, or documentation work.
- Never commit directly to a repository's default branch. Name branches `<type>/<short-description>` or `<type>/<id>-<short-description>` using the canonical types `task|feat|bug|refactor|chore|docs|ci|test|perf`. Include an Issue id only when the pull request is intended to fully complete that Issue; otherwise omit it or use the id of an independently actionable sub-issue. Example: `bug/42-fix-dfen-parser`.
- Do not apply `bug` or `enhancement` labels to Issues merely to repeat their Type. Keep those labels for pull-request release classification. On Issues, labels describe only a technical domain or cross-cutting concern, and only existing repository labels may be used.
- Before creating or updating an Issue, search relevant Fortemate repositories across open and closed Issues for semantic duplicates. Read the live Types, field options, labels, assignees, relationships, and open milestones before mutation; never rely on cached IDs or invent metadata.
- **Never apply or remove the `jules` label.** It is a human-only execution trigger that immediately dispatches an autonomous agent; it is not classification metadata. Humans apply it only to a reviewed `Ready` Issue and remove it when its pull request merges or the Issue is closed or reopened.
- Before creating or updating an Issue, search relevant Fortemate repositories across open and closed Issues for semantic duplicates. Read the live Types, field options, labels, assignees, and relationships before mutation; never rely on cached IDs or invent metadata.
- GitHub-facing work items are English-only. Use the appropriate Issue Form when available, or `gh issue create --body-file <file>` for CLI creation; never pass a multiline body inline. Every Issue must contain `Context`, `Objective`, and a testable `Definition of Done`.
- Add every actionable Issue and pull request to the organization Project [Fortemate Engineering](https://github.com/orgs/fortemate/projects/1).
- Add every actionable Issue (never pull requests) to the organization Project [Fortemate Engineering](https://github.com/orgs/fortemate/projects/1).
- Use Project `Status` only for workflow state:
- `Backlog` means triaged but not committed for active work.
- `Ready` means sufficiently defined and available to start.
- `In progress` means someone is actively working on it.
- `In review` means implementation is waiting for review or validation.
- `Done` means the Issue is closed or the pull request is merged.
- Set the organization `Priority` Issue field by impact and urgency: `Urgent` for an immediate incident, security problem, or release blocker; `High` for important or blocking planned work; `Medium` for normal planned work; and `Low` for opportunistic backlog.
- Set the organization `Effort` Issue field to `Low`, `Medium`, or `High` as a relative implementation-and-verification estimate, not as priority or a time promise. Never replace either organization field with labels or duplicate Project fields; leave a value unset when current evidence does not justify it.
- Triage establishes Type, Priority, Effort, applicable labels, Project membership, Status, milestone, and relationships. Assign an Issue only when a person owns its next action, and assign the active owner before moving it to `In progress`; unassigned means no current owner, not low priority.
- Use parent/sub-issue relationships for independently actionable decomposition, `Blocking`/`Blocked by` for hard ordering dependencies, and `Relates to` for non-blocking associations. If the live UI or API cannot create a relation, add an explicit `Related: owner/repository#<id>` cross-reference. Do not simulate relationships with title prefixes, labels, or duplicate task lists.
- `Done` means the Issue is closed.
- Set the Project `Execution tier` during triage:
- `Routine` for a bounded, reversible task suitable for Jules or another low-cost agent.
- `Mid` for a well-scoped task that needs a stronger coding agent with iterative supervision.
- `Frontier` for architecture, public contracts, complex diagnosis, or other high-blast-radius work; human-led.
- `Human-only` for releases, production operations, secrets, or legal decisions that must never be delegated.
- `Decompose` for work too large to route as-is: split it into sub-issues, tier each, then re-tier or close the parent.
- A blank value means the Issue has not been routed yet.
- Leave the organization `Priority` Issue field blank for normal work. Set it only to deliberately jump the queue: `Urgent` for an immediate incident, security problem, or release blocker; `High` for important or blocking planned work. Never replace organization fields with labels or duplicate Project fields.
- Triage establishes Type, Execution tier, applicable labels, Project membership, Status, and relationships (plus Priority only for queue-jumpers). Assign an Issue only when a person owns its next action, and assign the active owner before moving it to `In progress`; unassigned means agent pool or no current owner, not low priority.
- Use parent/sub-issue relationships for independently actionable decomposition, `Blocking`/`Blocked by` for hard ordering dependencies, and `Relates to` for non-blocking associations. If the live UI or API cannot create a relation, add an explicit typed cross-reference that preserves its semantics: `Parent:`, `Sub-issue:`, `Blocking:`, `Blocked by:`, or `Related:` followed by `owner/repository#<id>`. Do not simulate relationships with title prefixes, labels, or duplicate task lists.
- When a pull request targets the repository's default branch and fully completes an Issue, link it with `Closes #<id>` or `Closes owner/repository#<id>`. Use a non-closing reference for partial work or for a pull request targeting any other branch.
- After every Issue, pull-request, or Project mutation, read the item back. For an Issue, verify Type, Issue fields, labels, assignee, milestone, relationships, Project membership, and Status. For a pull request, verify base/head branches, draft and merge state, labels, assignees/reviewers, milestone, linked Issues, Project membership, and Status; Issue Type and Issue fields do not apply. Report any metadata that the available API or UI could not set.
- After every Issue, pull-request, or Project mutation, read the item back. For an Issue, verify Type, Issue fields, labels, assignee, relationships, Project membership, and Status. For a pull request, verify base/head branches, draft and merge state, labels, assignees/reviewers, and linked Issues; pull requests are never Project items, and Issue Type and Issue fields do not apply. Report any metadata that the available API or UI could not set.
- The human owner reviews, approves, and merges pull requests. Agents never merge pull requests or execute releases.

<!-- /dc-shared:issue-management -->
Loading