AI Project Governance

AI Project Governance is a Codex skill that establishes a compact, durable navigation layer for software repositories.

It is designed for new projects and half-built repositories whose requirements, architecture, operations, and historical material are difficult for future agents to distinguish. The skill creates or repairs the governance layer once; the generated AGENTS.md and docs/task-routing.md tell later agents when documentation must change during feature work and refactoring.

What It Establishes

The minimum layer is:

AGENTS.md
docs/
  README.md
  project-map.md
  document-taxonomy.md
  task-routing.md

Architecture, feature, decision, runbook, archive, and project-local skill documents are created only when real content needs an owner.

Installation

Copy the skill into your Codex skills directory:

mkdir -p ~/.codex/skills
cp -R skills/ai-project-governance ~/.codex/skills/

Use

Invoke one skill and describe the outcome:

$ai-project-governance
Audit this half-built repository and establish the smallest durable governance layer. Preserve existing facts and do not overwrite current files.

The skill first inventories the repository and reports gaps. It remains read-only when the user asks only for an audit. When changes are authorized, it patches existing owners or uses the bundled scaffold for a missing core layer.

Deterministic Scaffold

The scaffold is conservative and intentionally produces explicit placeholders where repository evidence is required:

python skills/ai-project-governance/scripts/scaffold_governance.py \
  --target /path/to/project \
  --project-name "Project Name" \
  --profile application \
  --risk production-impact

Default behavior:

• Missing core files are created.
• Existing files receive .proposed siblings.
• Existing files are overwritten only with --overwrite-existing --yes.
• Optional decision, runbook, archive, and skill indexes are created only with --with-supporting-indexes.

Use --dry-run to inspect the write plan.

Validation

After replacing scaffold placeholders with verified project facts, run:

python skills/ai-project-governance/scripts/validate_governance.py \
  --target /path/to/project \
  --strict

Validation checks the core reading path, local links, placeholders, likely secrets, machine-local paths, the documentation-maintenance contract, and project-local skill frontmatter.

Repository Layout

skills/ai-project-governance/
  SKILL.md
  agents/
  assets/
  references/
  scripts/
tests/

Supported Profiles

generic, application, service, frontend, data, research, library, cli, and monorepo.

Supported Risk Flags

external-side-effects, destructive-ops, sensitive-data, production-impact, and cost-impact.

These flags seed conservative defaults. The final governance layer must still describe the repository's actual safety boundaries.

License

MIT