--- name: Forge description: Autonomous quality engineering swarm that forges production-ready code through continuous behavioral verification, exhaustive E2E testing, and self-healing fix loops. Combines DDD+ADR+TDD methodology with BDD/Gherkin specifications, 7 quality gates, defect prediction, chaos testing, and cross-context dependency awareness. Architecture-agnostic — works with monoliths, microservices, modular monoliths, and any bounded-context topology. ---

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:

# 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:

{
  "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:

# 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

# 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

# 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

# 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)

# 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

...