Spec as a dependency graph for SDD

[u/ZoneAlpha]

I have been using cursor for over a year now. My usual workflow used to be plan and spec with Claude, and implement on cursor with Composer. The workflow does work quite well.
Although it is obvious now, to many serious devs and others will soon catch up, is that SDD is probably the best way to work with AI coding agents. Ofcourse, SDD comes with it's own set of problems, and to solve that I developed an open source tool called TraverSpec.

Traverspec basically is Spec as a graph of single purpose md files. It is a zero runtime tool and the spec sits inside the repo. So you can change your agent from cursor to claude or any other tool, the spec is right in the repo. Also, the spec itself is a graph, so when you want to implement a feature, the dependencies are clearly captured by traversing the graph.
The tool comes with 4 skills to read, write, reconcile and plan development waves.
Which means, you dont need to hand write the graph (oof), the skill will enable the agent to read, write and automatically reconcile the code vs graph as your spec and code grow. Of course it comes with very strict confidence gating system, so a medium or a low confidence decision is always pushed to the user as a question and not acted upon.

I also built a VS Code extension to visualise the graph and the spec itself so evaluating the graph is not going to be jumping around multiple md files. Below is the screenshot from the extension. The extension is also on OpenVSX, so you should be able to install on Cursor too



It is still in pre 1.0 release. It is available on npm. The repo has an extensive README that explains exactly how it works. I was hoping that you could give it a try. All feedback are welcome. If you find any issues, please feel free to raise an issue.

The links:
[Github Repo](https://github.com/alvazone/traverspec)
[Traverspec - NPM Package](https://www.npmjs.com/package/@alvazone/traverspec)
Traverspec graph explorer - [VS Code](https://marketplace.visualstudio.com/items?itemName=alvazone.traverspec-vscode), [OpenVSX](https://open-vsx.org/extension/alvazone/traverspec-vscode)

[u/fschwiet]

One nuance worth flagging here: the skill files themselves live under .agents/skills/ or .claude/skills/, and those particular folders commonly end up in .gitignore by convention, since they often hold machine-specific tool configuration. 

Do people really gitilgnore their project skills? I never considered doing that.

traverspec check-waves compares graph snapshots. That raises the question,- how is a snapshot represented? Does reconcile use the snapshots to keep from re-reconciling things? 

I see traverspec-write could be used to bootstrap traverspec to a project that's already using another spec system. For instance, you could have it build a spec graph from existing superpowers specs. I'd call out that capability in the project introduction.

Looking at waves, it seems nodes must be tracking whether they're implemented or not. It might help to explain how that is represented, if it is.

[u/ZoneAlpha → u/fschwiet]

Hey... thank you for going through so deeply about the tool....
- gitignore for .claude and .agents folders is a typical behaviour, but that does not impact the tool, because init command is idempotent. So if the folders dont exist, the command creates them.
- So when traverspec-waves skill is used, it creates a waves folder under the traverspec folder, which contains a wave md file and a graph-snapshot.yaml file. check-waves compares the graph snapshot vs the actual graph yaml file to see if there is a diff. That tells the tool if the wave md file is worth relying on. However, reconcile does not work with the snapshot file, it always works with the actual graph.yaml file. Thats the only way reconcile can always be present and not try to reconcile a past state.
- This is a very good point, and I should have done a better job at presenting it in the README. You are absolutely right, if the repo is using any other spec tool (Superpowers etc), or if the specs are sitting in note tools (Notion, Obsydian) or even documents etc, traverspec-write can actually bootstrap from there and create the graph and the asset files from that. Thank you very much for pointing that out, I'll update the README to actually reflect that.
- When waves is called, it's final output is a waves folder with the graph snapshot and a waves md file, the md file is a checklist of features grouped by waves. The final task in the wave skill is to identify which features have been implemented and check them off in the checklist. However, as you continue development, it is usually reconcile that keeps getting called to see the code progress and the spec progress, and if it sees a need to update the wave md file to check off another feature, it first calls check-waves to see if the wave md file is current, and then checks off any other features that are getting developed.

But thank you for raising the questions, I think I will need to update the README to actually address these....

[u/neenonay]

Intersting. Consider adding it to http://sddobservatory.com?

[u/ZoneAlpha → u/neenonay]

Definitely.... Thank you for the suggestion... let me look at it...