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
• Project Knowledge
• Wiki
• Per-User Daemon
• Collaboration
• Upstream Sync
• 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 it in the Project Knowledge drawer on the Roadmap (under Modernization → Project Knowledge): select Project Spec in the tree and use Knowledge chat. The drawer opens automatically the first time the spec is ready. 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 are organized in a dependency graph — independent milestones can execute in parallel, while dependent milestones wait until their prerequisites are merged.

• Functionally meaningful (not arbitrary file splits)
• Small enough to review safely
• Dependency-aware: independent milestones run in parallel for faster delivery; dependent milestones stay locked until prerequisites merge

Each completed milestone produces a Pull Request for your review. When a milestone merges, sibling milestone branches that share dependencies may be flagged for an automatic rebase to stay current with the feature branch.

​

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 Validation Hub with dedicated API/CLI, UI Testing (split into Test and Comprehensive sub-tabs), and Lifecycle tabs — the last of these reports install/build/run/test script results.

​

Project Knowledge

Project Knowledge is the in-app drawer on the Roadmap where structured context lives together: Project Spec, milestones, wikis, and rules, plus Knowledge chat. Agents read this context during work and write updates back (often as new or revised wiki pages). Approving the Project Spec is one important use of this drawer; everything else you can do there — imports, rules, diffs, milestone text — is covered in Project Knowledge. Project Knowledge serves two purposes:

• Agent-to-agent knowledge transfer — When one agent discovers a pattern or makes an architectural decision, it writes that knowledge back. 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.

​

Wiki

A Wiki page is a piece of project knowledge stored with your project (shown under Wikis in Project Knowledge). 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.

​

Per-User Daemon

When using a Self-hosted Daemon, each team member has their own daemon instance. Your daemon handles your work exclusively and runs one job at a time. This means multiple team members can work on the same project simultaneously — each using their own daemon — without blocking each other. The daemon reports its status in real time: online (ready), busy (running a job), or offline (disconnected). If your daemon is busy, new requests queue until the current job finishes.

​

Collaboration

Multiple team members can review the same milestone at the same time. Each reviewer gets their own independent review chat session, so conversations and issue triaging don’t collide. When one reviewer resolves an issue or the agent applies a fix, the change is propagated to other active reviewers’ workspaces.

​

Upstream Sync

As your team continues pushing to the repository’s mainline during the migration, can incorporate those changes through an upstream sync. This creates a sync milestone that integrates mainline changes into the feature branch and rebases affected milestone branches. See Git Strategy — Upstream Sync for details.

​

Visual Diagrams

​

Concept Relationship Diagram

​

Glossary