Paths: File paths (shared/, references/, ../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.
ln-721-frontend-restructure
Type: L3 Worker
Category: 7XX Project Bootstrap
Parent: ln-720-structure-migrator
Frontend structure worker with two modes: SCAFFOLD (generate minimal React project from template) or RESTRUCTURE (migrate monolith to component-based architecture).
Mode Selection
| Mode |
When |
Input |
Output |
| SCAFFOLD |
CREATE pipeline — no existing frontend |
Target stack config from ln-720 |
Minimal React + Vite project (~7 files) |
| RESTRUCTURE |
TRANSFORM pipeline — existing frontend found |
Monolithic React source |
Component-based architecture |
Purpose & Scope
| Aspect |
Description |
| Input |
Target stack config (SCAFFOLD) or monolithic React source (RESTRUCTURE) |
| Output |
Minimal project (SCAFFOLD) or component-based architecture (RESTRUCTURE) |
| Framework |
React + TypeScript + Vite |
Scope boundaries:
- SCAFFOLD: generates minimal starter files, no business logic
- RESTRUCTURE: restructures existing code, does not add new functionality
- Works with React + TypeScript projects
- Applies transformation rules from reference files
Workflow
SCAFFOLD Mode (CREATE pipeline)
| Phase |
Name |
Actions |
Output |
| S1 |
Generate |
Create minimal React + Vite + TypeScript project files |
~7 starter files |
| S2 |
Verify |
Check file structure, validate configs |
Valid project skeleton |
RESTRUCTURE Mode (TRANSFORM pipeline)
| Phase |
Name |
Actions |
Output |
| 1 |
Analyze |
Scan source, detect component types, measure complexity |
File inventory, complexity metrics |
| 2 |
Plan |
Apply split thresholds, calculate file moves, detect conflicts |
Migration plan |
| 3 |
Execute |
Create folders, extract content, update imports |
Restructured files |
| 4 |
Verify |
Run build, check imports, validate structure |
Build success report |
SCAFFOLD Mode Phases
Phase S1: Generate Starter Files
Create minimal React + Vite + TypeScript project.
| File |
Purpose |
package.json |
Dependencies: react, react-dom, typescript, vite, @vitejs/plugin-react |
vite.config.ts |
Vite config with React plugin, port, proxy settings |
tsconfig.json |
Strict TypeScript config with path aliases |
index.html |
Entry HTML with root div |
src/main.tsx |
React entry point with StrictMode |
src/App.tsx |
Root App component with router placeholder |
src/index.css |
Base styles (reset, variables, layout) |
Phase S2: Verify Scaffold
| Check |
Method |
Expected |
| All files created |
File existence check |
7 files present |
| package.json valid |
JSON parse |
No syntax errors |
| tsconfig.json valid |
JSON parse |
No syntax errors |
| No hardcoded values |
Content scan |
Project name from config, not hardcoded |
RESTRUCTURE Mode Phases
Phase 1: Analyze
Scan current frontend structure and classify components.
| Step |
Action |
Reference |
| 1.1 |
Scan all .tsx and .ts files in source |
— |
| 1.2 |
Measure file complexity (lines, hooks, types) |
transformation_rules.md |
| 1.3 |
Classify components by category |
component_patterns.md |
| 1.4 |
Build import dependency graph |
import_strategy.md |
Output: Component inventory with classifications and metrics.
Phase 2: Plan
Generate migration plan based on analysis.
| Step |
Action |
Reference |
| 2.1 |
Apply split thresholds to identify files to restructure |
transformation_rules.md |
| 2.2 |
Calculate target paths for each file |
react_folder_structure.md |
| 2.3 |
Identify import updates needed |
import_strategy.md |
| 2.4 |
Detect potential conflicts (name collisions, circular deps) |
— |
Output: Migration plan with Before/After mapping.
Phase 3: Execute
Apply transformations in correct order.
| Step |
Action |
Notes |
| 3.1 |
Create directory structure |
All target folders |
| 3.2 |
Extract types to types.ts |
Types have no dependencies |
| 3.3 |
Extract constants to constants.ts |
Constants depend only on types |
| 3.4 |
Extract hooks to hooks.ts |
Hooks depend on types, constants |
| 3.5 |
Extract sub-components |
Components use all above |
| 3.6 |
Create barrel exports (index.ts) |
For clean imports |
| 3.7 |
Update all import paths |
Fix references |
Order is critical: Execute in sequence to avoid broken imports.
Phase 4: Verify
Validate restructured project.
| Check |
Command |
Expected |
| TypeScript compilation |
npx tsc --noEmit |
No errors |
| Build |
npm run build |
Success |
| No orphan files |
Manual check |
Source location empty |
| Imports resolve |
Build success |
No module not found errors |
Transformation Summary
| Transformation |
Before State |
After State |
| Component Split |
Single file >300 lines |
Feature folder with co-located files |
| Type Extraction |
Inline interfaces |
Separate types.ts |
| Constant Extraction |
Inline magic values |
Separate constants.ts |
| Hook Extraction |
Inline useState/useEffect |
Separate hooks.ts or shared hooks |
| UI Component Move |
Scattered in features |
Centralized in components/ui/ |
| Layout Component Move |
Mixed with features |
Centralized in components/layout/ |
Critical Rules
- Mode Awareness: SCAFFOLD creates from template; RESTRUCTURE transforms existing — never mix
- Single Responsibility: Handle only frontend structure, no backend changes
- Idempotent: Can re-run without duplicate files or corruption
- Build Verification: Must verify build passes after changes (RESTRUCTURE:
npm run build)
- Preserve Functionality: No behavioral changes, only structural (RESTRUCTURE mode)
- Backup Strategy: Do not delete source files until verification passes (RESTRUCTURE mode)
- Import Consistency: Use path aliases for shared, relative for co-located
Definition of Done
SCAFFOLD mode:
RESTRUCTURE mode:
Risk Mitigation
| Risk |
Detection |
Mitigation |
| Build failure after restructure |
npm run build fails |
Rollback: restore from source, investigate specific error |
| Missing imports |
Module not found errors |
Scan all imports before/after, update missed paths |
| Circular dependencies |
Build warning or runtime error |
Analyze dependency graph, break cycles by extracting shared code |
| Lost functionality |
Tests fail or UI broken |
Run existing tests before/after transformation |
| Name collisions |
Duplicate export names |
Rename with feature prefix before moving |
Reference Files
| File |
Purpose |
references/transformation_rules.md |
Split thresholds, extraction rules, transformation order |
references/component_patterns.md |
Component classification by category |
references/import_strategy.md |
Import update rules, path aliases, barrel exports |
references/react_folder_structure.md |
Target directory structure template |
Version: 3.0.0
Last Updated: 2026-02-07
1---2name: ln-721-frontend-restructure3description: Frontend structure worker: SCAFFOLD new React project or RESTRUCTURE existing monolith to component-based architecture4license: MIT5---67> **Paths:** File paths (`shared/`, `references/`, `../ln-*`) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.89# ln-721-frontend-restructure1011**Type:** L3 Worker12**Category:** 7XX Project Bootstrap13**Parent:** ln-720-structure-migrator1415Frontend structure worker with two modes: SCAFFOLD (generate minimal React project from template) or RESTRUCTURE (migrate monolith to component-based architecture).1617---1819## Mode Selection2021| Mode | When | Input | Output |22|------|------|-------|--------|23| **SCAFFOLD** | CREATE pipeline — no existing frontend | Target stack config from ln-720 | Minimal React + Vite project (~7 files) |24| **RESTRUCTURE** | TRANSFORM pipeline — existing frontend found | Monolithic React source | Component-based architecture |2526---2728## Purpose & Scope2930| Aspect | Description |31|--------|-------------|32| **Input** | Target stack config (SCAFFOLD) or monolithic React source (RESTRUCTURE) |33| **Output** | Minimal project (SCAFFOLD) or component-based architecture (RESTRUCTURE) |34| **Framework** | React + TypeScript + Vite |3536**Scope boundaries:**37- SCAFFOLD: generates minimal starter files, no business logic38- RESTRUCTURE: restructures existing code, does not add new functionality39- Works with React + TypeScript projects40- Applies transformation rules from reference files4142---4344## Workflow4546### SCAFFOLD Mode (CREATE pipeline)4748| Phase | Name | Actions | Output |49|-------|------|---------|--------|50| S1 | Generate | Create minimal React + Vite + TypeScript project files | ~7 starter files |51| S2 | Verify | Check file structure, validate configs | Valid project skeleton |5253### RESTRUCTURE Mode (TRANSFORM pipeline)5455| Phase | Name | Actions | Output |56|-------|------|---------|--------|57| 1 | Analyze | Scan source, detect component types, measure complexity | File inventory, complexity metrics |58| 2 | Plan | Apply split thresholds, calculate file moves, detect conflicts | Migration plan |59| 3 | Execute | Create folders, extract content, update imports | Restructured files |60| 4 | Verify | Run build, check imports, validate structure | Build success report |6162---6364## SCAFFOLD Mode Phases6566### Phase S1: Generate Starter Files6768Create minimal React + Vite + TypeScript project.6970| File | Purpose |71|------|---------|72| `package.json` | Dependencies: react, react-dom, typescript, vite, @vitejs/plugin-react |73| `vite.config.ts` | Vite config with React plugin, port, proxy settings |74| `tsconfig.json` | Strict TypeScript config with path aliases |75| `index.html` | Entry HTML with root div |76| `src/main.tsx` | React entry point with StrictMode |77| `src/App.tsx` | Root App component with router placeholder |78| `src/index.css` | Base styles (reset, variables, layout) |7980### Phase S2: Verify Scaffold8182| Check | Method | Expected |83|-------|--------|----------|84| All files created | File existence check | 7 files present |85| package.json valid | JSON parse | No syntax errors |86| tsconfig.json valid | JSON parse | No syntax errors |87| No hardcoded values | Content scan | Project name from config, not hardcoded |8889---9091## RESTRUCTURE Mode Phases9293### Phase 1: Analyze9495Scan current frontend structure and classify components.9697| Step | Action | Reference |98|------|--------|-----------|99| 1.1 | Scan all `.tsx` and `.ts` files in source | — |100| 1.2 | Measure file complexity (lines, hooks, types) | `transformation_rules.md` |101| 1.3 | Classify components by category | `component_patterns.md` |102| 1.4 | Build import dependency graph | `import_strategy.md` |103104**Output:** Component inventory with classifications and metrics.105106---107108### Phase 2: Plan109110Generate migration plan based on analysis.111112| Step | Action | Reference |113|------|--------|-----------|114| 2.1 | Apply split thresholds to identify files to restructure | `transformation_rules.md` |115| 2.2 | Calculate target paths for each file | `react_folder_structure.md` |116| 2.3 | Identify import updates needed | `import_strategy.md` |117| 2.4 | Detect potential conflicts (name collisions, circular deps) | — |118119**Output:** Migration plan with Before/After mapping.120121---122123### Phase 3: Execute124125Apply transformations in correct order.126127| Step | Action | Notes |128|------|--------|-------|129| 3.1 | Create directory structure | All target folders |130| 3.2 | Extract types to `types.ts` | Types have no dependencies |131| 3.3 | Extract constants to `constants.ts` | Constants depend only on types |132| 3.4 | Extract hooks to `hooks.ts` | Hooks depend on types, constants |133| 3.5 | Extract sub-components | Components use all above |134| 3.6 | Create barrel exports (`index.ts`) | For clean imports |135| 3.7 | Update all import paths | Fix references |136137**Order is critical:** Execute in sequence to avoid broken imports.138139---140141### Phase 4: Verify142143Validate restructured project.144145| Check | Command | Expected |146|-------|---------|----------|147| TypeScript compilation | `npx tsc --noEmit` | No errors |148| Build | `npm run build` | Success |149| No orphan files | Manual check | Source location empty |150| Imports resolve | Build success | No module not found errors |151152---153154## Transformation Summary155156| Transformation | Before State | After State |157|----------------|--------------|-------------|158| Component Split | Single file >300 lines | Feature folder with co-located files |159| Type Extraction | Inline interfaces | Separate `types.ts` |160| Constant Extraction | Inline magic values | Separate `constants.ts` |161| Hook Extraction | Inline useState/useEffect | Separate `hooks.ts` or shared hooks |162| UI Component Move | Scattered in features | Centralized in `components/ui/` |163| Layout Component Move | Mixed with features | Centralized in `components/layout/` |164165---166167## Critical Rules168169- **Mode Awareness:** SCAFFOLD creates from template; RESTRUCTURE transforms existing — never mix170- **Single Responsibility:** Handle only frontend structure, no backend changes171- **Idempotent:** Can re-run without duplicate files or corruption172- **Build Verification:** Must verify build passes after changes (RESTRUCTURE: `npm run build`)173- **Preserve Functionality:** No behavioral changes, only structural (RESTRUCTURE mode)174- **Backup Strategy:** Do not delete source files until verification passes (RESTRUCTURE mode)175- **Import Consistency:** Use path aliases for shared, relative for co-located176177---178179## Definition of Done180181**SCAFFOLD mode:**182- [ ] All 7 starter files generated183- [ ] package.json and tsconfig.json valid184- [ ] No hardcoded project names (uses config values)185186**RESTRUCTURE mode:**187- [ ] All source files analyzed and classified188- [ ] Migration plan generated with Before/After mapping189- [ ] Directory structure created per template190- [ ] All extractions completed (types, constants, hooks, components)191- [ ] Import paths updated throughout project192- [ ] `npm run build` passes successfully193- [ ] No orphan imports or missing files194- [ ] Barrel exports created for shared folders195196---197198## Risk Mitigation199200| Risk | Detection | Mitigation |201|------|-----------|------------|202| Build failure after restructure | `npm run build` fails | Rollback: restore from source, investigate specific error |203| Missing imports | Module not found errors | Scan all imports before/after, update missed paths |204| Circular dependencies | Build warning or runtime error | Analyze dependency graph, break cycles by extracting shared code |205| Lost functionality | Tests fail or UI broken | Run existing tests before/after transformation |206| Name collisions | Duplicate export names | Rename with feature prefix before moving |207208---209210## Reference Files211212| File | Purpose |213|------|---------|214| `references/transformation_rules.md` | Split thresholds, extraction rules, transformation order |215| `references/component_patterns.md` | Component classification by category |216| `references/import_strategy.md` | Import update rules, path aliases, barrel exports |217| `references/react_folder_structure.md` | Target directory structure template |218219---220221**Version:** 3.0.0222**Last Updated:** 2026-02-07
levalencia