forge-workflow 1.0.0

package/.claude/commands/sonarcloud.md

@@ -0,0 +1,156 @@
+---
+name: SonarCloud Query
+description: Pull issues, metrics, quality gates, and analysis data from SonarCloud
+category: Code Quality
+tags: [sonarcloud, issues, metrics, quality]
+---
+
+# SonarCloud Query Command
+
+Pull code quality data from SonarCloud. Requires `SONARCLOUD_TOKEN` environment variable.
+
+## Arguments
+
+- `$ARGUMENTS` - Query type and parameters
+
+## Query Types
+
+| Query | Description | Example |
+|-------|-------------|---------|
+| `issues <project>` | Get open issues | `/sonarcloud issues my-project` |
+| `metrics <project>` | Get code metrics | `/sonarcloud metrics my-project` |
+| `gate <project>` | Quality gate status | `/sonarcloud gate my-project` |
+| `health <project>` | Full health report | `/sonarcloud health my-project` |
+| `pr <project> <pr#>` | PR analysis | `/sonarcloud pr my-project 123` |
+| `hotspots <project>` | Security hotspots | `/sonarcloud hotspots my-project` |
+| `history <project>` | Analysis history | `/sonarcloud history my-project` |
+
+## Filters (append to query)
+
+| Filter | Description | Example |
+|--------|-------------|---------|
+| `--branch <name>` | Filter by branch | `--branch develop` |
+| `--severity <levels>` | Filter severity | `--severity BLOCKER,CRITICAL` |
+| `--type <types>` | Filter issue type | `--type BUG,VULNERABILITY` |
+| `--new-code` | Only new code issues | `--new-code` |
+
+## Instructions
+
+<steps>
+
+1. Parse the query from `$ARGUMENTS` to determine:
+   - Query type (issues, metrics, gate, health, pr, hotspots, history)
+   - Project key
+   - Optional filters (branch, severity, type, new-code, etc.)
+2. Check for `SONARCLOUD_TOKEN` environment variable. If not set, inform user.
+3. Check for `SONARCLOUD_ORG` environment variable or ask user for organization key.
+4. Execute the appropriate API call using curl or the TypeScript client at `next-app/src/lib/integrations/sonarcloud.ts`
+5. Format and present results clearly:
+   - For issues: Group by severity/type, show file, line, message
+   - For metrics: Show as table with metric name and value
+   - For quality gate: Show pass/fail with failed conditions
+   - For health: Comprehensive summary with all data
+6. Offer follow-up actions:
+   - "Show issues in specific file?"
+   - "Get more details on a specific issue?"
+   - "Compare with another branch?"
+
+</steps>
+
+## Example Outputs
+
+### Issues Query
+
+```
+📋 Open Issues for my-project (branch: main)
+
+Total: 45 issues
+
+By Severity:
+  🔴 BLOCKER: 2
+  🟠 CRITICAL: 5
+  🟡 MAJOR: 18
+  ⚪ MINOR: 15
+  ⚫ INFO: 5
+
+By Type:
+  🐛 BUG: 8
+  🔓 VULNERABILITY: 3
+  💩 CODE_SMELL: 34
+
+Top Issues:
+1. [CRITICAL] src/auth/login.ts:42 - SQL injection vulnerability
+2. [BLOCKER] src/api/users.ts:156 - Null pointer dereference
+...
+```
+
+### Metrics Query
+
+```
+📊 Metrics for my-project
+
+| Metric | Value |
+|--------|-------|
+| Lines of Code | 51,234 |
+| Coverage | 78.5% |
+| Duplications | 3.2% |
+| Bugs | 8 |
+| Vulnerabilities | 3 |
+| Code Smells | 34 |
+| Technical Debt | 4d 2h |
+| Maintainability | A |
+| Reliability | B |
+| Security | A |
+```
+
+### Quality Gate Query
+
+```
+🚦 Quality Gate: ❌ FAILED
+
+Failed Conditions:
+| Metric | Threshold | Actual |
+|--------|-----------|--------|
+| Coverage on New Code | ≥ 80% | 65.3% |
+| New Bugs | = 0 | 2 |
+
+Passed Conditions:
+| Metric | Threshold | Actual |
+|--------|-----------|--------|
+| New Vulnerabilities | = 0 | 0 |
+| Duplicated Lines | ≤ 3% | 1.2% |
+```
+
+## API Reference
+
+Base URL: `https://sonarcloud.io/api`
+
+### Key Endpoints
+
+```bash
+# Issues
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/issues/search?organization=$ORG&componentKeys=$PROJECT&resolved=false"
+
+# Metrics
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/measures/component?component=$PROJECT&metricKeys=bugs,vulnerabilities,coverage"
+
+# Quality Gate
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/qualitygates/project_status?projectKey=$PROJECT"
+
+# Hotspots
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/hotspots/search?projectKey=$PROJECT&status=TO_REVIEW"
+```
+
+## Full Skill Reference
+
+See `.claude/skills/sonarcloud/SKILL.md` for complete API documentation including:
+
+- All endpoints and parameters
+- Response structures
+- Pagination handling
+- Advanced filtering
+- Integration patterns

package/.claude/commands/status.md

@@ -0,0 +1,76 @@
+---
+description: Check current stage and context
+---
+
+Check where you are in the project and what work is in progress.
+
+# Status Check
+
+This command helps you understand the current state of the project before starting new work.
+
+## Usage
+
+```bash
+/status
+```
+
+## What This Command Does
+
+### Step 1: Read Current Progress
+```bash
+cat docs/planning/PROGRESS.md
+```
+- What's completed?
+- What's the next priority?
+- Which week/milestone are we in?
+
+### Step 2: Check Active Work
+```bash
+# Active Beads issues
+bd list --status in_progress
+
+# Active OpenSpec proposals
+openspec list --active
+```
+
+### Step 3: Review Recent Work
+```bash
+# Recent commits
+git log --oneline -10
+
+# Recently completed Beads
+bd list --status done --limit 5
+
+# Archived OpenSpec proposals
+openspec list --archived --limit 3
+```
+
+### Step 4: Determine Context
+- **New feature**: No active work, ready to start fresh
+- **Continuing work**: In-progress issues found, resume where left off
+- **Review needed**: Work marked complete, needs review/merge
+
+## Example Output
+
+```
+✓ Current Stage: Week 7, AI Integration 100% complete
+✓ Next Priority: Week 8 - Billing & Testing
+
+Active Work:
+  - No in-progress Beads issues
+  - No active OpenSpec proposals
+
+Recent Completions:
+  - bd-a3f8: BlockSuite simplification (merged 2 days ago)
+  - bd-k2m5: Auth RLS policies (merged 5 days ago)
+
+Context: Ready for new feature
+
+Next: /research <feature-name>
+```
+
+## Next Steps
+
+- **If starting new work**: Run `/research <feature-name>`
+- **If continuing work**: Resume with appropriate phase command
+- **If reviewing**: Run `/review <pr-number>` or `/merge <pr-number>`

package/.claude/commands/verify.md

@@ -0,0 +1,185 @@
+---
+description: Cross-check all documentation, update if needed
+---
+
+Final verification that all documentation is properly updated across the entire workflow.
+
+# Verify
+
+This command performs a final documentation verification after merge.
+
+## Usage
+
+```bash
+/verify
+```
+
+## What This Command Does
+
+### Step 1: Read Feature Details
+```bash
+# Get feature name, Beads ID, PR number from git log
+git log --oneline -1
+
+# Get research doc if exists
+git show HEAD:docs/research/<feature-slug>.md
+```
+
+### Step 2: Cross-Check All Documentation Files
+
+**A. docs/planning/PROGRESS.md**:
+- ✓ Feature listed in completed section?
+- ✓ Completion date accurate?
+- ✓ Beads issue ID referenced?
+- ✓ PR number linked?
+- ✓ Research doc path included?
+- **If missing/incomplete**: Update now
+
+**B. docs/reference/API_REFERENCE.md** (if API changes):
+- ✓ New endpoints documented?
+- ✓ Request/response schemas complete?
+- ✓ Authentication requirements listed?
+- ✓ Example requests included?
+- ✓ Error responses documented?
+- **If missing/incomplete**: Update now
+
+**C. docs/architecture/** (if strategic):
+- ✓ Architecture diagrams updated?
+- ✓ New patterns documented?
+- ✓ System overview reflects changes?
+- ✓ Decision records (ADRs) added if applicable?
+- ✓ Component relationships accurate?
+- **If missing/incomplete**: Update now
+
+**D. README.md** (if user-facing):
+- ✓ Features list updated?
+- ✓ Configuration options documented?
+- ✓ Installation/setup steps current?
+- ✓ Usage examples included?
+- ✓ Screenshots/demos updated (if visual)?
+- **If missing/incomplete**: Update now
+
+**E. docs/testing/** (if new patterns):
+- ✓ New test utilities documented?
+- ✓ Testing strategy updated?
+- ✓ Example tests included?
+- ✓ Coverage requirements noted?
+- **If missing/incomplete**: Update now
+
+**F. docs/research/<feature-slug>.md** (if exists):
+- ✓ Research document exists?
+- ✓ All sections complete?
+- ✓ Key decisions documented with reasoning?
+- ✓ TDD scenarios identified?
+- ✓ OWASP Top 10 checklist completed?
+- **If missing/incomplete**: Update now
+
+### Step 3: Cross-Reference Consistency
+
+- ✓ PROGRESS.md links to research doc?
+- ✓ Research doc referenced in merged PR?
+- ✓ API changes in API_REFERENCE.md match code?
+- ✓ Architecture docs consistent with implementation?
+- ✓ README.md examples actually work?
+
+### Step 4: Fix Missing/Incomplete Documentation
+
+If any documentation is missing or incomplete:
+```bash
+# Make updates to relevant files
+
+# Commit documentation fixes
+git add docs/ README.md
+git commit -m "docs: post-merge documentation verification
+
+Cross-checked and updated all documentation after <feature-name> merge:
+- Updated: [list of files updated]
+- Fixed: [what was missing/incomplete]
+- Verified: All cross-references consistent"
+
+git push
+```
+
+### Step 5: Final Verification Checklist
+
+- [ ] PROGRESS.md: Feature completion documented
+- [ ] API_REFERENCE.md: API changes documented (if applicable)
+- [ ] Architecture docs: System changes reflected (if applicable)
+- [ ] README.md: User-facing updates complete (if applicable)
+- [ ] Testing docs: New patterns documented (if applicable)
+- [ ] Research doc: Complete and linked (if exists)
+- [ ] Cross-references: All links working and consistent
+
+## Example Output (All Complete)
+
+```
+✓ Documentation Verification Complete
+
+Checked Files:
+  ✓ docs/planning/PROGRESS.md: Complete and accurate
+  ✓ docs/reference/API_REFERENCE.md: 3 endpoints fully documented
+  ✓ docs/architecture/: Diagrams updated, consistent with code
+  ✓ README.md: Features list and examples updated
+  ✓ docs/testing/: New test patterns documented
+  ✓ docs/research/stripe-billing.md: Complete with all sections
+
+Cross-References:
+  ✓ PROGRESS.md → research doc: Valid link
+  ✓ PR #123 → research doc: Referenced
+  ✓ API_REFERENCE.md ↔ Code: Consistent
+  ✓ Architecture docs ↔ Implementation: Aligned
+  ✓ README.md examples: Tested and working
+
+No documentation issues found!
+
+Workflow complete! 🎉
+Ready for next task: /status
+```
+
+## Example Output (Issues Found & Fixed)
+
+```
+✓ Documentation Verification Complete
+
+Found Issues:
+  ✗ docs/planning/PROGRESS.md: Missing completion date
+  ✗ docs/reference/API_REFERENCE.md: Error responses not documented
+  ✗ README.md: Missing configuration example
+
+Fixed All Issues:
+  ✓ Updated PROGRESS.md: Added completion date (2026-01-28)
+  ✓ Updated API_REFERENCE.md: Added error response schemas
+  ✓ Updated README.md: Added .env configuration example
+  ✓ Committed: docs: post-merge documentation verification
+
+Final Verification:
+  ✓ All documentation complete
+  ✓ All cross-references valid
+  ✓ All examples tested
+
+Workflow complete! 🎉
+Ready for next task: /status
+```
+
+## Integration with Workflow
+
+```
+1. /status               → Understand current context
+2. /research <name>      → Research and document
+3. /plan <feature-slug>  → Create plan and tracking
+4. /dev                  → Implement with TDD
+5. /check                → Validate
+6. /ship                 → Create PR
+7. /review               → Address comments
+8. /merge                → Merge and cleanup
+9. /verify               → Final documentation check (you are here) ✓
+```
+
+## Tips
+
+- **Run after every merge**: Catch documentation gaps immediately
+- **Fix immediately**: Don't accumulate documentation debt
+- **Cross-check everything**: Verify consistency across all docs
+- **Test examples**: Ensure README examples actually work
+- **Complete checklist**: All items must be verified
+- **Ready for next feature**: After /verify, run /status for next task

package/.claude/rules/workflow.md

@@ -0,0 +1,98 @@
+# Forge Workflow Rules
+
+9-stage TDD-first development workflow for any project.
+
+## Workflow Commands
+
+| Phase | Command | Purpose |
+|-------|---------|---------|
+| 1 | `/status` | Check current stage, active work, recent completions |
+| 2 | `/research` | Deep research with parallel-ai, save to docs/research/ |
+| 3 | `/plan` | Create formal plan, branch, OpenSpec proposal (if strategic) |
+| 4 | `/dev` | Implement with TDD, parallel if needed |
+| 5 | `/check` | Type check, lint, code review, security, tests |
+| 6 | `/ship` | Push and create PR with full documentation |
+| 7 | `/review` | Handle ALL PR issues (GitHub Actions, reviewers, CI/CD) |
+| 8 | `/merge` | Update docs, merge PR, archive, cleanup |
+| 9 | `/verify` | Final documentation verification, update if needed |
+
+## Core Principles
+
+### TDD-First Development
+- Tests written UPFRONT in RED-GREEN-REFACTOR cycles
+- No implementation without failing test first
+- Commit after each GREEN cycle
+
+### Research-First Approach
+- All features start with comprehensive research
+- Use parallel-ai for web research (MANDATORY)
+- Document findings in `docs/research/<feature-slug>.md`
+
+### Security Built-In
+- OWASP Top 10 analysis for every feature
+- Security test scenarios identified upfront
+- Automated scans + manual review
+
+### Documentation Progressive
+- Updated at relevant stages
+- Cross-checked at end with `/verify`
+- Never accumulate documentation debt
+
+## Issue Tracking
+
+Use Beads for persistent tracking across sessions:
+```bash
+bd create "Feature name"           # Create issue
+bd update <id> --status in_progress  # Claim work
+bd update <id> --comment "Progress"  # Add notes
+bd close <id>                      # Complete
+bd sync                            # Sync with git
+```
+
+## Git Workflow
+
+```bash
+# Branch naming
+feat/<feature-slug>
+fix/<bug-slug>
+docs/<doc-slug>
+
+# Commit pattern
+git commit -m "test: add validation tests"     # RED
+git commit -m "feat: implement validation"     # GREEN
+git commit -m "refactor: extract helpers"      # REFACTOR
+```
+
+## Configuration
+
+Customize these commands for your stack:
+
+```bash
+# In your project's CLAUDE.md or .claude/rules/
+TYPE_CHECK_COMMAND="npm run typecheck"   # or: bun run typecheck, tsc, etc.
+LINT_COMMAND="npm run lint"               # or: bun run lint, eslint, etc.
+TEST_COMMAND="npm run test"               # or: bun run test:e2e, jest, etc.
+SECURITY_SCAN="npm audit"                 # or: bun audit, snyk test, etc.
+```
+
+## Skills Integration
+
+### parallel-ai (MANDATORY for web research)
+```bash
+# Use Skill tool for web research
+Skill("parallel-ai")
+```
+
+### sonarcloud (Code quality)
+```bash
+/sonarcloud  # Query PR-specific issues
+```
+
+## Flow Visualization
+
+```
+/status → /research → /plan → /dev → /check → /ship → /review → /merge → /verify
+   ↓          ↓          ↓        ↓        ↓         ↓          ↓          ↓         ↓
+  Check     Research   OpenSpec   TDD    Validate   PR      Address     Merge    Verify
+ context    + docs    + Beads   cycles   + scan   create   feedback    + docs    docs
+```

package/.claude/scripts/load-env.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Load environment variables from .env.local files
+# Works on Windows Git Bash and Unix systems
+
+# Function to load env file
+load_env_file() {
+  local env_file="$1"
+  if [ -f "$env_file" ]; then
+    # Export each line that matches KEY=VALUE pattern (skip comments and empty lines)
+    while IFS='=' read -r key value; do
+      # Skip comments and empty lines
+      [[ "$key" =~ ^#.*$ ]] && continue
+      [[ -z "$key" ]] && continue
+      # Remove quotes from value
+      value="${value%\"}"
+      value="${value#\"}"
+      value="${value%\'}"
+      value="${value#\'}"
+      # Export the variable
+      export "$key=$value"
+    done < "$env_file"
+  fi
+}
+
+# Load from project root .env.local
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+load_env_file "$PROJECT_ROOT/.env.local"
+load_env_file "$PROJECT_ROOT/next-app/.env.local"
+
+echo "Environment loaded. PARALLEL_API_KEY length: ${#PARALLEL_API_KEY}"

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

@@ -0,0 +1,135 @@
+# Parallel AI Tool Skill - Setup Instructions
+
+## What You Have
+
+A complete Claude Skill for using Parallel AI as a research tool with:
+- Web search
+- URL data extraction  
+- Structured data enrichment
+- Market analysis and reports
+
+## Folder Structure
+
+```
+parallel-ai-sdk/
+├── SKILL.md                    ← Main skill file
+└── references/
+    ├── api-reference.md        ← Complete API docs
+    ├── quick-reference.md      ← Cheat sheet & troubleshooting
+    └── research-workflows.md   ← 3 key use case examples
+```
+
+## How to Use
+
+### Option 1: Claude.ai Skills Directory (Recommended)
+
+1. Locate your Claude Skills folder:
+   - **Mac**: `~/.claude/skills/`
+   - **Windows**: `%APPDATA%\Claude\skills\`
+   - **Linux**: `~/.config/claude/skills/`
+
+2. Copy the entire `parallel-ai-sdk` folder there
+
+3. Restart Claude
+
+4. Ask Claude: "Research OpenAI for me" or "Search for AI news"
+
+### Option 2: Reference in Chat
+
+If you don't have a skills directory:
+
+1. Keep this folder anywhere in your project
+2. When chatting with Claude, say: "I have a Parallel AI skill in /path/to/parallel-ai-sdk"
+3. Claude will reference it automatically
+
+## Getting Started
+
+### Step 1: Get API Key
+1. Visit https://platform.parallel.ai
+2. Sign up and generate an API key
+3. Save it securely
+
+### Step 2: Set Environment Variable
+```bash
+export PARALLEL_API_KEY="your-api-key-here"
+```
+
+### Step 3: Ask Claude
+
+Try these prompts:
+- "Research OpenAI"
+- "Find the latest AI news"
+- "What's the current Bitcoin price?"
+- "Analyze the SaaS market"
+
+## File Descriptions
+
+| File | Purpose | Size |
+|------|---------|------|
+| SKILL.md | Main skill - Claude loads first | 2.4 KB |
+| api-reference.md | API endpoints & parameters | 2.3 KB |
+| quick-reference.md | Quick lookup & troubleshooting | 2.2 KB |
+| research-workflows.md | 3 example use cases | 1.6 KB |
+
+**Total: 8.5 KB** (very lightweight, won't bloat context)
+
+## Features
+
+✅ **Search API** - Web search with source filtering
+✅ **Extract API** - Scrape data from URLs
+✅ **Task API** - Structured data enrichment (company research, etc)
+✅ **Deep Research API** - Multi-source analysis & reports
+
+✅ **5 Processors** - From lite (fast, cheap) to ultra (slow, powerful)
+
+✅ **Rate Limits** - 2,000 requests/minute
+
+✅ **Error Handling** - Built-in troubleshooting guide
+
+## Quick Example
+
+When you ask Claude: "Research Anthropic"
+
+Claude will:
+1. Use the Task API with the `core` processor
+2. Submit your query to Parallel AI
+3. Poll for results (typically 1-5 minutes)
+4. Return structured data: founding year, employees, products, etc.
+
+Cost: ~$0.025
+Time: 1-5 minutes
+
+## Links
+
+- **Parallel AI Docs**: https://docs.parallel.ai
+- **Get API Key**: https://platform.parallel.ai
+- **Status**: https://status.parallel.ai
+
+## Troubleshooting
+
+**"API key not found"**
+- Make sure `PARALLEL_API_KEY` environment variable is set
+- `echo $PARALLEL_API_KEY` to verify
+
+**"Rate limited (429)"**
+- You hit 2,000 requests/minute limit
+- Wait 60 seconds before retrying
+
+**"Empty results"**
+- Try broader search terms
+- Remove domain filters (source_policy)
+
+**"Task stuck in running"**
+- Normal for complex queries (can take up to 25 minutes)
+- Keep polling, don't give up
+
+## Support
+
+For issues, check:
+1. `quick-reference.md` - Troubleshooting section
+2. `api-reference.md` - API details
+3. https://docs.parallel.ai - Official documentation
+
+---
+
+**Ready to go!** Just copy this folder and start using it with Claude. 🚀