@pieai/pro-gov

@pieai/pro-gov is the project-level setup kit for Project Governance System. It helps AI-assisted projects stay understandable after many plans, documents, tools, and AI sessions have accumulated.

Think of Project Governance System as a librarian, traffic desk, and inspection station:

• pro-gov shows which reusable project-governance parts are present or missing;
• @pieai/doc-gov checks documents, routing, links, guardrails, and CI;
• the AI host and project checks own normal execution;
• capture-learning visibly decides whether completed verified work produced a reusable lesson, and records it only when one exists.

The current pro-gov release is conservative by design. Public init and sync commands inspect and compare; they do not silently overwrite another project's router or local truth.

Install

Requires Node.js 24.x.

pnpm add -D @pieai/pro-gov @pieai/doc-gov

Optional project scripts:

{
  "scripts": {
    "pro-gov": "pro-gov",
    "doc-gov": "doc-gov"
  }
}

Public Commands

pro-gov assets list
pro-gov assets discover --target .
pro-gov assets recommend --target .
pro-gov portfolio check --config /path/to/portfolio.json
pro-gov portfolio plan --config /path/to/portfolio.json --target web-app --json
pro-gov portfolio assets-check --config /path/to/portfolio.json --json
pro-gov portfolio doctor --config /path/to/portfolio.json --json
pro-gov portfolio ai-health --config /path/to/portfolio.json --target all --out audits/portfolio-ai-health/2026-07-12
pro-gov host-lens scan --config /path/to/portfolio.json --out audits/host-lens/2026-07-16
pro-gov host-lens plan --config /path/to/portfolio.json --out audits/host-lens/cleanup-review.json
pro-gov lens inspect --target .
pro-gov lens report --target . --out .pro-gov/lens-report.md
pro-gov init --profile engineering-runtime --dry-run
pro-gov init --profile engineering-runtime --apply
pro-gov init --profile doc-only --dry-run
pro-gov sync --check --profile engineering-runtime
pro-gov doctor

What these commands do:

| Command group | Purpose | Writes project files? | | --- | --- | --- | | assets list | Shows packaged assets and public registry metadata. | No | | assets discover | Detects local project signals. | No | | assets recommend | Suggests relevant asset bundles with reasons. | No | | portfolio check | Validates an external portfolio manifest owned by the user or organization. | No | | portfolio plan | Builds dry-run asset plans for manifest targets, using packaged public assets unless a full checkout is supplied. | No | | portfolio assets-check | Checks the integrity of each target's current managed asset lock and symlinks. | No | | portfolio doctor | Runs the offline fleet gate: package, target CLI, bundle, asset, symlink, Git-state evidence, and optional host-tooling checks. | No | | portfolio ai-health | Writes the ProjectLens privacy-preserving HTML/JSON map of entry, user/project AI Host SSOT, exact technology-version, four verification-gate, project redundancy, MCP-name, skill, Git, and secret-location health. --target <id> refreshes one target and merges it into the same-portfolio board; --target all creates complete coverage. | Only the explicit output | | host-lens inspect | Inventories AI-host and shared-cache storage without reading configuration or session bodies. | No | | host-lens scan | Writes the fixed SwimmerUIKit HostLens dashboard and JSON evidence. | Only the explicit output | | host-lens plan | Writes a non-executable cleanup review checklist; it never deletes. | Only the explicit output | | lens inspect | Produces ProjectLens-style local evidence. | No | | lens report | Writes the requested report file. | Only the explicit output | | init --dry-run | Shows starter/profile files that would be needed. | No | | init --apply | Installs one profile into a fresh target; refuses the whole operation if any target file exists. Optional CI and Lefthook references are not installed. | Yes | | sync --check | Strictly compares shared core files, checks project-local seeds for presence, and leaves optional guardrail contents consumer-owned. | No | | doctor | Checks required packaged assets and whether doc-gov is available. | No |

Full Checkout Commands

The npm package can install reviewed public agent assets through an explicit plan. A full Project Governance System checkout can additionally use its maintainer-local asset registry:

pro-gov assets plan --bundle base-governance --target . --out .pro-gov/asset-plan.json
pro-gov assets apply --plan .pro-gov/asset-plan.json
pro-gov assets check --target .
pro-gov assets public-check --json
pro-gov assets npx update --plan

Skill placement normally comes from the asset registry. Use --placement manual only as an explicit migration override for project-scoped skills that should stay explicitly invoked instead of auto-discoverable:

pro-gov assets plan --bundle project-lens --target /path/to/project --host codex --placement manual --out /tmp/project-lens-plan.json

Codex manual placement writes managed skill links under .agents/manual-skills/ instead of .agents/skills/. User-scoped skills, such as a personal loop library, are not installed into project targets; link them once under the user's skill roots instead.

The plan is the safety gate. apply may update managed targets described by the plan; it must not overwrite an unrelated unmanaged file. When an asset leaves a bundle, a plan may remove its old symlink only when the previous lock proves ownership and both plan-time and apply-time checks confirm that the path is still the same managed symlink.

These checkout-only workflows depend on a maintainer-local agent-assets/ registry when local-only assets are being used. The public repository and npm package use public-agent-assets/ as the reviewed promotion surface. assets public-check verifies that every publishable public asset still matches the private-source and public-copy hashes recorded during promotion.

Package Boundary

• pro-gov distributes starter, profile, integration, and adoption assets.
• pro-gov assets discover|recommend provides read-only project evidence and deterministic recommendations.
• pro-gov portfolio check|plan|assets-check|doctor reads an external portfolio manifest. Real downstream project lists belong in the user's control repository, not in this public package. The manifest does not require a private headquarters repo: npm users can omit controlPlane and executionEngine, and PGS will use the reviewed public assets packaged with @pieai/pro-gov.
• pro-gov assets plan|apply|check manages local assets only from an explicit, reviewable plan in a full upstream checkout.
• pro-gov lens inspect|report provides read-only inspection and an explicit report output.
• doc-gov remains the document, router, manifest, link, CI, and migration validator.
• Product truth stays in the target project.
• pro-gov init --apply is intentionally fresh-target only. Existing projects use --dry-run and a deliberate migration so local truth is never overwritten.
• PGS does not require or bootstrap a workflow plugin.
• Optional hostTooling entries let portfolio doctor verify required Codex or Claude Code plugins. PGS does not install or upgrade those plugins.

Lightweight Agent Workflow

The AI host and the target project's proof commands own ordinary work. PGS does not appoint a mandatory workflow owner or require an external skill pack.

Before non-trivial implementation, debugging, release, architecture, or portfolio-sync work, run pro-gov learn recall --query "<task summary>" and read relevant docs/reference/learnings/** or CONCEPTS.md hits before changing files.

After completed, verified, non-trivial work, the small capture-learning Skill makes one visible decision. It writes a compact docs/reference/learnings/** record only when the result will help future work; otherwise it reports a skip. Resolve the CLI through the project (pnpm pro-gov in the PGS source repository) instead of assuming a global binary. PGS does not install Stop/SubagentStop reminder hooks or require a completion gate.

Read the full project introduction for beginner examples, profiles, adoption guidance, and exact integration boundaries.