agentleFS
Alice39sAlice39s/agent-stash/AGENTS.md

agent-stash

AGENTS.md20 starsChanged 21 days agoApache-2.0View on GitHub

  • Installs packages

The file

We split this AGENTS.md into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Keep the bundling script named bundle.

    line 30

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Repository Guidelines

Project Structure & Module Organization

  • src/init/: shared /init core (preset registry, prompt rendering, agent adapters). Test fixtures live in src/init/fixtures/.
  • src/code-styleguide/: converter that turns upstream style guides into the skill.
  • src/modern-web-guidance/: renders skills/modern-web-guidance/ (SKILL.md, category indexes, sources.json) from the guides in the latest modern-web-guidance npm release, which scripts/sync-modern-web-guidance.ts downloads and checks against its integrity hash.
  • Agent entry points: pi/extensions/init/, dsh/init/, cline/init/, and cli/agent-stash.ts.
  • DSH /init: dsh/cordis.patch.yml inserts one row named after the package root, so DSH serves the package's browser half too. The Host half (dsh/init/index.ts, exported as .) registers GET /agent-stash-init/presets and POST /agent-stash-init/run; the browser half (dsh/init/client.ts, exported as ./client and built to dist/dsh/client.js) registers the /init contribution with commandUi (title, icon, preset popup) and a / source in inputTriggers that claims /init followed by arguments. dsh/init/wire.ts holds the route paths and request schemas both halves share.
  • DSH bundle metadata: dsh/locale/*.json (bundle and row title and description, exported as ./locale/*.json), plus icon, engines.dsh, dsh.manifestVersion, and dsh.client in package.json. Every DSH bundle also repeats its engines.dsh range as an optional @deepseek-ai/dsh peer for tools that read the requirement from peerDependencies; the workspace overrides keep pnpm from installing DSH itself, and dsh/dsh-requirement.test.ts keeps the two in sync. Keep the package public; plugin index generators skip private bundles.
  • dsh/plugin-index.yaml: the plugin index sources. plugins lists npm package names (Agent Stash's own bundles, then recommended third-party DSH plugins), each with a category and labels declared under categories and labels (titles need en). .github/workflows/pages.yml turns the list into the plugin index at https://alice39s.github.io/agent-stash/index.json with DSH's reference generator; ci plugin-index then keeps the 10 highest versions of each plugin, plus any version a dist-tags entry points to, and writes the declarations and each plugin's category and labels into the index metadata. The same Pages artifact carries the docs site, so the index stays at the site root. The workflow also runs after every Release run and hourly; those runs build and deploy only when ci plugin-index-diff finds that the generated index differs from the published one.
  • docs/ (workspace package agent-stash-docs): the bilingual docs site, a statically exported Fumadocs (Next.js) app published to GitHub Pages under /agent-stash. Pages live in docs/content/docs/ (*.mdx in Chinese, *.en.mdx in English, with meta.json/meta.en.json); screenshots and recordings in docs/public/media/ are registered in docs/lib/media.ts and shown with <Showcase>. Recordings and their posters carry the repository watermark from docs/lib/watermark.ts; pnpm --filter agent-stash-docs media:watermark --source <dir> writes them from the unwatermarked originals in <dir>. docs/design.md holds the site's presentation rules (the root design.md covers the DSH overlays); read it before changing the site's interface.
  • packages/: further workspace packages published to npm, each with its own bundle script and committed dist/. packages/dsh-message-edit/ is a DSH bundle with a Host half (src/host/) and a browser half (src/client/); its UI follows packages/dsh-message-edit/design.md. packages/dsh-skill-scout/ (@agent-stash/dsh-skill-scout) uses the same layout plus src/shared.ts for the route schemas both halves share. Its Host half reads sessions through ctx.sessionQuery, lists the Skills an evidence session sees through ctx.sessionSkillCatalog, stores episodes and suggestions in the skill_scout storage domain, and calls the discovery model (summaries) and the drafting model (Skill drafts, only after the user approves a summary) through ctx.llm. Its browser half takes react-dom and @deepseek-ai/dsh-client-ui-primitives from the DSH module table (the third argument of clientBundle in packages/dsh-message-edit/tsdown.client.ts), so it needs DSH 0.2.1-rc.3 or later. packages/dsh-skill-scout/architecture.md records its design decisions, and its UI (a conversation view, a main panel page, and a header popover, with charts in src/client/ui/charts/) follows packages/dsh-skill-scout/design.md.
  • scripts/ci/: Python CLI (uv + Typer) that every workflow step calls (uv run --project scripts/ci ci --help). Workflows contain no inline shell; add a CLI command instead. Check it with uv run ruff format --check, uv run ruff check, and uv run pytest in that directory.
  • Standalone DSH bundles dsh/recall/ (@agent-stash/dsh-recall), dsh/autosuggest/ (@agent-stash/dsh-autosuggest), dsh/enhance/ (@agent-stash/dsh-enhance), and dsh/kit/ (@agent-stash/dsh-stash-kit, the Agent Stash Kit): workspace packages published to npm, each with its own package.json, cordis.patch.yml, locale/*.json, icon.svg, and README.md, a Host half in src/index.ts, and a browser half in src/client.tsx. Their plugin rows keep the short ids dsh-recall, dsh-autosuggest, dsh-enhance, and dsh-stash-kit, which also name their dictionaries and config. The kit's browser half provides the stashKit Cordis service (panel, ghost text, draft-swap motion, appearance store) and the plugins.row.config settings page; its Host half owns the volatile appearance Config. Recall and autosuggest register into the conversation.input.overlay slot, inject stashKit, import kit code only as types, and install or enable the kit bundle through pluginManager at Host startup (dsh/shared/host/kit.ts). Enhance does the same with the kit but registers a button into the conversation.input.right slot and its own plugins.row.config page; its Host half registers POST /dsh-enhance/rewrite and GET /dsh-enhance/context and calls the model through ctx.llm, and its volatile Config holds the model, timeout, session-context, shortcut, and preset settings. Its component tests mount through dsh/enhance/src/harness.tsx. Shared code lives in dsh/shared/ (prompts.ts for pure history logic, host/ for the prompt route and kit installation, client/ for the composer hooks and component-test harness). The root pnpm bundle writes both halves to each bundle's dist/; the browser half is CommonJS wrapped in window.__ModuleLoader__.load and takes react and @deepseek-ai/dsh-client-ui-primitives from the DSH module table. Their UI follows the root design.md.
  • benchmark/prompts/ (private workspace package agent-stash-prompt-benchmark): vieval benchmarks for the prompts the plugins send to models. enhance/ runs the dsh-enhance built-in presets through the plugin's own buildPrompt and runRewrite over the golden set in enhance/cases/*.yaml, then scores each result with rule checks (enhance/src/checks.ts) and a judge model (enhance/src/judge.ts). Its README holds the review process for prompt changes.
  • prompts/init/: hand-maintained presets (claude-code*.md).
  • Generated content, never edited by hand: vendor/init-prompts/ (from pnpm sync:init-prompts), skills/code-styleguide/ (from pnpm sync:code-styleguide), skills/modern-web-guidance/ (from pnpm sync:modern-web-guidance), SKILL.md and agents/openai.yaml in each skills/self-use-*-subagent/ (from uv run skills/self-use-haiku-subagent/scripts/render.py, which renders that directory's templates/ with models.yaml), and dist/ plus dsh/*/dist/ (from pnpm bundle).
  • Plugin names and descriptions: meta.title and meta.description in each bundle's locale/*.json hold the wording that READMEs, the docs site (overview table, page descriptions), and changesets reuse. The Chinese titles are /init, Prompt 回溯, Prompt 自动补全, 提示词增强器, Agent Stash 基础核心框架, 消息编辑, and 经验提炼器. A description is one clause, without trailing punctuation, that says what the plugin does (提示词增强器: 一键润色、结构化、提炼 Prompt 草稿的核心内容); key bindings, defaults, and limits go in the README and the docs page.

Build, Test, and Development Commands

Requires Node 24+ and pnpm 11.

  • pnpm install: install dependencies.
  • pnpm check: oxfmt --check, type-aware oxlint, and vitest run; this is what CI runs.
  • pnpm test, pnpm lint, pnpm format: run each step on its own.
  • pnpm bundle: rebuild dist/ and dsh/*/dist/ with tsdown. DSH, Cline, and the CLI load these directories directly, so commit the rebuilt output; CI fails when they differ from the sources. uv run --project scripts/ci ci bundle rebuilds every workspace package.

Keep the bundling script named bundle. A build script makes npm install -g github:... install a broken link.

  • pnpm --filter agent-stash-prompt-benchmark bench: run the prompt benchmark with real models (needs API keys; see benchmark/prompts/README.md). pnpm test covers its loaders, checks, and adapters without network.
  • pnpm --filter agent-stash-docs dev: serve the docs site at http://localhost:3883/agent-stash/.
  • pnpm --filter agent-stash-docs build: export the docs site to docs/out/. The Pages workflow builds it on pull requests that touch docs/ and deploys it from main.

Coding Style & Naming Conventions

  • TypeScript ESM with strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes, and erasableSyntaxOnly (no enums or namespaces). Import local files with the .ts extension.
  • oxfmt formats with a 100-column print width. oxlint denies warnings and forbids any and floating promises.
  • Validate external input with valibot schemas (ConfigSchema); use pathe for paths.
  • Constants use UPPER_SNAKE_CASE, schemas PascalCaseSchema, files kebab-case.ts. Write doc comments in Chinese, matching existing code.

Testing Guidelines

Tests use Vitest and sit next to their source as *.test.ts (src/init/registry.test.ts). Browser-half component tests are *.test.tsx files with a // @vitest-environment happy-dom header that mount the overlay through dsh/shared/client/harness.tsx, which provides the real kit service from dsh/kit/src/harness.tsx (kit tests use mountKit and createSettings from there); vitest.config.ts aliases @deepseek-ai/dsh-client-ui-primitives, which the DSH module table supplies at runtime, to dsh/kit/src/primitives-stand-in.tsx. Write describe/test names as English behavior statements. Put on-disk config cases under src/init/fixtures/<case>/. Every new preset, adapter, or config path needs a test. A change to the dsh-enhance prompts (dsh/enhance/src/presets.ts, or how rewrite.ts builds the request or checks the result) needs a baseline and candidate run of benchmark/prompts compared as its README describes; a draft the plugin rewrote wrongly becomes a golden-set case first.

Commit & Pull Request Guidelines

  • Commits follow Conventional Commits with a scope, for example feat(init): add Crush preset or ci(release): .... Use the body to explain why.
  • For user-facing changes, add a changeset to .tegami/<topic>.md with packages: { "@agent-stash/init": minor } frontmatter (use the name of each changed workspace package) and release notes in Chinese under at least one Markdown heading; Tegami ignores changesets without a heading. Tegami opens the Version Packages PR on main.
  • PRs must pass pnpm check and include the rebuilt dist/. Describe which agents or presets the change affects.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.