github-commander

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