# Investibook Agent-Inside Multi-Agent Diagnosis Plan **Date:** 2026-05-18 **Status:** Implementation plan **Input:** OpenCode runtime multi-agent diagnosis design --- ## 1. Summary Use the core orchestration idea from OMO without turning the Investibook backend into an orchestrator. The backend only initializes OpenCode configuration, copies agent instructions, copies a read-only Skill Catalog, and injects workspace context. The actual multi-agent diagnosis workflow runs inside the OpenCode agent through the Task tool. The final design keeps exactly three agents: - `diagnosis-orchestrator` - `evidence-agent` - `diagnosis-analyst` The complexity lives in the Skill Catalog, the delegation protocol, and fixed file outputs. It does not add backend state machines or more agent roles. --- ## 2. OpenCode Task Capability First verify that the current Investibook OpenCode runtime has OMO-style Task capability. - If available: register the three diagnosis agents directly in `.opencode/opencode.json`. - If unavailable: integrate an OMO-style plugin/task tool first, then enable the agents/task configuration. - If the Task tool cannot be integrated: fall back to a single-agent prompt protocol and do not claim that multi-agent diagnosis has been completed. Acceptance criteria: the main agent can invoke `evidence-agent` and `diagnosis-analyst` with a non-empty required skill list. If the OpenCode Task tool supports an explicit `load_skills` argument, use it. Otherwise encode the list in the task prompt under `Required skills to load`. --- ## 3. Agent Roles ### 3.1 `diagnosis-orchestrator` Responsibilities: - User-facing conversation entry point. - Decide whether the user request should enter diagnosis mode. - Read workspace context, sources, Jira/alert/cluster metadata, and existing evidence. - Read `.opencode/investibook/SKILL_CATALOG.md`. - Decide when to call `evidence-agent` and `diagnosis-analyst`. - Read child-agent outputs from files. Non-responsibilities: - Do not directly collect evidence. - Do not directly write the final root cause. - Do not parse JSON from child-agent chat text. ### 3.2 `evidence-agent` Responsibilities: - Own data-source analysis and evidence collection. - Consolidate metrics, logs, slow queries, TopSQL, events, and diagnostic files without splitting into more collectors. - Normalize time range, cluster tier, Premium `parent_id`, and Starter/Essential `keyspace_id`. - Reuse existing workspace evidence. - Load data-access skills. Required output: ```text evidences/agent-runs/evidence-agent.json ``` ### 3.3 `diagnosis-analyst` Responsibilities: - Combine the domain expert, reviewer, and synthesizer roles. - Read the evidence-agent output and evidence files. - Load diagnosis skills based on the symptoms. - Perform root-cause analysis, candidate rejection, evidence-chain review, and final report writing. - Enforce the hard rule that TiDB high CPU diagnosis must check Go GC metrics. Restrictions: - By default, do not call Clinic, O11Y, Jira, or DevOps to collect data directly. - If evidence is insufficient, output `needs_more_evidence=true` and let the orchestrator call `evidence-agent` again. Required outputs: ```text evidences/agent-runs/diagnosis-analyst.json evidences/workspace_evidence_report.json ``` --- ## 4. Skill Catalog Add a read-only index file that is not placed on a skill discovery path. Source file: ```text agentkit/config/SKILL_CATALOG.md ``` Workspace copy target: ```text .opencode/investibook/SKILL_CATALOG.md ``` Never copy it into: ```text .opencode/skills/ .opencode/.all-skills/ ``` Catalog groups: - `core` - `time-conversion` - `tidb-knowledge-base` - `data-access` - `clinic-cli` - `jira` - `devops` - `o11y-data` - `o11y-metrics-api` - `github-issue-search` - `diagnosis` - `tidb-clinic-diagnosis` - `tidb-query-tuning` - `tikv-fast-tune` - `tikv-performance` - `tikv-memory` - `pd-oncall-handbook` - `pd-scheduling` - `pd-resource-control` - `transaction-oncall-handbook` - `ticdc-health-inspection` - `autoscaler-dashboard` Loading rules: - `diagnosis-orchestrator`: read the catalog and workspace files by default. - `evidence-agent`: load only `core + data-access` by default. - `diagnosis-analyst`: load only `core + diagnosis` by default. - Diagnosis Task calls must not use an empty required skill list. - The analyst must not load data-access skills unless a future protocol explicitly allows it. --- ## 5. Static Protocol Update `build_static_protocol()` with an `Investibook Diagnosis Orchestration Protocol`. Fixed workflow: 1. The orchestrator determines user intent and diagnosis scope. 2. The orchestrator calls `evidence-agent`. 3. `evidence-agent` collects or reuses evidence and writes `evidence-agent.json`. 4. The orchestrator reads `evidence-agent.json`. 5. The orchestrator calls `diagnosis-analyst`. 6. The analyst analyzes and reviews the evidence, then writes `diagnosis-analyst.json` and `workspace_evidence_report.json`. 7. The orchestrator reads the analyst file and replies to the user. 8. If the analyst returns `needs_more_evidence=true`, the orchestrator may run at most one additional evidence collection pass and then one additional analyst pass. 9. If evidence is still insufficient, return "insufficient evidence + concrete gaps + recommended next steps" and do not force a conclusion. --- ## 6. Output Files And Schemas Add the following agent-side file convention: ```text evidences/ workspace_evidence_report.json metrics.json logs.json queries.json events.json agent-runs/ evidence-agent.json diagnosis-analyst.json ``` Schema documents copied into the workspace: ```text .opencode/investibook/schemas/evidence-agent-output.schema.json .opencode/investibook/schemas/diagnosis-analyst-output.schema.json ``` `evidence-agent.json` must include: ```json { "agent": "evidence-agent", "status": "ok|partial|failed", "summary": "", "scope": { "cluster_id": "", "time_range": {}, "tier": "", "parent_id": "", "keyspace_id": "" }, "evidence_files": [], "missing_evidence": [], "warnings": [], "next_recommended_skills": [] } ``` `diagnosis-analyst.json` must include: ```json { "agent": "diagnosis-analyst", "status": "ok|partial|failed", "root_cause": "", "confidence": "low|medium|high", "key_evidence": [], "rejected_causes": [], "needs_more_evidence": false, "missing_evidence": [], "quality_checks": [], "final_response": "" } ``` The orchestrator must read these JSON files from disk. If a file does not exist or is invalid, treat the child task as failed and retry once at most. --- ## 7. Backend Scope Keep backend changes minimal: - Update `agentkit/config/opencode.json.template`. - Add and copy catalog, agent prompts, and schemas under `.opencode/investibook/`. - Update workspace initialization so the new files are created for every workspace. - Update the static protocol. - Preserve the existing `.opencode/.all-skills` and `.opencode/skills` enablement flow. - Preserve existing artifact detection behavior. Do not add: - Diagnostic run tables. - Diagnostic task tables. - A backend runner. - Backend-managed child agent sessions. - New diagnosis status APIs. --- ## 8. Test Plan Backend tests: - After workspace initialization, verify these files exist: - `.opencode/opencode.json` - `.opencode/investibook/SKILL_CATALOG.md` - `.opencode/investibook/schemas/evidence-agent-output.schema.json` - `.opencode/investibook/schemas/diagnosis-analyst-output.schema.json` - Verify the catalog is not under `.opencode/skills` or `.opencode/.all-skills`. - Verify the existing skill enable/disable flow is unaffected. - Verify the first static protocol injection includes: - three-agent orchestration rules - Task delegation requirements - file output requirements - the one extra evidence round limit - the TiDB high CPU Go GC metrics rule Catalog/static tests: - Every skill referenced by the catalog exists under `agentkit/skills`. - `data-access` skills are not in the analyst default load group. - `diagnosis` skills are not in the evidence-agent default load group. - Schema JSON is valid. Manual E2E: - Create an O11Y issue workspace. - Trigger diagnosis. - Verify the main agent calls `evidence-agent`. - Verify `evidence-agent` writes `evidences/agent-runs/evidence-agent.json`. - Verify the main agent calls `diagnosis-analyst`. - Verify the analyst writes `evidences/agent-runs/diagnosis-analyst.json`. - Verify the analyst updates `evidences/workspace_evidence_report.json`. - Verify the frontend report artifact refreshes normally. - If the analyst returns `needs_more_evidence=true`, verify the orchestrator performs at most one supplemental evidence pass. --- ## 9. Assumptions - v1 only supports multi-agent orchestration inside the OpenCode agent. - Claude ACP keeps the existing single-agent behavior. - `SKILL_CATALOG.md` is a read-only index and is not registered as a skill. - Existing skill directory layout and enable/disable mechanisms are unchanged. - If the Task tool cannot be integrated, implement the catalog plus single-agent prompt-protocol fallback first.