speccrew 0.5.0 → 0.5.2

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

@@ -0,0 +1,238 @@
+---
+name: speccrew-sd-framework-evaluate
+description: Framework Evaluation Skill for System Designer. Analyzes Feature Spec requirements against current technology stack capabilities, identifies capability gaps, evaluates potential open-source frameworks/libraries, and generates a framework-evaluation.md report. Invoked by System Designer Agent during Phase 3.
+tools: Read, Write, Glob, Grep
+---
+
+# Trigger Scenarios
+
+- System Designer Agent dispatches this skill with Feature Spec paths and techs knowledge paths
+- User requests framework evaluation for current iteration
+- Need to assess technology stack gaps before system design
+
+# 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 ---
+```
+
+# 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speccrew",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Spec-Driven Development toolkit for AI-powered IDEs",
   "author": "charlesmu99",
   "repository": {
@@ -32,6 +32,5 @@
     "agents",
     "skills"
   ],
-  "license": "MIT",
-  "scripts": {}
+  "license": "MIT"
 }

package/.speccrew/skills/speccrew-fd-feature-generate/SKILL.md

@@ -1,243 +0,0 @@
----
-name: speccrew-fd-feature-generate
-description: Feature Spec Generation SOP. Reads .feature-analysis.md and .feature-design-data.md interface contracts, assembles complete Feature Spec document using template-first workflow. Handles Checkpoint B user confirmation before writing files. Use when Feature Designer needs to generate final Feature Spec document from completed design data.
-tools: Read, Write, Glob, Grep
----
-
-# Skill Overview
-
-Generates final Feature Spec document from completed design data. Reads intermediate artifacts and assembles complete specification using template-first workflow.
-
-## Trigger Scenarios
-
-- Feature design data ready (`.feature-design-data.md` exists)
-- Feature analysis complete (`.feature-analysis.md` exists)
-- Final Feature Spec document generation needed
-
----
-
-# Workflow
-
-## Absolute Constraints
-
-> **Violation = task failure**
-
-### ABORT CONDITIONS
-- `.feature-analysis.md` missing → **HARD STOP**
-- `.feature-design-data.md` missing → **HARD STOP**
-- Template file missing → **HARD STOP**
-- **NEVER skip preconditions verification**
-
-### FORBIDDEN
-- `create_file` for final documents — use template + `search_replace`
-- Full-file rewrite — use targeted `search_replace` per section
-
-### MANDATORY
-- **Template-first workflow** — Step 4 (copy template) MUST precede Step 5 (fill content)
-
----
-
-## Step 1: Read Input & Verify Preconditions
-
-### 1.1 Input Parameters
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `feature_analysis_path` | Yes | Path to `.feature-analysis.md` |
-| `feature_design_data_path` | Yes | Path to `.feature-design-data.md` |
-| `feature_id` | No | Feature identifier (e.g., F-CRM-01) |
-| `feature_name` | No | Feature name |
-| `feature_type` | No | Page+API or API-only |
-| `output_path` | No | Custom output path (auto-generated if not provided) |
-| `skip_checkpoint` | No | Boolean. If true, skip Checkpoint B (batch mode) |
-
-### 1.2 Verify Input Files
-
-**IF either file missing → ABORT:**
-```
-❌ ERROR: Prerequisite files not found.
-   Missing: [filename]
-   
-   This skill requires completed feature analysis and design.
-   Please run speccrew-fd-feature-analyze and speccrew-fd-feature-design first.
-```
-
-### 1.3 Read Files
-
-1. Read `.feature-analysis.md` — extract: Function Breakdown, [EXISTING]/[MODIFIED]/[NEW] counts
-2. Read `.feature-design-data.md` — extract: Frontend Design, Backend Design, Data Model, Business Rules
-3. Read Feature Spec template: `speccrew-fd-feature-design/templates/FEATURE-SPEC-TEMPLATE.md`
-
----
-
-## Step 2: Build Design Summary
-
-Extract statistics from intermediate artifacts:
-
-| Metric | Source |
-|--------|--------|
-| Functions Designed | `.feature-analysis.md` Function Breakdown section |
-| [EXISTING] / [MODIFIED] / [NEW] counts | Function markers in analysis |
-| Frontend Components | `.feature-design-data.md` Frontend Design (0 if API-only) |
-| Backend Interfaces | `.feature-design-data.md` Backend Design API count |
-| Data Entities | `.feature-design-data.md` Data Model (new/modified) |
-
----
-
-## Step 3: Checkpoint B — User Confirmation
-
-> **Skip this step if `skip_checkpoint=true`**
-
-### 3.1 Present Summary
-
-```
-Feature Design Summary for: {feature-name}
-
-Functions Designed: {count}
-├── [EXISTING] {count} functions reuse existing capabilities
-├── [MODIFIED] {count} functions enhance existing features
-└── [NEW] {count} functions are brand new
-
-Frontend Components: {count} pages/components
-Backend Interfaces: {count} APIs
-Data Entities: {count} new, {count} modified
-
-Output File: {filename}
-```
-
-### 3.2 Confirm 5 Questions
-
-**HARD STOP** — Wait for user confirmation on:
-
-1. Is the frontend prototype appropriate? (if applicable)
-2. Is the backend logic flow correct and complete?
-3. Is the data model reasonable and extensible?
-4. Are all business rules captured?
-5. [Legacy Master-Sub] Is the module breakdown appropriate?
-
-### 3.3 Update Checkpoint
-
-Update `.checkpoints.json`:
-```json
-{
-  "feature_spec_review": {
-    "passed": true,
-    "confirmed_at": "{timestamp}",
-    "description": "Feature specification confirmed"
-  }
-}
-```
-
----
-
-## Step 4: Determine Output Path & Copy Template
-
-### 4.1 Determine Output Path
-
-| Mode | Path Pattern |
-|------|--------------|
-| Single Feature | `{iteration}/02.feature-design/{feature-id}-{feature-name}-feature-spec.md` |
-| Legacy Single | `{iteration}/02.feature-design/[feature-name]-feature-spec.md` |
-| Legacy Master-Sub | Multiple files (master + sub-specs) |
-
-### 4.2 Copy Template
-
-1. Read template: `speccrew-fd-feature-design/templates/FEATURE-SPEC-TEMPLATE.md`
-2. Replace top-level placeholders: `{Feature Name}`, `{Feature ID}`, etc.
-3. **Create document** using `create_file` with template content
-4. Verify complete section structure exists
-
----
-
-## Step 5: Fill Sections Using search_replace
-
-Map data sources to template sections:
-
-| Template Section | Data Source |
-|------------------|-------------|
-| Feature Overview | `.feature-analysis.md` Feature Information + summary |
-| Function Breakdown | `.feature-analysis.md` Function Breakdown |
-| Frontend Design | `.feature-design-data.md` Frontend Design |
-| Backend Design | `.feature-design-data.md` Backend Design |
-| Data Model | `.feature-design-data.md` Data Model |
-| Business Rules | `.feature-design-data.md` Business Rules |
-| Cross-Module Interactions | `.feature-design-data.md` Cross-Module (if applicable) |
-
-**Rules:**
-- Use `search_replace` for each section individually
-- Preserve all section titles and numbering
-- No applicable content → replace placeholder with "N/A"
-- Legacy Master-Sub: repeat Step 4+5 for each sub-spec
-
----
-
-## Step 6: Mermaid Diagram Compliance
-
-Verify all Mermaid diagrams follow compatibility rules:
-
-- Use only basic node definitions: `A[text content]`
-- No HTML tags (e.g., `<br/>`)
-- No nested subgraphs
-- No `direction` keyword
-- No `style` definitions
-- Standard `graph TB/LR` or `sequenceDiagram` syntax only
-
-Reference: `speccrew-workspace/docs/rules/mermaid-rule.md`
-
----
-
-## Step 7: Update Checkpoints
-
-Update `.checkpoints.json`:
-- Set `feature_spec_review.passed = true`
-- Set `confirmed_at` timestamp
-- Preserve existing checkpoint states
-
----
-
-# Reference Guides
-
-## Legacy Mode Backward Compatibility
-
-When `feature_id` is NOT provided:
-
-**Single Feature Spec:**
-```
-02.feature-design/[feature-name]-feature-spec.md
-```
-
-**Master-Sub Feature Specs:**
-```
-02.feature-design/
-├── [feature-name]-feature-spec.md          # Master (overview + cross-module)
-├── [feature-name]-sub-[module1]-spec.md    # Sub: Module 1
-└── [feature-name]-sub-[module2]-spec.md    # Sub: Module 2
-```
-
-Master spec MUST include: overall overview, cross-module diagram, module list, interface contracts.
-
----
-
-# Key Rules
-
-| Rule | Description |
-|------|-------------|
-| **Template-First** | Copy template before filling content |
-| **search_replace Only** | Never use `create_file` for section updates |
-| **Checkpoint B** | Get user confirmation before writing files |
-| **Mermaid Compliance** | Follow mermaid-rule.md guidelines |
-| **Clear Markers** | Use [EXISTING]/[MODIFIED]/[NEW] consistently |
-
----
-
-# Output Checklist
-
-- [ ] Both input files verified and read
-- [ ] Design summary built with statistics
-- [ ] Checkpoint B passed (or skipped via flag)
-- [ ] Output path determined
-- [ ] Template copied using `create_file`
-- [ ] All sections filled using `search_replace`
-- [ ] Mermaid diagrams verified compliant
-- [ ] `.checkpoints.json` updated
-- [ ] [Legacy Master-Sub] All sub-specs generated