feat: restructure main.md generation for reliable single-agent AI consumption

[trmquang93]

Summary

• Rewrites generateMainMd() so an AI given only main.md still reads the full spec files (screens.md, navigation.md, build-guide.md, images/) instead of implementing from the summary alone
• Adds a prominent Instruction Files table before the Screen Roster with a "same directory" callout
• Adds Planning Requirements section that requires AI plans to embed spec file references per screen, so those references survive the context shift from planning to implementation
• Replaces the "Your Role as Orchestrator" section (which explicitly told the AI to skip detail files) with dual-mode How to Use These Instructions that works for both single-agent and multi-agent workflows
• Converts the Sub-Agent Contract fenced code block into a proper H3-headed Implementation Workflow (so AI treats it as instructions to follow, not a template to emit)
• Adds Spec column to the Screen Roster table pointing each row to its section in screens.md
• Renames "Orchestrator Responsibilities" → Final Integration
• Removes the redundant bottom "File Reference" section (absorbed into Instruction Files table)

Test plan

• Run the app, create a flow with 3+ screens with hotspots and connections
• Click Generate and open the Instructions panel
• Verify main.md tab shows "Instruction Files" table before the Screen Roster
• Verify "How to Use These Instructions" section has dual-mode language with no "you do NOT need to read" instruction
• Verify Screen Roster has a Spec column with screens.md > SCR-XXXXXXXX references
• Verify "Implementation Workflow" section uses H3 headings (not a fenced code block)
• Verify no "File Reference" section at the bottom
• Feed the generated main.md to an AI and confirm it creates plans that include spec file references per screen

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
flow-forge	Ready	Preview, Comment	Mar 15, 2026 7:02am