forge-workflow 1.0.0

package/.claude/skills/parallel-ai/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: parallel-ai
+description: Tool for web search, data extraction, and research using Parallel AI APIs. Use when you need to search the web, extract data from URLs, enrich company data, or analyze markets. Provides direct API access to Search, Extract, Task, and Deep Research without SDK.
+---
+
+# Parallel AI Research Tool
+
+**4 APIs for research**: Search (web), Extract (URLs), Task (structured data), Deep Research (analysis)
+
+## Setup
+
+API Key: https://platform.parallel.ai
+Store in: `.env.local` as `PARALLEL_API_KEY=your-key`
+
+**Load API key (Windows/Git Bash compatible)**:
+```bash
+API_KEY=$(grep "^PARALLEL_API_KEY=" .env.local | cut -d= -f2)
+```
+
+**Usage in curl**:
+```bash
+curl -s -X POST "https://api.parallel.ai/v1beta/search" \
+  -H "x-api-key: $API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "parallel-beta: search-extract-2025-10-10" \
+  -d '{"objective": "your query"}'
+```
+
+## The 4 APIs at a Glance
+
+| API | Purpose | Speed | Cost | Use For |
+|-----|---------|-------|------|---------|
+| Search | Web search + excerpts | 5-60s | $0.01 | Quick lookups |
+| Extract | Scrape specific URLs | 5-30s | $0.01 | Pricing, data |
+| Task | Structured enrichment | 1-25m | $0.01-0.30 | Companies, data |
+| Deep Research | Multi-source analysis | 5-25m | $0.10-0.30 | Markets, reports |
+
+## Processors (Pick One)
+
+| Processor | Speed | Cost/1K | When |
+|-----------|-------|---------|------|
+| lite | 5-60s | $5 | Simple Q&A |
+| base | 15-100s | $10 | Quick data |
+| core | 1-5m | $25 | Detailed |
+| pro | 3-9m | $100 | Analysis |
+| ultra | 5-25m | $300 | Deep |
+
+## Endpoint URLs
+
+```
+POST https://api.parallel.ai/v1beta/search       (web search)
+POST https://api.parallel.ai/v1beta/extract      (URL scraping)
+POST https://api.parallel.ai/v1beta/tasks/runs   (research tasks)
+GET  https://api.parallel.ai/v1beta/tasks/runs/{id}  (check status)
+```
+
+## Required Headers (All Requests)
+
+```
+x-api-key: your-api-key
+Content-Type: application/json
+parallel-beta: search-extract-2025-10-10     (only Search/Extract)
+```
+
+## Minimal Examples
+
+**Search**: `{"objective": "your question"}`
+
+**Extract**: `{"url": "https://...", "objective": "what to extract"}`
+
+**Task**: `{"input": "company name", "processor": "core"}`
+
+**Task Status**: `GET /v1beta/tasks/runs/{task_id}`
+
+## Task Polling Loop
+
+```
+Create task → get id
+Poll every 2-5s: GET /v1beta/tasks/runs/{id}
+Status: "running" → keep polling
+Status: "completed" → use result
+Status: "failed" → check error
+```
+
+## Limits & Errors
+
+- Rate limit: 2,000 req/min → HTTP 429 (wait, retry)
+- Invalid key: HTTP 401
+- Bad request: HTTP 400 (check parameters)
+- Server error: HTTP 500/503 (retry)
+
+See `api-reference.md` for complete endpoint docs
+See `quick-reference.md` for troubleshooting
+See `research-workflows.md` for real examples

package/.claude/skills/parallel-ai/api-reference.md

@@ -0,0 +1,141 @@
+# API Reference - Minimal
+
+## Search API
+`POST https://api.parallel.ai/v1beta/search`
+
+**Minimal request**:
+```json
+{"objective": "Find Bitcoin price"}
+```
+
+**Full request**:
+```json
+{
+  "objective": "Find current Bitcoin price",
+  "search_queries": ["BTC price today"],
+  "max_results": 5,
+  "mode": "agentic",
+  "source_policy": {"include_domains": ["bloomberg.com", "reuters.com"]}
+}
+```
+
+**Response**:
+```json
+{
+  "results": [
+    {"title": "...", "url": "...", "excerpt": "...", "relevance_score": 0.95}
+  ]
+}
+```
+
+---
+
+## Extract API
+`POST https://api.parallel.ai/v1beta/extract`
+
+**Request**:
+```json
+{
+  "url": "https://example.com/pricing",
+  "objective": "Extract all pricing plans"
+}
+```
+
+**Response**: Extracted JSON/text data
+
+---
+
+## Task API - Create
+`POST https://api.parallel.ai/v1beta/tasks/runs`
+
+**Minimal request**:
+```json
+{
+  "input": "OpenAI",
+  "processor": "core"
+}
+```
+
+**With schema**:
+```json
+{
+  "input": "OpenAI",
+  "processor": "core",
+  "output_schema": {
+    "type": "object",
+    "properties": {
+      "name": {"type": "string"},
+      "founded": {"type": "integer"},
+      "employees": {"type": "integer"}
+    }
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "id": "task_abc123",
+  "status": "queued"
+}
+```
+
+---
+
+## Task API - Get Status
+`GET https://api.parallel.ai/v1beta/tasks/runs/{task_id}`
+
+**Response**:
+```json
+{
+  "id": "task_abc123",
+  "status": "completed",
+  "result": {
+    "content": {"name": "OpenAI", "founded": 2015},
+    "basis": {"citations": [{"url": "...", "excerpt": "..."}]}
+  }
+}
+```
+
+**Status values**: `queued`, `running`, `completed`, `failed`
+
+---
+
+## Deep Research
+`POST https://api.parallel.ai/v1beta/tasks/runs` + use processor `pro` or `ultra`
+
+**Request**:
+```json
+{
+  "input": "Analyze the AI chip market in 2024",
+  "processor": "pro",
+  "output_schema": "text"
+}
+```
+
+**Response**: Markdown report with citations
+
+---
+
+## Error Responses
+
+| Code | Meaning | Fix |
+|------|---------|-----|
+| 401 | Bad key | Check PARALLEL_API_KEY |
+| 400 | Bad request | Validate JSON |
+| 429 | Rate limit | Wait 60s |
+| 500 | Server error | Retry later |
+
+---
+
+## Source Filtering
+
+Include only:
+```json
+{"source_policy": {"include_domains": ["arxiv.org", "nature.com"]}}
+```
+
+Exclude:
+```json
+{"source_policy": {"exclude_domains": ["reddit.com", "twitter.com"]}}
+```

package/.claude/skills/parallel-ai/quick-reference.md

@@ -0,0 +1,100 @@
+# Quick Reference
+
+## Endpoints
+
+| Action | URL | Method |
+|--------|-----|--------|
+| Search | `https://api.parallel.ai/v1beta/search` | POST |
+| Extract | `https://api.parallel.ai/v1beta/extract` | POST |
+| Create task | `https://api.parallel.ai/v1beta/tasks/runs` | POST |
+| Check status | `https://api.parallel.ai/v1beta/tasks/runs/{id}` | GET |
+
+## Headers (All Requests)
+
+```
+x-api-key: $API_KEY
+Content-Type: application/json
+parallel-beta: search-extract-2025-10-10     (Search/Extract only)
+```
+
+**Load API key first (Windows compatible)**:
+```bash
+API_KEY=$(grep "^PARALLEL_API_KEY=" .env.local | cut -d= -f2)
+```
+
+## Processors
+
+| Processor | Speed | Cost/1K |
+|-----------|-------|---------|
+| lite | 5-60s | $5 |
+| base | 15-100s | $10 |
+| core | 1-5m | $25 |
+| pro | 3-9m | $100 |
+| ultra | 5-25m | $300 |
+
+## Task Polling Loop
+
+```
+1. POST /v1beta/tasks/runs → get {id}
+2. Loop: GET /v1beta/tasks/runs/{id}
+3. If status="running" → wait 2-5s → repeat
+4. If status="completed" → use result.content
+5. If status="failed" → check error
+```
+
+## Troubleshooting
+
+**"401 Unauthorized"**
+- Check API key: `echo $PARALLEL_API_KEY`
+- Regenerate at: https://platform.parallel.ai
+
+**"429 Too Many Requests"**
+- Hit rate limit (2,000/min)
+- Wait 60s, retry with backoff
+- Backoff: 2^attempt seconds (max 30s)
+
+**"Empty search results"**
+- Broaden objective
+- Remove source_policy filters
+- Try different keywords
+
+**Task stuck in "running"**
+- Normal for complex tasks (1-25m)
+- Set timeout to 1800 (30 min)
+- Use polling loop, don't give up
+
+**"Output doesn't match schema"**
+- Simplify schema
+- Add clearer descriptions
+- Don't specify exact field names
+
+## Cost Calculator
+
+Formula: `(tasks × cost_per_1k) ÷ 1000`
+
+Examples:
+- 100 lite tasks: (100 × 5) ÷ 1000 = **$0.50**
+- 50 core tasks: (50 × 25) ÷ 1000 = **$1.25**
+- 10 pro tasks: (10 × 100) ÷ 1000 = **$1.00**
+
+## When to Use Each API
+
+**Search** (fast, $0.01): Quick lookups, find sources
+
+**Extract** (fast, $0.01): Scrape known URLs, get pricing
+
+**Task** ($0.01-0.30): Enrichment, verification, structured data
+
+**Deep Research** ($0.10-0.30, slow): Analysis, reports, market research
+
+## Rate Limits
+
+- Task API: 2,000 req/min
+- Returns 429 when exceeded
+- Implement exponential backoff
+
+## Links
+
+- Docs: https://docs.parallel.ai
+- API Key: https://platform.parallel.ai
+- Status: https://status.parallel.ai

package/.claude/skills/parallel-ai/research-workflows.md

@@ -0,0 +1,77 @@
+# Key Research Workflows
+
+## 1. Quick Fact Lookup (30 seconds, $0.01)
+
+Find information quickly.
+
+**Request**:
+```json
+{
+  "objective": "What is the current Bitcoin price?",
+  "max_results": 3,
+  "mode": "agentic"
+}
+```
+
+**Use**: Stock prices, quick questions, news, facts
+
+---
+
+## 2. Company Research (5 minutes, $0.025)
+
+Get structured company information.
+
+**Create task**:
+```json
+{
+  "input": "OpenAI",
+  "processor": "core",
+  "output_schema": {
+    "type": "object",
+    "properties": {
+      "name": {"type": "string"},
+      "founded_year": {"type": "integer"},
+      "headquarters": {"type": "string"},
+      "employee_count": {"type": "integer"},
+      "key_products": {"type": "array", "items": {"type": "string"}}
+    }
+  }
+}
+```
+
+**Poll**: `GET /task/{task_id}` until status="completed"
+
+**Use**: Company enrichment, lead qualification, research
+
+---
+
+## 3. Market Analysis Report (10 minutes, $0.10)
+
+Comprehensive market intelligence.
+
+**Create task**:
+```json
+{
+  "input": "Analyze the AI chatbot market. Include: size, growth, key players, trends, competitive threats",
+  "processor": "pro",
+  "output_schema": "text"
+}
+```
+
+**Poll**: `GET /task/{task_id}` until status="completed"
+
+**Result**: Markdown report with citations
+
+**Use**: Strategic analysis, market research, reports
+
+---
+
+## Cost & Processor Guide
+
+| Task | Processor | Speed | Cost |
+|------|-----------|-------|------|
+| Simple Q&A | lite | 5-60s | $0.005 |
+| Quick data | base | 15-100s | $0.01 |
+| Enrichment | core | 1-5m | $0.025 |
+| Analysis | pro | 3-9m | $0.10 |
+| Deep analysis | ultra | 5-25m | $0.30 |

package/.claude/skills/sonarcloud/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: sonarcloud
+description: Pull issues, metrics, quality gates, and analysis data from SonarCloud. Use when checking code quality, security vulnerabilities, test coverage, technical debt, or CI/CD quality gates.
+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
+- Never expose tokens in output
+- Validate API responses before processing
+- Handle pagination for large result sets
+</constraints>
+
+<workflow>
+1. Verify credentials are available
+2. Determine the analysis scope (project, branch, PR)
+3. Query relevant endpoints
+4. Process and correlate results
+5. Return actionable summary to main context
+</workflow>
+
+# SonarCloud Integration
+
+**Base**: `https://sonarcloud.io/api` | **Auth**: `Bearer $SONARCLOUD_TOKEN`
+
+## Quick Start
+
+```bash
+# Set credentials (generate token at sonarcloud.io/account/security)
+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'
+```
+
+## TypeScript Client
+
+See [sonarcloud.ts](../../../next-app/src/lib/integrations/sonarcloud.ts):
+
+```typescript
+import { createSonarCloudClient } from '@/lib/integrations/sonarcloud';
+const client = createSonarCloudClient('my-org');
+await client.getProjectHealth('my-project');
+await client.getQualityGateStatus('my-project', { pullRequest: '123' });
+```
+
+## Detailed Reference
+
+For complete API parameters and response schemas, see [reference.md](reference.md).