133 lines
3.6 KiB
Markdown
133 lines
3.6 KiB
Markdown
# 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.
|