Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.ts
index 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 instea
use \`agent/instructions.ts\` or files under \`agent/instructions/\`. You do not
need 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 integrations
diff --git a/packages/eve/src/setup/scaffold/index.integration.test.ts b/packages/eve/src/setup/scaffold/index.integration.test.ts
index 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");