Estatewise Engineering

EstateWise Engineering

Use this skill for most coding tasks in this repository.

Mission

Implement the smallest defensible change in the correct subsystem, preserve contracts, and validate only the touched surface.

Step 1: Classify The Work

Identify the owning subsystem before editing:

• backend/: Express API, auth, chat, forums, properties, graph, commute, Swagger, Prometheus, tRPC bridge.
• frontend/: Next.js pages, REST client wrapper, local tRPC API, charts, map, forums, auth flows.
• mcp/: stdio MCP server, tool registry, token flows, monitoring, web research, A2A bridge.
• agentic-ai/: default orchestrator, LangGraph runtime, CrewAI runtime, HTTP server, A2A endpoints.
• grpc/: market_pulse.proto, service logic, server bootstrap.
• deployment-control/: deployment API, job runner, kubectl integration, Nuxt UI.
• Infra/docs: Docker, Kubernetes, Helm, Terraform, cloud folders, Jenkins/GitLab/GitHub docs, root architecture docs.

If the task spans multiple subsystems, sequence work from contract producer to contract consumer.

Step 2: Find Real Entry Points

Use rg first. Do not broad-scan once the owning files are clear.

High-value anchors:

• Backend bootstrap: backend/src/server.ts
• Backend routes/controllers/services: backend/src/routes/, backend/src/controllers/, backend/src/services/
• Graph workflows: backend/src/graph/
• Frontend shared REST wrapper: frontend/lib/api.ts
• Frontend pages: frontend/pages/chat.tsx, frontend/pages/insights.tsx, frontend/pages/map.tsx, frontend/pages/market-pulse.tsx
• Frontend local tRPC: frontend/pages/api/trpc/[trpc].ts, frontend/server/api/routers/insights.ts
• MCP entry + registry: mcp/src/server.ts, mcp/src/tools/index.ts
• Agentic runtime entrypoints: agentic-ai/src/index.ts, agentic-ai/src/http/server.ts, agentic-ai/src/orchestrator/
• gRPC contract + service: grpc/proto/market_pulse.proto, grpc/src/services/marketPulseService.ts
• Deployment-control API/UI: deployment-control/src/server.ts, deployment-control/ui/

Step 3: Apply The Subsystem Playbook

Backend

1. Update route/controller/service in backend/src/.
2. Preserve middleware and route order in backend/src/server.ts.
3. If an endpoint or payload changes, update frontend callers, MCP wrappers, and docs in the same task.
4. Add or adjust tests under backend/tests.
5. Keep Swagger annotations aligned when endpoint behavior changes.

Frontend

1. Patch the smallest owning page or component.
2. Check both frontend/lib/api.ts and direct page-level fetches for backend URL or payload assumptions.
3. Keep large files like chat.tsx and insights.tsx localized.
4. Update Jest/Cypress/Selenium coverage only where behavior actually changed.
5. If a route or page capability changed, update frontend/README.md.

MCP

1. Update the correct tool module in mcp/src/tools/.
2. Preserve Zod input validation and stringified text outputs for client portability.
3. Register new tool modules or exports in the registry when needed.
4. Validate with npm run build and at least one client:call.
5. Update mcp/README.md when tool names, inputs, or outputs change.

Agentic AI

1. Decide which runtime owns the change: default orchestrator, LangGraph, CrewAI, or HTTP/A2A layer.
2. Keep tool call contracts aligned with the MCP server.
3. Validate with a realistic goal run after build.
4. Update agentic-ai/README.md when runtime flags, server endpoints, or workflow semantics change.

gRPC

1. Treat grpc/proto/market_pulse.proto as the contract source.
2. Keep backward compatibility unless the task explicitly requests a breaking change.
3. Update handlers and server wiring after proto changes.
4. Run proto lint and tests on proto edits.
5. Update grpc/README.md examples when RPC behavior changes.

Deployment Control

1. Keep API and UI behavior aligned.
2. Preserve job status semantics and output handling.
3. Be explicit about trust boundaries; there is no built-in auth/RBAC.
4. Validate both API and UI build paths when touched.
5. Update deployment-control/README.md for endpoint or workflow changes.

Step 4: Guard Cross-Service Contracts

When one layer changes, immediately inspect its dependents:

• Backend REST change:

  • frontend/lib/api.ts
  • page-level direct fetch(...) usage in frontend/pages/
  • MCP tools under mcp/src/tools/
  • docs in backend/README.md, frontend/README.md, and root docs if public behavior changed

• Frontend local tRPC change:

  • frontend/server/api/routers/
  • frontend/lib/trpc.tsx
  • consuming pages/components

• MCP tool change:

  • mcp/src/client.ts
  • agentic-ai MCP wrappers or runtime assumptions
  • mcp/README.md

• Agentic A2A or HTTP change:

  • agentic-ai/src/http/server.ts
  • mcp/src/tools/a2a.ts
  • agentic-ai/README.md

• gRPC contract change:

  • grpc/src/services/
  • any clients/examples/docs

Use /estatewise-contracts if the contract surface is nontrivial.

Step 5: Validate Only What Changed

Use the smallest sufficient check set:

• Root:

  • npm run format or npm run lint only when requested or when broad formatting-sensitive files changed.

• Backend:

  • cd backend && npm run build
  • cd backend && npm run test

• Frontend:

  • cd frontend && npm run build
  • cd frontend && npm run test
  • cd frontend && npm run lint

• MCP:

  • cd mcp && npm run build
  • cd mcp && npm run client:call -- <tool> '<json>'

• Agentic AI:

  • cd agentic-ai && npm run build
  • cd agentic-ai && npm run dev "realistic goal"

• gRPC:

  • cd grpc && npm run build
  • cd grpc && npm run test
  • cd grpc && npm run proto:check

• Deployment Control:

  • cd deployment-control && npm run build
  • or cd deployment-control && npm run build:api && npm run build:ui

If environment dependencies block validation, state exactly what was skipped and why.

High-Risk Areas

• backend/src/server.ts: middleware order, metrics, swagger, routing, boot behavior.
• backend/src/services/geminiChat.service.ts: core generation flow and prompt behavior.
• frontend/pages/chat.tsx: huge page with many direct API calls.
• frontend/pages/insights.tsx: large page with multiple graph/analytics flows.
• frontend/lib/api.ts: shared REST client contract.
• mcp/src/core/http.ts and mcp/src/core/token.ts: global behavior across many tools.
• agentic-ai/src/http/server.ts: HTTP + A2A contract surface.
• grpc/proto/market_pulse.proto: source of truth for gRPC changes.

Done Criteria

Do not stop at code edits. The task is complete only when:

1. The requested behavior is implemented in the correct subsystem.
2. Affected validations ran, or skips are explicitly documented.
3. Producer and consumer paths were updated for any contract change.
4. Relevant package or root docs were updated.
5. The handoff includes exact files changed and validation commands run.