AgentSkillsCN

project-governance

创建并维护项目章程、代理指令文件（CLAUDE.md、AGENTS.md、.cursorrules），以及RFC/ADR文档。在制定编码标准、添加项目规则、创建代理指导文件、在各代理间同步规则、提出架构决策、创建RFC、审查RFC，或提升AI代理的一致性时使用此功能。

SKILL.md
--- frontmatter
name: project-governance
description: >-
  Create and maintain project constitutions, agent instruction files
  (CLAUDE.md, AGENTS.md, .cursorrules), and RFC/ADR documents. Use when
  establishing coding standards, adding project rules, creating agent guidance
  files, syncing rules across agents, proposing architectural decisions,
  creating RFCs, reviewing RFCs, or improving AI agent consistency.
allowed-tools: Bash, Read, Edit, Write
user-invocable: true

Project Governance

Create, modify, and maintain project constitutions, agent instruction files, and RFC/ADR documents that guide AI agents and formalize technical decisions.

Quick Start

Create a constitution

bash
# Analyze the project, then create oak/constitution.md
# See references/constitution-guide.md for the full process

Create an RFC

bash
{oak-cli-command} rfc create --title "Add caching layer" --template feature
{oak-cli-command} rfc list
{oak-cli-command} rfc validate oak/rfc/RFC-001-add-caching-layer.md

Sync agent instruction files

bash
{oak-cli-command} rules sync-agents          # Sync constitution references to all agent files
{oak-cli-command} rules detect-existing      # Discover all configured agent instruction files

Commands Reference

Rules commands

CommandPurpose
{oak-cli-command} rules sync-agentsSync constitution references to all agent instruction files
{oak-cli-command} rules sync-agents --dry-runPreview what files will be checked/updated
{oak-cli-command} rules detect-existingDiscover all configured agent instruction files
{oak-cli-command} rules detect-existing --jsonMachine-readable output of agent files

RFC commands

CommandPurpose
{oak-cli-command} rfc create --title "..." --template <type>Create a new RFC
{oak-cli-command} rfc listList all RFCs
{oak-cli-command} rfc validate <path>Validate RFC structure and content
{oak-cli-command} rfc show <path>Show RFC details
{oak-cli-command} rfc adopt <path>Mark RFC as adopted
{oak-cli-command} rfc abandon <path> --reason "..."Mark RFC as abandoned

When to Use

  • •Creating a new constitution for a project that doesn't have one
  • •Adding rules when you identify patterns that should be standardized
  • •Syncing agent files after constitution changes
  • •Creating CLAUDE.md, AGENTS.md, or .cursorrules for a new project
  • •Proposing a new feature that needs team review (RFC)
  • •Making architectural decisions that should be documented (ADR)
  • •Reviewing an RFC for completeness and technical soundness

Constitution Structure

A good constitution is explicit, enforceable, and anchored:

QualityGoodBad
Specificity"All API endpoints MUST validate input using Pydantic models""Use best practices"
Anchors"Copy src/features/auth/service.py for new services""Follow good patterns"
Non-goals"This tool is NOT a CI/CD orchestrator"(no boundaries)
Gates"make check must pass for all changes""Add tests if needed"

Required sections: Metadata, Scope and Non-Goals, Golden Paths with Anchor Index, Architecture Invariants, No-Magic-Literals, CLI Behavior, Quality Gates. See references/constitution-guide.md for the full structure and creation process.

RFC Templates

TemplateUse For
featureNew features, capabilities
architectureSystem architecture changes
engineeringDevelopment practices, tooling
processTeam processes, workflows

Key Workflows

Adding a rule to an existing constitution

  1. •Read the current constitution (oak/constitution.md)
  2. •Add the full rule to the appropriate section using RFC 2119 language (MUST, SHOULD, MAY)
  3. •Sync to all agent files: {oak-cli-command} rules sync-agents

CRITICAL: Rules MUST be added to the constitution FIRST, then synced to agent files. Never add a rule only to an agent file.

RFC lifecycle

  1. •Create: {oak-cli-command} rfc create --title "..." --template feature --author "Name"
  2. •Fill in: Problem context, proposed solution, trade-offs, alternatives
  3. •Review: Use the review checklist (see references/reviewing-rfcs.md)
  4. •Adopt or abandon: {oak-cli-command} rfc adopt <path> or {oak-cli-command} rfc abandon <path> --reason "..."

RFC review checklist (summary)

  • •Structure: Clear title, correct status, all required sections
  • •Context: Problem clearly stated, "why now?" addressed, scope defined
  • •Decision: Solution clear, technical approach explained
  • •Consequences: Positive/negative outcomes listed, mitigations proposed
  • •Alternatives: Other options considered, reasons for rejection explained

Common Anti-Patterns

Anti-PatternProblemFix
"Use best practices"Not enforceableSpecify the practice
"When possible"Loophole generatorDefine when it's required
No anchorsAgents freestylePoint to specific files
No non-goalsScope creepExplicitly exclude things
"Add tests if needed"Permission to skipDefine coverage requirements
"Make reasonable assumptions"Inconsistent patternsSay "ask if uncertain"

Files

  • •Constitution: oak/constitution.md or .constitution.md
  • •Agent files: Run {oak-cli-command} rules detect-existing to discover all agent instruction files
  • •RFCs: oak/rfc/RFC-XXX-short-title.md

Deep Dives

For detailed guidance, consult the reference documents:

  • •references/constitution-guide.md — Full constitution creation process and structure
  • •references/constitution-good-example.md — Complete example of a well-structured constitution
  • •references/constitution-bad-example.md — Anti-patterns to avoid
  • •references/agent-files-guide.md — Creating and syncing agent instruction files
  • •references/agent-file-good-example.md — Well-structured agent file example
  • •references/agent-file-bad-example.md — Poorly structured agent file example
  • •references/creating-rfcs.md — Detailed RFC creation workflow
  • •references/reviewing-rfcs.md — RFC review checklist and feedback format