Adding OpenSpec example

Author: jabrena

examples/requirements-examples/problem1/README.md

@@ -0,0 +1,38 @@
+# Problem 1
+
+## User Story Statement
+
+- **As an** API consumer / data analyst
+- **I want to** consume God APIs (Greek, Roman & Nordic), filter gods whose names start with 'n', convert each filtered god name into a decimal representation, and return the sum of those values
+- **So that** I can perform cross-pantheon analysis and aggregate mythology data for research, reporting, or educational applications.
+
+**Notes:**
+
+- Decimal conversion: Each character in a god name is converted to its numeric code (e.g., ASCII/Unicode), and those values are summed per name. The final result is the sum of all such per-name sums.
+- Case sensitivity: Filtering for gods starting with `n` is case-sensitive (only lowercase `n`), consistent with the Gherkin below.
+
+## Gherkin file
+
+```gherkin
+Feature: God Analysis API
+# REST API: GET /api/v1/gods/stats/sum
+# Notes:
+# - Decimal Conversion Rule: Name then each char to its Unicode int value, then concatenate these ints as strings.
+# (e.g., "Zeus" -> Z(90)e(101)u(117)s(115) -> "90101117115").
+# - Outbound HTTP uses Spring RestClient with connect/read timeouts from application configuration (defaults in application.yml).
+# - If a source request hits the configured timeout, aggregation continues with the other sources (partial result).
+# - Filtering for gods starting with 'n' is case-sensitive (only lowercase 'n').
+# - Greek API: https://my-json-server.typicode.com/jabrena/latency-problems/greek
+# - Roman API: https://my-json-server.typicode.com/jabrena/latency-problems/roman
+# - Nordic API: https://my-json-server.typicode.com/jabrena/latency-problems/nordic
+
+Background:
+    Given the God Analysis API is available at "/api/v1"
+    And the system is configured with HTTP connect and read timeouts for outbound RestClient calls (default 5 seconds in application configuration)
+
+Scenario: Happy path - Get sum with explicit sources
+    When the client sends a GET request to "/gods/stats/sum" with query parameters "filter" = "n" and "sources" = "greek,roman,nordic"
+    Then the response status code should be 200
+    And the response body should contain a JSON object with a "sum" field
+    And the value of "sum" should be "78179288397447443426"
+```

examples/requirements-examples/problem1/implementation/.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1,3 @@
+wrapperVersion=3.3.4
+distributionType=only-script
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.14/apache-maven-3.9.14-bin.zip

examples/requirements-examples/problem1/implementation/AGENTS.md

@@ -0,0 +1,70 @@
+# Contributor Quickstart Guide
+
+## Your role
+
+You are an expert Java backend engineer specializing in APIs, services, and databases.
+
+- You understand Spring Boot, REST API design, and backend service architecture
+- You help build and maintain Java backend applications with focus on API development
+- You work with databases, external service integrations, and backend business logic
+- You apply best practices for testing, error handling, and performance optimization
+
+## Tech stack
+
+- **Language:** Java 26
+- **Build:** Maven (wrapper: `./mvnw`)
+- **Framework:** Spring Boot 4.0.4
+- **Key Dependencies:** Spring Web, Spring Actuator; outbound HTTP via Spring `RestClient` with connect/read timeouts from configuration (no Resilience4j retries for US-001)
+- **Testing:** JUnit 5, Spring `RestClient` (acceptance tests), WireMock, Spring Boot Test
+- **Monitoring:** Spring Boot Actuator
+
+## File structure
+
+- `src/main/java/info/jab/ms/` – Main application source code using `info.jab.ms` package (WRITE here for business logic)
+- `src/main/resources/` – Configuration files and resources (WRITE here for config)
+- `src/test/java/info/jab/ms/` – Test source code using `info.jab.ms` package (WRITE here for tests)
+- `target/` – Generated build output (READ only, never edit directly)
+- `pom.xml` – Maven project configuration (WRITE here for dependencies)
+- `.mvn/` – Maven wrapper configuration (READ only)
+
+### Package Structure
+- **Base package:** `info.jab.ms`
+
+## Commands
+
+```bash
+# Build and test the application
+./mvnw clean verify
+
+# Run the application locally
+./mvnw spring-boot:run
+
+# Run only unit tests
+./mvnw test
+
+# Run only integration tests
+./mvnw failsafe:integration-test
+
+# Package the application
+./mvnw clean package
+
+# Clean build artifacts
+./mvnw clean
+```
+
+## Git workflow
+
+- **Conventional Commits**: Use conventional commit format for all commit messages
+- Format: `type(scope): description`
+- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+- Examples:
+  - `feat(api): add god stats aggregation endpoint`
+  - `fix(controller): resolve timeout handling in external API calls`
+  - `test(integration): add acceptance tests for filtering logic`
+  - `docs(readme): update API documentation`
+
+## Boundaries
+
+- ✅ **Always do:** Run `./mvnw clean verify` before committing changes, write tests for new functionality, follow REST API best practices, handle errors gracefully, use proper HTTP status codes
+- ⚠️ **Ask first:** Adding new dependencies to pom.xml, changing application configuration, modifying API contracts, adding new external service integrations
+- 🚫 **Never do:** Edit target/ directory directly, commit secrets or credentials, skip tests before promoting changes, break existing API contracts without versioning