milky-kit
Personal project kit for full-stack work. Ships paradigm-complete stack templates, composable modules for cross-cutting concerns (CI, security, ghlobes), and a Claude Code plugin that scaffolds new projects and retrofits existing ones.
The two layers
Two kinds of things live in this repo, and they compose differently. Mixing them up is the trap most kit repos fall into.
Templates (alternatives) — pick one per project
A template is a complete paradigm choice for a project. Each template owns its rules, scaffold tree, CLAUDE.md template, and capability set. Templates don't compose with each other.
| Template | Stack | Headline capabilities |
|---|
templates/effect-api | TS + Effect + @effect/platform + @effect/sql-drizzle + Postgres | HttpApi-driven server, auto-generated OpenAPI + Swagger, typed HttpApiClient, MCP server (@effect/ai), typed error channel, Schema-everywhere boundaries, Layer/Context DI, @effect/vitest |
templates/hono-api | TS + Hono + Drizzle + Effect (flavored) | Hono RPC, Zod-OpenAPI (manual), middleware DI, Workers deploy |
templates/react-spa | TS + React + TanStack Router/Query + Vite | Suspense-first data fetching, file-based routing, UI variants |
templates/axum-api | Rust + Axum + SeaORM + Postgres | Clean-architecture domain split, typed Result errors, OpenAPI via utoipa |
templates/bun-scripts | Bun + TS | Single-file scripts, no build step, Bun-native APIs |
Modules (composables) — layer on top of any template
A module is one orthogonal concern that composes cleanly with any template. They don't conflict because each module addresses a different concern.
| Module | What it adds |
|---|
modules/core | General rules, comments, config/env conventions, worktree mise tasks |
modules/ts | Paradigm-neutral TypeScript conventions, blank-lines style |
modules/effect | Effect-TS paradigm + universal clean architecture (domain/application/infrastructure/presentation). Use for any Effect project regardless of inbound protocol. |
modules/effect-http | @effect/platform HttpApi + Swagger + typed client + outbound HttpClient. Composes with effect. |
modules/effect-mcp | @effect/ai McpServer adapter. Composes with effect. |
modules/effect-sql | @effect/sql-drizzle + @effect/sql-pg repository pattern. Composes with effect + a DB module. |
modules/ci | GitHub Actions workflow + per-package script enforcement |
modules/security | OSV-Scanner, zizmor, pinned actions, GitHub-context shell-injection prevention |
modules/pnpm | pnpm workspace config + pnpm-specific supply-chain controls (cooldown, safe-chain, trust policy, onlyBuiltDependencies) |
modules/bun | Bun workspace + Bun-specific security notes (with honest gaps) |
modules/ghlobes | .ghlobes.toml scaffold + the glb agent rule file |
modules/postgres | docker-compose Postgres + Effect-flavored @effect/sql-pg notes |
modules/sqlite | local SQLite scaffold |
modules/release-please | GitHub Actions release pipeline + Trusted Publishing OIDC (variants: npm publish / tag-only) |
A project's .claude/rules/ directory symlinks one rule per file into the chosen template + modules. Claude Code auto-loads every .md (including symlinks) under .claude/rules/ at session start.
How a project consumes the kit
Rules are symlinked, not copied. Each project's .claude/rules/ directory holds one symlink per rule, pointing through ~/.claude/kit/ to the live source-of-truth file in this repo:
my-project/.claude/rules/
├── general.md -> ~/.claude/kit/modules/core/rules/general.md
├── comments.md -> ~/.claude/kit/modules/core/rules/comments.md
├── effect.md -> ~/.claude/kit/modules/effect/rules/effect.md
├── effect-http.md -> ~/.claude/kit/modules/effect-http/rules/effect-http.md
├── effect-sql.md -> ~/.claude/kit/modules/effect-sql/rules/effect-sql.md
├── postgres.md -> ~/.claude/kit/modules/postgres/rules/postgres.md
└── ...
Claude Code auto-loads every .md (including symlinks) under .claude/rules/ at session start — no @-refs needed in CLAUDE.md. The symlinks live in git (mode 120000); they reconstruct on checkout as long as the target exists on that machine.
Edit a rule file in milky-kit, and every project picks it up immediately — the symlinks point to the live file. Single source of truth, no copy, no drift.
Scaffold files (gitignore, biome.json, tsconfig, CI workflows, .ghlobes.toml) are copied once at init, then the project owns them. Updates flow through the upgrade skill.
Setup
One-time, per machine. Two parts: a symlink for rule resolution, and a plugin install for the skills.
1. Symlink the kit at ~/.claude/kit
Clone milky-kit anywhere stable on your machine (not Downloads or anywhere your OS may clean), then symlink:
