Spec

Argument: $ARGUMENTS

| Command | Behavior | | --- | --- | | spec list | List all specs with id, name, status, created date | | spec {idea} | Create new spec through collaborative interview | | spec revise {spec} | Save spec and go straight to review with codebase exploration |

---

List Mode

If $ARGUMENTS is list:

1. List .otto/specs/*.md
2. For each spec, read frontmatter (id, name, status, created_date)
3. Display as table:

   | Name | ID | Status | Created |
   |------|-----|--------|---------|
   | Design Skill | design-skill-a1b2 | approved | 2026-01-28 |

1. If no specs found: "No specs found. Run spec {idea} to create one."
2. Stop here — do not continue to interview workflow.

---

Revise Mode

If $ARGUMENTS starts with revise:

Spec Content: Everything after revise  in $ARGUMENTS

If no spec content provided, ask: "Provide the spec content to save. The first line should be the product name."

Parse the provided content:

• Name: First line of the spec content
• Body: Everything after the first line

1. Gather Context

Analyze codebase:

• Use Glob to find relevant files
• Use Read to understand current architecture
• Use Grep to search for related patterns
• Note patterns and design decisions for the review

2. Draft Spec

Map the provided content to this template structure (mark missing sections as [TBD]):

Product Requirements:

• Overview - What and why, problem being solved
• Goals / Non-Goals - Explicit scope boundaries
• User Stories - User-facing behavior

Technical Design:

• Architecture - System design, component relationships
• Detailed Design - Implementation approach, key algorithms
• API / Interface - Public interfaces, contracts
• Data Model - Schema, storage, state

Planning:

• Future Considerations - Deferred features, extensibility
• Open Questions - Unresolved decisions marked as [TBD: reason]

3. Save Draft

Generate unique ID from product name:

name=$(echo "$NAME" | head -1)
slug="${name,,}"              # Convert to lowercase
slug="${slug// /-}"           # Replace spaces with hyphens
slug="${slug:0:30}"           # Truncate to 30 characters

hash=$(sha1sum /dev/null || shasum  "Run `task {name}` to generate implementation tasks."

---

### Create Mode

**Product Idea:** $ARGUMENTS

If no argument provided, ask: "What would you like to build?"

### 1. Gather Context

**Check for existing specs:**

```bash
ls .otto/specs/*.md 2>/dev/null

Ask about reference projects:

> "Are there any reference projects or examples I should look at for inspiration?"

If provided, explore the reference project(s) to understand their approach.

Analyze codebase:

• Use Glob to find relevant files
• Use Read to understand current architecture
• Use Grep to search for related patterns
• Note patterns and design decisions to reference during interview

2. Research Best Practices

Use web search/research to find and read:

• Industry best practices for the product type
• Common pitfalls and recommendations
• How popular projects solve similar problems
• Documentation and API references

For visual research (competitor products, reference implementations):

• Use the host environment's available browser automation tool directly to navigate sites and capture screenshots
• Save screenshots to .otto/research/

3. Interview

Use an interactive prompt to gather requirements. For each decision point:

• Present 2-3 options
• Mark one as "(Recommended)" based on research
• Include pros/cons and what research suggests

Topics to cover:

• Core requirements and constraints
• Key architectural decisions
• Scope boundaries (what's in, what's out)
• Edge cases

4. Draft Spec

Write a spec covering:

Product Requirements:

• Overview - What and why, problem being solved
• Goals / Non-Goals - Explicit scope boundaries
• User Stories - User-facing behavior

Technical Design:

• Architecture - System design, component relationships
• Detailed Design - Implementation approach, key algorithms
• API / Interface - Public interfaces, contracts
• Data Model - Schema, storage, state

Planning:

• Future Considerations - Deferred features, extensibility
• Open Questions - Unresolved decisions marked as [TBD: reason]

5. Save Draft

Generate unique ID from product idea:

slug="${ARGUMENTS,,}"          # Convert to lowercase
slug="${slug// /-}"            # Replace spaces with hyphens
slug="${slug:0:30}"            # Truncate to 30 characters

hash=$(sha1sum /dev/null || shasum  "Run `task {name}` to generate implementation tasks."

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [brsbl](https://github.com/brsbl)
- **Source:** [brsbl/ottonomous](https://github.com/brsbl/ottonomous)
- **License:** MIT

Install and usage instructions live in the source repository linked above.