Core Concepts

Morph structures the modernization process as a series of well-defined stages, guiding teams from initial project setup all the way to delivering production-ready pull requests. This page explains the key terms used throughout each phase of that journey.

​

Table of Contents

• tl;dr
• Core Concepts
• Project
• Repositories and Roles
• Build Environment
• Project Spec
• Milestones
• Tasks
• Rules
• Functional Testing
• Knowledge Hub
• Wiki
• Visual Diagrams
• Glossary

​

tl;dr

Morph turns your migration into a step-by-step pipeline:

1. Create a Project (pick your repo(s) and assign roles)
2. Configure the Build Environment (lifecycle commands, env vars, validation)
3. Define your Project Spec (what should change & how)
4. Review and approve the Project Spec
5. Generate a Roadmap of Milestones
6. Execute each Milestone. During execution, Morph dynamically generates Tasks so progress is transparent and each deliverable is verifiable.
7. Once milestone tasks are completed and verified, Morph produces a production-ready PR for that milestone.

Each concept builds on the previous one, so decisions stay traceable from high-level goals down to individual code changes.

​

Core Concepts

​

Project

A Project is the top-level container for a modernization effort. It defines:

• Which repositories are in scope and their roles in the migration
• Which branch strategy to use for generated code (feature branch)
• The operational boundary for the Project Spec, milestones, and rules

In practice, a project is where Morph keeps the full migration context from initial setup to final PR delivery. Some common use cases:

• Modernizing a legacy Flask-based application to FastAPI
• Rewrite C++ CLI using Rust
• Java application version upgrade
• Migrating a backend and its shared library together

​

Repositories and Roles

A project can contain one or more repositories. Each repository has a defined role in the migration: When creating a project, you select repositories and set an origin branch for each. The project also has a shared feature branch (prefixed with morph-) where generated code is committed. The Project Overview — part of the Project Spec flow — captures the full picture: which repos you start with, which repos you end with, and each repo’s modernization role.

​

Build Environment

The Build Environment defines how your project builds, runs, and tests. This is configured during onboarding and is required before Morph can validate and execute migrations. There are two options:

• Cloud — Morph provides a cloud-based build environment for projects with publicly accessible dependencies. Lifecycle configuration is auto-discovered.
• Self-hosted Daemon — A lightweight binary you run on your own infrastructure, necessary when your project depends on private registries, internal APIs, or on-premise services

Each project has a Lifecycle Setup — a configuration containing:

• Scripts — Ordered shell scripts that install dependencies, build, run, health check, and test the application
• Environment variables — Variables your application needs at build or runtime, with optional encryption for secrets
• Lifecycle document — A markdown overview describing the application architecture and how scripts fit together
• Validation — An end-to-end run that executes each script in sequence to confirm everything works

For cloud projects, Morph maintains separate lifecycle configurations for the origin (source) and target (destination) sides of the migration. The origin is discovered during onboarding; the target is discovered automatically during the foundation milestone.

​

Project Spec

The Project Spec is the source-of-truth document for what “done” means. It captures migration requirements before implementation begins. You review and approve the Project Spec in the Knowledge Hub. The first time the Project Spec is generated, the Knowledge Hub opens automatically; after that, open Knowledge Hub from the sidebar. Select Project Spec in the tree, then use the chat to refine it with Morph before you approve. Typical contents include:

• Target stack
• High-level migration plan
• Key design decisions
• Project overview (repos at start, repos at end, and their roles)
• Testing strategy

The Project Spec must be approved before Morph generates the roadmap. Once approved, it cannot be edited.

​

Milestone

A Milestone is a coherent, reviewable chunk of migration work. Milestones sequence the project into manageable steps with explicit scope, risks, and dependencies.

• Functionally meaningful (not arbitrary file splits)
• Small enough to review safely
• Ordered so each one unlocks the next

Each completed milestone produces a Pull Request for your review.

​

Task

A Task is the smallest executable unit inside a milestone. Tasks translate milestone intent into specific implementation actions. Tasks usually map to one of:

• File/module creation or migration
• Endpoint or data-model implementation
• Test implementation
• Refactor/fix work

​

Rules

Rules are custom instructions that apply across all milestones. They encode your team’s coding standards, library preferences, and patterns so that Morph follows them consistently throughout the migration. Rules can be added, edited, or removed at any point during the migration.

​

Functional Testing

Functional Testing verifies that migrated code behaves identically to the original by comparing real outputs side by side. Morph automatically generates, runs, and validates these tests as part of the milestone lifecycle — no manual test authoring required. Functional testing supports multi-repo projects and covers three types of applications:

• API testing — Compares HTTP responses (status codes, response bodies) between origin and target for each endpoint
• CLI testing — Compares exit codes and stdout/stderr output between origin and target for each command
• UI testing — Captures screenshots and video recordings of the target application’s frontend, with optional side-by-side comparison against the origin

Results are surfaced per-milestone (as a test summary on each milestone card) and in a project-level Functional Testing dashboard with dedicated API/CLI and UI tabs.

​

Knowledge Hub

The Knowledge Hub is the central repository of structured context that Morph agents read from and write to. It contains all wikis, rules, milestones, and the Project Spec in one place. The Knowledge Hub serves two purposes:

• Agent-to-agent knowledge transfer — When one agent discovers a pattern or makes an architectural decision, it writes that knowledge back to the hub. Later agents read it and stay consistent.
• User-to-agent guidance — You can add documentation, coding standards, or design decisions at any time. The content you provide is broken down into structured wiki pages and rules that agents can consume efficiently.

The Knowledge Hub has a built-in chat interface for adding and updating knowledge conversationally.

​

Wiki

A Wiki page is a piece of project knowledge stored in the Knowledge Hub. Wikis capture architecture decisions, design patterns, integration notes, and other context that agents reference during execution. Unlike rules, wikis are treated as informational context rather than hard requirements.

​

Visual Diagrams

​

Concept Relationship Diagram

​

Glossary