278 lines
9.7 KiB
YAML
278 lines
9.7 KiB
YAML
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
|