forge-workflow 1.0.0

package/.claude/commands/check.md

@@ -0,0 +1,145 @@
+---
+description: Complete validation (type/lint/tests/security)
+---
+
+Run comprehensive validation including type checking, linting, code review, security review, and tests.
+
+# Check
+
+This command validates all code before creating a pull request.
+
+## Usage
+
+```bash
+/check
+```
+
+## What This Command Does
+
+### Step 1: Type Check
+```bash
+# Run your project's type check command
+npm run typecheck    # or: bun run typecheck, tsc, etc.
+```
+- Verify all TypeScript types are valid
+- No `any` types allowed
+- Strict mode enforcement
+
+### Step 2: Lint
+```bash
+# Run your project's lint command
+npm run lint    # or: bun run lint, eslint ., etc.
+```
+- Linting rules
+- Code style consistency
+- Best practices compliance
+
+### Step 3: Code Review (if available)
+```bash
+/code-review:code-review
+```
+- Static code analysis
+- Code quality check
+- Potential issues flagged
+
+### Step 4: Security Review
+
+**OWASP Top 10 Checklist**:
+- A01: Broken Access Control
+- A02: Cryptographic Failures
+- A03: Injection
+- A04: Insecure Design
+- A05: Security Misconfiguration
+- A06: Vulnerable Components
+- A07: Authentication Failures
+- A08: Data Integrity Failures
+- A09: Logging & Monitoring Failures
+- A10: Server-Side Request Forgery
+
+**Automated Security Scan**:
+```bash
+# Run your project's security scan
+npm audit    # or: bun audit, snyk test, etc.
+```
+
+**Manual Review**:
+- Review security test scenarios (from research doc)
+- Verify security mitigations implemented
+- Check for sensitive data exposure
+
+### Step 5: Tests
+```bash
+# Run your project's test command
+npm run test    # or: bun run test, jest, vitest, etc.
+```
+- All tests passing
+- Includes security test scenarios
+- TDD tests from /dev phase
+
+### Step 6: Handle Failures
+
+If any check fails:
+```bash
+# Create Beads issue for problems
+bd create "Fix <issue-description>"
+
+# Mark current issue as blocked
+bd update <current-id> --status blocked --comment "Blocked by <new-issue-id>"
+
+# Output what needs fixing
+```
+
+If all pass:
+```
+Ready for /ship
+```
+
+## Example Output (Success)
+
+```
+✓ Type check: Passed
+✓ Lint: Passed
+✓ Code review: No issues
+✓ Security Review:
+  - OWASP Top 10: All mitigations verified
+  - Automated scan: No vulnerabilities
+  - Manual review: Security tests passing
+✓ Tests: 15/15 passing (TDD complete)
+
+Ready for /ship
+```
+
+## Example Output (Failure)
+
+```
+✗ Tests: 2/15 failing
+  - validation.test.ts: Assertion failed
+  - auth.test.ts: Timeout exceeded
+
+✓ Beads issue created: bd-k8m3 "Fix validation test"
+✓ Current issue marked: Blocked by bd-k8m3
+
+Fix issues then re-run /check
+```
+
+## 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 (you are here)
+6. /ship                 → Create PR
+7. /review               → Address comments
+8. /merge                → Merge and cleanup
+9. /verify               → Final documentation check
+```
+
+## Tips
+
+- **All checks must pass**: Don't proceed to /ship with failures
+- **Security is mandatory**: OWASP Top 10 review required for all features
+- **Create issues for failures**: Track problems in Beads
+- **TDD helps**: Tests should already pass from /dev phase
+- **Fix before shipping**: Resolve all issues before creating PR

package/.claude/commands/dev.md

@@ -0,0 +1,184 @@
+---
+description: TDD development with parallel orchestration
+---
+
+Implement features using Test-Driven Development with intelligent parallelization.
+
+# Development
+
+This command handles implementation with TDD as the default approach.
+
+## Usage
+
+```bash
+/dev
+```
+
+## What This Command Does
+
+### Step 1: Analyze Complexity & Dependencies
+
+Read OpenSpec tasks.md (if strategic) and identify:
+- All files to be created/modified
+- **Independent files**: Can run in parallel tracks
+- **Co-dependent files**: Must run sequentially
+- **Shared foundation**: Create first, then parallelize
+
+**Example Dependency Analysis**:
+```
+INDEPENDENT (Can Parallelize):
+- Track A: API endpoint (/api/payments) → No dependencies
+- Track B: UI components (PaymentForm.tsx) → No dependencies
+- Track C: Database migration (add_payments.sql) → No dependencies
+
+CO-DEPENDENT (Must Sequence):
+- Step 1: Types (types/payment.ts) → FIRST
+- Step 2: API uses types → AFTER Step 1
+- Step 3: UI uses types → AFTER Step 1
+
+Decision: Parallel tracks possible after types created
+```
+
+### Step 2: Create TodoWrite (TDD Pattern)
+
+**TESTS WRITTEN UPFRONT** - Before implementation
+
+Structure as RED-GREEN-REFACTOR cycles:
+1. Write failing test (RED)
+2. Implement minimal solution (GREEN)
+3. Refactor and clean up
+4. Repeat
+
+### Step 3: Execute Development
+
+**Option A: Sequential** (Simple, no parallelization needed)
+
+```
+TodoWrite (TDD):
+  1. ☐ Write test: payment-validation.test.ts (RED)
+  2. ☐ Implement: validation logic (GREEN)
+  3. ☐ Refactor: extract helpers
+  4. ☐ Write test: payment-errors.test.ts (RED)
+  5. ☐ Implement: error handling (GREEN)
+  6. ☐ Refactor: clean up
+  7. ☐ Write test: payment-db.test.ts (RED)
+  8. ☐ Implement: database layer (GREEN)
+  9. ☐ Refactor: optimize queries
+  10. ☐ Write test: payment-flow.e2e.ts (RED)
+  11. ☐ Implement: E2E integration (GREEN)
+  12. ☐ Refactor: final cleanup
+```
+
+**Option B: Parallel** (Complex, independent tracks)
+
+```
+Step 1: Create shared types (sequential)
+TodoWrite (Foundation):
+  1. ☐ Write test: types.test.ts
+  2. ☐ Create: types/payment.ts
+
+Step 2: Launch 3 parallel tracks
+
+Track 1 (backend-architect):
+TodoWrite (TDD):
+  1. ☐ Write test: api endpoint tests
+  2. ☐ Implement: /api/payments
+  3. ☐ Refactor
+
+Track 2 (frontend-developer):
+TodoWrite (TDD):
+  1. ☐ Write test: component tests
+  2. ☐ Implement: PaymentForm.tsx
+  3. ☐ Refactor
+
+Track 3 (database-architect):
+TodoWrite (TDD):
+  1. ☐ Write test: migration tests
+  2. ☐ Implement: add_payments.sql
+  3. ☐ Refactor
+
+Step 3: Integration (sequential)
+TodoWrite (TDD):
+  1. ☐ Write test: E2E flow
+  2. ☐ Integrate: all tracks
+  3. ☐ Refactor
+```
+
+### Step 4: Update Beads Throughout
+
+```bash
+# When starting
+bd update <id> --status in_progress
+
+# Mid-session progress
+bd update <id> --comment "API done, UI pending"
+
+# If blocked
+bd update <id> --status blocked --comment "Reason"
+```
+
+### Step 5: Commit After Each GREEN Cycle
+
+```bash
+git add .
+git commit -m "test: add payment validation tests"
+
+git add .
+git commit -m "feat: implement payment validation"
+
+git add .
+git commit -m "refactor: extract validation helpers"
+
+# Regular pushes
+git push
+```
+
+## Example Output (Sequential)
+
+```
+✓ TodoWrite: 12/12 TDD cycles completed
+✓ Tests written first: 4 test files (42 test cases)
+✓ Implementation: All tests passing
+✓ Beads updated: bd-x7y2 in_progress → ready for review
+✓ Commits: 12 commits (1 per TDD cycle)
+
+Ready for /check
+```
+
+## Example Output (Parallel)
+
+```
+✓ Dependency Analysis: 3 independent tracks + 1 shared foundation
+✓ Foundation: types/payment.ts created (tests passing)
+✓ Parallel Execution:
+  - Track 1 (API): Completed (tests passing)
+  - Track 2 (UI): Completed (tests passing)
+  - Track 3 (DB): Completed (tests passing)
+✓ Integration: E2E tests passing
+✓ Beads updated: bd-x7y2 in_progress → ready for review
+✓ Commits: 18 commits (from 3 tracks + integration)
+
+Ready for /check
+```
+
+## 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 (you are here)
+5. /check                → Validate
+6. /ship                 → Create PR
+7. /review               → Address comments
+8. /merge                → Merge and cleanup
+9. /verify               → Final documentation check
+```
+
+## Tips
+
+- **TDD is mandatory**: Always write tests first
+- **Commit after each cycle**: RED → commit test, GREEN → commit impl, REFACTOR → commit cleanup
+- **Parallel for independence**: Only parallelize truly independent tracks
+- **Update Beads regularly**: Keep status current for handoffs
+- **Tests must pass**: Don't move to /check with failing tests

package/.claude/commands/merge.md

@@ -0,0 +1,170 @@
+---
+description: Update docs, merge PR, archive, cleanup
+---
+
+Update project documentation, merge the pull request, archive proposals, and clean up.
+
+# Merge
+
+This command completes the feature by merging the PR and updating documentation.
+
+## Usage
+
+```bash
+/merge <pr-number>
+```
+
+## What This Command Does
+
+### Step 1: Final Verification
+```bash
+gh pr checks <pr-number>  # Ensure all checks pass
+gh pr view <pr-number> --json reviewDecision  # Check approval status
+```
+
+### Step 2: Update Project Documentation (BEFORE merge)
+
+**A. Update PROGRESS.md**:
+```bash
+# Add feature to completed list with:
+# - Feature name
+# - Completion date
+# - Beads issue ID
+# - PR number
+# - Research doc link
+```
+
+**B. Update API_REFERENCE.md** (if API changes):
+```bash
+# Document:
+# - New endpoints
+# - Request/response schemas
+# - Authentication requirements
+# - Example requests
+```
+
+**C. Update Architecture docs** (if strategic):
+```bash
+# Update:
+# - docs/architecture/ diagrams
+# - New patterns introduced
+# - System architecture overview
+# - Decision records (ADRs) if applicable
+```
+
+**D. Update README.md** (if user-facing):
+```bash
+# Update:
+# - Features list
+# - Configuration options
+# - Installation/setup steps
+# - Usage examples
+```
+
+**E. Update Testing docs** (if new patterns):
+```bash
+# Document:
+# - New test utilities
+# - Testing strategy
+# - Examples
+```
+
+**F. Commit documentation updates**:
+```bash
+git add docs/ README.md
+git commit -m "docs: update project documentation for <feature-name>
+
+- Updated PROGRESS.md: Marked <feature> as complete
+- Updated API_REFERENCE.md: Added <endpoints> (if applicable)
+- Updated architecture docs: <changes> (if applicable)
+- Updated README.md: <changes> (if applicable)
+
+Closes: <beads-id>
+See: docs/research/<feature-slug>.md"
+
+git push
+```
+
+### Step 3: Merge PR
+```bash
+gh pr merge <pr-number> --squash --delete-branch
+```
+
+### Step 4: Archive OpenSpec (if strategic)
+```bash
+openspec archive <feature-slug> --yes
+```
+
+### Step 5: Sync Beads
+```bash
+bd sync
+```
+
+### Step 6: Switch to Main
+```bash
+git checkout main
+git pull
+```
+
+### Step 7: Verify Cleanup
+- Documentation updated: ✓
+- Branch deleted: ✓
+- OpenSpec archived (if strategic): ✓
+- Beads synced: ✓
+
+## Example Output
+
+```
+✓ Documentation Updates:
+  - docs/planning/PROGRESS.md: Feature marked complete
+  - docs/reference/API_REFERENCE.md: 3 new endpoints documented
+  - docs/architecture/: Payment system diagram updated
+  - README.md: Billing features added
+  - Committed: docs: update project documentation
+
+✓ PR checks: All passing
+✓ PR approval: Approved by user
+✓ PR merged: squash-merge to main
+✓ Branch deleted: feat/stripe-billing
+✓ OpenSpec archived: openspec/changes/stripe-billing/ (if strategic)
+✓ Beads synced
+✓ Switched to main
+
+Merge complete!
+
+Summary:
+  - Feature: Stripe billing integration
+  - Research: docs/research/stripe-billing.md
+  - Beads: bd-x7y2 (closed)
+  - OpenSpec: Archived (if strategic)
+  - PR: #123 (merged)
+  - Commits: 18 (across 3 parallel tracks + integration)
+  - Tests: 42 test cases, all passing
+  - Documentation: Updated across 4 files
+
+Next: /verify (cross-check all documentation)
+```
+
+## 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 (you are here)
+9. /verify               → Final documentation check
+```
+
+## Tips
+
+- **Update docs BEFORE merge**: All documentation must be current
+- **Verify PR approval**: Ensure user has approved the PR
+- **Squash merge**: Keep main branch history clean
+- **Archive OpenSpec**: Strategic proposals get archived after merge
+- **Sync Beads**: Ensure Beads database is up-to-date
+- **Switch to main**: Ready for next feature
+- **Run /verify**: Final documentation verification step

package/.claude/commands/plan.md

@@ -0,0 +1,141 @@
+---
+description: Write OpenSpec + Beads + tasks
+---
+
+Create formal plan based on research, with optional OpenSpec proposal for strategic changes.
+
+# Plan
+
+This command creates a formal implementation plan after research is complete.
+
+## Usage
+
+```bash
+/plan <feature-slug>
+```
+
+## What This Command Does
+
+### Step 1: Read Research
+Load the research document:
+```bash
+cat docs/research/<feature-slug>.md
+```
+
+### Step 2: Determine Scope
+
+**Tactical** (Quick fix, < 1 day):
+- Skip OpenSpec
+- Create Beads issue only
+- Single-session work
+
+**Strategic** (Major feature, architecture change):
+- Create OpenSpec proposal first
+- Wait for approval
+- Then create Beads issue
+- Multi-session or parallel work
+
+### Step 3A: If Tactical
+
+```bash
+# Create Beads issue
+bd create "<feature-name>"
+bd show <id>
+
+# Create branch
+git checkout -b feat/<feature-slug>
+```
+
+**Output**:
+```
+✓ Scope: Tactical (no OpenSpec needed)
+✓ Beads Issue: bd-p8q1 "Fix login validation bug"
+✓ Branch: feat/fix-login-validation
+✓ Research: docs/research/fix-login-validation.md
+
+Next: /dev
+```
+
+### Step 3B: If Strategic
+
+```bash
+# Create OpenSpec proposal
+openspec proposal create <feature-slug>
+
+# Write to openspec/changes/<feature-slug>/:
+# - proposal.md (problem, solution, alternatives, impact)
+# - tasks.md (implementation checklist, TDD-ordered)
+# - design.md (technical decisions from research)
+# - specs/<capability>/spec.md (delta changes)
+
+# Validate
+openspec validate <feature-slug> --strict
+
+# Create Beads issue
+bd create "<feature-name> (see openspec/changes/<feature-slug>)"
+bd show <id>
+
+# Create branch
+git checkout -b feat/<feature-slug>
+
+# Commit proposal
+git add openspec/ docs/research/
+git commit -m "proposal: <feature-name>
+
+Research documented in docs/research/<feature-slug>.md
+OpenSpec proposal in openspec/changes/<feature-slug>/"
+
+git push -u origin feat/<feature-slug>
+
+# Create proposal PR
+gh pr create --title "Proposal: <feature-name>" \
+  --body "See openspec/changes/<feature-slug>/proposal.md"
+```
+
+**Output**:
+```
+✓ Scope: Strategic (architecture change)
+✓ OpenSpec Proposal: openspec/changes/stripe-billing/
+  - proposal.md: ✓ (references research doc)
+  - tasks.md: ✓ (8 steps, TDD-ordered)
+  - design.md: ✓ (8 key decisions documented)
+  - specs/payments/spec.md: ✓ (delta changes)
+  - Validation: PASSED
+
+✓ Beads Issue: bd-x7y2 "Stripe billing (see openspec/changes/stripe-billing)"
+✓ Branch: feat/stripe-billing
+✓ Committed: Proposal + research doc
+✓ PR created: https://github.com/.../pull/456
+
+⏸️  WAITING FOR PROPOSAL APPROVAL
+
+After approval, run: /dev
+```
+
+### Step 4: Link Beads to OpenSpec (if strategic)
+
+```bash
+bd update <id> --comment "OpenSpec: openspec/changes/<feature-slug>"
+```
+
+## Integration with Workflow
+
+```
+1. /status               → Understand current context
+2. /research <name>      → Research and document
+3. /plan <feature-slug>  → Create plan and tracking (you are here)
+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
+```
+
+## Tips
+
+- **Strategic vs Tactical**: When in doubt, start tactical. Refactor to strategic if needed.
+- **OpenSpec for architecture**: Use proposals for anything that changes system design
+- **Use research decisions**: Reference research doc in OpenSpec proposal
+- **TDD-ordered tasks**: Order tasks.md by test dependencies
+- **Link everything**: Connect Beads → OpenSpec → Research doc