spec

name	spec
description	Writes product specifications through collaborative interview with web research. Use when planning, gathering requirements, designing new features, or creating a spec/PRD.
argument-hint	list | revise {spec} | [product idea]

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 |

4. If no specs found: "No specs found. Run spec {idea} to create one."
5. 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 <<< "$name$(date +%s%N)" 2>/dev/null || shasum <<< "$name$(date +%s%N)")
hash="${hash:0:4}"

id="${slug}-${hash}"

mkdir -p .otto/specs

Write to .otto/specs/{id}.md:

---
id: {id}
name: {Name}
status: draft
created_date: {YYYY-MM-DD}
description: {one-line summary of the spec}
---

{spec content mapped to template structure}

4. Clarify Ambiguities

If any sections are marked [TBD] or contain ambiguous requirements:

Use an interactive prompt to resolve each ambiguity before proceeding to review. For each unclear item:

• Present what's missing or unclear
• Offer 2-3 options if applicable
• Update the spec file with the user's answers

Skip this step if the spec is complete with no [TBD] markers.

5. Review Spec

Delegate to the technical-product-manager subagent (persona in $SKILL_DIR/agents/technical-product-manager.md):

Handoff to technical-product-manager:

• Spec path: .otto/specs/{id}.md
• Spec ID: {id}
• Codebase context: Include relevant patterns and architecture discovered in step 1

The subagent reads the spec, reviews for completeness, consistency, feasibility, ambiguity, and technical correctness. Returns prioritized findings (P0-P2) with specific sections, issues, and suggestions.

Wait for review to complete.

6. Interview User on Findings

If no findings, skip to step 7.

For each finding (highest priority first):

1. Present the finding with its priority level
2. If suggestion is clear: an interactive prompt with "Accept", "Reject", "Modify"
3. If alternatives exist: an interactive prompt with the options
4. If accepted: Update the spec file with the change
5. If rejected: Skip to next finding
6. If modify: Apply user's modified version

After processing all findings, update the spec file with changes.

7. Approval

Output the full spec as rendered markdown so the user can review it inline.

Use an interactive prompt with options:

• "Approve"
• "Request changes"
• "Open in editor" — run open .otto/specs/{id}.md, then ask again

After each revision: Output the full updated spec as rendered markdown before asking for approval again. Revise until approved.

On approval, update status: draft to status: approved in the file.

Report: "Spec approved and saved to .otto/specs/{id}.md"

8. Next Steps

Offer task generation:

"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:

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 <<< "$ARGUMENTS$(date +%s%N)" 2>/dev/null || shasum <<< "$ARGUMENTS$(date +%s%N)")
hash="${hash:0:4}"

id="${slug}-${hash}"

mkdir -p .otto/specs

Write to .otto/specs/{id}.md:

---
id: {id}
name: {Product Idea}
status: draft
created_date: {YYYY-MM-DD}
description: {one-line summary of the spec}
---

{spec content}

6. Review Spec

Delegate to the technical-product-manager subagent (persona in $SKILL_DIR/agents/technical-product-manager.md):

Handoff to technical-product-manager:

• Spec path: .otto/specs/{id}.md
• Spec ID: {id}

The subagent reads the spec, reviews for completeness, consistency, feasibility, ambiguity, and technical correctness. Returns prioritized findings (P0-P2) with specific sections, issues, and suggestions.

Wait for review to complete.

7. Interview User on Findings

If no findings, skip to step 8.

For each finding (highest priority first):

1. Present the finding with its priority level
2. If suggestion is clear: an interactive prompt with "Accept", "Reject", "Modify"
3. If alternatives exist: an interactive prompt with the options
4. If accepted: Update the spec file with the change
5. If rejected: Skip to next finding
6. If modify: Apply user's modified version

After processing all findings, update the spec file with changes.

8. Approval

Output the full spec as rendered markdown so the user can review it inline.

Use an interactive prompt with options:

• "Approve"
• "Request changes"
• "Open in editor" — run open .otto/specs/{id}.md, then ask again

After each revision: Output the full updated spec as rendered markdown before asking for approval again. Revise until approved.

On approval, update status: draft to status: approved in the file.

Report: "Spec approved and saved to .otto/specs/{id}.md"

9. Next Steps

Offer task generation:

"Run task {name} to generate implementation tasks."