Skip to main content
The Project Spec is the detailed document for your migration. It describes exactly how the Morph Platform will transform your code across the repositories in your project. This page is about that document — how to review it, refine it with chat, and approve it. You do that work inside the Project Knowledge drawer on the Roadmap. The first time the Morph Platform generates your Project Spec, that drawer opens automatically so you can review the spec. Select Project Spec in the tree, use Knowledge chat to interact with the Morph Platform, and approve when you are ready. Any time after that, go to the Roadmap and under Modernization click Project Knowledge to open the same drawer. For wikis, rules, milestones in that drawer, diffs, and imports, see Project Knowledge.
Take the time to review the Project Spec carefully before approving. You can still refine it with Knowledge chat after approval — if milestone planning has already run, edits apply to future milestones only.
The Morph Platform emails you when the spec is ready, so you don’t have to watch for it: Email reading: Your Project Spec is ready to review, with a Review Project Spec button

Reviewing the Project Spec

After you submit your Modernization Goals, the Morph Platform automatically generates the Project Spec. Project Knowledge opens the first time it is ready. To review:
  1. Confirm Project Spec is selected in the tree (it usually is on first open)
  2. Read the generated content and check that it captures your intent
  3. Use Knowledge chat to ask questions, drill into sections, or request clarifications
Later visits: On the Roadmap, open Project Knowledge (Modernization), then select Project Spec in the tree.
Once the Project Spec is ready, the Roadmap also surfaces a Next Step box at the top of the Getting Started checklist — “Approve your project spec to start planning your roadmap.” with an Approve Project Spec button. Clicking that button opens the Project Knowledge drawer directly on the Project Spec, so you don’t have to navigate through the tree yourself.While the spec is still generating you’ll see the same box in a loading state (“Generating Project Spec…”); it switches to the actionable Next Step automatically once the spec is ready.

What to Look For

  • Target stack — Are the destination technologies correct?
  • Migration approach — Does the planned transformation make sense?
  • Requirements — Are all your constraints captured?
  • Scope — Is it migrating the right parts of your codebase?

Refining the Project Spec

If something needs adjustment, use Knowledge chat in the Project Knowledge drawer. Describe what should change—for example:

What You Might Ask For

  • Missing requirements or constraints
  • Clearer wording on ambiguous sections
  • Preferred libraries or patterns
  • Scope corrections (include or exclude parts of the codebase)
  • Constraints (e.g., “maintain backward compatibility”)

Iterating with the Morph Platform

When the Project Spec has been updated, you can click Auto-review to have the Morph Platform compare the latest version against the codebase analysis and your original intent. It may suggest:
  • Clarifications for ambiguous statements
  • Missing details that could cause issues
  • Potential conflicts or inconsistencies
For each recommendation, you can Accept or Reject it. You must resolve all recommendations before approving.

Changing Repositories

The Repo map in the Project Spec shows your repositories Before migration and After migration, and what the Morph Platform does with each one: Edit in place, Read only, New repository, or Full migration. The repositories, their names, and their roles are read-only in the Repo map. You change them through Knowledge chat, which keeps the Project Spec and the wiki consistent with the map. Until you approve the spec, you can edit a repository’s role description in place: click the pencil next to it. To change the repositories before you approve the spec:
  1. Below the Repo map, click Change repositories in chat. Knowledge chat opens with the start of a message filled in.
  2. Describe the change — for example, rename the new repository, add a separate repository for the frontend, or make a repository read only.
  3. Send the message. The chat makes the change in the same turn, without a separate confirmation step: it updates the Repo map, the Project Spec text, and any wiki pages that describe the old layout. If the result isn’t what you wanted, ask it to change it again.
Repo map showing repositories before and after migration with their roles, Add origin repo, and Change repositories in chat at the bottom
For a repository the Morph Platform creates, you still pick where it is created under Publishing in the Repo map. The new repository is created when you approve the spec. If a proposed name is already taken on your git provider, the Morph Platform tries a different name before you see the spec.
To add a repository you already have, before or after approval, use Add origin repo in the Repo map. Once you approve the Project Spec, the repositories already in the Repo map can’t be renamed, removed or given a different role, and Change repositories in chat no longer appears. See Adding a Repository Later.

Approving the Project Spec

When you’re satisfied with the Project Spec:
  1. Resolve Auto-review recommendations (if any)
  2. Click Approve in the Project Knowledge drawer
  3. Confirm the approval
After approval, the Morph Platform immediately begins planning your migration roadmap.

What Happens After Approval

The approved Project Spec triggers Roadmap Generation — the Morph Platform plans a sequence of milestones based on your Project Spec, the codebase analysis, and the Repo map. See Milestones for details on how the roadmap executes.

Best Practices

Be Explicit About Preferences

Don’t assume the Morph Platform will guess your preferences. If you want:
  • A specific testing framework → say so
  • A particular folder structure → specify it
  • Certain naming conventions → include them

Consider Edge Cases

Think about areas where defaults might not work:
  • Configuration files that need special handling
  • Environment-specific code
  • Integration points with external systems

Review with Your Team

If others will work with the migrated code, consider having them review the Project Spec before approval. They may catch requirements you missed. You can hand over onboarding to a teammate so they can review and refine the spec directly.

Troubleshooting

”I approved but now I need changes”

You can still adjust an approved Project Spec. Open Project Knowledge from the Roadmap and use Knowledge chat to describe the change, the same way you refined it before approval. If milestone planning has already run, spec changes are reflected in future milestones only — already-completed milestones are not rewritten. After approval, the repositories already in the Repo map can’t be changed, but you can still add another source repository with Add origin repo. See Adding a Repository Later. For milestone-level changes, see Editing Milestones; for conventions you want enforced on future work, use Rules.

”The Auto-review recommendations don’t make sense”

Recommendations are suggestions, not requirements. If a recommendation doesn’t apply to your situation, click Reject and proceed.

”The Project Spec doesn’t match my goal”

If the generated Project Spec significantly misses your intent:
  1. Use Knowledge chat in Project Knowledge to correct the misunderstanding and ask for updates
  2. Use Auto-review to validate after changes
  3. Approve only when satisfied