Software Project Governance

AI coding delivery trust layer for evidence-backed planning, review, risk, quality, and release control.

Software Project Governance helps AI coding agents keep delivery trustworthy while you stay focused on product and technical decisions. It is designed for marketplace reviewers, AI coding users, and teams who need a repeatable way to stop drift, missing evidence, weak review loops, and premature release claims.

Marketplace Review Ready

Use this workflow when your AI coding setup needs:

• Evidence-backed delivery: every meaningful task can carry facts about what changed, why it changed, how it was verified, and what remains risky.
• Gate and risk control: stage gates, task status, risks, decisions, and release readiness stay connected instead of living in scattered chat memory.
• Reviewer separation with degraded-mode honesty: the workflow distinguishes real independent review from degraded or environment-dependent execution, and does not present every agent as fully supported.
• 5-minute orientation for new users: start with /governance, initialize .governance/, then let the agent resume state, check gates, and surface only critical decisions.

1.0.0 Readiness Boundary

0.57.0 packages the 0.55.0 Dynamic Lifecycle migration preview and external validation archive, the 0.55.1 Web console CLI/client entry patch, the 0.55.2 passive Web summary entry patch, the 0.55.3 governance-entry correction, the 0.56.0 zcode plugin marketplace adapter, the FIX-151 Web console real-data dashboard patch (0.56.1), and the AUDIT-121 architecture degradation audit archive (no functional code change). It is not the 1.0.0 release. 0.57.0 is a documentation/governance-only release: it archives the full-project architecture degradation diagnosis (docs/requirements/architecture-degradation-audit-0.57.0.md, F1-F6 facts: the verify_workflow.py God Module at 20,294 lines, the missing modern engineering infrastructure, the source/projection duplication, the command-surface redundancy, the self-evolution residue, and the architecture-health stewardship gap), adds a technical-debt ledger (skills/software-project-governance/core/technical-debt-ledger.md, TD-001006), cleans up root-directory residue (nul, _fix_030_reconstruct.py), and plans the subsequent refactor roadmap (0.58.0 ArchGuard as an independent capability version, 0.59.00.64.0 progressive per-domain split of verify_workflow.py). 0.57.0 does not modify verify_workflow.py functional code, does not implement ArchGuard, does not split any module, and does not introduce lint/type infrastructure. The release keeps the dry-run-only dynamic-lifecycle-migration --target --dry-run preview, the migration guide, the python_game chapter-flow validation archive, and the shitu non-game validation archive from 0.55.0. 0.55.1 added web-console --status and web-console --start [--install]; 0.55.2 added web-console --summary-link for read-only task, phase, and session summaries; 0.55.3 restores the intended product entry so manual /governance starts or reuses the local Web console through web-console --governance-entry, then reports the URL for follow-up Web UI interaction; 0.56.0 adds the zcode native plugin surface (.zcode-plugin/, top-level package.json) and a one-shot project/zcode-local-load.py tool so the plugin can run in the local zcode installation; 0.56.1 fixes the Web console dashboard to read real governance data instead of hardcoded mock values, adds a web/server.py API server and web/vite.config.js proxy, makes all dashboard buttons functional, and keeps the dashboard a read-only local companion. classic-phase-gate remains the active/default compatibility preset, dynamic-flow-gate remains inactive/non-default and opt-in only, and no project is migrated by this release. The external validations remain intentionally conservative: both dry-run previews reached READY_FOR_REVIEW, but installed-state validation still has target-native blockers, and non-game preset generalization remains partial because shitu preview flow units still come from the python_game_10_chapters example. RISK-036, RISK-037, and RISK-039 remain open: no official approval, no marketplace approval (the zcode adapter proves local load/runtime only; it is not submitted to or approved by the zcode official marketplace), no two-real-project external validation full PASS, no Codex Desktop lifecycle PASS, no project migration, no ArchGuard implementation, no RISK-036 closure, no RISK-037 closure, no RISK-039 closure, and no 1.0.0 production-ready claim. 0.62.0 update (FIX-167, DEC-093): the 0.56.0 reverse-engineered project/zcode-local-load.py seed-hash tool has been removed — newer zcode runtimes ship a marketplace chain and the plugin now installs via the shared Claude/zcode marketplace protocol (/plugin marketplace add peterwangze/software-project-governance). This is protocol-conformant installability, still not zcode official curation or approval; RISK-036/RISK-037/RISK-039 remain open.

Mainstream Agent Loading

0.47.0 makes the current loading paths explicit for mainstream AI coding agents. This is loading readiness, not official approval, marketplace approval, universal/full runtime support, or Codex Desktop marketplace-management E2E PASS. See the 0.47.0 scope note in docs/requirements/mainstream-agent-loading-0.47.0.md and the public runtime facts in docs/requirements/runtime-readiness-matrix-0.43.0.md.

Tier 1 loading guide:

Agent	Load or install path	First verification	Current boundary
Claude Code	Add this repo as a Claude plugin marketplace, then install software-project-governance@spg.	python adapters/claude/launch.py and python skills/software-project-governance/infra/verify_workflow.py check-agent-adapters --runtime	Claude target-cwd read use case is PASS/DEGRADED in local evidence. This is not official marketplace approval.
Codex	Use .agents/plugins/marketplace.json, .codex-plugin/plugin.json, AGENTS.md, and skills/software-project-governance/SKILL.md as the Codex plugin/project guidance package.	python C:\Users\peter\.codex\skills\.system\plugin-creator\scripts\validate_plugin.py ., python adapters/codex/launch.py, and python skills/software-project-governance/infra/verify_workflow.py agent-runtime-e2e --agent codex --timeout 180	Codex CLI headless target-cwd read E2E is PASS/DEGRADED as of 2026-06-11. This is still not Codex Desktop marketplace-management lifecycle PASS.
Gemini CLI	Use a thin GEMINI.md project context pointer to skills/software-project-governance/SKILL.md; custom commands, MCP, and extensions remain separate extension points.	python adapters/gemini/launch.py, then GEMINI_CLI_TRUST_WORKSPACE=true python skills/software-project-governance/infra/verify_workflow.py agent-runtime-e2e --agent gemini --timeout 180	Gemini CLI target-cwd read E2E is PASS/DEGRADED as of 2026-06-11 when headless workspace trust is enabled. No Gemini plugin marketplace claim.
opencode	Use AGENTS.md or configured opencode instructions to point at skills/software-project-governance/SKILL.md.	python skills/software-project-governance/infra/verify_workflow.py opencode-provider-preflight and python skills/software-project-governance/infra/verify_workflow.py agent-runtime-e2e --agent opencode --timeout 90	opencode target-cwd runtime E2E is PASS/DEGRADED in local evidence; provider/model preflight still guards future regressions.
Chrys	Chrys auto-loads AGENTS.md and CLAUDE.md as native context, plus native load_skill for skills/software-project-governance/SKILL.md.	python adapters/chrys/launch.py and python skills/software-project-governance/infra/verify_workflow.py check-agent-adapters	Chrys was the first adapter with a full native profile: native ask_user, sub_agent, tool_calling, and git_hooks. Only browser and MCP remain host-dependent.
DeepSeek Harness (dsh)	Standard plugin install: dsh plugin --profile web add github:peterwangze/software-project-governance (bundle layer; restart the profile to activate — the governance skills and /governance command projections then load in every session of that profile). Optional Coordinator persona preset: python adapters/dsh/launch.py --install generates the governance agent preset under ${DSH_HOME}/.agent-presets/ (the always-scanned user root). Per-project activation: python adapters/dsh/launch.py --bootstrap-project writes a thin AGENTS.md.	dsh --profile --dump-config shows the @zcode/software-project-governance-plugin bundle layer; python adapters/dsh/launch.py and python skills/software-project-governance/infra/verify_workflow.py check-agent-adapters	dsh matches Chrys's native profile (native ask_user_question, subagent, tool_calling, git_hooks; /governance loads the command shim skill). Only browser automation and MCP remain host-dependent. The dsh plugin install is the official bundle mechanism, not a marketplace approval or universal runtime claim.
zcode	Add this repo as a plugin marketplace and install: /plugin marketplace add peterwangze/software-project-governance, then /plugin install software-project-governance@spg. zcode reuses the Claude marketplace protocol (.claude-plugin/marketplace.json + .zcode-plugin/plugin.json).	python skills/software-project-governance/infra/verify_workflow.py check-agent-adapters	Protocol-conformant marketplace install. Not zcode official curation or approval. The 0.56.0 reverse-engineered local-load tool was retired in 0.62.0 (DEC-093).

Tier 2 compatibility and research rows:

Agent	Loading surface to watch	0.47.0 status
Cursor	Project/user/team rules and AGENTS.md style project instructions	Compatibility reference only; no adapter manifest or runtime PASS.
GitHub Copilot coding agent	Repository custom instructions and AGENTS.md custom instructions	Compatibility reference only; no adapter manifest or runtime PASS.
Cline	Markdown rules such as Cline rules files	Compatibility reference only; no adapter manifest or runtime PASS.
Windsurf/Cascade	Workspace rules and memories	Compatibility reference only; no adapter manifest or runtime PASS.
Kiro	Workspace steering files such as .kiro/steering/	Compatibility reference only; no adapter manifest or runtime PASS.

Claude Code:

/plugin marketplace add peterwangze/software-project-governance
/plugin install software-project-governance@spg

Alternative Claude paths:

/plugin install https://github.com/peterwangze/software-project-governance.git
git clone https://github.com/peterwangze/software-project-governance.git
/plugin install /path/to/software-project-governance

DeepSeek Harness (dsh) plugin install:

dsh plugin --profile web add github:peterwangze/software-project-governance
# local checkout alternative (run from anywhere; the path is anchored to your invoking directory):
dsh plugin --profile web add /path/to/software-project-governance

Restart the dsh web profile after installing — bundle layers apply at profile boot. The governance skills and the /governance command projections then load in every session of that profile. To also activate the Coordinator persona preset, generate it into the always-scanned user root (works against the dsh-installed package copy; adapt the profile name if you use another profile):

python "${DSH_HOME:-$HOME/.dsh}/profiles/web/node_modules/@zcode/software-project-governance-plugin/adapters/dsh/launch.py" --install

Codex personal marketplace package:

python -m json.tool .agents/plugins/marketplace.json
python -m json.tool .codex-plugin/plugin.json
python C:\Users\peter\.codex\skills\.system\plugin-creator\scripts\validate_plugin.py .

Gemini and opencode thin project projections:

python adapters/gemini/launch.py
python adapters/opencode/launch.py

For every agent, load skills/software-project-governance/SKILL.md as the workflow entry and let runtime records live in the target project's .governance/ directory. Adapter and marketplace assets describe install and loading paths; they are not evidence of marketplace approval or universal runtime readiness.

Trust and Data Boundary

• The workflow writes project governance state to your project-local .governance/ directory.
• It uses local files, git hooks, validation scripts, and agent-readable skills to keep delivery facts inspectable.
• The repository's own .governance/ directory is a dogfood/sample runtime record, not a template to copy into your project.
• Adapter and marketplace assets describe install and loading paths; they are not evidence of marketplace approval or universal runtime readiness.

5-Minute Start

The first success path is intentionally small: get one local trust signal before learning the full governance model.

1. Install through one of the paths above.
2. Open your project root in your AI coding environment.
3. Run /governance; if your environment exposes status directly, the same first signal is the status output.
4. Look for the Delivery Trust Snapshot: goal, stage, gate/setup status, risk, evidence, next action, preset guidance, verification signal, and no-overclaim boundary.
5. For a local demo-only check that needs no external credentials, run:

python skills/software-project-governance/infra/verify_workflow.py first-run-demo --assert-snapshot

The snapshot is the first trust signal: it proves the workflow can show what it knows, what remains missing, and the next evidence-backed action. It is not a claim of official approval, marketplace approval, universal/full runtime support, or 1.0.0 production-ready status.

External first-session measurement is tracked separately from this local demo. The current 0.43.0 measured state is local_demo=PASS and external_pilot=NOT_MEASURED in the first-session measurement evidence.

Optional Local Web Console

The primary user interface remains your AI coding CLI or client: Claude Code, Codex, Gemini CLI, opencode, or another agent host. The web/ console is an optional local companion view for users who want a cleaner status surface while still driving work from the CLI/client.

Use it for local configuration, current status, evidence/risk scanning, and advanced maintenance visibility. It does not replace /governance, does not auto-run agent tasks, and is not evidence of Codex Desktop marketplace-management lifecycle PASS.

Discover it from the same CLI/client path:

python skills/software-project-governance/infra/verify_workflow.py web-console --status

Manual /governance is the default user entry into the Web UI. It should start or reuse the local console and print the URL:

python skills/software-project-governance/infra/verify_workflow.py web-console --governance-entry

Print the no-side-effect footer that agents should append after a task, phase, or session summary:

python skills/software-project-governance/infra/verify_workflow.py web-console --summary-link

Start it from this repository checkout:

python skills/software-project-governance/infra/verify_workflow.py web-console --start

On a first checkout, include dependency installation explicitly:

python skills/software-project-governance/infra/verify_workflow.py web-console --start --install

Then open the local URL printed by the command, usually:

http://127.0.0.1:5173/

In a CLI/client session, manual /governance starts or reuses the Web console by default so the user can keep interacting through a readable local