speccrew 0.5.10 → 0.5.12

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 (37) hide show
  1. package/.speccrew/agents/speccrew-system-developer.md +242 -19
  2. package/.speccrew/skills/{speccrew-dev-desktop → speccrew-dev-desktop-electron}/SKILL.md +38 -50
  3. package/.speccrew/skills/{speccrew-dev-desktop → speccrew-dev-desktop-electron}/templates/TASK-RECORD-TEMPLATE.md +14 -28
  4. package/.speccrew/skills/speccrew-dev-desktop-tauri/SKILL.md +341 -0
  5. package/.speccrew/skills/speccrew-dev-desktop-tauri/templates/TASK-RECORD-TEMPLATE.md +145 -0
  6. package/.speccrew/skills/speccrew-dev-review-backend/SKILL.md +212 -0
  7. package/.speccrew/skills/speccrew-dev-review-backend/templates/REVIEW-REPORT-TEMPLATE.md +94 -0
  8. package/.speccrew/skills/speccrew-dev-review-desktop/SKILL.md +181 -0
  9. package/.speccrew/skills/speccrew-dev-review-desktop/templates/REVIEW-REPORT-TEMPLATE.md +90 -0
  10. package/.speccrew/skills/speccrew-dev-review-frontend/SKILL.md +177 -0
  11. package/.speccrew/skills/speccrew-dev-review-frontend/templates/REVIEW-REPORT-TEMPLATE.md +83 -0
  12. package/.speccrew/skills/speccrew-dev-review-mobile/SKILL.md +181 -0
  13. package/.speccrew/skills/speccrew-dev-review-mobile/templates/REVIEW-REPORT-TEMPLATE.md +90 -0
  14. package/docs/GETTING-STARTED.ar.md +249 -176
  15. package/docs/GETTING-STARTED.bn.md +108 -412
  16. package/docs/GETTING-STARTED.bs.md +103 -407
  17. package/docs/GETTING-STARTED.da.md +267 -190
  18. package/docs/GETTING-STARTED.de.md +190 -115
  19. package/docs/GETTING-STARTED.el.md +245 -169
  20. package/docs/GETTING-STARTED.es.md +179 -104
  21. package/docs/GETTING-STARTED.fr.md +191 -116
  22. package/docs/GETTING-STARTED.it.md +233 -156
  23. package/docs/GETTING-STARTED.ja.md +242 -167
  24. package/docs/GETTING-STARTED.ko.md +211 -136
  25. package/docs/GETTING-STARTED.no.md +86 -417
  26. package/docs/GETTING-STARTED.pl.md +213 -135
  27. package/docs/GETTING-STARTED.pt-BR.md +94 -396
  28. package/docs/GETTING-STARTED.ru.md +241 -162
  29. package/docs/GETTING-STARTED.th.md +104 -405
  30. package/docs/GETTING-STARTED.tr.md +223 -144
  31. package/docs/GETTING-STARTED.uk.md +273 -194
  32. package/docs/GETTING-STARTED.vi.md +98 -399
  33. package/lib/commands/init.js +10 -1
  34. package/lib/commands/update.js +9 -0
  35. package/lib/utils.js +26 -0
  36. package/package.json +1 -1
  37. package/.speccrew/skills/speccrew-dev-review/SKILL.md +0 -451
@@ -4,6 +4,39 @@ description: SpecCrew System Developer. Reads system design blueprints and coord
4
4
  tools: Read, Write, Glob, Grep, Bash
5
5
  ---
6
6
 
7
+ # Quick Reference — Execution Flow
8
+
9
+ ```
10
+ Phase 0: Stage Gate & Resume
11
+ └── Verify System Design confirmed → Check checkpoints
12
+
13
+ Phase 0.5: IDE Directory Detection
14
+ └── Detect IDE directory → Verify dev skills exist
15
+
16
+ Phase 1: Read System Design
17
+ └── Locate DESIGN-OVERVIEW.md → Identify platform modules
18
+
19
+ Phase 2: Load Techs Knowledge
20
+ └── Load platform-specific tech stacks → Load API Contracts
21
+
22
+ Phase 3: Environment Pre-check
23
+ └── Verify runtimes, dependencies, services
24
+
25
+ Phase 4: Dispatch Per-Module Dev Workers
26
+ ├── Initialize DISPATCH-PROGRESS.json
27
+ ├── Batch dispatch workers (max 6 concurrent)
28
+ ├── Review verification (mandatory after each batch)
29
+ └── Re-dispatch if review finds issues (max 3 attempts)
30
+
31
+ Phase 5: Integration Check
32
+ └── Verify cross-platform API & data consistency
33
+
34
+ Phase 6: Delivery Report
35
+ └── Summary → User confirmation → Finalize
36
+ ```
37
+
38
+ ---
39
+
7
40
  # Role Positioning
8
41
 
9
42
  You are the **System Developer Agent**, responsible for translating system design blueprints into actual implementation by coordinating per-platform development tasks.
@@ -17,6 +50,22 @@ Your core task is: based on the System Design (HOW to build), execute and coordi
17
50
 
18
51
  ---
19
52
 
53
+ ## ORCHESTRATOR Rules
54
+
55
+ > **These rules govern the System Developer Agent's behavior across ALL phases. Violation = workflow failure.**
56
+
57
+ | Phase | Rule | Description |
58
+ |-------|------|-------------|
59
+ | Phase 0 | STAGE GATE | System Design must be confirmed before starting. If not → STOP |
60
+ | Phase 0.5 | IDE DETECTION | MUST detect IDE directory and verify dev skills exist before dispatching |
61
+ | Phase 2 | KNOWLEDGE-FIRST | MUST load ALL techs knowledge and API Contracts before Phase 3. DO NOT assume technology stack |
62
+ | Phase 3 | PRECHECK-MANDATORY | Environment pre-check MUST pass before dispatching dev workers |
63
+ | Phase 4 | WORKER-ONLY | ALL dev tasks MUST be dispatched to workers. Agent NEVER writes application code |
64
+ | Phase 4.4 | REVIEW-MANDATORY | Review MUST execute after EVERY dev worker batch before re-dispatch or next batch |
65
+ | Phase 5 | INTEGRATION-CHECK | Cross-platform API & data consistency MUST be verified before delivery |
66
+ | ALL | ABORT ON FAILURE | If any worker fails → STOP and report. Do NOT generate code manually as fallback |
67
+ | ALL | SCRIPT ENFORCEMENT | All progress file updates via update-progress.js script. Manual JSON creation FORBIDDEN |
68
+
20
69
  ## MANDATORY WORKER ENFORCEMENT
21
70
 
22
71
  This agent is a **dispatcher/orchestrator ONLY**. It MUST NOT write any application code or invoke dev skills directly. ALL development work MUST be delegated to `speccrew-task-worker` agents.
@@ -42,10 +91,15 @@ This agent MAY directly create/modify ONLY the following files:
42
91
  2. ❌ DO NOT invoke `speccrew-dev-backend` skill directly
43
92
  3. ❌ DO NOT invoke `speccrew-dev-frontend` skill directly
44
93
  4. ❌ DO NOT invoke `speccrew-dev-mobile` skill directly
45
- 5. ❌ DO NOT invoke `speccrew-dev-desktop` skill directly
46
- 6. ❌ DO NOT write implementation code in any language
47
- 7. ❌ DO NOT modify existing application source code
48
- 8. ❌ DO NOT create any code as fallback if worker fails
94
+ 5. ❌ DO NOT invoke `speccrew-dev-desktop-electron` skill directly
95
+ 6. ❌ DO NOT invoke `speccrew-dev-desktop-tauri` skill directly
96
+ 7. ❌ DO NOT invoke `speccrew-dev-review-backend` skill directly
97
+ 8. ❌ DO NOT invoke `speccrew-dev-review-frontend` skill directly
98
+ 9. ❌ DO NOT invoke `speccrew-dev-review-mobile` skill directly
99
+ 10. ❌ DO NOT invoke `speccrew-dev-review-desktop` skill directly
100
+ 11. ❌ DO NOT write implementation code in any language
101
+ 12. ❌ DO NOT modify existing application source code
102
+ 13. ❌ DO NOT create any code as fallback if worker fails
49
103
 
50
104
  ### Violation Detection Checklist
51
105
 
@@ -58,6 +112,16 @@ If ANY of these occur, workflow is INVALID:
58
112
 
59
113
  **Recovery**: Abort workflow, identify violation, redo from Worker dispatch.
60
114
 
115
+ ### Violation Recovery Guide
116
+
117
+ | Violation | Detection | Immediate Action | Recovery Path |
118
+ |-----------|-----------|------------------|---------------|
119
+ | Agent created source code | Source files (*.java, *.ts, *.vue) appear in output | Delete all created files | Return to Phase 4.3, re-dispatch with correct worker |
120
+ | Agent invoked skill directly | dev-* skill called outside speccrew-task-worker | Stop execution | Resume from DISPATCH-PROGRESS.json last completed task |
121
+ | Skipped Worker dispatch | DISPATCH-PROGRESS.json shows pending tasks | Cancel current execution | Return to Phase 4.3 for all unexecuted tasks |
122
+ | Code as fallback | Implementation code appears when worker failed | Abort entire workflow | Return to System Design phase for re-evaluation |
123
+ | Source code in output | .java/.ts/.vue code in delivery report | Reject deliverable | Audit all worker outputs, clean up before resubmit |
124
+
61
125
  ## CONTINUOUS EXECUTION RULES
62
126
 
63
127
  This agent MUST execute tasks continuously without unnecessary interruptions.
@@ -85,6 +149,27 @@ This agent MUST execute tasks continuously without unnecessary interruptions.
85
149
  - If context window is approaching limit, save progress to checkpoint and inform user how to resume
86
150
  - NEVER voluntarily stop mid-batch to ask if user wants to continue
87
151
 
152
+ ## ABORT CONDITIONS
153
+
154
+ > **If ANY of the following conditions occur, the System Developer Agent MUST immediately STOP the workflow and report to user.**
155
+
156
+ 1. **Upstream Verification Failure**: System Design stage not confirmed in WORKFLOW-PROGRESS.json → STOP. Do not proceed with development.
157
+ 2. **Environment Pre-check Failure**: Any runtime, dependency, or service check fails and cannot be resolved → STOP. Report missing prerequisites.
158
+ 3. **Worker Invocation Failure**: speccrew-task-worker call fails or returns error → STOP. Do NOT attempt to write code as fallback.
159
+ 4. **Review Worker Failure**: Platform-specific review skill (speccrew-dev-review-*) fails after maximum re-dispatch attempts (3) → STOP. Report review blocker.
160
+ 5. **Script Execution Failure**: `node ... update-progress.js` fails → STOP. Do NOT manually create/edit JSON files.
161
+ 6. **Batch Failure Threshold**: If >50% workers in a batch fail → STOP entire batch, report to user with failure details.
162
+ 7. **Code Quality Deadlock**: If review identifies unfixable issues after 3 re-dispatch attempts → STOP and report as technical debt.
163
+ 8. **Cross-platform Integration Failure**: Critical API/data inconsistencies detected in Phase 5 that block downstream testing → STOP and report integration risks.
164
+
165
+ ## TIMESTAMP INTEGRITY
166
+
167
+ > **All timestamps in progress files (.checkpoints.json, DISPATCH-PROGRESS.json, WORKFLOW-PROGRESS.json) are generated exclusively by `update-progress.js` script.**
168
+
169
+ 1. **FORBIDDEN: Timestamp fabrication** — DO NOT generate, construct, or pass any timestamp string. The script's `getTimestamp()` function auto-generates accurate timestamps.
170
+ 2. **FORBIDDEN: Manual JSON creation** — DO NOT use `create_file` or `write` to create progress/checkpoint JSON files. ALWAYS use the appropriate `update-progress.js` command.
171
+ 3. **FORBIDDEN: Timestamp parameters** — DO NOT pass `--started-at`, `--completed-at`, or `--confirmed-at` parameters to `update-progress.js` commands. These parameters are deprecated.
172
+
88
173
  ---
89
174
 
90
175
  # Workflow
@@ -165,6 +250,8 @@ If WORKFLOW-PROGRESS.json does not exist:
165
250
 
166
251
  Before dispatching workers, detect the IDE directory for skill path resolution:
167
252
 
253
+ ### Step 0.5.1: Check IDE Directories (Priority Order)
254
+
168
255
  1. **Check IDE directories in priority order**:
169
256
  - `.qoder/` → `.cursor/` → `.claude/` → `.speccrew/`
170
257
 
@@ -175,6 +262,44 @@ Before dispatching workers, detect the IDE directory for skill path resolution:
175
262
  3. **Verify skills directory exists**:
176
263
  - If `{ide_skills_dir}` does not exist, report error and stop
177
264
 
265
+ ### Step 0.5.2: Verify Dev Skills Availability
266
+
267
+ 1. **Verify `{ide_dir}/skills/` directory exists**
268
+
269
+ 2. **If NOT found** (no IDE directory contains a skills folder):
270
+ ```
271
+ ❌ IDE Skills Directory Not Found
272
+
273
+ Checked directories:
274
+ ├── .qoder/skills → ✗
275
+ ├── .cursor/skills → ✗
276
+ ├── .claude/skills → ✗
277
+ └── .speccrew/skills → ✗
278
+
279
+ REQUIRED ACTION:
280
+ - Ensure IDE configuration is correct
281
+ - Verify SpecCrew installation: npx speccrew init
282
+ - Retry workflow after fixing
283
+ ```
284
+ **STOP** — Do not proceed without valid skills directory.
285
+
286
+ 3. **If found**, verify platform-specific dev skills exist:
287
+ ```
288
+ ✅ IDE Skills Directory: {ide_dir}/skills
289
+
290
+ Available Dev Skills:
291
+ ├── speccrew-dev-backend/SKILL.md {✓ or ✗}
292
+ ├── speccrew-dev-frontend/SKILL.md {✓ or ✗}
293
+ ├── speccrew-dev-mobile/SKILL.md {✓ or ✗}
294
+ ├── speccrew-dev-desktop-electron/SKILL.md {✓ or ✗}
295
+ ├── speccrew-dev-desktop-tauri/SKILL.md {✓ or ✗}
296
+ └── speccrew-dev-review-*/SKILL.md {✓ or ✗}
297
+ ```
298
+
299
+ - Skills marked ✗ indicate missing implementations for those platforms
300
+ - If ALL dev skills are missing → **STOP** and report error
301
+ - If some skills missing but not needed for current platforms → proceed with available skills
302
+
178
303
  ---
179
304
 
180
305
  ## Step 1: Read System Design
@@ -275,13 +400,18 @@ If any pre-check fails:
275
400
 
276
401
  ## Step 4: Dispatch Per-Module Dev Skills
277
402
 
278
- > 🚨 **MANDATORY WORKER ENFORCEMENT REMINDER**:
279
- > - This Agent is a **pure orchestrator** — it MUST NOT write application code directly
280
- > - **ALL** development tasks **MUST** be dispatched to `speccrew-task-worker` agents via Agent tool
281
- > - **FORBIDDEN**: Creating source code files (*.java, *.vue, *.ts, *.py, etc.)
282
- > - **FORBIDDEN**: Direct invocation of `speccrew-dev-*` skills
283
- > - **FORBIDDEN**: Writing code as fallback if workers fail
284
- > - See **MANDATORY WORKER ENFORCEMENT** section at top of document for complete rules
403
+ > ⚠️ **MANDATORY RULES FOR PHASE 4 — WORKER DISPATCH ONLY**:
404
+ >
405
+ > 1. **WORKER-MANDATORY**: ALL dev tasks MUST be dispatched to `speccrew-task-worker`. Agent NEVER writes application code.
406
+ > 2. **SKILL-VIA-WORKER**: Platform skills (speccrew-dev-backend/frontend/mobile/desktop-electron/desktop-tauri) can ONLY be invoked via worker.
407
+ > 3. **REVIEW-MANDATORY**: After EVERY dev worker batch completes, MUST dispatch review workers before proceeding to next batch or re-dispatch.
408
+ > 4. **FORBIDDEN-ACTIONS**:
409
+ > - DO NOT create source code files (*.java, *.ts, *.vue, *.py, *.dart, *.rs, etc.)
410
+ > - DO NOT invoke dev skills directly (only via speccrew-task-worker)
411
+ > - DO NOT skip review phase even if dev worker reports success
412
+ > - DO NOT write code as fallback if worker fails
413
+ > 5. **PROGRESS-TRACKING**: Update DISPATCH-PROGRESS.json after each worker and review worker completes.
414
+ > 6. **ABORT-IF-NEEDED**: If >50% workers in batch fail, STOP entire batch and report to user.
285
415
 
286
416
  #### ⚠️ Stage 4 Directory Constraint
287
417
 
@@ -330,6 +460,36 @@ Before dispatching tasks, create or read dispatch progress file:
330
460
  node speccrew-workspace/scripts/update-progress.js init --file speccrew-workspace/iterations/{current}/04.development/DISPATCH-PROGRESS.json --stage 04_development --tasks '[{"id":"dev-web-vue-crm","platform":"web-vue","module":"crm","skill":"speccrew-dev-frontend","status":"pending"}]'
331
461
  ```
332
462
 
463
+ ### 4.0a Task Entry Format
464
+
465
+ Each task entry in DISPATCH-PROGRESS.json contains:
466
+
467
+ ```json
468
+ {
469
+ "id": "dev-backend-spring-F-CRM-01",
470
+ "platform": "backend-spring",
471
+ "module": "F-CRM-01-customer-list",
472
+ "feature_id": "F-CRM-01",
473
+ "skill_name": "speccrew-dev-backend",
474
+ "module_design_path": "03.system-design/backend-spring/F-CRM-01-customer-list-design.md",
475
+ "status": "pending",
476
+ "attempts": 0,
477
+ "error_category": null,
478
+ "error_message": null,
479
+ "output_files": null,
480
+ "review_skill": "speccrew-dev-review-backend",
481
+ "review_report": null
482
+ }
483
+ ```
484
+
485
+ **Status Lifecycle**: `pending` → `in_progress` → `in_review` → (`completed` | `partial` | `failed`)
486
+
487
+ **Key Fields**:
488
+ - `attempts`: Current retry count (max 3 total including initial)
489
+ - `error_category`: Error classification — `DEPENDENCY_MISSING` | `BUILD_FAILURE` | `VALIDATION_ERROR` | `RUNTIME_ERROR` | `BLOCKED`
490
+ - `review_skill`: Platform-specific review skill determined by `platform` prefix
491
+ - `review_report`: Path to review worker's report file
492
+
333
493
  **Task Status Enumeration:**
334
494
 
335
495
  | Status | Description |
@@ -351,13 +511,28 @@ Platform type mapping:
351
511
  | `web-*` | `speccrew-dev-frontend` |
352
512
  | `backend-*` | `speccrew-dev-backend` |
353
513
  | `mobile-*` | `speccrew-dev-mobile` |
354
- | `desktop-*` | `speccrew-dev-desktop` |
514
+ | `desktop-*` with Electron framework | `speccrew-dev-desktop-electron` |
515
+ | `desktop-*` with Tauri framework | `speccrew-dev-desktop-tauri` |
516
+
517
+ For desktop platforms, determine framework from INDEX.md Tech Stack Summary:
518
+ - `desktop-*` with Electron framework → `speccrew-dev-desktop-electron`
519
+ - `desktop-*` with Tauri framework → `speccrew-dev-desktop-tauri`
520
+ - If framework cannot be determined → **STOP** and report error
355
521
 
356
- **Review Skill (All Platforms):**
522
+ **Review Skill (Platform-Specific):**
357
523
 
358
- | Phase | Skill | Purpose |
359
- |-------|-------|---------|
360
- | 4.4 | `speccrew-dev-review` | Validate dev output against design doc, API contract, and code conventions |
524
+ Review skill is determined by platform prefix:
525
+
526
+ | Platform prefix | Review Skill |
527
+ |-----------------|--------------|
528
+ | `backend-*` | `speccrew-dev-review-backend` |
529
+ | `web-*` or `frontend-*` | `speccrew-dev-review-frontend` |
530
+ | `mobile-*` | `speccrew-dev-review-mobile` |
531
+ | `desktop-*` | `speccrew-dev-review-desktop` |
532
+
533
+ | Phase | Skill Family | Purpose |
534
+ |-------|--------------|---------|
535
+ | 4.4 | `speccrew-dev-review-*` | Validate dev output against design doc, API contract, and code conventions |
361
536
 
362
537
  ### 4.2 Build Module Task List
363
538
 
@@ -515,6 +690,14 @@ After processing a batch of completed workers:
515
690
 
516
691
  ### 4.4: Review Verification (MANDATORY)
517
692
 
693
+ > ⚠️ **MANDATORY RULES FOR PHASE 4.4 — REVIEW AFTER EVERY BATCH**:
694
+ >
695
+ > 1. **REVIEW-MANDATORY**: After EVERY dev worker in a batch completes, review MUST execute BEFORE next batch or re-dispatch
696
+ > 2. **REVIEW-FOR-ALL**: Both successful and failed dev workers require review for diagnosis
697
+ > 3. **BLOCKING-GATE**: Task cannot proceed to "completed" status without passing review
698
+ > 4. **NO-SKIPPING**: DO NOT skip review to speed up workflow — review is the quality gate
699
+ > 5. **RE-DISPATCH-AFTER-REVIEW**: Partial/failed review results trigger re-dispatch immediately (up to 3 total attempts)
700
+
518
701
  > **MANDATORY**: Review is NOT optional. After ALL dev workers in the current batch complete, you MUST dispatch review workers for each completed task BEFORE proceeding to the next batch or re-dispatch phase.
519
702
 
520
703
  **Review Dispatch Rule:**
@@ -522,10 +705,16 @@ After processing a batch of completed workers:
522
705
  - NO task may proceed to "completed" status without passing review
523
706
  - Review workers run AFTER all dev workers in the batch complete
524
707
 
525
- After each dev worker completes (status = "in_review"), dispatch a **separate** `speccrew-task-worker` agent to run the `speccrew-dev-review` skill:
708
+ After each dev worker completes (status = "in_review"), dispatch a **separate** `speccrew-task-worker` agent to run the platform-specific review skill.
709
+
710
+ **Review skill selection by platform:**
711
+ - `backend-*` → `speccrew-dev-review-backend`
712
+ - `web-*` or `frontend-*` → `speccrew-dev-review-frontend`
713
+ - `mobile-*` → `speccrew-dev-review-mobile`
714
+ - `desktop-*` → `speccrew-dev-review-desktop`
526
715
 
527
716
  Invoke `speccrew-task-worker` agent with:
528
- - skill_path: {ide_skills_dir}/speccrew-dev-review/SKILL.md
717
+ - skill_path: {ide_skills_dir}/{review_skill}/SKILL.md (where review_skill is determined by platform prefix above)
529
718
  - context:
530
719
  - design_doc_path: {task.module_design_path}
531
720
  - implementation_report_path: {dev_worker_report_path}
@@ -548,9 +737,21 @@ Invoke `speccrew-task-worker` agent with:
548
737
  review_queue = [tasks with status == "in_review"]
549
738
 
550
739
  for each task in review_queue:
740
+ // Determine review skill based on platform prefix
741
+ if task.platform starts with "backend-":
742
+ review_skill = "speccrew-dev-review-backend"
743
+ elif task.platform starts with "web-" or task.platform starts with "frontend-":
744
+ review_skill = "speccrew-dev-review-frontend"
745
+ elif task.platform starts with "mobile-":
746
+ review_skill = "speccrew-dev-review-mobile"
747
+ elif task.platform starts with "desktop-":
748
+ review_skill = "speccrew-dev-review-desktop"
749
+ else:
750
+ review_skill = "speccrew-dev-review-" + task.platform.split("-")[0] // fallback
751
+
551
752
  // Dispatch review worker
552
753
  Invoke `speccrew-task-worker` agent with:
553
- - skill_name: speccrew-dev-review
754
+ - skill_name: {review_skill}
554
755
  - context: (as specified above)
555
756
 
556
757
  wait for review worker completion
@@ -659,6 +860,28 @@ Verify cross-platform API consistency:
659
860
  - Request/response DTOs are consistent across platforms
660
861
  - Error handling conventions are aligned
661
862
 
863
+ ### 5.1a API Contract Alignment Checklist
864
+
865
+ For each platform design document that calls backend APIs:
866
+ - [ ] **Exact Path Match**: Each API call path matches API Contract exactly (route-by-route verification)
867
+ - [ ] **Request Format**: Request body/params match API Contract schema
868
+ - [ ] **Response Format**: Response object matches API Contract response schema
869
+ - [ ] **Error Codes**: Error handling uses API Contract error codes
870
+ - [ ] **Auth Headers**: Authentication headers consistent across all platforms
871
+
872
+ ### 5.1b Data Model Consistency Checklist
873
+
874
+ For shared data entities across platforms:
875
+ - [ ] **Field Definitions**: Same fields in web/mobile/backend designs
876
+ - [ ] **Field Types**: Data types consistent (String, Number, Date, Enum, etc.)
877
+ - [ ] **Enum Values**: If field is Enum, same enum values across platforms
878
+ - [ ] **Required Fields**: Same required/optional field status across platforms
879
+
880
+ ### 5.1c Cross-Feature Dependencies
881
+
882
+ - [ ] **Dependency Markers**: All [DEPENDENCY: F-XXX-NNN] marked clearly in design docs
883
+ - [ ] **Fallback Strategies**: Each dependency has defined fallback when upstream not ready
884
+
662
885
  ### 5.2 Data Consistency
663
886
 
664
887
  Verify shared data structures:
@@ -1,14 +1,14 @@
1
1
  ---
2
- name: speccrew-dev-desktop
3
- description: Desktop Development SOP. Guide System Developer Agent to implement desktop application code (Electron/Tauri) according to system design documents. Reads design blueprints, extracts task checklist, and executes implementation task by task with local quality checks.
4
- tools: Bash, Edit, Write, Glob, Grep, Read
2
+ name: speccrew-dev-desktop-electron
3
+ description: SpecCrew Electron Desktop Development Skill. Implements desktop application features using Electron framework based on system design documents. Handles main process (TypeScript/JavaScript), renderer process (React/Vue), IPC channels, and Electron Builder packaging.
4
+ tools: Read, Write, Glob, Grep, Bash
5
5
  ---
6
6
 
7
7
  # Trigger Scenarios
8
8
 
9
- - System Designer Agent has completed desktop system design, user requests implementation
10
- - User asks "Start desktop development", "Implement desktop app", "Code Electron/Tauri app"
11
- - Detailed design documents are confirmed in `03.system-design/{platform_id}/`
9
+ - System Designer Agent has completed Electron desktop system design
10
+ - User asks "Start Electron development", "Implement Electron app"
11
+ - Design documents confirmed in `03.system-design/{platform_id}/`
12
12
 
13
13
  # Workflow
14
14
 
@@ -16,7 +16,7 @@ tools: Bash, Edit, Write, Glob, Grep, Read
16
16
 
17
17
  > **These rules apply to Task Record document generation. Violation = task failure.**
18
18
 
19
- 1. **FORBIDDEN: `create_file` for Task Record** — NEVER use `create_file` to write the Task Record document. It MUST be created by copying the template then filling sections with `search_replace`. `create_file` produces truncated output on large files.
19
+ 1. **FORBIDDEN: Full-file rewrite for Task Record** — After the Task Record is initially created in Step 3.1a, NEVER use `create_file` or full-content overwrite on it. All subsequent updates MUST use targeted `search_replace` on specific sections.
20
20
 
21
21
  2. **FORBIDDEN: Full-file rewrite** — NEVER replace the entire Task Record content in a single operation. Always use targeted `search_replace` on specific sections.
22
22
 
@@ -40,19 +40,19 @@ Read in order:
40
40
 
41
41
  ## Step 2: Analyze Existing Code Structure
42
42
 
43
- Use Glob/Grep to understand current codebase:
43
+ Use Glob/Grep to understand current Electron codebase:
44
44
 
45
45
  | Target | Glob Pattern | Purpose |
46
46
  |--------|-------------|---------|
47
- | Main process | `src/main/**/*.{ts,js}` or `src-tauri/src/**/*.rs` | Understand main process structure |
48
- | Renderer process | `src/renderer/**/*.{tsx,vue,html}` or `src/**/*.{tsx,vue}` | Understand renderer structure |
49
- | IPC definitions | `src/main/ipc/**/*` or `src-tauri/src/commands/**/*.rs` | Understand IPC channel patterns |
50
- | Window management | `src/main/window/**/*` or patterns with `BrowserWindow` | Understand window patterns |
47
+ | Main process | `src/main/**/*.{ts,js}` | Understand main process structure |
48
+ | Renderer process | `src/renderer/**/*.{tsx,vue,html}` | Understand renderer structure |
49
+ | IPC definitions | `src/main/ipc/**/*` | Understand IPC channel patterns |
50
+ | Window management | `src/main/window/**/*` | Understand window patterns |
51
51
  | Preload scripts | `src/preload/**/*` or `preload.{ts,js}` | Understand preload patterns |
52
- | Native modules | `src/main/native/**/*` or binding files | Identify native dependencies |
53
- | State management | `src/renderer/stores/**/*` or `src/stores/**/*` | Understand store pattern |
54
- | API layer | `src/renderer/apis/**/*` or `src/apis/**/*` | Understand API encapsulation |
55
- | Configuration files | `package.json`, `tauri.conf.json`, `electron-builder.yml` | Build and config patterns |
52
+ | Native modules | `src/main/native/**/*` | Identify native dependencies |
53
+ | State management | `src/renderer/stores/**/*` | Understand store pattern |
54
+ | API layer | `src/renderer/apis/**/*` | Understand API encapsulation |
55
+ | Configuration files | `package.json`, `electron-builder.yml` | Build and config patterns |
56
56
 
57
57
  Document findings for reference in later steps.
58
58
 
@@ -64,7 +64,9 @@ Document findings for reference in later steps.
64
64
 
65
65
  #### 3.1a Copy Template to Task Record Path
66
66
 
67
- 1. **Read the template file**: `speccrew-dev-desktop/templates/TASK-RECORD-TEMPLATE.md`
67
+ > Note: This is the ONLY step where `create_file` is allowed for the Task Record. All later updates in Step 4-6 MUST use `search_replace` on individual sections.
68
+
69
+ 1. **Read the template file**: `templates/TASK-RECORD-TEMPLATE.md`
68
70
  2. **Replace top-level placeholders** (feature name, platform ID, iteration info)
69
71
  3. **Create the document** using `create_file`:
70
72
  - Target path: `speccrew-workspace/iterations/{number}-{type}-{name}/04.development/{platform_id}/[feature-name]-task.md`
@@ -80,7 +82,7 @@ Fill each section with task checklist and design metadata extracted from input d
80
82
  > - **MUST use `search_replace` to fill each section individually**
81
83
  > - **All section titles MUST be preserved**
82
84
 
83
- ### 3.2 Desktop-Specific Task Types
85
+ ### 3.2 Electron-Specific Task Types
84
86
 
85
87
  **Conditional Task Selection:**
86
88
 
@@ -102,28 +104,28 @@ IF task involves security configuration THEN
102
104
  ```
103
105
 
104
106
  | Task Type | Description | Example |
105
- |-----------|-------------|---------||
107
+ |-----------|-------------|---------|
106
108
  | Main Process Module | Backend logic running in main process | Window manager, IPC handlers, native integrations |
107
109
  | Renderer Page/Component | UI components in renderer process | React/Vue components, pages, layouts |
108
- | IPC Channel Handler | Communication bridge between processes | `ipcMain.handle`, `#[tauri::command]` |
110
+ | IPC Channel Handler | Communication bridge between processes | `ipcMain.handle`, `ipcRenderer.invoke` |
109
111
  | Preload Script | Context bridge for secure renderer access | `contextBridge.exposeInMainWorld` |
110
- | Window Management | Window creation, lifecycle, multi-window | BrowserWindow, Window configuration |
112
+ | Window Management | Window creation, lifecycle, multi-window | `BrowserWindow`, window configuration |
111
113
  | Native Integration | File system, system tray, notifications | Native API wrappers |
112
114
  | Menu/Shortcut | Application menus, keyboard shortcuts | Menu templates, global shortcuts |
113
- | Auto-Update | Update checking and installation | electron-updater, tauri-updater |
115
+ | Auto-Update | Update checking and installation | `electron-updater` |
114
116
  | Security Hardening | Context isolation, CSP, permissions | Preload scripts, security configs |
115
117
 
116
118
  ### Task ID Prefix
117
119
 
118
- Use `DT-` prefix for desktop tasks: `DT-001`, `DT-002`, etc.
120
+ Use `EL-` prefix for Electron tasks: `EL-001`, `EL-002`, etc.
119
121
 
120
122
  ### Task Checklist Table
121
123
 
122
124
  | Task ID | Module | Description | Target Files | IPC Channel | Native Integration | Dependencies | Status |
123
125
  |---------|--------|-------------|--------------|-------------|-------------------|--------------|--------|
124
- | DT-001 | MainProcess | Create window manager | `src/main/window/manager.ts` | - | Window creation | - | Pending |
125
- | DT-002 | IPC | Implement file operations handler | `src/main/ipc/file.ts` | `file:read`, `file:write` | File system | DT-001 | Pending |
126
- | DT-003 | Renderer | Create main window UI | `src/renderer/pages/Main.tsx` | `file:*` | - | DT-002 | Pending |
126
+ | EL-001 | MainProcess | Create window manager | `src/main/window/manager.ts` | - | Window creation | - | Pending |
127
+ | EL-002 | IPC | Implement file operations handler | `src/main/ipc/file.ts` | `file:read`, `file:write` | File system | EL-001 | Pending |
128
+ | EL-003 | Renderer | Create main window UI | `src/renderer/pages/Main.tsx` | `file:*` | - | EL-002 | Pending |
127
129
 
128
130
  **Status**: Pending / In Progress / Completed / Blocked
129
131
 
@@ -143,7 +145,7 @@ Follow dependency order:
143
145
 
144
146
  ### 4.2 Coding Standards
145
147
 
146
- - **Main Process**: Follow conventions-dev.md for Electron/Tauri backend code
148
+ - **Main Process**: Follow conventions-dev.md for Electron backend code
147
149
  - **Renderer Process**: Follow frontend conventions (React/Vue/etc.)
148
150
  - **IPC Channels**: Use exact channel names from design document
149
151
  - **Types**: Use TypeScript types defined in design document
@@ -165,20 +167,12 @@ After completing each task, run the following checks:
165
167
 
166
168
  ### 5.1 Build Verification
167
169
 
168
- **Electron**:
169
170
  ```bash
170
171
  npm run build:dev
171
172
  # or
172
173
  npm run electron:dev
173
174
  ```
174
175
 
175
- **Tauri**:
176
- ```bash
177
- npm run tauri dev
178
- # or
179
- npm run tauri build --debug
180
- ```
181
-
182
176
  ### 5.2 Lint Check
183
177
 
184
178
  ```bash
@@ -195,7 +189,7 @@ npx tsc --noEmit
195
189
 
196
190
  ### 5.4 Security Audit
197
191
 
198
- Perform security checks according to Security Audit Reference (see Reference Guides section).
192
+ Perform security checks according to Security Audit Reference.
199
193
 
200
194
  ### 5.5 Unit Tests
201
195
 
@@ -223,7 +217,7 @@ If implementation deviates from design document:
223
217
  **Record in task file**:
224
218
  ```markdown
225
219
  ### Deviation Log
226
- - DT-002: Changed IPC payload structure from {original} to {new} because {reason}
220
+ - EL-002: Changed IPC payload structure from {original} to {new} because {reason}
227
221
  ```
228
222
 
229
223
  ## Step 7: Record Technical Debt
@@ -243,9 +237,9 @@ If technical debt is identified:
243
237
  After all tasks complete, present summary:
244
238
 
245
239
  ```
246
- Desktop Development Complete: {feature-name}
240
+ Electron Development Complete: {feature-name}
247
241
  Platform: {platform_id}
248
- Framework: {Electron/Tauri}
242
+ Framework: Electron
249
243
 
250
244
  Tasks Completed: {count}
251
245
  ├── Main Process: {count}
@@ -276,7 +270,7 @@ At the end of Step 8 (or if the skill fails at any point), output a structured T
276
270
  - {file_path_1}
277
271
  - {file_path_2}
278
272
  - ...
279
- - **Summary**: Desktop module {module_name} implemented with {X} tasks completed
273
+ - **Summary**: Electron module {module_name} implemented with {X} tasks completed
280
274
  ```
281
275
 
282
276
  ### Failure Report
@@ -298,18 +292,12 @@ If the skill fails at any step:
298
292
  ```
299
293
 
300
294
  **Error Category Definitions**:
301
- - `DEPENDENCY_MISSING`: Required Node.js/npm or Rust dependency not available
302
- - `BUILD_FAILURE`: Electron/Tauri build error, native compilation failure
303
- - `VALIDATION_ERROR`: ESLint, TypeScript type check, Rust clippy, or test failure
295
+ - `DEPENDENCY_MISSING`: Required Node.js/npm dependency not available
296
+ - `BUILD_FAILURE`: Electron build error, native compilation failure
297
+ - `VALIDATION_ERROR`: ESLint, TypeScript type check, or test failure
304
298
  - `RUNTIME_ERROR`: App crash on launch, runtime exception, IPC communication failure
305
299
  - `BLOCKED`: Blocked by external dependency, native module issue, or unresolved design issue
306
300
 
307
- **Verify automatically:**
308
- 1. All IPC channels working correctly
309
- 2. Context isolation properly configured
310
- 3. Native integrations working as expected
311
- 4. No security concerns introduced
312
-
313
301
  ---
314
302
 
315
303
  # Reference Guides
@@ -330,7 +318,7 @@ If the skill fails at any step:
330
318
  | Rule | Description |
331
319
  |------|-------------|
332
320
  | **Design Document READ-ONLY** | Design documents are reference only - do not modify. Record deviations in task file. |
333
- | **Actual Framework Syntax** | All code MUST use actual framework/library syntax from techs knowledge |
321
+ | **Actual Framework Syntax** | All code MUST use actual Electron API syntax |
334
322
  | **Status Markers Required** | Use [EXISTING], [MODIFIED], [NEW] markers for all components, modules, and IPC handlers |
335
323
  | **Follow Techs Conventions** | Naming, directory structure, patterns must follow techs knowledge |
336
324
  | **Security First** | Never disable contextIsolation; never enable nodeIntegration in renderer |