OpenCode SDLC Plugin

Strict TDD with domain modeling and event sourcing

Enforced software development lifecycle for OpenCode with TDD cycle enforcement, domain-driven design, and GitHub Issues integration.

What is OpenCode SDLC?

OpenCode SDLC Plugin enforces strict software development practices through automated tooling:

• TDD Cycle Enforcement - RED → DOMAIN → GREEN → DOMAIN with strict file ownership
• Domain Modeling - Type-driven development with domain agent veto power
• Event Modeling - Optional planning methodology for event-sourced systems
• GitHub Issues Integration - Work items tracked via GitHub Issues and project boards
• Orchestrator-Only Pattern - Main conversation delegates all file writes to agents

| Traditional Development | With SDLC Plugin | |------------------------|------------------| | Manual TDD discipline | Enforced TDD cycle | | Domain violations slip through | Domain agent veto power | | Mixed test/source edits | Strict file ownership | | Manual issue tracking | Automated GitHub sync | | Ad-hoc code reviews | 3-stage PR review |

Quick Start

npx opencode-sdlc install

The interactive installer will:

1. Ask about your LLM subscriptions (Claude, OpenAI, Google, GitHub Copilot)
2. Configure agent models for TDD roles
3. Set up GitHub integration
4. Configure Marvin modes

Requirements

• OpenCode 1.0.132+
• Node.js 20+
• GitHub CLI (gh) with authentication
• One or more LLM subscriptions:
  • Claude Pro/Max (recommended)
  • ChatGPT Plus/Pro
  • Google/Gemini
  • GitHub Copilot

Marvin: The Orchestrator

Marvin is the unified orchestrator that coordinates all development work. Instead of separate commands, Marvin operates in different modes that you switch between using the Tab key in OpenCode.

Available Modes

| Mode | Purpose | Key Activities | |------|---------|----------------| | Build | Implementation | TDD cycle, code changes via subagents | | Discover | Exploration | Problem understanding, user journeys, assumptions | | Model | Event Modeling | Event discovery, workflow design, GWT specs | | Architect | Design Decisions | ADRs, technology evaluation, tradeoffs | | PRD | Specifications | User stories, acceptance criteria, requirements | | PM | Project Management | Issues, branches, PRs, board management |

Mode Switching

Press Tab in OpenCode to switch modes. Marvin will:

• Suggest the appropriate mode for your request
• Carry context between modes when relevant
• Enforce mode-specific constraints (e.g., Build mode cannot skip TDD)

User: I need to add user authentication

Marvin (Discover): Let me understand the requirements first...
  - Who are the users?
  - What authentication methods needed?

[Tab → Model mode]

Marvin (Model): Let me design the events...
  - UserRegistered, UserLoggedIn, TokenRefreshed

[Tab → Build mode]

Marvin (Build): Starting TDD cycle for AC1...
  - RED: Writing failing test for registration
  - DOMAIN: Creating Email, Password types
  - GREEN: Implementing registration service

TDD Cycle Enforcement

The plugin enforces a strict 4-phase TDD cycle in Build mode:

RED → DOMAIN → GREEN → DOMAIN → [repeat or refactor]

Phase Details

| Phase | Agent | Purpose | Can Edit | |-------|-------|---------|----------| | RED | Red Agent | Write ONE failing test | Test files only | | DOMAIN (after RED) | Domain Agent | Review test, create types | Type definitions | | GREEN | Green Agent | Make test pass | Source files only | | DOMAIN (after GREEN) | Domain Agent | Verify domain integrity | Type definitions |

Domain Agent Veto Power

The domain agent can block workflow for:

• Primitive obsession - Using String instead of Email
• Structural types - Using NonEmptyString instead of UserName
• Invalid states representable - Using boolean flags instead of enum variants
• Parse-don't-validate violations - Checking email in business logic instead of at boundary

File Ownership

In Build mode, the orchestrator cannot directly edit files. All changes go through specialized subagents:

| Agent | Can Edit | Cannot Edit | |-------|----------|-------------| | Red Agent | *.test.*, *.spec.* | Source files | | Green Agent | Source files | Test files | | Domain Agent | Type definitions | Tests, implementation |

GitHub Issues Integration

Work items are tracked via GitHub Issues instead of local files:

• Issues are the source of truth
• Acceptance criteria become todos
• Todos sync back to issue checkboxes
• Project board columns track status

Todo Format

[#42ΔAC1] Implement login endpoint
[#42ΔAC2] Add rate limiting

Todos automatically sync with issue body checkboxes when marked complete.

Configuration

Configuration files are stored in ~/.config/opencode/:

• sdlc.json - SDLC plugin settings
• oh-my-opencode.json - Agent model configuration
• opencode.json - Plugin registration

Presets

npx opencode-sdlc install --preset minimal        # Basic TDD, standard git
npx opencode-sdlc install --preset standard       # TDD + review + memento
npx opencode-sdlc install --preset strict-tdd     # Full TDD + mutation testing
npx opencode-sdlc install --preset event-modeling # Standard + event modeling

Project Overrides

Create .opencode/sdlc.json in your project root to override global settings.

CLI Commands

npx opencode-sdlc install         # Install or reconfigure
npx opencode-sdlc upgrade         # Upgrade to latest version
npx opencode-sdlc upgrade --check # Check for updates without installing
npx opencode-sdlc doctor          # Diagnose issues
npx opencode-sdlc doctor --fix    # Auto-fix common problems
npx opencode-sdlc info            # Show current configuration
npx opencode-sdlc uninstall       # Remove SDLC plugin

Troubleshooting

npx opencode-sdlc doctor        # Diagnose issues
npx opencode-sdlc doctor --fix  # Auto-fix common problems

Common issues:

• "No LLM provider configured" - Run installer and enable at least one subscription
• "GitHub CLI not authenticated" - Run gh auth login
• "oh-my-opencode not installed" - Run npx opencode-sdlc doctor --fix

Development Status

This project is in active development for v1.0.0. See AGENTS.md for architecture details.

Project Board: https://github.com/users/jwilger/projects/27

Migration from v0.x

If you're upgrading from v0.x (which used bridge commands like /sdlc-dev), see MIGRATING-TO-V1.md for migration instructions.

Quick Migration Reference

| Old Command | New Approach | |-------------|--------------| | /sdlc-dev | Build mode (Tab) | | /sdlc-debug | Build mode + invoke Oracle | | /sdlc-research | Discover mode | | /sdlc-design | Model or Architect mode | | /sdlc-info | npx opencode-sdlc info | | /sdlc-status | PM mode |

Credits

Built on top of:

• OpenCode by SST
• oh-my-opencode by code-yeongyu
• opencode-athena by ZebulonRouseFrantzich

License

MIT - See LICENSE for details.