Rivo: A Spec-Driven Development Workflow for AI Programming Agents

Rivo is a Spec-Driven Development (SDD) plugin designed to solve context drift and decision opacity issues in AI-assisted development. It uses a pure Markdown, host-agnostic workflow with 12 minimal commands covering the full lifecycle from requirement to code. Key features include structured decision records, explicit status management, and multi-layered reviews to enable efficient human-AI collaboration while ensuring traceability and quality.

AI programming tools like Claude Code and Codex CLI face two major problems: Context Drift (AI forgets earlier consensus in multi-round interactions) and Decision Opacity (AI's key judgments lack traceability). These issues stem from the absence of structured workflows and documented decision records, which Rivo aims to address.

Rivo follows a 'less is more' philosophy:

• 12 commands covering the full development lifecycle
• Zero code (no orchestration or validation scripts)
• Pure Markdown for all specs (human-readable)
• Host-agnostic (consistent operation across Claude Code and Codex CLI via bidirectional symmetry) It emphasizes explicit status management (10-state transition enum) without automated state machines, relying on manual compliance to keep workflows lightweight.

Rivo's workflow has three tiers:

1. Requirement Tier: Understand problems (commands: /rivo:roadmap for project management, /rivo:charter for product principles, /rivo:clarify for root cause analysis producing contract.md)
2. Engineering Tier: Translate to code (commands: /rivo:architect for architecture alignment, /rivo:spec for implementation specs, /rivo:code for TDD-based development)
3. Closing Tier: Learn from experience (commands: /rivo:retro for retrospective, /rivo:archive for task archiving) Each engineering command includes built-in reviews (e.g., /rivo:review-spec for specification checks, /rivo:review-code for security/quality) with loop repairs until approval.

Rivo enforces a clear directory structure:

• CHARTER.md: Product core principles (context anchor)
• CLAUDE.md: Engineering norms (code style, language rules)
• .rivo/: Contains project.yaml (single source of truth for epics/entries) and per-item docs (contract, spec, plan) Entry status transitions follow an enum: draft → clarified → claimed → ... → archived (no automated state machine; compliance is manual to maintain zero-code promise).

Suitable Scenarios:

• Complex multi-day projects (needs long-term context consistency)
• Multi-person AI-assisted collaboration (standardized workflows & audit logs)
• Quality-critical projects (multi-dimensional reviews)
• Interpretability needs (traceable decision records)

Limitations:

• Not a heavy framework (no state machines/automated checks)
• Overkill for simple one-off tasks
• Depends on host AI capabilities (file I/O, git operations, sub-agent generation)

Rivo represents a new human-AI collaboration paradigm: AI handles execution/generation, humans manage judgment/quality, and spec docs act as contracts. It turns AI tools from 'toys' into production-ready ones by providing scaffolding for complex tasks while maintaining control and traceability. As AI programming agents become more prevalent, tools like Rivo will be key to balancing AI potential with quality and accountability.