Shape Spec

What it does

The /shape-spec command is designed to run in plan mode. It gathers context and structures planning for significant work, creating a spec folder that persists beyond the conversation.

Plan mode gives you the space to explore, ask questions, and shape the work before committing to implementation. The /shape-spec command enhances this by saving everything to files.

When to use it

Use /shape-spec when:

• You want decisions and context to persist (saved to files)
• You have visuals (mockups, screenshots) to include
• You want to identify reference implementations
• You need to align with product context
• The feature is significant enough to warrant documentation

Use plan mode directly when:

• It's a quick task
• Context doesn't need to persist
• No visuals or references needed

The process

1. Enter plan mode

/plan

2. Run /shape-spec

/shape-spec

3. Answer shaping questions

The command walks you through:

• What are we building? — Describe the feature. Follow-up questions clarify scope.
• Do you have visuals? — Mockups, wireframes, screenshots, or examples.
• Similar code to reference? — Point to existing features or files to study.
• Product alignment — If product docs exist, confirms alignment with goals.
• Which standards apply? — Suggests relevant standards from the index.

4. Review the plan

The command builds a plan with "Save spec documentation" as Task 1, then presents the full plan.

5. Approve and execute

When you approve, the first task saves all spec documentation, then implementation proceeds.

What gets saved

A spec folder is created with this structure:

agent-os/specs/2026-01-15-1430-user-comment-system/
├── plan.md        # The full plan
├── shape.md       # Scope, decisions, context
├── references.md  # Pointers to similar code
├── standards.md   # Full content of relevant standards
└── visuals/       # Mockups, screenshots (if any)

Folder names are auto-generated: YYYY-MM-DD-HHMM-{feature-slug}/

Why save specs?

Saved specs become project history. Months later, someone can find the spec and understand:

• What was built and why
• What decisions were made during planning
• Which standards applied
• What references were used

Tips

• Keep shaping fast — Capture enough to start, refine as you build
• Visuals are optional — Not every feature needs mockups
• Standards guide, not dictate — They inform the plan but aren't always mandatory