Skip to main content

Workflows: The Complete Journey

SpecWeave provides clear, repeatable workflows for every phase of software development—from initial concept to production deployment.

The Big Picture​

Each phase has:

  • Clear inputs and outputs
  • Step-by-step instructions
  • Mini-diagrams for clarity
  • Real-world examples
  • Common pitfalls to avoid

Phase-by-Phase Breakdown​

1. 💡 Concept → Research​

Question: "What should we build?"

Activities:

  • Identify user problems
  • Research existing solutions
  • Define value proposition
  • Scope initial features

Outputs:

  • Product vision document
  • User personas
  • Feature list (prioritized)

→ Full Research Workflow

2. 🔍 Research → Design​

Question: "How will it work?"

Activities:

  • Design user flows
  • Create wireframes/mockups
  • Define technical architecture
  • Choose tech stack

Outputs:

  • UX designs (Figma, etc.)
  • System architecture (C4 diagrams)
  • ADRs (architecture decisions)
  • Tech stack selection

→ Full Design Workflow

3. 🎨 Design → Planning​

Question: "What tasks do we need?"

Activities:

  • Create increment specification
  • Design implementation plan
  • Generate task checklist
  • Define test strategy

Outputs:

  • spec.md (requirements, AC-IDs)
  • plan.md (architecture, approach)
  • tasks.md (checklist, embedded tests)

Command: /specweave:increment "feature name"

→ Full Planning Workflow

4. 📋 Planning → Implementation​

Question: "Let's build it!"

Activities:

  • Implement each task
  • Write tests (TDD optional)
  • Update living docs
  • Review progress

Outputs:

  • Production code
  • Automated tests
  • Updated documentation
  • Completed tasks

Command: /specweave:do

→ Full Implementation Workflow

5. ⚙️ Implementation → Validation​

Question: "Does it work correctly?"

Activities:

  • Run test suite
  • Validate acceptance criteria
  • Check code quality
  • Review documentation

Outputs:

  • Test results (all passing)
  • Quality report
  • Completion summary
  • Deployment readiness

Command: /specweave:validate

→ Full Validation Workflow

6. ✅ Validation → Deployment​

Question: "Ship it?"

Activities:

  • Deploy to production
  • Monitor metrics
  • Gather feedback
  • Plan next iteration

Outputs:

  • Production deployment
  • Monitoring dashboards
  • User feedback
  • Next increment ideas

→ Full Deployment Workflow

Quick Command Reference​

PhaseCommandWhat It Does
Planning/specweave:increment "feature"Creates spec, plan, tasks
Implementation/specweave:doExecutes tasks, auto-resumes
Progress Check/specweave:progressShows status, next task
Validation/specweave:validateQuality checks
Completion/specweave:doneCloses increment

Workflow Patterns​

Pattern 1: Greenfield (New Project)​

Characteristics:

  • Start from scratch
  • Create complete architecture
  • Build incrementally
  • Comprehensive specs optional

→ Greenfield Guide

Pattern 2: Brownfield (Existing Project)​

Two Paths (choose based on project size):

PathBest ForUpfront WorkHow It Works
Quick StartLarge (50k+ LOC)1-2 hoursDocument core, start immediately, docs grow with changes
ComprehensiveSmall (under 50k LOC)1-2 weeksFull docs upfront, then increments

Key Point: SpecWeave considers existing code when planning increments—no mandatory module-by-module documentation loop!

→ Brownfield Guide

Pattern 3: Hotfix (Emergency)​

Characteristics:

  • Interrupt current work
  • Minimal planning (still documented!)
  • Fast implementation
  • Thorough testing

→ Hotfix Guide

Workflow Comparison​

WorkflowDurationPlanningTestingUse When
GreenfieldWeeks-MonthsComprehensiveFull TDDNew project
BrownfieldDays-WeeksQuick Start or ComprehensiveRegression focusExisting code
HotfixHours-DaysMinimalCritical pathsProduction bug
ExperimentDaysLightweightBasicPOC/spike

Interactive Decision Tree​

Not sure which workflow to use?

Key Principles Across All Workflows​

1. Specification First​

Always define WHAT and WHY before HOW:

❌ Wrong: "Start coding, figure it out as you go"
✅ Right: "Write spec.md, then plan.md, then implement"

2. One Increment at a Time​

Focus prevents context switching:

❌ Wrong: 3 increments in progress
✅ Right: Complete 0001, then start 0002

3. Test Everything​

Every feature needs validation:

❌ Wrong: "I tested it manually, looks good"
✅ Right: Automated tests (unit, integration, E2E)

4. Document as You Go​

Living docs update automatically:

❌ Wrong: "I'll document it later"
✅ Right: Hooks auto-update docs after each task

5. Validate Before Shipping​

Quality gates prevent issues:

❌ Wrong: "Ship it, we'll fix bugs later"
✅ Right: Validate AC-IDs, run tests, check coverage

Common Workflow Mistakes​

❌ Mistake 1: Skipping Planning​

Problem: Jump straight to coding without spec
Result: Unclear requirements, scope creep, rework
Solution: Always create spec.md and plan.md first

❌ Mistake 2: Multiple Increments in Progress​

Problem: Start 0002 before finishing 0001
Result: Context switching, neither complete, docs stale
Solution: One increment at a time (WIP limit = 1)

❌ Mistake 3: Manual Documentation​

Problem: Edit docs manually, forget to update
Result: Docs drift, become outdated, lose trust
Solution: Let hooks auto-update living docs

❌ Mistake 4: No Test Strategy​

Problem: Write tests as afterthought
Result: Poor coverage, bugs in production
Solution: Define test strategy in plan.md (v0.7.0+)

❌ Mistake 5: Ignoring Validation​

Problem: Mark tasks done without checking
Result: Incomplete features, failing tests
Solution: Run /specweave:validate before /specweave:done

Real-World Workflow Example​

Scenario: Add payment processing to e-commerce site

Week 1: Research & Design​

# Research payment providers
# Design Stripe integration
# Create C4 diagrams
# Document ADRs

Week 2: Planning​

/specweave:increment "0015-payment-processing"
# PM agent creates:
# ✅ spec.md (5 user stories, 15 AC-IDs)
# ✅ plan.md (Stripe architecture, test strategy)
# ✅ tasks.md (18 tasks, embedded tests, 90% coverage target)

Week 3-4: Implementation​

/specweave:do
# Implement task by task:
# T-001: Stripe client ✅
# T-002: Payment endpoint ✅
# T-003: Webhook handler ✅
# ...
# T-018: E2E payment flow ✅

/specweave:progress
# Shows: 18/18 tasks (100%)

Week 5: Validation & Deploy​

/specweave:validate 0015
# ✅ All AC-IDs validated
# ✅ Test coverage: 92%
# ✅ Quality checks passed

# Deploy to production
# Monitor metrics

Result: Production payment system with complete docs, tests, and audit trail.

Next Steps​

Ready to dive deeper? Choose your path:

Learn More: