Orchestrata Ultimate › Plans › kimi-delegation-plan

Kimi delegation plan — SPEC-018 Fireflies backend completion slice

Source: plans/kimi-delegation-plan.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-07-12 · 155 lines.

Prose pending.

Plan text

Kimi delegation plan — SPEC-018 Fireflies backend completion slice

Delegation brief for the IRC fleet agent kimi (Moonshot, localhost:6667 #agents). Kimi reads THIS FILE from its worktree — it is self-contained: everything needed to produce compliant work is in here. Kimi WRITES FILES ONLY; review, gates, tests, and commits happen from the main checkout (worktrees have no .venv). Author of record for all commits is Mohamed.

0. Logistics (fixed — do not improvise)

• Worktree: ~/workspace/orchestrata-kimi-wt on branch kimi/fireflies-slice (created from the main checkout with git worktree add). Work ONLY there.
• Loop: read this plan → ask questions on IRC (claude: <question>) → write the files → announce claude: WP<N> ready per package. Claude runs all gates from the main checkout and replies PASS or FAIL with the exact gate output; fix and re-announce until PASS.
• IRC framing: lines cap at ~450 chars (longer truncates silently). To discuss code inline use the file markers --- <path> --- ... --- end of <path> ---; but prefer writing files in the worktree and announcing paths.
• Never run: pip (blocked repo-wide; deps go in pyproject.toml via uv add, and NO new deps are expected for this slice), git commit, git push, pytest with -n/--dist (pytest-xdist deadlocks this suite and is banned in .claude/banned-libraries.txt).

1. Context — what this slice is

Repo: orchestrata-ultimate (single package, Python 3.14 free-threaded). SPEC-018 (Fireflies meeting intelligence) has a working backend core: a real GraphQL client (src/orchestrata_ultimate/integrations/fireflies_client.py), a KG sync engine (src/orchestrata_ultimate/integrations/fireflies_sync.py), and 4 gateway RPCs (src/orchestrata_ultimate/gateway/handlers/fireflies.py: fireflies.transcripts/.transcript/.search/.summary, registered in src/orchestrata_ultimate/gateway/rpc.py ~line 387). The 2026-07-12 audit (plans/spec-implementation-gaps.md §3, SPEC-018) found the missing pieces this slice closes: no test_connection, no fireflies.health RPC, no fireflies.sync RPC, and sync_recent() has zero production callers.

Spec oracle: specs/018-fireflies-integration/spec.md + its checklists/requirements.md. When this plan and the spec disagree, the spec wins — say so on IRC instead of silently following either.

2. Work packages (do in order; announce each separately)

WP1 — FirefliesClient.test_connection() + fireflies.health RPC

1. integrations/fireflies_client.py: add async def test_connection(self) -> dict[str, Any] — cheapest possible GraphQL probe (the user { user_id email } query, same _request plumbing as the other methods). Returns {"ok": True, "user": {...}} on success; on ANY failure returns {"ok": False, "error": "<message>"} — never raises (mirror how the sibling methods degrade; read get_transcript's error shape first).
2. gateway/handlers/fireflies.py: add async def handle_health(self, connection_id, params) calling test_connection(), response shape consistent with the 4 existing handlers.
3. gateway/rpc.py: register "fireflies.health": fireflies.handle_health in the method registry next to the existing fireflies rows.

WP2 — fireflies.sync RPC (first production caller of sync_recent)

1. gateway/handlers/fireflies.py: async def handle_sync(self, connection_id, params) — constructs/uses FirefliesSync (integrations/fireflies_sync.py:65 sync_recent(limit)), limit from params (default 20, validate int 1..100, reject otherwise with an error response, not an exception). Returns sync_recent's result dict.
2. Register "fireflies.sync" in rpc.py.
3. Read sync_recent first: whatever infra it needs (Neo4j) must be handled the way the handler's siblings handle unavailable infra — degrade with an error payload, never crash the RPC dispatcher.

WP3 — fireflies_test_connection MCP tool

session/fireflies_tools.py (FirefliesMCPTools): add a fireflies_test_connection tool method delegating to WP1's test_connection(), following the file's existing tool-method pattern exactly (naming, schema, return shape, docstring style).

Every WP also ships tests — see §4.

3. Code standards (gate-enforced; violations = FAIL)

• Python 3.14, absolute imports only (orchestrata_ultimate.*); no relative imports anywhere.
• Env access: os.environ.get("X", default) ONLY — never bare os.environ["X"]; accept an env= mapping parameter where the file's siblings do (that is the test seam).
• No mocking, no stubs, no placeholders — real implementations. If a thing can't be real, STOP and ask on IRC.
• Composition over inheritance; match the surrounding file's naming, docstring style, and comment density. Google-style docstrings with Args/ Returns like the neighbors.
• Traceability: stamp new public functions/methods with @traces(spec="018", reqs=[...]) using REAL requirement ids from specs/018-fireflies-integration/checklists/requirements.md — pick the rows your code actually implements; never invent ids. (Import: from orchestrata_ultimate.core.base.traces import traces — see how fireflies_client.py already does it.)
• No weasel words anywhere (docstrings, comments, errors): banned vocabulary like "problematic/issue/suboptimal" — say "failed/bug/wrong", give numbers.
• Formatting: black + ruff clean (Claude runs them; write it clean).
• Typing: full annotations on new signatures; zero NEW pyright errors.
• No new dependencies. stdlib + what pyproject.toml already declares.

4. Test standards (the hard rules of this repo)

• Location: tests/integrations/test_fireflies_client.py (extend), tests/gateway/handlers/test_fireflies.py (extend), tests/session/test_fireflies_tools.py (extend). READ each file first and copy its fixture/style conventions exactly.
• NO mock, NO monkeypatch (including setenv/delenv), NO skip, NO xdist. Enforced mechanically by scripts/audit_test_purity.py and scripts/test-review.py (T-rules) — a single violation fails the gate.
• Function-scope fixtures only. Any shared resource name is scoped with a per-test test_id (uuid) so tests are parallel-safe.
• Env goes through the code's env= injection seam as a plain dict — that is why §3 requires the seam.
• Behavioral asserts: assert on real returned values/shapes, not just is not None. Error paths get their own tests (bad limit, missing transcript id, API failure shape {"ok": False, ...}).
• Network reality: the Fireflies API key lives on this machine; the existing integration tests show the pattern for real-API tests vs credential-less degradation tests — follow that split. A test must pass BOTH when the API responds and (for the degradation tests) when credentials are absent from the injected env dict.
• Kimi does NOT run the suite (no .venv in worktrees). Claude runs, from the main checkout, per package: targeted pytest (live-observed), then scripts/code-review.py --min-severity ERROR, scripts/test-review.py, scripts/architecture_checker.py, ruff, black --check, pyright (zero new errors), scripts/serialize_codebase_ast.py standards and check-deps, and the Rule-8 orphan ratchet (orphans --check — your new modules must be import-reachable from production, which the rpc.py registration in WP1/WP2 guarantees).

5. Documentation requirements

• Module docstrings updated where behavior grew (client, handler, tools).
• Each new RPC documented in the handler class docstring's method list (match existing wording style).
• If the spec checklist rows you implement are currently unchecked, list their REQ ids in your IRC "ready" announcement — Claude updates the RTM; do not edit docs/rtm.* yourself (generated).

6. Definition of done (per package)

1. Files written in the worktree, on-brief, spec-consistent.
2. Tests written per §4 covering happy + error paths (aim ≥90% coverage of the lines you add).
3. claude: WP<N> ready — files: <paths> — reqs: <REQ ids> announced.
4. Claude's gate run comes back PASS. FAIL responses include exact output; fix in the worktree and re-announce.
5. Claude commits from the main checkout (Mohamed authorship, no AI attribution — never add Co-Authored-By of any kind).

7. Questions protocol

Ask early, ask specific (claude: WP2 — should sync limit >100 clamp or error? — the answer here is: error, per §2). Unanswered design forks = STOP on that package and move to the next; never guess policy.

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks