This commit is contained in:
DevRunbook release export
@@ -0,0 +1,5 @@
|
||||
# Changelog
|
||||
|
||||
## 1.0.0
|
||||
|
||||
- Initial reviewed example package for **Implement a Feature from a Functional Specification**.
|
||||
@@ -0,0 +1,5 @@
|
||||
# Implement a Feature from a Functional Specification
|
||||
|
||||
Translate bounded requirements into architecture-aware code, tests, documentation and verified user behavior.
|
||||
|
||||
This package is a normative DevRunbook example. Validate it against `schemas/playbook.schema.json`.
|
||||
@@ -0,0 +1,23 @@
|
||||
apiVersion: devrunbook.io/v1alpha1
|
||||
kind: EvaluationCase
|
||||
metadata:
|
||||
id: feature-from-spec.static-structure
|
||||
version: 1.0.0
|
||||
spec:
|
||||
playbookVersion: 1.0.0
|
||||
inputFile: ../examples/minimal.yaml
|
||||
expectedHeadings:
|
||||
- Mission
|
||||
- Scope
|
||||
- Constraints and guardrails
|
||||
- Execution workflow
|
||||
- Validation plan
|
||||
- Completion contract
|
||||
- Final reporting format
|
||||
prohibitedPatterns:
|
||||
- BEGIN PRIVATE KEY
|
||||
- 'Authorization: Bearer'
|
||||
deterministic: true
|
||||
requiredPatterns:
|
||||
- Implement a Feature from a Functional Specification
|
||||
expectedLintStatus: ready
|
||||
@@ -0,0 +1,12 @@
|
||||
playbook:
|
||||
slug: feature-from-spec
|
||||
version: 1.0.0
|
||||
workMode: plan
|
||||
autonomyLevel: repair
|
||||
inputs:
|
||||
functionalRequirements: Example value for Functional requirements
|
||||
acceptanceCriteria:
|
||||
- example
|
||||
nonGoals: []
|
||||
targetUsers: ''
|
||||
migrationRequired: false
|
||||
@@ -0,0 +1,277 @@
|
||||
apiVersion: devrunbook.io/v1alpha1
|
||||
kind: Playbook
|
||||
metadata:
|
||||
id: feature.from-spec
|
||||
slug: feature-from-spec
|
||||
version: 1.0.0
|
||||
title: Implement a Feature from a Functional Specification
|
||||
summary: Translate bounded requirements into architecture-aware code, tests, documentation and verified user behavior.
|
||||
category: feature-implementation
|
||||
tags:
|
||||
- feature
|
||||
- implementation
|
||||
- specification
|
||||
lifecycle: reviewed
|
||||
riskTier: moderate
|
||||
authors:
|
||||
- name: DevRunbook Core Team
|
||||
license: MIT
|
||||
package:
|
||||
files:
|
||||
- path: prompt.md
|
||||
role: template
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: README.md
|
||||
role: documentation
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: CHANGELOG.md
|
||||
role: changelog
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: examples/minimal.yaml
|
||||
role: example
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: evaluations/static-structure.yaml
|
||||
role: evaluation
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
spec:
|
||||
type: run-pack
|
||||
intent:
|
||||
problem: Feature work fails when functional expectations, non-goals, repository constraints and validation are mixed into
|
||||
an informal request.
|
||||
outcome: Implement a bounded feature from explicit requirements, integrate it with existing architecture, validate critical
|
||||
flows and produce a precise handoff.
|
||||
whenToUse:
|
||||
- A feature has clear functional requirements and acceptance criteria.
|
||||
- The repository has enough setup and validation information for implementation.
|
||||
whenNotToUse:
|
||||
- The request is still exploratory and lacks a stable desired outcome.
|
||||
- The feature requires unavailable production credentials or irreversible business decisions.
|
||||
modes:
|
||||
- plan
|
||||
- guided
|
||||
- execute
|
||||
defaultMode: execute
|
||||
autonomy:
|
||||
min: plan
|
||||
max: repair
|
||||
default: repair
|
||||
inputs:
|
||||
- key: functionalRequirements
|
||||
label: Functional requirements
|
||||
description: Describe the required user-visible and system behavior.
|
||||
type: multiline
|
||||
required: true
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
- key: acceptanceCriteria
|
||||
label: Acceptance criteria
|
||||
description: List observable criteria that prove the feature is complete.
|
||||
type: string-list
|
||||
required: true
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
- key: nonGoals
|
||||
label: Non-goals
|
||||
description: List behaviors and adjacent ideas explicitly outside this task.
|
||||
type: string-list
|
||||
required: false
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
default: []
|
||||
- key: targetUsers
|
||||
label: Target users
|
||||
description: Describe who uses the feature and any relevant permission differences.
|
||||
type: multiline
|
||||
required: false
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
default: ''
|
||||
- key: migrationRequired
|
||||
label: Migration may be required
|
||||
description: Indicate whether persisted data or configuration may need migration.
|
||||
type: boolean
|
||||
required: true
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
default: false
|
||||
compatibility:
|
||||
repositoryRequired: true
|
||||
languages: []
|
||||
frameworks: []
|
||||
packageManagers: []
|
||||
databases: []
|
||||
deploymentTypes: []
|
||||
requiredProfileCapabilities: []
|
||||
incompatibleConditions: []
|
||||
guardrails:
|
||||
- id: requirements-contract
|
||||
severity: blocking
|
||||
text: Implement the stated acceptance criteria and do not silently expand into non-goals.
|
||||
- id: architecture-fit
|
||||
severity: blocking
|
||||
text: Inspect and follow existing architecture, naming, data and error conventions before introducing new patterns.
|
||||
- id: backwards-compatible
|
||||
severity: blocking
|
||||
text: Preserve existing public behavior and persisted data unless an acceptance criterion explicitly changes it.
|
||||
- id: migration-safety
|
||||
severity: blocking
|
||||
text: Any migration must include compatibility, backup/rollback and validation behavior.
|
||||
when:
|
||||
fact:
|
||||
path: inputs.migrationRequired
|
||||
operator: eq
|
||||
value: true
|
||||
- id: no-placeholder-production
|
||||
severity: blocking
|
||||
text: Do not leave hidden mock data, TODO-only behavior or unsafe production fallbacks.
|
||||
workflow:
|
||||
- id: recon
|
||||
title: Understand existing system
|
||||
instruction: Read repository instructions, architecture, adjacent features, data model, authorization and validation commands.
|
||||
required: true
|
||||
- id: design
|
||||
title: Create implementation design
|
||||
instruction: Map each acceptance criterion to components, data/API changes, tests and migration impact. Record material
|
||||
decisions.
|
||||
required: true
|
||||
- id: vertical-slice
|
||||
title: Implement a vertical slice
|
||||
instruction: Build the smallest complete path through UI/API/domain/persistence as applicable before broad polish.
|
||||
required: true
|
||||
- id: complete-behavior
|
||||
title: Complete functional behavior
|
||||
instruction: Implement remaining states, validation, authorization, errors, empty/loading states and documentation.
|
||||
required: true
|
||||
- id: tests
|
||||
title: Add layered tests
|
||||
instruction: Add unit, integration and browser tests appropriate to the feature risk and critical flow.
|
||||
required: true
|
||||
- id: migration
|
||||
title: Implement safe migration
|
||||
instruction: Use reversible or staged migration behavior and validate existing data.
|
||||
required: true
|
||||
when:
|
||||
fact:
|
||||
path: inputs.migrationRequired
|
||||
operator: eq
|
||||
value: true
|
||||
- id: full-validation
|
||||
title: Run full validation
|
||||
instruction: Run all repository-required validation and focused manual/browser verification.
|
||||
required: true
|
||||
- id: handoff
|
||||
title: Prepare handoff
|
||||
instruction: Map delivered behavior to acceptance criteria and state limitations and follow-up.
|
||||
required: true
|
||||
validation:
|
||||
commandRoles:
|
||||
- lint
|
||||
- typecheck
|
||||
- unit-test
|
||||
- integration-test
|
||||
- end-to-end-test
|
||||
- build
|
||||
- smoke-test
|
||||
checks:
|
||||
- id: criteria-map
|
||||
type: artifact
|
||||
description: Every acceptance criterion maps to implementation and evidence.
|
||||
blocking: true
|
||||
evidence: Acceptance matrix.
|
||||
- id: tests
|
||||
type: command
|
||||
description: Relevant automated tests pass.
|
||||
blocking: true
|
||||
evidence: Command results.
|
||||
- id: build
|
||||
type: command
|
||||
description: Production build passes when the profile provides it.
|
||||
blocking: true
|
||||
evidence: Build result.
|
||||
- id: browser
|
||||
type: manual
|
||||
description: Critical user flow is verified in the running application when applicable.
|
||||
blocking: true
|
||||
evidence: Browser verification notes.
|
||||
- id: migration
|
||||
type: artifact
|
||||
description: Migration, rollback and existing-data validation are evidenced.
|
||||
blocking: true
|
||||
evidence: Migration report.
|
||||
when:
|
||||
fact:
|
||||
path: inputs.migrationRequired
|
||||
operator: eq
|
||||
value: true
|
||||
- id: diff
|
||||
type: assertion
|
||||
description: No unexplained non-goal work is included.
|
||||
blocking: true
|
||||
evidence: Final diff review.
|
||||
completion:
|
||||
criteria:
|
||||
- Every stated acceptance criterion is implemented and evidenced.
|
||||
- Non-goals remain outside scope.
|
||||
- Existing behavior and data remain compatible or the intended change is documented.
|
||||
- Relevant tests, build and critical user-flow validation pass.
|
||||
- Documentation and final handoff accurately describe the feature.
|
||||
failurePolicy:
|
||||
onValidationFailure: Investigate failures caused by the current work, repair them when they remain within scope, rerun
|
||||
the affected validation and report any genuine blocker without claiming success.
|
||||
onAmbiguity: Use repository evidence and existing conventions for minor choices. For material product ambiguity, preserve
|
||||
current behavior, document the decision needed and stop before an irreversible change.
|
||||
onMissingContext: Inspect the repository for the missing non-sensitive context. Never invent commands, credentials, production
|
||||
behavior or validation results. Report what remains unavailable.
|
||||
onOutOfScopeCause: Explain the evidenced out-of-scope cause, avoid broad unrelated changes and provide the smallest safe
|
||||
follow-up recommendation.
|
||||
onExternalDependencyUnavailable: Use a safe local fixture only when it preserves the behavior under test. Otherwise report
|
||||
the blocked validation and do not claim the external path succeeded.
|
||||
onUnableToReproduce: Record attempted reproduction and environment evidence. Do not make speculative production changes;
|
||||
provide the narrowest next diagnostic action.
|
||||
reporting:
|
||||
sections:
|
||||
- id: outcome
|
||||
title: Delivered outcome
|
||||
required: true
|
||||
description: Concise summary of the implemented user and system behavior.
|
||||
- id: criteria
|
||||
title: Acceptance-criteria matrix
|
||||
required: true
|
||||
description: Each criterion with implementation location and evidence.
|
||||
- id: changes
|
||||
title: Architecture and changed files
|
||||
required: true
|
||||
description: Important design choices and changed modules.
|
||||
- id: validation
|
||||
title: Validation
|
||||
required: true
|
||||
description: Automated and manual checks with results.
|
||||
- id: migration
|
||||
title: Migration and compatibility
|
||||
required: false
|
||||
description: Data/configuration migration and rollback information.
|
||||
- id: limitations
|
||||
title: Limitations and follow-up
|
||||
required: true
|
||||
description: Known limitations, deferred non-goals and recommended next work.
|
||||
template:
|
||||
main: prompt.md
|
||||
partials: []
|
||||
exports:
|
||||
prompt: true
|
||||
markdown: true
|
||||
runPack: true
|
||||
agentsSuggestion: true
|
||||
quality:
|
||||
reviewStatus: technical-reviewed
|
||||
testedStacks: []
|
||||
knownLimitations:
|
||||
- A specification cannot resolve missing product decisions that materially alter data ownership, permissions or irreversible
|
||||
behavior.
|
||||
evaluationCaseIds:
|
||||
- feature-from-spec.static-structure
|
||||
@@ -0,0 +1,21 @@
|
||||
# Feature implementation instructions
|
||||
|
||||
## Functional requirements
|
||||
|
||||
{{ inputs.functionalRequirements }}
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
{{ inputs.acceptanceCriteria }}
|
||||
|
||||
## Explicit non-goals
|
||||
|
||||
{{ inputs.nonGoals }}
|
||||
|
||||
## Target users
|
||||
|
||||
{{ inputs.targetUsers }}
|
||||
|
||||
Migration may be required: {{ inputs.migrationRequired }}.
|
||||
|
||||
Start with a concise implementation map but continue autonomously through implementation and verification at the selected autonomy level. Preserve the existing product language and design system while improving incomplete states needed by the feature. The final report must use an acceptance-criteria matrix rather than a generic summary.
|
||||
@@ -0,0 +1,5 @@
|
||||
# Changelog
|
||||
|
||||
## 1.0.0
|
||||
|
||||
- Initial reviewed example package for **Gitea Repository Best-Practices Audit**.
|
||||
@@ -0,0 +1,5 @@
|
||||
# Gitea Repository Best-Practices Audit
|
||||
|
||||
Review metadata, branch and tag protection, templates, Actions and releases without changing Gitea.
|
||||
|
||||
This package is a normative DevRunbook example. Validate it against `schemas/playbook.schema.json`.
|
||||
@@ -0,0 +1,23 @@
|
||||
apiVersion: devrunbook.io/v1alpha1
|
||||
kind: EvaluationCase
|
||||
metadata:
|
||||
id: gitea-best-practices.static-structure
|
||||
version: 1.0.0
|
||||
spec:
|
||||
playbookVersion: 1.0.0
|
||||
inputFile: ../examples/minimal.yaml
|
||||
expectedHeadings:
|
||||
- Mission
|
||||
- Scope
|
||||
- Constraints and guardrails
|
||||
- Execution workflow
|
||||
- Validation plan
|
||||
- Completion contract
|
||||
- Final reporting format
|
||||
prohibitedPatterns:
|
||||
- BEGIN PRIVATE KEY
|
||||
- 'Authorization: Bearer'
|
||||
deterministic: true
|
||||
requiredPatterns:
|
||||
- Gitea Repository Best-Practices Audit
|
||||
expectedLintStatus: ready
|
||||
@@ -0,0 +1,13 @@
|
||||
playbook:
|
||||
slug: gitea-best-practices
|
||||
version: 1.0.0
|
||||
workMode: inspect
|
||||
autonomyLevel: diagnose
|
||||
inputs:
|
||||
governanceDepth:
|
||||
- branches
|
||||
- templates
|
||||
- actions
|
||||
- releases
|
||||
teamWorkflow: ''
|
||||
publicRepository: false
|
||||
@@ -0,0 +1,226 @@
|
||||
apiVersion: devrunbook.io/v1alpha1
|
||||
kind: Playbook
|
||||
metadata:
|
||||
id: forge.gitea-best-practices
|
||||
slug: gitea-best-practices
|
||||
version: 1.0.0
|
||||
title: Gitea Repository Best-Practices Audit
|
||||
summary: Review metadata, branch and tag protection, templates, Actions and releases without changing Gitea.
|
||||
category: git-gitea
|
||||
tags:
|
||||
- gitea
|
||||
- git
|
||||
- governance
|
||||
lifecycle: reviewed
|
||||
riskTier: moderate
|
||||
authors:
|
||||
- name: DevRunbook Core Team
|
||||
license: MIT
|
||||
package:
|
||||
files:
|
||||
- path: prompt.md
|
||||
role: template
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: README.md
|
||||
role: documentation
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: CHANGELOG.md
|
||||
role: changelog
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: examples/minimal.yaml
|
||||
role: example
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: evaluations/static-structure.yaml
|
||||
role: evaluation
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
spec:
|
||||
type: guided
|
||||
intent:
|
||||
problem: A Gitea repository can function while lacking governance, templates, protected branches, reproducible workflows
|
||||
or accurate release metadata.
|
||||
outcome: Produce an evidence-based read-only review of Gitea repository governance and a prioritized configuration plan.
|
||||
whenToUse:
|
||||
- When onboarding a repository to Gitea.
|
||||
- Before expanding collaboration or release automation.
|
||||
- When settings have grown organically.
|
||||
whenNotToUse:
|
||||
- When the task requires changing Gitea settings immediately.
|
||||
- When the token cannot read enough metadata for a meaningful review.
|
||||
modes:
|
||||
- inspect
|
||||
- plan
|
||||
defaultMode: inspect
|
||||
autonomy:
|
||||
min: observe
|
||||
max: plan
|
||||
default: diagnose
|
||||
inputs:
|
||||
- key: governanceDepth
|
||||
label: Governance depth
|
||||
description: Select which governance areas to inspect.
|
||||
type: multiselect
|
||||
required: true
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
default:
|
||||
- branches
|
||||
- templates
|
||||
- actions
|
||||
- releases
|
||||
options:
|
||||
- metadata
|
||||
- branches
|
||||
- tags
|
||||
- permissions
|
||||
- templates
|
||||
- actions
|
||||
- releases
|
||||
- backup-mirroring
|
||||
- key: teamWorkflow
|
||||
label: Team workflow
|
||||
description: Describe how changes are normally proposed and approved.
|
||||
type: multiline
|
||||
required: false
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
default: ''
|
||||
- key: publicRepository
|
||||
label: Public repository
|
||||
description: Indicate whether public contribution and disclosure concerns apply.
|
||||
type: boolean
|
||||
required: true
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
default: false
|
||||
compatibility:
|
||||
repositoryRequired: true
|
||||
languages: []
|
||||
frameworks: []
|
||||
packageManagers: []
|
||||
databases: []
|
||||
deploymentTypes: []
|
||||
requiredProfileCapabilities: []
|
||||
incompatibleConditions: []
|
||||
guardrails:
|
||||
- id: read-only
|
||||
severity: blocking
|
||||
text: Do not create or change repository settings, branches, tags, issues, actions, secrets or releases.
|
||||
- id: capability-aware
|
||||
severity: blocking
|
||||
text: State when a finding is limited by Gitea version, token permission or unavailable API capability.
|
||||
- id: least-privilege
|
||||
severity: blocking
|
||||
text: Do not recommend admin-level access when repository-level read or write permissions are sufficient.
|
||||
- id: no-secret-content
|
||||
severity: blocking
|
||||
text: Do not read or report secret values from Actions or configuration.
|
||||
workflow:
|
||||
- id: capabilities
|
||||
title: Establish capabilities
|
||||
instruction: Record Gitea version, visible repository permissions and available evidence sources.
|
||||
required: true
|
||||
- id: metadata
|
||||
title: Review repository identity
|
||||
instruction: Review default branch, description, topics, license, README and archival state where selected.
|
||||
required: true
|
||||
- id: governance
|
||||
title: Review branch and tag governance
|
||||
instruction: Assess protection, direct push, review, status checks and release-tag controls where visible.
|
||||
required: true
|
||||
- id: workflow
|
||||
title: Review collaboration workflow
|
||||
instruction: Assess issue/PR templates, labels, contribution guidance and the stated team workflow.
|
||||
required: true
|
||||
- id: actions
|
||||
title: Review automation evidence
|
||||
instruction: Inspect visible workflow definitions, triggers, permissions and runner assumptions without exposing secrets.
|
||||
required: true
|
||||
- id: release
|
||||
title: Review release process
|
||||
instruction: Assess tags, releases, changelog, artifacts and rollback communication.
|
||||
required: true
|
||||
- id: plan
|
||||
title: Produce prioritized plan
|
||||
instruction: Separate settings changes, repository-file changes and optional future improvements.
|
||||
required: true
|
||||
validation:
|
||||
commandRoles: []
|
||||
checks:
|
||||
- id: no-writes
|
||||
type: assertion
|
||||
description: No Gitea write endpoint or repository modification was performed.
|
||||
blocking: true
|
||||
evidence: Integration request log or task report.
|
||||
- id: permission-limits
|
||||
type: artifact
|
||||
description: Unavailable or forbidden capabilities are listed.
|
||||
blocking: true
|
||||
evidence: Limitations section.
|
||||
- id: evidence
|
||||
type: artifact
|
||||
description: Each medium/high finding cites Gitea or repository evidence.
|
||||
blocking: true
|
||||
evidence: Finding table.
|
||||
- id: plan-separation
|
||||
type: artifact
|
||||
description: Recommendations distinguish Gitea settings from repository file changes.
|
||||
blocking: true
|
||||
evidence: Action plan.
|
||||
completion:
|
||||
criteria:
|
||||
- No Gitea or repository state was changed.
|
||||
- Governance findings include evidence and capability limitations.
|
||||
- Recommended settings fit the stated team workflow rather than generic policy.
|
||||
- A staged action plan identifies risk and required permission.
|
||||
failurePolicy:
|
||||
onValidationFailure: Investigate failures caused by the current work, repair them when they remain within scope, rerun
|
||||
the affected validation and report any genuine blocker without claiming success.
|
||||
onAmbiguity: Use repository evidence and existing conventions for minor choices. For material product ambiguity, preserve
|
||||
current behavior, document the decision needed and stop before an irreversible change.
|
||||
onMissingContext: Inspect the repository for the missing non-sensitive context. Never invent commands, credentials, production
|
||||
behavior or validation results. Report what remains unavailable.
|
||||
onOutOfScopeCause: Explain the evidenced out-of-scope cause, avoid broad unrelated changes and provide the smallest safe
|
||||
follow-up recommendation.
|
||||
onExternalDependencyUnavailable: Use a safe local fixture only when it preserves the behavior under test. Otherwise report
|
||||
the blocked validation and do not claim the external path succeeded.
|
||||
onUnableToReproduce: Record attempted reproduction and environment evidence. Do not make speculative production changes;
|
||||
provide the narrowest next diagnostic action.
|
||||
reporting:
|
||||
sections:
|
||||
- id: context
|
||||
title: Repository and capability context
|
||||
required: true
|
||||
description: Gitea version, visible permissions and workflow assumptions.
|
||||
- id: findings
|
||||
title: Governance findings
|
||||
required: true
|
||||
description: Evidence-based findings by metadata, branch/tag policy, collaboration, Actions and releases.
|
||||
- id: plan
|
||||
title: Prioritized implementation plan
|
||||
required: true
|
||||
description: Staged actions, required permissions and suggested playbooks.
|
||||
- id: limitations
|
||||
title: Limitations
|
||||
required: true
|
||||
description: Unavailable APIs, permission constraints and unverified settings.
|
||||
template:
|
||||
main: prompt.md
|
||||
partials: []
|
||||
exports:
|
||||
prompt: true
|
||||
markdown: true
|
||||
runPack: true
|
||||
agentsSuggestion: true
|
||||
quality:
|
||||
reviewStatus: technical-reviewed
|
||||
testedStacks: []
|
||||
knownLimitations:
|
||||
- Open-source and Enterprise editions can expose different governance capabilities.
|
||||
- API visibility may not reflect settings the token cannot access.
|
||||
evaluationCaseIds:
|
||||
- gitea-best-practices.static-structure
|
||||
@@ -0,0 +1,9 @@
|
||||
# Gitea repository governance instructions
|
||||
|
||||
Review these areas: {{ inputs.governanceDepth }}.
|
||||
Public repository: {{ inputs.publicRepository }}.
|
||||
Known team workflow:
|
||||
|
||||
{{ inputs.teamWorkflow }}
|
||||
|
||||
Use connected Gitea evidence only through the read-only adapter. For every recommendation, state whether it is a Gitea setting, a repository-file change or an organizational process change. Avoid enterprise-only assumptions unless the connected capability evidence confirms them.
|
||||
@@ -0,0 +1,5 @@
|
||||
# Changelog
|
||||
|
||||
## 1.0.0
|
||||
|
||||
- Initial reviewed example package for **Production Readiness Audit**.
|
||||
@@ -0,0 +1,5 @@
|
||||
# Production Readiness Audit
|
||||
|
||||
Evaluate deployability, security, migrations, recovery, monitoring, documentation and release evidence.
|
||||
|
||||
This package is a normative DevRunbook example. Validate it against `schemas/playbook.schema.json`.
|
||||
@@ -0,0 +1,23 @@
|
||||
apiVersion: devrunbook.io/v1alpha1
|
||||
kind: EvaluationCase
|
||||
metadata:
|
||||
id: production-readiness-audit.static-structure
|
||||
version: 1.0.0
|
||||
spec:
|
||||
playbookVersion: 1.0.0
|
||||
inputFile: ../examples/minimal.yaml
|
||||
expectedHeadings:
|
||||
- Mission
|
||||
- Scope
|
||||
- Constraints and guardrails
|
||||
- Execution workflow
|
||||
- Validation plan
|
||||
- Completion contract
|
||||
- Final reporting format
|
||||
prohibitedPatterns:
|
||||
- BEGIN PRIVATE KEY
|
||||
- 'Authorization: Bearer'
|
||||
deterministic: true
|
||||
requiredPatterns:
|
||||
- Production Readiness Audit
|
||||
expectedLintStatus: ready
|
||||
@@ -0,0 +1,18 @@
|
||||
playbook:
|
||||
slug: production-readiness-audit
|
||||
version: 1.0.0
|
||||
workMode: inspect
|
||||
autonomyLevel: plan
|
||||
inputs:
|
||||
targetEnvironment: Example value for Target environment
|
||||
releaseCandidate: Example value for Release candidate
|
||||
requiredDimensions:
|
||||
- build
|
||||
- tests
|
||||
- security
|
||||
- deployment
|
||||
- migrations
|
||||
- backup-restore
|
||||
- observability
|
||||
- documentation
|
||||
riskTolerance: conservative
|
||||
@@ -0,0 +1,268 @@
|
||||
apiVersion: devrunbook.io/v1alpha1
|
||||
kind: Playbook
|
||||
metadata:
|
||||
id: release.production-readiness
|
||||
slug: production-readiness-audit
|
||||
version: 1.0.0
|
||||
title: Production Readiness Audit
|
||||
summary: Evaluate deployability, security, migrations, recovery, monitoring, documentation and release evidence.
|
||||
category: audits
|
||||
tags:
|
||||
- production
|
||||
- readiness
|
||||
- release
|
||||
lifecycle: reviewed
|
||||
riskTier: high
|
||||
authors:
|
||||
- name: DevRunbook Core Team
|
||||
license: MIT
|
||||
package:
|
||||
files:
|
||||
- path: prompt.md
|
||||
role: template
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: README.md
|
||||
role: documentation
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: CHANGELOG.md
|
||||
role: changelog
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: examples/minimal.yaml
|
||||
role: example
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: evaluations/static-structure.yaml
|
||||
role: evaluation
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
spec:
|
||||
type: run-pack
|
||||
intent:
|
||||
problem: A repository can pass local tests while still lacking safe deployment, migration, recovery, monitoring and operator
|
||||
evidence.
|
||||
outcome: Produce a release decision with blocking findings, evidence gaps and a sequenced path to production readiness.
|
||||
whenToUse:
|
||||
- Before a first production deployment.
|
||||
- Before promoting a release candidate.
|
||||
- After major architectural or deployment changes.
|
||||
whenNotToUse:
|
||||
- When the goal is only a narrow code review.
|
||||
- When no target deployment assumptions can be established.
|
||||
modes:
|
||||
- inspect
|
||||
- plan
|
||||
defaultMode: inspect
|
||||
autonomy:
|
||||
min: observe
|
||||
max: plan
|
||||
default: plan
|
||||
inputs:
|
||||
- key: targetEnvironment
|
||||
label: Target environment
|
||||
description: Describe hosting platform, persistence, reverse proxy, network and operational ownership.
|
||||
type: multiline
|
||||
required: true
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
- key: releaseCandidate
|
||||
label: Release candidate
|
||||
description: Provide the branch, tag, commit or version being assessed.
|
||||
type: string
|
||||
required: true
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
- key: requiredDimensions
|
||||
label: Required dimensions
|
||||
description: Select readiness dimensions to assess.
|
||||
type: multiselect
|
||||
required: true
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
default:
|
||||
- build
|
||||
- tests
|
||||
- security
|
||||
- deployment
|
||||
- migrations
|
||||
- backup-restore
|
||||
- observability
|
||||
- documentation
|
||||
options:
|
||||
- build
|
||||
- tests
|
||||
- security
|
||||
- deployment
|
||||
- migrations
|
||||
- backup-restore
|
||||
- observability
|
||||
- documentation
|
||||
- performance
|
||||
- licensing
|
||||
- key: riskTolerance
|
||||
label: Risk tolerance
|
||||
description: Choose how strictly incomplete evidence should block release.
|
||||
type: enum
|
||||
required: true
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
default: conservative
|
||||
options:
|
||||
- conservative
|
||||
- balanced
|
||||
- experimental
|
||||
compatibility:
|
||||
repositoryRequired: true
|
||||
languages: []
|
||||
frameworks: []
|
||||
packageManagers: []
|
||||
databases: []
|
||||
deploymentTypes: []
|
||||
requiredProfileCapabilities: []
|
||||
incompatibleConditions: []
|
||||
guardrails:
|
||||
- id: read-only
|
||||
severity: blocking
|
||||
text: Do not modify application code, deployment settings, data or external systems.
|
||||
- id: evidence-gate
|
||||
severity: blocking
|
||||
text: Do not mark a dimension ready without executed or directly observable evidence.
|
||||
- id: no-production-tests
|
||||
severity: blocking
|
||||
text: Do not run destructive or load tests against production systems.
|
||||
- id: release-honesty
|
||||
severity: blocking
|
||||
text: Separate Passed, Failed, Not run and Not applicable. Do not convert unknown evidence into a pass.
|
||||
- id: migration-critical
|
||||
severity: blocking
|
||||
text: Treat unvalidated destructive migrations or unrecoverable data changes as blocking.
|
||||
workflow:
|
||||
- id: context
|
||||
title: Establish release context
|
||||
instruction: Identify exact candidate, target environment, architecture, data stores, deployment path and operator ownership.
|
||||
required: true
|
||||
- id: gate-inventory
|
||||
title: Build gate inventory
|
||||
instruction: Map selected dimensions to existing commands, documentation and evidence.
|
||||
required: true
|
||||
- id: static-review
|
||||
title: Review static readiness
|
||||
instruction: Inspect configuration, containerization, migration, backup, health, logging, secrets and release documentation.
|
||||
required: true
|
||||
- id: safe-validation
|
||||
title: Execute safe available checks
|
||||
instruction: Run non-destructive build, test and packaging checks appropriate to the candidate and environment.
|
||||
required: true
|
||||
- id: gap-analysis
|
||||
title: Classify readiness gaps
|
||||
instruction: Classify blockers, high-risk gaps, advisory improvements and evidence unavailable.
|
||||
required: true
|
||||
- id: decision
|
||||
title: Produce release decision
|
||||
instruction: State Go, Conditional Go or No-Go with precise conditions and staged remediation.
|
||||
required: true
|
||||
- id: run-pack
|
||||
title: Produce readiness Run Pack
|
||||
instruction: Export report, gate matrix, remediation plan and release handoff checklist.
|
||||
required: true
|
||||
validation:
|
||||
commandRoles:
|
||||
- lint
|
||||
- typecheck
|
||||
- unit-test
|
||||
- integration-test
|
||||
- end-to-end-test
|
||||
- build
|
||||
- smoke-test
|
||||
- migration-status
|
||||
- security-scan
|
||||
- dependency-audit
|
||||
checks:
|
||||
- id: candidate
|
||||
type: assertion
|
||||
description: The exact candidate identifier and target environment are recorded.
|
||||
blocking: true
|
||||
evidence: Report header.
|
||||
- id: gate-evidence
|
||||
type: artifact
|
||||
description: Each readiness gate has Pass, Fail, Not run or Not applicable with evidence.
|
||||
blocking: true
|
||||
evidence: Gate matrix.
|
||||
- id: no-writes
|
||||
type: assertion
|
||||
description: No production or repository changes were made.
|
||||
blocking: true
|
||||
evidence: Task report.
|
||||
- id: decision
|
||||
type: artifact
|
||||
description: Release decision follows directly from gate evidence and risk tolerance.
|
||||
blocking: true
|
||||
evidence: Decision section.
|
||||
- id: remediation
|
||||
type: artifact
|
||||
description: Every blocker has an owner-shaped action, validation and dependency.
|
||||
blocking: true
|
||||
evidence: Remediation plan.
|
||||
completion:
|
||||
criteria:
|
||||
- Exact candidate and deployment assumptions are recorded.
|
||||
- Every selected readiness dimension has explicit status and evidence.
|
||||
- Blocking gaps and unknowns are not hidden.
|
||||
- Release decision and conditions are justified.
|
||||
- Remediation is sequenced into actionable follow-up playbooks.
|
||||
failurePolicy:
|
||||
onValidationFailure: Investigate failures caused by the current work, repair them when they remain within scope, rerun
|
||||
the affected validation and report any genuine blocker without claiming success.
|
||||
onAmbiguity: Use repository evidence and existing conventions for minor choices. For material product ambiguity, preserve
|
||||
current behavior, document the decision needed and stop before an irreversible change.
|
||||
onMissingContext: Inspect the repository for the missing non-sensitive context. Never invent commands, credentials, production
|
||||
behavior or validation results. Report what remains unavailable.
|
||||
onOutOfScopeCause: Explain the evidenced out-of-scope cause, avoid broad unrelated changes and provide the smallest safe
|
||||
follow-up recommendation.
|
||||
onExternalDependencyUnavailable: Use a safe local fixture only when it preserves the behavior under test. Otherwise report
|
||||
the blocked validation and do not claim the external path succeeded.
|
||||
onUnableToReproduce: Record attempted reproduction and environment evidence. Do not make speculative production changes;
|
||||
provide the narrowest next diagnostic action.
|
||||
reporting:
|
||||
sections:
|
||||
- id: decision
|
||||
title: Release decision
|
||||
required: true
|
||||
description: Go, Conditional Go or No-Go with concise justification.
|
||||
- id: context
|
||||
title: Candidate and environment
|
||||
required: true
|
||||
description: Exact version/commit and deployment assumptions.
|
||||
- id: gates
|
||||
title: Readiness gate matrix
|
||||
required: true
|
||||
description: Status, evidence and notes for every selected dimension.
|
||||
- id: blockers
|
||||
title: Blocking and high-risk findings
|
||||
required: true
|
||||
description: Issues that prevent or materially endanger release.
|
||||
- id: remediation
|
||||
title: Remediation plan
|
||||
required: true
|
||||
description: Sequenced actions, validation and suggested playbooks.
|
||||
- id: limitations
|
||||
title: Evidence limitations
|
||||
required: true
|
||||
description: Checks not run, permission constraints and unverified assumptions.
|
||||
template:
|
||||
main: prompt.md
|
||||
partials: []
|
||||
exports:
|
||||
prompt: true
|
||||
markdown: true
|
||||
runPack: true
|
||||
agentsSuggestion: false
|
||||
quality:
|
||||
reviewStatus: technical-reviewed
|
||||
testedStacks: []
|
||||
knownLimitations:
|
||||
- A read-only audit cannot replace an isolated restore test or live operational rehearsal when those are unavailable.
|
||||
evaluationCaseIds:
|
||||
- production-readiness-audit.static-structure
|
||||
@@ -0,0 +1,11 @@
|
||||
# Production readiness audit instructions
|
||||
|
||||
Release candidate: {{ inputs.releaseCandidate }}.
|
||||
Risk tolerance: {{ inputs.riskTolerance }}.
|
||||
Required dimensions: {{ inputs.requiredDimensions }}.
|
||||
|
||||
Target environment:
|
||||
|
||||
{{ inputs.targetEnvironment }}
|
||||
|
||||
Use an explicit gate matrix. A command documented in the repository is not evidence that it currently passes. Run only safe checks available in the assessment environment and mark all others Not run. Produce a clear release decision and a sequenced remediation plan suitable for separate implementation playbooks.
|
||||
@@ -0,0 +1,5 @@
|
||||
# Changelog
|
||||
|
||||
## 1.0.0
|
||||
|
||||
- Initial reviewed example package for **Repository Cleanup and Hygiene**.
|
||||
@@ -0,0 +1,5 @@
|
||||
# Repository Cleanup and Hygiene
|
||||
|
||||
Remove dead files, stale scripts, generated artifacts and unused dependencies while preserving behavior.
|
||||
|
||||
This package is a normative DevRunbook example. Validate it against `schemas/playbook.schema.json`.
|
||||
@@ -0,0 +1,23 @@
|
||||
apiVersion: devrunbook.io/v1alpha1
|
||||
kind: EvaluationCase
|
||||
metadata:
|
||||
id: repository-cleanup.static-structure
|
||||
version: 1.0.0
|
||||
spec:
|
||||
playbookVersion: 1.0.0
|
||||
inputFile: ../examples/minimal.yaml
|
||||
expectedHeadings:
|
||||
- Mission
|
||||
- Scope
|
||||
- Constraints and guardrails
|
||||
- Execution workflow
|
||||
- Validation plan
|
||||
- Completion contract
|
||||
- Final reporting format
|
||||
prohibitedPatterns:
|
||||
- BEGIN PRIVATE KEY
|
||||
- 'Authorization: Bearer'
|
||||
deterministic: true
|
||||
requiredPatterns:
|
||||
- Repository Cleanup and Hygiene
|
||||
expectedLintStatus: ready
|
||||
@@ -0,0 +1,12 @@
|
||||
playbook:
|
||||
slug: repository-cleanup
|
||||
version: 1.0.0
|
||||
workMode: plan
|
||||
autonomyLevel: verify
|
||||
inputs:
|
||||
cleanupAreas:
|
||||
- dead-files
|
||||
- unused-dependencies
|
||||
- stale-scripts
|
||||
protectedPaths: []
|
||||
aggressiveness: conservative
|
||||
@@ -0,0 +1,253 @@
|
||||
apiVersion: devrunbook.io/v1alpha1
|
||||
kind: Playbook
|
||||
metadata:
|
||||
id: maintenance.repository-cleanup
|
||||
slug: repository-cleanup
|
||||
version: 1.0.0
|
||||
title: Repository Cleanup and Hygiene
|
||||
summary: Remove dead files, stale scripts, generated artifacts and unused dependencies while preserving behavior.
|
||||
category: code-quality
|
||||
tags:
|
||||
- cleanup
|
||||
- dead-code
|
||||
- dependencies
|
||||
lifecycle: reviewed
|
||||
riskTier: moderate
|
||||
authors:
|
||||
- name: DevRunbook Core Team
|
||||
license: MIT
|
||||
package:
|
||||
files:
|
||||
- path: prompt.md
|
||||
role: template
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: README.md
|
||||
role: documentation
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: CHANGELOG.md
|
||||
role: changelog
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: examples/minimal.yaml
|
||||
role: example
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: evaluations/static-structure.yaml
|
||||
role: evaluation
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
spec:
|
||||
type: guided
|
||||
intent:
|
||||
problem: Repositories accumulate unused dependencies, dead code, stale scripts, generated files and obsolete documentation
|
||||
that increase maintenance cost and confuse agents.
|
||||
outcome: Perform an evidence-based cleanup that removes genuinely unused material while preserving observable behavior
|
||||
and reproducible setup.
|
||||
whenToUse:
|
||||
- Before a release or major refactor.
|
||||
- After multiple experiments or abandoned features.
|
||||
- When repository size and navigation have become noisy.
|
||||
whenNotToUse:
|
||||
- When behavior changes or architecture redesign are the primary goal.
|
||||
- When there is no reliable way to validate important behavior.
|
||||
modes:
|
||||
- plan
|
||||
- guided
|
||||
- execute
|
||||
defaultMode: execute
|
||||
autonomy:
|
||||
min: plan
|
||||
max: repair
|
||||
default: verify
|
||||
inputs:
|
||||
- key: cleanupAreas
|
||||
label: Cleanup areas
|
||||
description: Select the cleanup dimensions to include.
|
||||
type: multiselect
|
||||
required: true
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
default:
|
||||
- dead-files
|
||||
- unused-dependencies
|
||||
- stale-scripts
|
||||
options:
|
||||
- dead-files
|
||||
- dead-code
|
||||
- unused-dependencies
|
||||
- stale-scripts
|
||||
- generated-artifacts
|
||||
- documentation
|
||||
- gitignore
|
||||
- key: protectedPaths
|
||||
label: Additional protected paths
|
||||
description: Paths that must not be modified or removed.
|
||||
type: string-list
|
||||
required: false
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
default: []
|
||||
- key: aggressiveness
|
||||
label: Cleanup aggressiveness
|
||||
description: Choose how conservative removal evidence must be.
|
||||
type: enum
|
||||
required: true
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
default: conservative
|
||||
options:
|
||||
- conservative
|
||||
- standard
|
||||
- aggressive-reviewed
|
||||
compatibility:
|
||||
repositoryRequired: true
|
||||
languages: []
|
||||
frameworks: []
|
||||
packageManagers: []
|
||||
databases: []
|
||||
deploymentTypes: []
|
||||
requiredProfileCapabilities: []
|
||||
incompatibleConditions: []
|
||||
guardrails:
|
||||
- id: evidence-before-removal
|
||||
severity: blocking
|
||||
text: Do not remove a file, dependency, export or script without evidence that it is unused in supported behavior.
|
||||
- id: preserve-runtime
|
||||
severity: blocking
|
||||
text: Do not alter product behavior, public contracts, migrations or persisted user data.
|
||||
- id: protect-paths
|
||||
severity: blocking
|
||||
text: Do not modify repository-profile protected paths or additional protected paths.
|
||||
- id: no-history-rewrite
|
||||
severity: blocking
|
||||
text: Do not rewrite Git history or delete remote branches/tags.
|
||||
- id: no-mass-format
|
||||
severity: blocking
|
||||
text: Do not combine cleanup with repository-wide formatting or unrelated refactoring.
|
||||
workflow:
|
||||
- id: baseline
|
||||
title: Capture baseline
|
||||
instruction: Record worktree state, repository commands and current validation result before cleanup.
|
||||
required: true
|
||||
- id: inventory
|
||||
title: Build cleanup inventory
|
||||
instruction: Identify candidates with references, import/use searches, package-manager evidence and generated/runtime
|
||||
ownership.
|
||||
required: true
|
||||
- id: classify
|
||||
title: Classify candidates
|
||||
instruction: Separate safe removals, uncertain items and intentionally retained compatibility assets.
|
||||
required: true
|
||||
- id: remove-batches
|
||||
title: Apply small cleanup batches
|
||||
instruction: Remove only supported candidates in reviewable groups and update direct references.
|
||||
required: true
|
||||
- id: validate-batches
|
||||
title: Validate after each batch
|
||||
instruction: Run the narrowest useful checks after risky batches to localize regressions.
|
||||
required: true
|
||||
- id: full-validation
|
||||
title: Run full validation
|
||||
instruction: Run install/lockfile checks and all available required repository validation.
|
||||
required: true
|
||||
- id: final-review
|
||||
title: Review repository state
|
||||
instruction: Confirm no runtime data, examples or required compatibility assets were removed.
|
||||
required: true
|
||||
validation:
|
||||
commandRoles:
|
||||
- lint
|
||||
- typecheck
|
||||
- unit-test
|
||||
- integration-test
|
||||
- build
|
||||
- dependency-audit
|
||||
checks:
|
||||
- id: baseline
|
||||
type: artifact
|
||||
description: A baseline validation and worktree state are recorded.
|
||||
blocking: true
|
||||
evidence: Baseline section.
|
||||
- id: removal-evidence
|
||||
type: artifact
|
||||
description: Every removal is traceable to evidence of non-use.
|
||||
blocking: true
|
||||
evidence: Cleanup inventory.
|
||||
- id: lockfile
|
||||
type: command
|
||||
description: Dependency manifest and lockfile remain consistent when dependencies change.
|
||||
blocking: true
|
||||
evidence: Install/frozen-lockfile result.
|
||||
when:
|
||||
fact:
|
||||
path: inputs.cleanupAreas
|
||||
operator: contains
|
||||
value: unused-dependencies
|
||||
- id: full-validation
|
||||
type: command
|
||||
description: Available lint, typecheck, tests and build pass.
|
||||
blocking: true
|
||||
evidence: Command results.
|
||||
- id: diff-review
|
||||
type: assertion
|
||||
description: No protected or unrelated files changed.
|
||||
blocking: true
|
||||
evidence: Final diff review.
|
||||
completion:
|
||||
criteria:
|
||||
- Selected cleanup areas are addressed with evidence.
|
||||
- Repository setup, tests and build remain reproducible.
|
||||
- No supported behavior or protected data path changed.
|
||||
- Uncertain candidates remain and are documented rather than guessed.
|
||||
failurePolicy:
|
||||
onValidationFailure: Investigate failures caused by the current work, repair them when they remain within scope, rerun
|
||||
the affected validation and report any genuine blocker without claiming success.
|
||||
onAmbiguity: Use repository evidence and existing conventions for minor choices. For material product ambiguity, preserve
|
||||
current behavior, document the decision needed and stop before an irreversible change.
|
||||
onMissingContext: Inspect the repository for the missing non-sensitive context. Never invent commands, credentials, production
|
||||
behavior or validation results. Report what remains unavailable.
|
||||
onOutOfScopeCause: Explain the evidenced out-of-scope cause, avoid broad unrelated changes and provide the smallest safe
|
||||
follow-up recommendation.
|
||||
onExternalDependencyUnavailable: Use a safe local fixture only when it preserves the behavior under test. Otherwise report
|
||||
the blocked validation and do not claim the external path succeeded.
|
||||
onUnableToReproduce: Record attempted reproduction and environment evidence. Do not make speculative production changes;
|
||||
provide the narrowest next diagnostic action.
|
||||
reporting:
|
||||
sections:
|
||||
- id: removed
|
||||
title: Removed items
|
||||
required: true
|
||||
description: List removals by category with concise evidence.
|
||||
- id: retained
|
||||
title: Intentionally retained
|
||||
required: true
|
||||
description: Explain uncertain or compatibility-related items that were not removed.
|
||||
- id: validation
|
||||
title: Validation
|
||||
required: true
|
||||
description: Commands and results before and after cleanup.
|
||||
- id: impact
|
||||
title: Impact
|
||||
required: true
|
||||
description: Repository size, dependency or navigation improvements where measured.
|
||||
- id: unresolved
|
||||
title: Follow-up
|
||||
required: false
|
||||
description: Remaining cleanup candidates or structural debt outside scope.
|
||||
template:
|
||||
main: prompt.md
|
||||
partials: []
|
||||
exports:
|
||||
prompt: true
|
||||
markdown: true
|
||||
runPack: true
|
||||
agentsSuggestion: false
|
||||
quality:
|
||||
reviewStatus: technical-reviewed
|
||||
testedStacks: []
|
||||
knownLimitations:
|
||||
- Dynamic imports, plugins and externally invoked scripts can make static non-use evidence incomplete.
|
||||
evaluationCaseIds:
|
||||
- repository-cleanup.static-structure
|
||||
@@ -0,0 +1,9 @@
|
||||
# Repository cleanup instructions
|
||||
|
||||
Selected cleanup areas: {{ inputs.cleanupAreas }}.
|
||||
Aggressiveness: {{ inputs.aggressiveness }}.
|
||||
Additional protected paths: {{ inputs.protectedPaths }}.
|
||||
|
||||
Use conservative evidence by default. Search references, build manifests, CI configuration, documentation, runtime loading patterns and external entry points before removal. Dynamic loading or deployment scripts should be treated as uncertainty, not proof of non-use.
|
||||
|
||||
Apply cleanup in coherent batches. Do not hide behavior changes inside a hygiene task.
|
||||
@@ -0,0 +1,5 @@
|
||||
# Changelog
|
||||
|
||||
## 1.0.0
|
||||
|
||||
- Initial reviewed example package for **Repository Health Audit**.
|
||||
@@ -0,0 +1,5 @@
|
||||
# Repository Health Audit
|
||||
|
||||
Assess repository hygiene, documentation, testing, dependencies, release readiness and agent readiness without making changes.
|
||||
|
||||
This package is a normative DevRunbook example. Validate it against `schemas/playbook.schema.json`.
|
||||
@@ -0,0 +1,23 @@
|
||||
apiVersion: devrunbook.io/v1alpha1
|
||||
kind: EvaluationCase
|
||||
metadata:
|
||||
id: repository-health-audit.static-structure
|
||||
version: 1.0.0
|
||||
spec:
|
||||
playbookVersion: 1.0.0
|
||||
inputFile: ../examples/minimal.yaml
|
||||
expectedHeadings:
|
||||
- Mission
|
||||
- Scope
|
||||
- Constraints and guardrails
|
||||
- Execution workflow
|
||||
- Validation plan
|
||||
- Completion contract
|
||||
- Final reporting format
|
||||
prohibitedPatterns:
|
||||
- BEGIN PRIVATE KEY
|
||||
- 'Authorization: Bearer'
|
||||
deterministic: true
|
||||
requiredPatterns:
|
||||
- Repository Health Audit
|
||||
expectedLintStatus: ready
|
||||
@@ -0,0 +1,9 @@
|
||||
playbook:
|
||||
slug: repository-health-audit
|
||||
version: 1.0.0
|
||||
workMode: inspect
|
||||
autonomyLevel: diagnose
|
||||
inputs:
|
||||
auditDepth: standard
|
||||
focusAreas: []
|
||||
excludedPaths: []
|
||||
@@ -0,0 +1,217 @@
|
||||
apiVersion: devrunbook.io/v1alpha1
|
||||
kind: Playbook
|
||||
metadata:
|
||||
id: audit.repository-health
|
||||
slug: repository-health-audit
|
||||
version: 1.0.0
|
||||
title: Repository Health Audit
|
||||
summary: Assess repository hygiene, documentation, testing, dependencies, release readiness and agent readiness without
|
||||
making changes.
|
||||
category: audits
|
||||
tags:
|
||||
- audit
|
||||
- repository
|
||||
- health
|
||||
lifecycle: reviewed
|
||||
riskTier: low
|
||||
authors:
|
||||
- name: DevRunbook Core Team
|
||||
license: MIT
|
||||
package:
|
||||
files:
|
||||
- path: prompt.md
|
||||
role: template
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: README.md
|
||||
role: documentation
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: CHANGELOG.md
|
||||
role: changelog
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: examples/minimal.yaml
|
||||
role: example
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: evaluations/static-structure.yaml
|
||||
role: evaluation
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
spec:
|
||||
type: guided
|
||||
intent:
|
||||
problem: Repositories often accumulate gaps across documentation, testing, dependencies, release practices and agent instructions
|
||||
without one evidence-based view.
|
||||
outcome: Produce a read-only, prioritized repository health report with evidence, confidence, impact and recommended follow-up
|
||||
playbooks.
|
||||
whenToUse:
|
||||
- Before major development or onboarding begins.
|
||||
- When repository quality has not been reviewed recently.
|
||||
- Before deciding where cleanup investment should go.
|
||||
whenNotToUse:
|
||||
- When a formal penetration test or legal compliance certification is required.
|
||||
- When the user expects automatic code changes rather than an audit report.
|
||||
modes:
|
||||
- inspect
|
||||
- plan
|
||||
defaultMode: inspect
|
||||
autonomy:
|
||||
min: observe
|
||||
max: plan
|
||||
default: diagnose
|
||||
inputs:
|
||||
- key: auditDepth
|
||||
label: Audit depth
|
||||
description: Select how broadly the repository should be inspected.
|
||||
type: enum
|
||||
required: true
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
default: standard
|
||||
options:
|
||||
- focused
|
||||
- standard
|
||||
- deep
|
||||
- key: focusAreas
|
||||
label: Focus areas
|
||||
description: Optional dimensions that deserve extra attention.
|
||||
type: multiselect
|
||||
required: false
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
default: []
|
||||
options:
|
||||
- documentation
|
||||
- testing
|
||||
- dependencies
|
||||
- architecture
|
||||
- security-hygiene
|
||||
- release
|
||||
- agent-readiness
|
||||
- key: excludedPaths
|
||||
label: Excluded paths
|
||||
description: Paths that must not be inspected beyond identifying their existence.
|
||||
type: string-list
|
||||
required: false
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
default: []
|
||||
compatibility:
|
||||
repositoryRequired: true
|
||||
languages: []
|
||||
frameworks: []
|
||||
packageManagers: []
|
||||
databases: []
|
||||
deploymentTypes: []
|
||||
requiredProfileCapabilities: []
|
||||
incompatibleConditions: []
|
||||
guardrails:
|
||||
- id: read-only
|
||||
severity: blocking
|
||||
text: Do not modify files, Git state, repository settings or external systems.
|
||||
- id: evidence-first
|
||||
severity: blocking
|
||||
text: Link each finding to observable repository or forge evidence and distinguish absence of evidence from confirmed
|
||||
absence.
|
||||
- id: no-secret-reading
|
||||
severity: blocking
|
||||
text: Do not open secret files, private keys, runtime databases or credential stores.
|
||||
- id: no-certification-claim
|
||||
severity: warning
|
||||
text: Do not present this audit as a penetration test, legal review or certification.
|
||||
workflow:
|
||||
- id: recon
|
||||
title: Establish repository context
|
||||
instruction: Read repository-level instructions, manifests, documentation, build/test configuration and selected governance
|
||||
evidence before evaluating quality.
|
||||
required: true
|
||||
- id: dimension-review
|
||||
title: Assess quality dimensions
|
||||
instruction: Review repository hygiene, documentation accuracy, test strategy, dependency management, release readiness,
|
||||
container/operations readiness and Codex instruction readiness.
|
||||
required: true
|
||||
- id: validate-findings
|
||||
title: Validate findings
|
||||
instruction: Check potential findings against multiple evidence sources where practical and remove weak or duplicate observations.
|
||||
required: true
|
||||
- id: prioritize
|
||||
title: Prioritize recommendations
|
||||
instruction: Rank findings by user impact, operational risk, confidence and realistic remediation order.
|
||||
required: true
|
||||
- id: report
|
||||
title: Produce audit report
|
||||
instruction: Create a concise executive summary plus detailed evidence table and recommended follow-up playbooks.
|
||||
required: true
|
||||
validation:
|
||||
commandRoles: []
|
||||
checks:
|
||||
- id: read-only-proof
|
||||
type: assertion
|
||||
description: Confirm the worktree and repository settings were not changed.
|
||||
blocking: true
|
||||
evidence: Git/status or equivalent evidence shows no modifications.
|
||||
- id: evidence-links
|
||||
type: artifact
|
||||
description: Every medium/high finding includes an evidence path or forge evidence pointer.
|
||||
blocking: true
|
||||
evidence: Audit report finding table.
|
||||
- id: limitations
|
||||
type: artifact
|
||||
description: Permission limits, uninspected paths and uncertainty are documented.
|
||||
blocking: true
|
||||
evidence: Limitations section.
|
||||
completion:
|
||||
criteria:
|
||||
- No repository files or external settings were changed.
|
||||
- Every reported finding includes severity, confidence, evidence and impact.
|
||||
- Recommendations are ordered and mapped to actionable follow-up.
|
||||
- Limitations and unknowns are explicit.
|
||||
failurePolicy:
|
||||
onValidationFailure: Investigate failures caused by the current work, repair them when they remain within scope, rerun
|
||||
the affected validation and report any genuine blocker without claiming success.
|
||||
onAmbiguity: Use repository evidence and existing conventions for minor choices. For material product ambiguity, preserve
|
||||
current behavior, document the decision needed and stop before an irreversible change.
|
||||
onMissingContext: Inspect the repository for the missing non-sensitive context. Never invent commands, credentials, production
|
||||
behavior or validation results. Report what remains unavailable.
|
||||
onOutOfScopeCause: Explain the evidenced out-of-scope cause, avoid broad unrelated changes and provide the smallest safe
|
||||
follow-up recommendation.
|
||||
onExternalDependencyUnavailable: Use a safe local fixture only when it preserves the behavior under test. Otherwise report
|
||||
the blocked validation and do not claim the external path succeeded.
|
||||
onUnableToReproduce: Record attempted reproduction and environment evidence. Do not make speculative production changes;
|
||||
provide the narrowest next diagnostic action.
|
||||
reporting:
|
||||
sections:
|
||||
- id: summary
|
||||
title: Executive summary
|
||||
required: true
|
||||
description: Overall health, strongest areas, highest risks and recommended first action.
|
||||
- id: findings
|
||||
title: Findings by dimension
|
||||
required: true
|
||||
description: Evidence-linked findings grouped by dimension and severity.
|
||||
- id: priorities
|
||||
title: Prioritized actions
|
||||
required: true
|
||||
description: Ordered remediation backlog with suggested playbooks.
|
||||
- id: limitations
|
||||
title: Limitations
|
||||
required: true
|
||||
description: Permissions, exclusions and uncertainty that affect the audit.
|
||||
template:
|
||||
main: prompt.md
|
||||
partials: []
|
||||
exports:
|
||||
prompt: true
|
||||
markdown: true
|
||||
runPack: true
|
||||
agentsSuggestion: true
|
||||
quality:
|
||||
reviewStatus: technical-reviewed
|
||||
testedStacks: []
|
||||
knownLimitations:
|
||||
- Static evidence cannot prove runtime behavior that is not exercised.
|
||||
- Forge governance findings depend on available permissions and capabilities.
|
||||
evaluationCaseIds:
|
||||
- repository-health-audit.static-structure
|
||||
@@ -0,0 +1,10 @@
|
||||
# Repository health audit instructions
|
||||
|
||||
Audit **{{ repository.displayName }}** at the selected `{{ inputs.auditDepth }}` depth.
|
||||
|
||||
Focus areas supplied by the user: {{ inputs.focusAreas }}.
|
||||
Excluded paths: {{ inputs.excludedPaths }}.
|
||||
|
||||
Use repository-wide reading only where necessary to understand the selected dimensions. Prefer concise evidence references over copying large source fragments. For each finding, state whether it is confirmed, probable or unknown because evidence is unavailable.
|
||||
|
||||
Do not implement the recommendations in this task. The final output must be useful as a remediation backlog and should reference the most suitable DevRunbook playbook slug where one exists.
|
||||
@@ -0,0 +1,5 @@
|
||||
# Changelog
|
||||
|
||||
## 1.0.0
|
||||
|
||||
- Initial reviewed example package for **Root-Cause Bug Fix**.
|
||||
@@ -0,0 +1,5 @@
|
||||
# Root-Cause Bug Fix
|
||||
|
||||
Reproduce a defect, identify its root cause, add regression evidence and implement the smallest structural repair.
|
||||
|
||||
This package is a normative DevRunbook example. Validate it against `schemas/playbook.schema.json`.
|
||||
@@ -0,0 +1,23 @@
|
||||
apiVersion: devrunbook.io/v1alpha1
|
||||
kind: EvaluationCase
|
||||
metadata:
|
||||
id: root-cause-bugfix.static-structure
|
||||
version: 1.0.0
|
||||
spec:
|
||||
playbookVersion: 1.0.0
|
||||
inputFile: ../examples/minimal.yaml
|
||||
expectedHeadings:
|
||||
- Mission
|
||||
- Scope
|
||||
- Constraints and guardrails
|
||||
- Execution workflow
|
||||
- Validation plan
|
||||
- Completion contract
|
||||
- Final reporting format
|
||||
prohibitedPatterns:
|
||||
- BEGIN PRIVATE KEY
|
||||
- 'Authorization: Bearer'
|
||||
deterministic: true
|
||||
requiredPatterns:
|
||||
- Root-Cause Bug Fix
|
||||
expectedLintStatus: ready
|
||||
@@ -0,0 +1,10 @@
|
||||
playbook:
|
||||
slug: root-cause-bugfix
|
||||
version: 1.0.0
|
||||
workMode: guided
|
||||
autonomyLevel: verify
|
||||
inputs:
|
||||
problemStatement: Example value for Problem statement
|
||||
reproductionClues: ''
|
||||
preserveCompatibility: true
|
||||
affectedScope: []
|
||||
@@ -0,0 +1,238 @@
|
||||
apiVersion: devrunbook.io/v1alpha1
|
||||
kind: Playbook
|
||||
metadata:
|
||||
id: bugfix.root-cause
|
||||
slug: root-cause-bugfix
|
||||
version: 1.0.0
|
||||
title: Root-Cause Bug Fix
|
||||
summary: Reproduce a defect, identify its root cause, add regression evidence and implement the smallest structural repair.
|
||||
category: bugfixing
|
||||
tags:
|
||||
- bugfix
|
||||
- root-cause
|
||||
- regression
|
||||
lifecycle: reviewed
|
||||
riskTier: moderate
|
||||
authors:
|
||||
- name: DevRunbook Core Team
|
||||
license: MIT
|
||||
package:
|
||||
files:
|
||||
- path: prompt.md
|
||||
role: template
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: README.md
|
||||
role: documentation
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: CHANGELOG.md
|
||||
role: changelog
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: examples/minimal.yaml
|
||||
role: example
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
- path: evaluations/static-structure.yaml
|
||||
role: evaluation
|
||||
digest: true
|
||||
exportByDefault: false
|
||||
spec:
|
||||
type: guided
|
||||
intent:
|
||||
problem: A reported defect can be patched superficially without proving the true cause, preserving the failure as a future
|
||||
regression.
|
||||
outcome: Reproduce the defect, identify the smallest structural root cause, add regression evidence and verify the repair
|
||||
across relevant checks.
|
||||
whenToUse:
|
||||
- A specific bug or regression is observable.
|
||||
- A failing test, error, incorrect flow or reproducible symptom exists.
|
||||
whenNotToUse:
|
||||
- Requirements are primarily a new feature request.
|
||||
- The environment needed to reproduce the issue is legally or operationally unavailable.
|
||||
modes:
|
||||
- guided
|
||||
- execute
|
||||
- recovery
|
||||
defaultMode: execute
|
||||
autonomy:
|
||||
min: diagnose
|
||||
max: repair
|
||||
default: verify
|
||||
inputs:
|
||||
- key: problemStatement
|
||||
label: Problem statement
|
||||
description: Describe the observed behavior, expected behavior and user impact.
|
||||
type: multiline
|
||||
required: true
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
- key: reproductionClues
|
||||
label: Reproduction clues
|
||||
description: Provide safe steps, errors or conditions already known.
|
||||
type: multiline
|
||||
required: false
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
default: ''
|
||||
- key: preserveCompatibility
|
||||
label: Preserve backwards compatibility
|
||||
description: Require existing public behavior and interfaces to remain compatible.
|
||||
type: boolean
|
||||
required: true
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
default: true
|
||||
- key: affectedScope
|
||||
label: Affected scope
|
||||
description: Optional files, modules or feature area believed to be involved.
|
||||
type: string-list
|
||||
required: false
|
||||
sensitive: false
|
||||
includeInOutput: true
|
||||
default: []
|
||||
compatibility:
|
||||
repositoryRequired: true
|
||||
languages: []
|
||||
frameworks: []
|
||||
packageManagers: []
|
||||
databases: []
|
||||
deploymentTypes: []
|
||||
requiredProfileCapabilities:
|
||||
- test-command
|
||||
incompatibleConditions: []
|
||||
guardrails:
|
||||
- id: reproduce-first
|
||||
severity: blocking
|
||||
text: Do not change production logic until the issue is reproduced or a bounded evidence-based explanation shows why reproduction
|
||||
is unavailable.
|
||||
- id: no-test-weakening
|
||||
severity: blocking
|
||||
text: Do not delete, skip or weaken tests and checks merely to obtain a passing result.
|
||||
- id: minimal-causal-fix
|
||||
severity: blocking
|
||||
text: Keep the implementation focused on the root cause and avoid unrelated cleanup.
|
||||
- id: protect-behavior
|
||||
severity: blocking
|
||||
text: Preserve existing documented behavior and public contracts unless the problem statement explicitly changes them.
|
||||
workflow:
|
||||
- id: read-rules
|
||||
title: Read repository guidance
|
||||
instruction: Inspect AGENTS.md, relevant documentation and test/build configuration before modifying files.
|
||||
required: true
|
||||
- id: reproduce
|
||||
title: Reproduce the defect
|
||||
instruction: Use the narrowest existing command or create a focused failing regression test that demonstrates the observed
|
||||
defect.
|
||||
required: true
|
||||
- id: trace
|
||||
title: Identify root cause
|
||||
instruction: Trace the failing behavior across relevant boundaries and distinguish cause from downstream symptoms.
|
||||
required: true
|
||||
- id: implement
|
||||
title: Implement structural repair
|
||||
instruction: Apply the smallest maintainable change that fixes the cause while preserving unrelated behavior.
|
||||
required: true
|
||||
- id: validate-targeted
|
||||
title: Run targeted validation
|
||||
instruction: Run the regression test and directly relevant tests immediately.
|
||||
required: true
|
||||
- id: validate-full
|
||||
title: Run declared validation
|
||||
instruction: Run available lint, typecheck, test and build roles appropriate to the changed scope.
|
||||
required: true
|
||||
- id: review-diff
|
||||
title: Review final diff
|
||||
instruction: Remove accidental changes and confirm protected paths and public contracts remain intact.
|
||||
required: true
|
||||
validation:
|
||||
commandRoles:
|
||||
- lint
|
||||
- typecheck
|
||||
- unit-test
|
||||
- integration-test
|
||||
- build
|
||||
checks:
|
||||
- id: reproduction
|
||||
type: assertion
|
||||
description: The defect is demonstrated before the production fix or inability is explicitly evidenced.
|
||||
blocking: true
|
||||
evidence: Failing test, command output or bounded reproduction report.
|
||||
- id: regression
|
||||
type: artifact
|
||||
description: A regression check covers the root cause where feasible.
|
||||
blocking: true
|
||||
evidence: New or updated test and result.
|
||||
- id: targeted
|
||||
type: command
|
||||
description: Directly relevant validation passes after the fix.
|
||||
blocking: true
|
||||
evidence: Command and exit result.
|
||||
- id: full
|
||||
type: command
|
||||
description: All available required repository validation roles pass or genuine unrelated failures are identified.
|
||||
blocking: true
|
||||
evidence: Command summary.
|
||||
- id: scope
|
||||
type: assertion
|
||||
description: Final diff contains no unexplained unrelated changes.
|
||||
blocking: true
|
||||
evidence: Changed-file review.
|
||||
completion:
|
||||
criteria:
|
||||
- Observed defect is fixed at the root cause.
|
||||
- Regression evidence demonstrates the prior failure and repaired behavior.
|
||||
- Relevant lint, typecheck, tests and build pass.
|
||||
- Compatibility and protected paths remain intact.
|
||||
- Unresolved environmental or unrelated failures are reported honestly.
|
||||
failurePolicy:
|
||||
onValidationFailure: Investigate failures caused by the current work, repair them when they remain within scope, rerun
|
||||
the affected validation and report any genuine blocker without claiming success.
|
||||
onAmbiguity: Use repository evidence and existing conventions for minor choices. For material product ambiguity, preserve
|
||||
current behavior, document the decision needed and stop before an irreversible change.
|
||||
onMissingContext: Inspect the repository for the missing non-sensitive context. Never invent commands, credentials, production
|
||||
behavior or validation results. Report what remains unavailable.
|
||||
onOutOfScopeCause: Explain the evidenced out-of-scope cause, avoid broad unrelated changes and provide the smallest safe
|
||||
follow-up recommendation.
|
||||
onExternalDependencyUnavailable: Use a safe local fixture only when it preserves the behavior under test. Otherwise report
|
||||
the blocked validation and do not claim the external path succeeded.
|
||||
onUnableToReproduce: Record attempted reproduction and environment evidence. Do not make speculative production changes;
|
||||
provide the narrowest next diagnostic action.
|
||||
reporting:
|
||||
sections:
|
||||
- id: root-cause
|
||||
title: Root cause
|
||||
required: true
|
||||
description: Explain the actual cause and why the previous behavior occurred.
|
||||
- id: changes
|
||||
title: Changes
|
||||
required: true
|
||||
description: List changed files and the purpose of each change.
|
||||
- id: validation
|
||||
title: Validation
|
||||
required: true
|
||||
description: List commands/checks and outcomes, including pre-fix reproduction.
|
||||
- id: risk
|
||||
title: Risk and compatibility
|
||||
required: true
|
||||
description: State compatibility impact, remaining risk and untested conditions.
|
||||
- id: unresolved
|
||||
title: Unresolved items
|
||||
required: true
|
||||
description: State genuine blockers or unrelated failures; write None when empty.
|
||||
template:
|
||||
main: prompt.md
|
||||
partials: []
|
||||
exports:
|
||||
prompt: true
|
||||
markdown: true
|
||||
runPack: false
|
||||
agentsSuggestion: false
|
||||
quality:
|
||||
reviewStatus: technical-reviewed
|
||||
testedStacks: []
|
||||
knownLimitations:
|
||||
- Some production-only defects may require a safe synthetic reproduction rather than direct access.
|
||||
evaluationCaseIds:
|
||||
- root-cause-bugfix.static-structure
|
||||
@@ -0,0 +1,14 @@
|
||||
# Root-cause bug-fix instructions
|
||||
|
||||
Problem to solve:
|
||||
|
||||
{{ inputs.problemStatement }}
|
||||
|
||||
Known reproduction clues:
|
||||
|
||||
{{ inputs.reproductionClues }}
|
||||
|
||||
Likely affected scope: {{ inputs.affectedScope }}.
|
||||
Backwards compatibility required: {{ inputs.preserveCompatibility }}.
|
||||
|
||||
Begin with evidence. Do not anchor on the user's suspected module if repository behavior points elsewhere. A new regression test should fail for the correct reason before the fix and pass afterward. Do not make unrelated style or dependency changes unless they are strictly necessary for the causal repair and are explained.
|
||||
Reference in New Issue
Block a user