Create .dev-framework.yml in your project root. Two paths:
- Conversational (default): run
/df-initin the project. It scaffolds the templates, writes a detected config, trial-runs it, and hands the wizard brief to the agent — which reads your Makefile, CI, and CONTRIBUTING, maps the real verification commands (wrappers likemake check, never reconstructed bare tools), asks at most 3 genuinely user-only questions, and ends at a config +hardening.mddiff for your review. Never merge unreviewed. - Scripted:
df initfrom a shell (see the Quickstart) auto-detects your language and writes a matching config — then adjust it.initalso trial-runs the detected test/typecheck once and reports PASS/FAIL per command, so guesses arrive verified or flagged. Same scaffold, no conversation; conflicts need--overwrite-existingor--skip-existing.
Trust model for the agentic path: the agent proposes, the shared
enforceability bar checks the draft (blocking profile plus at least one
real check — the same bar /df-goal applies, so no vacuous config can
pass), and you review the diff and commit. No party trusted alone.
What follows is the full commented reference. The authoritative schema
lives in ../plans/03-config-spec.md; this
page shows it in usable form.
profile: standard
commands:
typecheck: "go build ./..."
test: "go test ./..."
lint:
".go": "golangci-lint run {dir}"
protect:
- ".env*"
- "deploy/prod/**"
gate:
run_typecheck: true
run_tests: true
block_on_failure: true
# standard/strict default: sessions that changed files must produce a
# peer-review artifact (.dev-framework/review.md)
# before the completion gate passes. Substance is enforced, not just
# existence: at least 200 chars / 30 words, no unfinished template
# markers or unfilled checklists — a "looks good" checkbox fails.
# Freshness is enforced too: name every changed file and write the review
# after the latest session edit; an older same-file review is stale.
require_review: true
# Optional: named project-specific acceptance checks. Run sequentially
# after the typecheck/test steps; a failure fails the gate but other
# steps still run. Timeouts are per-check seconds (default: gate timeout).
# acceptance:
# - name: api-contract
# command: "./scripts/verify-api-contract.sh"
# - name: migration-safety
# command: "./scripts/check-migrations.sh"
# timeout: 120
# Optional: pre-flight task list. When set, edit tools are denied
# (standard/strict) until the agent writes its findings to
# .dev-framework/preflight.md.
# preflight:
# - "Summarize the current strategy configuration and its intent"
# - "Load the most recent backtest results and record headline metrics"
on_edit:
lint: true
# Optional: delegate per-file linting to pre-commit when available
# precommit: auto
# Optional: explicit rule files (replace bundled; use mode: append to extend)
# rules:
# - docs/team-rules.md
# Append form (keeps the bundled rules, adds project files after them):
# rules:
# mode: append
# files:
# - .dev-framework/hardening.md
# Optional: project style guide appended to the constitution.
# Auto-discovers STYLE.md / CONTRIBUTING.md / docs/STYLE.md when not set.
# style_guide: STYLE.md- Profiles (
off/advisory/standard/strict) set the defaults:advisorywarns wherestandard/strictdeny, and the gate only blocks whenblock_on_failureis true (standard/strictdefault). Seeenforcement.md. - Constitution. The bundled rules ship with the plugin. Override them by
dropping Markdown files into
.dev-framework/rules/, by setting explicitrules, or by letting the plugin auto-discover yourSTYLE.md/CONTRIBUTING.md. - Legacy compatibility. The previous config name
(
.opencode-dev-framework.yml) is still read when no.dev-framework.ymlexists, and flat-key documents keep working under either name — but the neutral name with the native format above is preferred for new projects. Likewise the framework's private files used to live under.opencode/opencode-dev-framework/(review, preflight, runtime snapshot, local rules); that home is still read as a fallback, and all new files go to.dev-framework/. - Worked example.
../../examples/go-service/shows a complete Go-service config.