Workflow Governance Kit

🇺🇸 English · 한국어: README.ko.md

Fail-closed workflow governance for coding-agent repositories. Codex, Claude, Cursor, Aider, Cline, and plain terminal commits all flow through the same precommit gate. The kit is language- and stack-neutral: a .workflow-governance.json config that your coding agent fills via the workflow-setup skill names your project's commands; the kit holds zero stack-specific code.

flowchart LR
  A[Coding agent or human commit] --> G[Universal pre-commit gate]
  G -->|"§2 lockstep<br/>CURRENT-PLAN.md staged?"| L[workflow-precommit.mjs]
  L -->|"optional consumer<br/>commands.guard"| C[your test/lint chain]
  C --> H[workflow-guard.mjs<br/>Mermaid + cleanup checks]
  H --> P[commit lands]

The kit installs documents, scripts, hooks, and agent skills into your project. Your team gets fail-closed enforcement of the Workflow Governance policy without writing custom CI glue.

Table of Contents

• Quick Start (5 minutes)
• Install
• Using with Claude Code
• Using with Codex CLI
• Supported Agents (v0.1.0)
• Workflow Scenarios
• Multi-Stack Support
• CLI Reference
• Task Graph
• Release Pipeline
• Agent Entrypoint Strategy
• Hook Strategy
• Troubleshooting
• Distribution Strategy
• License

Quick Start (5 minutes)

# 1. Install the kit's documents, scripts, hooks, and agent skills into your project.
cd path/to/your/repo
npx @workflow-governance/kit init --write

# 2. (one-time per clone) activate the universal git pre-commit gate.
git config core.hooksPath .githooks

At this point your project has:

• docs/WORKFLOW-GOVERNANCE.md, docs/CURRENT-PLAN.md, docs/HISTORY-MAP.md, docs/WORK-BACKLOG.md, docs/TASK-GRAPH.md
• scripts/workflow-guard.mjs + supporting libraries
• .githooks/pre-commit (universal gate)
• .claude/skills/workflow-{setup,init,status,close,release}/ and .codex/skills/workflow-{setup,init,status,close,release}/
• AGENTS.md and CLAUDE.md marker-bounded bootstrap blocks (preserves any existing content outside the markers)

The prepare script in your package.json runs git config core.hooksPath .githooks automatically on the next npm install, so subsequent clones do not need step 2.

# 3. Open your project in your coding agent and finish configuration.
#    The agent invokes a one-shot skill that detects your stack and writes
#    .workflow-governance.json — the language-neutral integration contract.

# Claude Code:
/workflow-setup

# Codex CLI:
$workflow-setup

The agent will inspect your project's marker files (package.json, Cargo.toml, pyproject.toml, go.mod, *.csproj, CMakeLists.txt, build.gradle*, Package.swift, etc.), propose appropriate commands.{guard, install, test, build, publish} values, and write a validated .workflow-governance.json at your project root.

# 4. Verify the setup landed and the kit is active.
workflow-governance status
workflow-governance config validate

That is the full first-time install. From now on:

• Every commit fires the three-stage gate (lockstep rule → your commands.guard if any → kit hygiene check).
• Use workflow-governance task add ... / update ... / close ... to track sub-tasks with a cycle-free DAG.
• Use workflow-governance release compose --write to produce a versioned release entry; the kit's CI workflow template handles publish.

Install

Recommended: project devDependency

npm install --save-dev @workflow-governance/kit
npx workflow-governance init --write
git config core.hooksPath .githooks

This adds @workflow-governance/kit to your devDependencies so the binary is resolvable without a fresh network fetch in CI. The prepare script the kit adds to your package.json activates the git hook on subsequent installs.

One-shot (without installing)

npx --yes @workflow-governance/kit init --write
git config core.hooksPath .githooks

Use this when evaluating the kit. Add --save-dev later for production projects.

From source (kit development)

git clone https://github.com/<your-fork>/workflow-governance-kit.git
cd workflow-governance-kit
node bin/workflow-governance.mjs init --write --target ../path/to/consumer-project

Add fail-closed enforcement

After init, install the per-agent enforcement adapters and the CI workflow:

npx workflow-governance install-enforcement --agent all --write
npx workflow-governance install-ci --write

--agent all auto-detects which coding agents your repo already uses (presence of .claude/, .codex/, .cursorrules, .aider.conf.yml, .clinerules) and installs only the relevant adapters. The git pre-commit hook is the runtime-agnostic baseline and is always included.

Using with Claude Code

Prerequisites

• Claude Code installed (@anthropic-ai/claude-code or the desktop app).
• Your project initialised with workflow-governance init --write.

What landed in your project

| File | Purpose | | --- | --- | | .claude/skills/workflow-setup/SKILL.md | Single onboarding entry point — invoke with /workflow-setup (auto-falls back to init if the kit is not yet installed) | | .claude/skills/workflow-status/SKILL.md | Active-lane / governance status check — /workflow-status | | .claude/skills/workflow-close/SKILL.md | Lane / sub-task closure procedure — /workflow-close | | .claude/skills/workflow-release/SKILL.md | Interactive wrapper around release compose --write — /workflow-release | | .claude/settings.json (after install-enforcement --agent claude) | PreToolUse + SessionStart hook entries pointing at the kit's gate scripts | | .claude/agent-memory/feedback_workflow_governance_priority.md | Memory stash for the user's profile-scoped memory directory (one-time copy) | | CLAUDE.md (marker block) | Project bootstrap reference; preserves existing content outside the markers |

First-time setup flow

1. Open the project in Claude Code (the IDE plugin or claude CLI).
2. Invoke the setup skill:

   /workflow-setup

3. The skill walks through an 8-step procedure (Step 0 + Steps 1–7):
   • Pre-flight (Step 0, new in v0.1.1) — checks for kit-installation markers (docs/WORKFLOW-GOVERNANCE.md, docs/CURRENT-PLAN.md, scripts/workflow-guard.mjs); if any are missing, the skill stops and directs you to npx workflow-governance init --write first. This makes workflow-setup the single onboarding entry point regardless of whether you've already run init.
   • Inventory — scans marker files, identifies your stack(s).
   • Propose commands — suggests commands.{guard, install, test, build, publish} values; you can override any.
   • CI provider detection — checks .github/workflows/, .gitlab-ci.yml, etc.
   • Write — produces .workflow-governance.json with the validated schema.
   • Customize CI template — if not GitHub Actions, translates templates/ci/release.yml to your provider.
   • Verify — runs workflow-governance run guard to confirm the configured guard works.
   • Hand-off — directs you to /workflow-status for ongoing use.

The skill is idempotent: re-invoking it on a project with an existing .workflow-governance.json preserves all set fields and only fills empty slots. Two runs against the same project + same answers produce byte-identical output.

Activate the kit-side hooks (if installed)

If you ran workflow-governance install-enforcement --agent claude --write, the kit added entries to .claude/settings.json. Claude Code reads this file automatically — no further action needed. The hooks fire on:

• SessionStart — surfaces the active lane and any governance warnings at the start of every session.
• PreToolUse — gates Bash:git commit to enforce §2 lockstep (no non-doc change without docs/CURRENT-PLAN.md staged).

Typical Claude Code workflow

1. Open project in Claude Code
2. (auto) SessionStart hook prints active lane + workflow:status summary
3. Plan / brainstorm with Claude
4. Make edits via Claude's Read/Edit tools
5. Stage changes: git add ...
6. Claude attempts git commit
7. (gate) PreToolUse runs workflow-precommit.mjs:
     - if docs/CURRENT-PLAN.md is staged → continue
     - else → BLOCKED with §2 citation
8. (gate) .githooks/pre-commit runs:
     - §2 lockstep + your commands.guard + kit hygiene
9. Commit lands

To close a sub-task, lane, or version:

/workflow-close <name>
/workflow-release            # only at version composition

Using with Codex CLI

Prerequisites

• Codex CLI installed (npm install -g @openai/codex).
• Your project initialised with workflow-governance init --write.

What landed in your project

| File | Purpose | | --- | --- | | .codex/skills/workflow-setup/SKILL.md | Single onboarding entry point — invoke as workflow-setup (auto-falls back to init if the kit is not yet installed) | | .codex/skills/workflow-{status,close,release}/SKILL.md | Ongoing governance skills (mirrors the Claude variants) | | .codex-plugin/plugin.json | Codex plugin manifest; Codex CLI auto-discovers it | | AGENTS.md (marker block) | Codex's canonical entrypoint; preserves existing content outside the markers |

First-time setup flow

1. Open the project in Codex CLI (codex from the project root).
2. Invoke the setup skill:

   workflow-setup

3. Same 8-step procedure as the Claude flow (Step 0 pre-flight kit check + Steps 1–7 setup; the SKILL.md content is byte-identical between Claude and Codex mirrors, only the install path differs).

Activate the kit-side hooks (if installed)

install-enforcement --agent codex copies the Codex skill files and the plugin manifest. Codex CLI auto-discovers them; no settings file edit needed.

Typical Codex CLI workflow

1. codex
2. (auto) Codex loads .codex-plugin/plugin.json and discovers skills
3. Plan / make edits via Codex
4. Stage changes
5. Commit attempt → .githooks/pre-commit fires (universal gate; same as Claude flow)
6. Commit lands

Supported Agents (v0.1.0)

| Agent | workflow-setup skill | Static convention file | Status | | --- | --- | --- | --- | | Claude Code | ✅ /workflow-setup | .claude/skills/workflow-setup/SKILL.md | MVP | | Codex CLI | ✅ workflow-setup | .codex/skills/workflow-setup/SKILL.md | MVP | | Gemini CLI | ⏳ deferred to v0.2 | — | Different skill format (.gemini/commands/*.toml) under review | | Cursor | ❌ (no project-local skill loader at v0.1.0) | .cursorrules | Static governance only | | Aider | ❌ (no project-local skill loader at v0.1.0) | CONVENTIONS.md + .aider.conf.yml.snippet | Static governance only | | Cline | ❌ (no project-local skill loader at v0.1.0) | .clinerules | Static governance only |

The static-convention agents (Cursor / Aider / Cline) still respect the universal git pre-commit hook on every commit they stage. They just don't (yet) run the interactive setup skill — you configure .workflow-governance.json from Claude or Codex, and Cursor / Aider / Cline inherit it via the kit's CLI dispatch.

Workflow Scenarios

Three concrete walkthroughs. Pick the one closest to your situation.

Scenario A — New project starting fresh

mkdir my-cool-project && cd my-cool-project
git init
npm init -y
npm install --save-dev @workflow-governance/kit
npx workflow-governance init --write
git config core.hooksPath .githooks

Open in Claude Code or Codex CLI, run /workflow-setup. Agent detects this is a Node project (because package.json exists), proposes commands.test = "npm test" etc., writes .workflow-governance.json.

# Confirm
npx workflow-governance config validate
npx workflow-governance status

You're done. Your first commit will go through the gate.

Scenario B — Existing project, applying governance retroactively

cd path/to/existing-repo
npm install --save-dev @workflow-governance/kit
npx workflow-governance init --write
git config core.hooksPath .githooks

init does not overwrite any existing AGENTS.md, CLAUDE.md, or docs/ files outside the marker-bounded sections. Pre-existing content stays. The kit-shipped policy documents land at docs/WORKFLOW-GOVERNANCE.md etc., and you can absorb your existing governance into them on your own schedule.

Then run /workflow-setup in your coding agent. If your project is non-Node (e.g., Python with a pyproject.toml), the agent proposes commands.test = "pytest" or similar — the kit never assumes Node.

For staged adoption (instead of all-at-once):

# Just add docs and scripts; skip hooks/skills/CI for now
npx workflow-governance init --check --write
# Later, when ready:
npx workflow-governance install-enforcement --agent all --write
git config core.hooksPath .githooks
npx workflow-governance install-ci --write

Scenario C — Producing your first release

You have closed several lanes (or sub-tasks) and they appear under docs/HISTORY-MAP.md ## Unreleased Workflow Evidence. Time to compose a version.

# Preview the release plan
npx workflow-governance release compose --version 0.1.0 --check

# Apply it: writes HISTORY-MAP + CURRENT-PLAN + bumps package.json
npx workflow-governance release compose --version 0.1.0 --write

# Commit, tag, push
git add docs/HISTORY-MAP.md docs/CURRENT-PLAN.md package.json
git commit -m "chore(release): compose v0.1.0"
git tag v0.1.0
git push origin main
git push origin v0.1.0

If you have templates/ci/release.yml installed (via install-ci) and NPM_TOKEN configured as a repo secret in GitHub Actions, the tag push automatically triggers release publish --write.

For a local publish:

$env:NPM_TOKEN = "<your token>"   # PowerShell
# or: export NPM_TOKEN="<your token>"   # bash
npx workflow-governance release publish --write

The kit's release publish writes a transient .npmrc from NPM_TOKEN, calls npm publish, then restores the prior .npmrc in a try/finally. .npmrc is in .gitignore as a crash-survivor safety net.

Multi-Stack Support

The kit's policy core is language-neutral; so is the integration surface. Every kit integration point reads commands from .workflow-governance.json via the canonical scripts/lib/config-schema.mjs:

• .githooks/pre-commit runs workflow-precommit.mjs (§2 lockstep, always), then commands.guard if set, then workflow-guard.mjs precommit (always).
• release publish runs commands.publish directly when set; falls back to npm publish[--dry-run] only when commands.publish is absent.
• templates/ci/release.yml (GitHub Actions) invokes workflow-governance run install/test/guard so the same template works for any stack.

The workflow-setup skill proposes appropriate commands for 13+ stacks. Examples:

| Stack | commands.install | commands.test | commands.build | commands.publish | | --- | --- | --- | --- | --- | | Node | npm ci | npm test | npm run build | npm publish | | Python (uv) | uv sync | uv run pytest | uv build | uv publish | | Python (poetry) | poetry install | poetry run pytest | poetry build | poetry publish | | Rust | (built-in) | cargo test | cargo build --release | cargo publish | | Go | go mod download | go test ./... | go build ./... | (varies) | | Java (gradle) | ./gradlew build -x test | ./gradlew test | ./gradlew assemble | ./gradlew publish | | C# / .NET | dotnet restore | dotnet test | dotnet build -c Release | dotnet nuget push | | C++ (CMake) | (ask) | ctest --output-on-failure | cmake --build build | (ask) | | Swift | (built-in) | swift test | swift build -c release | (ask) | | Ruby | bundle install | bundle exec rspec | gem build *.gemspec | gem push *.gem |

The kit holds zero of this knowledge in code — your coding agent fills the contract using its own stack expertise.

CLI Reference

# Governance bootstrap
workflow-governance init [--check|--write] [--mode greenfield|bootstrap] [--target <dir>]
workflow-governance install-codex [--check|--write]
workflow-governance install-claude [--check|--write]
workflow-governance install-hooks [--check|--write]
workflow-governance install-enforcement [--check|--write] [--agent claude|git|all|codex|cursor|aider|cline]
workflow-governance install-ci [--check|--write]

# Status / guard
workflow-governance status
workflow-governance guard
workflow-governance close-check

# Integration contract (Phase E)
workflow-governance config show           # prints .workflow-governance.json (exit 2 if absent)
workflow-governance config validate       # schema check (exit 0 pass / 1 invalid / 2 missing)
workflow-governance run <slot>            # slot = guard|install|test|build|publish

# Task graph (Phase C)
workflow-governance task add <id> --title "..." --lane <lane> [--depends-on <id>]... [--notes "..."]
workflow-governance task update <id> [--title ...] [--lane ...] [--status open|in-progress|blocked|done] [--reopen]
workflow-governance task depends-on <id> [--add <id>]... [--remove <id>]...
workflow-governance task close <id>
workflow-governance task list [--lane <lane>] [--status <status>]
workflow-governance task graph [--check]

# Release pipeline (Phase D)
workflow-governance release compose [--version <ver>|--bump major|minor|patch] [--check(default)|--write] [--allow-empty] [--date <YYYY-MM-DD>]
workflow-governance release publish [--registry npm|github] [--dry-run(default)|--write]

Concrete examples

# Track a feature breakdown as a DAG
workflow-governance task add login-ui --title "Login form UI" --lane "Q1-auth"
workflow-governance task add login-api --title "Auth API" --lane "Q1-auth"
workflow-governance task add login-tests --title "E2E tests" --lane "Q1-auth" --depends-on login-ui --depends-on login-api
workflow-governance task graph                       # renders docs/TASK-GRAPH-RENDER.md
workflow-governance task close login-ui              # transitions through the state machine
workflow-governance task list --status in-progress

# Compose a release from closed lanes
workflow-governance release compose --bump minor --check   # preview 0.1.0 → 0.2.0
workflow-governance release compose --bump minor --write   # apply

# Run consumer-defined commands through the kit's dispatch
workflow-governance run install      # `commands.install` or `npm ci` fallback
workflow-governance run test         # `commands.test` or `npm run check` fallback
workflow-governance run guard        # `commands.guard` or `node scripts/workflow-guard.mjs precommit` fallback

--check and --write are opt-in for every mutating verb. The default for init, release compose, install-* is check (no mutation); pass --write to apply.

Task Graph

The task graph (Phase C) captures intra-lane (and cross-lane) work-item structure. Tasks are nodes; dependsOn edges form a cycle-free DAG.

• Lifecycle: open → in-progress → done (with explicit --reopen required to revisit a closed task). A task cannot leave open until every dependsOn is done; the schema invariant catches the same condition on hand-edits.
• Render: task graph writes a deterministic Mermaid view at docs/TASK-GRAPH-RENDER.md. The precommit guard round-trips the data and the render to catch drift.
• Policy: full spec in docs/TASK-GRAPH.md. Canonical state file: tasks/state.json.

Release Pipeline

Two stages, both kit-CLI driven.

Stage 1 — Compose. release compose reads closed-but-unreleased lanes from docs/HISTORY-MAP.md "Unreleased Workflow Evidence", computes the next version per WORKFLOW-GOVERNANCE.md §7.2 semver bump rules (pre-1.0: minor default; explicit --version 1.0.0 for the cutover), writes a new ### vX.Y.Z entry to HISTORY-MAP with the §3 Composed milestones line, bumps package.json in lockstep. Writes are atomic (staging files in .tmp siblings, renaming after all writes succeed, re-running workflow:guard precommit to validate).

Stage 2 — Publish. release publish runs workflow:guard precommit → npm pack (or your commands.publish if set) → npm publish --dry-run (default) or npm publish (--write + NPM_TOKEN env + clean working tree). For non-npm stacks, commands.publish runs directly; the kit doesn't assume npm.

The GitHub Actions workflow at templates/ci/release.yml chains both stages: on v*.*.* tag push it runs install → test → guard → release publish. If NPM_TOKEN is not set as a repository secret, the action falls back to --dry-run.

Agent Entrypoint Strategy

The kit does NOT overwrite AGENTS.md or CLAUDE.md. It inserts or updates only this marker block:

<!-- WORKFLOW-GOVERNANCE:START -->
This repository follows [Workflow Governance](docs/WORKFLOW-GOVERNANCE.md).

Agents must keep [Current Plan](docs/CURRENT-PLAN.md) and its Mermaid status graph updated when work status changes. Durable history belongs in [History Map](docs/HISTORY-MAP.md).
<!-- WORKFLOW-GOVERNANCE:END -->

If your project already has equivalent policy text outside the marker block, the CLI reports it for manual review instead of deleting it.

Hook Strategy

Hooks are guards, not editors. They detect missing or inconsistent governance state and fail or warn; they never silently rewrite governance documents.

The universal git pre-commit gate at .githooks/pre-commit is installed by install-enforcement (or directly via install-hooks) and fires for every coding agent and every plain terminal commit:

1. Stage 1 (always) — scripts/workflow-precommit.mjs enforces the §2 Current Plan Freshness invariant: if any non-doc change is staged, docs/CURRENT-PLAN.md must be staged in the same commit.
2. Stage 2 (optional) — commands.guard from .workflow-governance.json runs (your project-specific check; e.g. npm run lint && pytest -q).
3. Stage 3 (always) — scripts/workflow-guard.mjs precommit runs broader hygiene checks (Mermaid status graph, lane/branch coherence, cleanup candidates, .workflow-governance.json schema validity).

Activate the gate once per clone:

git config core.hooksPath .githooks

(or rely on the prepare script the kit adds to your package.json).

CI can run the same guard against the staged tree:

npm run workflow:guard

Troubleshooting

npm publish fails with E403 — Two-factor authentication required

Your npm account has 2FA enabled and the token you used doesn't bypass it. Two fixes:

• Granular Access Token (recommended): at https://www.npmjs.com/settings/{user}/tokens/granular-access-tokens/new, ensure the new token has Read and write permission on the package + organisation. GATs auto-bypass 2FA when given write scope.
• Classic Automation Token: at https://www.npmjs.com/settings/{user}/tokens, choose type Automation when generating. This type is designed to bypass 2FA.

npm publish fails with E404 — scope not found

Your scoped package's npm organisation is not registered. For @your-scope/your-pkg:

npm org ls @your-scope

If the org doesn't exist, create it at https://www.npmjs.com/org/create (free tier supports public packages).

npm publish fails with E402 — payment required

The scoped package defaulted to restricted access. Add to your package.json:

"publishConfig": {
  "access": "public"
}

(or pass --access public to npm publish directly).

npm view <pkg>@<version> returns E404 right after publishing

npm registry CDN propagation. Wait 1–5 minutes. Workarounds:

# bypass local npm cache
npm view <pkg>@<version> --prefer-online

# explicit registry
npm view <pkg>@<version> --registry https://registry.npmjs.org/

Or verify directly on the web: https://www.npmjs.com/package/<pkg>.

Precommit gate blocks: "non-doc changes without docs/CURRENT-PLAN.md"

This is expected §2 lockstep enforcement. Stage your docs/CURRENT-PLAN.md update along with the code change, then commit. If the change truly doesn't affect lane status (e.g., a typo fix in a comment), use git commit --no-verify — the intentional bypass.

.workflow-governance.json not present info on every guard run

Expected if you haven't run the setup skill yet. The kit falls back to npm-flavoured defaults so the gate still works on Node projects. Run /workflow-setup in Claude Code or workflow-setup in Codex CLI to fill the config.

Working tree dirty: .claude/worktrees/ or .npmrc

Both are session-transient. .claude/worktrees/ is left by Claude Code worktree-based sessions; .npmrc is the transient auth file the kit writes during release publish --write. Both are in .gitignore; if you see them as untracked, git status is just listing the untracked directory itself. Either ignore or delete; neither affects publish.

Tag v0.1.0 doesn't exist when running publish helper

The helper script checks for a local tag. If you ran release compose --write but didn't tag yet:

git tag v0.1.0
git push origin v0.1.0

Help: my commands.<slot> doesn't run

Verify:

workflow-governance config show           # confirm the slot is set
workflow-governance run <slot>            # invoke directly

The run verb prints which source (config vs fallback) it resolved from. If "fallback", your config either has no commands.<slot> entry or the file isn't present.

Distribution Strategy

Core distribution is an npm package. The files allowlist ships only the kit's consumer-facing surface: bin/, templates/, scripts/, plugin/, README.md, CHANGELOG.md, docs/WORKFLOW-GOVERNANCE.md, docs/TASK-GRAPH.md. Per-session notes, briefings, and kit-internal operational state (docs/CURRENT-PLAN.md, docs/HISTORY-MAP.md) are NOT shipped — consumers receive starter copies via templates/docs/ during init.

Three-layer decoupling:

1. Policy core (docs/WORKFLOW-GOVERNANCE.md, docs/TASK-GRAPH.md) — language-neutral.
2. Universal gate (.githooks/pre-commit, scripts/workflow-{precommit,guard,resolve-command}.mjs) — runtime-agnostic; fires identically for Claude / Codex / Cursor / Aider / Cline / plain terminal commits.
3. Integration contract (.workflow-governance.json + scripts/lib/config-schema.mjs) — consumer-filled via the workflow-setup skill.

The kit holds zero stack-specific code. Adding a new stack to your team's workflow is a one-time /workflow-setup invocation in the consumer's project — the kit doesn't need to be updated.

License

MIT. See LICENSE or package.json for the full text.