@tudeorangbiasa/sdd-multiagent-opencode 0.2.1 → 0.2.3

package/.opencode/commands/sdd-quick.md

@@ -0,0 +1,196 @@
+---
+description: Quick one-shot fix for cosmetic/config changes with CLI wrapper for deterministic checks
+agent: sdd-implementer
+---
+
+Execute a small, safe change with minimal overhead. Uses CLI wrapper for Phase 1-2 (classification, pre-flight) and Phase 4-5 (verification, ledger). LLM is only used for Phase 3 (the actual edit).
+
+## Usage
+
+```text
+/sdd-quick "fix typo: succesful -> successful"
+/sdd-quick "rename isLoading to isFetching in auth.ts"
+```
+
+## Architecture: Hybrid CLI + 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
+```
+
+Total token cost: ~200 tokens (vs ~1000 for all-LLM approach).
+
+## Phase 1: Classification
+
+### Step 1a: CLI Keyword Scan (0 tokens)
+
+Run: `sdd-quick classify "<request>"`
+
+The CLI checks for:
+- Operators: `>`, `<`, `>=`, `<=`, `==`, `===`, `!=`, `!==`, `&&`, `||`, `!`, `?:`
+- Control flow keywords: `if`, `else`, `switch`, `case`, `for`, `while`, `return`, `throw`, `try`, `catch`, `finally`
+- Contract path patterns: `**/api/**`, `**/dto/**`, `**/schema/**`, `**/types/public-api.ts`
+
+**If CLI detects blocking keywords → FAIL immediately.** Output:
+```
+aborted: Quick fix rejected — <slug>
+reason: Request contains <operator/keyword> which indicates a logic change.
+suggestion: Run `/sdd-propose "<request>"` for full workflow.
+```
+
+**If CLI detects no blocking keywords → proceed to Step 1b only if a file path was provided and the file exists.**
+
+### Step 1b: Context-Aware Classification (~50 tokens, only if needed)
+
+If the CLI found ambiguous keywords but a file path was provided, run:
+```
+sdd-quick classify "<request>" <file-path>
+```
+
+The CLI returns a prompt. Send this prompt to the LLM and get back a classification result.
+
+**If LLM says `{"safe": false}` → FAIL.** Report reason and suggest `/sdd-propose`.
+**If LLM says `{"safe": true}` → proceed to Phase 2.**
+
+## Phase 2: Pre-Flight Checks (CLI, 0 tokens)
+
+Run: `sdd-quick preflight "<request>" [file-path] [old-string] [new-string]`
+
+The CLI checks:
+1. **Lock file**: Is another SDD process active? If yes → FAIL.
+2. **Cross-file scan**: How many files reference the pattern? If > 5 → WARN (show user, ask confirmation).
+3. **String length delta**: If old/new strings provided, check delta > 20 chars or > 50% increase → WARN (UI layout risk).
+
+**If preflight FAILS → abort.**
+**If preflight PASSES → proceed to Phase 3.**
+**If preflight WARNS → show user, ask "Proceed? (yes/no)".**
+
+Before proceeding, acquire lock:
+```
+sdd-quick lock acquire "sdd-quick" "<slug>"
+```
+
+## Phase 3: Edit (LLM, ~150 tokens)
+
+### Step 3a: Generate Edit Prompt
+
+Run: `sdd-quick edit-prompt "<request>" <file-path>`
+
+The CLI reads the file and generates an optimized prompt:
+- If file < 500 lines → "Return the ENTIRE file content with the change applied."
+- If file >= 500 lines → "Use search-replace blocks: <<<SEARCH ... >>> <<<REPLACE ... >>>"
+
+### Step 3b: Apply Edit
+
+1. **Backup the file**: Copy to `<file>.sdd-quick-backup`
+2. **Send the prompt to LLM** and get the response.
+3. **Write the response** to the target file.
+   - For full-file return: write directly.
+   - For search-replace blocks: parse and apply each block.
+4. **If write fails** (parse error, etc.) → restore from backup, FAIL.
+
+## Phase 4: Post-Flight Verification (CLI, 0 tokens)
+
+### Step 4a: Verify Actual Changes
+
+Run: `sdd-quick postflight <backup-path> <target-path>`
+
+The CLI checks:
+- Was the file actually changed? If no → FAIL (nothing to commit).
+- Did the LLM add extra lines beyond the request? If > 3 extra lines → AUTO-REVERT, FAIL.
+
+### Step 4b: Run Lint and Typecheck
+
+Run: `sdd-quick lint`
+Run: `sdd-quick typecheck`
+
+**Decision table:**
+
+| Result | Action |
+|--------|--------|
+| Both pass | Continue to Phase 5 |
+| Lint fails | Auto-revert from backup, FAIL |
+| Typecheck fails | Auto-revert from backup, FAIL |
+| Neither available | WARN (project lacks safety net), continue |
+
+### Step 4c: Cleanup
+
+- Remove backup file.
+- Release lock: `sdd-quick lock release`
+
+## Phase 5: Ledger Append (CLI, 0 tokens)
+
+Run: `sdd-quick ledger append "<entry>"`
+
+Entry format:
+```markdown
+## YYYY-MM-DD HH:MM — <kebab-case-slug>
+
+- **Trigger:** `/sdd-quick "<original request>"`
+- **Files:** `<file-path>` (L<line>, L<line>)
+- **Type:** Cosmetic | Config
+- **Verification:** lint passed, typecheck passed
+- **Cross-file refs:** <count> files affected
+- **Status:** ✅ Applied | ❌ Reverted (reason)
+```
+
+The CLI handles atomic write (via temp file + rename) and automatic archiving if ledger exceeds 50 entries.
+
+## Execution Mode: Silent
+
+Do NOT report intermediate steps. Do NOT narrate your process.
+All Phase 1-4 checks must be performed silently via CLI calls.
+
+Output ONLY the final result in the format below.
+No chain of thought. No step-by-step. No "I'm now checking X".
+
+If a gate fails → output ONLY the abort message.
+If all gates pass → output ONLY the success message.
+
+## Anti-Generic Gate
+
+Before final output, verify:
+
+- [ ] Classification was done via CLI (not AI judgment).
+- [ ] Lock file was checked and cleaned up.
+- [ ] Pre-flight checks passed (or user confirmed warnings).
+- [ ] Edit was applied and post-flight verification passed.
+- [ ] Lint and typecheck were run (or project lacks them).
+- [ ] Ledger was updated atomically via CLI.
+- [ ] No logic, contract, or new files were touched.
+- [ ] No extra lines were added beyond the requested change.
+
+If any item fails, report the failure and do not claim success.
+
+## Output
+
+If successful:
+
+```markdown
+changed: Quick fix applied — <slug>
+type: Cosmetic | Config
+verified: lint + typecheck passed
+cross-file refs: <count> files
+
+Log: specs/QUICKFIX_LOG.md
+
+Next: commit the change or run `/sdd-quick` again.
+```
+
+If aborted:
+
+```markdown
+aborted: Quick fix rejected — <slug>
+reason: <specific rule that blocked it>
+suggestion: Run `/sdd-propose "<request>"` for full workflow.
+```

package/.opencode/commands/sdd-ship.md

@@ -21,6 +21,15 @@ Verify a completed change before considering it ready.
 - Do not make product code changes unless the user explicitly asks for fixes.
 - If the user asks to finalize, mark the change complete only when readiness is `yes`.
 
+## Asymmetric Verification
+
+Perform a strict audit comparing the "Test Spec" tables in `tasks.md` against the actual test files (`*.test.ts`):
+
+- **Completeness**: Ensure every row in the Test Spec table has a corresponding test case in the code.
+- **Assertion Strength**: Check for "weakening" (e.g., spec says `expect(status).toBe(401)` but code says `expect(status).toBeGreaterThan(400)`). This is a VIOLATION.
+- **Mock Accuracy**: Verify mocks match the "Mock Requirement" column in the spec.
+- **Halt on Violation**: If you find a violation, DO NOT attempt to auto-correct. Mark `ready: no` and report the specific mismatch in findings.
+
 ## Review Focus
 
 - Requirements satisfied

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.