forge-workflow 1.0.0

package/.claude/skills/sonarcloud/reference.md

@@ -0,0 +1,466 @@
+# SonarCloud API Reference
+
+Complete parameter and response documentation for all endpoints.
+
+## Issues (`/api/issues/search`)
+
+### Parameters
+
+| Parameter | Description | Values |
+| --------- | ----------- | ------ |
+| `organization` | Org key | Required |
+| `componentKeys` | Project key(s) | Comma-separated |
+| `types` | Issue types | `BUG`, `VULNERABILITY`, `CODE_SMELL`, `SECURITY_HOTSPOT` |
+| `severities` | Severity | `BLOCKER`, `CRITICAL`, `MAJOR`, `MINOR`, `INFO` |
+| `statuses` | Status | `OPEN`, `CONFIRMED`, `REOPENED`, `RESOLVED`, `CLOSED` |
+| `resolutions` | Resolution | `FALSE-POSITIVE`, `WONTFIX`, `FIXED`, `REMOVED` |
+| `resolved` | Filter | `true`, `false` |
+| `branch` | Branch name | String |
+| `pullRequest` | PR number | String |
+| `createdAfter` | Date filter | `YYYY-MM-DD` |
+| `createdBefore` | Date filter | `YYYY-MM-DD` |
+| `languages` | Languages | `java`, `typescript`, `python`, etc. |
+| `rules` | Rule keys | Comma-separated |
+| `tags` | Issue tags | Comma-separated |
+| `assignees` | Assigned users | Comma-separated |
+| `authors` | Code authors | Comma-separated |
+| `scopes` | Scope | `MAIN`, `TEST` |
+| `inNewCodePeriod` | New code only | `true`, `false` |
+| `facets` | Aggregations | `severities`, `types`, `rules`, `tags` |
+| `p` | Page number | Integer (1-based) |
+| `ps` | Page size | Integer (max 500) |
+| `s` | Sort field | `CREATION_DATE`, `UPDATE_DATE`, `SEVERITY` |
+| `asc` | Sort order | `true`, `false` |
+
+### Response
+
+```json
+{
+  "total": 150,
+  "paging": { "pageIndex": 1, "pageSize": 100, "total": 150 },
+  "issues": [{
+    "key": "AYx...",
+    "rule": "typescript:S1234",
+    "severity": "MAJOR",
+    "component": "my-project:src/file.ts",
+    "line": 42,
+    "message": "Remove this unused variable.",
+    "type": "CODE_SMELL",
+    "status": "OPEN",
+    "effort": "5min",
+    "tags": ["unused"],
+    "creationDate": "2024-01-15T10:30:00+0000"
+  }],
+  "facets": [{ "property": "severities", "values": [{ "val": "MAJOR", "count": 50 }] }]
+}
+```
+
+---
+
+## Metrics (`/api/measures/component`)
+
+### Parameters
+
+| Parameter | Description |
+| --------- | ----------- |
+| `component` | Project key (required) |
+| `metricKeys` | Metrics (comma-separated) |
+| `branch` | Branch name |
+| `pullRequest` | PR number |
+| `additionalFields` | `metrics`, `periods` |
+
+### All Metric Keys
+
+| Category | Keys |
+| -------- | ---- |
+| Size | `ncloc`, `lines`, `statements`, `functions`, `classes`, `files` |
+| Complexity | `complexity`, `cognitive_complexity` |
+| Coverage | `coverage`, `line_coverage`, `branch_coverage`, `tests`, `test_success_density`, `uncovered_lines`, `uncovered_conditions` |
+| Duplication | `duplicated_lines`, `duplicated_lines_density`, `duplicated_blocks`, `duplicated_files` |
+| Issues | `bugs`, `vulnerabilities`, `code_smells`, `security_hotspots` |
+| Ratings | `sqale_rating`, `reliability_rating`, `security_rating`, `security_review_rating` (1=A to 5=E) |
+| Debt | `sqale_index` (minutes), `sqale_debt_ratio` (%) |
+| Quality Gate | `alert_status`, `quality_gate_details` |
+| New Code | `new_bugs`, `new_vulnerabilities`, `new_code_smells`, `new_coverage`, `new_duplicated_lines_density` |
+
+### Response
+
+```json
+{
+  "component": {
+    "key": "my-project",
+    "name": "My Project",
+    "measures": [
+      { "metric": "bugs", "value": "12" },
+      { "metric": "coverage", "value": "78.5" },
+      { "metric": "sqale_rating", "value": "2.0" }
+    ]
+  }
+}
+```
+
+---
+
+## Quality Gate (`/api/qualitygates/project_status`)
+
+### Parameters
+
+| Parameter | Description |
+| --------- | ----------- |
+| `projectKey` | Project key (required) |
+| `branch` | Branch name |
+| `pullRequest` | PR number |
+
+### Response
+
+```json
+{
+  "projectStatus": {
+    "status": "ERROR",
+    "conditions": [{
+      "status": "ERROR",
+      "metricKey": "new_coverage",
+      "comparator": "LT",
+      "errorThreshold": "80",
+      "actualValue": "65.3"
+    }],
+    "ignoredConditions": false
+  }
+}
+```
+
+---
+
+## Security Hotspots (`/api/hotspots/search`)
+
+### Parameters
+
+| Parameter | Description | Values |
+| --------- | ----------- | ------ |
+| `projectKey` | Project key | Required |
+| `branch` | Branch name | String |
+| `pullRequest` | PR number | String |
+| `status` | Status | `TO_REVIEW`, `REVIEWED` |
+| `resolution` | Resolution | `FIXED`, `SAFE`, `ACKNOWLEDGED` |
+| `inNewCodePeriod` | New code | `true`, `false` |
+| `p` / `ps` | Pagination | Integer |
+
+### Response
+
+```json
+{
+  "paging": { "total": 5 },
+  "hotspots": [{
+    "key": "...",
+    "component": "my-project:src/auth.ts",
+    "securityCategory": "sql-injection",
+    "vulnerabilityProbability": "HIGH",
+    "status": "TO_REVIEW",
+    "message": "Make sure this SQL query is safe.",
+    "line": 42
+  }]
+}
+```
+
+---
+
+## Projects (`/api/projects/search`)
+
+### Parameters
+
+| Parameter | Description |
+| --------- | ----------- |
+| `organization` | Org key |
+| `q` | Search query |
+| `qualifiers` | `TRK` (project), `APP` |
+| `p` / `ps` | Pagination |
+
+---
+
+## Analysis History (`/api/project_analyses/search`)
+
+### Parameters
+
+| Parameter | Description |
+| --------- | ----------- |
+| `project` | Project key |
+| `branch` | Branch name |
+| `from` / `to` | Date range |
+| `p` / `ps` | Pagination |
+
+### Response
+
+```json
+{
+  "analyses": [{
+    "key": "AYx...",
+    "date": "2024-01-15T10:30:00+0000",
+    "projectVersion": "1.2.0",
+    "revision": "abc123def",
+    "events": [{ "category": "VERSION", "name": "1.2.0" }]
+  }]
+}
+```
+
+---
+
+## Metrics History (`/api/measures/search_history`)
+
+### Parameters
+
+| Parameter | Description |
+| --------- | ----------- |
+| `component` | Project key |
+| `metrics` | Metric keys |
+| `from` / `to` | Date range (`YYYY-MM-DD`) |
+| `branch` | Branch name |
+| `p` / `ps` | Pagination |
+
+---
+
+## Component Tree (`/api/components/tree`)
+
+### Parameters
+
+| Parameter | Description |
+| --------- | ----------- |
+| `component` | Project key |
+| `branch` | Branch name |
+| `qualifiers` | `FIL` (file), `DIR`, `UTS` (test) |
+| `metricKeys` | Metrics per component |
+| `strategy` | `children`, `leaves`, `all` |
+| `q` | Search query |
+| `s` / `asc` | Sort field / ascending |
+| `metricSort` | Metric to sort by |
+
+---
+
+## Duplications (`/api/duplications/show`)
+
+Get detailed duplicate code blocks for a specific file.
+
+### Parameters
+
+| Parameter | Description |
+| --------- | ----------- |
+| `key` | File key (required) - format: `project-key:path/to/file.ts` |
+| `branch` | Branch name |
+| `pullRequest` | PR number |
+
+### Response
+
+```json
+{
+  "duplications": [
+    {
+      "blocks": [
+        {
+          "from": 1,
+          "size": 20,
+          "_ref": "1"
+        },
+        {
+          "from": 50,
+          "size": 20,
+          "_ref": "2"
+        }
+      ]
+    }
+  ],
+  "files": {
+    "1": {
+      "key": "my-project:src/utils/helpers.ts",
+      "name": "helpers.ts",
+      "projectName": "My Project"
+    },
+    "2": {
+      "key": "my-project:src/utils/common.ts",
+      "name": "common.ts",
+      "projectName": "My Project"
+    }
+  }
+}
+```
+
+### Workflow: Find All Duplicates
+
+```bash
+# 1. Get files with most duplication
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/components/tree?component=$PROJECT&qualifiers=FIL&metricKeys=duplicated_lines_density&s=metric&metricSort=duplicated_lines_density&asc=false&ps=20"
+
+# 2. For each file, get duplicate blocks
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/duplications/show?key=my-project:src/file.ts"
+```
+
+---
+
+## Rules (`/api/rules/search`)
+
+### Parameters
+
+| Parameter | Description |
+| --------- | ----------- |
+| `languages` | Filter by language |
+| `severities` | Filter by severity |
+| `types` | Filter by type |
+| `tags` | Filter by tags |
+| `q` | Search query |
+| `p` / `ps` | Pagination |
+
+---
+
+## Sources (`/api/sources/*`)
+
+### Raw Source Code (`/api/sources/raw`)
+
+| Parameter | Description |
+| --------- | ----------- |
+| `key` | File key (required) - format: `project:path/to/file.ts` |
+| `branch` | Branch name |
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/sources/raw?key=my-project:src/utils/helpers.ts"
+```
+
+### SCM Blame (`/api/sources/scm`)
+
+| Parameter | Description |
+| --------- | ----------- |
+| `key` | File key (required) |
+| `from` | Start line |
+| `to` | End line |
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/sources/scm?key=my-project:src/utils/helpers.ts"
+```
+
+**Response**: Returns author, date, and revision for each line.
+
+---
+
+## Compute Engine (`/api/ce/activity`)
+
+Get background task status (analysis jobs).
+
+| Parameter | Description |
+| --------- | ----------- |
+| `component` | Project key |
+| `status` | `SUCCESS`, `FAILED`, `CANCELED`, `PENDING`, `IN_PROGRESS` |
+| `type` | Task type (e.g., `REPORT`) |
+| `minSubmittedAt` | Filter by submission date |
+| `maxExecutedAt` | Filter by execution date |
+| `p` / `ps` | Pagination |
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/ce/activity?component=my-project&status=FAILED"
+```
+
+---
+
+## Quality Profiles (`/api/qualityprofiles/search`)
+
+| Parameter | Description |
+| --------- | ----------- |
+| `language` | Filter by language |
+| `project` | Project key |
+| `qualityProfile` | Profile name |
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/qualityprofiles/search?language=ts"
+```
+
+---
+
+## Languages (`/api/languages/list`)
+
+List all supported languages.
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/languages/list"
+```
+
+**Response**: `{ "languages": [{ "key": "ts", "name": "TypeScript" }, ...] }`
+
+---
+
+## Branches (`/api/project_branches/list`)
+
+| Parameter | Description |
+| --------- | ----------- |
+| `project` | Project key (required) |
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/project_branches/list?project=my-project"
+```
+
+**Response**: `{ "branches": [{ "name": "main", "isMain": true, "type": "LONG", "status": { "qualityGateStatus": "OK" } }] }`
+
+---
+
+## Badges (`/api/project_badges/*`)
+
+### Measure Badge (`/api/project_badges/measure`)
+
+| Parameter | Description |
+| --------- | ----------- |
+| `project` | Project key |
+| `metric` | `bugs`, `coverage`, `code_smells`, `vulnerabilities`, etc. |
+| `branch` | Branch name |
+
+Returns SVG badge image.
+
+```bash
+curl "https://sonarcloud.io/api/project_badges/measure?project=my-project&metric=coverage"
+```
+
+### Quality Gate Badge (`/api/project_badges/quality_gate`)
+
+| Parameter | Description |
+| --------- | ----------- |
+| `project` | Project key |
+| `branch` | Branch name |
+
+```bash
+curl "https://sonarcloud.io/api/project_badges/quality_gate?project=my-project"
+```
+
+---
+
+## Pagination Example
+
+```bash
+PAGE=1
+while true; do
+  R=$(curl -s -H "Authorization: Bearer $TOKEN" \
+    "https://sonarcloud.io/api/issues/search?organization=$ORG&componentKeys=$PROJECT&p=$PAGE&ps=500")
+  echo $R | jq '.issues[]'
+  [ $((PAGE * 500)) -ge $(echo $R | jq '.total') ] && break
+  PAGE=$((PAGE + 1))
+done
+```
+
+---
+
+## Error Codes
+
+| Code | Meaning | Fix |
+| ---- | ------- | --- |
+| 401 | Invalid token | Check `SONARCLOUD_TOKEN` |
+| 403 | No permission | Verify project access |
+| 404 | Not found | Check project/org key |
+| 400 | Bad request | Check parameter values |
+
+---
+
+## References
+
+- [SonarCloud Web API](https://sonarcloud.io/web_api)
+- [SonarCloud Docs](https://docs.sonarsource.com/sonarcloud/)

package/README.md

@@ -0,0 +1,205 @@
+# Forge
+
+A 9-stage TDD-first workflow for Claude Code. Ship features with confidence using test-driven development, research-first planning, and comprehensive documentation.
+
+```
+/status → /research → /plan → /dev → /check → /ship → /review → /merge → /verify
+```
+
+## Installation
+
+### Option 1: npm (Recommended)
+
+```bash
+npm install forge-workflow
+```
+
+### Option 2: bun
+
+```bash
+bun add forge-workflow
+```
+
+### Option 3: curl (No package manager)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/harshanandak/forge/main/install.sh | bash
+```
+
+### Option 4: GitHub Template (New projects)
+
+1. Click "Use this template" on GitHub
+2. Clone your new repo
+3. Start with `/status`
+
+## The 9 Stages
+
+| Stage | Command | What It Does |
+|-------|---------|--------------|
+| 1 | `/status` | Check current context, active work, recent completions |
+| 2 | `/research` | Deep research with web search, document findings |
+| 3 | `/plan` | Create implementation plan, branch, tracking |
+| 4 | `/dev` | TDD development (RED-GREEN-REFACTOR cycles) |
+| 5 | `/check` | Validation (type/lint/security/tests) |
+| 6 | `/ship` | Create PR with full documentation |
+| 7 | `/review` | Address ALL PR feedback |
+| 8 | `/merge` | Update docs, merge, cleanup |
+| 9 | `/verify` | Final documentation verification |
+
+## Quick Start
+
+```bash
+# 1. Check what's happening
+/status
+
+# 2. Research your feature
+/research user-authentication
+
+# 3. Plan the implementation
+/plan user-authentication
+
+# 4. Develop with TDD
+/dev
+
+# 5. Validate everything
+/check
+
+# 6. Ship it
+/ship
+```
+
+## Core Principles
+
+### TDD-First
+- Write tests BEFORE implementation
+- RED: Write failing test
+- GREEN: Make it pass
+- REFACTOR: Clean up
+- Commit after each GREEN cycle
+
+### Research-First
+- Understand before building
+- Document decisions with evidence
+- Use web research for best practices
+- Create `docs/research/<feature>.md`
+
+### Security Built-In
+- OWASP Top 10 analysis for every feature
+- Security tests as part of TDD
+- Automated scans + manual review
+
+### Documentation Progressive
+- Update docs at each relevant stage
+- Verify completeness with `/verify`
+- Never accumulate doc debt
+
+## Directory Structure
+
+After installation:
+
+```
+your-project/
+├── .claude/
+│   ├── commands/           # 9 workflow commands
+│   │   ├── status.md
+│   │   ├── research.md
+│   │   ├── plan.md
+│   │   ├── dev.md
+│   │   ├── check.md
+│   │   ├── ship.md
+│   │   ├── review.md
+│   │   ├── merge.md
+│   │   └── verify.md
+│   ├── rules/
+│   │   └── workflow.md     # Workflow rules
+│   ├── skills/
+│   │   ├── parallel-ai/    # Web research skill
+│   │   └── sonarcloud/     # Code quality skill
+│   └── scripts/
+│       └── load-env.sh
+└── docs/
+    ├── research/
+    │   └── TEMPLATE.md     # Research doc template
+    └── WORKFLOW.md         # Complete guide
+```
+
+## Configuration
+
+Customize commands for your tech stack in your project's `CLAUDE.md`:
+
+```markdown
+## Build Commands
+- Type check: `npm run typecheck`
+- Lint: `npm run lint`
+- Test: `npm run test`
+- Security: `npm audit`
+```
+
+## Optional: Beads Issue Tracking
+
+Forge integrates with [Beads](https://github.com/beads-ai/beads-cli) for persistent issue tracking across sessions:
+
+```bash
+# Install Beads (optional)
+npm install -g beads-cli
+
+# Initialize in your project
+bd init
+
+# Create issues
+bd create "Add user authentication"
+
+# Track progress
+bd update <id> --status in_progress
+bd close <id>
+```
+
+## Workflow Visualization
+
+```
+┌─────────┐
+│ /status │ → Check current stage & context
+└────┬────┘
+     │
+┌────▼──────┐
+│ /research │ → Deep research, save to docs/research/
+└────┬──────┘
+     │
+┌────▼────┐
+│  /plan  │ → Create plan, branch, tracking
+└────┬────┘
+     │
+┌────▼───┐
+│  /dev  │ → TDD implementation (RED-GREEN-REFACTOR)
+└────┬───┘
+     │
+┌────▼────┐
+│ /check  │ → Validation (type/lint/tests/security)
+└────┬────┘
+     │
+┌────▼────┐
+│  /ship  │ → Create PR with full documentation
+└────┬────┘
+     │
+┌────▼─────┐
+│ /review  │ → Address ALL PR issues
+└────┬─────┘
+     │
+┌────▼─────┐
+│  /merge  │ → Update docs, merge PR, cleanup
+└────┬─────┘
+     │
+┌────▼──────┐
+│  /verify  │ → Final documentation check
+└───────────┘
+     │
+     ✓ Complete
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please read the workflow guide at `docs/WORKFLOW.md` before submitting PRs.