Skip to content

Commit f727f22

Browse files
tippmar-nrtippmar-nr
committed
chore: add agent-skills config for engineering skills
Scaffold docs/agents/ (issue-tracker, triage-labels, domain) and a CLAUDE.md Agent skills section so the engineering skills read this repo's Jira (NR) issue tracker, triage-label vocabulary, and single-context domain-doc layout.
1 parent f16c288 commit f727f22

4 files changed

Lines changed: 164 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -234,3 +234,21 @@ only when no suitable overload exists *and* the call is not on a hot path.
234234
- Compact namespaces: `namespace NewRelic::Profiler::Logger { ... }`.
235235
- `.clang-format` at the profiler solution root is authoritative.
236236

237+
## Agent skills
238+
239+
### Issue tracker
240+
241+
Issues are tracked in Jira (New Relic, project `NR`) via the Atlassian MCP;
242+
the GitHub repo is a public code/PR mirror. External PRs are not a triage
243+
surface. See `docs/agents/issue-tracker.md`.
244+
245+
### Triage labels
246+
247+
Canonical role strings used as-is as Jira labels. See
248+
`docs/agents/triage-labels.md`.
249+
250+
### Domain docs
251+
252+
Single-context: one `CONTEXT.md` + `docs/adr/` at the repo root. See
253+
`docs/agents/domain.md`.
254+

‎docs/agents/domain.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Domain Docs
2+
3+
How the engineering skills should consume this repo's domain documentation when
4+
exploring the codebase. This repo is **single-context**.
5+
6+
## Before exploring, read these
7+
8+
- **`CONTEXT.md`** at the repo root.
9+
- **`docs/adr/`** -- read ADRs that touch the area you're about to work in.
10+
11+
If any of these files don't exist, **proceed silently**. Don't flag their
12+
absence; don't suggest creating them upfront. The `/domain-modeling` skill
13+
(reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates
14+
them lazily when terms or decisions actually get resolved.
15+
16+
## File structure
17+
18+
Single-context repo (this repo):
19+
20+
```
21+
/
22+
CONTEXT.md
23+
docs/adr/
24+
0001-some-decision.md
25+
0002-another-decision.md
26+
src/
27+
```
28+
29+
(A multi-context repo would instead have a `CONTEXT-MAP.md` at the root pointing
30+
at one `CONTEXT.md` per context, plus context-scoped `src/<context>/docs/adr/`.
31+
That layout does not apply here.)
32+
33+
## Use the glossary's vocabulary
34+
35+
When your output names a domain concept (in an issue title, a refactor proposal,
36+
a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift
37+
to synonyms the glossary explicitly avoids.
38+
39+
If the concept you need isn't in the glossary yet, that's a signal -- either
40+
you're inventing language the project doesn't use (reconsider) or there's a real
41+
gap (note it for `/domain-modeling`).
42+
43+
## Flag ADR conflicts
44+
45+
If your output contradicts an existing ADR, surface it explicitly rather than
46+
silently overriding:
47+
48+
> _Contradicts ADR-0007 -- but worth reopening because..._

‎docs/agents/issue-tracker.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Issue tracker: Jira
2+
3+
Issues and PRDs for this repo live in Jira, not GitHub Issues. The GitHub repo
4+
(`newrelic/newrelic-dotnet-agent`) is a public mirror for code and pull
5+
requests; planning and triage happen in Jira.
6+
7+
- **Site**: new-relic.atlassian.net
8+
- **Project key**: `NR`
9+
- **Access**: the Atlassian MCP tools (`mcp__plugin_nr_atlassian-jira__*`). The
10+
site host `new-relic.atlassian.net` works directly as the `cloudId` argument
11+
for those tools.
12+
13+
## Write formatting (mandatory)
14+
15+
Every Jira write -- create, edit, comment -- must use `contentFormat: "adf"`
16+
with a proper ADF (Atlassian Document Format) JSON body, even for plain text.
17+
Follow the `nr:jira-adf-format` skill. Passing raw markdown/plain strings is
18+
the most common mistake.
19+
20+
## Conventions
21+
22+
- **Create an issue**: `createJiraIssue` with `projectKey: NR`, an
23+
`issueTypeName` (`Task`, `Bug`, `Story`), a `summary`, and a `description`.
24+
New issues are assigned to the "APM+ -> .NET Agent" team (team field ID
25+
`ea229518-a006-4d09-b8c0-223a885aeff7-188`) via `additional_fields` unless
26+
told otherwise.
27+
- **Read an issue**: `getJiraIssue` with the issue key (e.g. `NR-574460`).
28+
Include `comment` in `fields` (or fetch `*all`) to get comments.
29+
- **List / search issues**: `searchJiraIssuesUsingJql`, e.g.
30+
`project = NR AND labels = "needs-triage" ORDER BY created DESC`.
31+
- **Comment on an issue**: `addCommentToJiraIssue`.
32+
- **Apply / remove labels**: `editJiraIssue`, setting the `labels` field (see
33+
`triage-labels.md` for the role strings).
34+
- **Transition state**: `getTransitionsForJiraIssue` to find the transition ID,
35+
then `transitionJiraIssue`.
36+
- **Link issues**: `createIssueLink` (`getIssueLinkTypes` lists types; for
37+
"A is blocked by B", inwardIssue = B, outwardIssue = A).
38+
39+
## Referencing tickets in git
40+
41+
Never link to Jira in commits or PR descriptions -- this is a public
42+
open-source repo and Jira is internal. Reference by ticket ID only, inline in
43+
prose (e.g. "from NR-574460"), never as a `Resolves` keyword.
44+
45+
## When a skill says "publish to the issue tracker"
46+
47+
Create a Jira issue in project `NR`.
48+
49+
## When a skill says "fetch the relevant ticket"
50+
51+
Read the Jira issue by key with `getJiraIssue`. The user will normally pass the
52+
key (e.g. `NR-574460`) directly.
53+
54+
## Pull requests as a triage surface
55+
56+
**No.** External GitHub PRs are not pulled into the triage queue.
57+
58+
## Wayfinding operations
59+
60+
Used by `/wayfinder`. The **map** is a single Jira issue with **child** issues
61+
as tickets.
62+
63+
- **Map**: a Jira issue (type `Task`/`Story`) holding the Notes /
64+
Decisions-so-far / Fog body; label it `wayfinder:map`.
65+
- **Child ticket**: a Jira issue linked to the map (a sub-task under the map,
66+
or a `Relates` link plus `Part of NR-<map>` in the body). Label
67+
`wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed,
68+
assign to the driving dev.
69+
- **Blocking**: use Jira issue links -- "is blocked by" (`createIssueLink` with
70+
type `Blocks`: inwardIssue = blocker, outwardIssue = blocked). A ticket is
71+
unblocked when every blocker is Done/closed.
72+
- **Frontier query**: JQL for the map's open children with no open blocker and
73+
no assignee; first in map order wins.
74+
- **Claim**: assign the issue to the driving dev -- the session's first write.
75+
- **Resolve**: comment the answer, transition the issue to Done, then append a
76+
context pointer (gist + link) to the map's Decisions-so-far.

‎docs/agents/triage-labels.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Triage Labels
2+
3+
The skills speak in terms of five canonical triage roles. This file maps those
4+
roles to the actual label strings used in this repo's issue tracker. For this
5+
repo they are applied as **Jira labels** in project `NR` (see
6+
`issue-tracker.md`).
7+
8+
| Role (in the skills) | Label in our tracker | Meaning |
9+
| -------------------- | -------------------- | ---------------------------------------- |
10+
| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue |
11+
| `needs-info` | `needs-info` | Waiting on reporter for more information |
12+
| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent |
13+
| `ready-for-human` | `ready-for-human` | Requires human implementation |
14+
| `wontfix` | `wontfix` | Will not be actioned |
15+
16+
When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the
17+
corresponding label string from this table. Set the labels via `editJiraIssue`
18+
on the `labels` field.
19+
20+
Edit the right-hand column to match whatever vocabulary you actually use. If you
21+
prefer to drive triage through Jira workflow statuses instead of labels, record
22+
the status names here and treat "apply label X" as "transition to status Y".

0 commit comments

Comments
 (0)