Imported from zxc1a1a1/Multi_Agent-AgentHub (
.claude/skills/observability-debugging-contract/SKILL.md). Install upstream withnpx skills add zxc1a1a1/Multi_Agent-AgentHub --skill observability-debugging-contract. Copyright stays with the author.
observability-debugging-contract
Purpose
Use this for tracing, logs, error propagation, and debug playbooks across Gateway/Orchestrator/Agents.
Authoritative source order
docs/superpowers/specs/2026-05-26-module-separation-and-runtime-redesign.mddocs/superpowers/specs/2026-05-27-module-separation-runtime-redesign.md- Contracts listed in this skill
- PDR product goals only
- Sprint/UML as supplemental demo/product context only
Active architecture facts
pkg/adk pure ADK engine
pkg/runtime runtime framework over ADK
services/gateway public Gateway, auth, SSE, persistence
services/orchestrator planner/router/executor/dispatcher
services/agents/* child A2A agents
frontend React client, Gateway-only access
Legacy paths are not implementation targets for new-architecture work:
server/** legacy reference only
agents/** legacy reference only
Contracts to read first
docs/contracts/observability-debugging.md
Allowed implementation targets
pkg/*services/*
Non-negotiable rules
- Follow the redesign plan over old PDR/Sprint directory details.
- Do not add new new-architecture work under legacy
server/or rootagents/. - Do not make Frontend call Orchestrator or Child Agents directly.
- Do not put concrete LLM providers or business handlers in
pkg/adk. - Keep Gateway and Orchestrator as separate services.
- Treat Gateway→Orchestrator gRPC streaming as target. HTTP/SSE is temporary compatibility only unless contracts are revised.
- Treat MySQL as target persistence. SQLite is demo/profile-only unless contracts are revised.
Required workflow
- Identify the relevant contract files above.
- Check whether the requested change touches cross-module fields or event lifecycles.
- Update contract first when the boundary changes.
- Implement only in allowed targets.
- Add/update tests for the touched module.
- Report changed files, tests run, and any remaining mismatch against the redesign plan.
Completion checklist
- No stale old-path instructions were introduced.
- Contract and implementation agree.
- Public Gateway API remains separate from internal service API.
-
agentName,runId,threadId, andrequestId/traceIdare preserved when relevant. - Errors are sanitized and do not expose secrets or internal URLs.
- Tests or a clear blocker are reported.
