Skip to main content
The Project Spec is the detailed document for your migration. It describes exactly how 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 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 , 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.
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, 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

When the Project Spec has been updated, you can click Auto-review to have 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.

​
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, immediately begins planning your migration roadmap.

​
What Happens After Approval

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

​
Best Practices

​
Be Explicit About Preferences

Don’t assume 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. The source repositories selected at project creation cannot be changed. 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