Modernization

Quick Start: Modernization

Getting Started with Modernization

Modernize an existing application by connecting your codebase, understanding its current state, defining your goals, and turning the analysis into an actionable plan for development and delivery.

Note: Modernization requires an existing codebase. You can connect a Git repository or provide your code as a local folder or ZIP file.

---

How it works

The journey has four phases:

The default journey includes: Assessment, Intent, PRD-Spec, Architecture, User Stories, and Testing.

Assessment and Intent are required and cannot be removed. You can also enable UI Design or use the BRD + PRD requirements path when needed.

---

Discover

Step 1: Create your project

1. From the Forge home screen, select Modernize Legacy Code.
2. Enter the project name.
3. Select how you want to provide the existing codebase: Git Repository, Local Folder, or ZIP File.
4. Optionally add database sources if your modernization requires database context.
5. Under Journey Stages, review and customize the stages if needed.
6. Select Start Modernization.

Tip: Start with the default journey if you are new to Forge. You can adjust stages later from project settings.

Step 2: Connect your codebase

Git Repository

1. Select Git Repository.
2. Provide a public repository URL or connect to a private repository through a supported source control connector.

Supported hosts: GitHub, GitLab, Bitbucket, Azure DevOps. Private repositories require the appropriate SCM connector.

Local Folder

1. Select Local Folder.
2. Browse for the application on your computer.

ZIP File

1. Select ZIP File.
2. Upload an archive of the application.

If the ZIP cannot be fully processed, Forge may offer the option to Proceed Without Full Code Analysis.

Add additional sources

Use Add sources at any point in the journey to provide:

• Requirements documents
• Jira or Confluence information
• Figma designs
• Database sources

Tip: The codebase gives Forge the current state. Add requirements or product documents when you also need Forge to understand the desired future state.

Step 3: Let Forge analyze your application

After you provide the codebase, Forge processes it automatically. You will see it progress through:

Uploading sources → Processing your codebase → Indexing files and dependencies → Preparing assessment

When the required context is ready, Forge automatically starts the Assessment. No action is needed from you during this step.

Step 4: Review the Assessment

The Assessment establishes an as-is baseline for your application before you define the modernization plan. Review it to understand what Forge discovered.

The Assessment includes:

Assessment does not require approval. The stage is complete when the artifact is generated.

Step 5: Select a modernization template (Recommended)

On Assessment, expand Modernization Template:

1. Review Suggested for your stack (or open Browse All Templates).
2. Preview a candidate with View Details, then select it.
3. Use Change or Remove if the fit is wrong.

Templates guide migration strategy, phases, and later artifact generation. They are optional but recommended when a built-in or custom pattern matches your stack.

See Templates and Ingest & analysis.

Step 6: Set Generation Preferences (Recommended)

On Assessment, expand Generation Preferences:

1. Confirm a Project Goal (Bug Fix, Enhancement, New Feature, Multi-Feature, Full Build, or Modernization). Use Skip to accept the AI suggestion when shown, or pick another option.
2. Optionally set Preferred number of user stories (1–200). Leave empty to auto-size from the Project Goal.
3. Use Change later if the wave of work shifts.

This calibrates how many user stories Forge generates and how detailed the plan is. Preferences are saved on the journey and apply to later stages. Available on Modernization Assessment only — not on New Build.

See Ingest & analysis → Generation Preferences.

Step 7: Review your ForgeScore

ForgeScore gives you a quantitative view of the application's health alongside the Assessment.

Access it from the Assessment experience, the ForgeScore sidebar tab, or the ForgeScore Dashboard.

ForgeScore evaluates the application across eight dimensions and produces a score from 0 to 100 with a maturity level:

Foundation → Developing → Established → Advanced → Optimized

Use ForgeScore to identify areas that need attention and to help prioritize modernization work.

Note: ForgeScore is informational. It does not determine whether you can continue through the journey.

See ForgeScore.

---

Define

Step 8: Define your modernization intent

Once the Assessment is available, define what you want to achieve with the modernization.

1. Review the Assessment findings.
2. Add additional requirements or UX references using Add sources if needed.
3. Select a Modernization Priority:
   • Modernize First
   • Features First
   • Parallel
4. Select how you want Forge to frame the intent:
   • Generate Modernization Intent
   • Generate Feature Intent
   • Generate Combined Intent
5. Generate the intent artifact.

Note: Once you complete and submit the Intent stage, Forge analyzes your project details and suggests the pipeline stages that best fit your needs. You can review and adjust the recommendations before approving the intent.

1. Review and refine the generated content.
2. Select Approve & Continue when it accurately represents your modernization goals.

Note: Generate and Approve are separate actions. Generate the intent first, review it, then approve.

See Defining Intent and Ingest & analysis.

Step 9: Generate and review requirements

The default requirements path is PRD-Spec.

1. Open PRD-Spec.
2. Complete any preflight questions if prompted.
3. Generate the requirements.
4. Review the current-to-target transition requirements, including parity gaps, data migration, cutover, and rollback considerations.
5. Refine the content as needed.
6. Select Approve & Continue.

Using BRD and PRD instead

If your project uses the alternative requirements path, Forge generates BRD first, then PRD. PRD-Spec and BRD + PRD are mutually exclusive and cannot be enabled together.

See PRD-Spec and Spec generation.

---

Plan

Step 10: Define the target architecture

1. Open Architecture.
2. Review the architecture sections, including the Migration & Transformation Plan.
3. Review the supporting diagrams and technical details.
4. Refine as needed.
5. Select Approve & Continue.

Note: Architecture generates one multi-section artifact. It is not an architecture selection screen. Modernization strategy options shown in Assessment are informational, not selectable options in this stage.

See Modernization plan and Architecture & user stories.

Step 11: Design the UI (Optional)

Enable UI Design when your modernization includes changes to the application's user experience.

1. Open UI Design.
2. Complete the modernization UI preflight.
3. Select the level of UI modernization, from Minimal polish to Complete redesign.
4. Generate the UI design in Forge or import an existing design from Figma.
5. Review and refine the design.
6. Select Approve & Continue.

Figma import requires the Figma connector. If UI Design is not enabled, the journey continues directly from Architecture to User Stories.

See UI Design.

Step 12: Review and approve user stories

Forge converts the approved modernization plan into implementation-ready work.

1. Open User Stories.
2. Review the generated epics and stories.
3. Review current behavior and target behavior where provided.
4. Review implementation steps, dependencies, and modernization phasing.
5. Refine or reprioritize as needed.
6. Select Approve & Continue.

Modernization work is represented through story content, labels, phasing, and current-to-target behavior. Forge can also generate a Requirements Traceability Matrix to connect requirements to the resulting stories.

See Migration user stories & tracking.

Step 13: Generate and review testing artifacts

1. Open Testing.
2. Select the test types you want to generate.
3. Generate the testing artifacts.
4. Review and export when needed.

Testing does not require an approval step. The stage is complete when the artifact is generated. Artifacts can be exported as Markdown, DOCX, PDF, or Excel.

---

Deliver

Step 14: Save the Application Context

1. Select Save Application Context.
2. Review and confirm the save.
3. Select Open Application Context to continue to the delivery workspace.

The first save creates version 1.0.0, a versioned snapshot of your artifacts and stories. After the first save, you can create additional versions as the project evolves.

Note: The Application Context is a delivery snapshot. Your journey artifacts remain editable separately.

See Application Context.

Step 15: Continue development and delivery

From the Application Context workspace, you can:

Manage modernization work

Use Stories to manage and track the generated implementation work in the ALM workspace.

Sync with external tools

Use External Sync to synchronize stories with Jira, Azure DevOps, and other supported tools.

Connect your IDE

Use Connect IDE to connect your development environment through MCP. Use Open in IDE from User Stories to work with individual stories. See MCP Integration.

Implement with Coding Agent

If Coding Agent is enabled, use it to implement stories against the connected modernization repository. See Coding Agent.

Explore the Knowledge Graph

Use Knowledge Graph to explore the structure and relationships discovered in the existing application. See Knowledge Graph.

Monitor delivery

Use Insights to monitor delivery and quality when the capability is enabled for your organization. See Insights.

---

Customize Your Journey

---

Understand Approvals

Approval records the current artifact version and moves the journey forward. It does not permanently lock the artifact. If you regenerate an upstream artifact, Forge clears downstream approvals so affected work can be regenerated from the updated information.

---

Tips

Start with the actual codebase
Make sure the code you provide represents the application you want to modernize. Forge uses it as the foundation for Assessment and everything that follows.

Review the Assessment before defining the target state
The Assessment gives you visibility into technology gaps, architectural concerns, and security considerations. Use it to inform your modernization goals before generating intent.

Use ForgeScore as a health indicator
Treat ForgeScore as a baseline view of the application's health, not a replacement for the Assessment.

Be specific about the modernization goal
Use the Intent stage to establish what the modernized application should achieve. Include business priorities, constraints, and outcomes that cannot be inferred from the codebase alone.

Pay attention to the current-to-target transition
Review how requirements, architecture, and stories address the transition from the existing application to the target state. This is where modernization projects most commonly need refinement.