Git Workflow

Twenty cross-agent skills for shipping software with evidence and control.

An agent-neutral package of 20 skills, eight specialized agents, and opt-in hooks for Git, pull requests, releases, QA, and desktop notifications. The same repository supports Claude Code and Codex without maintaining two copies of the workflows.

Documentation · Installation · Latest release

What it includes

Framework-agnostic branch, commit, PR, release, QA, RFC, and status workflows
Linear, Jira, and GitHub issue integration through the host’s MCP configuration
Native Claude plugin packaging and a native Codex plugin manifest
Eight review, release, version-research, and QA agents
Canonical runtime-neutral configuration and state in .git-workflow/
Backward-compatible reads from legacy .claude/ state
An opt-in review hook for new commits and pushes, with host-specific delivery
Opt-in local alerts for main-agent completion and new reviews on your pull requests

Install for Claude Code

The existing marketplace installation remains supported:

/plugin marketplace add rlajous/claude-code-commands
/plugin install git-workflow@git-workflow-marketplace

Skills installed from the marketplace use the package prefix, for example:

/git-workflow:start PROJ-123
/git-workflow:commit
/git-workflow:finish

For unprefixed project skills, copy skills/ to .claude/skills/, agents/ to .claude/agents/, and the shared references/ directory to .claude/references/.

Install for Codex

Install or load this repository as a Codex plugin. Its .codex-plugin/plugin.json exposes all 20 directories under skills/. Then run the setup skill in the target project:

$setup

Codex plugins distribute skills and hooks, while named project agents are discovered from .codex/agents/. $setup installs the eight generated agent definitions there. It shows a diff and asks before replacing a customized file; pass --force only when replacement is intentional.

Use $setup --host codex, $setup --host both, or $setup --dry-run to make host selection and preview behavior explicit.

During local plugin development, this repository can be loaded from a checkout with Codex’s plugin installation/development workflow. No marketplace or universal-directory mutation is performed by this package.

For checkout-local development, Codex also discovers the same 20 skills through the committed .agents/skills -> ../skills symlink. Use either the installed plugin or checkout-local discovery in a session, not both, because duplicate skill names appear as separate entries.

Configure

Run /git-workflow:setup for a Claude marketplace install, /setup for a manual Claude project copy, or $setup in Codex. New projects use:

.git-workflow/
├── config.yaml
└── version.json

Generated local state—pr-context.json, status.html, hook opt-in settings, and the reviewed-SHA ledger—also lives under .git-workflow/ and is ignored where appropriate. Setup imports legacy values from .claude/ without deleting or silently overwriting the original files.

A minimal configuration is:

workflow:
  type: staging
  developmentBranch: staging
  productionBranch: main

issueTracker:
  type: auto

attribution:
  enabled: false
  format: ""

See CONFIGURATION.md and INSTALLATION.md.

Skills

Invoke a skill as /name in Claude and $name in Codex.

Skill	Purpose
`setup`	Configure the workflow and install project agents
`update`	Safely synchronize skills, agents, templates, and metadata
`start`	Create a feature branch from a ticket
`tdd`	Implement a ticket test-first
`commit`	Create a formatted commit
`finish`	Push and open a pull request
`review`	Fan out a comprehensive PR review
`review-watch`	Auto-review PRs that request your review, in a loop (linters + fan-out; REQUEST_CHANGES / APPROVE)
`notifications`	Diagnose and run opt-in main-agent and authored-PR activity notifications
`change-brief`	Generate a sub-10-minute HTML decision brief with business logic and contextual evidence
`release`	Prepare and validate a release
`release-notes`	Generate release notes
`sync`	Back-merge production into development
`plan-qa`	Generate a QA plan
`start-qa`	Execute a QA plan
`rfc`	Create an RFC
`review-request`	Draft a review request
`standup`	Summarize recent work
`status`	Show workflow state and next action
`clean-gone`	Remove gone branches and linked worktrees safely

Detailed examples are in COMMANDS.md.

Unified notifications

Agent completion and GitHub review activity use one opt-in notification system. The packaged Stop hook announces only the main Claude Code or Codex turn; one daemon shared with Review Watch announces new approvals, requested changes, and review feedback on PRs you authored.

notifications:
  agentComplete: true
  prActivity: true
  sound: Glass

/notifications --doctor          # Claude Code
/notifications --daemon-command
$notifications --doctor          # Codex
$notifications --daemon-command

The first PR-activity run establishes a silent baseline. Later events deduplicate by GitHub review ID, while completion alerts deduplicate by host, session, and turn without storing the assistant’s full message. Read the Notifications guide for installation modes, exact formats, privacy, local state, and troubleshooting.

Review watcher (console)

Ask the skill for an absolute, copy-paste-safe command, then run it in a spare terminal to get pinged (sound + desktop notification) when a PR requests your review. Notifications identify the repository and PR in the title (owner/repo · PR #42) and the author plus PR title in the message (@alice — Fix login redirect):

/review-watch --daemon-command   # Claude Code
$review-watch --daemon-command   # Codex

Run /review-watch --doctor in Claude or $review-watch --doctor in Codex to check paths, dependencies, configuration, and GitHub authentication without publishing a review. When the daemon beeps, use /review-watch <pr-url> in Claude or $review-watch <pr-url> in Codex (or the matching --drain form). It runs the project linters and its bundled known-issues ruleset first, escalates to the full review fan-out only if those pass, posts REQUEST_CHANGES on problems, and on a clean PR posts APPROVE, generates a change-brief with diagrams, UI/mobile screenshots, or API cURL evidence when relevant, and pings you. Opt in with reviewWatch.enabled: true in .git-workflow/config.yaml.

What it looks like

Review Watch uses the same identity at both points in the lifecycle:

Review requested	Ready for merge

Linux uses the active desktop’s native notify-send appearance. The daemon only discovers, de-duplicates, queues, and notifies; the active Claude or Codex session performs the review.

A clean result produces one self-contained HTML decision brief designed for a 6–8 minute read. It combines business rules, a diagram when the flow benefits from one, contextual screenshots or API cURL evidence, focused before/after code, risks, rollout, rollback, and verification.

Open the HTML example, read the complete Review Watch guide, or see the Change Brief guide.

Agents and delegation

The canonical instructions live in agents/*.md; generated Codex definitions live in .codex/agents/*.toml.

review starts the specialized review agents in parallel and waits for all findings.
release uses release-validator and uses version-delta-analyst when a dependency, framework, or API version changed.
start-qa delegates sufficiently large plans to qa-executor.
Routine edits remain in the main session.

Read the complete catalog in docs/SUBAGENTS.md.

Commit-review hook

The hook is disabled by default. Enable it in the target project:

review-on-commit: true

Claude registers hooks/claude-hooks.json; Codex discovers hooks/hooks.json. Both invoke the same script. It reacts only to git commit and git push, suppresses duplicate SHAs, and returns host-appropriate output. See HOOKS.md.

Updating safely

Use /update or $update. By default it previews differences and requires confirmation before overwriting a locally customized skill or agent.

$update --dry-run
$update --source ../git-workflow
$update --source https://github.com/rlajous/claude-code-commands.git
$update --host both
$update --prune
$update --force

Development

After changing a canonical agent, regenerate the committed Codex definitions:

node scripts/generate-codex-agents.mjs
node scripts/generate-codex-agents.mjs --check

Run all repository checks with:

bash scripts/validate.sh

The Claude and Codex manifests, skill/agent parity, TOML syntax, generated-file drift, and hook behavior are validated in CI.

License

MIT. See LICENSE.