Skip to content

Latest commit

 

History

History
205 lines (163 loc) · 8.47 KB

AGENTS.md

File metadata and controls

205 lines (163 loc) · 8.47 KB

AGENTS.md — opencode-dev-framework

Context file for AI agents working on the opencode-dev-framework project.

Project purpose

opencode-dev-framework is an OpenCode plugin that enforces project-specific quality gates during AI coding sessions. It is inspired by anticomputer/dev-framework but is an independent, OpenCode-native implementation.

The plugin provides:

  • Constitution / rule injection per model request (session.hook("context")), with local override and style-guide auto-discovery.
  • Protected-path guardrails and dangerous-command blocking (tool.hook("execute.before")).
  • Per-edit lint feedback, with optional pre-commit delegation (event.subscribe on filesystem.changed).
  • A completion gate (tests / type-check / lint) that runs at the would-go-idle boundary (session.hook("experimental.idle"), same execution via session.synthetic) with an event.subscribe idle net for the boundaries the hook skips — on failure inside gate.max_blocks, admits a synthetic continuation (synthetic-first, prompt only as fallback).

There is no synchronous pre-stop veto — the gate continues the turn via synthetic at the idle boundary (same execution), with the event net as fallback for skip paths. gate.max_blocks is plugin-owned (no core 3-cap). See docs/plans/12-idle-hook-cutover.md and docs/plans/04-hook-mapping.md.

Tech stack

  • Language: TypeScript
  • Runtime target: Bun (OpenCode uses Bun to load plugins; V2 tui.tsx via Solid)
  • Development runtime: Node.js v22 + npm (Bun is not installed on this box)
  • Package manager: npm for development; npm publishing
  • Build output: dist/
  • Test runner: vitest
  • Formatter & Linter: Biome (dev dependency)
  • Markdown linter: markdownlint-cli2
  • Plugin API: @opencode/plugin ^2 (@opencode/plugin/tui for TUI, solid-js peer)

Linting and formatting

We enforce code style automatically. The exact tools are configured in package.json, but the interface is:

# Check formatting, lint, and import organization (all three in one).
# The switch from `lint` to `check` is what enforces organization —
# `organizeImports` is pinned explicitly on in biome.json but Biome
# defaults it on already.
npm run check

# Fix all of the above where auto-fixable
npm run check:fix

# Check formatting only
npm run format:check

# Fix formatting
npm run format:fix

# Check TypeScript lint only
npm run lint

# Fix TypeScript lint where auto-fixable
npm run lint:fix

# Check Markdown lint
npm run lint:md

Before finishing any change:

  1. Run npm run check. If it fails, run npm run check:fix.
  2. Run npm run lint:md on any Markdown files you changed.
  3. Re-run npm run check and npm run lint:md to confirm everything is clean.
  4. Do not suppress lint warnings without a comment explaining why.

If you add a new file, make sure it is covered by the biome.json files.include glob.

Build / test / validate

Run these before finishing any change:

npm install
npm run check
npm run lint:md
npm run typecheck
npm run test
npm run build

OpenCode loads the plugin via Bun at runtime, but all development and CI on this box use npm/Node. Keep the code Bun-compatible: avoid Node-only APIs and prefer standard ESM imports.

Conventions

  • Keep the plugin lightweight. Avoid heavy runtime dependencies.
  • Prefer explicit types. Use Zod for config validation.
  • Use a stubbed HostContext in unit tests; do not shell out to real tools in tests.
  • Match behavior across profiles (off, advisory, standard, strict) consistently.
  • When in doubt, document the limitation in docs/plans/08-notes.md.

Important rules

Do

  • Run npm run test after any code change.
  • Run npm run build and verify dist/ is produced.
  • Update tests when adding or changing behavior.
  • Update docs/plans/05-implementation-checklist.md when a task is done.
  • Keep README.md accurate with install/config instructions.
  • Keep AGENTS.md and the plan docs in docs/plans/ accurate as the project evolves.
  • Prefer real YAML/JSON for .dev-framework.yml; the legacy .opencode-dev-framework.yml name is still read as a fallback.

Don't

  • Don't rewrite opencode.json automatically from the plugin.
  • Don't claim the completion gate can hard-block OpenCode from finishing. The gate continues the turn via synthetic at the idle boundary (same execution), bounded by gate.max_blocks (plugin-owned, no core 3-cap) — it is a bounded continuation, not a veto, and the user can still close the session. The event.subscribe idle net covers the boundaries the hook skips (see /df-status Continuation (idle)). The pre-flight gate, by contrast, genuinely hard-blocks: it denies edit tools in tool.execute.before before the edit lands.
  • Don't add heavy dependencies without discussing.
  • Don't commit dist/, node_modules/, or lockfiles unless intentionally releasing.
  • Never push to remote. Commit changes locally only. Pushing releases or changes is a deliberate user action, not an agent action.

Project layout

opencode-dev-framework/
├── src/                    # Plugin source code
│   ├── core/               # Harness-agnostic shared core (no host imports)
│   │   ├── block-store.ts  # Persistent gate block counts (StorageLike inlined)
│   │   ├── command-utils.ts# Shared command parsing helpers
│   │   ├── config.ts       # Config loader
│   │   ├── detect.ts       # Project language/tooling auto-detection
│   │   ├── format-status.ts# Shared status renderer
│   │   ├── gate.ts         # Completion gate
│   │   ├── harness.ts      # Pre/post-flight harness (verdict runner)
│   │   ├── host.ts         # RunCommand abstraction
│   │   ├── lint.ts         # Per-edit lint + format runners
│   │   ├── protect.ts      # Guardrail logic (+ `decideFileGuard`/`decideShellGuard` seam)
│   │   ├── run-hooks.ts    # Shared HookState + per-edit/gate flows
│   │   └── …               # commands, rules, registry, logger, types, …
│   ├── adapters/
│   │   ├── opencode/       # OpenCode registration (Plugin.define, thin)
│   │   │   └── index.ts    # Plugin entry point (package main)
│   │   └── dsh/            # DSH Cordis wiring over core (plan 25)
│   │       ├── index.ts    # apply(ctx): pre/post-execute, turn-stopping
│   │       └── extract.ts  # DSH envelope → core guard inputs (pure)
├── tui.tsx                 # TUI plugin (Plugin.define via @opencode/plugin/tui, slot+keymap.layer)
├── bin/
│   └── df                  # df init / profile / status / version CLI
├── templates/              # Project scaffolding templates
│   └── .opencode/          # agents, skills, local rules dir
├── rules/                  # Bundled constitution (numbered, loaded sorted)
│   ├── 00-activation.md
│   ├── 10-quality-bar.md
│   ├── 20-match-existing-patterns.md
│   ├── 30-testing-discipline.md
│   └── 40-delegation.md
├── tests/                  # Unit tests
├── examples/               # Example project configs
│   └── go-service/
├── docs/plans/             # Implementation plans
│   ├── 00-restart-brief.md
│   ├── 01-master-plan.md
│   ├── 02-architecture.md
│   ├── 03-config-spec.md
│   ├── 04-hook-mapping.md
│   ├── 05-implementation-checklist.md
│   ├── 06-testing-strategy.md
│   ├── 07-publishing.md
│   └── 08-notes.md
├── package.json
├── tsconfig.json
└── README.md

Committing

  • Commit work locally when a logical unit is complete and all validation passes.
  • Never push to remote. The user controls when and if anything is published.
  • Use clear, concise commit messages. Prefer present tense and describe what the change does.

Example:

git add src/config.ts tests/config.test.ts
git commit -m "feat: add config loader with .dev-framework.yml fallback"

Planning docs

The authoritative plan lives in docs/plans/. Start any new session with docs/plans/00-restart-brief.md, then read the relevant detailed doc for the area you are changing.

Restart brief

If you are resuming work:

  1. Read docs/plans/00-restart-brief.md.
  2. Read docs/plans/05-implementation-checklist.md to see what is done.
  3. Pick the next unchecked item.
  4. Run npm run test frequently.