Govern AI-Assisted Specs in Git with SpecGov

AI coding agents can produce code faster than a team can review the documents that are supposed to govern that code. A repository may contain requirements, designs, tasks, and verification notes, while Git itself does not tell you whether a change still has a complete chain back to those artifacts.

SpecGov is an open-source TypeScript CLI and GitHub Action for that specific gap. It discovers common spec-driven workflows, normalizes their files into an artifact graph, and reports missing relationships or code changes that bypass explicit mappings. The useful part is its boundary: it checks repository structure and declared relationships, not whether an AI claim is true.

In this tutorial, you will build SpecGov from its public repository, run a local check, inspect the graph, add a domain mapping, and wire the result into a pull request workflow.

TL;DR

SpecGov gives a repository a deterministic governance check for durable development artifacts. It supports GitHub Spec Kit, OpenSpec, Kiro, and configurable Generic/TLC layouts. It runs locally without an account, API key, upload, or network call after installation.

The current repository documents version 1.0.0-rc.2 on the main branch. At the time of writing, that release candidate was not available from npm, so the commands below use a checkout and local build. Treat this as a current-source tutorial, not proof of a stable package release.

Prerequisites

• Git
• Node.js 20 or newer
• A repository containing specifications, plans, tasks, or other durable development artifacts
• A shell with permission to install dependencies and run Node.js

The project is released under the MIT license. Its README and package metadata identify Fernando Paladini as the author and paladini/specgov as the source repository.

Build and run the minimal path

Clone the repository and build the CLI:

git clone https://github.com/paladini/specgov.git
cd specgov
npm ci
npm run build

Run the generated CLI against the checkout itself:

node dist/cli.js check

The repository currently reports an advisory pass with the Generic framework, two change sets, seven artifacts, and zero findings. Your output will differ if you run it against another repository or a newer commit. The important result is the shape of the report: detected frameworks, change sets, artifacts, findings, evidence, and remediation details.

You can inspect the normalized graph as Markdown:

node dist/cli.js graph --format markdown

The graph lists artifact IDs, paths, roles, and relationships such as derives_from and verifies. This is more useful than a directory listing because it makes the relationships that governance depends on visible and reviewable.

Finally, preview the configuration SpecGov would create from detected workflows:

node dist/cli.js init --dry-run

The command prints a specgov/v1 manifest without changing the repository. That makes it a safe first step when you are inheriting an existing spec layout.

Add an explicit domain mapping

Autodetection is useful for common layouts, but path-sensitive governance should be explicit. Add a .specgov.yml file when a code area must be connected to particular artifacts:

schema: specgov/v1
mode: advisory
frameworks: auto

domains:
  - id: authentication
    code:
      - "src/auth/**"
    artifacts:
      - "specs/auth/**"
      - ".kiro/specs/auth/**"

policies:
  require_complete_chain: true
  require_change_artifact_for_code: true
  require_verification_evidence: false
  stale_after_days: 90

The domains block says which artifacts govern which code. The policy flags then define the minimum structural chain. A changed specification in an unrelated directory does not satisfy an explicit domain, which prevents a generic document from hiding a missing authentication-specific change.

Run the check again:

node dist/cli.js check

Start with mode: advisory while you learn the repository's actual shape. Once the findings are understood, strict mode can make policy findings fail the command. The project documents exit code 1 for strict policy failures and exit code 2 for configuration or runtime errors.

Enforce the result in GitHub Actions

SpecGov also ships a GitHub Action. The documented workflow checks out the full history and compares the pull request base and head revisions:

- uses: actions/checkout@v5
  with:
    fetch-depth: 0
- uses: paladini/specgov@v1
  with:
    mode: strict
    base-ref: ${{ github.event.pull_request.base.sha }}
    head-ref: ${{ github.event.pull_request.head.sha }}

The Action writes a Markdown summary and exposes status, report JSON, graph JSON, detected frameworks, and finding count. Full history matters because the comparison needs both revisions. The v1 Action reference is separate from the current npm-style package version shown in package.json, so check the project's release guidance before pinning a production workflow.

Why this works

SpecGov separates three questions that are often mixed together:

1. Which artifact workflows exist in this repository?
2. Are the declared files and relationships structurally complete?
3. Is the content semantically correct and truthful?

The first two are deterministic enough for a local command and a pull request check. SpecGov can prove that files, states, relationships, and explicit path mappings satisfy configured structural policy. It cannot prove that a requirement is well designed, that a test really covers a behavior, or that a declared AI producer actually created a file. Optional semantic auditors can add review signals, but they do not change that boundary.

That limitation is a feature for CI. A governance check should report evidence that a machine can reproduce, not turn an unverified declaration into a security guarantee.

Common failure modes

The documented npx command cannot resolve

The README shows npx specgov check, but the checked npm registry query did not find specgov@1.0.0-rc.2. Use the checkout workflow above until the package is published, or confirm the exact version in the registry before sharing an npx command.

The check passes but the change is still wrong

That is expected. A pass means the structural policy was satisfied. It does not validate business logic, semantic quality, authorship, or the correctness of an external claim. Keep normal code review, tests, and security review in the workflow.

A strict check fails unexpectedly

Inspect the report and graph first. Look for an incomplete artifact chain, a missing domain mapping, a stale artifact, or a base/head reference that is not available in the checkout. Run advisory mode locally to understand the findings, then make the smallest explicit mapping that represents the intended workflow.

Old manifests stop working

SpecGov v1 is an intentional break from the v0.1 contract. The upgrade guide says that old version, artifacts, mappings, and rules fields and the old scan, check-pr, trace, and drift commands are unsupported. Use specgov init --dry-run, convert trusted mappings into domains, and replace old PR checks with specgov check --base-ref ... --head-ref ....

FAQ

Does SpecGov upload repository content?

The project documents local and deterministic behavior by default, with no account, API key, upload, or network call. Verify the version and configuration you deploy, and review the repository's security policy for your environment.

Does it replace a spec-authoring framework?

No. It governs artifacts created by workflows such as GitHub Spec Kit, OpenSpec, Kiro, or a Generic/TLC layout. It is a governance layer, not another authoring system.

Can I use it without GitHub Actions?

Yes. The CLI is the primary local path. The Action is an optional enforcement boundary for pull requests.

Takeaway

The practical value of SpecGov is not that it makes AI-assisted development automatically correct. It makes the repository's declared development chain inspectable: code, artifacts, relationships, and policy become evidence that a local command and CI can reproduce.

If you try this on a real repository, begin with init --dry-run, review the graph, and keep advisory mode until the findings match your team's intended workflow. Then decide which structural rules are strong enough to block a pull request.

This tutorial was prepared with AI assistance. The repository documentation, package metadata, current configuration example, checkout build, tests, lint, typecheck, format check, audit, and CLI smoke commands were checked against the public project state at publication time.

What artifact relationship would you want a pull request check to prove before code could merge?