Shape Spec: Research and Plan

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

Use this phase when you need to take your rough idea for a feature and shape it into a well-scoped plan before officially writing it up. The agent asks clarifying questions and helps you produce clear requirements.

Already got your requirements shaped? Skip this phase and add those directly to your spec's requirements.md.

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 (write-spec).

What gets created

The shape-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/
    └── requirements.md

The shape-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 agent-os/specs/[this-spec]/planning/requirements.md with transcription of your Q&A, visual analysis, functional/non-functional requirements, scope boundaries

If you already have requirements, you can skip this phase and add those directly to agent-os/specs/[this-spec]/planning/requirements.md.

How to run

Claude Code

Run command, /shape-spec

When using Agent OS with Claude Code commands enabled, run:

/shape-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!)

Other Tools

Two ways to run this command

When using other AI coding tools, you have two options for running this command:

Option A: Run all steps in one shot

This single command instructs your agent to run both steps automatically in sequence. Some agents perform better at this than others.

@agent-os/commands/shape-spec/shape-spec.md run this

Option B: Run each numbered step manually

For more control and reliability, run each numbered command sequentially:

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

@agent-os/commands/shape-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 write-spec phase