ln-721-frontend-restructure
npx machina-cli add skill levnikolaevich/claude-code-skills/ln-721-frontend-restructure --openclawFiles (1)
SKILL.md
8.0 KB
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:
- All 7 starter files generated
- package.json and tsconfig.json valid
- No hardcoded project names (uses config values)
RESTRUCTURE mode:
- All source files analyzed and classified
- Migration plan generated with Before/After mapping
- Directory structure created per template
- All extractions completed (types, constants, hooks, components)
- Import paths updated throughout project
-
npm run buildpasses successfully - No orphan imports or missing files
- Barrel exports created for shared folders
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
Source
git clone https://github.com/levnikolaevich/claude-code-skills/blob/master/ln-721-frontend-restructure/SKILL.mdView on GitHub Overview
Ln-721 is a frontend structure worker with two modes: SCAFFOLD to bootstrap a minimal React + Vite + TypeScript project, and RESTRUCTURE to convert an existing monolith into a component-based architecture. It relies on inputs from ln-720-structure-migrator and applies reference rules to reorganize code without adding new functionality.
How This Skill Works
In SCAFFOLD mode, it generates starter project files (package.json, vite.config.ts, tsconfig.json, index.html, src/main.tsx, src/App.tsx, src/index.css). In RESTRUCTURE mode, it analyzes TS/TSX sources to inventory components, measures complexity, plans file moves against split thresholds, executes folder restructuring and import updates, and then runs a build to verify the result.
When to Use It
- Bootstrapping a brand-new React + TypeScript + Vite project from a target stack config (SCAFFOLD).
- Transforming an existing monolithic React frontend into a component-based architecture (RESTRUCTURE).
- Validating scaffold readiness by checking file structure and config validity against the target stack.
- Applying transformation rules and generating a migration plan from detailed analysis.
- Verifying the final build and import integrity after restructuring.
Quick Start
- Step 1: Choose mode (SCAFFOLD or RESTRUCTURE) and provide inputs (target stack config from ln-720 or monolithic React source).
- Step 2: If SCAFFOLD, generate starter files for a minimal React + Vite + TypeScript project (package.json, vite.config.ts, tsconfig.json, index.html, src/*).
- Step 3: If RESTRUCTURE, run Analyze, Plan, Execute, and Verify phases to restructure and validate.
Best Practices
- Use SCAFFOLD only for projects with no business logic yet; it creates a minimal starter skeleton.
- Keep tsconfig.json strict and align path aliases with the project root to avoid import issues.
- In RESTRUCTURE, start with an inventory and complexity metrics before planning moves.
- Do not introduce new functionality during RESTRUCTURE; focus on restructuring and refactoring only.
- After changes, run a build and import checks to confirm the project skeleton remains valid.
Example Use Cases
- Bootstrap a minimal React + Vite + TypeScript starter for a new frontend project using a target stack config.
- Migrate a large monolithic React app into a component-based structure without altering behavior.
- Validate a scaffold against the ln-720 target stack configuration before shipping.
- Generate a component inventory and complexity metrics for a mid-size React codebase.
- Apply transformation rules from reference files to reorganize an existing React + TS project.
Frequently Asked Questions
Add this skill to your agents
