---
name: github-commander
description: |
  Structured workflows for GitHub issues, PRs, milestones, and code audits with validation gates and HITL checkpoints. 
  Use when assigned a GitHub issue, reviewing a PR, sprinting through a milestone, updating dependencies, or running code audits. 
  Also use when asked to "triage an issue", "review a PR", or "update deps". 
  Do NOT trigger on bare verbs (e.g. "fix this"); require GitHub context. 
  NOT for pipeline authoring (use github-actions instead).
  Delegate all code quality, performance, and security audits to the dedicated `adversarial-*` skills instead.
---

# GitHub Commander

Structured, configurable workflows that teach AI agents to triage GitHub issues,
review PRs, and sprint through milestones. Every action is journaled for full
audit trails, and human-in-the-loop checkpoints keep you in control.

The reason every step journals its results is that it creates a searchable audit
trail — future sessions can find exactly what was tried, what passed, and what
failed, without the human needing to remember or repeat context.

## When to Load

Load this skill when any of these apply:

- You are assigned or asked to fix a GitHub issue
- You need to review or submit a pull request
- You need to work through issues in a milestone
- You want to run dependency updates, security audits, or code quality audits
- The user mentions an issue number (e.g., "fix #42") or PR number
- The user says "triage", "audit", "review", "update deps", or similar
- You are about to push code and want a structured validation pipeline

## Quick Reference

| Workflow                | File                            | Purpose                                     |
| ----------------------- | ------------------------------- | ------------------------------------------- |
| **Issue Triage**        | `workflows/issue-triage.md`     | Fix a single GitHub issue end-to-end        |
| **PR Review**           | `workflows/pr-review.md`        | Review a PR with validation pipeline        |
| **Milestone Sprint**    | `workflows/milestone-sprint.md` | Work through milestone issues sequentially  |
| **Roadmap Kickoff**     | `workflows/roadmap-kickoff.md`  | Translate planning epics into Kanban issues |
| **Update Dependencies** | `workflows/update-deps.md`      | Dependency update with audit trail          |

## Prerequisites

- `gh` CLI authenticated (`gh auth status`)
- `GITHUB_TOKEN` set for API access
- `PROJECT_REGISTRY` configured for repo auto-detection
- Project repo cloned locally

## Configuration

All commands are configurable via environment variables. Defaults assume a
Node.js project. Override for other ecosystems (Python, Rust, Go, etc.).

| Variable                        | Default             | Description                         |
| ------------------------------- | ------------------- | ----------------------------------- |
| `PROJECT_LINT_CMD`              | `npm run lint`      | Lint command                        |
| `PROJECT_TYPECHECK_CMD`         | `npm run typecheck` | Type-check command (empty = skip)   |
| `PROJECT_BUILD_CMD`             | `npm run build`     | Build command (empty = skip)        |
| `PROJECT_TEST_CMD`              | `npm run test`      | Unit/integration test command       |
| `PROJECT_E2E_CMD`               | _(empty = skip)_    | E2E test command                    |
| `PROJECT_PACKAGE_MANAGER`       | _(auto-detect)_     | `npm`, `yarn`, `pnpm`, or `bun`     |
| `PROJECT_HAS_DOCKERFILE`        | _(auto-detect)_     | `true` to enable Docker audit steps |
| `COMMANDER_HITL_FILE_THRESHOLD` | `10`                | HITL if changes touch > N files     |
| `COMMANDER_SECURITY_TOOLS`      | _(auto-detect)_     | Comma-separated override list       |
| `COMMANDER_BRANCH_PREFIX`       | `fix`               | Branch naming prefix                |

### Package Manager Auto-Detection

If `PROJECT_PACKAGE_MANAGER` is not set, detect by lockfile:

1. `bun.lockb` or `bun.lock` → `bun`
2. `pnpm-lock.yaml` → `pnpm`
3. `yarn.lock` → `yarn`
4. `package-lock.json` → `npm`
5. Fallback → `npm`

### Security Tool Auto-Detection

When `COMMANDER_SECURITY_TOOLS` is not set, each tool is detected independently:

| Tool           | Detection                       | What It Scans                 |
| -------------- | ------------------------------- | ----------------------------- |
| `npm-audit`    | Always (Node.js project)        | Dependency vulnerabilities    |
| `codeql`       | `codeql` CLI or `gh codeql`     | Static analysis (SAST)        |
| `trivy`        | `trivy --version` succeeds      | Container images, filesystems |
| `docker-scout` | `docker scout version` succeeds | Docker image CVEs             |
| `gitleaks`     | `gitleaks version` succeeds     | Secrets in git history        |
| `trufflehog`   | `trufflehog --version` succeeds | Secrets (verified only)       |

Missing tools are skipped with a journal note — never a failure.

## Core Concepts

### Validation Gates

Every workflow uses sequential validation gates. Each gate must pass before the
next runs. On failure, the agent attempts to auto-fix (lint/type errors). If
auto-fix fails after 2 attempts, the agent requests human input.

```
Gate 1: Lint + Typecheck  →  Gate 2: Build  →  Gate 3: Tests  →  Gate 4: E2E  →  Gate 5: Security
```

Gates configured with empty commands are skipped automatically.

### Journal Audit Trail

Every significant action creates a journal entry with structured tags:

- **`commander`** — all entries from this skill
- **`triage`** / **`review`** / **`milestone`** — workflow type
- **`gate-pass`** / **`gate-fail`** — validation results
- **`security`** — security scan findings

Entries link to issues/PRs via `issue_number` and `pr_number` fields, connecting
to the knowledge graph automatically.

### Human-in-the-Loop Checkpoints

The agent pauses and requests human approval when:

1. **Before `git push`** — present diff summary, files changed
2. **Critical security findings** — any critical/high severity scan result
3. **Unfixable test failures** — after 2 auto-fix attempts
4. **Large changesets** — changes touch more files than `COMMANDER_HITL_FILE_THRESHOLD`
5. **Between milestone issues** — in milestone-sprint workflow

## Shipped Entry Types

These entry types are used by Commander workflows for structured audit trails:

| Type                     | Used By          | Purpose                                     |
| ------------------------ | ---------------- | ------------------------------------------- |
| `triage`                 | issue-triage     | Issue context gathered, analysis complete   |
| `implementation`         | issue-triage     | Fix implemented                             |
| `gate_pass`              | all              | Validation gate passed                      |
| `gate_fail`              | all              | Validation gate failed (with error details) |
| `pr_submitted`           | issue-triage     | PR created and pushed                       |
| `review_start`           | pr-review        | PR review initiated                         |
| `review_complete`        | pr-review        | PR review completed                         |
| `milestone_sprint_start` | milestone-sprint | Sprint started                              |
| `deps_update`            | update-deps      | Dependency update completed                 |