forge-workflow 0.0.2 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-workflow",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "7-stage TDD workflow for ALL AI coding agents (Claude, Cursor, Cline, OpenCode, Copilot, Kilo Code, Roo Code, Codex)",
   "bin": {
     "forge": "bin/forge.js",
@@ -39,7 +39,7 @@
     "@commitlint/config-conventional": "^20.4.1",
     "@eslint/js": "^10.0.1",
     "@microsoft/eslint-formatter-sarif": "^3.1.0",
-    "@stryker-mutator/core": "^9.5.1",
+    "@stryker-mutator/core": "^9.6.0",
     "c8": "^11.0.0",
     "eslint": "^10.0.2",
     "globals": "^17.3.0",
@@ -76,12 +76,21 @@
   "files": [
     "bin/",
     "lib/",
+    "skills/",
     ".claude/commands/",
     ".claude/rules/",
     ".claude/scripts/",
-    ".forge/hooks/",
+    ".claude/skills/",
+    ".cursor/",
+    ".cline/",
+    ".roo/",
+    ".codex/",
+    ".kilocode/",
+    ".opencode/",
+    ".github/prompts/",
     ".github/PLUGIN_TEMPLATE.json",
-    "docs/",
+    ".forge/hooks/",
+    "docs/*.md",
     "install.sh",
     "lefthook.yml",
     "AGENTS.md",
@@ -89,10 +98,12 @@
     ".mcp.json.example"
   ],
   "dependencies": {
+    "@babel/parser": "^7.29.2",
     "fastest-levenshtein": "^1.0.16"
   },
   "overrides": {
     "eslint": "^10.0.2",
+    "flatted": "3.4.2",
     "minimatch": "10.2.4"
   },
   "c8": {

package/skills/parallel-deep-research/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: parallel-deep-research
+description: >
+  Produces comprehensive research reports that go far beyond what built-in web
+  search can achieve. Sends research tasks to Parallel AI's pro/ultra processors
+  which spend 3-25 minutes autonomously crawling, reading, and synthesizing dozens
+  of sources — returning structured reports with citations. Built-in WebSearch
+  can only run a few queries; this skill runs an entire research pipeline externally.
+  No binary install — requires PARALLEL_API_KEY in .env.local. ALWAYS use this
+  skill instead of doing multiple WebSearch calls when the user needs a comprehensive
+  report, market analysis, competitive landscape, industry deep-dive, strategic
+  recommendations, or multi-source synthesis. This is the RIGHT tool for any
+  research task that would require more than 3-4 web searches to answer properly.
+  Also trigger during /plan Phase 2 research and /research workflows.
+compatibility: Requires PARALLEL_API_KEY in .env.local. Uses curl. Takes 3-25 minutes.
+metadata:
+  author: harshanandak
+  version: "1.0.0"
+---
+
+# Parallel Deep Research
+
+Comprehensive research reports with multi-source synthesis. Use `pro` (3-9 min, $0.10) or `ultra` (5-25 min, $0.30) for deep analysis.
+
+> **CLI alternative (recommended)**: Install `parallel-cli` for official skill:
+> `npx skills add parallel-web/parallel-agent-skills --skill parallel-deep-research`
+
+## Setup
+
+```bash
+API_KEY=$(grep "^PARALLEL_API_KEY=" .env.local | cut -d= -f2)
+```
+
+## Create Research Task
+
+```bash
+curl -s -X POST "https://api.parallel.ai/v1/tasks/runs" \
+  -H "x-api-key: $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "input": "Analyze the AI chatbot market. Include: size, growth, key players, trends, competitive threats",
+    "processor": "pro"
+  }'
+```
+
+Response: `{"run_id": "trun_abc123...", "status": "queued"}`
+
+## Get Result (polling)
+
+The result endpoint returns both status and output in one call. Poll until `status` is `completed`.
+
+```bash
+RUN_ID="trun_abc123..."
+MAX_POLLS=180  # 30 min max (180 × 10s)
+
+for i in $(seq 1 $MAX_POLLS); do
+  RESULT=$(curl -s "https://api.parallel.ai/v1/tasks/runs/$RUN_ID/result" \
+    -H "x-api-key: $API_KEY")
+
+  STATUS=$(echo "$RESULT" | grep -o '"status":"[^"]*"' | head -1 | cut -d'"' -f4)
+
+  if [ "$STATUS" = "completed" ]; then
+    echo "$RESULT"
+    break
+  elif [ "$STATUS" = "failed" ]; then
+    echo "Task failed: $RESULT"
+    break
+  fi
+
+  echo "Poll $i/$MAX_POLLS — Status: $STATUS"
+  sleep 10
+done
+
+if [ "$i" = "$MAX_POLLS" ] && [ "$STATUS" != "completed" ] && [ "$STATUS" != "failed" ]; then
+  echo "Timeout: task did not complete within 30 minutes"
+fi
+```
+
+## Processors
+
+| Processor | Speed | Cost | Use For |
+|-----------|-------|------|---------|
+| pro | 3-9 min | $0.10/task | Market analysis, strategic reports |
+| ultra | 5-25 min | $0.30/task | Comprehensive deep research |
+
+## Example: Market Analysis
+
+```json
+{
+  "input": "Analyze the AI chip market in 2024. Include market size, growth rate, key players (NVIDIA, AMD, Intel), emerging competitors, and 2025 outlook.",
+  "processor": "pro"
+}
+```
+
+Result: Markdown report with citations.
+
+## When to Use
+
+- Market research and competitive analysis
+- Strategic reports requiring multiple sources
+- Research that needs synthesis across many documents
+- Any task that would need more than 3-4 web searches to answer properly
+
+For quick facts or single-source lookups, use built-in WebSearch instead.
+
+## Timeout
+
+Set polling timeout to 1800s (30 min) for ultra tasks. Pro tasks typically complete in 3-9 min.

package/skills/parallel-deep-research/evals/README.md

@@ -0,0 +1,27 @@
+# Eval Sets
+
+These eval files use a flat JSON array format targeting `scripts/eval_win.py`:
+
+```json
+[{"query": "...", "should_trigger": true}]
+```
+
+This is **not** compatible with the skill-creator plugin's `run_loop.py` which expects:
+
+```json
+{"skill_name": "...", "evals": [{"id": "...", "prompt": "...", "should_trigger": true}]}
+```
+
+To convert for `run_loop.py`:
+
+```bash
+python3 -c "
+import json, pathlib, uuid
+data = json.loads(pathlib.Path('evals.json').read_text())
+out = {'skill_name': 'SKILL-NAME-HERE', 'evals': [
+    {'id': str(uuid.uuid4()), 'prompt': item['query'], 'should_trigger': item['should_trigger']}
+    for item in data
+]}
+print(json.dumps(out, indent=2))
+" > evals_skill_creator.json
+```

package/skills/parallel-deep-research/evals/evals.json

@@ -0,0 +1,62 @@
+[
+  {
+    "query": "I need a comprehensive market analysis of the developer tools space — cover the top 20 players, their funding, market positioning, and where the industry is heading over the next 3-5 years. Include data from Gartner, Forrester, and any recent VC investment reports",
+    "should_trigger": true
+  },
+  {
+    "query": "Write a deep research report on the state of WebAssembly adoption in production — synthesize case studies from companies using WASM, performance benchmarks vs native code, ecosystem maturity analysis, and strategic recommendations for when to adopt it",
+    "should_trigger": true
+  },
+  {
+    "query": "Our CTO wants a competitive landscape analysis comparing Convex, Supabase, Firebase, and PlanetScale for our backend rewrite. Need comprehensive feature comparison, pricing analysis at our scale (50K DAU), community health metrics, and risk assessment for each",
+    "should_trigger": true
+  },
+  {
+    "query": "Create a strategic report on the AI code generation market — analyze GitHub Copilot, Cursor, Claude Code, and emerging competitors. Cover adoption rates, developer satisfaction surveys, enterprise pricing trends, and predictions for 2027",
+    "should_trigger": true
+  },
+  {
+    "query": "I'm doing /plan Phase 2 research — produce a comprehensive analysis of event-driven architecture patterns in microservices, covering Kafka vs RabbitMQ vs NATS, with production case studies, failure mode analysis, and recommendations for our 100K events/sec throughput requirement",
+    "should_trigger": true
+  },
+  {
+    "query": "Write an industry deep-dive into the observability market — compare Datadog, Grafana Cloud, and New Relic across features, pricing, scalability, and OpenTelemetry support. Include customer migration stories and TCO analysis for a 500-node cluster",
+    "should_trigger": true
+  },
+  {
+    "query": "Research and synthesize the current state of edge computing for real-time AI inference — cover hardware options, cloud provider edge offerings, latency benchmarks, and case studies from autonomous vehicles and IoT deployments",
+    "should_trigger": true
+  },
+  {
+    "query": "Quick search: what's the current price of Bitcoin and what were Anthropic's latest announcements?",
+    "should_trigger": false
+  },
+  {
+    "query": "Find the official migration guide URL for ESLint's new flat config format",
+    "should_trigger": false
+  },
+  {
+    "query": "Search for recent blog posts about Bun 2.0 features and release date",
+    "should_trigger": false
+  },
+  {
+    "query": "Go to https://stripe.com/docs/api and extract the authentication section with all the code examples",
+    "should_trigger": false
+  },
+  {
+    "query": "Scrape https://openai.com/pricing and extract the per-token costs for each model tier",
+    "should_trigger": false
+  },
+  {
+    "query": "Build a structured company profile for Databricks — return JSON with founding year, funding rounds, valuation, employee count, and tech stack",
+    "should_trigger": false
+  },
+  {
+    "query": "Fix the TypeScript compilation error in src/services/auth.ts — it's complaining about missing type for the session token",
+    "should_trigger": false
+  },
+  {
+    "query": "Add unit tests for the rate limiter middleware in src/middleware/rateLimit.ts",
+    "should_trigger": false
+  }
+]

package/skills/sonarcloud-analysis/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: sonarcloud-analysis
+description: >
+  Pull issues, metrics, quality gates, and analysis data from SonarCloud. ALWAYS
+  use this skill when the user mentions SonarCloud, asks about code quality metrics,
+  wants to check PR quality gates, or needs to review security vulnerabilities and
+  technical debt from static analysis. Also trigger during /review workflow when
+  SonarCloud issues need addressing. Trigger on phrases like "SonarCloud",
+  "quality gate", "code quality metrics", "technical debt", "coverage report",
+  "static analysis issues", "security vulnerabilities from scan".
+category: Code Quality
+tags: [sonarcloud, code-quality, issues, metrics, security]
+context: fork
+tools: [Bash, WebFetch, Read, Grep, Glob]
+model: sonnet
+---
+
+<role>
+You are a SonarCloud code quality analyst with expertise in static analysis, security vulnerability assessment, and technical debt management. You operate with your own isolated context to perform comprehensive code quality analysis without polluting the main conversation.
+</role>
+
+<capabilities>
+- Query SonarCloud API for issues, metrics, and quality gates
+- Analyze code quality across branches and pull requests
+- Identify security vulnerabilities and hotspots
+- Track coverage, duplication, and technical debt
+- Generate health reports and trend analysis
+- Correlate SonarCloud findings with local codebase
+</capabilities>
+
+<constraints>
+- Always use environment variables: $SONARCLOUD_TOKEN, $SONARCLOUD_ORG, $SONARCLOUD_PROJECT
+- Load credentials from .env.local if environment variables are not set
+- Never expose tokens in output
+- Validate API responses before processing
+- Handle pagination for large result sets
+</constraints>
+
+<workflow>
+1. Load environment variables (check .env.local if needed: `source .env.local 2>/dev/null || true`)
+2. Verify credentials are available
+3. Determine the analysis scope (project, branch, PR)
+4. Query relevant endpoints
+5. Process and correlate results
+6. Return actionable summary to main context
+</workflow>
+
+# SonarCloud Integration
+
+**Base**: `https://sonarcloud.io/api` | **Auth**: `Bearer $SONARCLOUD_TOKEN`
+
+## Configuration
+
+**Environment Variables**: Required for authentication
+- `SONARCLOUD_TOKEN` - Generate at sonarcloud.io/account/security
+- `SONARCLOUD_ORG` - Your SonarCloud organization key
+- `SONARCLOUD_PROJECT` - Your project key
+
+**Option 1: Use .env.local** (Recommended)
+Add to your project's `.env.local`:
+```bash
+SONARCLOUD_TOKEN=your_token_here
+SONARCLOUD_ORG=your-org
+SONARCLOUD_PROJECT=your-project
+```
+
+Before querying, load environment variables:
+```bash
+# Load .env.local into current environment
+export $(grep -v '^#' .env.local | xargs)
+```
+
+**Option 2: Export directly**
+```bash
+export SONARCLOUD_TOKEN="your_token"
+export SONARCLOUD_ORG="your-org"
+export SONARCLOUD_PROJECT="your-project"
+
+# Common queries
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/issues/search?organization=$ORG&componentKeys=$PROJECT&resolved=false"
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/measures/component?component=$PROJECT&metricKeys=bugs,coverage"
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/qualitygates/project_status?projectKey=$PROJECT"
+```
+
+## Endpoints
+
+| Endpoint                        | Purpose                  | Key Params                               |
+| ------------------------------- | ------------------------ | ---------------------------------------- |
+| `/api/issues/search`            | Bugs, vulnerabilities    | `types`, `severities`, `branch`, `pullRequest` |
+| `/api/measures/component`       | Coverage, complexity     | `metricKeys`, `branch`, `pullRequest`    |
+| `/api/qualitygates/project_status` | Pass/fail status      | `projectKey`, `branch`, `pullRequest`    |
+| `/api/hotspots/search`          | Security hotspots        | `projectKey`, `status`                   |
+| `/api/projects/search`          | List projects            | `organization`, `q`                      |
+| `/api/project_analyses/search`  | Analysis history         | `project`, `from`, `to`                  |
+| `/api/measures/search_history`  | Metrics over time        | `component`, `metrics`, `from`           |
+| `/api/components/tree`          | Files with metrics       | `qualifiers=FIL`, `metricKeys`           |
+| `/api/duplications/show`        | Duplicate code blocks    | `key` (file key), `branch`               |
+| `/api/sources/raw`              | Raw source code          | `key` (file key), `branch`               |
+| `/api/sources/scm`              | SCM blame info           | `key`, `from`, `to`                      |
+| `/api/ce/activity`              | Background tasks         | `component`, `status`, `type`            |
+| `/api/qualityprofiles/search`   | Quality profiles         | `language`, `project`                    |
+| `/api/languages/list`           | Supported languages      | -                                        |
+| `/api/project_branches/list`    | Project branches         | `project`                                |
+| `/api/project_badges/measure`   | SVG badge                | `project`, `metric`, `branch`            |
+| `/api/rules/search`             | Coding rules             | `languages`, `severities`, `types`       |
+
+## Common Filters
+
+**Issues**: `types=BUG,VULNERABILITY,CODE_SMELL` | `severities=BLOCKER,CRITICAL,MAJOR` | `resolved=false` | `inNewCodePeriod=true`
+
+**Metrics**: `bugs,vulnerabilities,code_smells,coverage,duplicated_lines_density,sqale_rating,reliability_rating,security_rating`
+
+**New Code**: `new_bugs,new_vulnerabilities,new_coverage,new_duplicated_lines_density`
+
+## Workflows
+
+### Health Check
+
+```bash
+curl ... "/api/qualitygates/project_status?projectKey=$PROJECT"
+curl ... "/api/measures/component?component=$PROJECT&metricKeys=bugs,vulnerabilities,coverage,sqale_rating"
+curl ... "/api/issues/search?organization=$ORG&componentKeys=$PROJECT&resolved=false&facets=severities,types&ps=1"
+```
+
+### PR Analysis
+
+```bash
+curl ... "/api/qualitygates/project_status?projectKey=$PROJECT&pullRequest=123"
+curl ... "/api/issues/search?organization=$ORG&componentKeys=$PROJECT&pullRequest=123&resolved=false"
+curl ... "/api/measures/component?component=$PROJECT&pullRequest=123&metricKeys=new_bugs,new_coverage"
+```
+
+### Security Audit
+
+```bash
+curl ... "/api/issues/search?organization=$ORG&componentKeys=$PROJECT&types=VULNERABILITY&resolved=false"
+curl ... "/api/hotspots/search?projectKey=$PROJECT&status=TO_REVIEW"
+```
+
+### Duplication Analysis
+
+```bash
+# Get duplication metrics
+curl ... "/api/measures/component?component=$PROJECT&metricKeys=duplicated_lines,duplicated_lines_density,duplicated_blocks,duplicated_files"
+
+# Get files with most duplication
+curl ... "/api/components/tree?component=$PROJECT&qualifiers=FIL&metricKeys=duplicated_lines_density&s=metric&metricSort=duplicated_lines_density&asc=false&ps=20"
+
+# Get duplicate blocks for a specific file (requires file key from above)
+curl ... "/api/duplications/show?key=my-project:src/utils/helpers.ts"
+```
+
+## Response Processing
+
+```bash
+# Count by severity
+curl ... | jq '.issues | group_by(.severity) | map({severity: .[0].severity, count: length})'
+
+# Failed quality gate conditions
+curl ... | jq '.projectStatus.conditions | map(select(.status == "ERROR"))'
+
+# Metrics as key-value
+curl ... | jq '.component.measures | map({(.metric): .value}) | add'
+```
+
+## Detailed Reference
+
+For complete API parameters and response schemas, see [references/api-reference.md](references/api-reference.md).

package/skills/sonarcloud-analysis/evals/README.md

@@ -0,0 +1,27 @@
+# Eval Sets
+
+These eval files use a flat JSON array format targeting `scripts/eval_win.py`:
+
+```json
+[{"query": "...", "should_trigger": true}]
+```
+
+This is **not** compatible with the skill-creator plugin's `run_loop.py` which expects:
+
+```json
+{"skill_name": "...", "evals": [{"id": "...", "prompt": "...", "should_trigger": true}]}
+```
+
+To convert for `run_loop.py`:
+
+```bash
+python3 -c "
+import json, pathlib, uuid
+data = json.loads(pathlib.Path('evals.json').read_text())
+out = {'skill_name': 'SKILL-NAME-HERE', 'evals': [
+    {'id': str(uuid.uuid4()), 'prompt': item['query'], 'should_trigger': item['should_trigger']}
+    for item in data
+]}
+print(json.dumps(out, indent=2))
+" > evals_skill_creator.json
+```

package/skills/sonarcloud-analysis/evals/evals.json

@@ -0,0 +1,50 @@
+[
+  {
+    "query": "Check the SonarCloud quality gate status for our latest PR — I want to see if there are any blockers before we can merge, especially around security vulnerabilities and code coverage",
+    "should_trigger": true
+  },
+  {
+    "query": "Pull the SonarCloud analysis results for our project — show me all the critical and major security vulnerabilities found in the last scan, with file locations and remediation guidance",
+    "should_trigger": true
+  },
+  {
+    "query": "We're in /review and SonarCloud flagged some issues — get the full list of code smells, bugs, and vulnerabilities from the latest analysis so I can address them before the quality gate passes",
+    "should_trigger": true
+  },
+  {
+    "query": "What's our current technical debt ratio in SonarCloud? Show me the metrics dashboard — maintainability rating, reliability rating, security rating, and coverage percentage",
+    "should_trigger": true
+  },
+  {
+    "query": "The SonarCloud quality gate is failing on our PR — pull the specific issues that are blocking it and show me what needs to be fixed, sorted by severity",
+    "should_trigger": true
+  },
+  {
+    "query": "Get the SonarCloud code coverage report for our project — I want to see which modules have low coverage and identify the files that need more tests before our next release",
+    "should_trigger": true
+  },
+  {
+    "query": "Implement a new REST API endpoint for user profile management with CRUD operations, input validation, and proper error handling",
+    "should_trigger": false
+  },
+  {
+    "query": "Search for best practices around implementing OAuth2 PKCE flow in a Node.js application",
+    "should_trigger": false
+  },
+  {
+    "query": "Write a comprehensive market analysis of the DevSecOps tools landscape covering SAST, DAST, and SCA vendors",
+    "should_trigger": false
+  },
+  {
+    "query": "Scrape https://docs.sonarcloud.io and extract the full list of supported languages and analysis rules",
+    "should_trigger": false
+  },
+  {
+    "query": "Build a structured company profile for SonarSource — return JSON with founding year, funding, products, and competitive positioning",
+    "should_trigger": false
+  },
+  {
+    "query": "Add proper citations to docs/research/security-audit-findings.md following our project's citation standards",
+    "should_trigger": false
+  }
+]