greenhouse
AGENTS.md3 starsChanged 21 days agoMITView on GitHub
- Reads credentials
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 33,315 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 repository8 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-agent-profileSkill
- add-agent-toolSkill
- add-api-routeSkill
- add-client-screenSkill
- add-db-tableSkill
- full-featureSkill
- quality-gateSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
16 rules. About 0 are common, 6 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 15
Read the nearest AGENTS.md and reuse existing implementations before adding one.
- Very specific: line 16
Prefer MCP graph tools for code discovery.
- Very specific: line 17
Write a spec before non-trivial cross-cutting work in local-only docs/specs/YYYYMMDD-<name>.md (status, decisions, acceptance criteria, …
- Very specific: line 18
Update README/AGENTS for behavior/convention changes and apps/api/src/profiles/agent-profiles.md for profile changes.
- Very specific: line 22
Use @greenhouse/utils/* helpers (nowIso, safeJsonParse, extractJson, runWithConcurrency, logger, encrypt/decrypt/parseHexKey, …
- Very specific: line 49
Run pnpm plugins:sync after assembly inputs change.
- Distinctive: line 53
Add hooks only with a real registry consumer, Example coverage and seam tests.
- Very specific: line 57
Prefer dataSources for table-backed entities.
- Very specific: line 74
Keep apps/client outside the root workspace with its own lockfile.
- Very specific: line 84
All business surfaces bind real active internal team/super accounts.
- Very specific: line 110
Run pnpm typecheck and pnpm lint after every change, pnpm test after functional changes and every task gate before handoff.
- Distinctive: line 120
Never mock or hand-edit product screenshots.
- Distinctive: line 121
Keep gitleaks allowlists narrow/commented and CI gates complete.
- Distinctive: line 129
Use Conventional squash commits.
- Distinctive: line 131
Keep the desktop bundle id/updater public key and the native app identity unchanged.
- Very specific: line 132
Keep Compose topologies, render.yaml, deploy/ and scripts/deploy-smoke.mjs aligned (the smoke is the platform contract), migrate before …
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 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
Greenhouse contributor rules
Product and ownership
- Greenhouse is a self-hosted internal Agent hub: a governance core, official plugins and deployment-specific plugins.
- Core owns identity/permissions, conversations/Agents, models/budgets/gateway, tools/runs/audit, MCP/connectors, automations, saved prompts, Files, notifications/push, settings/branding, the plugin host, administration and CLI.
- Knowledge, Tables, Skills, Feedback and Memory are default-on plugins; Projects, Reports, Email, Feishu, WeCom, Computer, Retro, Assets and Example are compiled but default-off.
- Retro depends on Knowledge; saved prompts,
/api/promptsandtask_capturestay core without SkillHub. - Core consumes active registries and never imports plugins or branches on plugin ids.
- There is one client, the universal client in
apps/client(web, iOS, Android;apps/desktopwraps it); there is no second web app. - Public docs describe implemented behavior and contain no private company/customer information.
Work discipline
- Read the nearest AGENTS.md and reuse existing implementations before adding one.
- Prefer MCP graph tools for code discovery; use rg for literals/config/docs or when graph tools are insufficient.
- Write a spec before non-trivial cross-cutting work in local-only
docs/specs/YYYYMMDD-<name>.md(status, decisions, acceptance criteria, index entry). - Update README/AGENTS for behavior/convention changes and
apps/api/src/profiles/agent-profiles.mdfor profile changes. - Deletions cascade to orphan consumers, types, copy, routes, navigation, tests and docs.
- Record why an existing implementation cannot be extended before adding a parallel one; no speculative abstractions or unused columns.
- Declared capabilities must work; unsupported or unconfigured paths error explicitly.
- Use
@greenhouse/utils/*helpers (nowIso,safeJsonParse,extractJson,runWithConcurrency,logger,encrypt/decrypt/parseHexKey,toErrorMessage,isUniqueViolation,randomDocId, semver,escapeHtml,composeRichOutput) instead of copies. - Cross-package imports use
@greenhouse/<package>; intra-package Node ESM imports use relative paths plus.js.
Repository map
apps/api/is the Hono governance API, runtime, plugin host (src/plugin-host/) and CLI; read backend rules.apps/client/is the isolated Expo universal client; read client rules and design rules.apps/desktop/is the Tauri macOS shell around the client; read desktop rules.packages/agent-core/owns the model loop/factory;packages/platform-kernel/owns pure manifests/actors/authz/dispatch.packages/db/owns core schema/services/migrations (packages/db/migrations/); read DB rules and schema.packages/types/andpackages/utils/own shared protocols and helpers;packages/crud/owns the list protocol and server CRUD (@greenhouse/crud/server).packages/knowledge-editor/owns the editor schema/Markdown conversion;packages/ui/owns token sources, brand and plant avatars;packages/ui-tokens/owns generated themes and the embed bridge.plugins/<id>/owns manifest, API half, schema/services, migrations, seeds and tests; read its AGENTS.md.skillhub/holds skill-pack sources (pack format);scripts/owns build/assembly/ops/gates;tests/owns shared test layers.
Configuration
.envowns infrastructure/secrets; DB Runtime Config owns live settings;greenhouse.config.tsowns structure; do not add a fourth layer.greenhouse.config.tshasplugins,extensions.enabled,packs,conversations.sharingandclients.stations;clients.webis a boot error.pluginsselects compiled packages;extensions.enabledselects active ids; GREENHOUSE_PLUGINS overrides assembly and GREENHOUSE_EXTENSIONS replaces (not appends to) enablement.- Rebuild for compilation changes and restart for enablement changes; Admin › Plugins is read-only; credentials alone never enable a plugin.
- Settings resolve DB → env → unset; batch writes validate atomically and preserve masked secrets.
Plugins
- New plugins are packages in
plugins/<id>/with SDK 2: an api half (api/index.ts,defineExtension) and a pure-datamanifest.ts; there is no web half. - Manifest id/sdk/version must agree with package.json; declare
sdk: 2and acorerange that includes the running release; a missing or mismatching declaration refuses activation. - Run
pnpm plugins:syncafter assembly inputs change; never edit or commitapps/api/src/plugin-host/compiled.generated.ts. - Production imports use only
@greenhouse/api/extension-kit,@greenhouse/types/*,@greenhouse/crud,@greenhouse/ui-tokens,@greenhouse/knowledge-editor/markdown, own files, Node builtins and declared dependencies (scripts/lib/plugin-imports.mjs). - Relative imports cannot escape a package; plugin dependencies need both
dependsOnand package.json; tests may reach host hooks;pnpm lintruns the boundary scanner. - Kit exports are snapshot-locked (
apps/api/src/__tests__/extension-kit.snapshot.test.ts); additions, removals and renames update the snapshot and use a commit scopedextension-kit(the generated CHANGELOG lists it). - Add hooks only with a real registry consumer, Example coverage and seam tests; never add per-module core cases.
- Plugin front ends pass
scripts/check-plugin-ui.mjs(inpnpm lint); known debt sits inplugins/<id>/design-baseline.jsonand only shrinks. - Client UI comes from manifest
surfaces(nav, pages: native, entity-list, entity-detail, settings-form, embed) and an optional staticui/; Admin sections useparent: 'administration'. - Client-facing plugin copy is manifest
LocalizedText({ en, zh }); official native screens live inapps/client/src/plugins/<id>/and use the client catalogs. - Prefer
dataSourcesfor table-backed entities; REST/tools/runtime share capability, row-scope, field-policy, export and audit checks. - Custom handlers use scoped services or enforce equivalent restrictions before paging/counting and external I/O.
- Writes reject unknown/immutable/forbidden fields atomically, even for super; ids, storage timestamps and internal/confidential/restricted fields are never caller input.
- Owner/member input requires explicit writable metadata and grants; creation validates, then stamps effective ownership.
- Writing tools declare
surface.proxy: 'write'; static/lazy tools implementcreate/createLazy; builtin metadata never grants permissions. - Custom protected commands use kit
recordWriteand notifications usenotify; do not create a parallel permission/audit plane. - Agent context is stable, capped and reach-filtered; resources/prompts recheck grants on each request.
- Observations carry ids/metadata, cannot veto and have isolated five-second deadlines; use bounded I/O and tolerate retries.
onInstallruns migration-locked after migrations; install/outbox consumers must be crash/retry idempotent.- Scheduled work uses host job claims (
runExtensionJob); register transport/identity/channel/retention/pricing/search/catalog/entity/discriminator contributions. - Preserve official URLs, tool ids, MCP groups and entity kinds; aliases belong to plugins and cannot replace core routes.
- Downstream changes stay in plugins, packs, deploy, config and fork workflows; generic improvements go upstream with an Example consumer.
Clients, permissions and security
- The API serves the hosted client from
public/appat/; API, plugin and OAuth paths never fall through to SPA HTML. pnpm app:buildexports the isolated Expo app intopublic/appwithout developer/desktop station overrides.- Keep
apps/clientoutside the root workspace with its own lockfile; Docker installs and exports it in a separate stage. /api/extensionsv2 is member-filtered; server and client API level are both 4 and a 3.x station gets an update notice.- Server-made browser links use
@greenhouse/types/client-routeswith secrets in the fragment; never emit#/…addresses to a browser. - Settings forms never weaken super-only settings APIs; an unknown page kind asks the member to update the app.
- Regenerate shared themes with
pnpm tokens:build; never hand-edit generated tokens. - Embeds receive ten-minute member/plugin credentials from
/api/ext-ui/token, scoped to the plugin API and basicGET /api/me. - Validate bridge window and exact origin; never inject full login tokens, persist credentials or submit assistant drafts automatically.
- Plugin pages use the
@greenhouse/ui-tokenspreset and React kit; the host draws their confirms and notices, and malformed bridge requests are dropped. - Same-origin installed plugin frames share code trust; user HTML previews stay opaque-origin and credential-free.
- Desktop CORS/framing trusts exactly
tauri://localhost; plugin frames get no native capabilities and explicitly allowlist the parent hint. - All business surfaces bind real active internal team/super accounts; reject anonymous/disabled/deleted/external/stale-generation identities.
TOKEN_SIGNING_KEYis mandatory; stored secrets needPROVIDER_TOKEN_ENCRYPTION_KEY; secret settings are encrypted and write-only.- Permissions only narrow from member to profile/grant/transport;
runtime.dispatchis the protected-action boundary. - MCP writes run as the member with evidence and delete preview/confirm; the Agent API requires
confirmon each write. - Core feature flags are empty; plugins contribute flags through feature points; UI hiding never replaces route checks.
models.yamldefines models;billableServicesaugments pricing; paid calls always use budget admission and metering.- Active chat runs, presence and some provider caches are process-local; keep multi-replica limits explicit.
Database and seeds
- Core history starts at immutable
packages/db/migrations/0000_v4_baseline.sql(49 core tables);archive-3xis byte-frozen and only bridges 3.x databases. - Persistent/shared databases use
pnpm db:migrate, never push; always set the intendedDATABASE_URLexplicitly. - Worktrees use isolated databases, never the owner's main DB; let run-dev arbitrate ports without killing unrelated processes.
- Schema changes need generated, reviewed SQL and updated schema docs; never edit applied migration bytes.
- Plugin DDL uses its own checksummed lane with statement breakpoints; never create core tables or append plugin DDL to the core chain.
- Fresh installs create only core tables; each plugin's
0001_adopt.sqlcreates its tables when enabled and adopts 3.x tables in place without DROP or copy. - Disablement retains data;
pnpm cli plugins droppreviews, then deletes only disabled owned tables/lane with RESTRICT. - Core cannot acquire plugin FKs; historical discriminator reads survive disablement and writes validate active registries.
pnpm db:migrateupgrades 3.x in place under its advisory lock and never drops data, plugin/overlay lane rows ordrizzle.greenhouse_carry; the API refuses an unbridged 3.x DB.- A fresh 4.0 install with all official plugins must match a bridged 3.x database (
tests/db/schema-equivalence.db-commit.test.ts); record intended differences there. - 1.x/2.x/half-carried databases are refused: upgrade to 3.0.2 first, then to 4.0;
db baselineadopts only DBs already on the 4.0 schema (dry run first). - Core seeds live in
data/examples, plugin seeds inplugins/<id>/seeds; load in dependency order and keep the dataset README current. - Seed refuses non-empty DBs without keep/reset; destructive reset needs explicit confirmation; fixtures contain no encrypted auth secrets.
Verification
- Run
pnpm typecheckandpnpm lintafter every change,pnpm testafter functional changes and every task gate before handoff. pnpm testincludes unit, transactional DB and committed-state DB layers; never trim the default suite.- Units use forks and no PostgreSQL; DB tests roll back; committed-state tests need
@db-commit-reasonand isolated cleanup. - Restore mocks/timers/env/registries and build fixtures with returned opaque ids, not fixed ids.
- DB tests need a loopback
TEST_DATABASE_URLwith test/e2e in the name; tuneVITEST_UNIT_MAX_WORKERS/VITEST_DB_MAX_WORKERS. - Plugin changes also run
pnpm plugins:sync --checkandpnpm test:core(zero packages, sequential with other generators). - HTTP security uses
pnpm test:e2e:ciagainst a migrated test DB and a dead LLM endpoint. - Browser tests are
pnpm test:e2e:client(tests/client-e2e,playwright.client.config.ts; ports and DB viaCLIENT_E2E_*); specs import only@playwright/test. - Root checks skip the isolated client's types and lint: run
pnpm typecheckandpnpm lintinsideapps/clientfor client changes. docs/index.htmlis bilingual:data-i18nkeys need ZH entries; runscripts/build-landing.shafter utility-class changes.- Never mock or hand-edit product screenshots.
- Keep gitleaks allowlists narrow/commented and CI gates complete.
Releases and operations
- One product version spans root/apps/packages/plugins/client/desktop via release-please extra-files; routine bumps and releases are automated.
- Candidate config uses the prerelease strategy (rc); RELEASING.md documents operator publication and stable promotion.
- Tags define releases;
APP_VERSION/APP_REVISIONand OCI labels stamp images;/healthdoes not expose the version. - Stable tags publish exact/minor/latest, rc only the exact rc, main only edge/main-sha.
- Use Conventional squash commits; do not hand-edit released CHANGELOG sections or versions outside an authorized cut.
- Local build authorization never implies push/tag/deploy/EAS publication or desktop signing/feed activation.
- Keep the desktop bundle id/updater public key and the native app identity unchanged.
- Keep Compose topologies,
render.yaml,deploy/andscripts/deploy-smoke.mjsaligned (the smoke is the platform contract), migrate before startup, and back up withscripts/backup-db.sh(integrity/rotation checks). - Upstream publishing workflows are repository-gated; forks use
fork-*.ymlandnode scripts/check-extension-overlay.mjs --base upstream/main --strict.
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.

