@laxture/vibe-pm 0.1.0

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 (63) hide show
  1. package/LICENSE +190 -0
  2. package/README.md +120 -0
  3. package/README.zh-CN.md +119 -0
  4. package/dist/core/commands.d.ts +17 -0
  5. package/dist/core/config.d.ts +12 -0
  6. package/dist/core/index.d.ts +8 -0
  7. package/dist/core/logger.d.ts +23 -0
  8. package/dist/core/plugin.d.ts +2 -0
  9. package/dist/core/types.d.ts +42 -0
  10. package/dist/docs/template/_coding_style/general.md +114 -0
  11. package/dist/docs/template/_coding_style/go.md +158 -0
  12. package/dist/docs/template/_coding_style/java.md +154 -0
  13. package/dist/docs/template/_coding_style/python.md +195 -0
  14. package/dist/docs/template/_coding_style/rust.md +161 -0
  15. package/dist/docs/template/_coding_style/sql.md +321 -0
  16. package/dist/docs/template/_coding_style/typescript.md +237 -0
  17. package/dist/docs/template/agents-template.md +38 -0
  18. package/dist/docs/template/bug-fix/flow.md +189 -0
  19. package/dist/docs/template/constitution-template.md +119 -0
  20. package/dist/docs/template/design-spec/flow.md +194 -0
  21. package/dist/docs/template/dictionary-template.md +40 -0
  22. package/dist/docs/template/large-refactor/flow.md +242 -0
  23. package/dist/docs/template/large-refactor/regulations/migration-checklist.md +28 -0
  24. package/dist/docs/template/research/flow.md +161 -0
  25. package/dist/docs/template/side-job/flow.md +147 -0
  26. package/dist/docs/template/spec-driven-dev/flow.md +420 -0
  27. package/dist/docs/template/spec-template.md +190 -0
  28. package/dist/engine/errors.d.ts +28 -0
  29. package/dist/engine/flow-engine.d.ts +32 -0
  30. package/dist/engine/index.d.ts +3 -0
  31. package/dist/i18n/index.d.ts +2 -0
  32. package/dist/i18n/loader.d.ts +23 -0
  33. package/dist/i18n/prompts-en-US.d.ts +47 -0
  34. package/dist/i18n/prompts-zh-CN.d.ts +50 -0
  35. package/dist/i18n/types.d.ts +51 -0
  36. package/dist/index.d.ts +5 -0
  37. package/dist/index.js +4886 -0
  38. package/dist/integration/dcp.d.ts +7 -0
  39. package/dist/integration/index.d.ts +1 -0
  40. package/dist/memory/errors.d.ts +11 -0
  41. package/dist/memory/index.d.ts +3 -0
  42. package/dist/memory/memory-system.d.ts +80 -0
  43. package/dist/memory/types.d.ts +157 -0
  44. package/dist/template/index.d.ts +3 -0
  45. package/dist/template/template-manager.d.ts +26 -0
  46. package/dist/template/types.d.ts +16 -0
  47. package/dist/token/backends/anthropic.d.ts +5 -0
  48. package/dist/token/backends/llama.d.ts +7 -0
  49. package/dist/token/backends/tiktoken.d.ts +7 -0
  50. package/dist/token/index.d.ts +3 -0
  51. package/dist/token/model-registry.d.ts +9 -0
  52. package/dist/token/token-counter.d.ts +17 -0
  53. package/dist/token/types.d.ts +39 -0
  54. package/dist/tui/components/collapsible.d.ts +9 -0
  55. package/dist/tui/components/empty-state.d.ts +7 -0
  56. package/dist/tui/data/task-status.d.ts +16 -0
  57. package/dist/tui/data/token-data.d.ts +16 -0
  58. package/dist/tui/index.d.ts +13 -0
  59. package/dist/tui/index.js +3293 -0
  60. package/dist/tui/slots/sidebar-content.d.ts +10 -0
  61. package/dist/tui/tui-plugin.d.ts +9 -0
  62. package/dist/tui/types.d.ts +63 -0
  63. package/package.json +63 -0
@@ -0,0 +1,420 @@
1
+ # Spec-Driven Development
2
+
3
+ **Template ID**: `spec-driven-dev`
4
+ **Category**: development
5
+ **Description**: Spec-driven standardized development workflow (Understand/Design/Code/Test/Accept/Merge, 10 steps)
6
+ **Command**: `/pm-spec-driven-dev`
7
+ **Version**: 1.1.0
8
+
9
+ ---
10
+
11
+ ## Applicable Scenarios
12
+
13
+ - Medium-to-large new feature development
14
+ - Tasks involving multi-module interaction
15
+ - Complex tasks requiring requirement clarification
16
+
17
+ ---
18
+
19
+ ## Input Requirements
20
+
21
+ | Input Item | Required | Description |
22
+ |--------|------|------|
23
+ | Spec Document | Yes | Existing specification document |
24
+ | Change Request | Yes | What to change and why |
25
+
26
+ ---
27
+
28
+ ## Default Deliverables
29
+
30
+ - Updated Spec document
31
+ - Code implementation + test code
32
+ - Delivery report
33
+
34
+ ---
35
+
36
+ ## State Machine
37
+
38
+ ```mermaid
39
+ stateDiagram-v2
40
+ [*] --> S1_Understand_Requirements_and_Current_State: Trigger
41
+ S1_Understand_Requirements_and_Current_State --> S2_Identify_Gaps
42
+ S2_Identify_Gaps --> S3_Progressive_Interview
43
+ S3_Progressive_Interview --> S3_Progressive_Interview: Continue inquiry
44
+ S3_Progressive_Interview --> S2_Identify_Gaps: Re-analyze based on clarified answers
45
+ S2_Identify_Gaps --> S3_Progressive_Interview: New questions discovered
46
+ S2_Identify_Gaps --> S4_Design_Plan: No more questions
47
+ S4_Design_Plan --> S5_Review_Plan
48
+ S5_Review_Plan --> S4_Design_Plan: Revisions needed
49
+ S5_Review_Plan --> S6_Write_Code: Approved
50
+ S6_Write_Code --> S7_Write_Tests
51
+ S7_Write_Tests --> S7_Write_Tests: Tests fail
52
+ S7_Write_Tests --> S8_Self_Check: All passed
53
+ S8_Self_Check --> S9_Review_Confirmation: Self-check passed, no high-risk items
54
+ S8_Self_Check --> S6_Write_Code: High-risk items need fixing
55
+ S9_Review_Confirmation --> S10_Deliver_and_Merge: Approved
56
+ S9_Review_Confirmation --> S6_Write_Code: Fixes needed
57
+ S9_Review_Confirmation --> S4_Design_Plan: Design issue
58
+ S10_Deliver_and_Merge --> [*]
59
+
60
+ note right of S3_Progressive_Interview: ⚠️ User intervention required
61
+ note right of S5_Review_Plan: ⚠️ User intervention required
62
+ note right of S9_Review_Confirmation
63
+ ⚠️ User intervention required
64
+ Design issue → Fall back to S4
65
+ end note
66
+ ```
67
+
68
+ ---
69
+
70
+ ## Task Steps
71
+
72
+ ### S1: Understand Requirements and Current State
73
+
74
+ **Goal**: Accurately understand the change intent and the current code state.
75
+
76
+ 1. Read the user-submitted change request
77
+ 2. Extract core intent — what needs to change? why?
78
+ 3. Locate and read the corresponding Spec document from the `docs/spec/` directory (do NOT skip this step), then read related source code
79
+ 4. Mark covered, vague, and missing information
80
+
81
+ **On completion**: Automatically proceed to S2
82
+
83
+ ---
84
+
85
+ ### S2: Identify Information Gaps and Contradictions
86
+
87
+ **Goal**: Systematically identify vague, missing, and conflicting items.
88
+
89
+ 1. Cross-reference the Spec against the change request, marking missing items, vague items, and contradictions
90
+ 2. Sort by impact level
91
+ 3. Prepare a list of interview questions, one per topic
92
+ 4. **Re-analyze after interview**: Upon returning from S3, re-examine the original S2 gap list based on clarified answers:
93
+ - Do the clarified answers introduce new ambiguities?
94
+ - Do the clarified conclusions conflict with the Spec or change request?
95
+ - Are there previously undiscovered missing items?
96
+ 5. If new questions are found → compile a new question list and return to S3 to continue interviewing; if no new questions → proceed to S4
97
+
98
+ **On completion**: No new questions → automatically proceed to S4; new questions found → return to S3
99
+
100
+ ---
101
+
102
+ ### S3: [Human-in-loop] Progressive Interview ⚠️
103
+
104
+ > **⚠️ This step requires user intervention.** Ask only 1 question at a time.
105
+
106
+ **Goal**: Clarify ambiguities one question at a time.
107
+
108
+ 1. Use the question / confirm blocking tool
109
+ 2. Ask only 1 question at a time
110
+ 3. Loop until the user confirms "no more questions"
111
+
112
+ **On completion**: User confirms "no more questions" → return to S2 for re-analysis
113
+
114
+ ---
115
+
116
+ ### S4: Design Plan
117
+
118
+ **Goal**: Based on the requirements clarified through S3 interviews, produce a unified Plan document covering Spec changes, code changes, and conflicts between them. **Save the Plan as a file** for S5 review.
119
+
120
+ > ⚠️ **Critical**: This step MUST save the Plan as a file `docs/plan/plan-{taskId}.md`. The S5 review step depends on this file.
121
+
122
+ #### Analysis Steps
123
+
124
+ ##### Phase 1: Spec Change Analysis (original S4 responsibility)
125
+
126
+ 1. **Review S3 interview results**: Revisit all Q&A sessions, distill the clarified core requirements
127
+ 2. **Locate relevant Spec documents**: List the involved Spec documents (`docs/spec/`), understand the existing chapter structure
128
+ 3. **Cross-reference chapter by chapter**: Using the clarified requirements as the baseline, iterate through each Spec chapter and determine the change type for each:
129
+ - **Modify** — Content is outdated, inaccurate, or needs supplementation
130
+ - **Add** — New concepts, interfaces, constraints, or flows introduced by the requirements
131
+ - **Delete** — Deprecated design, or content already covered by other chapters
132
+ - **Affected** — Content itself unchanged, but cross-references or dependencies are impacted by changes in other chapters
133
+
134
+ ##### Phase 2: Code Change Analysis (original S6 responsibility)
135
+
136
+ 4. **Read relevant source code**: Locate affected source files and understand existing implementations
137
+ 5. **Design code change points**: Map each Spec change point to an implementation path at the code level
138
+ 6. **Design test cases**: Design verification plans for each change point
139
+
140
+ ##### Phase 3: Conflict Analysis (🆕 New)
141
+
142
+ 7. **Spec vs Code cross-comparison**: Compare Spec change points against code change points item by item, identifying inconsistencies:
143
+ - Spec-defined interface signatures don't match code implementations
144
+ - Spec-described constraints are not enforced or are implemented oppositely in code
145
+ - Spec and code use different terminology for the same concept
146
+ - Code contains implicit behaviors not covered by the Spec
147
+ 8. **Annotate alignment direction**: Provide a recommendation for each conflict (align to Spec / align to Code / compromise), for the user to decide during S5
148
+
149
+ #### Plan Document Format
150
+
151
+ ```markdown
152
+ # Execution Plan
153
+
154
+ > Related Spec: [spec document path]
155
+ > Based on S3 interview results: [one-sentence summary of core conclusion]
156
+ > Goal: [one-sentence goal summary]
157
+
158
+ ---
159
+
160
+ ## 1. Spec Changes
161
+
162
+ ### Involved Spec Documents
163
+
164
+ | Document | Change Type | Description |
165
+ |------|----------|------|
166
+ | docs/spec/xxx.md | Modify | ... |
167
+
168
+ ### Change Overview
169
+
170
+ | Type | Count |
171
+ |------|------|
172
+ | Modify | N |
173
+ | Add | N |
174
+ | Delete | N |
175
+ | Affected (no change needed) | N |
176
+
177
+ ### Change Details
178
+
179
+ #### CHG-S1: [Chapter/Section Name] — Modify
180
+
181
+ - **Current Description**: [one-sentence summary of current state]
182
+ - **Reason for Change**: [which S3 interview conclusion]
183
+ - **Change Direction**: [what to change to, without writing specific implementation]
184
+
185
+ #### CHG-S2: [Chapter/Section Name] — Add
186
+
187
+ - **Reason for Addition**: [which S3 interview conclusion]
188
+ - **Chapter Draft**: [list of planned key points]
189
+ - **Dependencies**: [other chapters or documents to reference]
190
+
191
+ #### CHG-S3: [Chapter/Section Name] — Delete (if applicable)
192
+
193
+ - **Reason for Deletion**: [why deprecated]
194
+ - **Alternative**: [where functionality is migrated, or deprecation rationale]
195
+
196
+ ### Spec Consistency Checklist
197
+
198
+ - [ ] Each change point traceable to an S3 interview conclusion
199
+ - [ ] No logical contradictions between change points
200
+ - [ ] Deleted chapters have annotated alternatives or deprecation rationale
201
+
202
+ ---
203
+
204
+ ## 2. Code Changes
205
+
206
+ ### File List
207
+
208
+ | File | Operation | Description |
209
+ |------|------|------|
210
+ | path/to/file.ts | Modify | ... |
211
+ | path/to/new.ts | Add | ... |
212
+
213
+ ### Change Details
214
+
215
+ #### CHG-C1: [File/Module Name] — [Operation Type]
216
+
217
+ - **Related Spec**: [corresponding CHG-Sx]
218
+ - **Goal**: [what to change]
219
+ - **Approach**: [how to change, brief technical path]
220
+ - **Impact**: [which other modules are affected]
221
+ - **Test Points**: [what needs to be verified]
222
+
223
+ #### CHG-C2: ...
224
+
225
+ ### Configuration Items (if applicable)
226
+
227
+ | Config Item | Location | Change Description |
228
+ |--------|------|----------|
229
+ | ... | ... | ... |
230
+
231
+ ### Risks and Mitigations
232
+
233
+ | Risk | Impact | Mitigation |
234
+ |------|------|----------|
235
+ | ... | ... | ... |
236
+
237
+ ### Test Plan
238
+
239
+ | Test Type | Test Content | Expected Result |
240
+ |----------|----------|----------|
241
+ | Unit test | ... | ... |
242
+ | Integration test | ... | ... |
243
+
244
+ ---
245
+
246
+ ## 3. Spec vs Code Conflicts ⚠️
247
+
248
+ > Listed below are inconsistencies between Spec changes and code changes.
249
+ > Each conflict includes a **recommended alignment direction**. Please decide during S5 review.
250
+
251
+ | # | Conflict Description | Spec Definition | Code Status | Impact Scope | Recommended Alignment |
252
+ |------|----------|-----------|----------|----------|-------------|
253
+ | CF-1 | [brief conflict description] | [what Spec says] | [how code is implemented] | [affected modules] | Align to Spec / Align to Code / Compromise: [brief plan] |
254
+ | CF-2 | ... | ... | ... | ... | ... |
255
+
256
+ > If no conflicts, write "None — Spec and Code are consistent".
257
+ ```
258
+
259
+ #### Self-Check Checklist
260
+
261
+ After saving the Plan file, confirm the following item by item:
262
+
263
+ - [ ] **Spec section**: Each CHG-S traces back to an S3 interview conclusion; no contradictions between change points
264
+ - [ ] **Code section**: File list is complete; each CHG-C is linked to a corresponding CHG-S
265
+ - [ ] **Conflict section**: Spec vs Code compared item by item; no missed implicit inconsistencies
266
+ - [ ] Plan file saved to `docs/plan/plan-{taskId}.md`
267
+ - [ ] Risks have corresponding mitigations
268
+ - [ ] Test plan covers all change points
269
+
270
+ **On completion**: Plan file saved → automatically proceed to S5
271
+
272
+ ---
273
+
274
+ ### S5: [Human-in-loop] Review Plan ⚠️
275
+
276
+ **Goal**: User reviews the complete Plan (Spec changes + Code changes + Conflicts) in one pass, and makes alignment decisions on conflict points.
277
+
278
+ 1. Call `pm_task_set_step(step="S5")` to declare entry into this step
279
+ 2. Present the three sections of the Plan document
280
+ 3. ⚠️ For each CF-* entry in the "Spec vs Code Conflicts" table, use the `question` tool to ask the user for the alignment direction item by item:
281
+ - Options: `Align to Spec` / `Align to Code` / `Compromise`
282
+ - If the user chooses Compromise, follow up to ask for specific compromise details
283
+ 4. After collecting all decisions, use the `confirm` tool to wait for the user's final confirmation of the overall Plan:
284
+ - **Must** receive **strongly affirmative** instructions from the user such as "confirm / agree / approved / no problem / go ahead / LGTM" before proceeding
285
+ - Vague or weak affirmative responses ("looks OK", "let's try", "mm", "should be fine") are treated as **unconfirmed**; must follow up for explicit approval
286
+ 5. **Strictly prohibited** from performing any code modifications, file edits, or todo creation before receiving explicit confirmation
287
+
288
+ **On completion**: Explicitly confirmed → S6; revisions needed → S4; new ambiguities → S3
289
+
290
+ ---
291
+
292
+ ### S6: Write Code
293
+
294
+ **Goal**: Implement according to the Plan.
295
+ **Referenced Regulations**: coding_style.md, constitution.md
296
+
297
+ 1. Implement change points from the Plan one by one
298
+ 2. Run build/type-check after each change
299
+ 3. Follow code quality-first principles
300
+
301
+ **On completion**: All implemented → S7.
302
+
303
+ > ⚠️ **Iteration Counter**: Each execution of S6 (including re-executions after being sent back from S8 for fixes or from S9 for fixes) increments the S6 iteration count by 1. This count is read by S8 during self-check to determine whether to trigger deep iteration review (threshold: > 5 rounds).
304
+
305
+ ---
306
+
307
+ ### S7: Write Tests and Fix
308
+
309
+ **Goal**: Write test code and ensure all pass.
310
+ **Referenced Regulation**: coding_style.md
311
+
312
+ 1. Write tests according to the Plan's test cases
313
+ 2. Run tests, fix failures
314
+ 3. Do NOT delete failing tests
315
+
316
+ **On completion**: All passed → S8
317
+
318
+ ---
319
+
320
+ ### S8: Self-Check and Code Review
321
+
322
+ **Goal**: Perform a comprehensive self-check and use code review tools to discover potential issues.
323
+
324
+ > ⚠️ **Deep Iteration Review Trigger Condition**: If S6 iteration count > 5 rounds, the code review phase automatically upgrades to "Deep Review", additionally checking for ineffective modifications and excessive refactoring.
325
+
326
+ #### Phase 1: Basic Self-Check
327
+
328
+ **Referenced Regulation**: checklist.md
329
+
330
+ 1. Are all Plan tasks fully implemented
331
+ 2. Do build + tests pass
332
+ 3. Is the Spec fully implemented
333
+ 4. Is there any unnecessary refactoring
334
+
335
+ Basic self-check passed → proceed to Phase 2.
336
+ Issues found → return to S6 for fixes.
337
+
338
+ #### Precursor: Deep Iteration Review (triggered when S6 iteration count > 5)
339
+
340
+ When S6 has taken more than 5 iterations to reach this step, it indicates the code may have undergone extensive back-and-forth modifications. Before entering formal code review, perform additional deep review:
341
+
342
+ 1. **Ineffective Modification Detection**:
343
+ - Check for patterns of modifying the same code back and forth (changed, then changed back)
344
+ - Identify intermediate changes that were overwritten/deprecated by subsequent modifications
345
+ - Detect residual artifacts from multiple mutually exclusive approaches attempted for the same problem
346
+
347
+ 2. **Excessive Refactoring Detection**:
348
+ - Whether "passing refactoring" beyond the Plan scope introduced unnecessary complexity
349
+ - Whether new abstraction layers, utility functions, or configuration items not covered by the Plan were introduced
350
+ - Whether there is over-engineering for "possible future needs"
351
+
352
+ 3. Output deep review conclusions:
353
+ - Flag suspicious ineffective modification points, recommend whether to roll back some changes
354
+ - Flag out-of-scope excessive refactoring, recommend retention or removal
355
+ - Classify issues found in deep review into the 🔴/🟡/🟢 severity levels below
356
+
357
+ > If S6 iteration count ≤ 5, skip this phase and go directly to Phase 2.
358
+
359
+ #### Phase 2: Code Review
360
+
361
+ > **Conditional execution**: Check if the `/code-review-skill` command is available.
362
+ > - If available → perform code review
363
+ > - If unavailable → skip this phase, go directly to S9
364
+
365
+ 1. Call `skill(name="/code-review-skill")` to retrieve the code review guide
366
+ 2. Perform a comprehensive review of the changed files according to the review guide
367
+ 3. Output a review report, categorized by severity
368
+
369
+ ##### Review Severity Classification
370
+
371
+ | Severity | Definition | Handling |
372
+ |--------|------|----------|
373
+ | 🔴 Critical | Security vulnerabilities, data loss risk, logic errors, type safety violations | Must return to S6 for fixes |
374
+ | 🟡 Medium | Performance issues, code smells, maintainability issues, missing edge cases | Recorded in report; user decides in S9 whether to fix |
375
+ | 🟢 Low | Style issues, naming suggestions, documentation improvements | Recorded in report; user decides in S9 whether to fix |
376
+
377
+ ##### Flow Rules
378
+
379
+ - **Critical items exist (🔴 > 0)**: Output review report, automatically return to S6 for fixes. Fix each critical item one by one; after fixes, re-enter S7 (tests) → S8 (self-check).
380
+ - **No critical items (🔴 = 0)**: Output complete review report (including medium and low severity items), automatically proceed to S9. Medium and low items are left for user decision during review confirmation.
381
+
382
+ **On completion**: No critical items → S9; critical items exist → S6
383
+
384
+ ---
385
+
386
+ ### S9: [Human-in-loop] Review Confirmation ⚠️
387
+
388
+ **Goal**: User confirms deliverables and code review results.
389
+
390
+ 1. Present the delivery report
391
+ 2. If there is an S8 code review report, present the list of medium and low severity items, and use the `question` tool to ask the user:
392
+ - "Code review found N medium items and M low items. Should they be fixed in this round?"
393
+ - Options: "Ignore all, accept directly" / "Fix medium items only" / "Fix all"
394
+ 3. Use the `confirm` tool to wait for final confirmation
395
+
396
+ > ⚠️ **Design Issues vs Code Issues**:
397
+ > - **Code Issues**: Implementation bugs, missed edge cases, insufficient test coverage → return to S6 for fixes
398
+ > - **Design Issues**: User points out the overall approach direction is wrong, Spec understanding is off, architecture choice needs adjustment, the change points designed in the Plan themselves are unreasonable → return to S4 to redesign the plan
399
+
400
+ **On completion**:
401
+ - Approved (or user chooses to ignore fix items) → S10
402
+ - Fixes needed (code-level bugs/omissions) → S6
403
+ - Design issue (user points out design direction is wrong, approach is not viable, etc.) → S4 to redesign plan
404
+
405
+ ---
406
+
407
+ ### S10: Deliver and Merge
408
+
409
+ **Goal**: Wrap up, update documentation, prepare for commit.
410
+ **Referenced Regulation**: checklist.md
411
+
412
+ 1. Save the delivery report to the Plan
413
+ 2. Update the Spec document
414
+ 3. Run final verification
415
+ 4. Use the `question` tool to ask the user: "Perform `git commit`?"
416
+ - If the user selects "Yes": execute `git add -A && git commit`, using the development summary as the commit message
417
+ - If the user selects "No": skip commit
418
+ - ⚠️ User choice does not affect task completion
419
+
420
+ **On completion**: Call `pm_task_close()` to end the task and trigger analysis
@@ -0,0 +1,190 @@
1
+ # Feature Spec Template
2
+
3
+ ## Usage
4
+
5
+ When creating a new Feature Spec, follow the structure of this template, output to `/docs/spec/{feature-name}.md`, and fill in each section accordingly. Sections not applicable to the current feature may be removed.
6
+
7
+ For non-code-oriented features (process design, architecture design, rule definition, etc.), tailor the sections as appropriate.
8
+
9
+ ---
10
+
11
+ # {Feature Title}
12
+
13
+ **Created Date**: {YYYY-MM-DD}
14
+ **Status**: Draft / Review / Final
15
+ **Input Source**: {User Request / Design Discussion / Technical Proposal / Task Requirement}
16
+
17
+ ---
18
+
19
+ ## Background & Requirements
20
+
21
+ <!-- Describe the target problem to solve, and the consequences of not solving it -->
22
+
23
+ {Background Description}
24
+
25
+ ---
26
+
27
+ ## Use Cases & User Stories
28
+
29
+ <!--
30
+ User stories are ordered by priority (P1/P2/P3).
31
+ Each user story must be independently testable and independently deliverable.
32
+ P1 = core value; even if only this one is implemented, it should form a usable MVP.
33
+ For non-interactive features (e.g., architecture, process, rules), user stories can be omitted;
34
+ use "Use Case Scenarios" to describe system behavior instead.
35
+ -->
36
+
37
+ ### User Story 1 — {Title} (Priority: P1)
38
+
39
+ {Brief description of the user journey}
40
+
41
+ **Priority Reason**: {Why it is P1}
42
+
43
+ **Independent Verification**: {How to independently test this story — e.g., "After running xxx command, xxx output should appear"}
44
+
45
+ **Acceptance Scenarios**:
46
+
47
+ 1. **Given** {initial state}, **When** {action}, **Then** {expected result}
48
+ 2. **Given** {initial state}, **When** {action}, **Then** {expected result}
49
+
50
+ ---
51
+
52
+ ### User Story 2 — {Title} (Priority: P2)
53
+
54
+ {Brief description of the user journey}
55
+
56
+ **Priority Reason**: {Why it is P2}
57
+
58
+ **Independent Verification**: {How to independently test this story}
59
+
60
+ **Acceptance Scenarios**:
61
+
62
+ 1. **Given** {initial state}, **When** {action}, **Then** {expected result}
63
+
64
+ ---
65
+
66
+ ### User Story 3 — {Title} (Priority: P3)
67
+
68
+ {Brief description of the user journey}
69
+
70
+ **Priority Reason**: {Why it is P3}
71
+
72
+ **Independent Verification**: {How to independently test this story}
73
+
74
+ **Acceptance Scenarios**:
75
+
76
+ 1. **Given** {initial state}, **When** {action}, **Then** {expected result}
77
+
78
+ ---
79
+
80
+ ## Design Highlights
81
+
82
+ ### Domain Model
83
+
84
+ {Core entities/concepts involved, and the relationships between entities}
85
+
86
+ | Entity | Attributes | Relationships |
87
+ |--------|------------|---------------|
88
+ | {Entity Name} | {Key Attributes} | {Related entities and their relationships} |
89
+
90
+ ### Critical Path
91
+
92
+ {Main flow description; may use step list or flow chart}
93
+
94
+ ### Conditional Branches
95
+
96
+ {Behavior branches under different conditions}
97
+
98
+ ### Interface Design
99
+
100
+ {Externally exposed interfaces, parameters, and return values}
101
+
102
+ ### Interaction Design
103
+
104
+ {User-system interaction flow, key interface layouts, or operation sequences}
105
+
106
+ > Optionally use Mermaid sequence diagrams to describe interactions
107
+
108
+ ### Configurable Items
109
+
110
+ | Config Item | Default Value | Description |
111
+ |-------------|---------------|-------------|
112
+ | {key} | {value} | {description} |
113
+
114
+ ---
115
+
116
+ ## Decomposition Index
117
+
118
+ <!--
119
+ Use this section when the Spec scope is too large to describe all details in a single document.
120
+ "Design Highlights" retains only the layered architecture (domain model, module relationships, critical path);
121
+ detailed designs for individual feature points (domain models, interface designs, test cases, etc.)
122
+ are decomposed into independent Specs.
123
+ Remove this comment and table when not applicable.
124
+ -->
125
+
126
+ | Feature Point | Detailed Spec | Description |
127
+ |---------------|---------------|-------------|
128
+ | {Feature Point Name} | [`spec-{name}.md`](./{parent-feature}/spec-{name}.md) | {Brief description} |
129
+
130
+ ---
131
+
132
+ ## Edge Cases & Error Handling
133
+
134
+ | Scenario | Expected Behavior |
135
+ |----------|-------------------|
136
+ | {Empty input} | {How to handle} |
137
+ | {Extreme value input} | {How to handle} |
138
+ | {Concurrent access} | {How to handle} |
139
+ | {Dependency unavailable} | {Degradation strategy} |
140
+ | {Invalid operation} | {Error message} |
141
+
142
+ ---
143
+
144
+ ## Test Cases
145
+
146
+ ### ${Test File Name}
147
+
148
+ - **Test File**: `[file name](/path/to/xxx_test.go)`
149
+ - **Associated Design Doc**: The associated Feature Spec document
150
+ - **Setup/Teardown**: What needs to be done for Setup/Teardown
151
+
152
+ | Action | Test Method | Given | When | Then | Notes |
153
+ |--------|-------------|-------|------|------|-------|
154
+ | ${Add/Modify/Deprecate} | `${testMethod}` | ${gherkin} | ${gherkin} | ${gherkin} | ${notes} |
155
+
156
+ ---
157
+
158
+ ## Constraints & Limitations
159
+
160
+ ### Technical Constraints
161
+
162
+ {Dependency versions, performance requirements, compatibility requirements}
163
+
164
+ ### Business Constraints
165
+
166
+ {Unbreakable business rules, compliance/security requirements}
167
+
168
+ ### Known Risks
169
+
170
+ {Greatest uncertainties, most likely areas to go wrong}
171
+
172
+ ### Impact Scope
173
+
174
+ {Which existing modules are affected, whether existing code needs modification}
175
+
176
+ ---
177
+
178
+ ## Implementation Plan
179
+
180
+ > This section is continuously updated during development. Break down by milestone granularity, associating each milestone with feature points and risks.
181
+
182
+ ### [x] Milestone 1 — {Title}
183
+
184
+ - [x] {Feature Point 1}
185
+ - Known Issues/Risks: {Issues/risks remaining at delivery time, to be resolved later}
186
+
187
+ ### [ ] Milestone 2 — {Title}
188
+
189
+ - [x] {Feature Point 2}
190
+ - Known Issues/Risks: {Same as above}
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Flow Engine error classes
3
+ */
4
+ /** Thrown when attempting to start a new task in a session with an existing active task */
5
+ export declare class DuplicateActiveTaskError extends Error {
6
+ readonly existingTask: {
7
+ flow: string;
8
+ currentStep: string;
9
+ currentStepName: string;
10
+ summary: string;
11
+ startAt: string;
12
+ };
13
+ constructor(existingTask: {
14
+ flow: string;
15
+ currentStep: string;
16
+ currentStepName: string;
17
+ summary: string;
18
+ startAt: string;
19
+ }, locale: string);
20
+ }
21
+ /** Requested Flow document does not exist */
22
+ export declare class FlowNotFoundError extends Error {
23
+ constructor(flowName: string);
24
+ }
25
+ /** Flow document parsing failed */
26
+ export declare class FlowParseError extends Error {
27
+ constructor(flowName: string, reason: string);
28
+ }
@@ -0,0 +1,32 @@
1
+ import type { Task } from '../memory';
2
+ import { MemorySystem } from '../memory';
3
+ import { Part } from '@opencode-ai/sdk';
4
+ export interface StartTaskParams {
5
+ sessionId: string;
6
+ flow: string;
7
+ summary: string;
8
+ userRequest: string;
9
+ }
10
+ export declare class FlowEngine {
11
+ private memory;
12
+ private projectDir;
13
+ private commandFlowCache;
14
+ private promptTemplate;
15
+ constructor(memory: MemorySystem, projectDir: string);
16
+ initLocale(locale: string): void;
17
+ injectFlowControlPrompt(sessionId: string, flow: string, parts: Part[], msgId: string, msgSid: string): Promise<void>;
18
+ removeControlPrompt(parts: {
19
+ type: string;
20
+ text: string;
21
+ }[]): void;
22
+ buildControlPrompt(flowName?: string): string;
23
+ injectFlowWarningPrompt(sessionId: string, parts: Part[], msgId: string, msgSid: string): void;
24
+ startTask(params: StartTaskParams): Promise<Task>;
25
+ setStep(sessionId: string, step: string): Promise<void>;
26
+ closeTask(sessionId: string): Promise<Task | null>;
27
+ resolveFlowFromCommand(command: string): string | null;
28
+ clearCommandFlowCache(): void;
29
+ private flowExists;
30
+ private tryParseStepName;
31
+ private buildCommandFlowMap;
32
+ }
@@ -0,0 +1,3 @@
1
+ export { FlowEngine } from './flow-engine.js';
2
+ export type { StartTaskParams } from './flow-engine.js';
3
+ export { DuplicateActiveTaskError, FlowNotFoundError, FlowParseError } from './errors.js';
@@ -0,0 +1,2 @@
1
+ export type { Locale, LanguagePack, PromptsI18n, ControlPromptTemplate, CodingStyleI18n, ErrorI18n } from './types.js';
2
+ export { discoverLanguagePacks, getControlPromptTemplate, setCurrentLocale, getCurrentLocale, i18n, clearI18nCache, } from './loader.js';