The Project Spec is the detailed document for your migration. It describes exactly how will transform your code across the repositories in your project.
The first time generates your Project Spec, the Knowledge Hub opens automatically so you can review it. Select Project Spec in the tree, use the chat to interact with , and approve when you are ready. Any time after that, open Knowledge Hub from the left sidebar to get back to the Project Spec.
Take the time to review the Project Spec carefully. Once approved, it cannot be edited. If you need changes after approval, you’ll need to start a new migration.
Reviewing the Project Spec
After you submit your Modernization Goals, automatically generates the Project Spec. The Knowledge Hub opens the first time it is ready. To review:
- Confirm Project Spec is selected in the tree (it usually is on first open)
- Read the generated content and check that it captures your intent
- Use the chat to ask questions, drill into sections, or request clarifications
Later visits: open Knowledge Hub from the left sidebar, then select Project Spec in the tree.
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 the chat in the Knowledge Hub. Describe what should change—for example:
Add a requirement that all new APIs must return JSON and use
RFC 7807 problem details for errors.
The spec says we're moving to FastAPI, but we want Starlette
with Jinja2 templates for the admin UI only—please update that.
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:
- Resolve Auto-review recommendations (if any)
- Click Approve in the Knowledge Hub
- 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 & Tasks 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.
Troubleshooting
”I approved but now I need changes”
Once approved, the Project Spec is locked. To make changes:
- Review what’s already been generated (architecture, milestones)
- If early in the process, consider starting a new project with updated goals
- For minor adjustments, use Rules to guide specific behaviors
- For milestone-level changes, see Editing Milestones
”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:
- Use the Knowledge Hub chat to correct the misunderstanding and ask for updates
- Use Auto-review to validate after changes
- Approve only when satisfied
