@tudeorangbiasa/sdd-multiagent-opencode 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/.opencode/commands/sdd-construct.md +693 -0
  2. package/.opencode/commands/sdd-quick.md +136 -105
  3. package/.sdd/templates/model-profile-template.json +4 -2
  4. package/.sdd/templates/reasoning-profile-template.json +4 -2
  5. package/GUIDE.md +141 -4
  6. package/README.md +100 -33
  7. package/bin/sdd-quick.js +607 -0
  8. package/package.json +4 -3
package/.opencode/commands/sdd-quick.md CHANGED
@@ -1,9 +1,9 @@
1
1
  ---
2
- description: Quick one-shot fix for cosmetic/config changes with lightweight verification
2
+ description: Quick one-shot fix for cosmetic/config changes with CLI wrapper for deterministic checks
3
3
  agent: sdd-implementer
4
4
  ---
5
5
 
6
- Execute a small, safe change with minimal overhead. No full spec artifacts required.
6
+ 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).
7
7
 
8
8
  ## Usage
9
9
 
@@ -12,138 +12,169 @@ Execute a small, safe change with minimal overhead. No full spec artifacts requi
12
12
  /sdd-quick "rename isLoading to isFetching in auth.ts"
13
13
  ```
14
14
 
15
- ## Phase 1: Rule-Based Change Classification
16
-
17
- Do NOT guess the change type. Classify using these deterministic rules, evaluated in order. The first matching rule wins.
18
-
19
- ### Force → CONTRACT (❌ Abort → suggest `/sdd-propose`)
20
- - Change to any exported function, class, interface, or type name
21
- - Change to any file matching: `**/api/**`, `**/dto/**`, `**/schema/**`, `**/types/public-api.ts`, `**/graphql/types.ts`
22
- - Change to function signature (add/remove/rename parameter)
23
- - Change to any file explicitly marked as `@public` or `@api` in JSDoc
24
-
25
- ### Force → LOGIC (❌ Abort → suggest `/sdd-propose`)
26
- - ANY change to operators: `>`, `<`, `>=`, `<=`, `==`, `===`, `!=`, `!==`, `&&`, `||`, `!`, `?:`
27
- - ANY change to control flow keywords: `if`, `else`, `switch`, `case`, `for`, `while`, `return`, `throw`, `try`, `catch`, `finally`
28
- - ANY change to a condition expression or boolean logic
29
- - ANY change to calculation or math expression
30
- - Adding or removing a function call
31
- - Changing a function's return value
32
-
33
- ### Force → CONFIG (⚠️ Allowed with warning)
34
- - Change to constant value, env var, feature flag, or config file (`*.config.*`, `.env`, `*.json`)
35
- - Change to a string that is NOT rendered in a UI component
36
-
37
- ### Default → COSMETIC (✅ Allowed)
38
- - Typo fix in string literal or comment
39
- - Whitespace or formatting change
40
- - Internal variable rename (not exported)
41
- - Import reordering or unused import removal
42
- - Dead code removal
43
- - Comment addition or update
44
-
45
- If the change matches CONTRACT or LOGIC, STOP immediately. Do not proceed. Report why and suggest `/sdd-propose`.
46
-
47
- ## Phase 2: Pre-Flight Checks
48
-
49
- ### Lock File Check
50
- 1. Check if `specs/.sdd-lock` exists.
51
- 2. If it exists:
52
- - Read the PID from the lock file.
53
- - Check if that process is still running (`ps -p <PID>` or equivalent).
54
- - If PID is alive → Warn: "Another SDD process is active. Proceed anyway? (yes/no)"
55
- - If PID is dead → Remove stale lock and continue.
56
- 3. If no lock exists → Create `specs/.sdd-lock` with current PID and command name.
57
-
58
- ### Cross-File Impact Scan
59
- 1. Identify the symbol, string, or pattern that will change.
60
- 2. Run a project-wide grep for that pattern.
61
- 3. Count references:
62
- - ≤ 5 references → ✅ Continue
63
- - > 5 references → ⚠️ Flag as "Ripple Risk", show user the affected files, ask for confirmation before proceeding.
64
-
65
- ### String Length Check (for string changes only)
66
- 1. Calculate the length delta: `|new_length - old_length|`
67
- 2. Calculate percentage change: `delta / old_length * 100`
68
- 3. If delta > 20 characters OR percentage increase > 50%:
69
- - Flag as "UI Layout Risk"
70
- - Check if the string is in a UI component file (`.tsx`, `.vue`, `.jsx`, `.svelte`)
71
- - If in UI component → Require explicit user confirmation before proceeding
72
- 4. If the string is in a non-UI file (`.ts` logic, config, etc.) → Allow without flag
73
-
74
- ## Phase 3: Execute Change
75
-
76
- - Make the smallest possible change that satisfies the request.
77
- - Do NOT touch any file beyond what is strictly necessary.
78
- - Do NOT create new files.
79
- - Do NOT refactor or "improve" surrounding code.
80
- - Do NOT change logic, only what was explicitly requested.
81
-
82
- ## Phase 4: Verification
83
-
84
- ### Mandatory Checks
85
- Run the project's available verification commands. Check `package.json` scripts or equivalent:
86
-
87
- 1. **Lint**: `npm run lint` (or `pnpm lint`, `yarn lint`, etc.)
88
- 2. **Typecheck**: `npm run typecheck` (or `tsc --noEmit`, `vue-tsc`, etc.)
89
-
90
- ### Decision Table
15
+ ## Architecture: Hybrid CLI + LLM
16
+
17
+ ```
18
+ CLI (0 tokens) → Phase 1a: Keyword scan → PASS/FAIL
19
+ ↓ (if ambiguous)
20
+ LLM (~50 tokens) → Phase 1b: Context-aware classification
21
+ ↓
22
+ CLI (0 tokens) → Phase 2: Pre-flight (lock, grep, string delta)
23
+ ↓
24
+ LLM (~150 tokens) → Phase 3: Edit (full file return for < 500 lines)
25
+ ↓
26
+ CLI (0 tokens) → Phase 4: Post-flight (actual diff, lint, typecheck, auto-revert)
27
+ ↓
28
+ CLI (0 tokens) → Phase 5: Atomic ledger append
29
+ ```
30
+
31
+ Total token cost: ~200 tokens (vs ~1000 for all-LLM approach).
32
+
33
+ ## Phase 1: Classification
34
+
35
+ ### Step 1a: CLI Keyword Scan (0 tokens)
36
+
37
+ Run: `sdd-quick classify "<request>"`
38
+
39
+ The CLI checks for:
40
+ - Operators: `>`, `<`, `>=`, `<=`, `==`, `===`, `!=`, `!==`, `&&`, `||`, `!`, `?:`
41
+ - Control flow keywords: `if`, `else`, `switch`, `case`, `for`, `while`, `return`, `throw`, `try`, `catch`, `finally`
42
+ - Contract path patterns: `**/api/**`, `**/dto/**`, `**/schema/**`, `**/types/public-api.ts`
43
+
44
+ **If CLI detects blocking keywords → FAIL immediately.** Output:
45
+ ```
46
+ aborted: Quick fix rejected — <slug>
47
+ reason: Request contains <operator/keyword> which indicates a logic change.
48
+ suggestion: Run `/sdd-propose "<request>"` for full workflow.
49
+ ```
50
+
51
+ **If CLI detects no blocking keywords → proceed to Step 1b only if a file path was provided and the file exists.**
52
+
53
+ ### Step 1b: Context-Aware Classification (~50 tokens, only if needed)
54
+
55
+ If the CLI found ambiguous keywords but a file path was provided, run:
56
+ ```
57
+ sdd-quick classify "<request>" <file-path>
58
+ ```
59
+
60
+ The CLI returns a prompt. Send this prompt to the LLM and get back a classification result.
61
+
62
+ **If LLM says `{"safe": false}` → FAIL.** Report reason and suggest `/sdd-propose`.
63
+ **If LLM says `{"safe": true}` → proceed to Phase 2.**
64
+
65
+ ## Phase 2: Pre-Flight Checks (CLI, 0 tokens)
66
+
67
+ Run: `sdd-quick preflight "<request>" [file-path] [old-string] [new-string]`
68
+
69
+ The CLI checks:
70
+ 1. **Lock file**: Is another SDD process active? If yes → FAIL.
71
+ 2. **Cross-file scan**: How many files reference the pattern? If > 5 → WARN (show user, ask confirmation).
72
+ 3. **String length delta**: If old/new strings provided, check delta > 20 chars or > 50% increase → WARN (UI layout risk).
73
+
74
+ **If preflight FAILS → abort.**
75
+ **If preflight PASSES → proceed to Phase 3.**
76
+ **If preflight WARNS → show user, ask "Proceed? (yes/no)".**
77
+
78
+ Before proceeding, acquire lock:
79
+ ```
80
+ sdd-quick lock acquire "sdd-quick" "<slug>"
81
+ ```
82
+
83
+ ## Phase 3: Edit (LLM, ~150 tokens)
84
+
85
+ ### Step 3a: Generate Edit Prompt
86
+
87
+ Run: `sdd-quick edit-prompt "<request>" <file-path>`
88
+
89
+ The CLI reads the file and generates an optimized prompt:
90
+ - If file < 500 lines → "Return the ENTIRE file content with the change applied."
91
+ - If file >= 500 lines → "Use search-replace blocks: <<<SEARCH ... >>> <<<REPLACE ... >>>"
92
+
93
+ ### Step 3b: Apply Edit
94
+
95
+ 1. **Backup the file**: Copy to `<file>.sdd-quick-backup`
96
+ 2. **Send the prompt to LLM** and get the response.
97
+ 3. **Write the response** to the target file.
98
+ - For full-file return: write directly.
99
+ - For search-replace blocks: parse and apply each block.
100
+ 4. **If write fails** (parse error, etc.) → restore from backup, FAIL.
101
+
102
+ ## Phase 4: Post-Flight Verification (CLI, 0 tokens)
103
+
104
+ ### Step 4a: Verify Actual Changes
105
+
106
+ Run: `sdd-quick postflight <backup-path> <target-path>`
107
+
108
+ The CLI checks:
109
+ - Was the file actually changed? If no → FAIL (nothing to commit).
110
+ - Did the LLM add extra lines beyond the request? If > 3 extra lines → AUTO-REVERT, FAIL.
111
+
112
+ ### Step 4b: Run Lint and Typecheck
113
+
114
+ Run: `sdd-quick lint`
115
+ Run: `sdd-quick typecheck`
116
+
117
+ **Decision table:**
118
+
91
119
  | Result | Action |
92
120
  |--------|--------|
93
- | Both pass | ✅ Continue to Phase 5 |
94
- | Lint fails | ❌ Auto-revert all changes, report failure |
95
- | Typecheck fails | ❌ Auto-revert all changes, report failure |
96
- | Test fails (if run) | ⚠️ Check if failure is pre-existing or caused by this change. If caused by this change → auto-revert. If pre-existing → allow with warning. |
97
-
98
- If the project has NO lint or typecheck script → ❌ Reject, suggest `/sdd-propose` (project lacks safety net for quick changes).
121
+ | Both pass | Continue to Phase 5 |
122
+ | Lint fails | Auto-revert from backup, FAIL |
123
+ | Typecheck fails | Auto-revert from backup, FAIL |
124
+ | Neither available | WARN (project lacks safety net), continue |
99
125
 
100
- ## Phase 5: Atomic Ledger Append
126
+ ### Step 4c: Cleanup
101
127
 
102
- Do NOT create individual files per change. Append to a single ledger file.
128
+ - Remove backup file.
129
+ - Release lock: `sdd-quick lock release`
103
130
 
104
- ### Ledger File: `specs/QUICKFIX_LOG.md`
131
+ ## Phase 5: Ledger Append (CLI, 0 tokens)
105
132
 
106
- Format for each entry:
133
+ Run: `sdd-quick ledger append "<entry>"`
107
134
 
135
+ Entry format:
108
136
  ```markdown
109
137
  ## YYYY-MM-DD HH:MM — <kebab-case-slug>
110
138
 
111
139
  - **Trigger:** `/sdd-quick "<original request>"`
112
140
  - **Files:** `<file-path>` (L<line>, L<line>)
113
141
  - **Type:** Cosmetic | Config
114
- - **Verification:** `npm run lint` passed, `npm run typecheck` passed
115
- - **Cross-file refs:** <count> files affected (list if > 3)
142
+ - **Verification:** lint passed, typecheck passed
143
+ - **Cross-file refs:** <count> files affected
116
144
  - **Status:** ✅ Applied | ❌ Reverted (reason)
117
145
  ```
118
146
 
119
- ### Atomic Write Procedure
120
- 1. Read current content of `specs/QUICKFIX_LOG.md` (create if not exists, with header `# Quick Change Log`)
121
- 2. Append new entry at the END of the file
122
- 3. Write to temp file: `specs/QUICKFIX_LOG.md.tmp`
123
- 4. Atomic rename: replace `specs/QUICKFIX_LOG.md` with temp file
124
- 5. Remove `specs/.sdd-lock`
147
+ The CLI handles atomic write (via temp file + rename) and automatic archiving if ledger exceeds 50 entries.
148
+
149
+ ## Execution Mode: Silent
150
+
151
+ Do NOT report intermediate steps. Do NOT narrate your process.
152
+ All Phase 1-4 checks must be performed silently via CLI calls.
153
+
154
+ Output ONLY the final result in the format below.
155
+ No chain of thought. No step-by-step. No "I'm now checking X".
125
156
 
126
- ### Ledger Maintenance
127
- If the ledger exceeds 50 entries:
128
- - Move the oldest 25 entries to `specs/QUICKFIX_LOG_ARCHIVE.md`
129
- - Keep only the most recent 25 entries in the main ledger
157
+ If a gate fails → output ONLY the abort message.
158
+ If all gates pass → output ONLY the success message.
130
159
 
131
160
  ## Anti-Generic Gate
132
161
 
133
162
  Before final output, verify:
134
163
 
135
- - [ ] Change type was classified using deterministic rules, not AI judgment.
164
+ - [ ] Classification was done via CLI (not AI judgment).
136
165
  - [ ] Lock file was checked and cleaned up.
137
- - [ ] Cross-file scan was performed.
138
- - [ ] Lint and typecheck were run and passed.
139
- - [ ] Ledger was updated atomically.
166
+ - [ ] Pre-flight checks passed (or user confirmed warnings).
167
+ - [ ] Edit was applied and post-flight verification passed.
168
+ - [ ] Lint and typecheck were run (or project lacks them).
169
+ - [ ] Ledger was updated atomically via CLI.
140
170
  - [ ] No logic, contract, or new files were touched.
171
+ - [ ] No extra lines were added beyond the requested change.
141
172
 
142
173
  If any item fails, report the failure and do not claim success.
143
174
 
144
175
  ## Output
145
176
 
146
- End with:
177
+ If successful:
147
178
 
148
179
  ```markdown
149
180
  changed: Quick fix applied — <slug>
package/.sdd/templates/model-profile-template.json CHANGED
@@ -13,7 +13,8 @@
13
13
  "explorer": "FREE: DeepSeek v4 Flash — fast readonly exploration, token-efficient",
14
14
  "implementer": "FREE: DeepSeek v4 Flash — code generation, high token usage",
15
15
  "verifier": "FREE: Qwen3.6 Plus — multimodal for Chrome DevTools screenshots",
16
- "reviewer": "FREE: MiniMax M2.5 — structured code review output"
16
+ "reviewer": "FREE: MiniMax M2.5 — structured code review output",
17
+ "quick": "FREE: Qwen3.6 Plus or DeepSeek v4 Flash — minimal prompt for small edits"
17
18
  }
18
19
  },
19
20
  "defaultPrimary": "openai/gpt-5.5",
@@ -24,6 +25,7 @@
24
25
  "sdd-explorer": "opencode/deepseek-v4-flash-free",
25
26
  "sdd-implementer": "opencode/deepseek-v4-flash-free",
26
27
  "sdd-verifier": "opencode/qwen3.6-plus-free",
27
- "sdd-reviewer": "opencode/minimax-m2.5-free"
28
+ "sdd-reviewer": "opencode/minimax-m2.5-free",
29
+ "sdd-quick": "opencode/qwen3.6-plus-free"
28
30
  }
29
31
  }
package/.sdd/templates/reasoning-profile-template.json CHANGED
@@ -10,12 +10,14 @@
10
10
  "sdd-explorer": "low",
11
11
  "sdd-implementer": "medium",
12
12
  "sdd-verifier": "medium",
13
- "sdd-reviewer": "medium"
13
+ "sdd-reviewer": "medium",
14
+ "sdd-quick": "low"
14
15
  },
15
16
  "commands": {
16
17
  "sdd-explore": "medium",
17
18
  "sdd-propose": "high",
18
19
  "sdd-apply": "medium",
19
- "sdd-ship": "medium"
20
+ "sdd-ship": "medium",
21
+ "sdd-quick": "low"
20
22
  }
21
23
  }
package/GUIDE.md CHANGED
@@ -1,21 +1,77 @@
1
1
  # SDD Multi-Agent OpenCode Guide
2
2
 
3
- This kit exposes one small workflow for OpenCode:
3
+ This kit exposes five core commands for OpenCode:
4
4
 
5
5
  ```text
6
- /sdd-explore -> /sdd-propose -> /sdd-apply -> /sdd-ship
6
+ /sdd-construct -> /sdd-explore -> /sdd-propose -> /sdd-apply -> /sdd-ship
7
+ /sdd-quick (standalone for small fixes)
7
8
  ```
8
9
 
9
- 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.
10
+ 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.
10
11
 
11
12
  ## Commands
12
13
 
13
14
  | Command | Purpose | Writes Code? |
14
15
  |---------|---------|--------------|
16
+ | `/sdd-construct` | Initialize SDD workflow for a new or existing project | Yes (config files) |
15
17
  | `/sdd-explore` | Investigate unclear ideas, bugs, or code areas | No |
16
18
  | `/sdd-propose` | Create one focused change plan | No |
17
19
  | `/sdd-apply` | Implement an approved change | Yes |
18
20
  | `/sdd-ship` | Verify readiness before merge/release | No, unless explicitly asked |
21
+ | `/sdd-quick` | Lightweight cosmetic/config fix (~200 tokens) | Yes |
22
+
23
+ ## One-Time Project Setup
24
+
25
+ ### `/sdd-construct`
26
+
27
+ Run this once at the start of a project to set up the "spine" — stack detection, domain glossary, model routing, and type-specific guardrails.
28
+
29
+ ```text
30
+ /sdd-construct
31
+ /sdd-construct "e-commerce platform for digital goods"
32
+ ```
33
+
34
+ **What it does:**
35
+
36
+ 1. **Phase 1: Stack Detection**
37
+ - Empty directory guard → asks user for project type
38
+ - Quick sniff test → classifies clear patterns (Next.js, Laravel, etc.) instantly
39
+ - Conditional subagent exploration → only for unclear/complex projects
40
+ - Three-layer fallback: explorer → direct read → user input
41
+
42
+ 2. **Phase 2: Grilling Session** (one question at a time)
43
+ - Section A: Project Vision (all types)
44
+ - Section B: Constraints & Preferences (all types)
45
+ - Section C: Model Budget (all types)
46
+ - Section D: Issue Tracker (all types)
47
+ - Section E: Domain Glossary (all types)
48
+ - Section F: Type-specific guardrails (conditional)
49
+
50
+ 3. **Phase 3: Scaffold Artifacts**
51
+ - `.sdd/project-profile.json`, `.sdd/model-profile.json`, `.sdd/reasoning-profile.json`
52
+ - `CONTEXT.md` (domain glossary)
53
+ - `docs/adr/0001-project-initialization.md`
54
+ - Type-specific artifacts (conditional):
55
+
56
+ | Project Type | Artifacts |
57
+ |-------------|-----------|
58
+ | **frontend** | `DESIGN.md` (locked tokens), design rules in `AGENTS.md` |
59
+ | **backend** | `API_CONTRACT.md`, `SECURITY_RULES.md` |
60
+ | **library/sdk** | `PUBLIC_API.md`, `VERSIONING.md` |
61
+ | **cli** | `COMMAND_STRUCTURE.md` |
62
+ | **fullstack** | `DESIGN.md` + `API_CONTRACT.md` |
63
+
64
+ 4. **Phase 4: Verification** — checks all artifacts exist
65
+
66
+ **Project Type Classification:**
67
+
68
+ | Type | Signal Pattern | Example |
69
+ |------|---------------|---------|
70
+ | **frontend** | UI framework + styling + component dir, NO server | React + Tailwind + `components/` |
71
+ | **backend** | Server framework + NO UI framework | Express, Fastify, Laravel, Django |
72
+ | **library/sdk** | `exports` in package.json + NO entry point + NO server | Utility package, SDK |
73
+ | **cli** | `bin` in package.json + NO server + NO UI framework | CLI tool, scaffolding tool |
74
+ | **fullstack** | UI framework + server framework | Next.js App Router + API routes |
19
75
 
20
76
  ## Default Flow
21
77
 
@@ -61,6 +117,15 @@ specs/active/<change-id>/
61
117
  └── progress.md optional for large changes
62
118
  ```
63
119
 
120
+ **Test Spec Tables:** For tasks involving logic, `tasks.md` includes structured Test Spec tables:
121
+
122
+ | Scenario | Input | Expected Output | Mock Requirement |
123
+ |----------|-------|-----------------|------------------|
124
+ | Invalid email | `email: "abc"` | `400 Bad Request` | No mock needed |
125
+ | Valid login | `email: "a@b.c", pass: "123"` | `200 OK + token` | Mock DB query |
126
+
127
+ The implementer must translate this table exactly into test code.
128
+
64
129
  Review these files before applying. This is the agreement point.
65
130
 
66
131
  ### `/sdd-apply`
@@ -73,6 +138,12 @@ Use this after the proposal is accepted.
73
138
 
74
139
  It reads the artifacts, implements `tasks.md`, updates checkboxes, and runs targeted verification when possible.
75
140
 
141
+ **Test Integrity Rules:**
142
+ - **Source of Truth**: The Test Spec table in `tasks.md` defines exact test cases
143
+ - **No Weakening**: Forbidden from modifying assertions to make tests pass
144
+ - **Fix Implementation, Not Test**: If a test fails, fix source code, not the test
145
+ - **Report Mismatches**: If the Test Spec is incorrect, STOP and report it
146
+
76
147
  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.
77
148
 
78
149
  ### `/sdd-ship`
@@ -89,6 +160,54 @@ It audits the implementation against the artifacts and writes:
89
160
  specs/active/<change-id>/verification.md
90
161
  ```
91
162
 
163
+ **Asymmetric Verification:**
164
+ - **Completeness**: Every row in the Test Spec table has a corresponding test case
165
+ - **Assertion Strength**: Detects "weakening" (e.g., spec says `toBe(401)` but code says `toBeTruthy()`)
166
+ - **Mock Accuracy**: Verifies mocks match the spec
167
+ - **Halt on Violation**: If a violation is found, marks `ready: no` and reports — NO auto-correction
168
+
169
+ ### `/sdd-quick`
170
+
171
+ Use this for small, safe cosmetic/config changes — typo fixes, variable renames, config value changes.
172
+
173
+ ```text
174
+ /sdd-quick "fix typo: succesful -> successful"
175
+ /sdd-quick "rename isLoading to isFetching in auth.ts"
176
+ /sdd-quick "change MAX_RETRIES from 3 to 5"
177
+ ```
178
+
179
+ **What it does (hybrid CLI + LLM, ~200 tokens):**
180
+
181
+ 1. **Phase 1a**: CLI keyword scan (0 tokens) — detects operators, control flow keywords
182
+ 2. **Phase 1b**: Context-aware classification (~50 tokens) — only if ambiguous
183
+ 3. **Phase 2**: CLI pre-flight (0 tokens) — lock check, grep scan, string delta
184
+ 4. **Phase 3**: LLM edit (~150 tokens) — full file return for < 500 lines
185
+ 5. **Phase 4**: CLI post-flight (0 tokens) — actual diff, lint, typecheck, auto-revert
186
+ 6. **Phase 5**: CLI ledger append (0 tokens) — atomic write to `specs/QUICKFIX_LOG.md`
187
+
188
+ **Blocked automatically** (no LLM invoked):
189
+ - Logic changes (operators, control flow)
190
+ - Contract boundary files (`**/api/**`, `**/dto/**`, `**/schema/**`)
191
+ - Exported function/class/type name changes
192
+
193
+ **Warns and asks confirmation:**
194
+ - Cross-file references > 5
195
+ - String length delta > 20 chars or > 50% increase (UI layout risk)
196
+ - Another SDD process is active (lock file)
197
+
198
+ ## Example: New Project
199
+
200
+ ```text
201
+ /sdd-construct "task management app for teams"
202
+ -> detects Next.js + TypeScript + Tailwind
203
+ -> classifies as: fullstack
204
+ -> asks: vision, constraints, model budget, issue tracker, domain terms
205
+ -> generates: DESIGN.md (locked tokens), API_CONTRACT.md, CONTEXT.md, ADR
206
+ /sdd-propose auth-login "add email/password login with JWT"
207
+ /sdd-apply auth-login
208
+ /sdd-ship auth-login
209
+ ```
210
+
92
211
  ## Example: New Feature
93
212
 
94
213
  ```text
@@ -115,9 +234,24 @@ specs/active/<change-id>/verification.md
115
234
  /sdd-ship admin-ui-components
116
235
  ```
117
236
 
237
+ ## Example: Quick Fix
238
+
239
+ ```text
240
+ /sdd-quick "fix typo: 'succesful' -> 'successful'"
241
+ -> CLI: no blocking keywords, no contract path, 1 cross-file ref
242
+ -> LLM: change string in src/messages.ts
243
+ -> CLI: lint passed, typecheck passed, ledger updated
244
+ -> ✅ Applied (~200 tokens)
245
+
246
+ /sdd-quick "Ganti > jadi >= di validator.ts"
247
+ -> CLI: detected operator '>' → blocked
248
+ -> ❌ Abort: "Request contains operators which indicates a logic change."
249
+ -> Suggestion: Run `/sdd-propose "Ganti > jadi >= di validator.ts"`
250
+ ```
251
+
118
252
  ## Design Principles
119
253
 
120
- - Four commands only by default.
254
+ - Five commands + one quick-fix command.
121
255
  - No fake flags like `--deep` or `--until-finish`.
122
256
  - No source code changes during explore/propose.
123
257
  - One change folder per unit of work.
@@ -126,3 +260,6 @@ specs/active/<change-id>/verification.md
126
260
  - Long-running apply work must checkpoint to `progress.md`.
127
261
  - Parallel execution is a capability inside `/sdd-apply`, not a separate command.
128
262
  - Verification is a first-class step, not a vague final message.
263
+ - Type-aware scaffolding: frontend gets DESIGN.md, backend gets API_CONTRACT.md, library gets PUBLIC_API.md.
264
+ - Test-driven: Test Spec tables in tasks.md, Test Integrity rules in apply, Asymmetric Verification in ship.
265
+ - CLI-first for quick fixes: deterministic checks in Node.js, LLM only for the edit.