forge-workflow 1.0.0

package/bin/forge.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const COMMANDS = [
+  'status.md', 'research.md', 'plan.md', 'dev.md', 'check.md',
+  'ship.md', 'review.md', 'merge.md', 'verify.md'
+];
+
+const SKILLS_PARALLEL_AI = [
+  'SKILL.md', 'README.md', 'api-reference.md', 'quick-reference.md', 'research-workflows.md'
+];
+
+const SKILLS_SONARCLOUD = ['SKILL.md', 'reference.md'];
+
+console.log('');
+console.log('  ___                   ');
+console.log(' |  _|___  _ _  ___  ___ ');
+console.log(' |  _| . || \'_|| . || -_|');
+console.log(' |_| |___||_|  |_  ||___|');
+console.log('                 |___|   ');
+console.log('');
+console.log('Installing Forge - 9-Stage TDD-First Workflow...');
+console.log('');
+
+// Get the project root (where npm install was run)
+const projectRoot = process.env.INIT_CWD || process.cwd();
+
+// Get the package directory (where forge is installed)
+const packageDir = path.dirname(__dirname);
+
+// Directories to create
+const dirs = [
+  '.claude/commands',
+  '.claude/rules',
+  '.claude/skills/parallel-ai',
+  '.claude/skills/sonarcloud',
+  '.claude/scripts',
+  'docs/research'
+];
+
+// Create directories
+console.log('Creating directories...');
+dirs.forEach(dir => {
+  const fullPath = path.join(projectRoot, dir);
+  if (!fs.existsSync(fullPath)) {
+    fs.mkdirSync(fullPath, { recursive: true });
+  }
+});
+
+// Copy function
+function copyFile(src, dest) {
+  try {
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, dest);
+      return true;
+    }
+  } catch (err) {
+    // Silently continue if file doesn't exist
+  }
+  return false;
+}
+
+// Copy commands
+console.log('Copying workflow commands...');
+COMMANDS.forEach(cmd => {
+  const src = path.join(packageDir, '.claude/commands', cmd);
+  const dest = path.join(projectRoot, '.claude/commands', cmd);
+  if (copyFile(src, dest)) {
+    console.log(`  ✓ ${cmd}`);
+  }
+});
+
+// Copy rules
+console.log('Copying workflow rules...');
+const rulesSrc = path.join(packageDir, '.claude/rules/workflow.md');
+const rulesDest = path.join(projectRoot, '.claude/rules/workflow.md');
+if (copyFile(rulesSrc, rulesDest)) {
+  console.log('  ✓ workflow.md');
+}
+
+// Copy skills
+console.log('Copying skills...');
+SKILLS_PARALLEL_AI.forEach(file => {
+  const src = path.join(packageDir, '.claude/skills/parallel-ai', file);
+  const dest = path.join(projectRoot, '.claude/skills/parallel-ai', file);
+  copyFile(src, dest);
+});
+console.log('  ✓ parallel-ai');
+
+SKILLS_SONARCLOUD.forEach(file => {
+  const src = path.join(packageDir, '.claude/skills/sonarcloud', file);
+  const dest = path.join(projectRoot, '.claude/skills/sonarcloud', file);
+  copyFile(src, dest);
+});
+console.log('  ✓ sonarcloud');
+
+// Copy scripts
+console.log('Copying scripts...');
+const scriptSrc = path.join(packageDir, '.claude/scripts/load-env.sh');
+const scriptDest = path.join(projectRoot, '.claude/scripts/load-env.sh');
+if (copyFile(scriptSrc, scriptDest)) {
+  console.log('  ✓ load-env.sh');
+}
+
+// Copy documentation
+console.log('Copying documentation...');
+const workflowSrc = path.join(packageDir, 'docs/WORKFLOW.md');
+const workflowDest = path.join(projectRoot, 'docs/WORKFLOW.md');
+if (copyFile(workflowSrc, workflowDest)) {
+  console.log('  ✓ WORKFLOW.md');
+}
+
+const templateSrc = path.join(packageDir, 'docs/research/TEMPLATE.md');
+const templateDest = path.join(projectRoot, 'docs/research/TEMPLATE.md');
+if (copyFile(templateSrc, templateDest)) {
+  console.log('  ✓ research/TEMPLATE.md');
+}
+
+console.log('');
+console.log('✅ Forge installed successfully!');
+console.log('');
+console.log('┌─────────────────────────────────────────────────────────┐');
+console.log('│                    GET STARTED                          │');
+console.log('├─────────────────────────────────────────────────────────┤');
+console.log('│  /status    - Check current context                     │');
+console.log('│  /research  - Start researching a feature               │');
+console.log('│  /plan      - Create implementation plan                │');
+console.log('│  /dev       - Start TDD development                     │');
+console.log('│  /check     - Run validation                            │');
+console.log('│  /ship      - Create pull request                       │');
+console.log('│  /review    - Address PR feedback                       │');
+console.log('│  /merge     - Merge and cleanup                         │');
+console.log('│  /verify    - Final documentation check                 │');
+console.log('├─────────────────────────────────────────────────────────┤');
+console.log('│  Full guide: docs/WORKFLOW.md                           │');
+console.log('│  Research template: docs/research/TEMPLATE.md           │');
+console.log('└─────────────────────────────────────────────────────────┘');
+console.log('');

package/docs/WORKFLOW.md

@@ -0,0 +1,251 @@
+# Forge Development Workflow
+
+Complete 9-stage TDD-first workflow for feature development. Works with any tech stack.
+
+## Overview
+
+This workflow integrates:
+- **Test-Driven Development (TDD)**: Tests written UPFRONT
+- **Research-First**: Evidence-based decisions with parallel-ai
+- **Issue Tracking**: Beads for persistent tracking across agents
+- **Strategic Planning**: OpenSpec for architectural changes
+- **Security**: OWASP Top 10 analysis for every feature
+- **Documentation**: Progressive updates, final verification
+
+## Workflow Stages
+
+```
+┌─────────┐
+│ /status │ → Check current stage & context
+└────┬────┘
+     │
+┌────▼──────┐
+│ /research │ → Deep research (parallel-ai), save to docs/research/
+└────┬──────┘
+     │
+┌────▼────┐
+│  /plan  │ → OpenSpec (if strategic) + Beads + branch
+└────┬────┘
+     │
+┌────▼───┐
+│  /dev  │ → TDD implementation (RED-GREEN-REFACTOR)
+└────┬───┘
+     │
+┌────▼────┐
+│ /check  │ → Validation (type/lint/tests/security)
+└────┬────┘
+     │
+┌────▼────┐
+│  /ship  │ → Create PR with full documentation
+└────┬────┘
+     │
+┌────▼─────┐
+│ /review  │ → Address ALL PR issues (GitHub Actions, Greptile, SonarCloud)
+└────┬─────┘
+     │
+┌────▼─────┐
+│  /merge  │ → Update docs, merge PR, archive, cleanup
+└────┬─────┘
+     │
+┌────▼──────┐
+│  /verify  │ → Cross-check all documentation, update if needed
+└───────────┘
+     │
+     ✓ Complete
+```
+
+## Quick Reference
+
+| Stage | Command | Key Actions |
+|-------|---------|-------------|
+| 1. Status | `/status` | Check PROGRESS.md, Beads, OpenSpec |
+| 2. Research | `/research <name>` | parallel-ai + codebase, save to docs/research/ |
+| 3. Plan | `/plan <slug>` | OpenSpec (if strategic) + Beads + branch |
+| 4. Dev | `/dev` | TDD cycles (RED-GREEN-REFACTOR) |
+| 5. Check | `/check` | Type/lint/security/tests |
+| 6. Ship | `/ship` | Create PR with full docs |
+| 7. Review | `/review <pr>` | Fix ALL PR issues |
+| 8. Merge | `/merge <pr>` | Update docs, merge, archive |
+| 9. Verify | `/verify` | Cross-check docs, update if needed |
+
+For detailed information on each stage, see the individual command files in `.claude/commands/`.
+
+## TDD Principles
+
+### What is TDD?
+
+**Test-Driven Development**: Write tests BEFORE writing implementation code.
+
+**Benefits**:
+- Catches bugs early
+- Ensures code is testable
+- Documents expected behavior
+- Improves code design
+- Provides confidence in refactoring
+
+### TDD Cycle
+
+```
+┌─────────────┐
+│ RED (Test)  │ → Write failing test
+└──────┬──────┘
+       │
+┌──────▼───────┐
+│ GREEN (Code) │ → Write minimal code to pass
+└──────┬───────┘
+       │
+┌──────▼────────┐
+│ REFACTOR      │ → Clean up and optimize
+└───────────────┘
+       │
+       └─→ Repeat for next feature
+```
+
+### Example TDD Flow
+
+**Feature**: Add email validation
+
+**RED** (Write test first):
+```typescript
+// test/validation.test.ts
+test('should validate email format', () => {
+  expect(validateEmail('test@example.com')).toBe(true)
+  expect(validateEmail('invalid')).toBe(false)
+})
+```
+**Run test**: ❌ Fails (function doesn't exist)
+
+**GREEN** (Make it pass):
+```typescript
+// src/validation.ts
+export function validateEmail(email: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
+}
+```
+**Run test**: ✅ Passes
+
+**REFACTOR** (Optimize):
+```typescript
+// Extract regex to constant
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+export function validateEmail(email: string): boolean {
+  return EMAIL_REGEX.test(email)
+}
+```
+**Run test**: ✅ Still passes
+
+---
+
+## Research-First Approach
+
+### Why Research First?
+
+**Evidence-based decisions**:
+- Understand existing patterns before reinventing
+- Learn from others' mistakes (known issues)
+- Apply industry best practices
+- Make informed security decisions
+- Document reasoning for future reference
+
+### parallel-ai Integration
+
+**MANDATORY for all features**: Use parallel-ai skill for web research
+
+**Research Queries**:
+```
+"[your-framework] [feature] best practices 2026"
+"[feature] implementation patterns"
+"OWASP Top 10 risks for [feature] 2026"
+"[Feature] security vulnerabilities common attacks"
+"Secure [feature] implementation checklist"
+```
+
+**Document Everything**:
+- Source URLs
+- Key insights
+- Applicability to project
+- Decision impact
+- Evidence for choices
+
+---
+
+## Security-First Development
+
+### OWASP Top 10 Analysis
+
+**MANDATORY for every feature**: Analyze against OWASP Top 10 2021
+
+**The List**:
+1. A01: Broken Access Control
+2. A02: Cryptographic Failures
+3. A03: Injection
+4. A04: Insecure Design
+5. A05: Security Misconfiguration
+6. A06: Vulnerable Components
+7. A07: Identification and Authentication Failures
+8. A08: Software and Data Integrity Failures
+9. A09: Security Logging and Monitoring Failures
+10. A10: Server-Side Request Forgery (SSRF)
+
+**For Each Risk**:
+- Risk level: High/Medium/Low
+- Applicability: Yes/No
+- Mitigation strategy
+- Test scenarios
+- Evidence from research
+
+**Security Tests** (TDD):
+```typescript
+// test/security/access-control.test.ts
+test('should prevent unauthorized access to other team data', async () => {
+  const user = await createTestUser({ teamId: 'team-1' })
+  const response = await api.get('/data?team_id=team-2')
+    .set('Authorization', `Bearer ${user.token}`)
+
+  expect(response.status).toBe(403)
+  expect(response.body.data).toBeUndefined()
+})
+```
+
+---
+
+## Cross-Agent Collaboration
+
+### Beads for Persistence
+
+**Why Beads**:
+- Git-backed (survives agent switches)
+- Cross-agent visibility
+- Status tracking
+- Dependency management
+
+**Workflow**:
+```bash
+# Agent 1 (Claude Code)
+bd create "Add notifications"
+bd update bd-x7y2 --status in_progress --comment "API done, UI pending"
+bd sync && git push
+
+# Agent 2 (Cursor)
+git pull && bd sync
+bd show bd-x7y2  # See status: "API done, UI pending"
+# Continue UI work
+bd update bd-x7y2 --status done
+bd sync && git push
+```
+
+---
+
+## Tips & Best Practices
+
+1. **Always TDD**: Write tests BEFORE implementation
+2. **Research everything**: Use parallel-ai for every feature
+3. **Security first**: OWASP Top 10 analysis mandatory
+4. **Document decisions**: Evidence and reasoning in research docs
+5. **Update Beads regularly**: Keep status current for handoffs
+6. **Commit frequently**: After each TDD cycle
+7. **Address ALL PR feedback**: GitHub Actions, Greptile, SonarCloud
+8. **Update docs progressively**: Don't wait until the end
+9. **Verify at the end**: Final documentation check catches gaps
+10. **Sync often**: `bd sync` at end of every session

package/docs/research/TEMPLATE.md

@@ -0,0 +1,292 @@
+# Research: [Feature Name]
+
+**Date**: YYYY-MM-DD
+**Researcher**: Claude AI
+
+## Objective
+[What we're trying to achieve - clear problem statement and goals]
+
+## Codebase Analysis
+
+### Existing Patterns
+- **File**: `path/to/file.ts`
+- **Pattern**: [Description of existing implementation]
+- **Reusability**: [Yes/No + reasoning]
+- **Lessons learned**: [What worked, what didn't]
+
+### Affected Modules
+- **Module**: [name]
+- **Changes needed**: [Description]
+- **Impact**: [Low/Medium/High]
+- **Dependencies**: [List any dependencies]
+
+### Test Infrastructure
+- **Existing tests**: `path/to/tests/`
+- **Test utilities**: [Available testing tools/helpers]
+- **Coverage**: [Current state - percentage, gaps]
+- **Test patterns**: [What patterns are used - unit, integration, E2E]
+
+## Web Research
+
+### Best Practices (parallel-ai)
+1. **Source**: [URL]
+   - **Key insight**: [Summary of best practice]
+   - **Applicability**: [How it applies to our project]
+   - **Decision impact**: [What decision this influences]
+   - **Implementation notes**: [How to apply]
+
+2. **Source**: [URL]
+   - [...]
+
+### Known Issues (parallel-ai)
+1. **Issue**: [Description]
+   - **Source**: [GitHub/SO/Blog URL]
+   - **Mitigation**: [How to avoid]
+   - **Decision impact**: [Changes to approach]
+   - **Frequency**: [How common is this issue]
+
+2. **Issue**: [...]
+
+### Library Documentation (Context7)
+1. **Library**: [name and version]
+   - **API**: [Relevant methods/patterns]
+   - **Compatibility**: [Version requirements, breaking changes]
+   - **Decision impact**: [Implementation details]
+   - **Example usage**: [Code snippet]
+
+2. **Library**: [...]
+
+### Case Studies
+1. **Source**: [URL]
+   - **Company/Project**: [Who implemented this]
+   - **Scale**: [Production scale, users, data volume]
+   - **Lessons**: [What they learned]
+   - **Applicability**: [How it relates to our use case]
+
+2. **Source**: [...]
+
+## Key Decisions & Reasoning
+
+### Decision 1: [Decision Title]
+- **Decision**: [What we decided]
+- **Reasoning**: [Why we chose this approach]
+- **Evidence**: [Research that supports this - links to sources]
+- **Alternatives considered**:
+  1. [Alternative 1]: [Why rejected]
+  2. [Alternative 2]: [Why rejected]
+- **Trade-offs**: [What we're giving up, what we're gaining]
+- **Risk**: [Low/Medium/High] - [Risk description]
+
+### Decision 2: [Decision Title]
+- [...]
+
+## TDD Test Scenarios (Identified Upfront)
+
+### Unit Tests
+1. **Test**: [Scenario description]
+   - **File**: `test/path/test.ts`
+   - **Function under test**: `functionName()`
+   - **Assertions**: [What to verify]
+   - **Test data**: [Required test data/mocks]
+   - **Edge cases**: [List edge cases to cover]
+
+2. **Test**: [...]
+
+### Integration Tests
+1. **Test**: [Scenario description]
+   - **File**: `test/integration/test.ts`
+   - **Components**: [What components are being tested together]
+   - **Assertions**: [What to verify]
+   - **Test data**: [Database fixtures, API mocks]
+
+2. **Test**: [...]
+
+### E2E Tests
+1. **Test**: [User flow scenario]
+   - **File**: `test/e2e/test.ts`
+   - **User flow**: [Step-by-step user actions]
+   - **Assertions**: [What user should see/experience]
+   - **Test data**: [Complete test environment setup]
+
+2. **Test**: [...]
+
+## Security Analysis (OWASP Top 10 + Feature-Specific)
+
+### OWASP Top 10 Applicability
+
+#### A01: Broken Access Control
+- **Risk**: [High/Medium/Low]
+- **Applicable**: [Yes/No]
+- **Mitigation**: [How addressed - RLS policies, permission checks]
+- **Tests**: [Security test scenarios]
+- **Evidence**: [Links to security research]
+
+#### A02: Cryptographic Failures
+- **Risk**: [High/Medium/Low]
+- **Applicable**: [Yes/No]
+- **Mitigation**: [Encryption at rest/transit, key management]
+- **Tests**: [Encryption tests]
+- **Compliance**: [Data protection requirements]
+
+#### A03: Injection
+- **Risk**: [High/Medium/Low]
+- **Applicable**: [Yes/No]
+- **Mitigation**: [Parameterized queries, input validation, sanitization]
+- **Tests**: [SQL injection tests, XSS tests, command injection tests]
+- **Libraries**: [What libraries help prevent injection]
+
+#### A04: Insecure Design
+- **Risk**: [High/Medium/Low]
+- **Threat model**: [Key threats identified]
+- **Secure design patterns**: [Patterns used - zero trust, defense in depth]
+- **Architecture review**: [Security considerations in design]
+- **Tests**: [Security design validation]
+
+#### A05: Security Misconfiguration
+- **Risk**: [High/Medium/Low]
+- **Configuration reviewed**: [Yes/No]
+- **Security headers**: [CSP, HSTS, X-Frame-Options, etc.]
+- **Error handling**: [No sensitive info in errors]
+- **Default accounts**: [No default/test credentials]
+- **Tests**: [Configuration security tests]
+
+#### A06: Vulnerable Components
+- **Risk**: [High/Medium/Low]
+- **Dependencies scanned**: [Yes/No - tool used]
+- **Known CVEs**: [Count and severity from scan]
+- **Update plan**: [If vulnerabilities found]
+- **Monitoring**: [Dependabot, Snyk, etc.]
+- **Tests**: [Dependency security checks]
+
+#### A07: Identification and Authentication Failures
+- **Risk**: [High/Medium/Low]
+- **Auth mechanism**: [OAuth2/JWT/Session/etc.]
+- **Session management**: [Secure/reviewed - timeout, rotation]
+- **Password policy**: [Requirements if applicable]
+- **MFA**: [Required/Optional/Not applicable]
+- **Brute force protection**: [Rate limiting, account lockout]
+- **Tests**: [Authentication tests, session tests]
+
+#### A08: Software and Data Integrity Failures
+- **Risk**: [High/Medium/Low]
+- **Integrity checks**: [Where implemented - signatures, checksums]
+- **Code signing**: [Yes/No]
+- **CI/CD security**: [Pipeline reviewed, secrets management]
+- **Supply chain**: [Trusted sources, verification]
+- **Tests**: [Integrity validation tests]
+
+#### A09: Security Logging and Monitoring Failures
+- **Risk**: [High/Medium/Low]
+- **Security events logged**: [List what's tracked]
+- **Audit trail**: [What's tracked for compliance]
+- **No sensitive data**: [Verified - no passwords/tokens in logs]
+- **Alerting**: [Security alerts configured]
+- **Log retention**: [Duration and compliance]
+- **Tests**: [Logging tests, no sensitive data tests]
+
+#### A10: Server-Side Request Forgery (SSRF)
+- **Risk**: [High/Medium/Low]
+- **External requests**: [Where made in code]
+- **URL validation**: [Whitelist/validation rules]
+- **Network restrictions**: [Firewall rules, VPC]
+- **Input sanitization**: [User-controlled URLs]
+- **Tests**: [SSRF prevention tests]
+
+### Feature-Specific Security Risks
+
+1. **Risk**: [Specific risk for this feature]
+   - **Likelihood**: High/Medium/Low
+   - **Impact**: High/Medium/Low
+   - **Attack vector**: [How this could be exploited]
+   - **Mitigation**: [Specific solution]
+   - **Evidence**: [Research source showing this risk]
+   - **Tests**: [Security test scenarios]
+   - **Monitoring**: [How to detect attacks]
+
+2. **Risk**: [Next risk]
+   - [...]
+
+### Security Test Scenarios (TDD)
+
+1. **Test**: Unauthorized access attempt should fail
+   - **File**: `test/security/access-control.test.ts`
+   - **Scenario**: User tries to access another team's data
+   - **Expected**: 403 Forbidden, no data leak
+
+2. **Test**: SQL injection attempt should be blocked
+   - **File**: `test/security/injection.test.ts`
+   - **Scenario**: Malicious input in query parameter
+   - **Expected**: Input sanitized, no SQL execution, error logged
+
+3. **Test**: XSS attempt should be sanitized
+   - **File**: `test/security/xss.test.ts`
+   - **Scenario**: Script tag in user input
+   - **Expected**: HTML escaped, no script execution
+
+4. **Test**: [Additional security tests]
+   - [...]
+
+## Scope Assessment
+
+- **Type**: Tactical / Strategic
+  - **Rationale**: [Why this classification]
+  - **OpenSpec needed**: Yes / No
+
+- **Complexity**: Low / Medium / High
+  - **Rationale**: [Number of files, systems involved, dependencies]
+  - **Estimated effort**: [Without time, describe scope]
+
+- **Parallel opportunity**: Yes / No
+  - **Rationale**: [Independent tracks available?]
+  - **Tracks**: [If yes, list potential parallel tracks]
+
+- **Estimated files**: [Count]
+  - **New files**: [List]
+  - **Modified files**: [List]
+
+- **Dependencies**:
+  - **Internal**: [Other features/modules]
+  - **External**: [Third-party libraries]
+  - **Blockers**: [Any blocking dependencies]
+
+- **Security risk level**: Low / Medium / High / Critical
+  - **Rationale**: [Based on OWASP analysis]
+  - **Mitigation priority**: [When to address]
+
+## Next Steps
+
+1. **If Strategic**: Create OpenSpec proposal
+   - `openspec proposal create <feature-slug>`
+   - Write proposal.md, tasks.md, design.md
+   - Reference this research doc for evidence
+
+2. **Create Beads issue**:
+   - `bd create "<feature-name>"`
+   - Link to this research doc
+   - Link to OpenSpec if strategic
+
+3. **Create branch**:
+   - `git checkout -b feat/<feature-slug>`
+
+4. **Proceed to /plan**:
+   - Read this research doc
+   - Create formal implementation plan
+   - Wait for OpenSpec approval if strategic
+
+## Research Checklist
+
+- [ ] Codebase exploration complete
+- [ ] parallel-ai web research complete (multiple sources)
+- [ ] Context7 library documentation reviewed
+- [ ] Case studies analyzed
+- [ ] All key decisions documented with evidence
+- [ ] TDD test scenarios identified upfront
+- [ ] OWASP Top 10 analysis complete
+- [ ] Feature-specific security risks identified
+- [ ] Security test scenarios defined
+- [ ] Scope assessment complete
+- [ ] Next steps clear
+
+---
+
+**Note**: This research document serves as the single source of truth for all architectural and implementation decisions. Reference it throughout the development lifecycle (in OpenSpec proposals, PR descriptions, code reviews, and documentation).