Spec Writing & Updating
The recommended way to create and update specs is through AI agents using the MCP server:Spec Creation via MCP
Learn how to create specs using AI agents through the MCP server integration
- Creating new specs with
upsert_spec - Editing existing specs (both via tools and direct file editing)
- Linking specs to issues and other specs
- Adding references and relationships
Web-based spec creation is in development. For now, use the MCP server for creating specs, and the web interface for viewing and editing them.
Spec Viewing
While spec creation is handled via MCP, the web server excels at visualizing and browsing specs:
- View rendered markdown specs with live preview
- Navigate between specs using
[[spec-id]]references - See relationships (what implements this spec, what it references)
- View anchored feedback from completed issues
- Browse all specs in your project
Spec Editing
Directly view and edit specs from the web interface:
- Visual markdown editor with live preview
- Auto-complete for
[[references]]and entity IDs - Inline relationship creation
Best Practices
Regardless of how you create specs, follow these best practices:Start with Clear Requirements
Start with Clear Requirements
Write specs that clearly define what should be built and why. Focus on requirements, not implementation details.
Use References Liberally
Use References Liberally
Connect specs to related specs, issues, and other entities using
[[entity-id]] syntax. This builds your project’s knowledge graph.Break Specs Down Hierarchically
Break Specs Down Hierarchically
Specs can be decomposed into smaller sub-specs. Use relationships to model this hierarchy for clarity.
Review Agent Feedback
Review Agent Feedback
When agents implement issues, they provide feedback about what worked and what didn’t. Use this to improve your specs over time.