dev-helper-github

A Claude Code plugin that brings BA, triage, UI spec, and coding agents to any GitHub project — driven entirely by GitHub Issues, Milestones, and Projects v2.

You act as product owner. You write milestones and bug reports. The agents do the rest.

Feature flow

Milestone (you)
  → /ba          — decomposes milestone into scoped stories with acceptance criteria
  → You review   — approve stories, flip label to "ready"
  → /ui-spec     — generates UI spec comment on frontend/fullstack issues (optional)
  → /triage      — claims issues, validates readiness, writes implementation brief
  → /code        — implements, tests, opens PR
  → You approve  — merge when satisfied

Bug flow

Bug report (you)
  → Add labels: bug, needs-triage
  → /triage      — validates reproduction steps, posts branch name and test approach
  → /code        — writes failing test, fixes, opens PR
  → You approve  — merge when satisfied

Installation

1. Install once per machine

npm install -g @lah8789/dev-helper-github
dev-helper-github install

This:

• Copies /ba, /triage, /ui-spec, /code slash commands into ~/.claude/commands/
• Registers the MCP server in ~/.claude/settings.json

You'll need these environment variables set in your shell:

export GITHUB_TOKEN=ghp_...                        # PAT with repo + project scopes
export GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_TOKEN  # required by GitHub MCP server

ANTHROPIC_API_KEY is set automatically by Claude Code — no action needed.

2. Set up each project

cd your-project
dev-helper-github init

This creates agent.config.json. Edit it with your GitHub org/repo names:

{
  "project": "my-project",
  "hubRepo": "your-org/my-project",
  "repos": [
    {
      "name": "web",
      "repo": "your-org/my-project-web",
      "scope": "frontend",
      "stack": "React, TypeScript",
      "claudeMd": "../my-project-web/CLAUDE.md"
    },
    {
      "name": "api",
      "repo": "your-org/my-project-api",
      "scope": "backend",
      "stack": "Node.js, PostgreSQL",
      "claudeMd": "../my-project-api/CLAUDE.md"
    }
  ],
  "githubProject": {
    "owner": "your-org",
    "number": 1,
    "statusFieldName": "Status",
    "backlogValue": "Backlog"
  },
  "mcpServerUrl": "https://api.githubcopilot.com/mcp/"
}

3. Open the project in Claude Code

The slash commands and tools are immediately available.

Usage

Slash commands

/ba 3              Decompose milestone #3 into GitHub issues
/ui-spec web       Generate UI specs for frontend issues in the "web" repo
/triage api        Triage ready and bug issues in the "api" repo
/code api 42       Implement issue #42 in the "api" repo

The repo argument matches the name field in agent.config.json.

Or natural language

"run the BA agent on milestone 3"
"generate UI specs for the web repo"
"triage the ready issues in the API repo"
"implement issue 42 in the API repo"

Claude Code routes these to the right tool automatically.

How it works

BA agent (/ba)

1. Reads the milestone title and description from GitHub
2. Researches the problem domain with web search
3. Decomposes the milestone into independently implementable stories
4. Creates GitHub issues with user stories and Given/When/Then acceptance criteria
5. Adds each issue to your GitHub Projects v2 board with Status = Backlog

UI spec agent (/ui-spec)

Runs on frontend and fullstack repos only. For each issue labelled needs-ui-spec:

1. Reads the issue and the repo's CLAUDE.md for existing design system context
2. Generates a structured UI spec as a GitHub issue comment covering layout, components, interactions, and visual acceptance criteria
3. Moves the label from needs-ui-spec to ready

Apply the needs-ui-spec label manually after reviewing BA stories, before running /triage.

Triage agent (/triage)

Processes both feature issues (ready) and bug issues (needs-triage) in a single run.

Features: validates the issue has enough detail for the coding agent — at least two Given/When/Then criteria, clear scope, and no missing dependencies. If clear: posts an implementation brief and branch name, moves to in-progress. If unclear: posts exactly what is missing, moves to needs-review.

Bugs: validates the report has reproduction steps, expected vs actual behaviour, and enough context to write a failing test. If complete: posts the branch name and suggested test approach, moves to in-progress. If incomplete: posts what is missing and leaves the issue on needs-triage.

Coding agent (/code)

Features:

1. Creates a feature/issue-{n}-{slug} branch
2. Writes failing tests mapped to each acceptance criterion
3. Implements until tests pass
4. Opens a PR linking to the issue

Bugs:

1. Creates a fix/issue-{n}-{slug} branch
2. Writes a failing integration test that reproduces the bug
3. Fixes until the test passes — does not adjust the test to fit broken behaviour
4. Opens a PR describing the root cause and fix

Both modes support resuming interrupted sessions automatically.

Label state machine

Features

needs-ba → ba-in-progress → needs-review → [needs-ui-spec →] ready → in-progress → done

Bugs

needs-triage → in-progress → done

Labels and colours are created automatically in each repo on first run.

Multi-repo projects

One agent.config.json covers all repos. The BA agent routes stories to the right repo based on scope:

| Scope | When to use | |---|---| | frontend | UI components, routing, state management | | backend | Endpoints, business logic, data models | | shared | Types, contracts, shared utilities | | fullstack | Only when a change genuinely can't be split | | infra | Infrastructure, CI/CD, deployment |

If a feature needs both a frontend and backend story, the BA agent creates both and marks the backend as a dependency.

GitHub Projects v2

Issues created by the BA agent are automatically:

1. Added to your Projects v2 board via the GitHub MCP server
2. Set to the configured backlogValue (default: "Backlog")

Two transport options for the GitHub MCP server:

Remote (default, no binary needed):

{ "mcpServerUrl": "https://api.githubcopilot.com/mcp/" }

Local binary (more control over toolsets):

{ "mcpServerPath": "github-mcp-server" }

Install from github/github-mcp-server releases.

Session continuity

If a coding agent session is interrupted, run /code again with the same repo and issue number. The agent reads .agent/coding-<n>.json and picks up from the last completed step.

Required tokens

| Variable | Description | |---|---| | GITHUB_TOKEN | GitHub PAT — needs repo and project scopes | | GITHUB_PERSONAL_ACCESS_TOKEN | Same value — required by the GitHub MCP server | | ANTHROPIC_API_KEY | Set automatically by Claude Code |

Development

git clone https://github.com/lah8789/dev-helper-github
cd dev-helper-github
npm install
npm run build
npm run dev        # watch mode

Test locally by pointing .mcp.json at your build:

{
  "mcpServers": {
    "agent-library": {
      "command": "node",
      "args": ["/absolute/path/to/dev-helper-github/dist/index.js"]
    }
  }
}

Run the integration test against a real GitHub repo:

GITHUB_TOKEN=... TEST_HUB_REPO=your-org/hub npm run test:integration