Publish DevRunbook source

2026-09-03 04:09:17 +02:00
commit cfd2804e27
928 changed files with 161642 additions and 0 deletions
@@ -0,0 +1,132 @@
+# 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.