@tudeorangbiasa/sdd-multiagent-opencode 0.2.2 → 0.2.3

package/README.md

@@ -1,8 +1,8 @@
 # SDD Multi-Agent OpenCode
 
-Spec-Driven Development workflow kit for OpenCode with four core commands, multi-agent support, and configurable model routing.
+Spec-Driven Development workflow kit for OpenCode with five core commands, CLI wrappers, multi-agent orchestration, and configurable model routing.
 
-Inspired by [spec-kit-command-cursor](https://github.com/madebyaris/spec-kit-command-cursor), rebuilt from scratch for OpenCode's multi-agent architecture.
+Inspired by [spec-kit-command-cursor](https://github.com/madebyaris/spec-kit-command-cursor) and [mattpocock/skills](https://github.com/mattpocock/skills), rebuilt from scratch for OpenCode's multi-agent architecture.
 
 ## Layering
 
@@ -11,7 +11,7 @@ This repo is the **SDD workflow layer**. For base agent behavior, CLI-first scaf
 ```txt
 opencode-agent-rules        # base behavior + context/compaction policy
         ↓
-sdd-multiagent-opencode     # SDD commands, agents, skills, templates
+sdd-multiagent-opencode     # SDD commands, agents, skills, templates, CLI wrappers
         ↓
 external UI skills          # impeccable, taste, nothing-design, etc.
 ```
@@ -26,19 +26,20 @@ external UI skills          # impeccable, taste, nothing-design, etc.
 | **Web Research** | Cursor web search | `exa_web_search_exa` |
 | **Visual Verification** | N/A | Chrome DevTools + Qwen (image-capable) |
 | **Hooks** | `hooks.json` | Plugin JS/TS with event system |
-| **Commands** | 15+ slash commands | 4 core commands: explore, propose, apply, ship |
-| **Cost** | Per-token billing | Free-tier optimized with paid model routing |
+| **Commands** | 15+ slash commands | 5 core commands: construct, propose, apply, ship, quick |
+| **Cost** | Per-token billing | Free-tier optimized with paid model routing + CLI wrappers |
 
 ## Multi-Agent Architecture
 
 | Agent | Default Model | Role |
 |-------|--------------|------|
 | **sdd-orchestrator** | configurable | DAG scheduling, conflict detection, deadlock handling |
-| **sdd-planner** | configurable | Architecture design, technical planning |
+| **sdd-planner** | configurable | Architecture design, technical planning, project construction |
 | **sdd-explorer** | configurable | Codebase discovery (readonly) |
 | **sdd-implementer** | configurable | Code generation (high token usage) |
 | **sdd-verifier** | configurable | Completeness check + visual/UI verification (Chrome DevTools) |
 | **sdd-reviewer** | configurable | Code review (security, performance, spec compliance) |
+| **sdd-quick** | configurable | Small cosmetic/config edits (~200 tokens via CLI wrapper) |
 
 **All models are configurable** via `.sdd/model-profile.json`. Edit this file to change which model each agent uses. See [Model Settings](#model-settings) below.
 
@@ -63,7 +64,7 @@ To pin a specific version:
 ```json
 {
   "plugin": [
-    "@tudeorangbiasa/sdd-multiagent-opencode@0.2.0"
+    "@tudeorangbiasa/sdd-multiagent-opencode@0.2.2"
   ]
 }
 ```
@@ -103,13 +104,15 @@ See [GUIDE.md](GUIDE.md) for the practical command flow.
 Default workflow:
 
 ```text
-/sdd-explore   # investigate unclear ideas, bugs, or code areas; no code changes
-/sdd-propose   # create proposal.md, spec.md, design.md, tasks.md; no code changes
-/sdd-apply     # implement an approved change
-/sdd-ship      # final verification and readiness review
+/sdd-construct  # initialize SDD workflow for a new or existing project (one-time)
+/sdd-explore    # investigate unclear ideas, bugs, or code areas; no code changes
+/sdd-propose    # create proposal.md, spec.md, design.md, tasks.md; no code changes
+/sdd-apply      # implement an approved change
+/sdd-ship       # final verification and readiness review
+/sdd-quick      # lightweight cosmetic/config fix (~200 tokens via CLI wrapper)
 ```
 
-Most work starts with `/sdd-propose`, then `/sdd-apply`, then `/sdd-ship`. Use `/sdd-explore` first only when the problem is unclear.
+Most work starts with `/sdd-propose`, then `/sdd-apply`, then `/sdd-ship`. Use `/sdd-explore` first only when the problem is unclear. Use `/sdd-construct` once per project to set up the spine.
 
 ## Model Settings
 
@@ -211,7 +214,7 @@ Models available at no cost via OpenCode Zen. Run `opencode models opencode | gr
 | DeepSeek V4 Flash Free | `opencode/deepseek-v4-flash-free` | Explorer, Implementer | Code generation |
 | MiniMax M2.5 Free | `opencode/minimax-m2.5-free` | Reviewer, Compaction | Structured output |
 | Nemotron 3 Super Free | `opencode/nemotron-3-super-free` | Explorer | NVIDIA model, 1M context |
-| Qwen3.6 Plus Free | `opencode/qwen3.6-plus-free` | Verifier, General | Multimodal support |
+| Qwen3.6 Plus Free | `opencode/qwen3.6-plus-free` | Verifier, General, Quick fix | Multimodal support |
 
 ⚠️ Free models are limited-time offers and may be removed or rotated without notice. Not recommended for production SDD workflows. Use `opencode models opencode | grep "free"` to verify what's currently available.
 
@@ -234,7 +237,8 @@ Recommended starting configuration (orchestrator/planner use OpenAI GPT 5.5, oth
     "sdd-explorer": "opencode/deepseek-v4-flash-free",
     "sdd-implementer": "opencode/deepseek-v4-flash-free",
     "sdd-verifier": "opencode/qwen3.6-plus-free",
-    "sdd-reviewer": "opencode/minimax-m2.5-free"
+    "sdd-reviewer": "opencode/minimax-m2.5-free",
+    "sdd-quick": "opencode/qwen3.6-plus-free"
   }
 }
 ```
@@ -251,7 +255,8 @@ Recommended starting configuration (orchestrator/planner use OpenAI GPT 5.5, oth
     "sdd-explorer": "opencode/deepseek-v4-flash-free",
     "sdd-implementer": "opencode/deepseek-v4-flash-free",
     "sdd-verifier": "opencode-go/kimi-k2.6",
-    "sdd-reviewer": "opencode/minimax-m2.5-free"
+    "sdd-reviewer": "opencode/minimax-m2.5-free",
+    "sdd-quick": "opencode-go/qwen3.6-plus"
   }
 }
 ```
@@ -263,6 +268,7 @@ Recommended starting configuration (orchestrator/planner use OpenAI GPT 5.5, oth
 - **Implementer** → DeepSeek free: code generation, handles high token usage
 - **Verifier** → Qwen3.6 Plus free: multimodal for Chrome DevTools screenshots
 - **Reviewer** → MiniMax M2.5 free: structured code review output
+- **Quick** → Qwen3.6 Plus free: minimal prompt for small cosmetic/config edits (~200 tokens)
 
 `.opencode/plugins/sdd-model-router.js` reads this file at OpenCode startup and applies the model settings. **Restart OpenCode after editing it.**
 
@@ -286,7 +292,8 @@ Default routing:
     "sdd-orchestrator": "high",
     "sdd-planner": "high",
     "sdd-implementer": "medium",
-    "sdd-reviewer": "medium"
+    "sdd-reviewer": "medium",
+    "sdd-quick": "low"
   }
 }
 ```
@@ -316,6 +323,7 @@ Merge the `agent` and `permission` sections from `opencode.json` into your proje
 See [GUIDE.md](GUIDE.md) for the practical flow.
 
 ```text
+/sdd-construct                              # one-time project initialization
 /sdd-propose auth-reset "add secure password reset by email"
 /sdd-apply auth-reset
 /sdd-ship auth-reset
@@ -327,14 +335,23 @@ If the problem is unclear, start with exploration:
 /sdd-explore "admin UI feels messy, find reusable component opportunities"
 ```
 
+For small cosmetic fixes:
+
+```text
+/sdd-quick "fix typo: succesful -> successful"
+/sdd-quick "rename isLoading to isFetching in auth.ts"
+```
+
 ## Commands
 
-| Command | Purpose | Writes Code? |
-|---------|---------|--------------|
-| `/sdd-explore` | Investigate unclear ideas, bugs, or code areas | No |
-| `/sdd-propose` | Create one focused change plan | No |
-| `/sdd-apply` | Implement an approved change | Yes |
-| `/sdd-ship` | Final verification and readiness review | No, unless explicitly asked |
+| Command | Purpose | Writes Code? | Token Cost |
+|---------|---------|--------------|------------|
+| `/sdd-construct` | Initialize SDD workflow for a project | Yes (config files) | ~500-1000 |
+| `/sdd-explore` | Investigate unclear ideas, bugs, or code areas | No | ~200-500 |
+| `/sdd-propose` | Create one focused change plan | No | ~300-800 |
+| `/sdd-apply` | Implement an approved change | Yes | ~500-5000 |
+| `/sdd-ship` | Final verification and readiness review | No, unless explicitly asked | ~200-500 |
+| `/sdd-quick` | Lightweight cosmetic/config fix | Yes | ~200 |
 
 ## Project Structure
 
@@ -348,10 +365,12 @@ If the problem is unclear, start with exploration:
 │   ├── sdd-verifier.md       # Completeness and UI verification
 │   └── sdd-reviewer.md       # Final review and readiness checks
 ├── commands/
+│   ├── sdd-construct.md      # /sdd-construct
 │   ├── sdd-explore.md        # /sdd-explore
 │   ├── sdd-propose.md        # /sdd-propose
 │   ├── sdd-apply.md          # /sdd-apply
-│   └── sdd-ship.md           # /sdd-ship
+│   ├── sdd-ship.md           # /sdd-ship
+│   └── sdd-quick.md          # /sdd-quick
 └── skills/
     ├── sdd-research/SKILL.md
     ├── sdd-planning/SKILL.md
@@ -361,6 +380,8 @@ If the problem is unclear, start with exploration:
 .sdd/
 ├── config.json               # Project configuration
 ├── project-profile.json      # Stack and skill routing config
+├── model-profile.json        # Model routing per agent
+├── reasoning-profile.json    # Reasoning effort per agent/command
 └── templates/                # Document templates
     ├── proposal-template.md
     ├── spec-template.md
@@ -369,33 +390,79 @@ If the problem is unclear, start with exploration:
     ├── progress-template.md
     └── verification-template.md
 
+bin/
+├── sdd-opencode.js           # Main installer CLI
+└── sdd-quick.js              # Quick fix CLI wrapper (deterministic checks)
+
 specs/
-└── active/
-    └── <change-id>/
-        ├── proposal.md
-        ├── spec.md
-        ├── design.md
-        ├── tasks.md
-        ├── progress.md
-        └── verification.md
+├── active/
+│   └── <change-id>/
+│       ├── proposal.md
+│       ├── spec.md
+│       ├── design.md
+│       ├── tasks.md
+│       ├── progress.md
+│       └── verification.md
+├── QUICKFIX_LOG.md           # Ledger for /sdd-quick changes
+└── QUICKFIX_LOG_ARCHIVE.md   # Archived ledger entries
 ```
 
 ## Workflows
 
-Most changes use:
+### New Project Setup
+
+```text
+/sdd-construct  # one-time: detect stack, grill vision, scaffold config, create CONTEXT.md
+```
+
+### Feature Development
 
 ```text
 /sdd-propose -> /sdd-apply -> /sdd-ship
 ```
 
-Unclear changes use:
+### Unclear Changes
 
 ```text
 /sdd-explore -> /sdd-propose -> /sdd-apply -> /sdd-ship
 ```
 
+### Quick Fixes
+
+```text
+/sdd-quick "fix typo in error message"  # ~200 tokens, CLI-verified
+```
+
 This kit intentionally avoids fake CLI flags such as `--deep` or `--until-finish`. If deeper research or parallel execution is needed, describe that in normal language and let the agent plan it explicitly.
 
+## CLI Wrapper: `/sdd-quick` Architecture
+
+The `/sdd-quick` command uses a **hybrid CLI + LLM** architecture to minimize token cost (~200 tokens vs ~1000 for all-LLM):
+
+```
+CLI (0 tokens) → Phase 1a: Keyword scan → PASS/FAIL
+  ↓ (if ambiguous)
+LLM (~50 tokens) → Phase 1b: Context-aware classification
+  ↓
+CLI (0 tokens) → Phase 2: Pre-flight (lock, grep, string delta)
+  ↓
+LLM (~150 tokens) → Phase 3: Edit (full file return for < 500 lines)
+  ↓
+CLI (0 tokens) → Phase 4: Post-flight (actual diff, lint, typecheck, auto-revert)
+  ↓
+CLI (0 tokens) → Phase 5: Atomic ledger append
+```
+
+The CLI wrapper (`bin/sdd-quick.js`) handles deterministic checks:
+- **Phase 1a**: Regex-based keyword scan (operators, control flow, contract paths)
+- **Phase 2**: Lock file management, cross-file grep scan, string length delta
+- **Phase 4**: Post-flight verification — actual diff check, lint/typecheck, auto-revert
+- **Phase 5**: Atomic ledger append via temp file + rename, automatic archiving
+
+The LLM is only invoked for:
+- **Phase 1b**: Context-aware classification (if keywords found in comments/strings)
+- **Phase 3**: The actual edit (full file return or search-replace blocks)
+
 ## Tools Integration
 
 ### codebase-memory-mcp