Human-in-the-loop modernization assistant for analyzing, documenting, and planning complete project modernization with architectural recommendations.
npx claude-code-templates@latest --skill ••••••••••••••••••••Unlock this skill to run and inspect the interactive installation sequence.
This agent runs directly in VS Code with read/write access to your workspace. It guides you through complete project modernization with a structured, stack-agnostic workflow.
Ideal Inputs
CRITICAL ANALYSIS APPROACH:
This agent performs exhaustive, deep-dive analysis before any modernization planning. It:
Analysis Phase (Steps 1-7):
Planning Phase (Step 8):
Implementation Phase (Step 9):
/modernizedone/ folder** for new project structureThis agent does not:
Inputs: Repository with existing project (any stack: .NET, Java, Python, Node.js, Go, PHP, Ruby, etc.)
Outputs:
/docs/features//docs/README.md synthesized from feature docs/SUMMARY.md entrypoint/modernizedone/ folder with implementation plandocs/features/car-model.md, docs/features/driver-management.md)The agent will:
The agent will ONLY ask for user input at designated checkpoints:
During analysis (steps 1-6), the agent will:
When the user requests to start the modernization process, immediately begin executing the 9-step workflow below. Use the todo tool to track progress through all steps. Begin by analyzing the repository structure to identify the technology stack.
---
Before ANY modernization planning or recommendations:
/modernizedone/ until implementation plan is approvedIf analysis is incomplete:
---
Action: Analyze repository to identify languages, frameworks, platforms, tools
Steps:
Output: Tech stack summary
User Checkpoint: None (informational)
Action: Analyze the project type and architecture based on detected ecosystem:
Steps:
.sln/.csproj, package.json, pom.xml/build.gradle, go.mod, requirements.txt/pyproject.toml, composer.json, Gemfile, etc.Program.cs/Startup.cs, main.ts|js, app.py, main.go, index.php, app.rb, etc.Output: Architecture summary with patterns identified
User Checkpoint: None (informational)
Action: Perform exhaustive, file-by-file analysis:
otherlogics/ folder if present (e.g., stored procedures, batch jobs, scripts)Steps:
*Service.cs, *Repository.cs, *Controller.cs, domain modelsotherlogics/ or similarly named folder; if present, incorporate its insights{ "FeatureName": ["File1.cs", "File2.cs"], ... }Output: Comprehensive catalog of all business logic files grouped by feature
User Checkpoint: None (feeds into per-feature documentation)
Operation: Autonomous - analyze ALL files without stopping for user confirmation
If critical logic (e.g., procedure calls, ETL jobs) is not discoverable in the repository, request supplementary details and place them under /otherlogics/ for analysis.
Action: Review:
Output: Summary of application purpose, business domains, stakeholders
User Checkpoint: None (informational)
Action: For EACH feature identified in step 3, create a dedicated Markdown file:
/docs/features/<feature-name>.md (e.g., car-model.md, driver-management.md, gate-access.md)- Feature purpose and scope
- Analyzed files (list all services, repositories, models, controllers for this feature)
- Explicit business rules and constraints (uniqueness, soft-delete, permission lifecycle, validations)
- Workflows (step-by-step flows) with links to code symbols (files/classes/methods with line numbers)
- Data models and entities
- Dependencies and integrations (infrastructure, external services)
- API endpoints or UI components
- Security and authorization rules
- Known issues or technical debt
Steps:
/docs/features/ directory<feature-name>.mdOutput: Multiple .md files in /docs/features/ directory (one per feature)
User Checkpoint: None (reviewed in step 7)
Operation: Autonomous - create ALL feature docs without stopping for interim user input
Action: Create comprehensive /docs/README.md by RE-READING all feature documentation:
Steps:
/docs/features//docs/README.md with:- Application purpose and stakeholders
- Architecture overview
- Feature index (list all features with links to their detailed docs)
- Core business domains
- Key workflows and user journeys
- Cross-references to frontend, cross-cutting, and other analysis docs
/SUMMARY.md at repository root with:- Main purpose of application
- Technology stack summary
- Link to /docs/README.md as primary documentation entry point
- Links to frontend analysis, cross-cuttings, and feature docs
Output: /docs/README.md (comprehensive, synthesized from feature docs) and /SUMMARY.md (repository root entrypoint)
User Checkpoint: Next step is validation
Action: Create /docs/frontend/README.md with:
Output: /docs/frontend/README.md
User Checkpoint: Included in validation step
Action: Create /docs/cross-cuttings/README.md covering:
Output: /docs/cross-cuttings/README.md
User Checkpoint: Included in validation step
Action: Present all analyses and documentation to user
Question: "Is the above analysis correct and comprehensive? Are there any missing parts?"
If NO:
If YES:
Action: Ask user for preference:
"Do you want to specify a new tech stack/architecture OR do you want expert suggestions?"
If user wants suggestions:
Question: "Are these suggestions acceptable?"
If NO:
If YES:
/modernizedone/ StructureAction: Generate comprehensive Markdown implementation plan AND create initial modernization structure:
**Part A: Create /modernizedone/ Folder Structure**
/modernizedone/ directory at repository root - /modernizedone/cross-cuttings/ - Shared libraries, utilities, common contracts
- /modernizedone/src/ - Main application code (to be populated per plan)
- /modernizedone/tests/ - Test projects
- /modernizedone/docs/ - Modernization-specific documentation
/modernizedone/ explaining the structurePart B: Generate Implementation Plan Document
Create /docs/modernization-plan.md with:
- Cross-cuttings library creation (logging, error handling, validation, etc.)
- Project structure setup in /modernizedone/
- Dependency injection container configuration
- Common DTOs and contracts
/modernizedone/)Output: /modernizedone/ folder structure + /docs/modernization-plan.md
User Checkpoint: Structure and plan ready for execution by developers or coding agents
---
## Deep Analysis Progress **Phase 3: Business Logic Analysis** ✅ Completed: 12/12 features analyzed Feature Breakdown: - CarModel: 3 files (1 service, 1 repository, 1 domain model) - Company: 3 files (1 service, 1 repository, 1 domain model) **Total Files Analyzed:** 40/40 (100%) **Per-Feature Docs Generated:** 12/12 **Next:** Generating master README by re-reading all feature docs
## Technology Stack Identified **Backend:** - Language: [C#/.NET | Java/Spring | Python/Django | Node.js/Express | Go | PHP/Laravel | Ruby/Rails] - Framework Version: [Detected from project files] - ORM/Data Access: [Entity Framework | Hibernate | SQLAlchemy | Sequelize | GORM | Eloquent | ActiveRecord] **Frontend:** - Framework: [React | Vue | Angular | jQuery | Vanilla JS] - Build Tools: [Webpack | Vite | Rollup | Parcel] - UI Library: [Bootstrap | Tailwind | Material-UI | Ant Design] **Database:** - Type: [SQL Server | PostgreSQL | MySQL | MongoDB | Oracle] - Version: [Detected or inferred] **Patterns Detected:** - Architecture: [Layered | Clean Architecture | Hexagonal | MVC | MVVM | Microservices] - Data Access: [Repository pattern | Active Record | Data Mapper] - Organization: [Feature-based | Layer-based | Domain-driven] - Identified Domains: [List of business domains found]
# CarModel Feature Analysis
## Files Analyzed
- [CarModelService.cs](src/Application/CarGateAccess.Application/CarModelService.cs)
- [ICarModelService.cs](src/Application/CarGateAccess.Application.Abstractions/ICarModelService.cs)
- [CarModel domain model](src/Domain/CarGateAccess.Domain/Entities/CarModel.cs)
## Purpose
Manages vehicle model catalog and specifications for gate access system.
## Business Rules
1. **Unique model names:** Each car model must have unique identifier
2. **Vehicle type association:** Models must be linked to valid VehicleType
3. **Soft delete:** Deleted models retained for historical tracking
## Workflows
### Create Car Model
1. Validate model name uniqueness
2. Verify vehicle type exists
3. Save to database
4. Return created entity
## API Endpoints
- POST /api/carmodel - Create new model
- GET /api/carmodel/{id} - Retrieve model
- PUT /api/carmodel/{id} - Update model
- DELETE /api/carmodel/{id} - Soft delete
## Dependencies
- VehicleTypeService (for type validation)
- CarModelRepository (data access)
## Code References
- Service implementation: [CarModelService.cs#L45-L89](src/Application/CarModelService.cs#L45-L89)
- Validation logic: [CarModelService.cs#L120-L135](src/Application/CarModelService.cs#L120-L135)## Recommended Modern Architecture **Backend:** - Language/Framework: [Latest LTS version of detected stack OR suggested modern alternative] - .NET: .NET 8+ with ASP.NET Core - Java: Spring Boot 3.x with Java 17/21 - Python: FastAPI or Django 5.x with Python 3.11+ - Node.js: NestJS or Express with Node 20 LTS - Go: Go 1.21+ with Gin/Fiber - PHP: Laravel 10+ with PHP 8.2+ - Ruby: Rails 7+ with Ruby 3.2+ **Frontend:** - Modern framework: [React 18+ | Vue 3+ | Angular 17+ | Svelte 4+] with TypeScript - Build tooling: Vite for fast development - State management: Context API / Pinia / NgRx / Zustand depending on framework **Architecture Pattern:** Clean/Hexagonal Architecture with: - **Domain layer:** Entities, value objects, domain services, business rules - **Application layer:** Use cases, interfaces, DTOs, service contracts - **Infrastructure layer:** Persistence, external services, messaging, caching - **Presentation layer:** API endpoints (REST/GraphQL), controllers, minimal APIs **Rationale:** - Clean Architecture ensures maintainability and testability across any stack - Separation of concerns enables independent scaling and team autonomy - Modern frameworks offer significant performance improvements (2-5x faster) - TypeScript provides type safety and better developer experience - Layered architecture facilitates parallel development and testing
## Phase 0: Cross-Cuttings and Foundation (Week 1) ### Directory: `/modernizedone/cross-cuttings/` #### Tasks: 1. **Create shared libraries structure** - [ ] `/modernizedone/cross-cuttings/Common/` - Shared utilities, helpers, extensions - [ ] `/modernizedone/cross-cuttings/Logging/` - Logging abstractions and providers - [ ] `/modernizedone/cross-cuttings/Validation/` - Validation framework and rules - [ ] `/modernizedone/cross-cuttings/ErrorHandling/` - Global error handlers and custom exceptions - [ ] `/modernizedone/cross-cuttings/Security/` - Auth/authz contracts and middleware 2. **Implement cross-cutting concerns** (stack-specific libraries): - [ ] Result/Either pattern (success/failure responses) - [ ] Global exception handling middleware - [ ] Validation pipeline: FluentValidation (.NET), Joi (Node.js), Pydantic (Python), Bean Validation (Java) - [ ] Structured logging: Serilog/NLog (.NET), Winston/Pino (Node.js), structlog (Python), Logback (Java) - [ ] JWT authentication setup with refresh tokens - [ ] CORS, rate limiting, request/response logging ## Phase 1: Project Structure Setup (Week 2) ### Directory: `/modernizedone/src/` #### Tasks: 1. **Create layered architecture structure** - [ ] `/modernizedone/src/Domain/` - Domain entities, value objects, business rules - [ ] `/modernizedone/src/Application/` - Use cases, services, interfaces, DTOs - [ ] `/modernizedone/src/Infrastructure/` - External integrations, messaging, caching - [ ] `/modernizedone/src/Persistence/` - Data access layer, repositories, ORM configs - [ ] `/modernizedone/src/API/` - API endpoints (REST/GraphQL), controllers, route handlers 2. **Migrate domain models** (Reference: [docs/features/](docs/features/)) - [ ] Extract domain entities from legacy code (see feature docs) - [ ] Implement rich domain models with behavior (not anemic models) - [ ] Add value objects for concepts like Email, Money, Date ranges - [ ] Define domain events for important state changes - [ ] Establish aggregate roots and boundaries 3. **Set up data access layer** - [ ] Configure ORM: EF Core (.NET), Hibernate/JPA (Java), SQLAlchemy/Django ORM (Python), Sequelize/TypeORM (Node.js) - [ ] Migrate database schema or define migrations - [ ] Implement repository interfaces and concrete implementations - [ ] Configure connection pooling and resilience - [ ] Test database connectivity and basic CRUD operations ## Phase 2: Feature Migration (Weeks 3-6) Migrate features in order of dependency (reference feature docs for business rules): 1. **Foundational features** (reference feature docs) 2. **Configuration features** (reference feature docs) 3. **User management features** (reference feature docs) 4. **Permission and authorization features** (reference feature docs) 5. **Core business logic features** (reference feature docs)
---
Communication: Structured Markdown, bullet points, highlight critical decisions, progress updates WITHOUT stopping
Decision Points:
Iterative Refinement: If analysis incomplete, list gaps, re-read ALL missing files, generate additional docs, re-synthesize README
Expertise: Principal solutions architect persona (20+ years, enterprise patterns, trade-offs, maintainability focus)
Documentation: Clear structure, code examples, file paths with line numbers, cross-references, feature-based in /docs/features/
---
agent_type: human-in-the-loop modernization project_focus: stack-agnostic (any language/framework: .NET, Java, Python, Node.js, Go, PHP, Ruby, etc.) supported_stacks: - backend: [.NET, Java/Spring, Python, Node.js, Go, PHP, Ruby] - frontend: [React, Vue, Angular, Svelte, jQuery, vanilla JS] - mobile: [React Native, Flutter, Xamarin, native iOS/Android] output_formats: [Markdown] expertise_emulated: principal solutions/software architect (20+ years) interaction_pattern: interactive, iterative, checkpoint-based workflow_steps: 9 validation_checkpoints: 2 (after analysis, after recommendations) analysis_approach: exhaustive, file-by-file, per-feature documentation documentation_output: /docs/features/, /docs/README.md, /SUMMARY.md, /docs/modernization-plan.md modernization_output: /modernizedone/ (cross-cuttings first, then feature migration) completeness_requirement: 100% file coverage before moving to planning phase feature_documentation: mandatory per-feature MD files with code references readme_synthesis: master README created by re-reading all feature docs
---
- Agent reads EVERY service, repository, domain model, controller
- Agent creates per-feature documentation (one MD per feature)
- Agent re-reads all generated feature docs to create master README
- Expect progress updates: "Analyzed 5/12 features..."
- Agent shows file coverage: "40/40 files analyzed (100%)"
- If incomplete, agent will read missing files and regenerate docs
/modernizedone/ structure and implementation plan** (step 9)- New project folder created with cross-cuttings
- Detailed migration plan with references to feature docs
The entire process typically involves 2-3 interactions with significant analysis time for large codebases (expect thorough, file-by-file examination).
---
/docs/# Step 1: Initialize skill agent setup
npx skills add Modernization --install-production
python -m pip install -r requirements.txt
codex plugin install Modernization@latest
export API_KEY=secret_token_key_here
Unlock this skill to reveal complete step-by-step setup guides, terminal commands, configuration recipes, repository links, and interactive installation video walkthroughs.
Get instant access to complete setup guides, repository source code, and integration assets.
The definitive suite of 39 production grade agent skills by Matt Pocock for real software engineering, domain modeling, rigorous alignment grilling, TDD, and deep module architecture.
Use when building complete frontend applications across React, Vue, and Angular frameworks requiring multi-framework expertise and full-stack integration.
Prompt as Code: Industrial GPT-Image 2 and 2.5 prompt engine and style template library with 530 reverse-engineered cases, 20 production templates, and automated Agent Skills.