New Spec: Research and Plan

The new-spec command is the first step in the repeatable feature development cycle in the spec-driven development workflow with Agent OS.

This phase initializes a new spec folder with proper structure, researches your requirements through targeted questions, collects visual assets, identifies existing code patterns to reuse, and documents everything for reference in the next phase (create-spec).

What gets created

The new-spec command creates a dated spec folder in your project's specs folder: agent-os/specs/:

agent-os/specs/2025-10-15-user-auth/
├── planning/
│   └── visuals/
├── implementation/
└── verification/

The new-spec command will then conduct an interactive research dialogue that:

• Analyzes context (product mission, roadmap, tech stack)
• Asks you targeted clarifying questions
• Requests visual assets (mockups, wireframes, screenshots) for planning/visuals/
• Identifies similar existing features to reference
• Automatically scans for and analyzes visuals
• Asks follow-up questions if needed

Your agent will then document all of this information and create these files inside of agent-os/specs/[this-spec]/planning/:

• initialization.md - Your feature description
• requirements.md - transcription of your Q&A, visual analysis, functional/non-functional requirements, scope boundaries

How to run

Multi-Agent Mode

Run command, /new-spec

When you're running Agent OS in multi-agent mode (typically in Claude Code), you can initiate and run the entire new-spec phase with a single command:

/new-spec

It will begin by looking at your product roadmap (documented in agent-os/product/roadmap.md) to see what the next feature might be. You can confirm that's the one, or provide your raw description of your next new feature instead. (It's perfectly fine to deviate from your roadmap as your product evolves!)

Single-Agent Mode

Run these two prompts sequentially

Run each of the following prompts sequentially in your AI tool. You can simply @ reference the prompt markdown file and append "run this" (or similar) to your prompt to instruct your AI tool to read and run the instructions in that file.

@agent-os/commands/new-spec/1-new-spec.md run this

@agent-os/commands/new-spec/2-research-spec.md run this

Next step

With your feature fully scoped, planned and documented, you and your agent can confidently proceed to the next phase of formalizing your spec.

Proceed to the create-spec phase