AGENTS.md · diff

git:20260414.5728c7e to git:20260723.e470633

48 added, 265 removed. Audit A to A.

-

- ## Rules

- # Bun APIs

- **Prefer Bun over Node.js** when running in Bun environment.

- **File system:**

- - `Bun.file(path).exists()` not `fs.existsSync()`

- - `Bun.file(path).text()` not `readFileSync()`

- - `Bun.write(path, data)` not `writeFileSync()`

- *Verify:* `grep 'from .node:fs' src/`

- *Fix:* Replace with Bun.file/Bun.write

- **Shell commands:**

- - `Bun.$\`cmd\`` not `child_process.spawn()`

- *Verify:* `grep 'child_process' src/`

- *Fix:* Replace with Bun.$ template literal

- **Path resolution:**

- - `Bun.resolveSync()` for module resolution

- - `import.meta.dir` for current directory

- - Keep `node:path` for join/resolve/dirname

- *Verify:* Check for `process.cwd()` misuse

- **Executables:**

- - `Bun.which(cmd)` to check if command exists

- - `Bun.$\`bun add pkg\`` for package management

- **When Node.js OK:** readline (interactive input), node:path utilities, APIs without Bun equivalents

- **Docs:** https://bun.sh/docs

- # Workflow

- ## Git Commits

- **Conventional commits** - `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, `test:`

- **Multi-line messages** - Use for detailed context

- **Never --no-verify** - Fix the issue, don't bypass hooks

- *Verify:* Check git log format

- ## GitHub CLI

- **Use `gh` over WebFetch** - Better data access, auth, private repos

- **PR evaluation** - Fetch ALL sources:

- ```bash

- # 1. Comments/reviews

- gh pr view <n> --repo <owner>/<repo> --json title,body,comments,reviews,state

- # 2. Security alerts

- gh api repos/<owner>/<repo>/code-scanning/alerts

- # 3. Inline comments

- gh api repos/<owner>/<repo>/pulls/<n>/comments

- ```

- **PR checklist:**

- - [ ] Human reviewer comments

- - [ ] AI code review comments

- - [ ] Security alerts (ReDoS, injection)

- - [ ] Code quality comments

- - [ ] Inline suggestions

- **URL patterns:**

- | URL | Command |

- |-----|---------|

- | `github.com/.../pull/<n>` | `gh pr view <n> --repo ...` |

- | `github.com/.../issues/<n>` | `gh issue view <n> --repo ...` |

- | `.../security/code-scanning/<id>` | `gh api .../code-scanning/alerts/<id>` |

- **Review states:** `APPROVED`, `CHANGES_REQUESTED`, `COMMENTED`, `PENDING`

- # Module Organization

- **No index.ts** - Never use index files, they create implicit magic

- *Exception:* Plugin entry points under `plugins/` where the SDK requires `index.ts` as the entry file

- *Verify:* `find . -name 'index.ts' -not -path 'plugins/*/index.ts'`

- *Fix:* Rename to feature name: `feature/index.ts` → `feature.ts` at parent level

- **Explicit .ts extensions** - `import { x } from './file.ts'` not `'./file'`

- *Verify:* `grep "from '\./.*[^s]'" src/` (imports without .ts)

- *Fix:* Add `.ts` extension

- **Re-export at boundaries** - Parent `feature.ts` re-exports from `feature/feature.ts`

- ```mermaid

- graph TD

- A[src/] --> B[feature/]

- A --> C[feature.ts]

- B --> D[feature.ts]

- B --> E[tests/]

- E --> F[feature.spec.ts]

- C -.Re-exports.-> D

- ```

- **File organization within modules:**

- - `feature.types.ts` - Type definitions only

- - `feature.schemas.ts` - Zod schemas + `z.infer<>` types

- - `feature.constants.ts` - Constants, error codes

- - `feature.ts` - Main implementation

- **Direct imports** - Import from specific files, not through re-exports within module

- *Verify:* Check for circular imports

- *Fix:* Import directly: `from './feature.types.ts'` not `from './feature.ts'`

- # Testing

- **Use test not it** - `test('description', ...)` instead of `it('...')`

- *Verify:* `grep '\bit(' src/**/*.spec.ts`

- *Fix:* Replace `it(` with `test(`

- **No conditional assertions** - Never `if (x) expect(x.value)`

- *Verify:* `grep 'if.*expect\|&&.*expect' src/**/*.spec.ts`

- *Fix:* Assert condition first: `expect(x).toBeDefined(); expect(x.value)...`

- **Test both branches** - Try/catch, conditionals, fallbacks need both paths tested

- *Verify:* Review test coverage for error paths

- *Fix:* Add test for catch block, else branch, fallback case

- **Use real dependencies** - Prefer installed packages over mocks when testing module resolution

- *Verify:* Review test imports for fake paths

- *Fix:* Use actual package like `typescript`

- **Organize with describe** - Group related tests in `describe('feature', () => {...})`

- *Verify:* Check for flat test structure

- *Fix:* Add describe blocks by category (happy path, edge cases, errors)

- **Coverage checklist** - Happy path, edge cases, error paths, real integrations

- *Verify:* Review test file completeness

- **Docker tests** - `*.docker.ts` for external APIs, run via docker-compose

- *Verify:* Check if test needs API key or external service

- *Fix:* Rename to `.docker.ts`, update CI gating

- **Run:** `bun test` before commit

- # Accuracy

- **95% confidence threshold** - Report uncertainty rather than guess

- **Verification first** - Read files before stating implementation details

- *Verify:* Did you read the file before commenting on it?

- **When uncertain:**

- - State the discrepancy clearly

- - Explain why you can't confidently recommend a fix

- - Present issue to user for resolution

- - Never invent solutions

- **TypeScript verification** - Use LSP tools for type-aware analysis:

- - `lsp-find` - Search symbols across workspace

- - `lsp-refs` - Find all usages before modifying

- - `lsp-hover` - Verify type signatures

- - `lsp-analyze` - Batch analysis of file structure

- **Dynamic exploration:**

- - Read tool for direct file verification

- - Grep/Glob for content and pattern searches

- - Prioritize live code over cached knowledge

- **Agent-specific applications:**

- - Documentation: Only update TSDoc if types match current code

- - Architecture: Verify patterns exist in codebase

- - Code review: Read files before commenting

- - Patterns: Confirm examples reflect actual usage

- See rules/testing.md for verification in test contexts.

- # Skill Activation

- **Evaluate on every prompt** - Before any response, tool call, or action, check available skills for relevance

- **Activation sequence:**

- 1. **Evaluate** - For each skill in `<available_skills>`, assess: `[skill-name] - YES/NO - [reason]`

- 2. **Activate** - Call `Skill(skill-name)` for each relevant skill before proceeding

- 3. **Respond** - Begin response only after activation is complete

- **Applies to all tasks** - Research, explanation, code changes, debugging, review — no exceptions

- **Decision-point re-evaluation** - Re-evaluate skills at each planning or delegation step:

- - Before entering plan mode

- - Before launching subagents (Task tool)

- - Before starting each task in a task list

- - When the domain shifts mid-task (e.g., from code to evaluation, from schema to grading)

- *Verify:* Every Task tool call and plan mode entry was preceded by skill evaluation

- *Fix:* Pause, evaluate skills, activate relevant ones, then continue

- **Example:**

- ```

- - code-patterns: NO - not writing code

- - git-workflow: YES - need commit conventions

- - documentation: YES - writing README

- > Skill(git-workflow)

- > Skill(documentation)

- ```

- **Activation before action** - Evaluating skills without calling `Skill()` provides no benefit

- *Verify:* Check that `Skill()` was called for each YES evaluation

- *Fix:* Call `Skill(skill-name)` for skipped activations

- # Documentation

- **TSDoc required** for public APIs

+ # Agent Instructions

- **Template:**

- ```typescript

- /**

- * Brief description

- *

- * @remarks

- * Additional context

- *

- * @param options - Description

- * @returns Description

- *

- * @public

- */

- ```

+ This repo packages You.com skills and plugin manifests for multiple coding-agent surfaces. Keep changes small, verified, and tied to the requested surface.

- **No @example** - Tests are living examples

- **Use @internal** - Mark non-public APIs

- **Mermaid only** - No ASCII box-drawing diagrams

- *Verify:* `grep '[┌│└─]' *.md`

+ ## Tooling discovery

+ - Prefer Bun for TypeScript, scripts, orchestration, and running checks. Use Bun to trigger Python and TypeScript tooling unless an existing script says otherwise.

+ - Bun MCP docs: https://bun.com/docs/mcp

+ - Before choosing commands, scan `package.json`, `biome.json`, `ruff.toml`, and relevant `packages/*/package.json` scripts. Do not guess command names.

+ - Root checks currently flow through Bun: `bun test`, `bun run check`, `bun run check:types`, `bun run check:ts`, `bun run check:py`, `bun run check:package`.

+ - Package checks often differ. Use the package script in `packages/<name>/package.json` for package-scoped work.

- # Core Conventions

+ ## Minimal-implementation directive

- **Type over interface** - `type User = {` instead of `interface User {`

- *Verify:* `lsp-find interface` or `grep 'interface [A-Z]' src/`

- *Fix:* Replace `interface X {` with `type X = {`

+ Before writing code, resolve the task at the FIRST step that holds:

- **No any types** - Use `unknown` with type guards

- *Verify:* `grep ': any' src/`

- *Fix:* Replace `any` with `unknown`, add type guard

+ 1. Does this capability need to exist for the stated task? If it is speculative, do not build it. Say so in one sentence and stop.

+ 2. Does something already in THIS codebase do it? Reuse it. Read before you write; re-implementing a helper that lives three files over is the most common waste.

+ 3. Does the standard library or the runtime/platform already do it? (`<input type="date">`, a DB unique constraint, a CSS rule.) Use it.

+ 4. Does an already-installed dependency do it? Use it. Do not add a new dependency for something a few lines cover.

+ 5. Can it be one clear expression? Write the one expression.

+ 6. Otherwise: the smallest code that fully handles the task.

- **PascalCase types** - `type UserConfig`, schemas get `Schema` suffix: `UserConfigSchema`

- *Verify:* `lsp-find` for lowercase type names

- *Fix:* Rename to PascalCase

+ NON-NEGOTIABLE FLOOR: none of the steps above may remove any of these, and "minimal" is never a reason to drop them:

- **Arrow functions** - Prefer `const fn = () =>` over `function fn()`

- *Verify:* `grep 'function \w' src/`

- *Fix:* Convert to arrow function

+ - input validation at trust boundaries (anything crossing a process, network, file, or user edge),

+ - error handling that prevents data loss or silent corruption,

+ - authn/authz and other security checks,

+ - accessibility for anything a human interacts with.

- **Object params >2 args** - `fn({ a, b, c }: { ... })` not `fn(a, b, c)`

- *Exception:* CLI entry points take `args: string[]`

- *Verify:* Review function signatures with `lsp-hover`

+ If a step would require cutting one of these, that step does not apply.

- **Private fields** - Use `#field` (ES2022) not `private field` (TypeScript)

- *Verify:* `grep 'private \w' src/`

- *Fix:* Replace `private x` with `#x`

+ Leave exactly one runnable check behind for any non-trivial logic.

+ Mark deliberate shortcuts with a `MINIMAL:` comment naming the ceiling and the upgrade path, so "later" is greppable instead of forgotten.

- **JSON imports** - `import x from 'file.json' with { type: 'json' }`

- *Verify:* `grep "from.*\.json['\"]" src/` (check for missing `with`)

- *Fix:* Add `with { type: 'json' }`

+ ## Style enforcement

- **@ts-ignore needs description** - `// @ts-ignore - reason here`

- *Verify:* `grep '@ts-ignore' src/` (check for missing comment)

+ - TypeScript, JSON, and Markdown formatting/linting are governed by `biome.json` plus `tsc`.

+ - Python formatting/linting is governed by `ruff.toml` plus Hermes package checks.

+ - Read these config files before changing style rules. Keep only conventions not enforced by tools in this file.

- **Short-circuit/ternary OK** - `condition && doSomething()` is acceptable

+ ## Workflow

- **Empty interface extending single** - `interface Custom extends Base {}` is OK for branded types

+ - Read existing code before editing. Prefer `Read`, `Grep`, and `Glob` for exploration.

+ - Treat generated or copied skill/package files as release artifacts unless the task is explicitly about them.

+ - Do not inline MCP configs into shared manifests unless the host specifically requires it; users choose keyless, API-key, OAuth, MPP, or x402 setup by need.

+ - Keep marketplace `plugins[].version` pegged to the paired `plugin.json` version.

+ - For PR review work, use `gh` when available and check PR comments, reviews, code scanning alerts, and inline comments.

+ - Conventional commits only: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, `test:`, `ci:`.

- **Mermaid diagrams only** - No ASCII box-drawing in markdown

- *Verify:* `grep '[┌│└─]' *.md`

+ ## Release workflow

- **No @example in TSDoc** - Tests are living examples

+ The GitHub Actions UI runs **Semantic Release** manually:

- **AgentSkills validation** - `bunx @plaited/development-skills validate-skill <path>`

+ 1. Open **Actions** -> **Semantic Release** -> **Run workflow**.

+ 2. First run with `apply_versions=false` and `publish_artifacts=false`; inspect the `release-plan` artifact.

+ 3. Set `base_ref` to the intended comparison point. `HEAD~1` only sees the last commit; an older base may bump every changed skill, plugin, npm package, PyPI package, and ClawHub package since that ref.

+ 4. Run again with `apply_versions=true` to commit version bumps.

+ 5. Run with `publish_artifacts=true` only when ready to publish npm, PyPI, and ClawHub artifacts.

+ ## Verification

-

+ - Non-trivial TypeScript/script change: at least `bun test <target>` and `bun run check:types`.

+ - Python/Hermes change: use `packages/hermes/package.json` scripts, usually `bun run --cwd packages/hermes check:python`.

+ - Formatting/linting: `bun run check:ts` for Biome, `bun run check:package` for package manifests, `bun run check:py` for Python.

+ - Skill content: `bun test tests/validate-skills.spec.ts`; use `bunx @plaited/development-skills validate-skill <path>` when validating one skill.

+ - Before final handoff after edits, run the smallest relevant checks plus any requested full checks. Report known pre-existing warnings separately.