team-conventions
/team-conventions
Przypomina konwencje monorepo Bun z pakietami core, types, api, ui i mcp oraz procedurę odstępstw od standardu.
- Autor
- kjgarza ↗
- Repozytorium
- marketplace-claude ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 18.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 18.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Przypomina konwencje monorepo Bun z pakietami core, types, api, ui i mcp oraz procedurę odstępstw od standardu.
Wyzwalacze z opisu
Oryginalny opis (EN)
This skill should be used when the user is working on a prototype monorepo with the standard Bun workspace structure (core, types, api, ui, mcp packages), mentions "team defaults", "deviation protocol", "our conventions", "standard stack", asks about anti-patterns, or references @repo/types, @repo/core, Bun workspaces, or any of the stable packages. It also applies when the user mentions "plan mode" in the context of suggesting alternatives to established patterns.
Jak działa
- Deviation Protocol
- Default Stack
- Research Workflow
- Package Roles
- Testing Defaults
- Replace-Not-Layer Principle
- Common Anti-Patterns to Avoid
- Related Skills
Podgląd SKILL.md
--- name: team-conventions description: > This skill should be used when the user is working on a prototype monorepo with the standard Bun workspace structure (core, types, api, ui, mcp packages), mentions "team defaults", "deviation protocol", "our conventions", "standard stack", asks about anti-patterns, or references @repo/types, @repo/core, Bun workspaces, or any of the stable packages. It also applies when the user mentions "plan mode" in the context of suggesting alternatives to established patterns. --- # Team Conventions for Prototype Development These conventions apply to all prototypes built with this team's standard monorepo structure. Multiple people work on each prototype, so consistency matters. ## Deviation Protocol When working in **execution mode**, follow the defaults below without question. When working in **Plan mode** and an alternative to a default is worth considering, follow this protocol: 1. **State the default**: "Our team default for this is X." 2. **Name the alternative**: "For this prototype, Y could work better because..." 3. **Explain the trade-off**: What do we gain? What team consistency do we lose? 4. **Flag the blast radius**: - **Low risk**: Change is isolated to `packages/core` (the variable package) - **Medium risk**: Change affects one of the stable packages (api, ui, or mcp) - **High risk**: Change ripples across multiple packages or affects `@repo/types` 5. **Let the human decide.** Never silently deviate from defaults. When a deviation is approved, add it to the project's CLAUDE.md under "Deviations from Team Defaults" with: what was changed, why, who approved it, and what other team members should watch out for. The core package is expected to change tech per prototype — that is low risk by design. API, UI, and MCP stacks changing is medium-to-high risk because it creates inconsistency across prototypes and requires the team to context-switch. ## Default Stack - **Runtime**: Bun (not Node.js) - **Monorepo**: Bun workspaces - **Linting + Formatting**: Biome (not ESLint, not Prettier) - **Testing**: `bun:test` (not Jest, Vitest, etc.) - **CI**: GitHub Actions (`.github/workflows/ci.yml`) - **Task runner**: justfile (not Makefile, not npm scripts for complex tasks) - **API**: Hono + @hono/zod-openapi. Routes use `createRoute()` + `app.openapi()`. Paths follow JSON:API spec. - **UI**: Next.js 16+ App Router + shadcn/ui + Lucide icons. Server Components by default. Server Actions for mutations. Design tokens over hard-coded styles. - **MCP**: @modelcontextprotocol/sdk with stdio transport. Actor pattern when using domain entities. - **Database**: `bun:sqlite` when persistence is needed. Not better-sqlite3, Prisma, or Drizzle unless deviation approved. - **Types**: Shared `@repo/types` package. Types and Zod schemas defined once. - **Entity Modeling**: Use Schema.org property names where a relevant type exists (e.g. `headline` not `title`, `datePublished` not `publishedAt`, `text` not `body`). Only include fields actually needed; enforce strict types. - **Infrastructure**: SST v3 (optional — use when deploying to AWS) ## Research Workflow When introducing **new technologies** to the stack (libraries, frameworks, tools not already in the defaults above), use the `/context7` MCP to fetch up-to-date documentation and examples before writing code. This prevents hallucinated APIs and outdated patterns. ## Package Roles - `@repo/core` — All business logic. **Variable tech stack per prototype.** - `@repo/types` — All shared types and Zod schemas. Single source of truth. - `packages/api` — Thin HTTP wrapper around core. Hono + OpenAPI. - `packages/ui` — Dashboard visualisation. Next.js + shadcn/ui. - `packages/mcp` — Thin MCP wrapper around core. Official SDK. ## Testing Defaults - Every generated package must have test infrastructure scaffolded before development begins - Use `superpowers:test-driven-development` for new features - Minimum: one test file per source file with business logic - CI must pass `bun test` before merge - Run `/generate-tests` after scaffolding to set up test directories, helpers, and example tests - Test files mirror source structure: `src/routes/items.ts` → `tests/routes/items.test.ts` ## Replace-Not-Layer Principle When introducing a new approach, delete the old code in the same PR. Do not layer new code on top of old code and leave both in place. **Deviation protocol addition** — when evaluating an alternative approach, add this step: > **Replacement Check** — Does this replace existing functionality? If yes, identify and > remove the old implementation in the same PR. Do not leave dead code. **Anti-patterns:** - Keeping dead code "just in case" — if it's in git history, it's recoverable - Adding a new utility alongside the old one without removing the old one - Wrapping old code in new abstractions instead of replacing it - Leaving `// TODO: remove old implementation` comments **Enforcement:** - Run `/simplify` to catch accumulated layers - Code review (`superpowers:requesting-code-review`) should flag layered code - When in doubt, delete — git has the history ## Common Anti-Patterns to Avoid - Express/Fastify middleware patterns (`req, res, next`) instead of Hono context - Pages Router patterns (`getServerSideProps`) instead of App Router - Client-side data fetching (`useEffect` + `fetch`, Tanstack Query) instead of RSC - Duplicating types across packages instead of using `@repo/types` - Business logic in API handlers or MCP tools instead of `@repo/core` - `process.env` instead of `Bun.env` - ESLint/Prettier instead of Biome - Jest/Vitest instead of `bun:test` - Hard-coded colors/spacing in UI instead of design tokens - Calling actor methods outside `provide()` callback - Missing `.passthrough()` on Zod schemas for external API data - Skipping validation before `provide()` in actor pattern - Verb-based API paths (`/items/create`) instead of JSON:API resource paths (`POST /items`) - Inventing field names (`title`, `publishedAt`, `body`) when a relevant Schema.org type exists (`headline`, `datePublished`, `text`) ## Related Skills For package-specific patterns, consult the corresponding skill: - **`prototyping:generate-api`** — Hono + @hono/zod-openapi route patterns - **`prototyping:generate-ui`** — Next.js + shadcn/ui dashboard patterns - **`prototyping:generate-mcp`** — MCP server tool patterns - **`prototyping:init-prototype`** — Bootstrap a new monorepo - **`prototyping:generate-tests`** — Scaffold test infrastructure per package - **`prototyping:development-workflow`** — Bridge scaffolding to development with skill chaining
Wersje
W bazie nie ma innych skilli o nazwie team-conventions.
Migawka bazy z 13.11.2026 · wersja paczki 986c953659f1 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100init-prototype
Zakłada monorepo prototypu ze standardowymi pakietami core, api, ui, mcp i types, połączonymi przez workspaces Bun. - 100monorepo
Podaje skrypty monorepo, szkielety pakietów i konwencje: uruchamianie bun run, budowanie, testy, typecheck, lintowanie i tworzenie nowych pakietów. - 90bun-script
Pisze skrypt TypeScript dla Bun, stosując szablon, konwencje i wymagane wzorce. - 100generate-tests
Tworzy infrastrukturę testową dla monorepo z prototypem: konfigurację bun:test, helpery, wzorce testów i brakujące pliki testowe. - 100bun-nextjs
Wspiera pracę z Next.js na Bun: uruchamianie aplikacji, rozwój, create-next-app i budowanie z użyciem Bun jako runtime. - 95pnpm-workspace
Konfiguruje monorepo w pnpm: strukturę workspace, protokół workspace:*, kolejność budowania i filtrowanie poleceń między pakietami.