본문으로 건너뛰기
J

opencode-dev-framework

jwitmann/opencode-dev-framework

Enforcement gates for AI coding agents on OpenCode and DeepSeek Harness

설치

dsh plugin --profile web add github:jwitmann/opencode-dev-framework

README

opencode-dev-framework

AI agents can say they're done without proving it. This plugin replaces assertion with evidence: guardrails, per-edit formatting and lint feedback, a completion gate that runs your real checks, and verified goals that require a tool-result PASS on the final tree. Exit codes don't negotiate.

One shared enforcement core powers native adapters for OpenCode and DSH (DeepSeek Harness, via Cordis), with the same config, profiles, rules, and gates on both.

Inspired by anticomputer/dev-framework, which supports Copilot CLI, Claude Code, and Codex CLI; this is an independent implementation. DSH guide: docs/user/dsh.md.

Quickstart

Five minutes from zero to your first gated session.

1. Install the plugin

On OpenCode:

opencode plugin add opencode-dev-framework

Or declare it in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-dev-framework"]
}

On DSH:

dsh plugin --profile <name> add opencode-dev-framework
df install-dsh --profile <name>  # preset seam + verification

Full DSH reference: docs/user/dsh.md.

2. Init your project (same on both harnesses)

In any project, run:

/df-init

It scaffolds the templates, writes a detected config, trial-runs it, and hands your session agent a brief — what was detected, what passed, Makefile targets worth mapping to wrappers, at most 3 open questions. The agent resolves what it can, asks only genuinely user-only questions, and ends with a config + hardening.md draft for your review. Budget ~5 minutes, review-only at the end; imperfections assumed, manual always possible.

Prefer a shell? Same thing non-interactively — for CI, dotfiles, and scripted runs (add --dsh on DSH so the host-visible skill mirror is scaffolded too):

npx df init [--dsh]

Conflicts need --overwrite-existing or --skip-existing — everything else is under npx df init --help.

On DSH, run dsh from the project root (or export ODF_WORKDIR), and accept template drift via df-update if the session reports any.

Then ask the agent for a small edit. You will see the plugin working: the edit is checked against guardrails before it lands, your linter runs on the edited file, and when the session goes idle the completion gate runs your typecheck/tests. /df-status shows the live state at any time. Start with profile: advisory if you want to observe before enforcing.

Local development

From a checkout — the contributor loop. Build once, then wire the profile directly at the built file (no registry needed):

npm run build
df install-dsh --profile <name> --dist /path/to/opencode-dev-framework/dist/adapters/dsh/index.js

Rebuild after every source change; rerun df install-dsh any time (it is idempotent outside its managed block). The full contributor contract — validation commands, commit policy, never-push rule — is AGENTS.md.

Harness differences

Same core, same config, same profiles — different wiring where the hosts differ. Neither harness is the "real" one; each is stronger somewhere:

AreaOpenCodeDSH
Completion gateSynthetic continuation at the idle boundary (re-prompt round-trip)Blocks termination pre-terminal; failure work continues in the same turn
Per-edit lintLogged against the landed editFails the tool call (block) — agent retries same turn
Guard warnLogged (advisory never blocks)Logged, or prompts the human as ask when the approval seam is injected
Redirect targets (a > file)Not guard-checkedGuard-checked (wider than OpenCode)
denial identityReason textReason text + structured {name, code}
Skills.opencode/skills (native).dsh/skills (installed by df-init, kept current by df-update)
Reviewer agents.opencode/agents specialists run as subagentsAdapter-dispatched DSH children on review-blocks (one per kind; read-only preset where the registry exists; findings fold into the steer; customize via .dev-framework/agents/); inline steer when the seam is absent
Goals/df-goal wraps native /goaldf-goal creates the host goal with the same verification contract
InstallOne command (opencode plugin add)dsh plugin add + df install-dsh (bundle auto-wires the base entry)
Review UIInstant TUI modals, never feed the LLMHost commands returning text

Bold marks where DSH currently enforces harder — the host exposes pre-terminal hooks, tool-call blocking, and human approval, so the same verdict bites earlier and louder there. OpenCode keeps the edge in install simplicity and instant review UI; both run the identical gate contract (typecheck, tests, acceptance, review artifact, max_blocks budgeting).

Identical on both: pre-execute deny hardness, pre-flight ordering and semantics, block budgeting, protect_off scope, and all eight df-*/dev_framework_* command and tool names. Details: docs/user/enforcement.md (OpenCode), docs/user/dsh.md (DSH).

What it does

  • Constitution injection. Adds a project quality bar to the system prompt at session start (bundled default, overridable per project).
  • Guardrails. Blocks or warns on protected paths (.env, vendored code, your own globs) and dangerous shell commands (git push, rm -rf).
  • Per-edit lint. Runs your linter on each edited file. On OpenCode the result is logged against the landed edit; on DSH a finding fails the tool call so the agent retries clean in the same turn.
  • Completion gate. At the would-go-idle boundary, runs typecheck, tests, acceptance checks, and (optionally) lint on changed files — plus a required substantive peer-review artifact in standard/strict (length floors, no template checkboxes, written after the latest session edit). On OpenCode, failures steer the session back via a synthetic continuation, bounded by gate.max_blocks (fewer when the failure repeats with no new edits — the gate stands down early on zero progress). On DSH the same verdict runs pre-terminal in the same turn — no re-prompt round-trip.
  • Verified goals (/df-goal). Wraps a task in native /goal with a verification contract the reviewer weighs as evidence.
  • Pre-flight gate (optional). Denies edits until the agent records required upfront research.
  • Custom tools + CLI. dev_framework_* tools for in-agent use; df init [--dsh] / profile / status / version / install-dsh --profile <name> from the shell (children may not invoke gate tools — deny + redirect).

Minimal configuration

Create .dev-framework.yml in your project root (the legacy .opencode-dev-framework.yml name is still read when no neutral-named file exists):

profile: standard

commands:
  typecheck: "npm run typecheck"
  test: "npm test"

Full reference (all keys, acceptance checks, pre-flight, rule overrides): docs/user/configuration.md. Copy-paste starters: examples/go-service/.

How it fits together

Every session runs the same loop — constitution, guardrails, lint, gate — whether or not it starts under /df-goal. A goal just wraps that loop in native verification. The diagram below shows the OpenCode wiring (idle synthetic continuation); on DSH the same verdict bites earlier — the pre-terminal completion block, same-turn lint blocks, and dispatched reviewers above all run inside the turn instead of round-tripping through it:

                        user prompt
                  (plain or /df-goal plan)
                                |
                                v
                       agent implements
                                |
                                v
                       tool.execute.before
                        /                \
                     allow                deny: protected / dangerous / pre-flight
                       |                                |
                       v                                v
                   edit lands                 BLOCKED before landing
                       |
                       v
           per-edit lint + change tracker
                /                         \
               v                           v
agent runs dev_framework_verify        session idle
               |                               |
               v                               v
            verdict               completion gate (same full contract)
             /    \                     |             |               |                    |
          PASS    FAIL                 PASS    within max_blocks   past max_blocks   identical x3, no new edits
            |       |                   |             |               |                    |
            v       v                   v             v               v                    v
      gate green   loops back         done     synthetic          STAND DOWN (honest unmet report)
      (in a goal:  to agent                        continuation
       evidence     implements                            |
       into /goal)                                        v
                                                 loops back to agent implements

wrappers (dotted lines in the diagram version):
  /df-goal plan (optional) ── delegates once, appends contract ──> native /goal (owns objective + review)
  native /goal ── wraps the loop, drives turns ──> agent implements

The diagram version of this flow (rendered on GitHub) lives in docs/user/enforcement.md — update both together.

Profiles

ProfileGuardrailsGate failuresLint on editPre-flightReview requiredNotes
offdisablednot reportednononoPlugin registers no hooks at all.
advisorywarnwarnyeswarn onlywarned, not blockedNothing blocks; everything is logged.
standarddenyerroryesdeny editsblocks completionThe default when a config file exists.
strictdenyerroryesdeny editsblocks completionAlso lints changed files in the gate.

How each layer is enforced, and what it honestly cannot do: docs/user/enforcement.md.

Commands

CommandWhat it does
/df-statusInstant modal: profile, guardrails, gate, configured commands.
/df-runtimeInstant modal: plugin version + live hook/gate runtime state.
/df-helpInstant modal: lists the dev-framework commands.
/df-profileInstant modal picker (or /df-profile <name>): switches profile now, written to config.
/df-verifyRuns the verification suite manually; pass/fail summary in a modal.
/df-initServer-side command: scaffolds templates, writes the detected config, trial-runs it, hands the brief to the agent.
/df-updateServer-side command: diffs installed templates against shipped, refresh/add each with user approval (detection only, never writes). Drift is also mentioned once at session startup.
/df-goal <objective>Server-side command: starts a verified native goal (requires native /goal, a blocking profile, and at least one real check).

The TUI commands open instantly and never feed the LLM; /df-init, /df-update, and /df-goal are server-side and drive the session. Same eight names on DSH, where they run as host commands returning text instead of modals. Full reference: docs/user/commands.md.

Limitations (short version)

Both harnesses

  • Completion enforcement is bounded by gate.max_blocks (and stands down earlier after repeated failures with no new edits). Stand-down is loud, and you can always close the session; this is not an unlimited trap.
  • Pre-flight and guardrail denials are pre-edit hard blocks, distinct from the bounded completion mechanisms below.
  • A cached pass never survives a restart — after a restart the gate always re-verifies the final tree from scratch.
  • Formatting and linting stay with your project tooling — the framework does not reimplement them.

OpenCode

  • A failed completion gate admits a synthetic continuation at the idle boundary. A genuine pre-stop veto was proposed upstream (anomalyco/opencode#54487, closed unmerged) — restoration is tracked in docs/plans/08-notes.md if the hook ever lands.
  • Guardrails add to OpenCode permissions; they never replace them. Formatting is OpenCode core's job, not the plugin's.

DSH

  • In standard/strict, a failed completion gate blocks termination pre-terminal and enqueues required same-turn work until pass or stand-down.
  • After a restart, all prior gate state is unknown (block budget included) — the gate re-verifies from scratch. df-status reports continuity per session (clean, resumed after interruption, or unknown).
  • Human approval prompts, reviewer dispatch, and the read-only reviewer preset depend on services provided by the DSH profile. Missing optional services disable only their enhancement; df-status reports the seams. df install-dsh handles the profile-dependent preset wiring.

Full story: docs/user/enforcement.md (OpenCode), docs/user/dsh.md (DSH).

Troubleshooting

Duplicate plugin IDs, stale npm cache, TUI not loading, version matrix: docs/user/troubleshooting.md.

Contributing

AGENTS.md is the canonical contributor contract. Build/test commands and the release path: docs/dev/contributing.md.

Disclaimer

This plugin changes how an AI agent behaves in your repository. Review the constitution, protected paths, and gate commands before enabling the standard or strict profiles, and start with advisory if you want to observe behavior without enforcement.

License

MIT

관련 플러그인