speccrew 0.1.0

package/.speccrew/skills/speccrew-test-execute/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: speccrew-test-execute
+description: Executes generated test code, collects results, performs deviation detection against expected outcomes, and generates comprehensive test reports and individual bug reports for failed test cases.
+tools: Read, Write, Glob, Grep, Terminal
+---
+
+# Trigger Scenarios
+
+- When speccrew-test-manager dispatches test execution after test code is confirmed
+- When user explicitly requests test execution and reporting
+- When user mentions "run tests", "execute tests", "generate test report"
+
+# Workflow
+
+## Step 1: Read Inputs
+
+Read the following documents in order:
+
+1. **Test Cases Document**: `test_cases_path`
+   - Contains test case definitions with TC IDs, descriptions, and expected results
+   - Used for deviation detection against actual results
+
+2. **Test Code Plan**: `test_code_plan_path`
+   - Contains mapping between TC IDs and test file locations
+   - Identifies platform_id and corresponding test framework
+
+3. **Platform Configuration**:
+   - Confirm platform_id (frontend/backend/desktop/mobile)
+   - Identify test framework (jest/vitest/pytest/junit/etc.)
+
+**Input Validation**:
+- Verify all required paths are provided and files exist
+- If any input is missing, report to user and stop
+
+## Step 2: Environment Pre-check
+
+Before executing tests, verify the environment is ready:
+
+### 2.1 Check Test Dependencies
+
+| Platform | Dependency Check Command |
+|----------|--------------------------|
+| Frontend | `npm ls jest` or `npm ls vitest` |
+| Backend (Node) | `npm ls jest` or `npm ls mocha` |
+| Backend (Python) | `pip show pytest` |
+| Desktop | Platform-specific dependency check |
+| Mobile | Platform-specific dependency check |
+
+If dependencies are missing:
+```
+Environment Error: Missing test dependencies
+- Missing: {dependency_name}
+- Install command: {install_command}
+
+Please install dependencies before proceeding.
+```
+
+### 2.2 Check Test Configuration Files
+
+Verify test configuration files exist:
+
+| Framework | Config Files |
+|-----------|--------------|
+| Jest | `jest.config.js`, `jest.config.ts`, or `jest` field in `package.json` |
+| Vitest | `vitest.config.ts` or `vite.config.ts` with test section |
+| Pytest | `pytest.ini`, `pyproject.toml`, or `setup.cfg` |
+| JUnit | `junit.xml` or build tool configuration |
+
+### 2.3 Check Service Dependencies
+
+Determine if the system under test requires:
+- Database service running
+- API server running
+- Mock services configured
+
+**Checkpoint A**: If any environment check fails, report specific missing items and stop execution.
+
+## Step 3: Execute Tests
+
+### 3.1 Determine Test Command
+
+Based on platform and framework, execute appropriate test command:
+
+| Platform | Framework | Default Command |
+|----------|-----------|-----------------|
+| Frontend | Jest | `npm test -- --json --outputFile=test-results.json` |
+| Frontend | Vitest | `npx vitest run --reporter=json --outputFile=test-results.json` |
+| Backend | Jest | `npm test -- --json --outputFile=test-results.json` |
+| Backend | Pytest | `pytest --json-report --json-report-file=test-results.json` |
+| Desktop | Platform-specific | Depends on technology stack |
+| Mobile | Platform-specific | Depends on technology stack |
+
+### 3.2 Execute and Collect Output
+
+Run the test command and collect:
+- **Standard Output (stdout)**: Test progress and summary
+- **Standard Error (stderr)**: Error messages and stack traces
+- **Exit Code**: Success (0) or failure (non-zero)
+- **Execution Duration**: Total time taken
+- **Result Files**: JSON/XML reports if supported by framework
+
+### 3.3 Handle Execution Errors
+
+If test execution fails completely (e.g., syntax errors, configuration errors):
+```
+Test Execution Failed
+- Error Type: {error_type}
+- Error Message: {error_message}
+- Suggested Fix: {suggestion}
+
+Please fix the issue and retry.
+```
+
+## Step 4: Parse Results
+
+### 4.1 Extract Test Summary
+
+Parse test framework output to extract:
+
+| Metric | Description |
+|--------|-------------|
+| Total | Total number of test cases executed |
+| Passed | Number of passed tests |
+| Failed | Number of failed tests |
+| Errors | Number of tests with runtime errors |
+| Skipped | Number of skipped tests |
+| Duration | Total execution time |
+
+### 4.2 Extract Failed Test Details
+
+For each failed test, extract:
+- **Test Function Name**: Full test name/suite
+- **Error Message**: Primary error description
+- **Stack Trace**: Call stack leading to failure
+- **Assertion Details**: Expected vs actual values (if available)
+
+### 4.3 Map Tests to TC IDs
+
+Use TC ID comments in test code to reverse-map:
+```
+// TC-ID: TC-001
+test('should validate user input', () => { ... });
+```
+
+Extract TC IDs from:
+- Test file comments
+- Test description patterns
+- Test code plan mapping
+
+## Step 5: Deviation Detection
+
+### 5.1 Compare Expected vs Actual
+
+For each test case:
+1. Read expected result from test cases document
+2. Compare with actual test result
+3. Classify deviation type
+
+### 5.2 Classify Deviation Types
+
+| Type | Code | Description | Severity |
+|------|------|-------------|----------|
+| FAIL | FAIL | Test assertion failed - actual result differs from expected | High |
+| ERROR | ERROR | Runtime error - code threw exception or crashed | Critical |
+| SKIP | SKIP | Test was skipped - preconditions not met | Medium |
+| FLAKY | FLAKY | Intermittent failure - non-deterministic behavior | High |
+
+### 5.3 Root Cause Analysis
+
+For each deviation, analyze:
+- **Assertion Failure**: Which specific assertion failed and why
+- **Runtime Error**: Exception type and location
+- **Skip Reason**: Why test could not execute
+- **Flaky Pattern**: Conditions causing intermittent failure
+
+## Step 6: Generate Test Report
+
+### 6.1 Read Template
+
+Read template: `speccrew-test-execute/templates/TEST-REPORT-TEMPLATE.md`
+
+### 6.2 Fill Report Content
+
+Generate comprehensive test report including:
+
+**Execution Summary**:
+- Feature name and platform
+- Test framework and version
+- Execution date and duration
+- Overall pass rate
+
+**Results Overview**:
+- Counts and percentages for all result types
+- Visual pass/fail indication
+
+**Results by Test Dimension**:
+- Breakdown by test type (happy path, boundary, exception, etc.)
+- Pass rate per dimension
+
+**Failed Test Details**:
+- Table of all failed tests
+- Links to corresponding bug reports
+
+**Coverage Status**:
+- Requirement-to-test-case mapping
+- Status per requirement
+
+**Environment Information**:
+- OS, runtime, framework versions
+- Key dependencies
+
+**Recommendations**:
+- Priority fixes needed
+- Suggested next steps
+
+### 6.3 Write Report
+
+Output path: `{output_dir}/{feature}-test-report.md`
+
+## Step 7: Generate Bug Reports
+
+### 7.1 Read Template
+
+Read template: `speccrew-test-execute/templates/BUG-REPORT-TEMPLATE.md`
+
+### 7.2 Create Individual Bug Reports
+
+For each FAIL type failure:
+
+1. **Assign Bug ID**: `BUG-{feature}-{seq}` (sequential numbering)
+
+2. **Determine Severity**:
+   | Criteria | Severity |
+   |----------|----------|
+   | Blocks core functionality, no workaround | Critical |
+   | Major feature broken, workaround exists | High |
+   | Minor feature issue, cosmetic problem | Medium |
+   | Enhancement, minor improvement | Low |
+
+3. **Fill Bug Report Content**:
+   - Bug title reflecting the failure
+   - Related TC ID for traceability
+   - Clear reproduction steps
+   - Expected result from test case
+   - Actual result from execution
+   - Relevant error log excerpt
+   - Suggested fix direction
+
+4. **Write Individual File**:
+   Output path: `{output_dir}/bugs/{feature}-bug-{seq}.md`
+
+### 7.3 Bug Report Quality Checklist
+
+Each bug report must include:
+- [ ] Unique Bug ID
+- [ ] Related TC ID
+- [ ] Severity classification
+- [ ] Clear reproduction steps
+- [ ] Expected vs actual result
+- [ ] Relevant log excerpt
+- [ ] Suggested fix direction
+
+# Key Rules
+
+| Rule | Description |
+|------|-------------|
+| **Environment First** | Always verify environment before running tests |
+| **Complete Output Capture** | Capture both stdout and stderr for diagnostics |
+| **TC ID Traceability** | Every failed test must be traced back to its TC ID |
+| **One Bug Per File** | Each bug gets its own report file for tracking |
+| **Severity Classification** | Always classify bug severity for prioritization |
+| **Actionable Reports** | Bug reports must include suggested fix direction |
+
+# Checklist
+
+- [ ] Environment pre-check passed before execution
+- [ ] All test files from code plan were executed
+- [ ] Failed tests are correctly traced back to TC IDs
+- [ ] Test report includes pass rate and failure details
+- [ ] Each FAIL has a corresponding bug report with reproduction steps
+- [ ] Bug severity is classified (Critical/High/Medium/Low)
+- [ ] All bug reports written to correct output path
+- [ ] Test report written to correct output path

package/.speccrew/skills/speccrew-test-execute/templates/BUG-REPORT-TEMPLATE.md

@@ -0,0 +1,50 @@
+# Bug Report: {Bug Title}
+
+## Bug Information
+| Item | Value |
+|------|-------|
+| Bug ID | BUG-{feature}-{seq} |
+| Related Test Case | {tc_id} |
+| Severity | {Critical/High/Medium/Low} |
+| Status | Open |
+| Platform | {platform_id} |
+| Detected Date | {date} |
+| Detected By | speccrew-test-execute |
+
+## Description
+{brief_description_of_the_bug}
+
+## Reproduction Steps
+1. {step_1}
+2. {step_2}
+3. {step_3}
+
+## Expected Result
+{expected_result_from_test_case}
+
+## Actual Result
+{actual_result_observed}
+
+## Error Log
+```
+{relevant_error_log_or_stack_trace}
+```
+
+## Environment
+| Item | Value |
+|------|-------|
+| OS | {os} |
+| Runtime | {runtime_version} |
+| Related Module | {module_name} |
+
+## Suggested Fix Direction
+{analysis_of_likely_root_cause_and_suggested_fix_approach}
+
+## Related Files
+- Test File: {test_file_path}
+- Source File: {likely_source_file} (if identifiable)
+
+---
+
+**Bug Created:** {timestamp}
+**Priority:** {priority_level}

package/.speccrew/skills/speccrew-test-execute/templates/TEST-REPORT-TEMPLATE.md

@@ -0,0 +1,57 @@
+# Test Execution Report: {Feature Name}
+
+## 1. Execution Summary
+| Item | Value |
+|------|-------|
+| Feature Name | {feature_name} |
+| Platform | {platform_id} |
+| Test Framework | {framework} |
+| Execution Date | {date} |
+| Total Duration | {duration} |
+| Executor | speccrew-test-execute |
+
+## 2. Results Overview
+| Metric | Count | Percentage |
+|--------|-------|------------|
+| Total | {total} | 100% |
+| Passed | {passed} | {pass_rate}% |
+| Failed | {failed} | {fail_rate}% |
+| Error | {error} | {error_rate}% |
+| Skipped | {skipped} | {skip_rate}% |
+
+## 3. Results by Test Dimension
+| Dimension | Total | Passed | Failed | Pass Rate |
+|-----------|-------|--------|--------|-----------|
+| Happy Path | {n} | {n} | {n} | {rate}% |
+| Boundary Value | {n} | {n} | {n} | {rate}% |
+| Exception Handling | {n} | {n} | {n} | {rate}% |
+| Business Rules | {n} | {n} | {n} | {rate}% |
+| Permission/Security | {n} | {n} | {n} | {rate}% |
+| Data Validation | {n} | {n} | {n} | {rate}% |
+
+## 4. Failed Test Details
+| TC ID | Test Name | Failure Type | Error Message | Bug Report |
+|-------|-----------|-------------|---------------|------------|
+| {tc_id} | {test_name} | FAIL/ERROR | {message} | {bug_report_link} |
+
+## 5. Coverage Status
+| Requirement ID | Test Case IDs | Status |
+|---------------|---------------|--------|
+| {req_id} | {tc_ids} | Pass/Fail/Partial |
+
+## 6. Environment Information
+| Item | Value |
+|------|-------|
+| OS | {os} |
+| Runtime | {runtime_version} |
+| Test Framework | {framework_version} |
+| Dependencies | {key_dependencies} |
+
+## 7. Recommendations
+- {recommendation_1}
+- {recommendation_2}
+
+---
+
+**Report Generated:** {timestamp}
+**Next Action:** {next_action}

package/.speccrew/skills/speccrew-workflow-diagnose/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: speccrew-workflow-diagnose
+description: Diagnose issues in AI engineering workflows. Analyze workflow bottlenecks, Agent behavior anomalies, deliverable quality issues, and provide solutions. Trigger scenarios: user mentions "workflow stuck", "diagnose problem", "Agent not working as expected", "poor deliverable quality"
+tools: Read, Glob, Grep
+---
+
+# Trigger Scenarios
+
+- AI engineering workflow stuck at a certain stage
+- Agent output does not meet expectations
+- Deliverable quality does not meet standards
+- User mentions "workflow issues", "diagnose", "Agent behavior anomaly"
+
+# Workflow
+
+## 1. Collect Problem Information
+
+Ask or identify the following information:
+- Which stage did the problem occur? (PM / Solution / Design / Development / Testing)
+- What are the specific symptoms?
+- What solutions have been tried?
+
+## 2. Read Related Deliverables
+
+Based on the problem stage, read the corresponding deliverables:
+
+| Problem Stage | Deliverables to Read |
+|---------------|----------------------|
+| PM Stage | `se/prd.md` |
+| Solution Stage | `se/solution.md` |
+| Design Stage | `se/*-design.md` |
+| Development Stage | Related code files |
+| Testing Stage | Test cases, test reports |
+
+## 3. Analyze Root Cause
+
+Common problem types and diagnostic directions:
+
+### Agent Behavior Issues
+
+| Symptom | Possible Cause | Solution |
+|---------|----------------|----------|
+| Output too generic | Agent prompt lacks project-specific information | Use `agent-optimize` Skill to supplement specific tech stack |
+| Skipping necessary steps | Workflow description unclear | Add checklists (checkboxes) |
+| Output format chaotic | Output specification unclear | Provide specific template examples |
+| Responsibility overreach | Insufficient constraints | Clearly define prohibited actions |
+
+### Workflow Handoff Issues
+
+| Symptom | Possible Cause | Solution |
+|---------|----------------|----------|
+| Design document unclear | Missing transition from Solution to design | Add context input requirements for design Agent |
+| Code does not match design | Design document not detailed enough | Output pseudo-code level details in design stage |
+| Test cases incomplete coverage | Testing Agent lacks design input | Ensure testing Agent reads design documents |
+
+### Deliverable Quality Issues
+
+| Symptom | Possible Cause | Solution |
+|---------|----------------|----------|
+| PRD requirements vague | PM Agent did not fully explore requirements | Add multi-round dialogue confirmation |
+| Solution lacks feasibility analysis | Technical constraints not identified | Add technical feasibility checkpoints |
+| Design document too complex | Not following simple design principles | Split modules, design in phases |
+
+## 4. Provide Solutions
+
+For identified problems, provide:
+1. **Immediate Solution** - Actions that can be taken immediately
+2. **Long-term Improvement** - Mechanisms to prevent similar issues
+3. **Files to Modify** - Specific configurations or documents to adjust
+
+## 5. Execute Fixes (Optional)
+
+If user agrees, execute fixes:
+- Use `agent-optimize` to adjust Agent prompts
+- Use `skill-develop` to create new check Skills
+- Update related deliverable templates
+
+# Diagnostic Checklist
+
+Standard checklist items when analyzing problems:
+
+- [ ] Problem stage accurately identified
+- [ ] Related deliverables have been read
+- [ ] Root cause analysis is well-founded
+- [ ] Solutions are specific and feasible
+- [ ] Long-term prevention measures considered
+
+# Common Diagnostic Scenarios
+
+## Scenario 1: Agent Output Does Not Meet Expectations
+
+**Diagnostic Steps:**
+1. Read the corresponding Agent file
+2. Check if description contains trigger scenarios
+3. Check if workflow has checklists
+4. Check if constraints are clear
+
+**Fix Solutions:**
+- Optimize Agent prompts (call `agent-optimize`)
+- Add example outputs
+- Clearly define prohibited actions
+
+## Scenario 2: Workflow Loops at a Certain Stage
+
+**Diagnostic Steps:**
+1. Check if previous stage deliverables are complete
+2. Check if current stage input requirements are clear
+3. Check if deliverable standards are too high or vague
+
+**Fix Solutions:**
+- Adjust deliverable acceptance standards
+- Add intermediate checkpoints
+- Split overly long workflow steps
+
+## Scenario 3: Multiple Agent Responsibility Conflicts
+
+**Diagnostic Steps:**
+1. Compare responsibility descriptions of related Agents
+2. Check for overlaps (what can/cannot be done)
+3. Check deliverable definitions at handoff points
+
+**Fix Solutions:**
+- Redefine responsibility boundaries
+- Clarify deliverable handoff standards
+- Add dedicated handoff Agent
+
+# Verification Checklist
+
+- [ ] Problem root cause identified
+- [ ] Solutions provided
+- [ ] User understands and agrees with solution
+- [ ] If fixes needed, fixes completed
+
+# Output Format
+
+```
+## Workflow Diagnostic Report
+
+### Problem Description
+[User described problem]
+
+### Root Cause Analysis
+[Analyzed root cause]
+
+### Solutions
+1. **Immediate Measures**: [What can be done immediately]
+2. **Long-term Improvement**: [Prevention mechanism]
+
+### Files to Modify
+- [File path] - [Modification content]
+
+### Recommendations
+[Next step action recommendations]
+```
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DevCrew Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.