Spec-driven development works best when the spec sits in the repo rather than in a separate tool. It lives in the same folder as the code it describes, so when the agent goes back mid-task it reads the markdown next to the file it is editing. Javadoc or markdown does not matter much, the habit of returning to it does. We also put a booted-app route walk into the merge checks, since a spec can be perfectly clear and still describe wiring the compiler has no view of.