# house-rules

> A TypeScript monorepo template and the house plugin behind it: checked rules for code that agents write.

Every page below is a Markdown file. The same page as HTML lives at the path without `.md`. https://stack.kubaszwajka.com/llms-full.txt holds every page in one file. The law for code in house-rules is AGENTS.md in the repository. Generated rule and skill pages come from packages/rules and skills/, so they match the code at the `docs/site` ref, and every source link points at that ref.

## Start here

- [What house-rules is](https://stack.kubaszwajka.com/start/what-is-house-rules.md): A template for TypeScript monorepos, the plugin that checks it, and the fence that makes agents run the checks.
- [For agents](https://stack.kubaszwajka.com/start/for-agents.md): How an agent reads this site, which files are the law, and which skill to load for which job.
- [Use it in your project](https://stack.kubaszwajka.com/start/adopt.md): Start a repo from the template, or install the house plugin and the capability library into an app you already have.

## Guides

- [The stack](https://stack.kubaszwajka.com/guides/the-stack.md): The template's workspace, its apps and packages, the layers inside an app, and the thin configs over the house plugin.
- [What pnpm check runs](https://stack.kubaszwajka.com/guides/checks.md): The order of the checks, the tool behind each one, and the prose rules that no tool can check.
- [The fence](https://stack.kubaszwajka.com/guides/the-fence.md): The git hook, the harness hooks, and the command policy that stop an agent from skipping the checks.
- [Pins and install policy](https://stack.kubaszwajka.com/guides/pins-and-install-policy.md): Exact versions everywhere, a one-day release age, and no install scripts.
- [Capabilities and authorization](https://stack.kubaszwajka.com/guides/capabilities.md): One action is one contract and one handler. The Grant and Approval gates run before it, and the module checks the object.
- [Modules and data](https://stack.kubaszwajka.com/guides/modules-and-data.md): A module is a package with one public entry. It owns its tables, its migrations, and its transactions.
- [Effect](https://stack.kubaszwajka.com/guides/effect.md): How Effect 4 code is written in the stack, and which of those rules the compiler checks.
- [The MCP adapter](https://stack.kubaszwajka.com/guides/mcp-adapter.md): How agents call an app's use-cases over MCP, with OAuth, a small tool catalogue, and access that never exceeds the user's.

## Rules

- [All rules](https://stack.kubaszwajka.com/rules.md): Every check in pnpm check that comes from the house plugin: 33 rules over 5 tools.
- [ESLint rules](https://stack.kubaszwajka.com/rules/eslint.md): The 8 checks the house plugin runs through ESLint.
- [comment-discipline](https://stack.kubaszwajka.com/rules/eslint/comment-discipline.md): Top-level narrative, multiline comments, adjacent groups; keeps one-line whys beside code
- [no-broken-relative-links](https://stack.kubaszwajka.com/rules/eslint/no-broken-relative-links.md): Relative Markdown links to untracked paths
- [design-no-raw-color](https://stack.kubaszwajka.com/rules/eslint/design-no-raw-color.md): Raw hex, rgb(), hsl(), etc. in CSS
- [design-no-raw-color-literal](https://stack.kubaszwajka.com/rules/eslint/design-no-raw-color-literal.md): Raw hex, rgb(), hsl(), etc. in JS/TS strings
- [design-no-unknown-token](https://stack.kubaszwajka.com/rules/eslint/design-no-unknown-token.md): var(--name) with no definition
- [design-scale-value](https://stack.kubaszwajka.com/rules/eslint/design-scale-value.md): CSS values off a fixed scale
- [use-case-is-capability](https://stack.kubaszwajka.com/rules/eslint/use-case-is-capability.md): A use-case file that does not export exactly one implement(...) capability, exports a second contract, or exports another value
- [no-hand-rolled-surface](https://stack.kubaszwajka.com/rules/eslint/no-hand-rolled-surface.md): Tool.make, Rpc.make, or HttpApiEndpoint.<method> outside packages/capability/**
- [Dependency Cruiser rules](https://stack.kubaszwajka.com/rules/dependency-cruiser.md): The 16 checks the house plugin runs through Dependency Cruiser.
- [no-cycles](https://stack.kubaszwajka.com/rules/dependency-cruiser/no-cycles.md): Circular imports
- [packages-do-not-import-apps](https://stack.kubaszwajka.com/rules/dependency-cruiser/packages-do-not-import-apps.md): Packages importing apps
- [apps-do-not-import-other-apps](https://stack.kubaszwajka.com/rules/dependency-cruiser/apps-do-not-import-other-apps.md): Apps importing other apps
- [packages-imported-by-name](https://stack.kubaszwajka.com/rules/dependency-cruiser/packages-imported-by-name.md): Local imports of packages by path instead of name
- [packages-public-entry-only](https://stack.kubaszwajka.com/rules/dependency-cruiser/packages-public-entry-only.md): Imports of package internals
- [delivery-does-not-import-server](https://stack.kubaszwajka.com/rules/dependency-cruiser/delivery-does-not-import-server.md): Delivery layer importing server layer
- [server-does-not-import-delivery](https://stack.kubaszwajka.com/rules/dependency-cruiser/server-does-not-import-delivery.md): Server layer importing delivery layer
- [use-cases-do-not-import-outer-layers](https://stack.kubaszwajka.com/rules/dependency-cruiser/use-cases-do-not-import-outer-layers.md): Use-cases importing delivery or server
- [no-unresolved-deep-package-imports](https://stack.kubaszwajka.com/rules/dependency-cruiser/no-unresolved-deep-package-imports.md): Unresolved deep package imports
- [production-does-not-import-tests](https://stack.kubaszwajka.com/rules/dependency-cruiser/production-does-not-import-tests.md): Production code importing tests
- [tests-live-in-tests-dir](https://stack.kubaszwajka.com/rules/dependency-cruiser/tests-live-in-tests-dir.md): Test files outside tests/ folders
- [tests-do-not-import-internals](https://stack.kubaszwajka.com/rules/dependency-cruiser/tests-do-not-import-internals.md): Tests importing package internals
- [no-unresolved-imports](https://stack.kubaszwajka.com/rules/dependency-cruiser/no-unresolved-imports.md): Unresolved imports
- [app-code-in-layers](https://stack.kubaszwajka.com/rules/dependency-cruiser/app-code-in-layers.md): App code outside layer folders
- [use-cases-do-not-import-use-cases](https://stack.kubaszwajka.com/rules/dependency-cruiser/use-cases-do-not-import-use-cases.md): Use-case importing another use-case
- [no-ownerless-files](https://stack.kubaszwajka.com/rules/dependency-cruiser/no-ownerless-files.md): utils/, helpers/, misc/ files or folders
- [TypeScript rules](https://stack.kubaszwajka.com/rules/typescript.md): The 2 checks the house plugin runs through TypeScript.
- [Strict compiler flags](https://stack.kubaszwajka.com/rules/typescript/strict-compiler-flags.md): 15 flags: strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes, and more
- [Effect diagnostics](https://stack.kubaszwajka.com/rules/typescript/effect-diagnostics.md): 31 diagnostics set to error
- [Biome rules](https://stack.kubaszwajka.com/rules/biome.md): The 5 checks the house plugin runs through Biome.
- [noReExportAll](https://stack.kubaszwajka.com/rules/biome/no-re-export-all.md): export * from
- [noExcessiveLinesPerFile](https://stack.kubaszwajka.com/rules/biome/no-excessive-lines-per-file.md): Files over 300 lines (warn)
- [noNonNullAssertion](https://stack.kubaszwajka.com/rules/biome/no-non-null-assertion.md): ! non-null assertions
- [useFilenamingConvention](https://stack.kubaszwajka.com/rules/biome/use-filenaming-convention.md): Files not kebab-case or export
- [Formatter](https://stack.kubaszwajka.com/rules/biome/formatter.md): indentWidth 2, lineWidth 100, indentStyle space
- [Node rules](https://stack.kubaszwajka.com/rules/node.md): The 2 checks the house plugin runs through Node.
- [Exact pins](https://stack.kubaszwajka.com/rules/node/exact-pins.md): Every dependency must be an exact version, workspace:<exact>, or a Git spec with full commit SHA
- [house-rules-migrations](https://stack.kubaszwajka.com/rules/node/house-rules-migrations.md): Cross-module foreign keys, migrations or SQL strings that touch another package's tables, .sql files outside <package>/migrations/ (a package's fixtures/ and tests/ excepted), use-cases that open a transaction

## Skills

- [Skills](https://stack.kubaszwajka.com/skills.md): The 5 agent skills in house-rules, one page each.
- [Add a capability](https://stack.kubaszwajka.com/skills/add-a-capability.md): Add one action to an app as a capability. Define its contract with a permission, implement the handler on a module's service, call it from delivery, and test the gates and the typed errors.
- [Add an Effect module](https://stack.kubaszwajka.com/skills/add-an-effect-module.md): Add one Effect module as a workspace package and carry it through a use-case and a delivery handler in an app without breaking the workspace or layer rules.
- [Add an MCP tool](https://stack.kubaszwajka.com/skills/add-an-mcp-tool.md): Expose an existing use-case to agents as an MCP tool, and set up the MCP adapter in an app the first time, with OAuth, a small tool catalogue, and the tests that prove access holds.
- [Learn house-rules](https://stack.kubaszwajka.com/skills/learn-house-rules.md): Find your way around house-rules or a repo made from its template. Where the law, the words, the rules and the docs site are, and the order to read them in before you change code.
- [Write a docs page](https://stack.kubaszwajka.com/skills/write-a-docs-page.md): Add or change a page on the house-rules docs site in site/. Decide whether the page is hand-written or generated, place it, link it by relative path, and prove the build, the llms files and the checks.

## Reference

- [Glossary](https://stack.kubaszwajka.com/reference/glossary.md): The words house-rules uses, in one line each. CONTEXT.md holds the full definitions.
- [Commands](https://stack.kubaszwajka.com/reference/commands.md): Every root command in the stack, and the commands for this docs site.
- [Docs in the repo](https://stack.kubaszwajka.com/reference/repo-docs.md): The Markdown files in house-rules that this site links to, and what each one owns.