organizing-fsd-architecture
Skill11 starsChanged 51 days agoMITView on GitHub
Guides organization of code using Feature-Sliced Design (FSD) architecture. Use when structuring projects, creating new features, determining file and layer placement, or reviewing architectural decisions. Also monitors codebase size and proactively suggests structural improvements.
In this repository44 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- auditing-uiSkill
- browser-testingSkill
- capturing-product-mediaSkill
- ci-local-exportSkill
- ci-pulseSkill
- ci-quarantineSkill
- ci-statusSkill
- creating-pull-requestsSkill
- debugging-systematicallySkill
- debugging-test-failuresSkill
- debugging-typescript-errorsSkill
- deps-weeklySkill
- designing-frontendSkill
- opensrcSkill
- runtime-watchSkill
- stewarding-ci-pipelineSkill
- syncing-agent-skillsSkill
- verification-before-completionSkill
- vision-drift-checkSkill
- visual-companionSkill
- writing-adrsSkill
- writing-app-copySkill
- writing-blog-postsSkill
- writing-changelogsSkill
- writing-developer-guidesSkill
- writing-for-humansSkill
- writing-to-usersSkill
- adding-config-fieldsSkill
- clarifying-requirementsSkill
- maintaining-dependenciesSkill
- maintaining-dev-playgroundSkill
- managing-specsSkill
- marketplace-devSkill
- orchestrating-parallel-workSkill
- reading-session-transcriptsSkill
- receiving-code-reviewSkill
- requesting-code-reviewSkill
- styling-with-tailwind-shadcnSkill
- test-driven-developmentSkill
- upgrading-runtime-dependenciesSkill
- working-in-worktreesSkill
- dorkbot-triageSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 66
When features need to share data or logic:
- Distinctive: line 72
Never let one feature's model/hooks import another feature's model/hooks.
- Distinctive: line 89
When suggesting, name the threshold that fired and the concrete restructure, then ask before moving files.
- Distinctive: line 108
Putting everything in shared/: only truly reusable, domain-agnostic code belongs in shared
- Very specific: line 111
Skipping index.ts: every module needs a public API barrel export
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Organizing FSD Architecture
Overview
This skill provides expertise for implementing Feature-Sliced Design (FSD) in the DorkOS monorepo. FSD organizes code by business domains with clear layer boundaries and unidirectional dependency rules.
The full layer-import matrix, cross-module rules, segment structure, and barrel/alias conventions live in .claude/rules/fsd-layers.md — that rule is the authority; this skill is the placement and size-monitoring guidance on top of it.
When to Use
- Creating new features, widgets, or entities in
apps/client - Deciding where code should live (which layer/segment)
- Reviewing imports for layer violations
- Refactoring components into FSD structure
- Adding new services to
apps/server(size-aware guidance)
The Layer Spine
Strict top-to-bottom dependency flow within apps/client/src/layers/:
app → widgets → features → entities → sharedHigher imports lower, never the reverse; same-level model/hook cross-imports are forbidden (UI composition across features is allowed). See .claude/rules/fsd-layers.md for the per-layer import matrix and code examples.
Step-by-Step: Determine the Correct Layer
Is it a reusable utility, UI primitive (Button, Card), or type?
└─ YES → shared/
Is it a core business entity (Session, Agent, Workspace)?
└─ YES → entities/[entity-name]/
Is it a complete user-facing feature (chat, command palette, settings)?
└─ YES → features/[feature-name]/
Is it a large composition of multiple features (app layout, dashboard)?
└─ YES → widgets/[widget-name]/
Is it app initialization, providers, or entry point?
└─ YES → the src/ root shell (App.tsx, AppShell.tsx, main.tsx, router.tsx)DorkOS-Specific Layer Mapping
Current shape of apps/client/src/layers/ (representative, not exhaustive — ls the layer for ground truth):
| Layer | Scale | Representative modules |
shared/ | base layer | ui/ (shadcn components), model/ (TransportContext, app-store, useTheme, useIsMobile), lib/ (cn, Transport implementations) |
entities/ | ~14 modules | session, agent, command, marketplace, mesh, relay, runtime, tasks, workspace |
features/ | ~30 modules | chat, command-palette, session-list, settings, marketplace, agents-list, dashboard-*, onboarding |
widgets/ | ~9 modules | app-layout, session, dashboard, agents, marketplace, tasks |
The app shell (App.tsx, AppShell.tsx, main.tsx, router.tsx) lives at the src/ root and may import from any layer.
Cross-Feature Communication
When features need to share data or logic:
- UI composition (allowed) — a feature's UI may render a sibling feature's component (ChatPanel renders CommandPalette)
- Lift shared logic to entities — hooks used by several features belong in an entity module
- Zustand store in shared — for truly global UI state (
shared/model/app-store.ts)
Never let one feature's model/hooks import another feature's model/hooks.
Size Monitoring
Proactively suggest structural improvements when these thresholds are hit:
Client:
- A feature reaches 20+ files → split into multiple features or extract entities
- A module accumulates logic used by several features → lift it to
entities/orshared/
Server (apps/server/src/) — already domain-grouped (services/<domain>/, flat routes/; see .claude/rules/server-structure.md):
- A new service always joins an existing domain — no loose files at
services/root - Several related services emerge with a clear boundary and no home → propose a new domain directory (never for a single orphan file)
- A single domain grows unwieldy or two services develop circular/unclear dependencies → propose splitting the domain
When suggesting, name the threshold that fired and the concrete restructure, then ask before moving files.
Detecting Layer Violations
# Find features importing from other features
grep -r "from '@/layers/features/" apps/client/src/layers/features/ --include="*.ts" --include="*.tsx" | grep -v "__tests__"
# Find entities importing from features (should be 0)
grep -r "from '@/layers/features/" apps/client/src/layers/entities/ --include="*.ts"
# Find shared importing from anywhere except shared
grep -r "from '@/layers/" apps/client/src/layers/shared/ --include="*.ts" | grep -v "from '@/layers/shared"(ESLint no-restricted-imports enforces the hierarchy as errors; these greps are for quick audits.)
Common Pitfalls
- Putting everything in shared/: only truly reusable, domain-agnostic code belongs in shared
- Feature-to-feature model imports: lift shared logic to entities
- Giant features: 20+ files means split
- Skipping index.ts: every module needs a public API barrel export
- Transport in wrong layer: the Transport interface lives in
packages/shared, implementations inshared/lib/, TransportContext inshared/model/
References
.claude/rules/fsd-layers.md— Layer-import matrix, cross-module rules, segments, import conventions.claude/rules/server-structure.md— Server domain layout and service placementcontributing/project-structure.md— Full FSD patterns, directory layout, adding featurescontributing/architecture.md— Hexagonal architecture, Transport interface
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

