Estatewise Engineering

EstateWise Engineering

Use this skill as the default playbook for coding work in this repository.

Objective

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

Operating Rules

1. Keep patches surgical.
2. Do not refactor unrelated files.
3. Preserve backward compatibility unless the task explicitly requests a breaking change.
4. Avoid changing environment defaults unless explicitly requested.
5. Never commit secrets or .env values.

Classify Scope First

Identify the owning subsystem before editing:

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

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

Find Real Entry Points

Use rg first. Open only the relevant files once the owning path is clear.

Start from:

• backend/src/server.ts
• backend/src/routes/, backend/src/controllers/, backend/src/services/
• frontend/lib/api.ts
• frontend/pages/chat.tsx, frontend/pages/insights.tsx, frontend/pages/map.tsx, frontend/pages/market-pulse.tsx
• frontend/server/api/routers/insights.ts
• mcp/src/server.ts, mcp/src/tools/, mcp/src/core/
• agentic-ai/src/index.ts, agentic-ai/src/http/server.ts, agentic-ai/src/orchestrator/
• grpc/proto/market_pulse.proto, grpc/src/services/
• deployment-control/src/server.ts, deployment-control/ui/

Subsystem Playbooks

Backend

1. Update route/controller/service in backend/src/.
2. Preserve middleware and route ordering 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.

Frontend

1. Patch the smallest owning page or component.
2. Check both frontend/lib/api.ts and direct page-level fetch(...) usage before assuming one edit is enough.
3. Keep large files like chat.tsx and insights.tsx localized.
4. Update only the tests needed for the changed behavior.

MCP

1. Update the correct tool module in mcp/src/tools/.
2. Keep Zod validation strict.
3. Preserve text-first, stringified JSON output patterns expected by clients.
4. Validate with npm run build and at least one focused client:call.

Agentic AI

1. Decide whether the change belongs to the 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 when behavior changes.

gRPC

1. Treat grpc/proto/market_pulse.proto as the contract source.
2. Update handlers and service wiring after proto edits.
3. Run proto lint and tests on proto changes.

Deployment Control

1. Keep API and UI behavior aligned.
2. Preserve queued/running/succeeded/failed job semantics.
3. Remember there is no built-in auth/RBAC; do not silently widen trust assumptions.

Cross-Service Contract Checks

Inspect dependent consumers whenever a producer changes:

• Backend REST changes:

  • frontend/lib/api.ts
  • direct frontend fetch(...) callers in frontend/pages/
  • MCP tools in mcp/src/tools/

• Frontend local tRPC changes:

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

• MCP tool changes:

  • mcp/src/client.ts
  • agentic-ai/src/lang/tools.ts
  • docs in mcp/README.md

• Agentic A2A/HTTP changes:

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

• gRPC contract changes:

  • grpc/src/services/
  • proto docs/examples/tests

Use estatewise-contracts if the contract surface is non-trivial.

Validation Matrix

Run the smallest sufficient check set:

• Root: npm run dev, npm run format, npm run lint
• Backend: cd backend && npm run build && npm run test
• Frontend: cd frontend && npm run build && npm run test, plus npm run lint when UI or TS lint-sensitive paths changed
• MCP: cd mcp && npm run build && npm run client:call -- <tool> '<json>'
• Agentic AI: cd agentic-ai && npm run build && npm run dev "realistic goal"
• gRPC: cd grpc && npm run build && npm run test && npm run proto:check
• Deployment Control: cd deployment-control && npm run build or npm run build:api && npm run build:ui

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

High-Risk Files

• backend/src/server.ts
• backend/src/services/geminiChat.service.ts
• frontend/pages/chat.tsx
• frontend/pages/insights.tsx
• frontend/lib/api.ts
• mcp/src/core/http.ts
• mcp/src/core/token.ts
• agentic-ai/src/http/server.ts
• grpc/proto/market_pulse.proto

Prefer minimal diffs and avoid style-only churn in these files.

Documentation Requirements

Update affected docs when behavior or commands change:

• backend/README.md
• frontend/README.md
• mcp/README.md
• agentic-ai/README.md
• grpc/README.md
• deployment-control/README.md
• root docs like README.md, ARCHITECTURE.md, DEPLOYMENTS.md, DEVOPS.md, GRPC_TRPC.md, RAG_SYSTEM.md

Done Criteria

Finish only when all are true:

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