Forge

What this skill does

# Forge — Autonomous Quality Engineering Swarm

**Quality forged in, not bolted on.**

Forge is a self-learning, autonomous quality engineering swarm that unifies three approaches into one:

| Pillar | Source | What It Does |
|--------|--------|--------------|
| **Build** | DDD+ADR+TDD methodology | Structured development with quality gates, defect prediction, confidence-tiered fixes |
| **Verify** | BDD/Gherkin behavioral specs | Continuous behavioral verification — the PRODUCT works, not just the CODE |
| **Heal** | Autonomous E2E fix loop | Test → Analyze → Fix → Commit → Learn → Repeat |

**"DONE DONE"** means: the code compiles AND the product behaves as specified. Every Gherkin scenario passes. Every quality gate clears. Every dependency graph is satisfied.

---

## ARCHITECTURE ADAPTABILITY

Forge adapts to any project architecture. Before first run, it discovers your project structure:

### Supported Architectures

| Architecture | How Forge Adapts |
|-------------|-----------------|
| **Monolith** | Single backend process, all contexts in one codebase. Forge runs all tests against one server. |
| **Modular Monolith** | Single deployment with bounded contexts as modules. Forge discovers modules and tests each context independently. |
| **Microservices** | Multiple services. Forge discovers service endpoints, tests each service, validates inter-service contracts. |
| **Monorepo** | Multiple apps/packages in one repo. Forge detects workspace structure (Turborepo, Nx, Lerna, Melos, Cargo workspace). |
| **Mobile + Backend** | Frontend app with backend API. Forge starts backend, then runs E2E tests against it. |
| **Full-Stack Monolith** | Frontend and backend in same deployment. Forge tests through the UI layer against real backend. |

### Project Discovery

On first invocation, Forge analyzes the project to build a context map:

```bash
# Forge automatically discovers:
# 1. Backend technology (Rust/Cargo, Node/npm, Python/pip, Go, Java/Maven/Gradle, .NET)
# 2. Frontend technology (Flutter, React, Next.js, Vue, Angular, SwiftUI, Kotlin/Compose)
# 3. Test framework (integration_test, Jest, Pytest, Go test, JUnit, xUnit)
# 4. Project structure (monorepo layout, service boundaries, module boundaries)
# 5. API protocol (REST, GraphQL, gRPC, WebSocket)
# 6. Build system (Make, npm scripts, Gradle tasks, Cargo features)
```

Forge stores the discovered project map:

```json
{
  "architecture": "mobile-backend",
  "backend": {
    "technology": "rust",
    "buildCommand": "cargo build --release --features test-endpoints",
    "runCommand": "cargo run --release --features test-endpoints",
    "healthEndpoint": "/health",
    "port": 8080,
    "migrationCommand": "cargo sqlx migrate run"
  },
  "frontend": {
    "technology": "flutter",
    "testCommand": "flutter drive --driver=test_driver/integration_test.dart --target={target}",
    "testDir": "integration_test/e2e/",
    "specDir": "integration_test/e2e/specs/"
  },
  "contexts": ["identity", "rides", "payments", "..."],
  "testDataSeeding": {
    "method": "api",
    "endpoint": "/api/v1/test/seed",
    "authHeader": "X-Test-Key"
  }
}
```

### Configuration Override

Projects can provide a `forge.config.yaml` at the repo root to override auto-discovery:

```yaml
# forge.config.yaml (optional — Forge auto-discovers if absent)
architecture: microservices
backend:
  services:
    - name: auth-service
      port: 8081
      healthEndpoint: /health
      buildCommand: npm run build
      runCommand: npm start
    - name: payment-service
      port: 8082
      healthEndpoint: /health
      buildCommand: npm run build
      runCommand: npm start
frontend:
  technology: react
  testCommand: npx cypress run --spec {target}
  testDir: cypress/e2e/
  specDir: cypress/e2e/specs/
contexts:
  - name: identity
    testFile: auth.cy.ts
    specFile: identity.feature
  - name: payments
    testFile: payments.cy.ts
    specFile: payments.feature
dependencies:
  identity:
    blocks: [payments, orders]
  payments:
    depends_on: [identity]
    blocks: [orders]
```

---

## CRITICAL: NO MOCKING OR STUBBING ALLOWED

**ABSOLUTE RULE: This skill NEVER uses mocking or stubbing of the backend API.**

- ALL tests run against the REAL backend API
- NO mocking frameworks for API calls (no `mockito`, `wiremock`, `MockClient`, `nock`, `msw`, `httpretty`, etc.)
- NO stubbed responses or fake data from API endpoints
- The backend MUST be running and healthy before any tests execute
- Test data is seeded through REAL API calls, not mocked state

**Why No Mocking:**
- Mocks hide real integration bugs
- Mocks create false confidence
- Mocks don't test the actual data flow
- Real API tests catch serialization, validation, and timing issues

---

## PHASE 0: BACKEND SETUP (MANDATORY FIRST STEP)

**BEFORE ANY TESTING, the backend MUST be built, compiled, and running.**

This is the FIRST thing the skill does — no exceptions.

### Step 1: Check and Start Backend

```bash
# 1. Read project config or auto-discover backend settings
# 2. Check if backend is already running
curl -s http://localhost:${BACKEND_PORT}/${HEALTH_ENDPOINT} || {
  echo "Backend not running. Starting..."

  # 3. Navigate to backend directory
  cd ${BACKEND_DIR}

  # 4. Ensure environment is configured
  cp .env.example .env 2>/dev/null || true

  # 5. Build the backend
  ${BUILD_COMMAND}

  # 6. Run database migrations (if applicable)
  ${MIGRATION_COMMAND}

  # 7. Start backend (background)
  nohup ${RUN_COMMAND} > backend.log 2>&1 &
  echo $! > backend.pid

  # 8. Wait for backend to be healthy (up to 60 seconds)
  for i in {1..60}; do
    if curl -s http://localhost:${BACKEND_PORT}/${HEALTH_ENDPOINT} | grep -q "ok\|healthy\|UP"; then
      echo "Backend healthy on port ${BACKEND_PORT}"
      break
    fi
    sleep 1
  done
}
```

### Step 2: Verify Backend Health

```bash
# Verify critical endpoints are responding
curl -s http://localhost:${BACKEND_PORT}/${HEALTH_ENDPOINT} | jq .

# Verify test fixtures endpoint (for seeding)
curl -s -H "${TEST_AUTH_HEADER}" http://localhost:${BACKEND_PORT}/${TEST_STATUS_ENDPOINT} | jq .
```

### Step 3: Contract Validation

```bash
# Verify API spec matches running API (if OpenAPI/Swagger available)
curl -s http://localhost:${BACKEND_PORT}/${OPENAPI_ENDPOINT} > /tmp/live-spec.json

# Store contract snapshot for regression detection
npx @claude-flow/cli@latest memory store \
  --key "contract-snapshot-$(date +%s)" \
  --value "$(cat /tmp/live-spec.json | head -c 5000)" \
  --namespace forge-contracts
```

### Step 4: Seed Test Data (Real API Calls)

```bash
# Seed test data through REAL API — adapt to your project's seeding endpoint
curl -X POST http://localhost:${BACKEND_PORT}/${SEED_ENDPOINT} \
  -H "Content-Type: application/json" \
  -H "${TEST_AUTH_HEADER}" \
  -d '${SEED_PAYLOAD}'
```

---

## PHASE 1: BEHAVIORAL SPECIFICATION & ARCHITECTURE RECORDS

**Before testing, verify Gherkin specs and architecture decision records exist for the target bounded context.**

Behavioral specifications define WHAT the product does from the user's perspective. Every test traces back to a Gherkin scenario. If tests pass but specs fail, the product is broken.

### Spec Location

Gherkin specs are stored alongside tests:

```
${SPEC_DIR}/
├── [context-a].feature
├── [context-b].feature
├── [context-c].feature
└── ...
```

The exact location depends on your project's test structure. Forge auto-discovers this from the project map.

### Spec-to-Test Mapping

Each Gherkin `Scenario` maps to exactly one test function. The mapping is tracked:

```gherkin
Feature: [Context Name]
  As a [user role]
  I want to [action]
  So that [outcome]

  Scenario: [Descriptive scenario name]
    Given [precondition]
    When [action]
    Then [expected result]
    And [additional verification]
```

### Missing Spec Generation

If specs are missing for a target context, the Specification Verifier agent creates them:

1. Read the screen/component/route implement