|
| 1 | +--- |
| 2 | +description: Generate or update AGENTS.md documentation for a source folder |
| 3 | +argument-hint: <folder-path, e.g., src/tools> |
| 4 | +--- |
| 5 | + |
| 6 | +# Generate Folder Documentation |
| 7 | + |
| 8 | +Generate or update the `AGENTS.md` file for the folder: `$ARGUMENTS` |
| 9 | + |
| 10 | +## Process |
| 11 | + |
| 12 | +1. **Explore the folder**: Read every file in `$ARGUMENTS/` to understand: |
| 13 | + - What each file does |
| 14 | + - Key exports (functions, types, interfaces, classes) |
| 15 | + - Design patterns used |
| 16 | + - Dependencies on other modules (imports from outside the folder) |
| 17 | + - How other modules depend on this one (search for imports of this folder across src/) |
| 18 | + |
| 19 | +2. **Check for existing AGENTS.md**: If `$ARGUMENTS/AGENTS.md` already exists, read it and update it rather than replacing from scratch. Preserve any manually-added context that is still accurate. |
| 20 | + |
| 21 | +3. **Check related test files**: Look in `tests/` for test files that mirror this folder structure. Note which files have tests and which do not. |
| 22 | + |
| 23 | +4. **Generate the AGENTS.md** following this template: |
| 24 | + |
| 25 | +~~~markdown |
| 26 | +# <Module Name> |
| 27 | + |
| 28 | +<One paragraph summary: what this module does, why it exists, and its role in the bashkit system.> |
| 29 | + |
| 30 | +## Files |
| 31 | + |
| 32 | +| File | Purpose | |
| 33 | +|------|---------| |
| 34 | +| `filename.ts` | One-line description of what this file does | |
| 35 | + |
| 36 | +## Key Exports |
| 37 | + |
| 38 | +List the most important public exports that other modules or consumers use: |
| 39 | + |
| 40 | +- `functionName(params)` -- What it does |
| 41 | +- `InterfaceName` -- What it represents |
| 42 | + |
| 43 | +## Architecture |
| 44 | + |
| 45 | +Describe how the files in this folder relate to each other. Include: |
| 46 | +- Internal dependency graph (which files import from which) |
| 47 | +- Key data flows |
| 48 | +- Important abstractions |
| 49 | + |
| 50 | +## Design Patterns |
| 51 | + |
| 52 | +Document specific patterns used in this module with brief rationale: |
| 53 | +- **Pattern name** -- How it is applied and why |
| 54 | + |
| 55 | +## Integration Points |
| 56 | + |
| 57 | +How this module connects to the rest of bashkit: |
| 58 | +- **Depends on**: Which other `src/` folders this module imports from |
| 59 | +- **Used by**: Which other `src/` folders import from this module |
| 60 | +- **Exported from**: Whether/how it surfaces in `src/index.ts` |
| 61 | + |
| 62 | +## Common Modifications |
| 63 | + |
| 64 | +### <Task: e.g., "Adding a new tool"> |
| 65 | +1. Step-by-step instructions |
| 66 | +2. Files to modify |
| 67 | +3. Gotchas to watch out for |
| 68 | + |
| 69 | +## Testing |
| 70 | + |
| 71 | +- List relevant test files in `tests/` |
| 72 | +- Note any gaps in test coverage |
| 73 | +- Describe how to run tests for this module: `bun test tests/<path>` |
| 74 | +~~~ |
| 75 | + |
| 76 | +## Guidelines |
| 77 | + |
| 78 | +- Write for an AI coding agent that needs to understand and modify this module |
| 79 | +- Be precise about file names and function signatures |
| 80 | +- Include actual type signatures where they clarify the API |
| 81 | +- Keep descriptions factual and concise -- no marketing language |
| 82 | +- Use the `.nullable()` convention note where relevant to tool schemas |
| 83 | +- Note any breaking change risks for public API surface |
| 84 | +- Do NOT include code examples that duplicate the root AGENTS.md (which covers consumer-facing usage) |
| 85 | +- Focus on INTERNAL architecture, not external API usage |
| 86 | +- Keep total length under 200 lines -- this should be a quick-reference, not a novel |
0 commit comments