@agent-smith/feat-agents 0.0.1 → 0.0.2

package/dist/skills/create-project-docs/SKILL.md

@@ -9,12 +9,15 @@ Create or update the documentation files that help AI agents navigate a codebase
 
 | File | Scope | Purpose |
 |------|-------|---------|
-| `AGENTS.md` | Project root | Index with reading order + links to other docs |
-| `.agents/documentation/codebase-summary.md` | Every repo/module | Standardized technical summary (7 sections) |
+| `AGENTS.md` | Project root | Index with mission, conventions, quick start, and doc links |
+| `<repo>/AGENTS.md` | Each repo (multi-repo only) | Localized context for agents working in that repo |
+| `.agents/documentation/decision-tree.md` | Project root only | Quick guide: find the right doc for your task |
+| `.agents/documentation/project-overview.md` | Project root only | Concise project overview (~1 page) |
+| `.agents/documentation/codebase-summary.md` | Every repo/module | Standardized technical summary (7 core + optional sections) |
 | `.agents/documentation/project-nav.md` | Project root only | Comprehensive navigation map |
 
-> **Single-repo projects**: All 3 files live at the project root.
-> **Multi-repo projects**: `AGENTS.md` and `project-nav.md` at workspace root; each repo gets its own `AGENTS.md` and `codebase-summary.md`.
+> **Single-repo projects**: All 5 files live at the project root.
+> **Multi-repo projects**: `AGENTS.md`, `decision-tree.md`, `project-overview.md`, and `project-nav.md` at workspace root; each repo gets its own `AGENTS.md` and `codebase-summary.md`.
 
 ## Workflow
 
@@ -22,103 +25,272 @@ Execute steps in order:
 
 ### 1. Explore the Project
 
-Walk the directory tree. Identify repos, packages/modules, entry points, dependencies, and key files. Read manifest or config files to understand structure and language.
+Walk the directory tree. Identify repos, packages/modules, entry points, dependencies, and key files. Read manifest or config files to understand structure and language. Identify key conventions and patterns used by the project.
 
 ### 2. Create AGENTS.md (Project Root)
 
+Use this exact structure:
+
 ```markdown
 # <Project Name>
 
-## Reading Order for AI Agents
+## Mission
+<One-line mission statement describing what the project does and its core capabilities.>
 
-1. **Start here** → This file is your index
-2. **Comprehensive reference** → `.agents/documentation/project-nav.md` — Full project map
-3. **Technical summary** → `.agents/documentation/codebase-summary.md` — Dependencies, entry points, key files
-4. **Per-repo navigation** → Each repo has its own `AGENTS.md` and `.agents/documentation/codebase-summary.md`
+## Repositories
 
----
+| Repo | Path | Purpose |
+|------|------|---------|
+| `<repo-name>` | `</workspace/repo-path/>` | <One-line description> |
 
-This is a <language> project for <purpose>. It contains these repositories:
+## Conventions (for AI Agents)
 
-- `<repo-name>` — <one-line description>
+- **<Convention name>**: <Brief description of the pattern>
 - ...
 
-Documentation:
+## Quick Start for AI Agents
+
+1. Read `.agents/documentation/decision-tree.md` to find the right doc for your task
+2. Read `.agents/documentation/project-overview.md` for high-level context
+3. Read `.agents/documentation/project-nav.md` for detailed navigation and dependency graph
+4. Navigate to the relevant repo/package and read its `.agents/documentation/codebase-summary.md`
 
-- `.agents/documentation/codebase-summary.md`: top-level codebase summary
-- `.agents/documentation/project-nav.md`: navigation map
-- `<repo>/.agents/documentation/codebase-summary.md`: per-repo summaries
+## Documentation
+
+- `.agents/documentation/decision-tree.md` — Quick guide: find the right doc for your task
+- `.agents/documentation/codebase-summary.md` — Top-level codebase summary (structured, machine-readable)
+- `.agents/documentation/project-overview.md` — Concise project overview (~1 page)
+- `.agents/documentation/project-nav.md` — Detailed navigation map with dependency graph
+- `<repo>/.agents/documentation/codebase-summary.md` — <Repo> summary
+- ...
+
+Each package or library directory has `.agents/documentation/codebase-summary.md`. Use them to navigate in the codebase easily.
 ```
 
-### 3. Create codebase-summary.md (Every Repo/Module)
+**Rules for AGENTS.md**:
+- **Mission**: One concise sentence capturing the project's purpose and capabilities
+- **Repositories table**: Include all repos with path and one-line purpose
+- **Conventions**: List 3-5 key patterns AI agents need to know (tool formats, file structures, state management, etc.)
+- **Quick Start**: Always list `decision-tree.md` FIRST, then `project-overview.md`, then `project-nav.md`, then per-repo summaries
+- **Documentation**: List all doc files with brief descriptions
+
+### 3. Create Per-Repo AGENTS.md (Multi-Repo Projects Only)
 
-Use exactly these 7 sections in this order:
+For multi-repo projects, create an `AGENTS.md` in each repository so agents navigating directly to a repo have localized context:
 
 ```markdown
-# <module-name>
+# <Repo Name>
 
-## Summary
-One sentence: what the module does.
+## Mission
+<One-line mission statement for this specific repo.>
 
-## Dependencies
-- `<internal-dep>` — what it provides
-- External: `<library>` (<purpose>)
+## Structure
 
-## Used By
-- `<consumer>` — why it uses this module
+| Directory | Purpose |
+|-----------|---------|
+| `<dir>` | <One-line description> |
 
-## Entry Point
-- `<path>` — one-line description
+## Conventions
 
-## Key Files
-| File | Purpose |
-|------|---------|
-| `<path>` | One-line: what the file does |
+- **<Convention>**: <Brief description> (repo-specific patterns)
 
-## Architecture
-- 2–4 bullets on design patterns and data flow.
+## Quick Start for AI Agents
 
-## Related
-- See `<module>` — how they work together
+1. Read `.agents/documentation/codebase-summary.md` for technical summary
+2. Explore key files listed in codebase-summary.md
+3. <Build/run instructions specific to this repo>
 
 ## Documentation
+
+- `.agents/documentation/codebase-summary.md` — Technical summary of this repo
+- `../../AGENTS.md` — Project-wide context and conventions (workspace root)
+```
+
+**Rules for per-repo AGENTS.md**:
+- **Self-contained**: Should be useful for agents working directly in that repo
+- **Structure table**: List key directories with one-line purposes
+- **Conventions**: Include repo-specific conventions (subset of or additions to root conventions)
+- **Quick Start**: Always reference the local codebase-summary.md first
+- **Documentation**: Always link back to root `../../AGENTS.md` for project-wide context
+- **Skip for single-repo**: Only create when there are multiple repos
+
+### 4. Create decision-tree.md (Project Root Only)
+
+Quick guide helping agents find the right documentation based on their task:
+
+```markdown
+# Documentation Decision Tree
+
+> Quick guide: What to read based on your task
+
+## I need to understand the project
+
+- High-level overview → `.agents/documentation/project-overview.md`
+- Full navigation map → `.agents/documentation/project-nav.md`
+- Structured summary → `.agents/documentation/codebase-summary.md`
+
+## I need to work on a specific repo/package
+
+- `<repo>` → `<repo>/.agents/documentation/codebase-summary.md`
+- ...
+
+<!-- OPTIONAL: For monorepos with sub-packages, add this section -->
+## I need to work on a specific package
+
+- `<package-name>` → `<repo>/packages/<package>/.agents/documentation/codebase-summary.md`
+- ...
+
+## I need detailed documentation
+
+- `<topic>` → `<path-to-docs>`
+- ...
+
+## Common Tasks (Quick Reference)
+
+| Task | Go To |
+|------|-------|
+| <Task description> | `<path>` |
+
+## Conventions
+
+- <Convention> — <Brief description>
+
+→ See `AGENTS.md` for full conventions summary.
+```
+
+**Rules for decision-tree.md**:
+- Organize by task type (understand project, work on specific area, detailed docs)
+- Include a "Common Tasks" table mapping tasks to paths
+- End with reference to AGENTS.md for full conventions
+- **Optional**: For monorepos with sub-packages, add a "I need to work on a specific package" section listing individual packages
+
+### 5. Create project-overview.md (Project Root Only)
+
+Concise ~1 page overview with these sections:
+
+```markdown
+# <Project Name> — Project Overview
+
+> **Role**: Concise "what is this" for context loading (~1 page overview).
+> **See also**: `.agents/documentation/decision-tree.md` to find the right doc for your task.
+> **See also**: `.agents/documentation/project-nav.md` for detailed navigation and task references.
+
+---
+
+## What is <Project Name>?
+
+<One paragraph describing the project, its purpose, and core capabilities.>
+
+---
+
+## Core Capabilities
+
+- **<Capability 1>** — <Brief description>
+- **<Capability 2>** — <Brief description>
+- ...
+
+---
+
+## Repository Structure
+
+| Repo | Path | Purpose |
+|------|------|---------|
+| `<repo>` | `<path>` | <Purpose> |
+
+---
+
+<!-- OPTIONAL: For monorepos with internal packages, add this section after Repository Structure -->
+## Runtime Packages (`<repo>/packages/`)
+
+| Package | Purpose |
+|---------|---------|
+| `<package>` | <One-line purpose> |
+
+---
+
+## Key Architecture Patterns
+
+- **<Pattern>**: <Brief description>
+- ...
+
+---
+
+## Quick Reference: Common Tasks
+
+| Task | Go To |
+|------|-------|
+| <Task> | `<path>` |
+
+---
+
+## Code Snippets
+
+### <Snippet Title>
+```<language>
+# Example code showing typical usage
+```
+
+---
+
+## Documentation Links
+
 | Resource | Path |
 |----------|------|
-| Full docsite | `<path>` |
-```
+| <Resource name> | `<path>` |
+
+**Rules for project-overview.md**:
+- Keep to ~1 page
+- Include header notes referencing decision-tree.md and project-nav.md
+- Include code snippets showing typical usage patterns
+- End with documentation links table
+- **Optional**: For monorepos with internal packages, add a "Runtime Packages" table after Repository Structure
+
+### 6. Create codebase-summary.md (Every Repo/Module)
 
-**Rules**: Information-dense, short. No project description (that's in project-nav.md). No architecture patterns duplicated from project-nav.md.
+Load and follow the `update-codebase-summary` skill for each repo/module. This specialized skill defines the standardized 7-section format (Summary, Dependencies, Used By, Entry Point, Key Files, Architecture, Related).
 
-### 4. Create project-nav.md (Project Root Only)
+> **Note**: Include the optional "Documentation" section ONLY in the project root `codebase-summary.md` — lists all doc resources with paths. Omit from per-repo/module summaries.
 
-Comprehensive map with these sections:
+### 7. Create project-nav.md (Project Root Only)
 
-1. **Project Overview** — What it does, repos/modules table, core capabilities
-2. **Architecture Principles** — Table: Principle | Detail | Key Files
-3. **Dependency Graph** — ASCII art showing module dependencies + prose explanation
-4. **Packages/Modules** — Per-module: Purpose, Key files, Key types/classes
-5. **Server** (if applicable) — Routes, key files, patterns
-6. **Plugins** (if applicable) — Categories, plugins table, key files
-7. **UI** (if applicable) — Components, services, themes, extensions
-8. **Apps** (if applicable) — Extensions, dependencies
-9. **Code Snippets** — Language-appropriate examples showing typical usage
-10. **Navigation Quick Reference** — Task → Path table for common development tasks
-11. **Documentation Links** — All doc resources with paths
-12. **Key Conventions & Patterns** — Naming, file structure, tool formats, etc.
+Load and follow the `update-project-nav` skill. This specialized skill defines all required sections (Project Overview, Architecture Principles, Dependency Graph, Packages/Modules, Code Snippets, Navigation Quick Reference, Documentation Links, Key Conventions & Patterns) and optional sections (Server, Plugins, UI, Apps, project-specific).
 
-Add header note: `> **Primary reference** — Comprehensive navigation map for the project.`
+> **Tip**: Number sections sequentially based on which ones you include. Skip numbers for omitted optional sections.
 
-### 5. Cross-Reference and Verify
+> **Note**: Include the header note: `> Purpose: Single-reference map for AI coding agents to understand, navigate, and modify the <Project Name> codebase.`
 
-- `AGENTS.md` → links to project-nav.md and codebase-summary.md
-- `codebase-summary.md` → Related section points to project-nav.md for overview
+### 8. Cross-Reference and Verify
+
+- Root `AGENTS.md` → links to decision-tree.md, project-overview.md, project-nav.md, codebase-summary.md, and per-repo AGENTS.md files
+- Per-repo `AGENTS.md` → links to local codebase-summary.md; links back to root `../../AGENTS.md` for project-wide context
+- `decision-tree.md` → references all doc files; ends with link to root AGENTS.md for conventions
+- `project-overview.md` → header notes reference decision-tree.md and project-nav.md
+- `codebase-summary.md` → Related section points to related modules
 - `project-nav.md` → no external cross-references needed (it's the primary source)
-- No duplicated content across files: project description, architecture patterns, quick-reference tables, and code snippets live ONLY in project-nav.md
+
+**No duplicated content across files**:
+- Project description, architecture patterns, code snippets, and quick-reference tables live ONLY in `project-nav.md` and `project-overview.md`
+- Per-module technical details (entry points, key files, dependencies) live in `codebase-summary.md`
+- Conventions summary lives in root `AGENTS.md`; decision-tree.md references it
+- Per-repo context (structure, repo-specific conventions) lives in per-repo `AGENTS.md`
 
 ## Rules
 
 - **No redundancy**: Each piece of information lives in exactly one file
-- **codebase-summary.md preserves format**: The 7-section structure is standardized — do not change it
+- **codebase-summary.md core format**: The 7-section structure (Summary, Dependencies, Used By, Entry Point, Key Files, Architecture, Related) is standardized — do not change the order or rename sections. Optional "Documentation" section may be added at the end for the project root only.
 - **Information-dense**: Keep files short. Use tables, bullets, one-line descriptions
 - **project-nav.md is canonical**: Single source of truth for project overview, architecture, snippets, and quick references
+- **decision-tree.md first**: Always the first file agents should read to find the right doc
 - **Language-agnostic**: Adapt examples and conventions to the project's language and ecosystem
+- **Adapt optional sections**: Include optional sections (sub-packages in decision-tree, Runtime Packages in project-overview, Documentation in codebase-summary, conditional sections in project-nav) only when they add value for the specific project
+
+## Related Skills
+
+| Skill | When to Use |
+|-------|-------------|
+| `update-codebase-summary` | Used in **step 6** to create/update each module's `.agents/documentation/codebase-summary.md` |
+| `update-project-nav` | Used in **step 7** to create/update the project root `.agents/documentation/project-nav.md` |
+| `document-package` | Create/update documentation for a package in the project docsite |
+| `update-doc-map` | Regenerate the documentation map (runs a script) |
+
+> **Tip**: Steps 6 and 7 load these specialized skills during initial creation. Use them again for ongoing targeted updates after code changes.

package/dist/skills/create-readme/SKILL.md

@@ -11,12 +11,13 @@ description: use this to create comprehensive README file for a given package or
 3. Locate target in the codebase summary (note its position, dependencies, and purpose)
 
 ### Phase 2: Deep Dive
-3. Navigate to directory: `/workspace/agent-smith/packages/{package-name}/` for a package, adapt the path
-4. Read `.agents/documentation/codebase-summary.md` for architecture, key files, and usage patterns
-5. Read documentation from `/workspace/agent-smith/docsite/public/doc/libraries/{package-name}/*.md` (get_started, usage, api)
+3. Use the `smart-explore` skill to walk the module's directory tree
+4. Navigate to directory: `/workspace/agent-smith/packages/{package-name}/` for a package, adapt the path
+5. Read `.agents/documentation/codebase-summary.md` for architecture, key files, and usage patterns
+6. Read documentation from `/workspace/agent-smith/docsite/public/doc/libraries/{package-name}/*.md` if it exists
 
 ### Phase 3: Synthesis & Writing
-6. Create `README.md` with this structure:
+7. Create `README.md` with this structure:
    - **Npm badge**: example:
       ```
       [![pub package](https://img.shields.io/npm/v/this-package-name)](https://www.npmjs.com/package/this-package-name)

package/dist/skills/create-task-from-template/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: create-task-from-template
+description: create an executable task by instantiating a task template with project-specific values
+---
+
+# Create Task from Template
+
+This skill creates an executable task by instantiating a reusable task template. Templates live in `.agents/task-templates/` and contain placeholder variables that get replaced with actual values.
+
+## Workflow
+
+### Step 1: Identify the Template
+
+1. Determine which template to use based on the task type
+2. Available templates are in `.agents/task-templates/`
+3. Load the template's `template.md` to understand required variables
+
+**Available Templates:**
+
+| Template | Purpose |
+|----------|---------|
+| `maintain-agent-docs` | Create/update agent navigation documentation (AGENTS.md, codebase-summary.md, project-nav.md, etc.) |
+
+### Step 2: Load the Template
+
+1. Read `template.md` to get metadata and required variables
+2. Read all template files (`goals.md`, `plan.md`, `state.md`)
+3. Identify all placeholder variables (format: `{variable-name}`)
+
+### Step 3: Gather Variable Values
+
+For each required variable:
+- **Infer from context** if possible (e.g., project name from AGENTS.md)
+- **Ask the user** if the value cannot be determined
+- Use these common sources:
+  - `AGENTS.md` — project name, repos, conventions
+  - `.agents/documentation/project-nav.md` — repo paths, architecture
+  - User's task description — specific scope and goals
+
+### Step 4: Instantiate the Task
+
+1. Create directory: `.agents/tasks/[task-name]/`
+2. For each template file:
+   - Read the template content
+   - Replace all `{variable-name}` placeholders with actual values
+   - Write the instantiated file to the task directory
+3. Generate a unique task name (e.g., `maintain-agent-docs-[date]` or user-specified name)
+
+### Step 5: Verify and Report
+
+1. Verify all placeholders were replaced (no remaining `{...}` patterns)
+2. Check that the instantiated task is coherent
+3. Report to user with summary
+
+## Output Format
+
+After instantiation:
+
+```
+Task Created from Template: [template-name]
+Task Name: [generated-task-name]
+Location: .agents/tasks/[task-name]/
+
+Variables Used:
+- {variable1}: value1
+- {variable2}: value2
+
+Files Created:
+- goals.md
+- plan.md
+- state.md
+- [additional files if template includes them]
+
+Next Step: Review the task and execute with `execute-task-solo` or `execute-task-team`
+```
+
+## Placeholder Conventions
+
+- All placeholders use `{variable-name}` format
+- Common variables:
+  - `{project-name}` — Project name
+  - `{repo-path}` — Path to repository
+  - `{module-name}` — Module/package name
+  - `{task-scope}` — Specific scope of this task instance
+  - `{changed-files}` — Files that changed (for update tasks)
+  - `{target-path}` — Where output should be placed
+
+## Example: Instantiating maintain-agent-docs Template
+
+**User Request:** "Update documentation for agent-smith-plugins after adding a new plugin"
+
+**Process:**
+1. Load `maintain-agent-docs` template
+2. Read `template.md` → requires: `{project-name}`, `{repo-path}`, `{changed-files}`
+3. Infer values:
+   - `{project-name}` = "Agent Smith" (from AGENTS.md)
+   - `{repo-path}` = "/workspace/agent-smith-plugins/"
+   - `{changed-files}` = User specifies: "new video plugin added"
+4. Instantiate task at `.agents/tasks/maintain-agent-docs-video-plugin/`
+5. All placeholders replaced, task is ready for execution
+
+## Rules
+
+- **Never skip variable gathering** — All required variables must have values
+- **Preserve template structure** — The instantiated task follows the same file layout
+- **Task name uniqueness** — Each instantiation gets a unique name
+- **Template is read-only** — Never modify the original template files
+- **Verify completeness** — Check no placeholders remain after instantiation

package/dist/skills/document-package/SKILL.md

@@ -1,83 +1,54 @@
 ---
 name: document-package
-description: use when asked to create or update package documentation in the docsite
+description: use when asked to create or update documentation for a package or module in the project docsite
 ---
 
-This skill describes the workflow to document a package for the Agent Smith CLI.
+This skill describes the workflow to document a package or module for the project's documentation site.
 
 ## Workflow
 
-Execute this one step after the other:
+Execute these steps in order:
 
 1. **Locate the package** — Read `.agents/documentation/codebase-summary.md` to find the package path
 
-2. **Read codebase summary** — Read `[package-path].agents/documentation/codebase-summary.md` (e.g., `agent-smith-plugins/system/shell/.agents/documentation/codebase-summary.md`). This provides a quick overview of tools, agents, dependencies, and architecture.
+2. **Read codebase summary** — Read `[package-path]/.agents/documentation/codebase-summary.md`. This provides a quick overview of tools, agents, dependencies, and architecture.
 
-3. **Read source code** — Inspect `src/actions/`, `dist/agents/*.yml`, `dist/tasks/*.yml` to identify tools, agents, and capabilities.
+3. **Read source code** — Inspect `src/` directories to identify key exports, capabilities, and usage patterns.
 
-4. **Find next number** — List existing docs in `agent-smith/docsite/public/doc/plugins/`. Use the next available number (e.g., if 1-8 exist, use 9).
+4. **Find next number** — List existing docs in the documentation directory. Use the next available number (e.g., if 1-8 exist, use 9).
 
-5. **Write the doc** at `agent-smith/docsite/public/doc/plugins/<N>.<name>.md` using this exact structure:
+5. **Write the doc** at `<docsite-path>/<category>/<N>.<name>.md` using this structure:
 
 ```markdown
 # <PackageName>
 
-![pub package](https://img.shields.io/npm/v/@agent-smith/feat-<name>)
-
 One-line description of what the package does.
 
 ## Install
 
-```bash
-npm i -g @agent-smith/feat-<name>
-```
-
-Add the package to your `config.yml` file and run the `conf` command:
-
-```yml
-plugins:
-  - "@agent-smith/feat-<name>"
-```
-
-```bash
-lm conf
-```
+<Installation instructions appropriate for the project's ecosystem>
 
-## Actions and tools
+## Features and Capabilities
 
 ### <category>
 
-Available tools:
-
-- <kbd>tool-name</kbd> one-line description of what it does (include container image if applicable)
-
-## Agents
+Available features:
 
-Available agents:
+- <kbd>feature-name</kbd> one-line description of what it does
 
-- <kbd>agent-name</kbd> one-line description. Lists tools used:
-    - `tool-a` — purpose
-    - `tool-b` — purpose
+## Usage
 
-## Example agent
-
-```yaml
-description: A brief description
-model: qwen4b
-toolsList:
-  - agent-name # this tool is a subagent
-```
+<Example code showing typical usage>
 
 ## Links
 
-Add a next page link. All internal links must be of this form:
-
-<a href="javascript:openLink('/plugins/overview')">Back: Overview</a>
+Add navigation links to related documentation.
 ```
 
 ## Rules
 
-- Keep it short and information-dense — match the style of `6.filesystem.md` and `8.search.md`
-- Use `<kbd>tool-name</kbd>` for all tools/agents
-- Use backticks `for tool names in prose
-- End with navigation link to overview (or next package if known)
+- **Keep it short and information-dense** — match the style of existing docs
+- Use `<kbd>feature-name</kbd>` for all tools/features
+- Use backticks `` ` `` for feature names in prose
+- End with navigation links to overview or related packages
+- **Language-agnostic**: Adapt installation, examples, and conventions to the project's ecosystem

package/dist/skills/execute-task-solo/SKILL.md

@@ -9,6 +9,7 @@ This skill describes how to execute a task created with `create-task-solo`. A si
 
 ## Task Location
 
+Use the `load-task` tool to load the task.
 Tasks are located in `.agents/tasks/[task-name]/` directory.
 
 ## Task Structure

package/dist/skills/execute-task-team/SKILL.md

@@ -5,6 +5,8 @@ description: use this to execute a team task (coordinator delegates phases to ex
 
 # Coordinator Agent Instructions (Task Execution)
 
+Use the `load-task` tool to load the task.
+
 ## Your Role
 You are the **Coordinator Agent**. Delegate phases to executor agents.
 

package/dist/skills/smart-explore/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: smart-explore
+description: use when exploring a project directory to discover structure while excluding noise (dependencies, build artifacts, version control)
+---
+
+Smart directory exploration for any project type. Discovers repos, packages, entry points, and key files while excluding noise that bloats context.
+
+## Exclusions
+
+### Always exclude
+`.git`, `node_modules`, `vendor`, `.venv`, `venv`, `dist`, `build`, `target`, `__pycache__`, `.cache`, `coverage`, `.idea`, `.vscode`, `.DS_Store`
+
+### Add when detected
+- Python: `.tox`, `.nox`, `.pytest_cache`, `.mypy_cache`
+- Rust: `.cargo/`
+- Java: `.gradle/`, `.mvn/`
+- .NET: `bin/`, `obj/`
+- Ruby: `.bundle/`, `tmp/`
+- PHP: `.composer/`
+
+## Workflow
+
+### 1. Read `.gitignore` (if exists)
+Add any additional exclusion patterns.
+
+### 2. Detect project type
+Check for manifest files: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Gemfile`, `pom.xml`, `composer.json`, `*.csproj`, `CMakeLists.txt`
+
+### 3. Walk directory tree
+Use `find` with exclusions. Start shallow (`-maxdepth 2`), go deeper only when needed.
+
+```bash
+find /workspace/<project> -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | head -50
+```
+
+### 4. Find packages
+Locate manifest files to identify all packages/repos.
+
+### 5. Read manifests
+For each package discovered, read its manifest to understand dependencies and structure.
+
+## Rules
+
+- Use `-maxdepth` to control depth; start shallow
+- Limit results with `head` to avoid overwhelming context
+- Adapt exclusions based on detected language/ecosystem
+- Skip binary files and large artifacts