references/clean_architecture_dotnet.md
# Clean Architecture Template (.NET)
<!-- SCOPE: .NET Clean Architecture folder structure ONLY. Contains Api/Domain/Infrastructure layers, file naming. -->
<!-- DO NOT add here: Migration workflow → ln-720-structure-migrator SKILL.md -->
Reference structure for .NET backend projects.
---
## Directory Structure
```
src/
├── {Project}.Api/
│ ├── Controllers/
│ ├── DTOs/
│ │ ├── Requests/
│ │ └── Responses/
│ ├── Middleware/
│ ├── MockData/
│ ├── Extensions/
│ ├── Program.cs
│ └── appsettings.json
│
├── {Project}.Domain/
│ ├── Entities/
│ ├── Enums/
│ └── Common/
│
├── {Project}.Services/
│ ├── Interfaces/
│ └── Implementations/
│
├── {Project}.Repositories/
│ ├── Interfaces/
│ ├── Implementations/
│ └── Data/
│
└── {Project}.Shared/
├── Constants/
└── Helpers/
```
---
## Layer Responsibilities
| Layer | Project | Responsibilities | Dependencies |
|-------|---------|------------------|--------------|
| **API** | {Project}.Api | HTTP endpoints, DTOs, Middleware, Extensions | Services, Shared |
| **Domain** | {Project}.Domain | Entities, Enums, Business rules | None |
| **Services** | {Project}.Services | Business logic, Orchestration | Domain, Repositories |
| **Repositories** | {Project}.Repositories | Data access, Persistence | Domain |
| **Shared** | {Project}.Shared | Constants, Helpers, Extensions | None |
---
## Project References
| Project | References | Rationale |
|---------|------------|-----------|
| Api | Services, Shared | Needs business logic, utilities |
| Services | Domain, Repositories | Business logic uses entities and data |
| Repositories | Domain | Data layer maps to entities |
| Domain | (none) | Core, independent |
| Shared | (none) | Utilities, independent |
---
## API Layer Components
| Folder | Purpose | Contents |
|--------|---------|----------|
| Controllers/ | HTTP endpoints | One controller per entity/feature |
| DTOs/Requests/ | Input validation | Create/Update request classes |
| DTOs/Responses/ | Output formatting | Response classes, paginated responses |
| Middleware/ | Cross-cutting | Exception, Logging, CorrelationId |
| MockData/ | Development data | Static mock data per feature |
| Extensions/ | DI configuration | Service registration methods |
---
## Domain Layer Components
| Folder | Purpose | Contents |
|--------|---------|----------|
| Entities/ | Business objects | Entity classes inheriting BaseEntity |
| Enums/ | Domain enumerations | Status, Priority, Type enums |
| Common/ | Base classes | BaseEntity, AuditableEntity |
---
## Program.cs Structure
| Section | Purpose | Order |
|---------|---------|-------|
| Builder creation | Initialize WebApplicationBuilder | 1 |
| Serilog config | Configure structured logging | 2 |
| Service registration | AddControllers, AddSwagger, AddCors, AddHealthChecks | 3 |
| App services | AddApplicationServices extension | 4 |
| Build app | builder.Build() | 5 |
| Middleware pipeline | Correlation, Logging, Exception, CORS | 6 |
| Endpoints | MapControllers, MapHealthChecks | 7 |
| Run | app.Run() | 8 |
---
## NuGet Packages
| Package | Version | Purpose |
|---------|---------|---------|
| Swashbuckle.AspNetCore | 7.* | Swagger/OpenAPI |
| Serilog.AspNetCore | 9.* | Structured logging |
| Serilog.Sinks.Console | 6.* | Console output |
---
## Controller Conventions
| Aspect | Convention |
|--------|------------|
| Route | `api/[controller]` |
| Base class | `ControllerBase` |
| Attributes | `[ApiController]`, `[Route]` |
| DI | Constructor injection |
| Response types | `[ProducesResponseType]` attributes |
| Async | All actions async |
---
## Entity Conventions
| Aspect | Convention |
|--------|------------|
| Base class | Inherit from `BaseEntity` or `AuditableEntity` |
| Primary key | `Guid Id` in base class |
| Required strings | `required` keyword |
| Collections | Initialize with `new List<T>()` |
| Timestamps | `CreatedAt`, `UpdatedAt` in AuditableEntity |
---
**Version:** 2.0.0
**Last Updated:** 2026-01-10
references/frontend_structure.md
# Frontend Structure Template
<!-- SCOPE: React frontend folder structure ONLY. Contains components/hooks/services directories, naming conventions. -->
<!-- DO NOT add here: Migration workflow → ln-720-structure-migrator SKILL.md -->
Reference structure for React frontend projects.
---
## Directory Structure
```
src/frontend/
├── src/
│ ├── components/
│ │ ├── ui/ # Reusable UI components
│ │ │ ├── Button/
│ │ │ ├── Input/
│ │ │ ├── Modal/
│ │ │ └── index.ts # Barrel export
│ │ │
│ │ └── layout/ # Layout components
│ │ ├── AppLayout/
│ │ ├── Header/
│ │ ├── Sidebar/
│ │ └── index.ts
│ │
│ ├── pages/ # Route pages
│ │ ├── Dashboard/
│ │ │ ├── index.tsx
│ │ │ ├── types.ts
│ │ │ ├── constants.ts
│ │ │ ├── hooks.ts
│ │ │ └── components/
│ │ ├── Settings/
│ │ └── Profile/
│ │
│ ├── hooks/ # Shared custom hooks
│ │ ├── useAuth.ts
│ │ ├── useApi.ts
│ │ └── index.ts
│ │
│ ├── contexts/ # React contexts
│ │ ├── AuthContext.tsx
│ │ ├── ThemeContext.tsx
│ │ └── index.ts
│ │
│ ├── lib/ # Utilities
│ │ ├── api/
│ │ │ ├── client.ts
│ │ │ └── endpoints/
│ │ ├── utils/
│ │ └── constants.ts
│ │
│ ├── types/ # Shared TypeScript types
│ │ └── index.ts
│ │
│ ├── App.tsx
│ ├── main.tsx
│ └── index.css
│
├── public/
├── package.json
├── tsconfig.json
└── vite.config.ts
```
---
## Folder Responsibilities
| Folder | Purpose | Contents |
|--------|---------|----------|
| `components/ui/` | Reusable UI primitives | Button, Input, Modal, Select, etc. |
| `components/layout/` | App structure | AppLayout, Header, Sidebar, Footer |
| `pages/` | Route-level components | Feature folders with co-located files |
| `pages/{Feature}/` | Feature code | index.tsx, types.ts, constants.ts, hooks.ts |
| `hooks/` | Shared hooks | Cross-feature reusable hooks |
| `contexts/` | State providers | React Context providers |
| `lib/` | Utilities | API client, formatters, helpers |
| `types/` | Shared types | Cross-feature type definitions |
---
## Component Organization
| Component Type | Location | Example |
|----------------|----------|---------|
| UI Primitive | `components/ui/` | Button, Input, Modal |
| Layout | `components/layout/` | AppLayout, Header |
| Feature-specific | `pages/{Feature}/components/` | DashboardCard |
| Page | `pages/{Feature}/index.tsx` | Dashboard, Settings |
---
## Feature Folder Structure
| File | Purpose | When to Create |
|------|---------|----------------|
| `index.tsx` | Main component | Always |
| `types.ts` | Feature types | If >3 type definitions |
| `constants.ts` | Feature constants | If magic values present |
| `hooks.ts` | Feature hooks | If custom hooks needed |
| `components/` | Sub-components | If >2 sub-components |
| `utils.ts` | Feature utilities | If helper functions needed |
---
## Path Aliases
| Alias | Path | Usage |
|-------|------|-------|
| `@/` | `src/` | All imports |
| `@/components` | `src/components/` | Component imports |
| `@/hooks` | `src/hooks/` | Hook imports |
| `@/lib` | `src/lib/` | Utility imports |
| `@/types` | `src/types/` | Type imports |
---
## Import Conventions
| Scenario | Pattern |
|----------|---------|
| Shared UI component | `import { Button } from '@/components/ui'` |
| Layout component | `import { AppLayout } from '@/components/layout'` |
| Shared hook | `import { useAuth } from '@/hooks'` |
| Feature-local | `import { useData } from './hooks'` (relative) |
| Types | `import type { User } from '@/types'` |
---
## File Naming
| Type | Convention | Example |
|------|------------|---------|
| Component | PascalCase.tsx | `Button.tsx` |
| Hook | camelCase.ts | `useAuth.ts` |
| Types | types.ts | `types.ts` |
| Constants | constants.ts | `constants.ts` |
| Utilities | camelCase.ts | `format.ts` |
| Barrel export | index.ts | `index.ts` |
---
## Entry Points
| File | Purpose |
|------|---------|
| `main.tsx` | App bootstrap, ReactDOM.render |
| `App.tsx` | Root component, routing |
| `index.css` | Global styles |
---
## Config Files
| File | Purpose |
|------|---------|
| `package.json` | Dependencies, scripts |
| `tsconfig.json` | TypeScript config, path aliases |
| `vite.config.ts` | Build config, path aliases mirror |
---
**Version:** 2.0.0
**Last Updated:** 2026-01-10
references/meta_analysis_protocol.md
<!-- SOURCE-OF-TRUTH: shared/references/meta_analysis_protocol.md. Edit ONLY here; run `node tools/marketplace/shared.mjs sync` -->
# Meta-Analysis Protocol
Optional post-run self-audit for skills that need protocol-formatted reflection. Do not load this file by default; load it only when the user asks for meta-analysis, when a command explicitly requires a run retrospective, or when debugging repeated skill failures.
## Use When Requested
Produce only actionable findings from the current run:
- deliverable gaps against the user's goal
- failed, wasted, or repeated tool/agent steps
- worker or subagent failures that changed the result
- concrete skill or command improvements tied to observed evidence
Skip generic SDLC commentary. If there are no findings, write: `Meta-analysis: clean run.`
## Output
```markdown
### Meta-Analysis: {Skill Name}
#### Improvements
| # | Finding | Target | Fix |
|---|---------|--------|-----|
| 1 | {observed issue} | {skill/phase/file} | {specific change} |
#### Session Errors
| Problem Type | Count | Examples |
|--------------|-------|----------|
| {type} | {N} | {brief examples} |
```
Omit empty sections. For subagents, add a separate `#### Subagent Errors: {Agent Name}` table only when that agent had material failures.
## Issue Suggestion Trigger
If the same failure pattern is reproducible across multiple runs, suggest creating an issue with the affected skill, evidence, and expected fix.
---
**Version:** 4.2.0
**Last Updated:** 2026-03-21
SKILL.md
---
name: ln-720-structure-migrator
description: "Scaffolds new or restructures existing projects to Clean Architecture. Use when setting up project structure."
license: MIT
---
> **Paths:** File paths (`references/`, `../ln-*`) are relative to this skill directory.
# ln-720-structure-migrator
**Type:** L2 Domain Coordinator
**Category:** 7XX Project Bootstrap
**Parent:** ln-700-project-bootstrap
Coordinates project restructuring to Clean Architecture. Mode-aware: delegates to workers with appropriate mode parameters based on CREATE/TRANSFORM pipeline.
---
## Purpose & Scope
| Aspect | Description |
|--------|-------------|
| **Input** | Current project structure + mode (CREATE/TRANSFORM) from ln-700 |
| **Output** | Restructured project with Clean Architecture |
| **Workers** | See Workers table below |
### Workers
| Worker | Role | CREATE mode | TRANSFORM mode |
|--------|------|-------------|----------------|
| ln-721 | Frontend structure | SCAFFOLD (generate starter) | RESTRUCTURE (migrate monolith) |
| ln-722 | Backend generator | RUN (generate backend) | RUN (generate backend) |
| ln-723 | Seed data | GENERATE (from entities) | MIGRATE (from ORM schemas) |
| ln-724 | Artifact cleaner | **SKIP** (no artifacts) | **CONDITIONAL** (only if platform detected) |
**Scope boundaries:**
- Analyzes current project structure (TRANSFORM) or accepts target config (CREATE)
- Generates migration plan or scaffold plan
- Delegates to specialized workers via Agent tool
- Verifies final result
---
## Workflow
| Phase | Name | CREATE mode | TRANSFORM mode |
|-------|------|-------------|----------------|
| 1 | Analyze | Receive target stack config | Scan structure, detect framework, map files |
| 2 | Plan | Calculate scaffold actions | Calculate moves, identify conflicts |
| 3 | Execute | Delegate: ln-721 SCAFFOLD → ln-722 → ln-723 GENERATE | Delegate: ln-724 (conditional) → ln-721 RESTRUCTURE → ln-722 → ln-723 MIGRATE |
| 4 | Verify | Check file structure, validate configs | Run builds, check imports, validate structure |
---
## Target Structures
### Frontend (React)
```
src/frontend/
├── public/
├── src/
│ ├── components/
│ │ ├── layout/ # AppLayout, Header, Sidebar
│ │ └── ui/ # Reusable UI components
│ ├── contexts/ # React contexts
│ ├── hooks/ # Custom hooks
│ ├── lib/ # Utilities, API clients
│ ├── pages/ # Page components
│ │ └── {Feature}/ # Feature-specific files
│ ├── App.tsx
│ ├── main.tsx
│ └── index.css
├── package.json
├── vite.config.ts
└── tsconfig.json
```
### Backend (.NET Clean Architecture)
```
src/
├── {Project}.Api/
│ ├── Controllers/
│ ├── DTOs/
│ ├── Middleware/
│ ├── MockData/
│ ├── Extensions/
│ ├── Program.cs
│ └── appsettings.json
├── {Project}.Domain/
│ ├── Entities/
│ ├── Enums/
│ └── Common/
├── {Project}.Services/
│ └── Interfaces/
├── {Project}.Repositories/
│ └── Interfaces/
└── {Project}.Shared/
```
---
## Delegation Protocol
### To ln-724 (Artifact Cleaner)
**When to invoke:** TRANSFORM mode AND platform artifacts detected (`.replit`, `.stackblitzrc`, `sandbox.config.json`, `glitch.json`).
**Skip conditions:** CREATE mode OR no platform config files found.
```yaml
Context:
projectPath: /project
skipPreview: false
Options:
# ln-724 auto-detects platform, no need to specify
cleanConfigFiles: true
cleanDirectories: true
cleanPackages: true
cleanBuildConfig: true
cleanCodeComments: true
cleanGitignore: true
```
### To ln-721 (Frontend)
```yaml
Context:
mode: SCAFFOLD | RESTRUCTURE # From pipeline mode
# SCAFFOLD mode:
targetPath: /project/src/frontend
projectName: MyApp
# RESTRUCTURE mode:
sourcePath: /project/client
targetPath: /project/src/frontend
framework: react
features:
- Dashboard
- Settings
- Profile
Options:
# RESTRUCTURE only:
splitMonolithicFiles: true
extractConstants: true
extractTypes: true
createComponentLibrary: true
```
### To ln-722 (Backend)
```yaml
Context:
projectName: MyApp
targetPath: /project/src
targetFramework: net10.0
features:
- Dashboard
- Users
Options:
createMockData: true
addSwagger: true
addHealthChecks: true
```
### To ln-723 (Seed Data)
```yaml
Context:
mode: MIGRATE | GENERATE # From pipeline mode
targetFormat: csharp | typescript | python | json | sql
# MIGRATE mode:
sourceORM: auto # Auto-detect (drizzle/prisma/typeorm/efcore/sqlalchemy/django)
sourcePath: /project/references/schema.ts
# GENERATE mode:
entities: # Optional — if empty, starter template used
- name: User
fields: [id, name, email, role, createdAt]
- name: Role
fields: [id, name, description]
targetPath: /project/src/MyApp.Api/MockData
```
---
## Critical Rules
- **Orchestrator Pattern:** Analyze and delegate via Skill tool, do not execute transformations directly
- **Mode Awareness:** Pass correct mode to all workers — CREATE vs TRANSFORM determines worker behavior
- **Conditional Workers:** ln-724 runs ONLY in TRANSFORM mode when platform artifacts detected; SKIP otherwise
- **Sequential Workers:** Execute in order (ln-724 conditional → ln-721 → ln-722 → ln-723)
- **Pre-flight Checks:** Verify git status clean, target paths available
- **No Data Loss:** Copy before delete, verify before removing source (TRANSFORM mode)
- **Build Verification:** All builds must pass (`npm run build`, `dotnet build`)
- **Rollback Ready:** Keep backup branch until verification complete (TRANSFORM mode)
**Invocations:**
```
Skill(skill: "ln-724-artifact-cleaner", args: "{projectPath}") # TRANSFORM only, conditional
Skill(skill: "ln-721-frontend-restructure", args: "{projectPath} --mode {SCAFFOLD|RESTRUCTURE}")
Skill(skill: "ln-722-backend-generator", args: "{projectPath}")
Skill(skill: "ln-723-seed-data-generator", args: "{projectPath} --mode {GENERATE|MIGRATE}")
```
---
**TodoWrite format (mandatory):**
```
- Invoke ln-724-artifact-cleaner (conditional TRANSFORM) (pending)
- Invoke ln-721-frontend-restructure (pending)
- Invoke ln-722-backend-generator (pending)
- Invoke ln-723-seed-data-generator (pending)
- Verify structure and builds (pending)
```
## Worker Invocation (MANDATORY)
**Host Skill Invocation:** `Skill(skill: "...", args: "...")` is mandatory delegation.
- Claude: call the Skill tool exactly as shown.
- Codex: if no Skill tool exists, locate the named skill in available skills, read its `SKILL.md`, treat `args` as `$ARGUMENTS`, execute that skill workflow, then return here with its result/artifact.
- Do not inline worker logic or mark the worker complete without executing the target skill.
| Phase | Worker | Context |
|-------|--------|---------|
| 3a | ln-724-artifact-cleaner | Shared (Skill tool) — remove platform artifacts (TRANSFORM only, conditional) |
| 3b | ln-721-frontend-restructure | Shared (Skill tool) — scaffold or restructure frontend |
| 3c | ln-722-backend-generator | Shared (Skill tool) — generate backend project structure |
| 3d | ln-723-seed-data-generator | Shared (Skill tool) — generate or migrate seed data |
**All workers:** Invoke via Skill tool — workers see coordinator context.
## Definition of Done
**CREATE mode:**
- [ ] Target stack config received from ln-700
- [ ] ln-721 completed: Frontend scaffolded (SCAFFOLD mode)
- [ ] ln-722 completed: Backend generated
- [ ] ln-723 completed: Seed data generated (GENERATE mode)
- [ ] File structure matches target templates
- [ ] All configs valid (package.json, tsconfig.json, .csproj)
**TRANSFORM mode:**
- [ ] Current structure analyzed and documented
- [ ] Migration plan generated
- [ ] ln-724 completed: Platform artifacts removed (if applicable)
- [ ] ln-721 completed: Frontend restructured (RESTRUCTURE mode)
- [ ] ln-722 completed: Backend generated
- [ ] ln-723 completed: Seed data migrated (MIGRATE mode)
- [ ] Frontend builds successfully (`npm run build`)
- [ ] Backend builds successfully (`dotnet build`)
- [ ] No orphan files in old locations
- [ ] All imports resolve correctly
- [ ] Migration report generated
---
## Risk Mitigation
| Risk | Detection | Mitigation |
|------|-----------|------------|
| Uncommitted changes | `git status` not clean | Require clean working directory |
| Build failure (frontend) | `npm run build` fails | Rollback, delegate to ln-721 for fix |
| Build failure (backend) | `dotnet build` fails | Rollback, delegate to ln-722 for fix |
| Lost files | Files missing after migration | Restore from backup branch |
| Import errors | Module not found | Re-run import update phase |
| Partial migration | Worker fails mid-execution | Atomic: complete all or rollback all |
| Wrong worker mode | Mode mismatch | Validate mode parameter before delegation |
---
## Reference Files
| File | Purpose |
|------|---------|
| `references/clean_architecture_dotnet.md` | .NET project structure template |
| `references/frontend_structure.md` | React project structure template |
---
## Meta-Analysis
Optional reference: load `references/meta_analysis_protocol.md` only when the user asks for post-run meta-analysis or protocol-formatted run reflection.
Skill type: `execution-orchestrator`. When requested, run after all phases complete. Output to chat using the `execution-orchestrator` format.
---
**Version:** 3.0.0
**Last Updated:** 2026-02-07