@psnext/s-subagents 0.1.20260522-1

package/.slingshot/agentHooks.json

@@ -0,0 +1,24 @@
+[
+  {
+    "id": "hook-1779457904343-864",
+    "name": "Code review",
+    "description": "Review the code for all coding standard",
+    "triggerType": "file_saved",
+    "filePaths": "src/*.js",
+    "prompt": "Analyze the recently saved file and provide a comprehensive code review with actionable feedback. Focus on:\n\n**Code Quality & Standards:**\n- Adherence to language-specific coding conventions and style guidelines\n- Proper naming conventions for variables, functions, and classes\n- Code structure, readability, and maintainability\n- Consistent formatting and indentation\n\n**Best Practices:**\n- Error handling and edge case management\n- Performance considerations and potential optimizations\n- Security vulnerabilities or concerns\n- Code reusability and DRY principles\n- Proper commenting and documentation\n\n**Technical Review:**\n- Logic correctness and potential bugs\n- Resource management (memory, file handles, connections)\n- Appropriate use of design patterns\n- Type safety and null checks where applicable\n\n**Output Format:**\nProvide specific, line-referenced feedback when possible. Categorize issues by severity (Critical, Major, Minor, Suggestion). Include positive observations alongside improvement recommendations. Keep comments constructive and educational, explaining the \"why\" behind each suggestion.\n\nIf no issues are found, acknowledge good practices observed in the code.",
+    "agentId": "coding-agent",
+    "parameters": {
+      "task": "Analyze the recently saved file and provide a comprehensive code review with actionable feedback. Focus on:\n\n**Code Quality & Standards:**\n- Adherence to language-specific coding conventions and style guidelines\n- Proper naming conventions for variables, functions, and classes\n- Code structure, readability, and maintainability\n- Consistent formatting and indentation\n\n**Best Practices:**\n- Error handling and edge case management\n- Performance considerations and potential optimizations\n- Security vulnerabilities or concerns\n- Code reusability and DRY principles\n- Proper commenting and documentation\n\n**Technical Review:**\n- Logic correctness and potential bugs\n- Resource management (memory, file handles, connections)\n- Appropriate use of design patterns\n- Type safety and null checks where applicable\n\n**Output Format:**\nProvide specific, line-referenced feedback when possible. Categorize issues by severity (Critical, Major, Minor, Suggestion). Include positive observations alongside improvement recommendations. Keep comments constructive and educational, explaining the \"why\" behind each suggestion.\n\nIf no issues are found, acknowledge good practices observed in the code.",
+      "files": [
+        "src/*.js"
+      ],
+      "context": "Review the code for all coding standard"
+    },
+    "enabled": false,
+    "createdBy": "user",
+    "tags": [],
+    "debounceDuration": "120000",
+    "createdAt": "2026-05-22T13:51:44.411Z",
+    "updatedAt": "2026-05-22T13:51:44.411Z"
+  }
+]

package/.slingshot/code-tagging/51adc022-context.json

@@ -0,0 +1,15 @@
+{
+  "filename": "index.ts",
+  "path": "index.ts",
+  "version": "1.1",
+  "files": {},
+  "promptMessage": {
+    "0dbda967": {
+      "value": "Cannot find name 'node:child_process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.ts"
+    }
+  },
+  "localPrompts": {},
+  "remotePrompts": {},
+  "figma": {},
+  "jira": {}
+}

package/.slingshot/code-tagging/51adc022-lock.json

@@ -0,0 +1,101 @@
+{
+  "index.ts": {
+    "filename": "index.ts",
+    "path": "index.ts",
+    "version": "1.2",
+    "contextFile": "51adc022-context.json",
+    "chunks": {
+      "33a9a4": {
+        "user": "Rakesh Ravuri",
+        "model": "claude-sonnet-4-5@20250929",
+        "timestamp": 1779458883,
+        "platform": "VisualStudioCode",
+        "product": "AIPP",
+        "productVersion": "2.5.0",
+        "source": "chat",
+        "type": "compareCode",
+        "extraContext": {
+          "promptMessage": "0dbda967"
+        },
+        "hash": "0d52ee42",
+        "messageId": "system_980f1e50-55e7-11f1-92a0-cdb27b9735e4",
+        "codeBlockId": "system_980f1e50-55e7-11f1-92a0-cdb27b9735e4-Codeblock-2",
+        "isActive": false
+      },
+      "ee44cb": {
+        "user": "Rakesh Ravuri",
+        "model": "claude-sonnet-4-5@20250929",
+        "timestamp": 1779458886,
+        "platform": "VisualStudioCode",
+        "product": "AIPP",
+        "productVersion": "2.5.0",
+        "source": "chat",
+        "type": "insertCode",
+        "extraContext": {
+          "promptMessage": "0dbda967"
+        },
+        "hash": "0d52ee42",
+        "messageId": "system_980f1e50-55e7-11f1-92a0-cdb27b9735e4",
+        "codeBlockId": "system_980f1e50-55e7-11f1-92a0-cdb27b9735e4-Codeblock-2",
+        "isActive": true
+      },
+      "3caf2e": {
+        "user": "Rakesh Ravuri",
+        "model": "claude-sonnet-4-5@20250929",
+        "timestamp": 1779458886,
+        "platform": "VisualStudioCode",
+        "product": "AIPP",
+        "productVersion": "2.5.0",
+        "source": "chat",
+        "type": "pasteCode",
+        "extraContext": {
+          "promptMessage": "0dbda967"
+        },
+        "hash": "0d52ee42",
+        "messageId": "system_980f1e50-55e7-11f1-92a0-cdb27b9735e4",
+        "codeBlockId": "system_980f1e50-55e7-11f1-92a0-cdb27b9735e4-Codeblock-2",
+        "isActive": false
+      }
+    },
+    "lines": {
+      "32": {
+        "chunkId": "ee44cb",
+        "hash": "699fd80f",
+        "encoded": "%7D",
+        "prevChunkIds": []
+      },
+      "55": {
+        "chunkId": "ee44cb",
+        "hash": "2ef1d392",
+        "encoded": "%7D",
+        "prevChunkIds": []
+      },
+      "71": {
+        "chunkId": "ee44cb",
+        "hash": "f064f9d6",
+        "encoded": "%7D",
+        "prevChunkIds": []
+      },
+      "429": {
+        "chunkId": "ee44cb",
+        "hash": "bd760bbf",
+        "encoded": "%7D,",
+        "prevChunkIds": [
+          "ee44cb"
+        ]
+      },
+      "872": {
+        "chunkId": "ee44cb",
+        "hash": "c3395656",
+        "encoded": "%7D,",
+        "prevChunkIds": []
+      },
+      "913": {
+        "chunkId": "ee44cb",
+        "hash": "f8f5c1fc",
+        "encoded": "%7D,",
+        "prevChunkIds": []
+      }
+    }
+  }
+}

package/.slingshot/code-tagging/5a95fab8-lock.json

@@ -0,0 +1,87 @@
+{
+  "tsconfig.json": {
+    "filename": "tsconfig.json",
+    "path": "tsconfig.json",
+    "version": "1.2",
+    "contextFile": null,
+    "chunks": {
+      "ba71e7": {
+        "user": "Rakesh Ravuri",
+        "model": "claude-sonnet-4-5@20250929",
+        "timestamp": 1779458900,
+        "platform": "VisualStudioCode",
+        "product": "AIPP",
+        "productVersion": "2.5.0",
+        "source": "chat",
+        "type": "createFileWithCode",
+        "extraContext": {},
+        "hash": "0d52ee42",
+        "messageId": "2f82f3d1-de96-4e70-b6f0-6bd10a200ad6",
+        "codeBlockId": null,
+        "isActive": true
+      }
+    },
+    "lines": {
+      "0": {
+        "chunkId": "ba71e7",
+        "hash": "47009686",
+        "encoded": "%7B",
+        "prevChunkIds": []
+      },
+      "1": {
+        "chunkId": "ba71e7",
+        "hash": "c1221f13",
+        "encoded": "%22compilerOptions%22:%20%7B",
+        "prevChunkIds": []
+      },
+      "2": {
+        "chunkId": "ba71e7",
+        "hash": "dbfbff26",
+        "encoded": "%22types%22:%20%5B%22node%22%5D,",
+        "prevChunkIds": []
+      },
+      "4": {
+        "chunkId": "ba71e7",
+        "hash": "57c8aecd",
+        "encoded": "%22esModuleInterop%22:%20true,",
+        "prevChunkIds": []
+      },
+      "5": {
+        "chunkId": "ba71e7",
+        "hash": "54a5ae06",
+        "encoded": "%22skipLibCheck%22:%20true,",
+        "prevChunkIds": []
+      },
+      "6": {
+        "chunkId": "ba71e7",
+        "hash": "fe5f646c",
+        "encoded": "%22target%22:%20%22ES2020%22,",
+        "prevChunkIds": []
+      },
+      "9": {
+        "chunkId": "ba71e7",
+        "hash": "e58a5dfb",
+        "encoded": "%7D,",
+        "prevChunkIds": []
+      },
+      "10": {
+        "chunkId": "ba71e7",
+        "hash": "ce5ebcb5",
+        "encoded": "%22include%22:%20%5B%22**/*.ts%22%5D,",
+        "prevChunkIds": []
+      },
+      "11": {
+        "chunkId": "ba71e7",
+        "hash": "b7a45cbe",
+        "encoded": "%22exclude%22:%20%5B%22node_modules%22%5D",
+        "prevChunkIds": []
+      },
+      "12": {
+        "chunkId": "ba71e7",
+        "hash": "6a3f2143",
+        "encoded": "%7D",
+        "prevChunkIds": []
+      }
+    }
+  }
+}

package/.slingshot/prompts/sample.prompt.md

@@ -0,0 +1,118 @@
+
+  SAMPLE LOCAL PROMPT
+  ───────────────────────────────
+  Welcome to your Slingshot Local Prompt setup!
+
+  ───────────────────────────────
+  HOW IT WORKS
+  ───────────────────────────────
+  You can add your own ".prompt.md" files under either of these folders available at the root of your repository
+  (In case you don't see these folders, you can either create them manually or follow the steps mentioned below):
+
+      • .slingshot/prompts/   ← recommended option
+      • .github/prompts/
+
+  All prompt files with the ".prompt.md" extension inside these folders are automatically available in the Prompt Select Drawer.
+
+  ───────────────────────────────
+  HOW TO CREATE A PROMPT
+  ───────────────────────────────
+  You can create a new prompt file by:
+    • Clicking on "Add/Edit Prompt File" from the Slash Command Drawer
+      OR
+    • Running the Slingshot command "Create or Open Prompt File"
+
+  ───────────────────────────────
+  HOW TO USE A PROMPT
+  ───────────────────────────────
+  You can use your local prompt by:
+    • Clicking on "Attach Prompt Commands" from the Slash Command Drawer
+      OR
+    • Typing the shortcut key "~" in the chat input box
+
+  The filename of your prompt will act as the command name.
+  You can use multiple local prompts at a time, but only one non-local prompt.
+
+  ───────────────────────────────
+  USING PLACEHOLDERS AND VARIABLES
+  ───────────────────────────────
+  You can reference the following VSCode workspace variables in your prompts: 
+  When creating custom prompts, users can reference the following workspace variables to dynamically insert context-specific information:
+
+- ${userHome}: Path of the user's home folder.
+- ${workspaceFolder}: Path of the folder opened in VS Code.
+- ${workspaceFolderBasename}: Name of the folder opened in VS Code without any slashes (/).
+- ${file}: Currently opened file.
+- ${fileWorkspaceFolder}: Currently opened file's workspace folder.
+- ${relativeFile}: Currently opened file relative to workspaceFolder.
+- ${relativeFileDirname}: Currently opened file's dirname relative to workspaceFolder.
+- ${fileBasename}: Currently opened file's basename.
+- ${fileBasenameNoExtension}: Currently opened file's basename with no file extension.
+- ${fileExtname}: Currently opened file's extension.
+- ${fileDirname}: Currently opened file's folder path.
+- ${fileDirnameBasename}: Currently opened file's folder name.
+- ${cwd}: Task runner's current working directory upon the startup of VS Code.
+- ${lineNumber}: Currently selected line number in the active file.
+- ${columnNumber}: Currently selected column number in the active file.
+- ${selectedText}: Currently selected text in the active file.
+- ${execPath}: Path to the running VS Code executable.
+- ${pathSeparator}: Character used by the operating system to separate components in file paths.
+
+  Additionally, you can define custom placeholders such as "{file_name}". These placeholders can be replaced with specific values when the prompt is used.
+
+  **Rules for Placeholders:**
+  - Do not include special characters like "?", "*", "+", "^", "|", "&", "!", "@", "#", "$", "%", "^", "(", ")", "=", "[", "]", ";", ":", "'", """, "<", ">", ",", ".", "/", "", "~", and "" ` "" within placeholders.
+  - Do not use double curly brackets "{{}}".
+  - Ensure placeholders are clearly defined and meaningful.
+
+  ───────────────────────────────
+  ENVIRONMENT VARIABLES
+  ───────────────────────────────
+  You can reference environment variables from your system using the %{VARIABLE_NAME} syntax:
+
+  Common examples:
+  - %{HOME}: User's home directory path
+  - %{USER}: Current username  
+  - %{PATH}: System PATH environment variable
+  - %{NODE_ENV}: Node.js environment (development, production, etc.)
+  - %{API_KEY}: Custom API keys or secrets
+  - %{DATABASE_URL}: Database connection strings
+
+  You can also reference local environment variables defined in your .env file
+
+  Example usage:
+  "Hello %{USER}! Working in %{NODE_ENV} environment from %{HOME} working on %{MY_CUSTOM_VAR}"
+
+  Note: Environment variables are resolved at prompt execution time, if you add new variables to your .env file, you may need to refresh VS Code window. Type %{ in your prompt to see available variables with autocomplete.
+
+  ───────────────────────────────
+  REFERENCING PROMPTS AND FILES
+  ───────────────────────────────
+  You can reference other local prompts and files within a prompt: 
+    • Reference prompts using ~{promptname} syntax.
+    • Reference files using #{path/to/file.txt} syntax.
+
+  ───────────────────────────────
+  SAMPLE PROMPT
+  ───────────────────────────────
+  For example:
+
+      My Custom Code Generation Prompt
+      --------------------------------
+      ## Follow all the below best practices while generating code
+
+      - Ensure code readability with meaningful variable and function names
+      - Maintain consistent formatting and indentation
+      - Avoid deep nesting and keep functions short and focused
+      - Handle errors and exceptions gracefully
+      - Write efficient and performant logic
+      - Add comments where necessary for complex logic
+      - Follow security best practices and avoid hardcoding secrets
+      - Include necessary input validations and edge case handling
+      - Prefer reusability and modularity over duplication
+      - Follow project-specific coding conventions and linting rules
+
+  ───────────────────────────────
+  TIP
+  ───────────────────────────────
+  Keep your prompts clear, short, and well-structured for the best results.

package/.slingshot/prompts_cache.json

@@ -0,0 +1 @@
+{}

package/.slingshot/skills_cache.json

@@ -0,0 +1 @@
+{}

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "Slingshot.readFileLineLimit": 3000
+}

package/README.md

@@ -0,0 +1,164 @@
+# Minimal Subagents
+
+A [sling](https://www.npmjs.com/package/@psnext/slingcli) extension that registers a single `subagent` tool with three agents:
+
+| Agent | Tools | Model | Purpose |
+|-------|-------|-------|---------|
+| **scout** | read, grep, find, ls | claude-haiku-4-5 | Fast codebase recon |
+| **researcher** | web_search, web_fetch | claude-sonnet-4-6 | Web research |
+| **worker** | read, write, edit, safe_bash, web_search, web_fetch, subagent | claude-sonnet-4-6 | Code changes (can dispatch scout/researcher to protect its own context) |
+
+`worker` is allowlisted to spawn only `scout` and `researcher` (via `subagent_agents` in its frontmatter), so the chain stops at depth 2 — a worker cannot recurse into another worker.
+
+## Dependencies
+
+`safe_bash` ships in this repo (`tools/safe-bash.ts`). `web_search` and `web_fetch` do not — `researcher` and `worker` depend on them. Grab those two extensions from [amosblomqvist/pi-config](https://github.com/amosblomqvist/pi-config) (`extensions/web-search/`, `extensions/web-fetch/`) and drop them into `~/.pi/agent/extensions/`. Without them the affected agents will launch with an empty tool allowlist and silently do nothing useful.
+
+## Usage
+
+One tool call = one subagent:
+```json
+{ "agent": "scout", "task": "Find all auth-related files in src/" }
+```
+
+To fan out, emit multiple `subagent` tool calls in the same assistant turn — pi runs them in parallel automatically. A per-process semaphore caps simultaneous subagents at `maxConcurrency` (default 4); calls past the cap wait their turn.
+
+Each subagent runs as an isolated `pi` process with no inherited context — all context must be in the task description.
+
+## Config
+
+Optional `config.json` next to `index.ts`:
+
+```json
+{ "maxConcurrency": 4 }
+```
+
+## Output
+
+Subagents return text only — there's no file handoff. If the parent needs artifacts, instruct the subagent to `write` them and return the path.
+
+Large outputs (>`DEFAULT_MAX_BYTES`) are head-truncated before being returned to the parent.
+
+## UI
+
+Two levels, toggled with `ctrl+o`:
+
+- **Collapsed (default):** the tool call shows one line — `subagent <agent> <60-char task preview>`. The result block shows the agent header (status, tool count, duration), the chronological tool log (one line per call, running calls marked with `▸`), the latest prose "thinking" line, and a usage line (tokens in/out, cache, cost, context-window gauge).
+- **Expanded:** the call header streams the full task body live as the parent writes it (like `write`/`edit`). The result block additionally renders the subagent's full final output as markdown. Nested children (when a worker spawns scout/researcher) render inline, indented under the row that dispatched them, with their own per-row context gauge.
+
+## Registering Agents from Other Extensions
+
+Other extensions can dynamically register and unregister agents at runtime. This is useful for domain-specific agents that should only be available when a particular extension is active.
+
+### 1. Define agent `.md` files
+
+Create markdown files with YAML frontmatter in your extension's directory (e.g. `my-extension/agents/my-agent.md`):
+
+```markdown
+---
+name: my-agent
+description: Does a specific thing
+tools: web_search, video_extract
+model: claude-sonnet-4-20250514
+---
+
+You are an agent that does a specific thing...
+```
+
+Frontmatter fields:
+- **name** (required) — unique agent name, used in `{ agent: "my-agent" }` calls
+- **description** — short description
+- **tools** — comma-separated list of tools the agent needs (builtin or extension). Include `subagent` here to let this agent spawn other agents.
+- **model** — model identifier (defaults to `anthropic/claude-sonnet-4-6`)
+- **thinking** — reasoning level: `off`, `low`, `medium`, `high` (defaults to `medium`)
+- **subagent_agents** — if `subagent` is in `tools`, restrict which agents this one may spawn. Comma-separated list of agent names. Omit for no restriction. Enforced by passing `PI_SUBAGENT_ALLOWED` env to the child `pi` process — the child's subagents extension filters its registry before any tool description sees it, so the child LLM literally can't reference an agent outside the allowlist.
+
+The markdown body becomes the agent's system prompt.
+
+### 2. Register agents via `globalThis.__pi_subagents`
+
+Pi loads extensions via jiti, which creates separate module instances. Direct imports from the subagents extension will reference a different `agents` array than the one the `subagent` tool uses. Use the `globalThis` bridge instead:
+
+```typescript
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+interface AgentConfig {
+  name: string;
+  description: string;
+  tools: string[];
+  model: string;
+  thinking: string;        // "off" | "low" | "medium" | "high"
+  systemPrompt: string;
+  filePath: string;
+  subagentAgents?: string[]; // optional spawn-allowlist when `subagent` is in tools
+}
+
+const AGENTS_DIR = path.join(path.dirname(new URL(import.meta.url).pathname), "agents");
+
+function registerMyAgents(): void {
+  const subagents = (globalThis as any).__pi_subagents as
+    | { registerAgent: (config: AgentConfig) => void; unregisterAgent: (name: string) => void }
+    | undefined;
+  if (!subagents) return; // subagents extension not loaded
+
+  for (const entry of fs.readdirSync(AGENTS_DIR)) {
+    if (!entry.endsWith(".md")) continue;
+    const filePath = path.join(AGENTS_DIR, entry);
+    const content = fs.readFileSync(filePath, "utf-8");
+    const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+    if (!frontmatter.name) continue;
+
+    const tools = (frontmatter.tools || "").split(",").map(t => t.trim()).filter(Boolean);
+    const subagentAgents = frontmatter.subagent_agents
+      ? frontmatter.subagent_agents.split(",").map(t => t.trim()).filter(Boolean)
+      : undefined;
+    try {
+      subagents.registerAgent({
+        name: frontmatter.name,
+        description: frontmatter.description || "",
+        tools,
+        model: frontmatter.model || "anthropic/claude-sonnet-4-6",
+        thinking: frontmatter.thinking || "medium",
+        systemPrompt: body,
+        filePath,
+        ...(subagentAgents ? { subagentAgents } : {}),
+      });
+    } catch {
+      // Already registered — skip
+    }
+  }
+}
+```
+
+Call `registerMyAgents()` when your extension activates (e.g. in a command handler). The agents become available to the `subagent` tool immediately.
+
+### 3. Adding custom tool support
+
+If your agents need tools beyond the built-in set, those tools must be mapped in the `CUSTOM_TOOL_EXTENSIONS` record in `subagents/index.ts`:
+
+```typescript
+const CUSTOM_TOOL_EXTENSIONS: Record<string, string> = {
+  web_search: path.join(EXT_BASE, "web-search", "index.ts"),
+  web_fetch: path.join(EXT_BASE, "web-fetch", "index.ts"),
+  safe_bash: path.join(TOOLS_DIR, "safe-bash.ts"),
+  video_extract: path.join(EXT_BASE, "video-extract", "index.ts"),
+  youtube_search: path.join(EXT_BASE, "youtube-search", "index.ts"),
+  google_image_search: path.join(EXT_BASE, "google-image-search", "index.ts"),
+};
+```
+
+Built-in tools (`read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`) work automatically. Any other tool the agent lists in its frontmatter must have a corresponding entry here pointing to the extension's `index.ts`.
+
+The `subagent` tool itself is listed in `CUSTOM_TOOL_EXTENSIONS` pointing back to this extension's own `index.ts` — that's how an agent like `worker` can recursively spawn other agents. Recursion is bounded only by each agent's `subagent_agents` allowlist (e.g. worker can spawn scout/researcher, neither of which declares the `subagent` tool, so the chain stops at depth 2).
+
+## Structure
+
+```
+subagents/
+├── index.ts           # Extension entry point
+├── agents/            # Built-in agent configs (frontmatter + system prompt)
+└── tools/             # Extensions loaded into subagent processes
+    └── safe-bash.ts   # bash with dangerous command blocking
+```

package/agents/researcher.md

@@ -0,0 +1,47 @@
+---
+name: researcher
+description: Web researcher — searches the web and synthesizes findings
+tools: web_search, web_fetch
+model: claude-sonnet-4-5@20250929
+thinking: medium
+---
+
+You are a research specialist. Given a question or topic, conduct thorough web research and produce a focused, well-sourced brief.
+
+Process:
+1. Break the question into 2-4 searchable facets
+2. Search with `web_search` using varied angles
+3. Read the answers. Identify what's well-covered, what has gaps.
+4. For the 2-3 most promising source URLs, use `web_fetch` to get full page content
+5. Synthesize everything into a brief that directly answers the question
+
+Search strategy — always vary your angles:
+- Direct answer query (the obvious one)
+- Authoritative source query (official docs, specs, primary sources)
+- Practical experience query (case studies, benchmarks, real-world usage)
+- Recent developments query (only if the topic is time-sensitive)
+
+Evaluation — what to keep vs drop:
+- Official docs and primary sources outweigh blog posts and forum threads
+- Recent sources outweigh stale ones
+- Sources that directly address the question outweigh tangentially related ones
+- Drop: SEO filler, outdated info, beginner tutorials (unless that's the audience)
+
+If the first round of searches doesn't fully answer the question, search again with refined queries targeting the gaps.
+
+Output format:
+
+## Summary
+2-3 sentence direct answer.
+
+## Findings
+Numbered findings with inline source citations:
+1. **Finding** — explanation. [Source](url)
+2. **Finding** — explanation. [Source](url)
+
+## Sources
+- Kept: Source Title (url) — why relevant
+- Dropped: Source Title — why excluded
+
+## Gaps
+What couldn't be answered. Suggested next steps.

package/agents/scout.md

@@ -0,0 +1,36 @@
+---
+name: scout
+description: Fast codebase recon — explores files, finds patterns, maps architecture
+tools: read, grep, find, ls
+model: gpt-5.4-nano
+thinking: medium
+---
+
+You are a scout agent. Quickly investigate a codebase and return structured findings.
+
+Thoroughness (infer from task, default medium):
+- Quick: Targeted lookups, key files only
+- Medium: Follow imports, read critical sections
+- Thorough: Trace all dependencies, check tests/types
+
+Strategy:
+1. grep/find to locate relevant code
+2. Read key sections (not entire files)
+3. Identify types, interfaces, key functions
+4. Note dependencies between files
+
+Output format:
+
+## Files Found
+List with exact line ranges:
+1. `path/to/file.ts` (lines 10-50) — Description
+2. `path/to/other.ts` (lines 100-150) — Description
+
+## Key Code
+Critical types, interfaces, or functions with actual code snippets.
+
+## Architecture
+Brief explanation of how the pieces connect.
+
+## Start Here
+Which file to look at first and why.