Skip to content

Integration Standards

This is the most important standard in GE. It directly implements Principles 1, 2, 3, and 6.

The Anti-Scaffolding Rule

RULE: Never create a function, endpoint, component, or service without simultaneously creating its integration point.

WRONG ORDER (scaffolding): 1. Create handler function 2. Create route 3. Create test 4. Wire handler to route 5. Wire route to app

RIGHT ORDER (integration-first): 1. Create route in app (returns 501 Not Implemented) 2. Verify route is reachable (curl returns 501) 3. Create handler, wire to route 4. Verify handler responds (curl returns real response) 5. Create test that exercises the real route 6. Verify test passes through the actual HTTP path

Proof of Life Requirements

RULE: Every feature completion must demonstrate the feature working through its actual production path.

For the GE platform specifically, the actual system path is: 

TaskService -> Redis XADD to triggers.{agent} -> executor consumer group picks up
-> executor fetches agent config from admin-ui API -> loads identity (IDENTITY-CORE + IDENTITY-ROLE + IDENTITY-REFERENCE)
-> builds prompt (constitution + identity + task) -> provider adapter builds CLI command
-> PTY captures output -> completion file written to ge-ops/system/completions/
-> host cron syncs COMP files to DB via /api/system/sync-completions
NOTE: XADD to ge:work:completed is PLANNED but not yet implemented. The ge-orchestrator
listens on that stream but nothing publishes to it yet.

For API endpoints: - PROOF: curl command that hits the real endpoint and returns real data - NOT PROOF: unit test that calls the handler function directly

For agent features: - PROOF: Redis trigger -> executor picks up -> CLI executes -> completion file written - NOT PROOF: calling the agent function directly from a test script

For UI features: - PROOF: Admin UI at office.growing-europe.com displays data created through the real pipeline - NOT PROOF: Admin UI displays data inserted directly into PostgreSQL

For discussion system: - PROOF: Agent triggered via Redis -> agent's CLI session POSTs to /api/discussions/{id}/messages -> message appears in discussion - NOT PROOF: Direct POST to discussion API without agent involvement

What Simulation Looks Like (Anti-Patterns)

These are DECEPTIVE patterns. They produce correct-looking output through the wrong path:

  • Inserting rows directly into PostgreSQL to make the Admin UI display a "working" feature
  • An agent reporting "I'm on OpenAI GPT-4o" because config says so, without the Codex CLI being installed or functional
  • A discussion system that "works" because the test script called the API endpoints directly instead of triggering real agents through Redis
  • A billing dashboard that shows costs because test data was POSTed to /api/internal/consumption/llm, not because actual agent sessions were tracked
  • A provider switching feature that "works" because the dropdown saves to the database, but the executor never actually invokes the selected CLI

IF YOU CATCH YOURSELF DOING ANY OF THESE: Stop. State explicitly what is simulated and what is real. Build the real path.

The "Wait a Minute" Rule

RULE: If you find yourself saying "wait a minute, the stream name is X but I'm calling Y" -- this indicates a contract violation (Principle 4). Do not fix it locally. Check the authoritative config file (config/dolly-routing.yaml for streams, config/ports.yaml for ports) and update the non-conforming code.

If no authoritative config entry exists for this interface, CREATE ONE before proceeding.

ENFORCEMENT: Code review. Proof of Life section in completion files. Integration tests.