Milky Kit
milkyskies/milky-kit
Templates e módulos reutilizáveis para full-stack via regras Claude
Ver no GitHubKit de projeto full-stack que fornece templates paradigma-completos (Effect, Hono, React, Axum, Bun) e módulos composáveis para preocupações transversais (CI, segurança, banco de dados). Inclui plugin Claude Code que scaffolda novos projetos e retrofita existentes via regras compartilhadas.
Instalação
npx convez-ai milkyskies/milky-kit1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Scaffoldar novos projetos TypeScript/Rust com stack pré-configurado
- Aplicar convenções de código e arquitetura de forma consistente em múltiplos projetos
- Gerenciar pipelines CI/CD, segurança (OSV, zizmor) e release automation
Veredito

Ferramenta focada para quem trabalha em full-stack TypeScript/Rust e valoriza reutilização de patterns através de regras Claude. Força está em templates bem-estruturados e módulos ortogonais; curva de aprendizado é moderada por exigir compreensão da filosofia de composição.
README
A tradução para o português deste README ainda está na fila.
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:
git clone https://github.com/milkyskies/milky-kit <wherever-you-keep-projects>/milky-kit
ln -s <wherever-you-keep-projects>/milky-kit ~/.claude/kit
ls -la ~/.claude/kit # verify it resolves
The kit can live at any path as long as ~/.claude/kit points to it. The symlink is what consuming projects' .claude/rules/ symlinks resolve through. The kit's own .claude/rules/ uses relative symlinks back into its modules/, so cloning on a new machine works without any setup — it eats its own dog food.
2. Install the Claude Code plugin
In any Claude Code session (project doesn't matter for the install):
/plugin marketplace add milkyskies/milky-kit
/plugin install milky-kit@milkyskies
Claude clones the repo to its own plugin cache and registers the skills. Run /help to confirm /milky-kit:new, :retrofit, :upgrade, :realign, :edit, :kit-modify, :check-version, :purge, :mode, plus the pre-existing :ship, :land, :rulify, :simplify, etc. all appear.
To pull future kit changes:
/plugin marketplace update milkyskies
Scaffold a new project
In Claude Code, in an empty directory:
/milky-kit:new
The skill asks:
- Which template? (
effect-api,hono-api,react-spa,axum-api,bun-scripts) - Which composable modules? (multi-select: ghlobes, security, ci, postgres, etc.)
- Variants where applicable (db backend, auth, UI library)
- Project name + directory
- Any project-specific rules to append? (free-text, written under
## Project-specificin CLAUDE.md)
Then it copies the template + module scaffolds, creates .claude/rules/ symlinks for every chosen rule, writes a thin CLAUDE.md (project description + project-specific section), runs the package manager install, initializes git, and commits the initial scaffold.
Apply the kit to an existing repo
/milky-kit:retrofit
The skill detects the current stack, asks which modules to apply, copies in scaffold files (merging, not overwriting), creates .claude/rules/ symlinks for the new rules, and writes a thin CLAUDE.md if none exists. Existing project-specific content stays untouched.
Upgrade an existing project
/milky-kit:upgrade
The skill reads .milky-kit-version, walks milky-kit's git log since that SHA, and guides you through each change that affects your project's stack — with judgment, because every project diverges from the kit over time.
Workflow modes
Each project picks one workflow mode via the .milky-kit-mode file at its root:
| Mode | Branch | Worktree | Ship via | Best for |
|---|---|---|---|---|
main | no — on main | no | push to main | the kit itself, solo solo work, no review wanted |
branch (default) | yes — in root checkout | no | PR to main | typical solo work, GitHub-native flow |
worktrees | yes — lead on a branch in root | yes — delegated tasks in ../<worktree-dir>/<num>/ | PR to main | one lead agent that spawns parallel sub-agents; isolation matters |
Flip per project at any time:
/milky-kit:mode main # switch to main
/milky-kit:mode branch # switch to branch
/milky-kit:mode worktrees # switch to worktrees
/milky-kit:mode # show current
workflow.md reads .milky-kit-mode at session start and follows the matching task workflow section.
Versioning
milky-kit has no semver tags (yet). The version of milky-kit a project was scaffolded against is the commit SHA at scaffold time, recorded in the project's .milky-kit-version file. milky-kit:check-version compares that SHA against git rev-parse HEAD of the local kit checkout and prints what's changed since.
Tagged releases may come later as the kit stabilizes; the skills will prefer tag names over SHAs once they exist.
Repo layout
milky-kit/
├── README.md
├── .claude-plugin/ Claude Code plugin manifest
├── skills/ Plugin skills (new, retrofit, upgrade, realign, edit, kit-modify, check-version, purge, mode, ship, land, write-pr, arch-diagrams, rulify, simplify, retrospective, and template-specific helpers)
├── templates/ Stack templates (alternatives — pick one per project)
│ ├── effect-api/
│ │ ├── rules/
│ │ ├── scaffold/ One-shot copy at init
│ │ └── CLAUDE.md Template for the project's CLAUDE.md
│ ├── hono-api/
│ ├── react-spa/
│ ├── axum-api/
│ └── bun-scripts/
└── modules/ Cross-cutting modules (composables — layer freely)
├── core/
├── ts/ Paradigm-neutral TS rules
├── ci/
├── security/
├── pnpm/
├── bun/
├── ghlobes/
├── postgres/
├── sqlite/
└── release-please/
Why templates vs modules
The split exists because not every concern composes. Templates declare paradigm choices that conflict with each other (Effect's typed error channel vs Hono's middleware throws; Rust's Result vs TS's Promise). You pick one. Modules declare orthogonal concerns (CI is independent of the API framework; ghlobes is independent of the language). They layer freely.
This split is what makes the asymmetry between templates honest. effect-api ships MCP, hono-api does not — that's not a missing feature, it's a different paradigm with a different ceiling. Each template's README.md lists its capabilities so projects choose with eyes open.
Task tracking
This kit uses glb (ghlobes) for issue tracking via GitHub Issues + Projects. See modules/ghlobes/rules/glb.md for the agent workflow and command reference.