Skip to content

Configure agent skills: issue tracker, triage labels, domain docs - #7

Merged
lesnik512 merged 2 commits into
mainfrom
chore/agent-skills-config
Aug 23, 2026
Merged

Configure agent skills: issue tracker, triage labels, domain docs#7
lesnik512 merged 2 commits into
mainfrom
chore/agent-skills-config

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Why

The engineering skills in ~/.claude/skills (/to-tickets, /triage,
/to-spec, /code-review, /domain-modeling, /diagnosing-bugs) all assume
per-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 skills section in
CLAUDE.md that names them. The skills read the section; the section names the
files; the files carry the detail. Nothing hard-codes a path, so any of the
three can move later by editing one line.

  • Issue tracker: local markdown under .scratch/<feature-slug>/, gitignored
    alongside .superpowers/. This repo has a GitHub remote, so GitHub Issues was
    the 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-tickets output cannot be referenced as #N from a PR body.
  • Triage labels: the five canonical roles unchanged (needs-triage,
    needs-info, ready-for-agent, ready-for-human, wontfix), recorded as a
    Status: line in each issue file rather than as tracker labels.
  • Domain docs: single-context, the stock consumer rules. This currently
    points at a CONTEXT.md and a docs/adr/ that do not exist yet; both arrive
    in the two follow-up PRs that convert planning/decisions/ to native ADRs and
    extract the glossary. The consumer rules say to proceed silently when the
    files are absent, so the intermediate state is the documented one.

Non-goals

  • Does not convert planning/decisions/ to docs/adr/. That is the next
    PR, and it is what makes docs/agents/domain.md accurate.
  • Does not extract CLAUDE.md's Vocabulary section to CONTEXT.md. PR
    after that one.
  • Does not create any .scratch/ content. The directory appears the first
    time a skill writes an issue.
  • Does not change the PRs as a request surface posture. The local-markdown
    tracker 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 lint passes (ruff format: 98 files unchanged; ruff check: all
    checks passed; ty check: all checks passed).
  • just check-planning passes (planning: OK).
  • just check-links passes (links: OK) — this is the gate that matters here,
    since the change is four files of cross-references.
  • just test and just test-migrations were not run: this diff contains no
    Python and no Markdown that either reads.

@lesnik512
lesnik512 merged commit be08655 into main Aug 23, 2026
3 checks passed
@lesnik512
lesnik512 deleted the chore/agent-skills-config branch August 23, 2026 10:34
@lesnik512
lesnik512 restored the chore/agent-skills-config branch August 23, 2026 10:42
@lesnik512
lesnik512 deleted the chore/agent-skills-config branch August 23, 2026 10:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant