Lujanita - Spec-Driven Development

Development instructions for the Lujanita chatbot following GitHub's Spec-Driven Development (SDD) toolkit. This project implements a conversational automation platform for Lujan de Cuyo Express with React frontend, Java Spring Boot BFF, and Odoo backend integration via Model Context Protocol (MCP).

Architecture Overview

**Widget**: React + Vite conversational interface (`apps/widget/`)

**BFF (Backend for Frontend)**: Java 21 + Spring Boot orchestrating LLM (Ollama) and MCP (Odoo) interactions (`apps/middleware/`)

**Backend**: Odoo with official MCP server (`platform/odoo/`)

**Contracts**: Shared MCP definitions (`packages/contracts/`)

**Infrastructure**: Google Cloud Run + Cloud Build

**Important**: MCP stands for "Model Context Protocol" (not "Model Content Protocol"). Always use correct terminology.

Spec-Driven Development Workflow

Phase 0: Specification (BLOCKING)

**STOP** - Before writing any code, verify specification exists in `/specs/NNN-feature/`:

```

/specs/NNN-feature-name/

├── spec.md # User stories, FR-XXX requirements, acceptance criteria

├── plan.md # Architecture decisions

├── research.md # Technology evaluation

├── data-model.md # Entity schemas and MCP/Odoo relationships

└── tasks.md # Task breakdown with test-first approach

```

**If specification doesn't exist** → Create it first using `.github/prompts/speckit.*.prompt.md`

Phase 0.5: Generate Gherkin Feature Files (MANDATORY)

**AFTER creating `spec.md` and BEFORE implementing code**:

1. Use `.github/prompts/speckit.gherkin.prompt.md` to generate feature files

2. Each User Story must produce a Gherkin feature file in the appropriate layer:

- React Widget → `apps/widget/features/`

- BFF (Java) → `apps/middleware/features/`

- Orchestration services → `apps/services/features/`

3. Each feature file MUST include:

- Jira tags (`@JIRA:LUJ-XXX`)

- Priority tags (`@P1`, `@P2`, `@P3`)

- Requirement tags (`@FR-XXX`)

- Executable Given-When-Then scenarios

4. Create Jira issue "BDD: <Feature Short Name>" with:

- Path to `spec.md`

- List of created feature files + paths

- Scenario and tag counts

- Initial command (must fail): e.g., `cd apps/widget && npm run test:bdd -- features/chatbot.feature`

5. Comment on original business issue: "Gherkin feature generated at: <paths>; see BDD issue: LUJ-XYZ"

Example Gherkin:

```gherkin

@JIRA:LUJ-2

@P1

Feature: Odoo order reception

As Lujanita assistant I need to query confirmed orders in Odoo via MCP

@smoke @FR-001

Scenario: Get confirmed order

Given a confirmed order exists in Odoo

When Lujanita queries the order by ID

Then respond with status, date and contact details

```

Phase 1: AI Context Gathering

Read in this order:

1. `/specs/NNN-feature/spec.md` - Business requirements

2. Gherkin feature files - Acceptance criteria

3. This file - General project patterns

4. `.github/copilot-knowledge/` - Specific technical patterns

5. `/docs/` - Reference documentation (Odoo, MCP, internal flows)

Phase 2: Test-First Implementation with BDD (NON-NEGOTIABLE)

**A. Implement Step Definitions (BDD Tests - MUST FAIL)**

```bash

Widget (React + Cucumber)

cd apps/widget && npm run test:bdd # MUST FAIL - steps undefined

Implement steps in apps/widget/steps/*_steps.ts with Testing Library

BFF (Java + Cucumber + JUnit)

cd apps/middleware && mvn test -Dcucumber.filter.tags="@bdd" # MUST FAIL - steps undefined

Implement steps in apps/middleware/src/test/java/.../*Steps.java using RestAssured/Ollama/MCP client

```

**B. Implement Minimal Code**

```bash

Widget

cd apps/widget && npm run test:unit # Vitest + Testing Library

BFF

cd apps/middleware && mvn test # JUnit + WireMock for Odoo/MCP + Ollama

```

**C. Verify Tests Pass**

```bash

cd apps/widget && npm run test:bdd && npm run test

cd apps/middleware && mvn test -Dcucumber.filter.tags="@bdd" && mvn test

```

**D. Refactor and Commit**

```bash

git add .

git commit -m "feat(LUJ-XXX): Implement [feature] with BDD tests"

```

Phase 3: Documentation Updates

Update `.github/copilot-knowledge/` if new patterns emerge

Update `/docs/` with any new conventions

Record lessons learned in `spec.md`

Knowledge Base (Read Before Coding)

**Location**: `.github/copilot-knowledge/`

| Article | When to Read |

|---------|-------------|

| **widget-patterns.md** | React components, i18n, chat hooks |

| **middleware-patterns.md** | BFF↔MCP↔Ollama integration, Spring Boot, HTTP clients |

| **testing-guide.md** | BDD/Unit testing strategy |

| **contracts-mcp.md** | MCP contracts between BFF and Odoo |

**Usage**: Reference specific articles in prompts, e.g., "Implement step following middleware-patterns.md"

Monorepo Structure

```

apps/

widget/ # React Widget + Vite (port 4173)

middleware/ # Java Spring Boot BFF + Cucumber (port 9000)

services/ # Additional orchestrations

packages/

contracts/ # MCP definitions, shared DTOs

ui/ # Shared components (if applicable)

platform/

odoo/ # MCP server configuration in Odoo

```

Path Conventions

```

Is it shared between widget and BFF?

├─ YES → packages/

│ ├─ MCP Contracts → packages/contracts/

│ └─ UI Components → packages/ui/

└─ NO → apps/

├─ Conversation UI → apps/widget/

├─ BFF/REST API → apps/middleware/

```

Code Standards

React Widget (TypeScript)

`strict` + `strictNullChecks` enabled

Functional components with hooks

Mandatory i18n (`apps/widget/src/i18n`)

Tests with Vitest + Testing Library

Mock data in `apps/widget/mocks/`

BFF Java (Spring Boot)

Java 21, Maven

BFF orchestration ↔ Ollama (ollama4j) ↔ MCP Odoo

Tests with JUnit 5 + Mockito + WireMock

Structured metrics and logs (Micrometer + JSON)

Lombok Usage in Java

All Java model classes, DTOs and configurations in `apps/middleware/` must use Lombok annotations (`@Data`, `@Getter`, `@Setter`, `@Builder`, etc.) to avoid boilerplate

Do not manually write accessor methods except for special cases (validation logic, custom serialization)

Import Lombok in `pom.xml` and ensure IDE support is enabled

Example:

```java

import lombok.Data;

@Data

public class MyDTO {

private String name;

private int age;

}

```

Testing (Test-First MANDATORY)

Testing Pyramid

```

┌──────────┐

│ E2E │ Critical conversation scenarios

├──────────┤

│ Integr. │ MCP contracts and Odoo/LLM calls

├──────────┤

│ Unit │ Hooks, Java services, reducers

└──────────┘

```

Commands

```bash

cd apps/widget && npm run test # Unit tests

cd apps/widget && npm run test:bdd # BDD tests

cd apps/middleware && mvn test # Unit/Integration tests

cd apps/middleware && mvn testBdd # BDD tests

```

Rules

1. Write tests before implementation

2. Every BDD step must be used in CI

3. MCP contracts must have mocks in `packages/contracts/mocks/`

Observability

Structured logs with `correlationId`, `llmOperation`, `mcpOperation`

Errors must include codes (`OD00X`, `LLM00X`, `MW00X`, `UI00X`)

Key metrics: MCP/LLM latency, Odoo response rate, user satisfaction

Internationalization (i18n)

Keys in English camelCase

`translations.ts` for widget

Never hardcode visible text

Feature Flags

Use `FEATURE_<NAME>` pattern

Disabled by default

Document rollout strategy in `plan.md`

Common Tasks

New Feature

1. Create `/specs/NNN-feature/` (spec, plan, data-model, tasks)

2. Generate Gherkin feature files (widget/BFF)

3. Write failing tests

4. Implement minimum code to pass

5. Update documentation

New MCP Contract

1. Define DTO in `packages/contracts/src`

2. Document in `data-model.md`

3. Add compatibility tests (Java + TypeScript)

4. Publish mocks in `packages/contracts/mocks/`

Protocol for AI Assistants

1. Verify specification exists (`/specs/`)

2. Read relevant knowledge base articles

3. Generate failing BDD/Unit tests

4. Implement following established patterns

5. Suggest validation commands (`npm run test`, `mvn test`, etc.)

Quick Reference

| Task | Command |

|------|---------|

| Setup widget | `cd apps/widget && npm install` |

| Setup BFF | `cd apps/middleware && mvn clean install` |

| Run widget tests | `npm run test` |

| Run BFF tests | `mvn test` |

| Run widget BDD | `npm run test:bdd` |

| Run BFF BDD | `mvn testBdd` |

Constraints

**Spec-first**: No code without specification in `/specs/`

**Test-first**: No implementation without failing tests

**BDD mandatory**: All user stories must have Gherkin scenarios

**MCP terminology**: Always use "Model Context Protocol" correctly

**Lombok required**: All Java DTOs must use Lombok annotations

Lujanita - Spec-Driven Development

Lujanita - Spec-Driven Development

Architecture Overview

Spec-Driven Development Workflow

Phase 0: Specification (BLOCKING)

Phase 0.5: Generate Gherkin Feature Files (MANDATORY)

Phase 1: AI Context Gathering

Phase 2: Test-First Implementation with BDD (NON-NEGOTIABLE)

Widget (React + Cucumber)

Implement steps in apps/widget/steps/*_steps.ts with Testing Library

BFF (Java + Cucumber + JUnit)

Implement steps in apps/middleware/src/test/java/.../*Steps.java using RestAssured/Ollama/MCP client

Widget

BFF

Phase 3: Documentation Updates

Knowledge Base (Read Before Coding)

Monorepo Structure

Path Conventions

Code Standards

React Widget (TypeScript)

BFF Java (Spring Boot)

Lombok Usage in Java

Testing (Test-First MANDATORY)

Testing Pyramid

Commands

Rules

Observability

Internationalization (i18n)

Feature Flags

Common Tasks

New Feature

New MCP Contract

Protocol for AI Assistants

Quick Reference

Constraints

Reviews (0)