Devian v10 — Workspace Management

Defines and enforces the single workspace structure and npm policies for Devian TypeScript projects (v10).

What This Skill Does

This skill helps you manage Devian v10 TypeScript projects by:

Project Structure

Single Workspace Root

The project uses a **single workspace root** architecture:

```

framework-ts/

├── package.json # Root workspace manifest

├── package-lock.json # Only valid lockfile

├── node_modules/ # Only valid node_modules

├── tsconfig.json # Root TypeScript config

├── module/*/ # Core modules

├── apps/*/ # Applications

└── tools/*/ # Build tools

```

Hard Rules

1. Root-Only npm Operations

**MUST** run all npm commands from `framework-ts/` directory:

```bash

cd framework-ts

npm install

npm ci

npm run <script>

```

**MUST NOT** run npm commands in subdirectories (`module/*`, `apps/*`, `tools/*`).

2. Single Lockfile Policy

Instructions

Step 1: Verify Workspace Root

When working with a Devian v10 project:

1. Check that you're in the `framework-ts/` directory

2. Verify `package.json` contains `"workspaces"` array

3. Confirm workspace paths: `["module/*", "apps/*", "tools/*"]`

Step 2: Install Dependencies

Always install from the workspace root:

```bash

cd framework-ts

npm install

```

For CI/CD environments:

```bash

cd framework-ts

npm ci

```

Step 3: Run Workspace Scripts

Use the standardized npm workspace scripts:

| Command | Purpose | Example |

|---------|---------|---------|

| `npm run builder -- <input>` | Run build tool | `npm run builder -- ../input/input_common.json` |

| `npm run archive -- <args>` | Archive project | `npm run archive -- --output ./archive` |

| `npm run dev:client` | Start client dev server | `npm run dev:client` |

| `npm run start:server` | Start game server | `npm run start:server` |

Step 4: Handle TypeScript Paths

The root `tsconfig.json` defines module aliases:

When importing core modules:

```typescript

import { Something } from '@devian/core';

```

Step 5: Troubleshoot Lockfile Issues

If you encounter lockfile corruption or inconsistencies:

```bash

cd framework-ts

rm -rf node_modules package-lock.json

npm install

```

**Warning**: Only do this when absolutely necessary. Prefer `npm ci` in CI/CD.

Validation Checklist

Before committing changes:

Common Mistakes to Avoid

1. **Running `npm install` in subdirectories** — Always use workspace root

2. **Creating nested node_modules** — Remove immediately if found

3. **Ignoring workspace scripts** — Use standardized scripts instead of direct workspace commands

4. **Modifying subdirectory package.json versions** — Manage versions through workspace root

Related Skills

Technical Details

Root package.json Schema

```json

{

"name": "devian-framework-ts",

"version": "10.0.0",

"type": "module",

"private": true,

"workspaces": [

"module/*",

"apps/*",

"tools/*"

],

"scripts": {

"builder": "npm -w builder run build --",

"archive": "npm -w archive run archive --",

"dev:client": "npm -w game-client run dev",

"start:server": "npm -w game-server run start"

}

}

```

TypeScript Configuration

Key settings in `framework-ts/tsconfig.json`:

Status