Publish DevRunbook source

examples/playbooks/feature-from-spec/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0
+
+- Initial reviewed example package for **Implement a Feature from a Functional Specification**.

examples/playbooks/feature-from-spec/README.md

@@ -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`.

examples/playbooks/feature-from-spec/evaluations/static-structure.yaml

@@ -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

examples/playbooks/feature-from-spec/examples/minimal.yaml

@@ -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

examples/playbooks/feature-from-spec/playbook.yaml

@@ -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

examples/playbooks/feature-from-spec/prompt.md

@@ -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.