agent-stash
AGENTS.md20 starsChanged 21 days agoApache-2.0View on GitHub
- Installs packages
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository7 other files it gives its agents.
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
- Very specific: line 30
Keep the bundling script named bundle.
≈ “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.
Files
Repository Guidelines
Project Structure & Module Organization
src/init/: shared/initcore (preset registry, prompt rendering, agent adapters). Test fixtures live insrc/init/fixtures/.src/code-styleguide/: converter that turns upstream style guides into the skill.src/modern-web-guidance/: rendersskills/modern-web-guidance/(SKILL.md, category indexes,sources.json) from the guides in the latestmodern-web-guidancenpm release, whichscripts/sync-modern-web-guidance.tsdownloads and checks against its integrity hash.- Agent entry points:
pi/extensions/init/,dsh/init/,cline/init/, andcli/agent-stash.ts. - DSH
/init:dsh/cordis.patch.ymlinserts 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.) registersGET /agent-stash-init/presetsandPOST /agent-stash-init/run; the browser half (dsh/init/client.ts, exported as./clientand built todist/dsh/client.js) registers the/initcontribution withcommandUi(title, icon, preset popup) and a/source ininputTriggersthat claims/initfollowed by arguments.dsh/init/wire.tsholds 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), plusicon,engines.dsh,dsh.manifestVersion, anddsh.clientinpackage.json. Every DSH bundle also repeats itsengines.dshrange as an optional@deepseek-ai/dshpeer for tools that read the requirement frompeerDependencies; the workspaceoverrideskeep pnpm from installing DSH itself, anddsh/dsh-requirement.test.tskeeps the two in sync. Keep the package public; plugin index generators skip private bundles. dsh/plugin-index.yaml: the plugin index sources.pluginslists npm package names (Agent Stash's own bundles, then recommended third-party DSH plugins), each with acategoryandlabelsdeclared undercategoriesandlabels(titles needen)..github/workflows/pages.ymlturns the list into the plugin index athttps://alice39s.github.io/agent-stash/index.jsonwith DSH's reference generator;ci plugin-indexthen keeps the 10 highest versions of each plugin, plus any version adist-tagsentry 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 whenci plugin-index-difffinds that the generated index differs from the published one.docs/(workspace packageagent-stash-docs): the bilingual docs site, a statically exported Fumadocs (Next.js) app published to GitHub Pages under/agent-stash. Pages live indocs/content/docs/(*.mdxin Chinese,*.en.mdxin English, withmeta.json/meta.en.json); screenshots and recordings indocs/public/media/are registered indocs/lib/media.tsand shown with<Showcase>. Recordings and their posters carry the repository watermark fromdocs/lib/watermark.ts;pnpm --filter agent-stash-docs media:watermark --source <dir>writes them from the unwatermarked originals in<dir>.docs/design.mdholds the site's presentation rules (the rootdesign.mdcovers the DSH overlays); read it before changing the site's interface.packages/: further workspace packages published to npm, each with its ownbundlescript and committeddist/.packages/dsh-message-edit/is a DSH bundle with a Host half (src/host/) and a browser half (src/client/); its UI followspackages/dsh-message-edit/design.md.packages/dsh-skill-scout/(@agent-stash/dsh-skill-scout) uses the same layout plussrc/shared.tsfor the route schemas both halves share. Its Host half reads sessions throughctx.sessionQuery, lists the Skills an evidence session sees throughctx.sessionSkillCatalog, stores episodes and suggestions in theskill_scoutstorage domain, and calls the discovery model (summaries) and the drafting model (Skill drafts, only after the user approves a summary) throughctx.llm. Its browser half takesreact-domand@deepseek-ai/dsh-client-ui-primitivesfrom the DSH module table (the third argument ofclientBundleinpackages/dsh-message-edit/tsdown.client.ts), so it needs DSH 0.2.1-rc.3 or later.packages/dsh-skill-scout/architecture.mdrecords its design decisions, and its UI (a conversation view, a main panel page, and a header popover, with charts insrc/client/ui/charts/) followspackages/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 withuv run ruff format --check,uv run ruff check, anduv run pytestin that directory.- Standalone DSH bundles
dsh/recall/(@agent-stash/dsh-recall),dsh/autosuggest/(@agent-stash/dsh-autosuggest),dsh/enhance/(@agent-stash/dsh-enhance), anddsh/kit/(@agent-stash/dsh-stash-kit, the Agent Stash Kit): workspace packages published to npm, each with its ownpackage.json,cordis.patch.yml,locale/*.json,icon.svg, andREADME.md, a Host half insrc/index.ts, and a browser half insrc/client.tsx. Their plugin rows keep the short idsdsh-recall,dsh-autosuggest,dsh-enhance, anddsh-stash-kit, which also name their dictionaries and config. The kit's browser half provides thestashKitCordis service (panel, ghost text, draft-swap motion, appearance store) and theplugins.row.configsettings page; its Host half owns the volatile appearanceConfig. Recall and autosuggest register into theconversation.input.overlayslot, injectstashKit, import kit code only as types, and install or enable the kit bundle throughpluginManagerat Host startup (dsh/shared/host/kit.ts). Enhance does the same with the kit but registers a button into theconversation.input.rightslot and its ownplugins.row.configpage; its Host half registersPOST /dsh-enhance/rewriteandGET /dsh-enhance/contextand calls the model throughctx.llm, and its volatileConfigholds the model, timeout, session-context, shortcut, and preset settings. Its component tests mount throughdsh/enhance/src/harness.tsx. Shared code lives indsh/shared/(prompts.tsfor pure history logic,host/for the prompt route and kit installation,client/for the composer hooks and component-test harness). The rootpnpm bundlewrites both halves to each bundle'sdist/; the browser half is CommonJS wrapped inwindow.__ModuleLoader__.loadand takesreactand@deepseek-ai/dsh-client-ui-primitivesfrom the DSH module table. Their UI follows the rootdesign.md. benchmark/prompts/(private workspace packageagent-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 ownbuildPromptandrunRewriteover the golden set inenhance/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/(frompnpm sync:init-prompts),skills/code-styleguide/(frompnpm sync:code-styleguide),skills/modern-web-guidance/(frompnpm sync:modern-web-guidance),SKILL.mdandagents/openai.yamlin eachskills/self-use-*-subagent/(fromuv run skills/self-use-haiku-subagent/scripts/render.py, which renders that directory'stemplates/withmodels.yaml), anddist/plusdsh/*/dist/(frompnpm bundle). - Plugin names and descriptions:
meta.titleandmeta.descriptionin each bundle'slocale/*.jsonhold 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-awareoxlint, andvitest run; this is what CI runs.pnpm test,pnpm lint,pnpm format: run each step on its own.pnpm bundle: rebuilddist/anddsh/*/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 bundlerebuilds 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; seebenchmark/prompts/README.md).pnpm testcovers its loaders, checks, and adapters without network.pnpm --filter agent-stash-docs dev: serve the docs site athttp://localhost:3883/agent-stash/.pnpm --filter agent-stash-docs build: export the docs site todocs/out/. The Pages workflow builds it on pull requests that touchdocs/and deploys it frommain.
Coding Style & Naming Conventions
- TypeScript ESM with
strict,noUncheckedIndexedAccess,exactOptionalPropertyTypes, anderasableSyntaxOnly(no enums or namespaces). Import local files with the.tsextension. - oxfmt formats with a 100-column print width. oxlint denies warnings and forbids
anyand floating promises. - Validate external input with valibot schemas (
ConfigSchema); usepathefor paths. - Constants use
UPPER_SNAKE_CASE, schemasPascalCaseSchema, fileskebab-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 presetorci(release): .... Use the body to explain why. - For user-facing changes, add a changeset to
.tegami/<topic>.mdwithpackages: { "@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 onmain. - PRs must pass
pnpm checkand include the rebuiltdist/. Describe which agents or presets the change affects.
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
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.

