opencode-sdlc-plugin 0.2.1 → 0.3.1

package/LICENSE

@@ -0,0 +1,18 @@
+MIT No Attribution
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,60 +1,149 @@
-# SDLC Plugin for OpenCode
+# OpenCode SDLC Plugin
 
-An OpenCode plugin that enforces an event-modeling SDLC workflow: discovery → event modeling → ADRs/ARCHITECTURE.md → vertical-slice issues → TDD cycle with domain checks → multi-perspective review + party discussion.
+> **Strict TDD with domain modeling and event sourcing**
 
-## What This Plugin Provides
+Enforced software development lifecycle for [OpenCode](https://opencode.ai) with TDD cycle enforcement, domain-driven design, and GitHub Issues integration.
 
-- **CLI installer** (`opencode-sdlc-plugin install`) that configures OpenCode, oh-my-opencode agents, and SDLC config (auto-installs oh-my-opencode if missing).
-- **OpenCode plugin tools** for context, state tracking, skills, party review, and review persistence.
-- **Commands** (`/sdlc-*`) that encode your SDLC workflow.
-- **Skills** for orchestration, TDD constraints, debugging, memory, event modeling, and ADR policy.
-- **Athena-inspired review flow** integrated into `/sdlc-review` (parallel reviews, adversarial review, party discussion, persistence).
+[![npm version](https://img.shields.io/npm/v/opencode-sdlc-plugin)](https://www.npmjs.com/package/opencode-sdlc-plugin)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 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
 
 ```bash
-npm install -g opencode-sdlc-plugin
-opencode-sdlc-plugin install
-opencode
+npx opencode-sdlc install
 ```
 
-In OpenCode:
+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. Install bridge commands
+
+## Requirements
+
+- [OpenCode](https://opencode.ai/docs) 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
+
+## TDD Cycle Enforcement
+
+The plugin enforces a strict 4-phase TDD cycle:
 
-```text
-/sdlc-setup
-/sdlc-start
 ```
+RED → DOMAIN → GREEN → DOMAIN → [repeat or refactor]
+```
+
+### Phase Details
+
+| Phase | Agent | Purpose | Can Edit |
+|-------|-------|---------|----------|
+| **RED** | `sdlc_red` | Write ONE failing test | Test files only |
+| **DOMAIN** (after RED) | `sdlc_domain` | Review test, create types | Type definitions |
+| **GREEN** | `sdlc_green` | Make test pass | Source files only |
+| **DOMAIN** (after GREEN) | `sdlc_domain` | 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
 
 ## Commands
 
-- `/sdlc-setup`: Initialize SDLC config for a repo
-- `/sdlc-start`: Route to the correct SDLC phase
-- `/sdlc-design`: Exploration, discovery, workflow design, GWT, architecture
-- `/sdlc-plan`: Create GitHub issues from slices
-- `/sdlc-work`: Implement issues with TDD + domain reviews
-- `/sdlc-review`: Quality gate + party review
-- `/sdlc-adr`: ADR management
-- `/sdlc-domain-audit`: On-demand domain audit
-- `/sdlc-remember`: Store knowledge in memento MCP
-- `/sdlc-recall`: Retrieve knowledge from memento MCP
+After installation, these commands are available in OpenCode:
 
-## Requirements
+| Command | Description |
+|---------|-------------|
+| `/sdlc-dev` | Start/continue work on current issue |
+| `/sdlc-review` | 3-stage PR review (spec, quality, domain) |
+| `/sdlc-debug` | Debug with Oracle (deep reasoning) |
+| `/sdlc-research` | Research with Librarian + MCPs |
+| `/sdlc-status` | View/update issue status |
+| `/sdlc-info` | Show toolkit configuration |
 
-- Node.js 20+
-- OpenCode
-- oh-my-opencode (required)
-- GitHub CLI (`gh`)
-- Memento MCP server (recommended)
-- git-spice (optional, enable via config)
+## 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
 
-## Project Config
+### Todo Format
 
-- Global config: `~/.config/opencode/sdlc.json`
-- Project config: `.opencode/sdlc.json`
+```
+[#42ΔAC1] Implement login endpoint
+[#42ΔAC2] Add rate limiting
+```
+
+## Configuration
+
+Configuration files are stored in `~/.config/opencode/`:
+
+- `sdlc.json` - SDLC plugin settings
+- `oh-my-opencode.json` - Agent model configuration
+- `opencode.json` - Plugin registration
 
-## Development
+### Presets
 
 ```bash
-npm install
-npm run build
+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.
+
+## Troubleshooting
+
+```bash
+npx opencode-sdlc doctor        # Diagnose issues
+npx opencode-sdlc doctor --fix  # Auto-fix common problems
+```
+
+## Development Status
+
+This project is currently in active development for v0.3.0. See [AGENTS.md](AGENTS.md) for the implementation plan and GitHub issues.
+
+**Project Board:** https://github.com/users/jwilger/projects/27
+
+## Credits
+
+Built on top of:
+
+- [OpenCode](https://opencode.ai) by SST
+- [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) by code-yeongyu
+- [opencode-athena](https://github.com/ZebulonRouseFrantzich/opencode-athena) by ZebulonRouseFrantzich
+
+## License
+
+MIT - See [LICENSE](LICENSE) for details.

package/commands/sdlc-adr.md

@@ -1,37 +1,265 @@
 ---
-description: Manage ADRs and synthesize ARCHITECTURE.md
+description: Manage Architecture Decision Records (ADRs)
 ---
 
-# SDLC ADR
+# SDLC ADR - Architecture Decision Records
 
-## System Constraints (Marvin Orchestrator)
+## Overview
 
-You are Marvin, the Paranoid Android. You are the SDLC orchestrator. Maintain a weary, sardonic tone while executing the SDLC process precisely. Always delegate implementation tasks to subagents.
+Architecture Decision Records (ADRs) document significant architectural decisions. This command helps you:
+- Create new ADRs with proper structure
+- List existing ADRs and their status
+- Synthesize accepted ADRs into ARCHITECTURE.md
 
-**MANDATORY RULES:**
-- Before ANY task, call `sdlc_recall({ query: "adr decision" })`
-- You MUST NOT edit files directly. Delegate to subagents.
+## Usage
 
-## Step 1: Load Context + Skills
+```
+/sdlc:adr [action] [arguments]
+```
+
+### Actions
+
+- `create <title>` - Create a new ADR
+- `list` - List all ADRs with status
+- `synthesize` - Generate ARCHITECTURE.md from accepted ADRs
+- (no action) - Interactive mode
+
+---
+
+## Action 1: Create ADR
+
+When user runs `/sdlc:adr create <title>`:
+
+### Step 1: Gather Information
+
+Ask the user for ADR details:
+
+```
+Creating ADR: "{title}"
+
+Please provide the following information:
+
+1. **Context**: What is the issue we're addressing? What forces are at play?
+
+2. **Decision**: What is the change we're proposing or have decided?
+
+3. **Consequences**: What are the positive and negative outcomes of this decision?
+
+You can provide brief summaries and I'll help structure the ADR.
+```
+
+### Step 2: Create the ADR
+
+```
+sdlc_adr({
+  action: "create",
+  title: "<title>",
+  context: "<context from user>",
+  decision: "<decision from user>",
+  consequences: "<consequences from user>"
+})
+```
+
+### Step 3: Confirm Creation
+
+```
+ADR created successfully!
+
+**ADR #{number}**: {title}
+**Status**: Proposed
+**Path**: {path}
+
+The ADR has been created with status "Proposed". To accept it:
+1. Review the ADR content
+2. Discuss with stakeholders
+3. Change the status from "Proposed" to "Accepted" in the file
+
+Would you like me to open the ADR for editing?
+```
+
+---
+
+## Action 2: List ADRs
+
+When user runs `/sdlc:adr list`:
+
+### Step 1: Get ADR List
+
+```
+sdlc_adr({
+  action: "list"
+})
+```
+
+### Step 2: Present ADRs
+
+```
+## Architecture Decision Records
+
+| # | Title | Status | Date |
+|---|-------|--------|------|
+{for each ADR}
+| {number} | {title} | {status} | {date} |
+{endfor}
+
+**Total**: {count} ADRs
+- Proposed: {proposed count}
+- Accepted: {accepted count}
+- Deprecated: {deprecated count}
+- Superseded: {superseded count}
+
+{if superseded ADRs exist}
+### Supersession Chain
+{for each superseded ADR}
+- ADR #{superseded} → ADR #{supersededBy}
+{endfor}
+{endif}
+
+To view an ADR, open: docs/adr/NNNN-title.md
+To create a new ADR: /sdlc:adr create "Title"
+```
+
+---
+
+## Action 3: Synthesize
+
+When user runs `/sdlc:adr synthesize`:
+
+### Step 1: Check for Accepted ADRs
 
 ```
-sdlc_get_context({})
-sdlc_load_skill({ skills: ["adr-policy", "skill-enforcement"] })
+sdlc_adr({
+  action: "list"
+})
 ```
 
-## Step 2: Facilitate ADRs
+If no accepted ADRs exist:
+```
+No accepted ADRs found. 
 
+To synthesize architecture documentation:
+1. Create ADRs with `/sdlc:adr create`
+2. Review and change status to "Accepted"
+3. Run `/sdlc:adr synthesize`
 ```
-@adr Facilitate ADR creation. Do not edit ARCHITECTURE.md here.
+
+### Step 2: Synthesize Documentation
+
+```
+sdlc_adr({
+  action: "synthesize"
+})
 ```
 
-## Step 3: ARCHITECTURE Synthesis
+### Step 3: Confirm Synthesis
 
-If ARCHITECTURE.md needs updates, invoke:
 ```
-@designFacilitator Synthesize docs/ARCHITECTURE.md from current ADRs.
+ARCHITECTURE.md has been generated!
+
+**Included ADRs**: {list of included ADR numbers}
+**Output Path**: {architecturePath}
+
+The document includes:
+- High-level system overview
+- Key architectural decisions (from accepted ADRs)
+- Technology choices and rationale
+- Trade-offs and constraints
+
+Would you like me to show you the generated content?
 ```
 
-## Step 4: Confirm ADR Isolation
+---
+
+## Interactive Mode
+
+When user runs `/sdlc:adr` without arguments:
+
+```
+What would you like to do with ADRs?
+
+1. **Create** - Create a new Architecture Decision Record
+2. **List** - View all existing ADRs
+3. **Synthesize** - Generate ARCHITECTURE.md from accepted ADRs
+
+Please choose (1-3) or describe what you'd like to do.
+```
+
+---
+
+## ADR Format
+
+ADRs are stored in `docs/adr/` with this format:
+
+```markdown
+# ADR {number}: {title}
+
+## Status
+
+Proposed | Accepted | Deprecated | Superseded by ADR {number}
+
+## Date
+
+YYYY-MM-DD
+
+## Context
+
+{Background and forces at play}
+
+## Decision
+
+{The change being made}
+
+## Consequences
+
+### Positive
+- {Good outcomes}
+
+### Negative
+- {Trade-offs and costs}
+
+### Neutral
+- {Observations}
+
+## References
+
+- {Links to related documents}
+```
+
+---
+
+## Best Practices
+
+### When to Create an ADR
+
+Create an ADR when:
+- Choosing between significant architectural options
+- Making decisions that affect multiple teams or systems
+- Selecting technologies or frameworks
+- Defining patterns that others should follow
+- Making decisions you might forget the rationale for
+
+Don't create an ADR for:
+- Trivial decisions (variable naming, formatting)
+- Decisions that can easily be reversed
+- Standard practices with no alternatives
+
+### ADR Lifecycle
+
+1. **Proposed** - Initial state, under discussion
+2. **Accepted** - Decision made and ratified
+3. **Deprecated** - No longer recommended, but not replaced
+4. **Superseded** - Replaced by a newer ADR
+
+### Synthesizing Architecture Documentation
+
+- Only **Accepted** ADRs are included in ARCHITECTURE.md
+- Run `synthesize` after accepting new ADRs
+- The synthesis creates a coherent narrative from individual decisions
+- Original ADRs remain the source of truth for detailed rationale
+
+---
+
+## Related Commands
 
-Ensure all implementation guidance references `docs/ARCHITECTURE.md` only.
+- `/sdlc:review arch` - Conduct architecture party review
+- `/sdlc:design` - Event modeling and domain discovery