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