DevRunbook-Public/docs/20-content-governance.md

20 — Content authoring and governance

Authoring goals

A playbook should provide enough structure for reliable execution without pretending every repository is identical. It should constrain risk and evidence, not hardcode one imagined implementation.

Required author workflow

1. Define the exact outcome and non-goals.
2. Choose playbook type, work modes and autonomy range.
3. Define repository requirements.
4. Add typed inputs with safe defaults.
5. Define scope and guardrails.
6. Write ordered workflow steps.
7. Define validation roles and evidence.
8. Define completion and failure behavior.
9. Define final reporting sections.
10. Add examples and run lint.
11. Add changelog and review evidence.
12. Publish a semantic version.

Writing rules

Use explicit outcomes

Good:

Identify and remove unused production dependencies while preserving existing runtime behavior and proving that install, tests and production build still pass.

Weak:

Clean up the dependencies.

Separate observation from action

An audit playbook must not accidentally authorize changes. A plan playbook may create a plan artifact but not production code.

Define “best practices”

Replace broad phrases with dimensions such as:

• branch protection;
• test coverage of critical flows;
• dependency hygiene;
• release reproducibility;
• secret handling;
• documentation accuracy.

Avoid persona theater

Do not begin with “Act as a world-class senior engineer.” The task contract, evidence and standards matter more than roleplay.

Avoid impossible guarantees

Do not promise a full security audit, zero regressions or complete performance optimization unless the scope and evidence genuinely support it.

Do not solicit secrets

Use capability questions:

• “Is a test credential available in the environment?”

Never:

• “Paste the production API token.”

Review checklist

• Is the problem specific?
• Is the scope bounded?
• Are read and change permissions distinct?
• Are protected behaviors explicit?
• Are all inputs necessary?
• Are defaults safe?
• Does autonomy match the workflow?
• Are validations available from a repository profile?
• Does the completion contract prove the outcome?
• Does failure behavior preserve honesty?
• Is reporting useful for handoff?
• Are limitations documented?
• Do examples cover minimal and repository-aware cases?

Versioning guidance

Patch:

• typo or clarity improvement without behavioral change;
• added example;
• non-semantic documentation correction.

Minor:

• optional input;
• new compatible stack;
• stronger validation;
• additional report section;
• new conditional workflow path.

Major:

• removed or renamed input;
• widened destructive permission;
• changed meaning of autonomy;
• reduced validation requirement;
• incompatible output contract;
• changed package API version with incompatible migration.

Even patch versions create new immutable package content.

Built-in catalog governance

• every built-in package has an owner;
• changes require review;
• schema/examples/lint run in CI;
• validated status requires evidence;
• deprecation identifies migration/replacement;
• security-sensitive playbooks receive additional review;
• catalog additions must solve a distinct recurring job.

Future community governance

Before community publication:

• package signatures;
• source identity;
• moderation and reporting;
• quarantine for new publishers;
• no executable scripts by default;
• transparent fork ancestry;
• vulnerability response and revocation;
• ratings separated from quality evidence;
• license and attribution enforcement.