agentleFS
dork-labsdork-labs/dorkos/.agents/skills/organizing-fsd-architecture/SKILL.md

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.

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
  1. Distinctive:

    When features need to share data or logic:

    line 66
  2. Distinctive:

    Never let one feature's model/hooks import another feature's model/hooks.

    line 72
  3. Distinctive:

    When suggesting, name the threshold that fired and the concrete restructure, then ask before moving files.

    line 89
  4. Distinctive:

    Putting everything in shared/: only truly reusable, domain-agnostic code belongs in shared

    line 108
  5. Very specific:

    Skipping index.ts: every module needs a public API barrel export

    line 111

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 → shared

Higher 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):

LayerScaleRepresentative modules
shared/base layerui/ (shadcn components), model/ (TransportContext, app-store, useTheme, useIsMobile), lib/ (cn, Transport implementations)
entities/~14 modulessession, agent, command, marketplace, mesh, relay, runtime, tasks, workspace
features/~30 moduleschat, command-palette, session-list, settings, marketplace, agents-list, dashboard-*, onboarding
widgets/~9 modulesapp-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:

  1. UI composition (allowed) — a feature's UI may render a sibling feature's component (ChatPanel renders CommandPalette)
  2. Lift shared logic to entities — hooks used by several features belong in an entity module
  3. 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/ or shared/

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 in shared/lib/, TransportContext in shared/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 placement
  • contributing/project-structure.md — Full FSD patterns, directory layout, adding features
  • contributing/architecture.md — Hexagonal architecture, Transport interface

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.