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,111 @@
+# 02 — Personas and jobs-to-be-done
+
+## Persona A — Independent builder
+
+Uses Codex for personal products, prototypes and self-hosted tools. Has several repositories with different stacks and repeatedly copies long instructions.
+
+Jobs:
+
+- “When I start a recurring development task, give me a proven structure so I do not forget validation or safety constraints.”
+- “When I return to an older repository, reuse its real commands and conventions.”
+- “When I ask Codex to work autonomously, show exactly what autonomy I am granting.”
+
+Pain points:
+
+- scattered prompts in notes and prior chats;
+- prompts become stale when a repository changes;
+- inconsistent results between projects;
+- lack of evidence that Codex actually validated the change.
+
+## Persona B — Infrastructure and operations engineer
+
+Works across scripts, containers, automation, M365 tooling, internal portals and operational repositories. Values safe, reversible work and clear support handoffs.
+
+Jobs:
+
+- generate audits that separate observations from recommendations;
+- prepare cleanup or hardening tasks without breaking deployments;
+- standardize backup, restore, logging and release checks;
+- produce a clear final report suitable for future troubleshooting.
+
+## Persona C — Engineering lead or reviewer
+
+Wants team members and agents to use consistent standards without maintaining one giant global prompt.
+
+Jobs:
+
+- publish reviewed playbooks;
+- enforce validation and reporting requirements;
+- compare versions and review changes;
+- know which playbook and repository context produced a task;
+- prevent unsafe community content from appearing trusted.
+
+## Persona D — Playbook author
+
+Creates and maintains reusable workflows for particular technologies or task types.
+
+Jobs:
+
+- define typed inputs and conditional blocks;
+- preview output with representative profiles;
+- lint ambiguity and missing controls;
+- attach evaluation cases and changelogs;
+- publish a new version without mutating previous runs.
+
+## Persona E — Self-hosted platform operator
+
+Deploys DevRunbook on Docker or Unraid and manages storage, backups, upgrades and integrations.
+
+Jobs:
+
+- deploy from a documented compose configuration;
+- keep secrets out of logs and backups where appropriate;
+- see failed jobs and integration health;
+- back up and restore the platform;
+- upgrade with reversible migrations.
+
+## Key usage scenarios
+
+### Scenario 1 — Audit a repository without changing it
+
+1. User searches for “repository health”.
+2. Selects the read-only audit playbook.
+3. Selects a repository profile.
+4. Chooses Observe autonomy.
+5. Reviews detected stack, scope and exclusions.
+6. Exports a prompt requiring an evidence-based report and no changes.
+
+### Scenario 2 — Fix a reproducible bug
+
+1. User selects Root-Cause Bug Fix.
+2. Provides the symptom and any error text.
+3. Selects Verify autonomy.
+4. Composer requires reproduction, regression test and relevant test commands.
+5. Generated task forbids deleting behavior or weakening tests.
+6. Run history preserves the exact task.
+
+### Scenario 3 — Build a new feature autonomously
+
+1. User selects a feature implementation playbook.
+2. Adds functional requirements and explicit exclusions.
+3. Chooses a repository profile.
+4. Defines permitted modules and protected paths.
+5. Selects Repair autonomy.
+6. Exports a Run Pack with specification, workflow, validation and handoff files.
+
+### Scenario 4 — Inspect Gitea governance
+
+1. Operator connects Gitea using a read-only token.
+2. Selects a repository.
+3. DevRunbook snapshots branch protection, default branch, templates, release and workflow evidence where supported.
+4. The workspace shows gaps with source evidence.
+5. User launches the matching Gitea Best Practices playbook.
+
+### Scenario 5 — Author and validate a private playbook
+
+1. Author creates a draft from a template.
+2. Adds typed inputs and conditional validation rules.
+3. Prompt Lab renders several examples.
+4. Linter finds ambiguous scope and missing failure behavior.
+5. Author corrects the package and adds a changelog.
+6. Reviewer publishes version 1.0.0.