From c7006c9e5f917fcac53ced1f86c4cad5b8dbb4ac Mon Sep 17 00:00:00 2001 From: Zeren Wang <53075619+Vanzeren@users.noreply.github.com> Date: Fri, 2 Oct 2026 15:41:03 +0200 Subject: [PATCH] docs: add extension-first evaluation gate to agent guidance (#6178) * docs: add extension-first evaluation gate to agent guidance Require AI coding agents to evaluate whether a feature can ship as a packaged extension before editing core code: route self-contained capabilities to the extension-api contribution points (middleware, observers, services, routers, full-stack plugins), keep bug fixes and agent-loop/memory/compaction/auth changes in core, and prefer adding a generic hook over hard-coding business logic when existing hooks fall short. Mirrored in compact form in copilot-instructions.md. * docs: fold extension gate into extensions paragraph, trim dated notes The agent-guidance CI hard limit (98304 bytes per AGENTS.md chain) left only ~53 bytes of headroom on the root file, so the gate moves from a new Cross-Cutting Conventions bullet into the existing extensions paragraph, and the dated skill-review and scheduled-task notes are compressed to their non-discoverable rules. Net effect: root AGENTS.md is ~190 bytes smaller than main. --- .github/copilot-instructions.md | 20 +++++++++++++++- AGENTS.md | 41 ++++++++++++++++++--------------- 2 files changed, 41 insertions(+), 20 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 1f3497a0ff..f3dc726cc8 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -202,7 +202,25 @@ Important root entries: - `config.example.yaml` - `extensions_config.example.json` -## 9) Instruction Priority +## 9) Extension-First Feature Evaluation + +Before implementing a feature by editing core code, evaluate whether it can ship as a +packaged extension instead (non-invasive contribution). The public extension contract +(`backend/packages/extension-api/`) supports: middleware, task-lifecycle and +model/context observers, Gateway services, FastAPI routers, and full-stack plugins +(model tools + browser pages). + +- Use an extension when the capability is self-contained and expressible through those + contribution points. +- Stay in core for bug fixes and for changes to the agent loop, memory, context + compaction, or authentication. +- If existing hooks cannot express the feature, extend `extension-api` with a generic + hook and build the feature as an extension — do not hard-code business logic into core. + +Authoritative details: `AGENTS.md` (the extensions paragraph in "Repository Map") and +`backend/packages/harness/deerflow/extensions/AGENTS.md`; examples in `examples/`. + +## 10) Instruction Priority Trust this onboarding guide first. diff --git a/AGENTS.md b/AGENTS.md index bdca8853ba..a6a40ab4c3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -84,6 +84,14 @@ contribution contract live in [the extensions guide](backend/packages/harness/deerflow/extensions/AGENTS.md); the user manual is `frontend/src/content/{en,zh}/harness/extensions/`. +**Extension-first evaluation** — before implementing a feature by editing core code, +evaluate whether it can ship as a packaged extension through the contribution points +above. Stay in core for bug fixes and for changes to the agent loop, memory, context +compaction, or authentication. If existing hooks cannot express the feature, add a +generic hook to the extension contract plus an extension that uses it — do not +hard-code business logic into core. Working examples: +`examples/deerflow-extension-{example,bookmarks}`. + Runtime config lives at the **repo root**: copy `config.example.yaml` → `config.yaml` (main app config) and `extensions_config.example.json` → `extensions_config.json` (MCP servers + skills). Both real files are gitignored and may be edited at runtime via the @@ -91,27 +99,22 @@ Gateway API. Config schema and resolution order are documented in [backend/AGENTS.md](backend/AGENTS.md). Skill quality review note: -- `skills/public/skill-reviewer/` is the built-in read-only skill quality reviewer. - It uses the harness-layer `review_skill_package` tool and contracts in - `contracts/skill_review/`. Model-visible review data is compact and - tag-neutralized; full raw payloads stay in tool artifacts. See - [backend/AGENTS.md](backend/AGENTS.md) for the non-activation, SkillScan, and - `skill-creator` ownership boundaries. -- CI waivers live in `.github/skill-review-waivers.v1.json` and are enforced by - `scripts/review_changed_public_skills.py`. Pull requests may validate waiver - edits from their head revision, but only the manifest from the trusted base - revision can suppress that run. Entries match one error finding exactly, - include the reviewed file's SHA-256 and an expiry date, remain visible in CI - output, and can never waive blocker findings. An entry may also preapprove - future full-file SHA-256 values, effective only once the manifest change lands - in the trusted base — so relying on a waiver takes two merges: the manifest - first, the skill change after, then promote the consumed hash to `file_sha256` - in a follow-up cleanup. +- `skills/public/skill-reviewer/` is the built-in read-only reviewer (harness tool + `review_skill_package`, contracts in `contracts/skill_review/`). Model-visible review + data is tag-neutralized; raw payloads stay in tool artifacts. See + [backend/AGENTS.md](backend/AGENTS.md) for the ownership boundaries. +- CI waivers live in `.github/skill-review-waivers.v1.json`, enforced by + `scripts/review_changed_public_skills.py`. Only the manifest from the trusted base + revision can suppress a run, and blocker findings can never be waived. Scheduled-task note: -- The scheduled-task MVP adds a workspace page at `/workspace/scheduled-tasks` plus a background scheduler service gated by `config.yaml -> scheduler.enabled`. -- Scheduled background runs are intentionally non-interactive: the lead-agent toolset excludes `ask_clarification` when `context.non_interactive=true`. That key, `disable_clarification`, and `github_token` are honored only for internally-authenticated callers; client-supplied copies are dropped from both `body.context` and `body.config`. -- Busy scheduled occurrences are persisted as `queued`; `launching` is a short lease-fenced claim, `running` remains the normal Gateway run lifecycle, and `scheduler.queue_timeout_seconds` bounds the durable wait. Do not reintroduce skip-on-overlap or count waiting rows against `max_concurrent_runs`. +- The scheduled-task MVP adds a workspace page at `/workspace/scheduled-tasks` plus a + background scheduler gated by `config.yaml -> scheduler.enabled`. +- Scheduled runs are non-interactive: `ask_clarification` is excluded. `non_interactive`, + `disable_clarification`, and `github_token` are honored only for internally-authenticated + callers; client-supplied copies are dropped. +- Busy occurrences persist as `queued`; `scheduler.queue_timeout_seconds` bounds the wait. + Do not reintroduce skip-on-overlap. ## Commands: Root vs. Module