The Open Framework for Building Agents
perf: streamline generated authoring guidance (#2267)
Colton Padden97d166a89774
diff --git a/.changeset/swift-authoring-guidance.md b/.changeset/swift-authoring-guidance.mdnew file mode 100644index 000000000..5c1ff0dd2--- /dev/null+++ b/.changeset/swift-authoring-guidance.md@@ -0,0 +1,5 @@+---+"eve": patch+---++New eve projects now give coding agents direct documentation routes and a bounded authoring loop, including a local recipe for routine typed tools. This reduces redundant project and package discovery while preserving deeper guidance for approvals and other advanced behavior.diff --git a/packages/eve/src/setup/scaffold/create/project.ts b/packages/eve/src/setup/scaffold/create/project.tsindex 0a3a42dfa..72ebdb5ef 100644--- a/packages/eve/src/setup/scaffold/create/project.ts+++ b/packages/eve/src/setup/scaffold/create/project.ts@@ -299,13 +299,64 @@ instructions. Fresh projects use \`agent/instructions.md\`; a project may insteause \`agent/instructions.ts\` or files under \`agent/instructions/\`. You do notneed to read the framework docs for a content-only instructions change.-Before adding or changing eve framework features such as tools, connections,-channels, skills, subagents, schedules, authentication, or deployment, read the-relevant guide from the installed eve package docs. In most installs, those docs-are at \`node_modules/eve/docs/\`. In workspaces or local package installs,-resolve the installed \`eve\` package location first and read its \`docs/\`-directory. If package docs are unavailable, use https://eve.dev/docs as a-fallback.+Before adding or changing eve framework features, classify the requested+capability. A self-contained typed tool can use the routine recipe below without+further discovery. For other changes, open the relevant guide directly from the+installed eve package docs:++- tools beyond the routine recipe: \`node_modules/eve/docs/tools/overview.mdx\`+- tool approvals: \`node_modules/eve/docs/tools/human-in-the-loop.md\`+- connections: \`node_modules/eve/docs/connections/overview.mdx\`+- channels: \`node_modules/eve/docs/channels/overview.mdx\`+- skills: \`node_modules/eve/docs/skills.mdx\`+- subagents: \`node_modules/eve/docs/subagents/index.mdx\`+- schedules: \`node_modules/eve/docs/schedules.mdx\`+- authentication: \`node_modules/eve/docs/guides/auth-and-route-protection.md\`+- deployment: \`node_modules/eve/docs/guides/deployment/overview.md\`++Use a bounded authoring loop:++1. Read this file and the relevant guide's opening example and contract.+2. Inspect only existing files you will modify or need to imitate.+3. Stop discovery once the file location, imports, and definition shape are+ clear. Implement the smallest complete behavior the user requested.+4. Run one narrow verification. Expand investigation only when it fails or the+ request needs project-specific integration details.++Do not create a plan or todo list for a contained one-file change. Do not+recursively glob \`node_modules\`, enumerate the entire docs tree, or read+unrelated scaffold files when the direct path is known. Package-manager links+can hide files from recursive glob tools even though direct reads work.++In workspaces or local package installs where \`node_modules/eve\` is absent,+resolve it with \`realpath node_modules/eve\` or the package manager, then open+the same path below its \`docs/\` directory. If package docs are unavailable,+use https://eve.dev/docs as a fallback.++## Routine typed tools++For a self-contained typed action, the standard shape is enough; do not inspect+unrelated agent config or invent a third-party integration the user did not ask+for:++\`\`\`ts+// agent/tools/<tool_name>.ts — the filename supplies the tool name.+import { defineTool } from "eve/tools";+import { z } from "zod";++export default defineTool({+ description: "Describe when the model should call this tool.",+ inputSchema: z.object({ value: z.string() }),+ async execute({ value }) {+ return { value };+ },+});+\`\`\`++Omitting \`approval\` allows calls without human approval, equivalent to+\`approval: never()\`. Read the tools guide when the implementation needs+approval, authentication, sandbox access, streaming output, or custom model+output.## Adding integrationsdiff --git a/packages/eve/src/setup/scaffold/index.integration.test.ts b/packages/eve/src/setup/scaffold/index.integration.test.tsindex 37565abc4..2c85e7573 100644--- a/packages/eve/src/setup/scaffold/index.integration.test.ts+++ b/packages/eve/src/setup/scaffold/index.integration.test.ts@@ -989,8 +989,16 @@ describe("scaffoldBaseProject", () => {expect(agentsMd).toContain("`agent/instructions.ts` or files under `agent/instructions/`");expect(agentsMd).toContain("Before adding or changing eve framework features");expect(agentsMd).toContain("installed eve package docs");- expect(agentsMd).toContain("node_modules/eve/docs/");- expect(agentsMd).toContain("resolve the installed `eve` package location");+ expect(agentsMd).toContain("node_modules/eve/docs/tools/overview.mdx");+ expect(agentsMd).toContain("node_modules/eve/docs/connections/overview.mdx");+ expect(agentsMd).toContain("Use a bounded authoring loop");+ expect(agentsMd).toContain("Stop discovery once the file location");+ expect(agentsMd).toContain("Do not create a plan or todo list");+ expect(agentsMd).toContain("recursively glob `node_modules`");+ expect(agentsMd).toContain("realpath node_modules/eve");+ expect(agentsMd).toContain("## Routine typed tools");+ expect(agentsMd).toContain('import { defineTool } from "eve/tools"');+ expect(agentsMd).toContain("Omitting `approval` allows calls without human approval");expect(agentsMd).toContain("eve registry search <query> --json");expect(agentsMd).toContain("eve registry view <item>");expect(agentsMd).toContain("eve add <item> --non-interactive");