Przejdź do treści
Biblioteka skilli
Programowanie · Nauka i wyjaśnianie

team-conventions

/team-conventions

Przypomina konwencje monorepo Bun z pakietami core, types, api, ui i mcp oraz procedurę odstępstw od standardu.

Licencja
MIT
Ostatnia zmiana repozytorium
18.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 18.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

team defaultsdeviation protocolour conventionsstandard stackplan mode
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

  1. Deviation Protocol
  2. Default Stack
  3. Research Workflow
  4. Package Roles
  5. Testing Defaults
  6. Replace-Not-Layer Principle
  7. Common Anti-Patterns to Avoid
  8. Related Skills
Sekcje z nagłówków SKILL.md, w oryginale · 117 linii, 876 słów
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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.