Configure agent skills: issue tracker, triage labels, domain docs - #7
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The engineering skills in
~/.claude/skills(/to-tickets,/triage,/to-spec,/code-review,/domain-modeling,/diagnosing-bugs) all assumeper-repo configuration that this repo never had: where issues live, what the
triage label vocabulary is, and where domain docs sit. Without it each skill
either guesses or stops and asks, and two of them guess differently.
Design
Three pointer files under
docs/agents/, and one## Agent skillssection inCLAUDE.mdthat names them. The skills read the section; the section names thefiles; the files carry the detail. Nothing hard-codes a path, so any of the
three can move later by editing one line.
.scratch/<feature-slug>/, gitignoredalongside
.superpowers/. This repo has a GitHub remote, so GitHub Issues wasthe obvious choice and was rejected: issues here are working notes for a
reference application with one maintainer, not a queue other people read. The
cost is that
/to-ticketsoutput cannot be referenced as#Nfrom a PR body.needs-triage,needs-info,ready-for-agent,ready-for-human,wontfix), recorded as aStatus:line in each issue file rather than as tracker labels.points at a
CONTEXT.mdand adocs/adr/that do not exist yet; both arrivein the two follow-up PRs that convert
planning/decisions/to native ADRs andextract the glossary. The consumer rules say to proceed silently when the
files are absent, so the intermediate state is the documented one.
Non-goals
planning/decisions/todocs/adr/. That is the nextPR, and it is what makes
docs/agents/domain.mdaccurate.CLAUDE.md's Vocabulary section toCONTEXT.md. PRafter that one.
.scratch/content. The directory appears the firsttime a skill writes an issue.
PRs as a request surfaceposture. The local-markdowntracker has no such concept; if this repo later moves to GitHub Issues the
flag defaults off.
Verification
Docs and configuration only: no application code, no migration, no test is
touched by this diff.
just lintpasses (ruff format: 98 files unchanged;ruff check: allchecks passed;
ty check: all checks passed).just check-planningpasses (planning: OK).just check-linkspasses (links: OK) — this is the gate that matters here,since the change is four files of cross-references.
just testandjust test-migrationswere not run: this diff contains noPython and no Markdown that either reads.