Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

cmk:project-layout

/cmk:project-layout

Zakłada lub sprawdza układ monorepo według ról, z obszarami roboczymi dla ekosystemów i zasadami umieszczania bibliotek.

Repozytorium
ai-devkit ↗
Licencja
MIT
Ostatnia zmiana repozytorium
20.10.2026

Ocena i bezpieczeństwo

80/ 100Klasa: dobry
Format15 / 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ść25 / 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
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 20.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

Zakłada lub sprawdza układ monorepo według ról, z obszarami roboczymi dla ekosystemów i zasadami umieszczania bibliotek.

Wyzwalacze z opisu

set up the repo structureorganize the monorepowhere should this package liverestructure foldersadd a new package
Oryginalny opis (EN)

Use when the user asks to "set up the repo structure", "organize the monorepo", "where should this package live", "restructure folders", "add a new package", or needs to establish or audit a role-first monorepo layout with per-ecosystem workspaces, library placement rules, and vendored-source conventions.

Jak działa

  1. Modes
  2. Role-first top level
  3. One workspace per ecosystem, rooted at the repo root
  4. Cross-language name collisions
  5. Library promotion rule
  6. Private test packages
  7. external/ vendoring
  8. scripts/ grouped by responsibility
  9. Placement rubric
  10. Verify
Sekcje z nagłówków SKILL.md, w oryginale · 136 linii, 1 015 słów
Podgląd SKILL.md
---
name: cmk:project-layout
description: Use when the user asks to "set up the repo structure", "organize the monorepo", "where should this package live", "restructure folders", "add a new package", or needs to establish or audit a role-first monorepo layout with per-ecosystem workspaces, library placement rules, and vendored-source conventions.
version: 0.2.1
---

# Project Layout

Establish or audit a monorepo's top-level layout: which directory a new
package joins, how many workspaces each language ecosystem gets, when a
shared library graduates out of a single role-area, and how vendored upstream
source stays editable without becoming unmanageable.

## Modes

**Init** (default) — establish the role-first top level: pick the roles the
product actually needs, place existing packages by the rubric, and set one
workspace per ecosystem.

**Update** — place a new package, promote a shared library, or add a role
directory as the repo grows; change only what the request touches.

**Verify** — report-only audit against the checks under `## Verify`;
never mutates.

## Role-first top level

A repo-root directory names a **role** — what a thing is — never a language
or framework. Typical roles: `ui/` (frontends), `backend/` (deployable
services), `cli/` (operator tooling), `libs/` (shared libraries),
`contracts/` (on-chain or similarly deployed packages, when the product has
any), `infra/` (platform and IaC), `scripts/` (developer and operational
automation), `docs/` (documentation), `tests/` (private test packages). A
repo picks the roles it actually needs — not every project has `contracts/`
— but whatever roles exist stay named for role, not implementation language.
A new package always joins by role first: decide what it *is* before
deciding what its own language ecosystem wants inside that role.

Two languages can coexist inside one role directory (a Rust service and a TS
service both under `backend/`) — the role groups by responsibility, not by
toolchain.

## One workspace per ecosystem, rooted at the repo root

Each language ecosystem gets exactly one workspace, rooted at the repo root
— not one per role directory: one Cargo workspace covers every Rust crate
regardless of which role directory holds it, one package-manager workspace
(single lockfile) covers every JS/TS package the same way. Never create a
second, nested workspace file inside a subdirectory — a nested workspace
manifest or a second lockfile fragments dependency resolution and defeats the
point of a single workspace.

Package-filtered installs and commands (installing, building, or testing one
package by name) are how independent CI and deployment cadence is preserved
*without* nested workspaces — filter the command, don't fork the workspace.

## Cross-language name collisions

Two ecosystems sometimes want the same package name for related code (a wire
protocol implemented once in Rust and once in TypeScript). Only when that
collision actually happens, suffix the name with `-rs` / `-ts` (or the
equivalent for the ecosystems in play) to disambiguate. Do not suffix
pre-emptively — an unsuffixed name is correct until a second ecosystem
actually claims it.

## Library promotion rule

A library used by exactly one role-area may live inside that role area next
to its only consumer (e.g. a support crate under `cli/my-tool/core/`). The
moment a second role-area imports it, move it to the shared `libs/` root —
don't wait for a third consumer, and don't leave it in the original role area
"just this once" out of convenience. The trigger is the second real import,
not a predicted future one.

## Private test packages

`tests/e2e/` and `tests/parity/` (or a repo's equivalents) are private test
packages, not shared libraries: each owns its own runtime configuration and
lifecycle rather than inheriting one from a product package. A parity
package specifically owns cross-language renderers, golden vectors, and a
stale-fixture check that fails when a vector and its renderer drift apart.
Read `references/parity-testing.md` for the full pattern.

## `external/` vendoring

`external/` holds complete, editable mirrors of upstream source that is
governed in another repository — normal tracked files, not a submodule or a
dependency cache. Add one only when both halves are true: product-local
development on that source is actually needed, *and* a safe way to
round-trip changes back upstream exists. Every `external/` package needs a
baseline lockfile recording the upstream state it was mirrored from, and a
scripted round-trip: edit product-first, test in place, export the change
immediately, and sync again after upstream merges it. Exclude the vendored
tree's own nested git metadata and any build artifacts — the mirror is
source, not a second repository.

## `scripts/` grouped by responsibility

Group scripts by what they do, not by which package calls them: typical
groups are `dev/`, `workflow/`, `setup/`, `benchmark/`, and similar
responsibility buckets. Keep the scripts root itself down to stable, public
command wrappers — thin entry points meant to be called by name from outside
the directory. Anything else belongs inside a responsibility subdirectory.

## Placement rubric

When it's unclear where a new thing goes, answer in this order:

1. **What is its role?** (frontend, service, operator tool, library,
   on-chain package, infra, script, doc, test package)
2. **Does a role-area already own something like it?** If so, join that
   role area.
3. **Is it shared across role-areas?** If a second role-area needs to
   import it, it belongs in `libs/`, not inside either consumer.
4. **Is it a test package?** Private test packages own their own
   configuration; they don't inherit a product package's.
5. **Is it externally governed?** Source mirrored from an upstream
   repository with round-tripping obligations belongs in `external/`, not
   mixed into a product role area.
6. **Still unresolved?** Don't force-fit. Derive a proposal from widely
   accepted practice for the ecosystem, its conventions, and the repo's own
   existing precedents — and when more than one placement remains genuinely
   defensible, present the options, ask what the human has in mind, and help
   carry that intent through rather than deciding silently.

## Verify

Report-only — never mutate:

- Every top-level directory names a role, not a language or framework.
- Exactly one workspace/lockfile exists per language ecosystem, at the repo
  root — no nested workspace file or second lockfile in a subdirectory.
- No library is imported by two or more role-areas while still living
  inside one of them.
- Every private test package under `tests/` owns its own runtime
  configuration rather than inheriting a product package's.
- Every `external/` package has a baseline lockfile and a documented
  round-trip script; none embed nested git metadata or build artifacts.
- The `scripts/` root holds only stable, public command wrappers; everything
  else sits under a responsibility subdirectory.
Pliki w paczce (2)
  • SKILL.md 7 KB
  • references/parity-testing.md 2 KB

Wersje

W bazie nie ma innych skilli o nazwie cmk:project-layout.

Migawka bazy z 13.11.2026 · wersja paczki ca28335d5aca (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

  • 100project-structure
    Pomaga zaplanować strukturę projektu w Pythonie: układ src/ lub płaski, pliki __init__.py, __all__, marker py.typed, umieszczenie testów i monorepo kontra pojedynczy pakiet.
  • 100shared-packages
    Ustala wzorce wspólnych pakietów monorepo dla szybkich MVP: dodawanie bibliotek, narzędzi i importów między pakietami.
  • 100init-prototype
    Zakłada monorepo prototypu ze standardowymi pakietami core, api, ui, mcp i types, połączonymi przez workspaces Bun.
  • 100scaffold-project
    Tworzy szkielet nowego projektu TypeScript lub monorepo: układ pakietów, pliki konfiguracyjne i szkielety modułów, bez logiki aplikacji. Przydaje się przy starcie repozytorium od zera.
  • 95monorepo
    Konfiguruje monorepo w Nx, Turborepo lub pnpm workspaces, optymalizuje buildy i zarządza współdzielonym kodem.
  • 90monorepo-workspaces
    Prowadzi monorepo JavaScript i TypeScript z workspaces, orkiestracją zadań i wersjonowaniem wewnętrznych pakietów, gdy buildy i instalacje rosnącego monorepo zwalniają.

Uwagi i zgłoszenia

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