Git Workflow

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.

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

Unified notifications identify the repository and host or pull request before the event itself:

The sequence is assembled from three real Notification Center captures and plays once in under five
seconds. The Notifications guide keeps each original frame available for
closer inspection.

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:

# .git-workflow/git-workflow.local.md
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.