feat: Add examples & some lightweight configuration docs

README.md

@@ -13,9 +13,11 @@ The rise of AI-powered code generation tools like Cursor, GitHub Copilot, and Cl
 - **Agents don't know how to configure their environment** - Agents need to run certain commands that usually require some sort of environment (aka how do you run E2E tests without your `.env` setup properly)
 
 We need our agents to not only generate code, but validate that the code they wrote:
-- ✅ passes tests
-- ✅ is formatted correctly
-- ✅ can transpile
+
+- ✅ actually works, aka it passes tests
+- ✅ is formatted correctly, aka it passes linting and formatting
+- ✅ can transpile, aka it passes type-checking
+- ✅ can run, aka it can be run locally
 
 ## The Standard
 
@@ -53,7 +55,7 @@ What this does in this case is allow for the `scripts` (aka `tasks`) to run usin
 
 #### Monorepository
 
-The `agents.js` standard also supports the concept of monorepositories:
+The `agents.js` standard also supports the concept of monorepos:
 
 ```json
 {
@@ -111,4 +113,8 @@ You will need to configure the agents to utilize these commands, by updating you
 
 ### Examples
 
+Below are a list of open source projects that have implemented the `agents.js` standard:
+
+- [Viteval](https://github.com/viteval/viteval)
+
 You can view pre-built examples [here](./examples).

docs/configuration.md

@@ -0,0 +1,46 @@
+# Configuration
+
+You need to provide basic information about your project to the agent
+
+
+
+
+.you can this in one of the following ways:
+
+- Detection: let the agent detect the project type and configuration.
+- Manual: provide the information manually.
+
+## Manual
+
+Configure the 
+
+```markdown
+## Project Details
+
+
+```
+
+## Detection
+
+```markdown
+## Project Details
+
+### Package Manager
+
+You need to determine which package manager you are using:
+
+- If there is a `package-lock.json` file, you are using `npm`.
+- If there is a `yarn.lock` file, you are using `yarn`.
+- If there is a `pnpm-lock.yaml` file, you are using `pnpm`.
+
+### Monorepos
+
+You need to determine if you are using a monorepo, check the following in order:
+
+1. If there is a `turbo.json` file, you are using a `turbo` monorepo.
+2. If there is a `lerna.json` file, you are using a `lerna` monorepo.
+3. If there is a `nx.json` file, you are using a `nx` monorepo.
+4. If there is a `pnpm-workspace.yaml` file, you are using a `pnpm` monorepo.
+5. If the project has a `package.json` file in the root check if there is a "workspaces" field, that you are using a `npm` or `yarn` monorepo.
+```
+

examples/dotenv/biome.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.8.3/schema.json",
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  }
+}

examples/dotenv/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@examples/dotenv",
+  "description": "An example using dotenv",
+  "scripts": {
+    "agents": "dotenv -e .env.dev -- npm run",
+    "test": "node --test src/index.test.ts",
+    "check": "biome check src/",
+    "fix": "biome check --write src/",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "validate": "npm run check && npm run typecheck && npm run test"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "@biomejs/biome": "^1.8.3",
+    "typescript": "^5.0.0"
+  }
+}

examples/dotenv/src/index.test.ts

@@ -0,0 +1,7 @@
+import { test } from "node:test";
+import assert from "node:assert";
+import { openPodBayDoors } from "./index";
+
+test("should return false", () => {
+  assert.strictEqual(openPodBayDoors(), false);
+});

examples/dotenv/src/index.ts

@@ -0,0 +1,4 @@
+export function openPodBayDoors() {
+  console.log("I'm sorry, Dave. I'm afraid I can't do that.");
+  return false;
+}

examples/dotenv/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

examples/infisical/biome.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.8.3/schema.json",
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  }
+}

examples/infisical/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@examples/npm",
+  "description": "An example using npm",
+  "scripts": {
+    "agents": "CI=true npm run",
+    "test": "node --test src/index.test.ts",
+    "check": "biome check src/",
+    "fix": "biome check --write src/",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "validate": "npm run check && npm run typecheck && npm run test"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "@biomejs/biome": "^1.8.3",
+    "typescript": "^5.0.0"
+  }
+}

examples/infisical/src/index.test.ts

@@ -0,0 +1,7 @@
+import { test } from "node:test";
+import assert from "node:assert";
+import { openPodBayDoors } from "./index";
+
+test("should return false", () => {
+  assert.strictEqual(openPodBayDoors(), false);
+});

examples/infisical/src/index.ts

@@ -0,0 +1,4 @@
+export function openPodBayDoors() {
+  console.log("I'm sorry, Dave. I'm afraid I can't do that.");
+  return false;
+}

examples/infisical/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

examples/npm/biome.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.8.3/schema.json",
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  }
+}

examples/npm/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@examples/infisical",
+  "description": "An example using infisical",
+  "scripts": {
+    "agents": "infisical run --projectId=agent-project --env=dev --silent -- npm run",
+    "test": "node --test src/index.test.ts",
+    "check": "biome check src/",
+    "fix": "biome check --write src/",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "validate": "npm run check && npm run typecheck && npm run test"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "@biomejs/biome": "^1.8.3",
+    "typescript": "^5.0.0"
+  }
+}

examples/npm/src/index.test.ts

@@ -0,0 +1,7 @@
+import { test } from "node:test";
+import assert from "node:assert";
+import { openPodBayDoors } from "./index";
+
+test("should return false", () => {
+  assert.strictEqual(openPodBayDoors(), false);
+});

examples/npm/src/index.ts

@@ -0,0 +1,4 @@
+export function openPodBayDoors() {
+  console.log("I'm sorry, Dave. I'm afraid I can't do that.");
+  return false;
+}

examples/npm/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}