playbooks

home / skills / velcrafting / codex-skills / governance-sync

governance-sync skill

/skills/meta/governance-sync

This skill helps you align governance artifacts with actual changes by generating a delta checklist after milestones.

npx playbooks add skill velcrafting/codex-skills --skill governance-sync

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.3 KB
---
name: governance-sync
description: End-of-work audit that identifies which governance artifacts should be updated based on actual changes. Use when wrapping a milestone/checkpoint or after multi-file/structural work.
---
# Governance Sync

## Goal
Keep governance artifacts truthful with minimal churn.

## Non-negotiables
- Read-only. Do not edit files automatically.
- Recommend updates only when triggered by actual changes.
- Be explicit about what changed and why that forces a doc update.

## Workflow
1) Inspect what changed
- Prefer git diff/summary when available, otherwise use the user’s change summary.

2) Determine which artifacts’ truth conditions changed
Common candidates:
- Tree map (Tree.txt / tree.md)
- Roadmap (roadmap.md)
- Architecture docs (ARCHITECTURE.md)
- Agent rules (AGENTS.md)
- Decision log (DECISIONS.md)
- Review queue (REVIEW_QUEUE.md)
- Suggestions log (SUGGESTIONS.md)
- Domain docs (docs/*)

3) Output a delta checklist

## Output (follow exactly)

# Governance Sync

## Trigger summary
- Change type: <bugfix | feature | refactor | restructure | docs>
- Structural change: <yes/no>
- Decision required: <yes/no>

## Required updates
[ ] <File>: <exact update needed and why>

## Optional updates
[ ] <File>: <nice-to-have update and why>

## Risks if skipped
- <Risk 1>
- <Risk 2>

Overview

This skill performs an end-of-work governance audit to identify which governance artifacts need updates based on actual changes. It focuses on being read-only and only recommends edits when changes truly affect a document’s truth conditions. The goal is to keep governance files accurate with minimal churn and clear rationale.

How this skill works

The skill inspects change metadata—preferentially a git diff/summary, otherwise a user-provided change summary—to detect file, structural, and decision-level changes. It maps those changes to common governance artifacts (tree maps, roadmaps, architecture docs, agent rules, decision logs, review queues, suggestions, and domain docs) and generates a concise delta checklist. The output is explicit about what changed, why that triggers a recommended update, and the risk of skipping the update.

When to use it

  • After completing a milestone or checkpoint that touched multiple files or components
  • Following a structural refactor that changes hierarchy, paths, or ownership
  • When features add or remove agents, capabilities, or major behavior
  • After decisions that change policies, rules, or long-lived defaults
  • When documentation and code drift risk creating inconsistent project truths

Best practices

  • Provide or point to a git diff/summary to enable deterministic inspection
  • Be explicit: state which truth condition changed and the precise lines or examples
  • Keep recommendations read-only; never auto-edit governance artifacts
  • Distinguish mandatory updates from optional housekeeping to reduce churn
  • Record the decision rationale in a decision log entry when a doc update is required

Example use cases

  • A repo restructure moved agent folders and renamed components; run the audit to update the tree map and review queue
  • A refactor consolidated agent rules; identify required updates to the agent rules file and architecture notes
  • A feature adds a new long-lived agent; recommend additions to the roadmap, agent register, and domain docs
  • A policy change alters approval flow; flag the decision log and review queue for mandatory updates

FAQ

Will the skill change files automatically?

No. It only recommends updates and explains exactly why each recommendation is required.

What input best enables accurate recommendations?

A git diff or concise change summary showing moved, added, deleted, and modified files gives the most deterministic results.