speccrew 0.7.63 → 0.7.64

package/.speccrew/skills/speccrew-sd-framework-evaluate/SKILL.md

@@ -14,248 +14,4 @@ tools: Read, Write, Glob, Grep
 
 <!-- @agentflow: SKILL.xml -->
 
-> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `speccrew-workspace/docs/rules/agentflow-spec.md`
-
-## Workflow
-
-## Absolute Constraints
-
-> **These rules apply to ALL steps. Violation = task failure.**
-
-1. **READ-ONLY on Feature Spec and API Contract** — NEVER modify Feature Spec or API Contract documents. Only read for analysis.
-2. **READ-ONLY on techs knowledge** — NEVER modify techs knowledge files. Only read for capability assessment.
-3. **Evidence-based evaluation** — Every recommendation MUST cite specific Feature Spec requirements and specific tech stack limitations.
-4. **No assumptions** — DO NOT assume framework capabilities. Only recommend frameworks with documented capabilities.
-
-## Step 1: Read Inputs
-
-**Input Parameters** (from agent context):
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `feature_spec_paths` | Yes | Array of Feature Spec file paths |
-| `api_contract_paths` | Yes | Array of API Contract file paths |
-| `techs_knowledge_paths` | Yes | Object with platform_id → knowledge paths mapping |
-| `iteration_path` | Yes | Current iteration directory path |
-| `output_path` | No | Output file path (default: `iteration_path/03.system-design/framework-evaluation.md`) |
-
-Read in order:
-
-1. **All Feature Spec documents** — Extract functional requirements, especially:
-   - Real-time features (WebSocket, SSE, push notifications)
-   - File processing (upload, download, preview, conversion)
-   - Data visualization (charts, dashboards, reports)
-   - Rich text / editor features
-   - Map / geolocation features
-   - Payment / third-party integrations
-   - Search / filtering / pagination patterns
-   - Media processing (image, video, audio)
-
-2. **All API Contract documents** — Extract:
-   - Communication protocols (REST, GraphQL, WebSocket, gRPC)
-   - Authentication patterns (JWT, OAuth, Session)
-   - Data formats (JSON, protobuf, multipart)
-
-3. **Techs knowledge per platform**:
-   - `tech-stack.md` — Current frameworks, libraries, versions
-   - `architecture.md` — Current architecture patterns
-   - `conventions-design.md` — Design conventions
-   - `conventions-dev.md` — Development conventions
-
-## Step 2: Gap Analysis
-
-For each requirement extracted in Step 1, evaluate against current tech stack:
-
-### 2.1 Build Capability Matrix
-
-| Requirement Category | Specific Requirement | Source (Feature ID) | Current Stack Support | Gap? |
-|---------------------|---------------------|--------------------|-----------------------|------|
-| Real-time | WebSocket connections | F-CRM-01 | Not in current stack | YES |
-| File Processing | PDF preview | F-ORD-02 | Not in current stack | YES |
-| Data Viz | Dashboard charts | F-RPT-01 | Not in current stack | YES |
-| Authentication | JWT token | F-SYS-01 | Already supported | NO |
-
-### 2.2 Categorize Gaps
-
-Group identified gaps by category:
-
-- **Critical Gaps**: Core functionality cannot be implemented without new framework
-- **Enhancement Gaps**: Functionality possible but significantly better with dedicated library
-- **Optional Gaps**: Nice-to-have improvements, current stack can handle acceptably
-
-## Step 3: Framework Research
-
-For each identified gap (Critical and Enhancement only):
-
-### 3.1 Evaluate Candidates
-
-For each gap, research and evaluate 1-3 candidate frameworks/libraries:
-
-| Evaluation Criteria | Description |
-|--------------------|-------------|
-| **Functionality Fit** | Does it solve the specific capability gap? |
-| **License** | MIT, Apache 2.0, BSD preferred. GPL requires flagging. |
-| **Maturity** | GitHub stars, npm downloads, last release date, version stability |
-| **Bundle Size** | Impact on frontend bundle (if applicable) |
-| **Integration Complexity** | How much existing code needs modification? |
-| **Community & Docs** | Documentation quality, community support, ecosystem |
-
-### 3.2 Make Recommendations
-
-For each gap, provide a single primary recommendation with justification.
-
-## Step 4: Generate Report
-
-Write the framework evaluation report to `output_path`.
-
-### Report Structure (When Gaps Found)
-
-```markdown
-# Framework Evaluation Report — iteration_name
-
-## 1. Evaluation Summary
-
-- **Iteration**: iteration_name
-- **Feature Specs Analyzed**: feature_count
-- **Platforms Evaluated**: platform_count
-- **Capability Gaps Found**: gap_count
-- **New Frameworks Recommended**: framework_count
-
-## 2. Capability Gap Analysis
-
-### 2.1 Gap Summary
-
-| # | Gap Category | Specific Gap | Severity | Source Features | Recommendation |
-|---|-------------|-------------|----------|----------------|---------------|
-| 1 | Real-time | WebSocket support | Critical | F-CRM-01, F-MSG-01 | Socket.IO |
-| 2 | Data Viz | Chart rendering | Enhancement | F-RPT-01 | ECharts |
-| ... | ... | ... | ... | ... | ... |
-
-### 2.2 Detailed Gap Analysis
-
-#### Gap 1: {Gap Name}
-
-**Requirement Source**: {Feature IDs and specific requirement text}
-**Current Stack Status**: {What the current stack provides/lacks}
-**Impact**: {What cannot be implemented without addressing this gap}
-
-## 3. Framework Recommendations
-
-### 3.1 Recommendation Summary
-
-| # | Framework | Version | License | For Gap | Platform | Integration Impact |
-|---|-----------|---------|---------|---------|----------|-------------------|
-| 1 | Socket.IO | ^4.x | MIT | WebSocket support | backend + web | Medium |
-| 2 | ECharts | ^5.x | Apache 2.0 | Chart rendering | web | Low |
-
-### 3.2 Detailed Recommendations
-
-#### Recommendation 1: {Framework Name}
-
-- **Solves Gap**: {gap description}
-- **License**: {license type}
-- **Maturity**: {stars, downloads, last release}
-- **Integration Impact**: Low / Medium / High
-- **Integration Notes**: {specific integration considerations}
-- **Alternatives Considered**: {other options and why not chosen}
-
-## 4. No-Change Confirmations
-
-Capabilities already covered by current stack:
-- {capability 1}: Covered by {existing framework}
-- {capability 2}: Covered by {existing framework}
-
-## 5. Version Constraints
-
-| Framework | Required Version | Constraint Reason |
-|-----------|-----------------|-------------------|
-| {name} | {version range} | {compatibility reason} |
-```
-
-### Simplified Report Structure (When No Gaps Found)
-
-```markdown
-# Framework Evaluation Report — iteration_name
-
-## 1. Evaluation Summary
-
-- **Feature Specs Analyzed**: feature_count
-- **Platforms Evaluated**: platform_count
-- **Capability Gaps Found**: 0
-- **New Frameworks Recommended**: 0
-
-## 2. Assessment
-
-All Feature Spec requirements can be fully implemented with the current technology stack. No new frameworks or libraries are needed.
-
-### Capabilities Confirmed
-- {list each major capability confirmed as supported}
-
-## 3. Conclusion
-
-Current tech stack is sufficient. Proceed to system design without framework changes.
-```
-
-## Step 5: Output Task Completion Report
-
-After writing the report, output:
-
-```
---- TASK COMPLETION REPORT ---
-Task: Framework Evaluation
-Status: SUCCESS
-Output: output_path
-Gaps Found: gap_count
-Frameworks Recommended: framework_count
---- END REPORT ---
-```
-
-If any step fails:
-
-```
---- TASK COMPLETION REPORT ---
-Task: Framework Evaluation  
-Status: FAILED
-Error: {specific error description}
-Failed At: Step {N}
---- END REPORT ---
-```
-
-## OUTPUT EFFICIENCY RULES
-
-When executing this skill:
-
-1. **Direct-to-File Output**: All design content (architecture diagrams, API mappings, component specifications, data models) MUST be written directly to the output file
-2. **Minimal Conversation Output**: Only output:
-   - Block execution announcements (1 line each): `"[Block XX] Designing..."`
-   - Error messages requiring attention
-   - Task Completion Report (final summary)
-3. **FORBIDDEN in conversation**:
-   - ❌ Full document sections or drafts
-   - ❌ Mermaid diagrams displayed in chat
-   - ❌ API endpoint listings
-   - ❌ Data model tables
-   - ❌ Architecture descriptions longer than 2 lines
-4. **Rationale**: Workers run in batch mode. Displaying design content in conversation wastes context window and provides no value since content goes to file anyway.
-
-# Key Rules
-
-| Rule | Description |
-|------|-------------|
-| **READ-ONLY Inputs** | Feature Spec, API Contract, and techs knowledge are reference only — never modify |
-| **Evidence-based** | Every gap and recommendation must cite specific requirement sources |
-| **Gap Categories** | Only Critical and Enhancement gaps require framework recommendations |
-| **License Awareness** | GPL and copyleft licenses must be flagged in recommendations |
-| **No Assumptions** | Only recommend frameworks with documented, verified capabilities |
-
-# Checklist
-
-- [ ] All Feature Spec documents read and requirements extracted
-- [ ] All API Contract documents read and protocols identified
-- [ ] Techs knowledge loaded for all platforms
-- [ ] Capability matrix built with all requirements mapped
-- [ ] Gaps categorized by severity (Critical/Enhancement/Optional)
-- [ ] Framework candidates evaluated against criteria
-- [ ] Primary recommendations made for each gap
-- [ ] Report generated with correct structure
-- [ ] Task Completion Report output
+> **REQUIRED**: Read and execute the XML workflow above. The XML contains the complete workflow definition including all steps, rules, conditions, and checklist.

package/.speccrew/skills/speccrew-sd-framework-evaluate/SKILL.xml

@@ -36,6 +36,19 @@
     <field name="text">Only recommend frameworks with documented capabilities</field>
   </block>
 
+  <block type="rule" id="R5" level="mandatory" desc="Direct-to-File Output">
+    <field name="text">All design content MUST be written directly to the output file</field>
+  </block>
+
+  <block type="rule" id="R6" level="mandatory" desc="Minimal Conversation Output">
+    <field name="text">Only output block execution announcements, error messages, and Task Completion Report</field>
+  </block>
+
+  <block type="rule" id="R7" level="forbidden" desc="No conversation document output">
+    <field name="text">NEVER display full document sections, Mermaid diagrams, API endpoint listings, data model tables in conversation</field>
+    <field name="text">NEVER display architecture descriptions longer than 2 lines in conversation</field>
+  </block>
+
   <!-- ============================================================
        Main Processing Sequence
        ============================================================ -->
@@ -219,8 +232,34 @@ Frameworks Recommended: ${recommendations.length}
       </branch>
     </block>
 
+    <block type="checkpoint" id="CP2" name="final_checklist" desc="Framework Evaluation Final Checklist">
+      <field name="conditions">
+        feature_specs_read: all Feature Spec documents read and requirements extracted,
+        api_contracts_read: all API Contract documents read and protocols identified,
+        techs_knowledge_loaded: techs knowledge loaded for all platforms,
+        capability_matrix_built: capability matrix built with all requirements mapped,
+        gaps_categorized: gaps categorized by severity (Critical/Enhancement/Optional),
+        framework_candidates_evaluated: framework candidates evaluated against criteria,
+        primary_recommendations_made: primary recommendations made for each gap,
+        report_generated: report generated with correct structure,
+        task_completion_report_output: task completion report output
+      </field>
+    </block>
+
   </sequence>
 
+  <!-- ============================================================
+       Failure Report Format
+       ============================================================ -->
+  <block type="event" id="E4" action="log" level="error" desc="Task failure report">
+    <field name="message">--- TASK COMPLETION REPORT ---
+Task: Framework Evaluation
+Status: FAILED
+Error: {specific error description}
+Failed At: Step {N}
+--- END REPORT ---</field>
+  </block>
+
   <!-- ============================================================
        Output Results
        ============================================================ -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speccrew",
-  "version": "0.7.63",
+  "version": "0.7.64",
   "description": "Spec-Driven Development toolkit for AI-powered IDEs",
   "author": "charlesmu99",
   "repository": {