Skip to main content

Basic Workflow

What is Spec-Driven Workflow?​

Spec-driven development is the foundational methodology of VibeSpec where all features and changes require approved specifications before implementation. This workflow ensures thoughtful design, clear traceability, and systematic quality control through a structured sequence: planning → approval → implementation → review.

The workflow operates through two primary specification types that work together to define complete project requirements. Product specs define what to build—user value, business requirements, and success criteria. Architecture specs define how to build—technical design, implementation constraints, and system integration approaches.

This methodology replaces traditional meetings, verbal discussions, and ad-hoc decision-making with structured prompt-as-interface interactions. Instead of scheduling meetings to discuss requirements, you use specific prompts to generate comprehensive specifications. Instead of verbal architectural discussions, you create documented technical designs that become permanent project knowledge.

The spec-driven approach transforms development from reactive coding to proactive planning, ensuring every line of code traces back to approved requirements and architectural decisions stored in your project's memory system.

Why This Matters​

Problems It Solves​

Scope Creep and Feature Drift: Without specifications, projects expand beyond original intent as new ideas emerge during implementation. Spec-driven workflow establishes clear boundaries and requires formal approval for changes, preventing uncontrolled scope expansion.

Architectural Inconsistency: Ad-hoc development leads to inconsistent patterns, conflicting approaches, and technical debt. Architecture specs ensure all implementation follows established patterns and integrates properly with existing systems.

Communication Overhead: Traditional development requires constant meetings, discussions, and clarifications about requirements and technical approaches. Spec-driven workflow captures all decisions in permanent, searchable documentation.

Knowledge Loss: Verbal decisions and informal discussions disappear when team members leave or forget context. Specifications create permanent knowledge that survives team changes and time gaps.

Benefits You'll Gain​

Reduced Rework: Clear specifications catch design issues before implementation, eliminating costly rewrites. Teams report 60-80% reduction in implementation rework when following spec-driven workflows.

Faster Onboarding: New team members can understand project requirements and architecture by reading specifications rather than requiring extensive knowledge transfer sessions.

Better Estimates: Detailed specifications enable accurate time and complexity estimates, improving project planning and delivery predictability.

Audit Trail: Every feature traces back to approved specifications, providing complete accountability and enabling impact analysis for changes.

Real-World Impact​

A fintech startup replaced their weekly planning meetings with spec-driven workflow. Instead of 4-hour meetings with 8 developers (32 person-hours), they used 30-minute specification sessions with the Architect Agent. The specifications were more detailed, decisions were documented permanently, and implementation proceeded without clarification meetings.

How to Execute Spec-Driven Workflow​

Step 1: Activate Architect Agent for Planning​

Start with planning prompt:

Activate Architect Agent

"I want to build [describe your feature or requirement]"

What this does: Engages the Architect Agent to analyze your requirement and begin specification creation process.

Step 2: Generate Product Specification​

Request product spec creation:

"Create a product specification for this feature including:
- User value and business requirements
- Success criteria and acceptance conditions
- Scope boundaries and exclusions
- Integration with existing features"

What to expect: The Architect Agent will create a comprehensive product spec in specs/product.md covering all user-facing requirements.

Step 3: Generate Architecture Specification​

Request technical design:

"Create an architecture specification including:
- Technical approach and implementation strategy
- System integration and data flow
- Security and performance considerations
- Implementation constraints and dependencies"

What to expect: Detailed technical design in specs/architecture.md defining how the feature will be built.

Step 4: Review and Approve Specifications​

Review both specifications:

"Present the complete specification package for approval"

What this does: Architect Agent summarizes both specs and requests explicit approval before proceeding to implementation.

Advanced Workflow Patterns​

For complex features requiring research:

"Research [technology/approach] and create specifications based on findings"

For modifications to existing features:

"Update specifications for [existing feature] to include [new requirements]"

For architectural changes:

"Analyze impact of [proposed change] and update architecture specifications"

What to Expect​

Complete Specification Package​

When the workflow completes successfully, you'll have:

Product Specification Example​

# Feature: User Authentication

## User Value
- Secure access to application features
- Personalized user experience
- Data privacy and protection

## Business Requirements
- Support email/password and OAuth login
- Password reset functionality
- User profile management
- Session management and security

## Success Criteria
- 99.9% authentication uptime
- <2 second login response time
- Zero security vulnerabilities
- 95% user satisfaction score

## Scope Boundaries
- Includes: Login, logout, password reset, profile updates
- Excludes: Social media integration, multi-factor authentication (future phase)

## Integration Points
- User dashboard (displays user info)
- Admin panel (user management)
- API endpoints (authentication middleware)

Architecture Specification Example​

# Architecture: User Authentication System

## Technical Approach
- JWT-based authentication with refresh tokens
- bcrypt password hashing (12 rounds)
- Redis session storage
- Express.js middleware integration

## System Integration
- Database: PostgreSQL users table
- Cache: Redis for session storage
- API: RESTful endpoints with OpenAPI spec
- Frontend: React context for auth state

## Security Considerations
- HTTPS-only cookie transmission
- CSRF protection with SameSite cookies
- Rate limiting on auth endpoints
- Input validation and sanitization

## Implementation Constraints
- Must integrate with existing user database
- Backward compatibility with current session system
- Performance: under 100ms token validation
- Scalability: Support 10,000 concurrent users

Workflow Progression Indicators​

Phase 1: Requirement Analysis (5-10 minutes)

  • ✅ User requirements captured and clarified
  • ✅ Business value and success criteria defined
  • ✅ Scope boundaries established

Phase 2: Technical Design (10-15 minutes)

  • ✅ Implementation approach selected
  • ✅ System integration points identified
  • ✅ Security and performance requirements addressed

Phase 3: Specification Review (5 minutes)

  • ✅ Complete specification package presented
  • ✅ Consistency between product and architecture specs verified
  • ✅ Ready for approval and implementation

Specification Quality Indicators​

Product Spec Quality:

  • ✅ Clear user value proposition
  • ✅ Measurable success criteria
  • ✅ Explicit scope boundaries
  • ✅ Integration requirements defined

Architecture Spec Quality:

  • ✅ Specific technical approaches chosen
  • ✅ Security considerations addressed
  • ✅ Performance requirements specified
  • ✅ Implementation constraints documented

Prompt-as-Interface vs Traditional Meetings​

Traditional Meeting Approach​

Schedule: 2-hour requirements meeting
Attendees: 6 people (12 person-hours)
Output: Meeting notes, action items
Follow-up: Additional clarification meetings
Documentation: Scattered across emails and notes

Spec-Driven Prompt Approach​

Time: 30 minutes with Architect Agent
Attendees: 1 person (0.5 person-hours)
Output: Complete, structured specifications
Follow-up: None needed (all decisions documented)
Documentation: Permanent, searchable, version-controlled

Troubleshooting Specification Issues​

  • If you see: Vague or incomplete specifications

  • It means: Requirements weren't sufficiently detailed in initial prompt

  • Solution: Provide more specific requirements and ask for specification refinement

  • If you see: Conflicting product and architecture specs

  • It means: Technical constraints don't align with business requirements

  • Solution: Request specification reconciliation and constraint analysis

  • If you see: Missing integration or security considerations

  • It means: System context wasn't fully considered

  • Solution: Request comprehensive system analysis and specification updates

Common Mistakes and Warnings​

⚠️ Critical Warnings​

  • Never Skip Specification Approval: Don't proceed to implementation without explicit approval of both product and architecture specifications. Unapproved specs lead to scope creep, rework, and architectural inconsistencies that require expensive corrections.

  • Don't Modify Specs During Implementation: Resist the temptation to change requirements or architecture during coding. All changes must go through the specification update process to maintain traceability and prevent scope drift.

Common Mistakes​

Mistake: Rushing through specification creation​

Why it happens: Developers want to start coding immediately and view specifications as overhead
How to avoid: Understand that specification time prevents much larger implementation rework time
If it happens: Stop implementation and create proper specifications before continuing

Mistake: Creating overly detailed specifications​

Why it happens: Teams try to specify every implementation detail upfront
How to avoid: Focus on requirements, constraints, and approach—leave implementation details flexible
If it happens: Simplify specifications to focus on essential decisions and constraints

Mistake: Skipping architecture specifications for "simple" features​

Why it happens: Developers assume simple features don't need technical design
How to avoid: Create architecture specs for all features to ensure consistency and integration
If it happens: Create architecture spec before continuing with implementation

Mistake: Treating specifications as unchangeable documents​

Why it happens: Teams fear that changing specs means the process failed
How to avoid: Understand that specs evolve—use formal update process for changes
If it happens: Update specifications through proper workflow and document rationale

Best Practices​

  • ✅ Start Every Feature with Specs: Never begin implementation without approved specifications
  • ✅ Use Specific Prompts: Detailed prompts produce better specifications than vague requests
  • ✅ Review Both Spec Types: Ensure product and architecture specs are consistent and complete
  • ✅ Document All Decisions: Capture rationale for technical and business decisions in specifications
  • ✅ Update Specs for Changes: Use formal process to modify specifications when requirements evolve