zhongwei/gh-martybonacci-specswarm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:39:24 +08:00
commit 7e16d8a2a1
40 changed files with 16981 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

993
commands/implement.md Normal file
View File

@@ -0,0 +1,993 @@
---
description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
---
<!--
ATTRIBUTION CHAIN:
1. Original: GitHub spec-kit (https://github.com/github/spec-kit)
Copyright (c) GitHub, Inc. | MIT License
2. Adapted: SpecKit plugin by Marty Bonacci (2025)
3. Forked: SpecSwarm plugin with tech stack management
by Marty Bonacci & Claude Code (2025)
-->
## User Input
```text
$ARGUMENTS
```
You **MUST** consider the user input before proceeding (if not empty).
## Outline
1. **Discover Feature Context**:
**YOU MUST NOW discover the feature context using the Bash tool:**
a. **Get repository root** by executing:
```bash
git rev-parse --show-toplevel 2>/dev/null || pwd
```
Store the result as REPO_ROOT.
b. **Get current branch name** by executing:
```bash
git rev-parse --abbrev-ref HEAD 2>/dev/null
```
Store the result as BRANCH.
c. **Extract feature number from branch name** by executing:
```bash
echo "$BRANCH" | grep -oE '^[0-9]{3}'
```
Store the result as FEATURE_NUM.
d. **Initialize features directory and find feature**:
```bash
# Source features location helper
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PLUGIN_DIR="$(dirname "$SCRIPT_DIR")"
source "$PLUGIN_DIR/lib/features-location.sh"
# Initialize features directory
get_features_dir "$REPO_ROOT"
# If feature number is empty, find latest feature
if [ -z "$FEATURE_NUM" ]; then
FEATURE_NUM=$(list_features "$REPO_ROOT" | grep -oE '^[0-9]{3}' | sort -nr | head -1)
fi
# Find feature directory
find_feature_dir "$FEATURE_NUM" "$REPO_ROOT"
# FEATURE_DIR is now set by find_feature_dir
```
f. **Display to user:**
```
📁 Feature Context
✓ Repository: {REPO_ROOT}
✓ Branch: {BRANCH}
✓ Feature: {FEATURE_NUM}
✓ Directory: {FEATURE_DIR}
```
2. **Check checklists status** (if FEATURE_DIR/checklists/ exists):
- Scan all checklist files in the checklists/ directory
- For each checklist, count:
* Total items: All lines matching `- [ ]` or `- [X]` or `- [x]`
* Completed items: Lines matching `- [X]` or `- [x]`
* Incomplete items: Lines matching `- [ ]`
- Create a status table:
```
| Checklist | Total | Completed | Incomplete | Status |
|-----------|-------|-----------|------------|--------|
| ux.md | 12 | 12 | 0 | ✓ PASS |
| test.md | 8 | 5 | 3 | ✗ FAIL |
| security.md | 6 | 6 | 0 | ✓ PASS |
```
- Calculate overall status:
* **PASS**: All checklists have 0 incomplete items
* **FAIL**: One or more checklists have incomplete items
- **If any checklist is incomplete**:
* Display the table with incomplete item counts
* **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
* Wait for user response before continuing
* If user says "no" or "wait" or "stop", halt execution
* If user says "yes" or "proceed" or "continue", proceed to step 3
- **If all checklists are complete**:
* Display the table showing all checklists passed
* Automatically proceed to step 3
3. Load and analyze the implementation context:
- **REQUIRED**: Read tasks.md for the complete task list and execution plan
- **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
- **IF EXISTS**: Read data-model.md for entities and relationships
- **IF EXISTS**: Read contracts/ for API specifications and test requirements
- **IF EXISTS**: Read research.md for technical decisions and constraints
- **IF EXISTS**: Read quickstart.md for integration scenarios
- **IF EXISTS**: Read `.specswarm/tech-stack.md` for runtime validation (SpecSwarm)
<!-- ========== TECH STACK VALIDATION (SpecSwarm Enhancement) ========== -->
<!-- Added by Marty Bonacci & Claude Code (2025) -->
3b. **Pre-Implementation Tech Stack Validation** (if tech-stack.md exists):
**Purpose**: Runtime validation before writing any code or imports
**YOU MUST NOW perform tech stack validation using these steps:**
1. **Check if tech-stack.md exists** using the Read tool:
- Try to read `.specswarm/tech-stack.md`
- If file doesn't exist: Skip this entire section (3b)
- If file exists: Continue with validation
2. **Load Tech Stack Compliance Report** from plan.md using the Read tool:
- Read `${FEATURE_DIR}/plan.md`
- Search for "Tech Stack Compliance Report" section
- If section does NOT exist: Skip validation (plan created before SpecSwarm)
- If section DOES exist: Continue to step 3
3. **Verify All Conflicts Resolved** using the Grep tool:
a. Search for conflicts:
```bash
grep -q "⚠️ Conflicting Technologies" "${FEATURE_DIR}/plan.md"
```
b. If conflicts found, check if unresolved:
```bash
grep -q "**Your choice**: _\[" "${FEATURE_DIR}/plan.md"
```
c. If unresolved choices found:
- **HALT** implementation
- Display error: "❌ Tech stack conflicts still unresolved"
- Display message: "Cannot implement until all conflicts in plan.md are resolved"
- Stop execution
4. **Verify No Prohibited Technologies in Plan** using the Grep tool:
a. Search for prohibited techs:
```bash
grep -q "❌ Prohibited Technologies" "${FEATURE_DIR}/plan.md"
```
b. If found, check if blocking:
```bash
grep -q "**Cannot proceed**" "${FEATURE_DIR}/plan.md"
```
c. If blocking issues found:
- **HALT** implementation
- Display error: "❌ Prohibited technologies still present in plan.md"
- Display message: "Remove or replace prohibited technologies before implementing"
- Stop execution
4. **Load Prohibited Technologies List**:
```bash
# Extract all prohibited technologies from tech-stack.md
PROHIBITED_TECHS=()
APPROVED_ALTERNATIVES=()
while IFS= read -r line; do
if [[ $line =~ ^-\ ❌\ (.*)\ \(use\ (.*)\ instead\) ]]; then
PROHIBITED_TECHS+=("${BASH_REMATCH[1]}")
APPROVED_ALTERNATIVES+=("${BASH_REMATCH[2]}")
fi
done < <(grep "❌" "${REPO_ROOT}.specswarm/tech-stack.md")
```
5. **Runtime Import/Dependency Validation**:
**BEFORE writing ANY file that contains imports or dependencies:**
```bash
# For each import statement or dependency about to be written:
check_technology_compliance() {
local TECH_NAME="$1"
local FILE_PATH="$2"
local LINE_CONTENT="$3"
# Check if technology is prohibited
for i in "${!PROHIBITED_TECHS[@]}"; do
PROHIBITED="${PROHIBITED_TECHS[$i]}"
APPROVED="${APPROVED_ALTERNATIVES[$i]}"
if echo "$TECH_NAME" | grep -qi "$PROHIBITED"; then
ERROR "Prohibited technology detected: $PROHIBITED"
MESSAGE "File: $FILE_PATH"
MESSAGE "Line: $LINE_CONTENT"
MESSAGE "❌ Cannot use: $PROHIBITED"
MESSAGE "✅ Must use: $APPROVED"
MESSAGE "See .specswarm/tech-stack.md for details"
HALT
fi
done
# Check if technology is unapproved (warn but allow)
if ! grep -qi "$TECH_NAME" "${REPO_ROOT}.specswarm/tech-stack.md" 2>/dev/null; then
WARNING "Unapproved technology: $TECH_NAME"
MESSAGE "File: $FILE_PATH"
MESSAGE "This library is not in tech-stack.md"
PROMPT "Continue anyway? (yes/no)"
read -r RESPONSE
if [[ ! "$RESPONSE" =~ ^[Yy] ]]; then
MESSAGE "Halting. Please add $TECH_NAME to tech-stack.md or choose approved alternative"
HALT
fi
fi
}
```
6. **Validation Triggers**:
**JavaScript/TypeScript**:
- Before writing: `import ... from '...'`
- Before writing: `require('...')`
- Before writing: `npm install ...` or `yarn add ...`
- Extract library name and validate
**Python**:
- Before writing: `import ...` or `from ... import ...`
- Before writing: `pip install ...`
- Extract module name and validate
**Go**:
- Before writing: `import "..."`
- Before executing: `go get ...`
- Extract package name and validate
**General**:
- Before writing any `package.json` dependencies
- Before writing any `requirements.txt` entries
- Before writing any `go.mod` require statements
- Before writing any `composer.json` dependencies
7. **Pattern Validation**:
Check for prohibited patterns (not just libraries):
```bash
validate_code_pattern() {
local FILE_CONTENT="$1"
local FILE_PATH="$2"
# Check for prohibited patterns from tech-stack.md
# Example: "Class components" prohibited
if echo "$FILE_CONTENT" | grep -q "class.*extends React.Component"; then
ERROR "Prohibited pattern: Class components"
MESSAGE "File: $FILE_PATH"
MESSAGE "Use functional components instead"
HALT
fi
# Example: "Redux" prohibited
if echo "$FILE_CONTENT" | grep -qi "createStore\|configureStore.*@reduxjs"; then
ERROR "Prohibited library: Redux"
MESSAGE "File: $FILE_PATH"
MESSAGE "Use React Router loaders/actions instead"
HALT
fi
}
```
8. **Continuous Validation**:
- Run validation before EVERY file write operation
- Run validation before EVERY package manager command
- Run validation before EVERY import statement
- Accumulate violations and report at end if in batch mode
<!-- ========== END TECH STACK VALIDATION ========== -->
4. **Project Setup Verification**:
- **REQUIRED**: Create/verify ignore files based on actual project setup:
**Detection & Creation Logic**:
- Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so):
```sh
git rev-parse --git-dir 2>/dev/null
```
- Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore
- Check if .eslintrc* or eslint.config.* exists → create/verify .eslintignore
- Check if .prettierrc* exists → create/verify .prettierignore
- Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
- Check if terraform files (*.tf) exist → create/verify .terraformignore
- Check if .helmignore needed (helm charts present) → create/verify .helmignore
**If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only
**If ignore file missing**: Create with full pattern set for detected technology
**Common Patterns by Technology** (from plan.md tech stack):
- **Node.js/JavaScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*`
- **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/`
- **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/`
- **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/`
- **Go**: `*.exe`, `*.test`, `vendor/`, `*.out`
- **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/`
**Tool-Specific Patterns**:
- **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/`
- **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js`
- **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
- **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
5. Parse tasks.md structure and extract:
- **Task phases**: Setup, Tests, Core, Integration, Polish
- **Task dependencies**: Sequential vs parallel execution rules
- **Task details**: ID, description, file paths, parallel markers [P]
- **Execution flow**: Order and dependency requirements
6. Execute implementation following the task plan:
- **Phase-by-phase execution**: Complete each phase before moving to the next
- **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together
- **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
- **File-based coordination**: Tasks affecting the same files must run sequentially
- **Validation checkpoints**: Verify each phase completion before proceeding
7. Implementation execution rules:
- **Setup first**: Initialize project structure, dependencies, configuration
- **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
- **Core development**: Implement models, services, CLI commands, endpoints
- **Integration work**: Database connections, middleware, logging, external services
- **Polish and validation**: Unit tests, performance optimization, documentation
8. Progress tracking and error handling:
- Report progress after each completed task
- Halt execution if any non-parallel task fails
- For parallel tasks [P], continue with successful tasks, report failed ones
- Provide clear error messages with context for debugging
- Suggest next steps if implementation cannot proceed
- **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
9. Completion validation:
- Verify all required tasks are completed
- Check that implemented features match the original specification
- Validate that tests pass and coverage meets requirements
- Confirm the implementation follows the technical plan
- Report final status with summary of completed work
<!-- ========== SSR PATTERN VALIDATION ========== -->
<!-- Added by Marty Bonacci & Claude Code (2025-10-15) -->
9b. **SSR Architecture Validation** - Prevent Bug 913-type issues:
**Purpose**: Detect hardcoded URLs and relative URLs in server-side rendering contexts
**YOU MUST NOW run SSR pattern validation using the Bash tool:**
1. **Execute SSR validator:**
```bash
cd ${REPO_ROOT} && bash ~/.claude/plugins/marketplaces/specswarm-marketplace/plugins/specswarm/lib/ssr-validator.sh
```
2. **Parse validation results:**
- Exit code 0: No issues found (✓ PASS)
- Exit code 1: Issues detected (⚠️ FAIL)
3. **If issues detected:**
a. **Display issue summary** from validator output
b. **Ask user for action:**
```
⚠️ SSR Pattern Issues Detected
================================
Would you like me to:
1. Auto-fix common issues (create getApiUrl helper, update imports)
2. Show detailed issues and fix manually
3. Skip (continue anyway - NOT RECOMMENDED)
Choose (1/2/3):
```
c. **If user chooses option 1 (Auto-fix):**
- Check if app/utils/api.ts exists
- If not, create it with getApiUrl() helper:
```typescript
export function getApiUrl(path: string): string {
const base = typeof window !== 'undefined'
? ''
: process.env.API_BASE_URL || 'http://localhost:3000';
return `${base}${path}`;
}
```
- Scan all files with hardcoded URLs using Grep tool
- For each file:
* Add import: `import { getApiUrl } from '../utils/api';`
* Replace `fetch('http://localhost:3000/api/...')` with `fetch(getApiUrl('/api/...'))`
* Replace `fetch('/api/...')` in loaders/actions with `fetch(getApiUrl('/api/...'))`
- Re-run SSR validator to confirm fixes
- Display: "✅ Auto-fix complete. All SSR patterns corrected."
d. **If user chooses option 2 (Manual fix):**
- Display detailed issue list from validator
- Display recommendations
- Wait for user to fix manually
- Offer to re-run validator: "Type 'validate' to re-check or 'continue' to proceed"
e. **If user chooses option 3 (Skip):**
- Display warning: "⚠️ Skipping SSR validation. Production deployment may fail."
- Continue to next step
4. **If no issues found:**
- Display: "✅ SSR patterns validated - No architectural issues detected"
- Continue to next step
**IMPORTANT**: This validation prevents production failures from Bug 913-type issues (relative URLs in SSR contexts).
<!-- ========== END SSR PATTERN VALIDATION ========== -->
<!-- ========== QUALITY VALIDATION (SpecSwarm Phase 1) ========== -->
<!-- Added by Marty Bonacci & Claude Code (2025) -->
10. **Quality Validation** - CRITICAL STEP, MUST EXECUTE:
**Purpose**: Automated quality assurance before merge
**YOU MUST NOW CHECK FOR AND RUN QUALITY VALIDATION:**
1. **First**, check if quality standards file exists by reading the file at `${REPO_ROOT}.specswarm/quality-standards.md` using the Read tool.
2. **If the file does NOT exist:**
- Display this message to the user:
```
ℹ️ Quality Validation
====================
No quality standards defined. Skipping automated validation.
To enable quality gates:
1. Create .specswarm/quality-standards.md
2. Define minimum coverage and quality score
3. Configure test requirements
See: plugins/specswarm/templates/quality-standards-template.md
```
- Then proceed directly to Step 11 (Git Workflow)
3. **If the file EXISTS, you MUST execute the full quality validation workflow using the Bash tool:**
a. **Display header** by outputting directly to the user:
```
🧪 Running Quality Validation
=============================
```
b. **Detect test frameworks** using the Bash tool:
```bash
cd ${REPO_ROOT} && bash ~/.claude/plugins/marketplaces/specswarm-marketplace/plugins/specswarm/lib/test-framework-detector.sh
```
Parse the JSON output to extract:
- List of all detected frameworks
- Primary framework (highest priority)
- Framework count
Store primary framework for use in tests.
c. **Run unit tests** using the detected framework:
**YOU MUST NOW run tests using the Bash tool:**
1. **Source the test detector library:**
```bash
source ~/.claude/plugins/marketplaces/specswarm-marketplace/plugins/specswarm/lib/test-framework-detector.sh
```
2. **Run tests for primary framework:**
```bash
run_tests "{PRIMARY_FRAMEWORK}" ${REPO_ROOT}
```
3. **Parse test results:**
```bash
parse_test_results "{PRIMARY_FRAMEWORK}" "{TEST_OUTPUT}"
```
Extract: total, passed, failed, skipped counts
4. **Display results to user:**
```
1. Unit Tests ({FRAMEWORK_NAME})
✓ Total: {TOTAL}
✓ Passed: {PASSED} ({PASS_RATE}%)
✗ Failed: {FAILED}
⊘ Skipped: {SKIPPED}
```
d. **Measure code coverage** (if coverage tool available):
**YOU MUST NOW measure coverage using the Bash tool:**
1. **Check for coverage tool:**
```bash
source ~/.claude/plugins/marketplaces/specswarm-marketplace/plugins/specswarm/lib/test-framework-detector.sh
detect_coverage_tool "{PRIMARY_FRAMEWORK}" ${REPO_ROOT}
```
2. **If coverage tool detected, run coverage:**
```bash
run_coverage "{PRIMARY_FRAMEWORK}" ${REPO_ROOT}
```
Parse coverage percentage from output.
3. **Calculate proportional coverage score (Phase 2 Enhancement):**
- Read min_coverage from quality-standards.md (default 80%)
- Calculate score using proportional formula:
* Coverage >= 90%: 25 points (full credit)
* Coverage 80-89%: 20-24 points (proportional)
* Coverage 70-79%: 15-19 points (proportional)
* Coverage 60-69%: 10-14 points (proportional)
* Coverage 50-59%: 5-9 points (proportional)
* Coverage < 50%: 0-4 points (proportional)
Formula: `score = min(25, (coverage / 90) * 25)`
4. **Display results to user:**
```
3. Code Coverage
Coverage: {COVERAGE}%
Target: {TARGET}%
Score: {SCORE}/25 points
Status: {EXCELLENT/GOOD/ACCEPTABLE/NEEDS IMPROVEMENT/INSUFFICIENT}
```
5. **If no coverage tool:**
- Display: "Coverage measurement not configured (0 points)"
- Score: 0 points
e. **Detect browser test framework**:
```bash
cd ${REPO_ROOT} && source ~/.claude/plugins/marketplaces/specswarm-marketplace/plugins/specswarm/lib/quality-gates.sh && detect_browser_test_framework
```
f. **Run browser tests** (if Playwright/Cypress detected):
- For Playwright: `npx playwright test 2>&1 | tail -30`
- For Cypress: `npx cypress run 2>&1 | tail -30`
- Parse results (passed/failed/total)
- Display with "4. Browser Tests" header
- If no browser framework: Display "No browser test framework detected - Skipping"
f2. **Analyze bundle sizes** (Phase 3 Enhancement):
**YOU MUST NOW analyze bundle sizes using the Bash tool:**
1. **Run bundle size monitor:**
```bash
cd ${REPO_ROOT} && bash ~/.claude/plugins/marketplaces/specswarm-marketplace/plugins/speclabs/lib/bundle-size-monitor.sh
```
2. **Parse bundle analysis results:**
- Exit code 0: All bundles within budget (✓ PASS)
- Exit code 1: Large bundles detected (⚠️ WARNING)
- Exit code 2: Critical bundle size exceeded (🔴 CRITICAL)
3. **Extract bundle metrics:**
- Total bundle size (in KB)
- Number of large bundles (>500KB)
- Number of critical bundles (>1MB)
- List of top 5 largest bundles
4. **Calculate bundle size score:**
- < 500KB total: 20 points (excellent)
- 500-750KB: 15 points (good)
- 750-1000KB: 10 points (acceptable)
- 1000-2000KB: 5 points (poor)
- > 2000KB: 0 points (critical)
5. **Display results to user:**
```
5. Bundle Size Performance
Total Size: {TOTAL_SIZE}
Largest Bundle: {LARGEST_BUNDLE}
Score: {SCORE}/20 points
Status: {EXCELLENT/GOOD/ACCEPTABLE/POOR/CRITICAL}
```
6. **If no build directory found:**
- Display: "No build artifacts found - Run build first (0 points)"
- Score: 0 points
- Note: Bundle size analysis requires a production build
7. **Track bundle size in metrics:**
- Add bundle_size_kb to metrics.json
- Enables bundle size tracking over time
f3. **Enforce performance budgets** (Phase 3 Enhancement - Optional):
**YOU MUST NOW check if performance budgets are defined:**
1. **Check for budget configuration:**
- Read quality-standards.md using Read tool
- Look for budget settings:
* max_bundle_size (KB)
* max_initial_load (KB)
* enforce_budgets (true/false)
2. **If enforce_budgets is true, run enforcement:**
```bash
cd ${REPO_ROOT} && bash ~/.claude/plugins/marketplaces/specswarm-marketplace/plugins/speclabs/lib/performance-budget-enforcer.sh
```
3. **Parse enforcement results:**
- Exit code 0: All budgets met (✓ PASS)
- Exit code 1: Budgets violated (❌ FAIL)
4. **If budgets violated:**
a. **Display violations** from enforcer output
b. **Check block_merge setting:**
- If block_merge_on_budget_violation is true: HALT
- If false: Warn and ask user "Continue anyway? (yes/no)"
5. **Display budget status:**
```
⚡ Performance Budget Status
- Bundle Size: {PASS/FAIL}
- Initial Load: {PASS/FAIL}
Overall: {PASS/FAIL}
```
6. **If no budgets configured:**
- Skip enforcement
- Note: "Performance budgets not configured (optional)"
g. **Calculate quality score** using proportional scoring (Phase 2 & 3 Enhancement):
**YOU MUST NOW calculate scores for each component:**
1. **Unit Tests** (0-25 points - proportional by pass rate):
- 100% passing: 25 points
- 90-99% passing: 20-24 points (proportional)
- 80-89% passing: 15-19 points (proportional)
- 70-79% passing: 10-14 points (proportional)
- 60-69% passing: 5-9 points (proportional)
- <60% passing: 0-4 points (proportional)
Formula: `score = min(25, (pass_rate / 100) * 25)`
2. **Code Coverage** (0-25 points - proportional by coverage %):
- >=90% coverage: 25 points
- 80-89% coverage: 20-24 points (proportional)
- 70-79% coverage: 15-19 points (proportional)
- 60-69% coverage: 10-14 points (proportional)
- 50-59% coverage: 5-9 points (proportional)
- <50% coverage: 0-4 points (proportional)
Formula: `score = min(25, (coverage / 90) * 25)`
3. **Integration Tests** (0-15 points - proportional):
- 100% passing: 15 points
- Proportional for <100%
- 0 points if not detected
Formula: `score = min(15, (pass_rate / 100) * 15)`
4. **Browser Tests** (0-15 points - proportional):
- 100% passing: 15 points
- Proportional for <100%
- 0 points if not detected
Formula: `score = min(15, (pass_rate / 100) * 15)`
5. **Bundle Size** (0-20 points - Phase 3 feature):
- < 500KB total: 20 points
- 500-750KB: 15 points
- 750-1000KB: 10 points
- 1000-2000KB: 5 points
- > 2000KB: 0 points
- No build found: 0 points
6. **Visual Alignment** (0-15 points - Phase 3 future):
- Set to 0 for now (screenshot analysis not yet implemented)
**Total possible: 115 points** (but scaled to 100 for display)
**Scoring Note**: When Visual Alignment is implemented, adjust other components to maintain 100-point scale.
**Example Calculation:**
- Unit Tests: 106/119 passing (89%) → 22.25 points
- Coverage: 75% → 20.83 points
- Integration Tests: Not detected → 0 points
- Browser Tests: Not configured → 0 points
- Bundle Size: 450KB → 20 points
- Visual Alignment: Not implemented → 0 points
- **Total: 63.08/115 points** (scaled to ~55/100)
h. **Display quality report** with proportional scoring details:
```
Quality Validation Results
==========================
1. Unit Tests ({FRAMEWORK}): {SCORE}/25 points
✓ Passed: {PASSED}/{TOTAL} ({PASS_RATE}%)
✗ Failed: {FAILED}
Status: {EXCELLENT/GOOD/ACCEPTABLE/NEEDS IMPROVEMENT}
2. Code Coverage: {SCORE}/25 points
Coverage: {COVERAGE}% (target: {TARGET}%)
Status: {EXCELLENT/GOOD/ACCEPTABLE/NEEDS IMPROVEMENT/INSUFFICIENT}
3. Integration Tests: {SCORE}/15 points
{DETAILS or "Not detected"}
4. Browser Tests: {SCORE}/15 points
{DETAILS or "Not configured"}
5. Bundle Size: {SCORE}/20 points
Total: {TOTAL_SIZE} | Largest: {LARGEST_BUNDLE}
Status: {EXCELLENT/GOOD/ACCEPTABLE/POOR/CRITICAL}
6. Visual Alignment: 0/15 points
Status: Not yet implemented (Phase 3 future)
════════════════════════════════════════
Raw Score: {RAW_SCORE}/115 points
Scaled Score: {SCALED_SCORE}/100 points
════════════════════════════════════════
Status: {PASS/FAIL} (threshold: {THRESHOLD}/100)
Score Breakdown:
████████████████░░░░░░░░ {SCALED_SCORE}% ({VISUAL_BAR})
Note: Score scaled from 115-point system to 100-point display
```
i. **Check quality gates** from quality-standards.md:
- Read min_quality_score (default 80)
- Read block_merge_on_failure (default false)
- If score < minimum:
- If block_merge_on_failure is true: HALT and show error
- If block_merge_on_failure is false: Show warning and ask user "Continue with merge anyway? (yes/no)"
- If score >= minimum: Display "✅ Quality validation passed!"
j. **Save quality metrics** by updating `${REPO_ROOT}.specswarm/metrics.json`:
- Add entry for current feature number
- Include quality score, coverage, test results
- Use Write tool to update the JSON file
**IMPORTANT**: You MUST execute this step if quality-standards.md exists. Do NOT skip it. Use the Bash tool to run all commands and parse the results.
4. **Proactive Quality Improvements** - If quality score < 80/100:
**YOU MUST NOW offer to improve the quality score:**
a. **Check for missing coverage tool:**
- If Vitest was detected but coverage measurement showed 0% or "not configured":
- Display to user:
```
⚡ Coverage Tool Not Installed
=============================
Installing @vitest/coverage-v8 would add +25 points to your quality score.
Current: {CURRENT_SCORE}/100
With coverage: {CURRENT_SCORE + 25}/100
Would you like me to:
1. Install coverage tool and re-run validation
2. Skip (continue without coverage)
Choose (1 or 2):
```
- If user chooses 1:
- Run: `npm install --save-dev @vitest/coverage-v8`
- Check if vitest.config.ts exists using Read tool
- If exists, update it to add coverage configuration
- If not exists, create vitest.config.ts with coverage config
- Re-run quality validation (step 3 above)
- Display new score
b. **Check for missing E2E tests:**
- If Playwright was detected but no tests were found:
- Display to user:
```
⚡ No E2E Tests Found
=====================
Writing basic E2E tests would add +15 points to your quality score.
Current: {CURRENT_SCORE}/100
With E2E tests: {CURRENT_SCORE + 15}/100
Would you like me to:
1. Generate basic Playwright test templates
2. Skip (continue without E2E tests)
Choose (1 or 2):
```
- If user chooses 1:
- Create tests/e2e/ directory if not exists
- Generate basic test file with:
* Login flow test (if authentication exists)
* Main feature flow test (based on spec.md)
* Basic smoke test
- Run: `npx playwright test`
- Re-run quality validation
- Display new score
c. **Display final improvement summary:**
```
📊 Quality Score Improvement
============================
Before improvements: {ORIGINAL_SCORE}/100
After improvements: {FINAL_SCORE}/100
Increase: +{INCREASE} points
{STATUS_EMOJI} Quality Status: {PASS/FAIL}
```
**Note**: This proactive improvement step can increase quality scores from 25/100 to 65/100+ automatically.
<!-- ========== END QUALITY VALIDATION ========== -->
11. **Git Workflow Completion** (if git repository):
**Purpose**: Handle feature branch merge and cleanup after successful implementation
**INSTRUCTIONS FOR CLAUDE:**
1. **Check if in a git repository** using Bash tool:
```bash
git rev-parse --git-dir 2>/dev/null
```
If this fails, skip git workflow entirely.
2. **Get current and main branch names** using Bash:
```bash
git rev-parse --abbrev-ref HEAD
git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'
```
3. **Only proceed if on a feature branch** (not main/master). If already on main, display "Already on main branch" and stop.
4. **Display git workflow options** to the user:
```
🌳 Git Workflow
===============
Current branch: {CURRENT_BRANCH}
Main branch: {MAIN_BRANCH}
Feature implementation complete! What would you like to do?
1. Merge to {MAIN_BRANCH} and delete feature branch (recommended)
2. Stay on {CURRENT_BRANCH} for additional work
3. Switch to {MAIN_BRANCH} without merging (keep branch)
Choose (1/2/3):
```
5. **Wait for user choice** and proceed based on their selection.
**OPTION 1: Merge and Delete Branch**
a. **Check for uncommitted changes** using Bash:
```bash
git diff-index --quiet HEAD --
```
If exit code is non-zero, there are uncommitted changes.
b. **If there are uncommitted changes:**
- Display: `git status --short` to show changes
- Ask user: "Commit these changes first? (yes/no)"
c. **If user wants to commit, intelligently stage ONLY source files:**
**CRITICAL - Smart Git Staging (Project-Aware):**
**YOU MUST NOW perform smart file staging using these steps:**
1. **Detect project type** by checking for files:
- Read package.json using Read tool
- Check for framework indicators:
* Vite: `vite.config.ts` or `"vite"` in package.json
* Next.js: `next.config.js` or `"next"` in package.json
* Remix: `remix.config.js` or `"@remix-run"` in package.json
* Create React App: `react-scripts` in package.json
* Node.js generic: package.json exists but no specific framework
- Store detected type for use in exclusions
2. **Build exclusion patterns based on project type:**
a. **Base exclusions (all projects):**
```
':!node_modules/' ':!.pnpm-store/' ':!.yarn/'
':!*.log' ':!coverage/' ':!.nyc_output/'
```
b. **Project-specific exclusions:**
- Vite: `':!dist/' ':!build/'`
- Next.js: `':!.next/' ':!out/'`
- Remix: `':!build/' ':!public/build/'`
- CRA: `':!build/'`
c. **Parse .gitignore** using Read tool:
- Read .gitignore if it exists
- Extract patterns (lines not starting with #)
- Convert to pathspec format: `:!{pattern}`
- Add to exclusion list
3. **Check for large files** using Bash:
```bash
git status --porcelain | cut -c4- | while read file; do
if [ -f "$file" ] && [ $(stat -f%z "$file" 2>/dev/null || stat -c%s "$file" 2>/dev/null) -gt 1048576 ]; then
echo "$file ($(du -h "$file" | cut -f1))"
fi
done
```
a. **If large files found:**
- Display warning:
```
⚠️ Large Files Detected
======================
The following files are >1MB:
- {file1} ({size1})
- {file2} ({size2})
These may not belong in git. Add to .gitignore?
1. Add to .gitignore and skip
2. Commit anyway
3. Cancel commit
Choose (1/2/3):
```
- If option 1: Append to .gitignore, exclude from staging
- If option 2: Include in staging
- If option 3: Cancel commit, return to main flow
4. **Stage files with exclusions** using Bash:
```bash
git add . {BASE_EXCLUSIONS} {PROJECT_EXCLUSIONS} {GITIGNORE_EXCLUSIONS}
```
Example for Vite project:
```bash
git add . ':!node_modules/' ':!dist/' ':!build/' ':!*.log' ':!coverage/'
```
5. **Verify staging** using Bash:
```bash
git diff --cached --name-only
```
a. **Check if any excluded patterns appear:**
- If `dist/`, `build/`, `.next/`, etc. appear in staged files
- Display error: "❌ Build artifacts detected in staging"
- Ask user: "Unstage and retry? (yes/no)"
- If yes: `git reset` and retry with stricter patterns
6. **Commit with message** using Bash:
```bash
git commit -m "{USER_PROVIDED_MESSAGE}"
```
**IMPORTANT**: This project-aware staging prevents build artifacts and large files from being committed.
d. **Merge to main branch:**
- Test merge first (dry run): `git merge --no-commit --no-ff {CURRENT_BRANCH}`
- If successful: abort test, do real merge with message
- If conflicts: abort, show manual resolution steps, stay on feature branch
e. **Delete feature branch** if merge succeeded:
```bash
git branch -d {CURRENT_BRANCH}
```
**OPTION 2: Stay on Current Branch**
- Display message about when/how to merge later
- No git commands needed
**OPTION 3: Switch to Main (Keep Branch)**
- Switch to main: `git checkout {MAIN_BRANCH}`
- Keep feature branch for later
**IMPORTANT**: When staging files for commit, NEVER use `git add .` - always filter out build artifacts!
Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/tasks` first to regenerate the task list.