Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
14 changes: 14 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,3 +41,17 @@ Repository skills are stored in `.agents/skills/` using the portable Agent Skill
- `new-dmn-check`: create a reusable check DMN and its Bruno tests.

Claude compatibility is provided through the `.claude/skills` symlink to `.agents/skills`.

## Agent skills

### Issue tracker

Track issues and specs in GitHub Issues. Read `docs/agents/issue-tracker.md` before tracker operations.

### Triage labels

Use the five default triage labels. Read `docs/agents/triage-labels.md` when assigning triage roles.

### Domain docs

Use a single-context layout. Read `docs/agents/domain.md` before exploring domain concepts or architectural decisions.
20 changes: 20 additions & 0 deletions docs/agents/domain.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Domain docs

## Layout and reading rules

Use one root `GLOSSARY.md` and `docs/adr/` for repository-wide decisions.
Before exploring, read the glossary and ADRs relevant to the work.

If these files are absent, proceed silently. The domain-modeling skill
creates them as terms and decisions are resolved.

## Vocabulary

Use the glossary's terms in issues, proposals, hypotheses, and tests.
If a concept is missing, reconsider the terminology or note the gap
for domain-modeling.

## Decisions

Surface conflicts with existing ADRs explicitly, identifying the ADR
and explaining why the decision may need reconsideration.
35 changes: 35 additions & 0 deletions docs/agents/issue-tracker.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Issue tracker: GitHub

Issues and specs live in CodeForPhilly/benefit-decision-toolkit.
Use the `gh` CLI from this checkout.

## Operations

- Read: `gh issue view <number> --json number,title,body,labels,comments`.
- List: `gh issue list --state open`, with relevant label filters.
- Create: `gh issue create --title "..." --body-file <file>`.
- Comment: `gh issue comment <number> --body-file <file>`.
- Label: `gh issue edit <number> --add-label "..."` or `--remove-label "..."`.
- Close: post the explanation as a comment, then run `gh issue close <number>`.

Use files with actual newlines for multiline bodies and comments.

Before the first issue creation in a session, verify the target with
`gh repo view --json nameWithOwner`. The expected repository is
`CodeForPhilly/benefit-decision-toolkit`; resolve any mismatch before writing.

## Relationships

Use native GitHub sub-issues and issue dependencies when supported.
Otherwise, put `Part of #<parent>` and `Blocked by: #<number>` at the top
of the child issue body and link children in the parent's task list.
A ticket is unblocked when every blocker is closed.

## Pull requests as a triage surface

**PRs as a request surface: no.**

## Skill terminology

“Publish to the issue tracker” means create a GitHub issue.
“Fetch the relevant ticket” means read the GitHub issue.
11 changes: 11 additions & 0 deletions docs/agents/triage-labels.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Triage labels

| Canonical role | Tracker label | Meaning |
| --- | --- | --- |
| needs-triage | needs-triage | Maintainer needs to evaluate |
| needs-info | needs-info | Waiting on reporter information |
| ready-for-agent | ready-for-agent | Fully specified for agent implementation |
| ready-for-human | ready-for-human | Requires human implementation |
| wontfix | wontfix | Will not be actioned |

When a skill names a triage role, apply the corresponding tracker label.
Loading