@tudeorangbiasa/sdd-multiagent-opencode 0.2.2 → 0.3.0

package/.sdd/templates/model-profile-template.json

@@ -13,7 +13,8 @@
       "explorer": "FREE: DeepSeek v4 Flash — fast readonly exploration, token-efficient",
       "implementer": "FREE: DeepSeek v4 Flash — code generation, high token usage",
       "verifier": "FREE: Qwen3.6 Plus — multimodal for Chrome DevTools screenshots",
-      "reviewer": "FREE: MiniMax M2.5 — structured code review output"
+      "reviewer": "FREE: MiniMax M2.5 — structured code review output",
+      "quick": "FREE: Qwen3.6 Plus or DeepSeek v4 Flash — minimal prompt for small edits"
     }
   },
   "defaultPrimary": "openai/gpt-5.5",
@@ -24,6 +25,7 @@
     "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"
   }
 }

package/.sdd/templates/reasoning-profile-template.json

@@ -10,12 +10,14 @@
     "sdd-explorer": "low",
     "sdd-implementer": "medium",
     "sdd-verifier": "medium",
-    "sdd-reviewer": "medium"
+    "sdd-reviewer": "medium",
+    "sdd-quick": "low"
   },
   "commands": {
     "sdd-explore": "medium",
     "sdd-propose": "high",
     "sdd-apply": "medium",
-    "sdd-ship": "medium"
+    "sdd-ship": "medium",
+    "sdd-quick": "low"
   }
 }

package/GUIDE.md

@@ -1,21 +1,77 @@
 # SDD Multi-Agent OpenCode Guide
 
-This kit exposes one small workflow for OpenCode:
+This kit exposes five core commands for OpenCode:
 
 ```text
-/sdd-explore -> /sdd-propose -> /sdd-apply -> /sdd-ship
+/sdd-construct -> /sdd-explore -> /sdd-propose -> /sdd-apply -> /sdd-ship
+/sdd-quick (standalone for small fixes)
 ```
 
-It is inspired by spec-driven development, but it is not a port of another tool. The goal is to make OpenCode safer on real projects by separating investigation, planning, implementation, and final verification.
+It is inspired by spec-driven development and Matt Pocock's skill-driven engineering workflow. The goal is to make OpenCode safer on real projects by separating investigation, planning, implementation, and final verification — with type-aware guardrails for different project types.
 
 ## Commands
 
 | Command | Purpose | Writes Code? |
 |---------|---------|--------------|
+| `/sdd-construct` | Initialize SDD workflow for a new or existing project | Yes (config files) |
 | `/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` | Verify readiness before merge/release | No, unless explicitly asked |
+| `/sdd-quick` | Lightweight cosmetic/config fix (~200 tokens) | Yes |
+
+## One-Time Project Setup
+
+### `/sdd-construct`
+
+Run this once at the start of a project to set up the "spine" — stack detection, domain glossary, model routing, and type-specific guardrails.
+
+```text
+/sdd-construct
+/sdd-construct "e-commerce platform for digital goods"
+```
+
+**What it does:**
+
+1. **Phase 1: Stack Detection**
+   - Empty directory guard → asks user for project type
+   - Quick sniff test → classifies clear patterns (Next.js, Laravel, etc.) instantly
+   - Conditional subagent exploration → only for unclear/complex projects
+   - Three-layer fallback: explorer → direct read → user input
+
+2. **Phase 2: Grilling Session** (one question at a time)
+   - Section A: Project Vision (all types)
+   - Section B: Constraints & Preferences (all types)
+   - Section C: Model Budget (all types)
+   - Section D: Issue Tracker (all types)
+   - Section E: Domain Glossary (all types)
+   - Section F: Type-specific guardrails (conditional)
+
+3. **Phase 3: Scaffold Artifacts**
+   - `.sdd/project-profile.json`, `.sdd/model-profile.json`, `.sdd/reasoning-profile.json`
+   - `CONTEXT.md` (domain glossary)
+   - `docs/adr/0001-project-initialization.md`
+   - Type-specific artifacts (conditional):
+
+| Project Type | Artifacts |
+|-------------|-----------|
+| **frontend** | `DESIGN.md` (locked tokens), design rules in `AGENTS.md` |
+| **backend** | `API_CONTRACT.md`, `SECURITY_RULES.md` |
+| **library/sdk** | `PUBLIC_API.md`, `VERSIONING.md` |
+| **cli** | `COMMAND_STRUCTURE.md` |
+| **fullstack** | `DESIGN.md` + `API_CONTRACT.md` |
+
+4. **Phase 4: Verification** — checks all artifacts exist
+
+**Project Type Classification:**
+
+| Type | Signal Pattern | Example |
+|------|---------------|---------|
+| **frontend** | UI framework + styling + component dir, NO server | React + Tailwind + `components/` |
+| **backend** | Server framework + NO UI framework | Express, Fastify, Laravel, Django |
+| **library/sdk** | `exports` in package.json + NO entry point + NO server | Utility package, SDK |
+| **cli** | `bin` in package.json + NO server + NO UI framework | CLI tool, scaffolding tool |
+| **fullstack** | UI framework + server framework | Next.js App Router + API routes |
 
 ## Default Flow
 
@@ -61,6 +117,15 @@ specs/active/<change-id>/
 └── progress.md        optional for large changes
 ```
 
+**Test Spec Tables:** For tasks involving logic, `tasks.md` includes structured Test Spec tables:
+
+| Scenario | Input | Expected Output | Mock Requirement |
+|----------|-------|-----------------|------------------|
+| Invalid email | `email: "abc"` | `400 Bad Request` | No mock needed |
+| Valid login | `email: "a@b.c", pass: "123"` | `200 OK + token` | Mock DB query |
+
+The implementer must translate this table exactly into test code.
+
 Review these files before applying. This is the agreement point.
 
 ### `/sdd-apply`
@@ -73,6 +138,12 @@ Use this after the proposal is accepted.
 
 It reads the artifacts, implements `tasks.md`, updates checkboxes, and runs targeted verification when possible.
 
+**Test Integrity Rules:**
+- **Source of Truth**: The Test Spec table in `tasks.md` defines exact test cases
+- **No Weakening**: Forbidden from modifying assertions to make tests pass
+- **Fix Implementation, Not Test**: If a test fails, fix source code, not the test
+- **Report Mismatches**: If the Test Spec is incorrect, STOP and report it
+
 For large changes, it uses `progress.md` as a checkpoint so work can resume without relying on chat history. If tasks touch disjoint files, it can run safe batches in parallel through subagents; otherwise it runs sequentially.
 
 ### `/sdd-ship`
@@ -89,6 +160,54 @@ It audits the implementation against the artifacts and writes:
 specs/active/<change-id>/verification.md
 ```
 
+**Asymmetric Verification:**
+- **Completeness**: Every row in the Test Spec table has a corresponding test case
+- **Assertion Strength**: Detects "weakening" (e.g., spec says `toBe(401)` but code says `toBeTruthy()`)
+- **Mock Accuracy**: Verifies mocks match the spec
+- **Halt on Violation**: If a violation is found, marks `ready: no` and reports — NO auto-correction
+
+### `/sdd-quick`
+
+Use this for small, safe cosmetic/config changes — typo fixes, variable renames, config value changes.
+
+```text
+/sdd-quick "fix typo: succesful -> successful"
+/sdd-quick "rename isLoading to isFetching in auth.ts"
+/sdd-quick "change MAX_RETRIES from 3 to 5"
+```
+
+**What it does (hybrid CLI + LLM, ~200 tokens):**
+
+1. **Phase 1a**: CLI keyword scan (0 tokens) — detects operators, control flow keywords
+2. **Phase 1b**: Context-aware classification (~50 tokens) — only if ambiguous
+3. **Phase 2**: CLI pre-flight (0 tokens) — lock check, grep scan, string delta
+4. **Phase 3**: LLM edit (~150 tokens) — full file return for < 500 lines
+5. **Phase 4**: CLI post-flight (0 tokens) — actual diff, lint, typecheck, auto-revert
+6. **Phase 5**: CLI ledger append (0 tokens) — atomic write to `specs/QUICKFIX_LOG.md`
+
+**Blocked automatically** (no LLM invoked):
+- Logic changes (operators, control flow)
+- Contract boundary files (`**/api/**`, `**/dto/**`, `**/schema/**`)
+- Exported function/class/type name changes
+
+**Warns and asks confirmation:**
+- Cross-file references > 5
+- String length delta > 20 chars or > 50% increase (UI layout risk)
+- Another SDD process is active (lock file)
+
+## Example: New Project
+
+```text
+/sdd-construct "task management app for teams"
+    -> detects Next.js + TypeScript + Tailwind
+    -> classifies as: fullstack
+    -> asks: vision, constraints, model budget, issue tracker, domain terms
+    -> generates: DESIGN.md (locked tokens), API_CONTRACT.md, CONTEXT.md, ADR
+/sdd-propose auth-login "add email/password login with JWT"
+/sdd-apply auth-login
+/sdd-ship auth-login
+```
+
 ## Example: New Feature
 
 ```text
@@ -115,9 +234,24 @@ specs/active/<change-id>/verification.md
 /sdd-ship admin-ui-components
 ```
 
+## Example: Quick Fix
+
+```text
+/sdd-quick "fix typo: 'succesful' -> 'successful'"
+    -> CLI: no blocking keywords, no contract path, 1 cross-file ref
+    -> LLM: change string in src/messages.ts
+    -> CLI: lint passed, typecheck passed, ledger updated
+    -> ✅ Applied (~200 tokens)
+
+/sdd-quick "Ganti > jadi >= di validator.ts"
+    -> CLI: detected operator '>' → blocked
+    -> ❌ Abort: "Request contains operators which indicates a logic change."
+    -> Suggestion: Run `/sdd-propose "Ganti > jadi >= di validator.ts"`
+```
+
 ## Design Principles
 
-- Four commands only by default.
+- Five commands + one quick-fix command.
 - No fake flags like `--deep` or `--until-finish`.
 - No source code changes during explore/propose.
 - One change folder per unit of work.
@@ -126,3 +260,6 @@ specs/active/<change-id>/verification.md
 - Long-running apply work must checkpoint to `progress.md`.
 - Parallel execution is a capability inside `/sdd-apply`, not a separate command.
 - Verification is a first-class step, not a vague final message.
+- Type-aware scaffolding: frontend gets DESIGN.md, backend gets API_CONTRACT.md, library gets PUBLIC_API.md.
+- Test-driven: Test Spec tables in tasks.md, Test Integrity rules in apply, Asymmetric Verification in ship.
+- CLI-first for quick fixes: deterministic checks in Node.js, LLM only for the edit.

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