Issue management: gh-issue skill (review + write) and issue templates

[dilberryhoundog]

Cropped up during the DraftHorse spec-upgrade discussions (branch drafthorse-spec-upgrade, see dev/workspace/plans/): nearly all work is funneled through GitHub issues, and the Dynamic Improvement convention (agents upload issues from live skill usage; a repair agent integrates fixes) needs an issue pipeline to land on. Two parts.

1. Issue skill

One skill covering issue reviewing and issue writing, in the agent-tools plugin.

• Routing via an Agent decision slot keyed on user input: an issue number routes to review; an issue statement (prose describing a problem/task) routes to write.
• Reviewer path: skill → agent → reviewer subagent.
• Writer path: skill → agent.
• Uses the GitHub MCP for all issue operations.
• Authored as a DraftHorse document — post-spec-upgrade conventions apply (machinery headings, parent/child vocabulary, harness-format stamp, condition-list notation).

2. Issue templates

• Error reporting template — the Dynamic Improvement hook: what a skill-running agent files when it hits trouble (skill name, step, the condition or passage that misbehaved, what actually happened). Agents reveal troubles, not propose solutions; the format keeps reports repair-agent-ready.
• Issue writer template — the shape the issue-writing path produces for general work items.

Context

• Dynamic Improvement convention: docs/drafthorse/framework/conventions.md.
• Error-step disposition catalogue ("suggest an issue to inform the skill repair agent") lands via dev/workspace/plans/plan-half-applied-dispositions.md — the error reporting template is what that disposition points at.
• Child-skill / sub-agent patterns for the reviewer path: git-box skill is the reference implementation.

[dilberryhoundog]

Auth avenue: plugin userConfig PAT → GitHub MCP server config

Surfaced while decoding the DraftHorse "config wiring" bullet (dev/workspace/plans/plan-config-wiring.md). The blocker on shipping an issue-opener in a plugin has been that issue creation needs GitHub auth, and a plugin can't assume the installing user has gh installed and authenticated. Plugin userConfig looks like a clean answer.

The mechanism

plugin.json declares userConfig values that Claude Code prompts for when the plugin is enabled. Marking one "sensitive": true masks the input and stores it in the system keychain (or ~/.claude/.credentials.json where no keychain exists) rather than settings.json.

The substitution rule (docs/claude_docs/plugin_reference.md:561):

Each value is available for substitution as ${user_config.KEY} in MCP and LSP server configs, hook commands, and monitor commands. Non-sensitive values can also be substituted in skill and agent content.

So the PAT reaches an MCP server config, which is exactly where it's needed. Sketch:

{
  "userConfig": {
    "github_pat": {
      "type": "string",
      "title": "GitHub personal access token",
      "description": "Token used to file issues. Needs issues:write on the target repo.",
      "sensitive": true
    },
    "issue_repo": {
      "type": "string",
      "title": "Target repository",
      "description": "owner/repo that skill problem reports are filed against."
    }
  },
  "mcpServers": {
    "gh-issues": {
      "command": "...",
      "args": ["..."],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${user_config.github_pat}" }
    }
  }
}

Why this shape is the right one

The sensitive/non-sensitive split maps onto the two halves of the skill cleanly, and the constraint is a feature rather than a limitation:

• github_pat is sensitive → it can go into the MCP server config but can never be substituted into skill or agent content. The agent therefore never sees the token in its context. It calls MCP tools; the server holds the credential. That's the correct security posture, and it's enforced by the platform rather than by discipline.
• issue_repo is non-sensitive → it can substitute into skill content, so a DraftHorse step receives a resolved owner/repo in its prose without reaching for configuration.

One userConfig block, both substitution paths, each carrying the thing it should.

Verified vs. unverified

Verified against plugin_reference.md:

• ${user_config.*} substitutes in MCP server configs (line 561).
• Sensitive → keychain; non-sensitive → settings.json under pluginConfigs[<plugin-id>].options (line 563).
• mcpServers entries support command / args / env / cwd with variable substitution (lines 164–178).
• Values are exported to plugin subprocesses as CLAUDE_PLUGIN_OPTION_<KEY> (line 561) — note this covers hook/MCP subprocesses, not arbitrary Bash the agent runs, so ${user_config.*} substitution stays the right channel for skill-launched scripts.

Not yet verified — resolve before building:

• The exact token env var / config shape the GitHub MCP server expects (the env key above is a placeholder).
• Whether a remote HTTP GitHub MCP server's headers field accepts ${user_config.*}. Related caveat found in the docs sweep: headersHelper commands cannot reference ${user_config.*} (v2.1.207+), and shell-form hook commands reject it too (exec form with an args array is required). If the remote path is wanted, confirm headers isn't caught by the same restriction.
• Keychain storage is shared with OAuth tokens and capped around 2 KB total — fine for a PAT, worth knowing if more secrets get added later.

Open questions

• PAT scope: classic repo vs. fine-grained issues:write. Fine-grained is tighter and probably right for a single target repo.
• Does the plugin ship its own GitHub MCP server, or reuse an already-configured one when present? Shipping its own makes agent-tools self-contained for distribution, at the cost of a second GitHub MCP server for users who already have one.
• Fallback when the user declines to supply a PAT: the skill should degrade to drafting the issue body for manual paste rather than failing. Relevant to the error-reporting template, since the Dynamic Improvement hook shouldn't hard-fail a run just because issue filing isn't wired.

Thread to resume

Nothing in this repo currently uses userConfig — no plugin.json here declares one — so this would be the first. The DraftHorse side of the thread is separate: config wiring is being removed from scaffold.md's frontmatter section (it's declared in plugin.json, not in a document's frontmatter, and cannot substitute into frontmatter at all) and recatalogued as a "User configuration" dynamic reference in references.md, with the harness specifics going to surfaces.md. The sensitive-value limit above becomes a framework principle there: a step never receives a secret as resolved prose.

[dilberryhoundog]

Lets also handle these features:

• closing an issue. Running completion checks across the scope, using a sub agent.
• updating an issue with comment, main agent does this.