Algolia-Central-Spectrum (ACS) — Project Index

What this is: Demo/sales instance of the AC2 (Algolia-Central2) grounded conversational-agent panel, running on Adobe/Spectrum's own docs as the prospect corpus — proves the AC2 architecture ports to any corpus, live on algolia-central-spectrum.vercel.app. Repo: ~/Dropbox/AI-Development/RAG/Algolia-Central-Spectrum. Base to port from: Algolia-Central2 (sibling, [index](/p/sb-algolia-central/v2/index.md)).

Live agents (3 now, up from 2): ACS-generic-neural (95826da6-d1b6-4b81-b061-bfb52b881356, front door, all sources) + ACS-technical-neural (ae127977-c728-4b7c-bc15-6502a77873d1, React code, scoped to ReactSpectrumS2/V3/ReactAria) + new ACS-classifier-neural (dbb4faa9-e917-4be9-b8ee-6dfd9a81daef, internal-only, no search tool, decides the deep-dive offer). All on gemini-2.5-flash. Corpus: ACS_SPECTRUM_MULTI, ~502+ records, neural search on.

Architecture, current and stable (rewritten 2026-07-10): Generic answers fully (no pause, no tool call). Immediately after, the client makes ITS OWN synchronous, awaited call to the new ACS-classifier-neural agent — passing the real question, Generic's real answer, and the real retrieved hits — and that call's plain-text response (parsed for a SPECIALIST: prefix) is the deep-dive offer signal. On accept, the frontend calls Technical directly (unchanged mechanism). This REPLACES the prior design (Agent Studio's native config.suggestions, a platform-internal async job) because that mechanism could race the platform's own per-query response cache and silently drop the offer — see the incident below, this is the actual root-cause fix, not a workaround.

2026-07-09/10 overnight arc, in order: 1. Arijit halted further building on a proposed pure-orchestrator design (validated the night before with hand-faked data) and ordered a real E2E test on real data. Built + ran a 6-case suite against real -dev agents: 10/10 real offer-signal precision, 10/10 real orchestrator-chaining-correctness (a null===false JS strict-equality bug in the test script's own scoring briefly under-reported this as 5/10 — fixed, re-verified 10/10). 2. Reconciliation finding, surfaced before any Build code: the orchestrator sat entirely downstream of the SAME racy config.suggestions signal the caching-race bug lived in — building it would not have fixed anything. Architecture Review then required the caching-race fix to use a NEW dedicated classifier agent (Generic's own agentId can't absorb a one-off classification prompt — no per-request instructions override exists, and Generic still has its search tool attached). Once that classifier existed, Arijit caught that the orchestrator's routing decision became provably redundant with what the client already computes — killed for ACS, kept fully specced and shelved for Algolia-Central2's port if it ever needs real multi-agent routing. 3. Full TDD build (development-loop, 9 tasks A1-A9, FULL path — Risk + Architecture Review both run, 2 real Critical findings caught and fixed before Build: a query-provenance/injection risk in the (killed) orchestrator design, and a scopeTools gap with no way to give an agent zero search tools). Live-verified via a 7-pair repeated-query probe against real -dev agents: found and fixed a REAL classifier over-triggering bug (design questions incorrectly got the SPECIALIST offer) before ever touching production. Live flip: new classifier agent created, Generic/Technical PATCHed in place with unchanged IDs. Merged, pushed, deployed, browser-verified. 4. 3 more real bugs, all caught by Arijit actually using the live site, none caught by the test suite — fixed same session: (a) the classifier still fired and offered a deep-dive even when Generic's answer came back empty (the known ~1-in-8 platform flake) — fixed by skipping the classifier call on an empty answer; (b) a numbered-list rendering bug where the markdown-lite renderer only recognized */- bullets, never 1./2. numbered lines — first fix attempt was too subtle (4px spacing) and Arijit correctly rejected it as not actually visible; (c) the REAL root cause of (b): the renderer classified an entire text block as list-or-prose as ONE unit, so a single intro sentence sharing a block with a numbered list (no blank line between them — the normal shape of a real answer) sent the whole block, list included, to the plain-paragraph path. Fixed by grouping lines into same-kind runs instead of classifying the whole block — verified via a real DOM query (document.querySelector('ol')) on the actual live production page, not a screenshot or a claim.

Prior (2026-07-09 evening) build, now superseded by the above: 9-task dev-loop (B0-B9), shipped 111c8fd — replaced consult_technical_specialist tool-call with Agent Studio's native config.suggestions. That native-suggestions mechanism is what the 2026-07-10 classifier fix above just replaced, for the caching-race reason stated. 2 real bugs caught pre-deploy at the time: generation.max_words round-trips clean on write but 500s the completions endpoint at runtime; R11's history summarizer silently deleted Technical's content in realistic-length answers. Full detail: ADR 2026-07-09.

2026-07-09 evening incident, root-caused and closed: Google deprecated gemini-2.5-flash-lite mid-session (live 404: "This model ... is no longer available") — broke every agent at once. Diagnosed via real browser + network inspection (curl alone missed it — HTTP/2 protocol error only reproduced in-browser). Switched to gemini-2.5-flash (~4x cheaper than -pro: $0.30/$2.50 vs $1.25/$10.00 per 1M tokens). Fixing this surfaced two MORE real regressions, both fixed same session: (1) Generic had silently lost its brevity constraint — the "dead" HANDOFF section deleted during the suggestions migration was the ONLY thing telling Generic not to write full code itself, so once removed Generic and Technical converged on near-duplicate answers; restored the constraint explicitly, separate from the retired tool mechanism. (2) Both agents were recapping the PREVIOUS turn's topic before answering a new question — traced to the shared "user must never repeat themselves" instruction combined with full conversation history; added an explicit "answer only the current turn" constraint. Also found and fixed: a built-in sample-question chip's exact wording got cache-poisoned by the day's heavy repeat-testing (same bug class as a 2026-07-03 incident) — reworded. All four fixes verified live in a real browser, both before and after each push, not just via curl.

Standing infra issue, NOT resolved: Arijit's own mandate-guard.sh hook (built 2026-07-06, blocks git push/vercel --prod pending a token-file unlock) collides with Claude Code's built-in auto-mode permission classifier — the classifier vetoes the unlock-file write itself as a bypass pattern, regardless of Arijit's in-session explicit yes. Net effect: every push/deploy tonight had to be run by Arijit manually in his own terminal. Two proposed fixes, neither applied yet: (a) add an explicit Bash allow-rule in ~/.claude/settings.json for this pattern, (b) redesign the hook to use a real permission-prompt instead of a file-write signal.

Eval harness (pre-existing, untouched by today's suggestions migration): lab/eval/src/orchestratorRunner.ts, 120-question bank, @lab/judge. Judge is UNCALIBRATED (P2b never run) — every score directional only. 20-Q pilot from 07-08: mean 8.61/10. Full 100-Q run still never attempted.

Top items for next session: (1) build the empty-state sample-question nudge per the approved spec (docs/superpowers/specs/2026-07-10-empty-state-sample-question-nudge-design.md) — copy label + promoted resting-style chips, scoped small, no code written yet; (2) resolve the mandate-guard/classifier conflict — Arijit's decision this session: redesign the hook (real permission-prompt, not a settings.json allow-rule), not started; (3) scope + start the AC2 port per docs/plans/2026-07-10-reconciled-handoff-architecture-build.md (3 open decisions: agent roster collapse, browser-direct vs backend-mediated, dead-code disposition — ask Arijit before any port code); (4) run the full 100-question eval + judge calibration (P2b) — both explicitly deferred again this session, still never run; (5) the react-instantsearch <Chat> widget swap — still not started; (6) consider whether Agent Studio has a cache-bypass mechanism to prevent future sample-question poisoning recurring a third time.

Plan-doc hygiene (2026-07-12): two stale plan docs cleaned up this session — docs/plans/2026-07-09-revert-to-tool-call-and-port-to-ac2.md archived (moved to docs/plans/archive/, superseded-note added, describes a tool-call revert that was never built) and docs/plans/2026-07-10-reconciled-handoff-architecture-build.md deleted+rewritten in place (its Track A/B framing was superseded by the classifier-agent design that actually shipped — new version documents what shipped, then carries forward only the still-open AC2-port task list, now correctly scoped to reuse the classifier architecture instead of the killed orchestrator plumbing).

Porting knowledge base: everything above plus every gotcha hit across both build days has been distilled into a standalone, replicable playbook for porting this architecture to Algolia-Central2 (the "algolia-contentsearch" target): Porting Playbook. Repo-side copy at Algolia-Central2/docs/porting-playbook-from-acs.md. Read this before starting any Algolia-Central2 work that touches agents, orchestration, or the source-pills/suggestions UI — it exists specifically so none of the 17 documented gotchas get re-discovered from scratch.

Timeline (append-only, most recent last)

• 2026-07-01 — Project initialized. Fork of Algolia-Central2 for Adobe. Namespace ACS- locked. Source: Projects/Algolia-Central/spectrum/log.md.
• 2026-07-01 (session 1) — Corpus live (502 recs, ACS_SPECTRUM_MULTI, neural). 2 agents built + verified. algolia-content-fetch skill shipped. Judge harness ported (e2e, scoring bug open at the time).
• 2026-07-02/03 — Chat UI built end-to-end (Vite/React/TS, hand-built — see OPEN ARCHITECTURE GAP above): human-gated deep-dive, agent-generated follow-up, Algolia×Adobe cobrand skin. Pushed to GitHub.
• 2026-07-03 (night) — Docs shipped (README, ARCHITECTURE.md, diagrams). Vercel deploy fixed + verified live (missing vercel.json was the root cause).
• 2026-07-03 (late-night, fabbd07 v0.3.0) — Grounding judge surfaced in chat UI (Confidence chip → JudgeDrawer), wired to hosted VPS judge. Fixed a false grounding-gate cap (3.0→8.9 on a real ComboBox answer).
• 2026-07-08 (session, this handoff) — Agent-to-agent client-tool spike (repo docs/spikes/2026-07-08-agent-to-agent-tool-spike.md): first pass leaned on 2026-06-27 vault research (Projects/Algolia-Central/v2/) and stopped short of empirical proof; Arijit caught this and directed running the actual live test. Ran it: found the real live-API tool schema empirically (docs are wrong — {type:"function"} is rejected, real shape is flat {name,type:"client_side",description,inputSchema}), confirmed deterministic pause/resume across 5+2 independent cycles, zero production drift. GO verdict, now implemented and deployed.
• 2026-07-08 (same session, continued) — Replaced **HANDOFF:technical** text sentinel with the real tool call in useChat.ts/agents.ts/build_acs_agents.mjs/instructions_generic.md. Redeployed both live agents twice (IDs churn each redeploy since build_acs_agents.mjs deletes+recreates by name — current: generic a94ee722-f8c0-40e5-8610-6bc1c250f72a, technical a15c8b8c-cd5c-4222-ad80-d840b1c8cd2e). npm run build clean.
• 2026-07-08 (same session, eval loop) — Built orchestratorRunner.ts + 120-question bank to prove the orchestration end-to-end with @lab/judge. Found and fixed 3 real bugs in order: (1) harness fed the judge YAML frontmatter instead of real SpectrumDesignDocs body text — root cause, not an agent defect; (2) Generic genuinely under-searched on "X vs Y" comparison questions, answering one side from general knowledge — fixed via a new hard rule in _shared_grounding_acs.md; (3) harness used res.text() on the streaming completions endpoint, which SESSION.md had ALREADY documented as truncating responses and poisoning Agent Studio's query cache — a lesson that should have been checked before writing the harness, not after hitting the bug. 20-Q pilot before/after fixes: mean 8.02→8.61, grounding 7.03→8.18. Full 100-question run and re-confirmation of fix #3 were NOT completed this session (last re-run was killed before producing output).
• 2026-07-08 (same session, close #1) — Committed + pushed all of the above to origin/spike/agent-to-agent-tool (main untouched, no deploy risk). Local dev server verified running (localhost:5173). Arijit flagged the hand-built-UI architecture gap; logged here as the top open item.
• 2026-07-08 (same session, resumed after /handoff was invoked then paused) — Arijit tested the local server, hit a real "no response" bug on Technical's leg and re-flagged the react-instantsearch gap harder. Fixed the empty-completion flake with an auto-retry (commit a4de7d0), installed algoliasearch+react-instantsearch as migration step 1, researched <Chat>'s real API (multi-agent limitation + tools prop mechanics — see OPEN ARCHITECTURE GAP above), and redesigned the follow-up-question mechanism end to end including a frontend bug fix (commit fac01d5). Current live agent IDs: generic 95826da6-d1b6-4b81-b061-bfb52b881356, technical ae127977-c728-4b7c-bc15-6502a77873d1. Next session: (1) design + execute the <Chat> swap, (2) run the full 100-question eval, (3) confirm the auto-retry actually reduces "no response" incidents in real use.
• 2026-07-09 — Scoped a build to replace the **HANDOFF:technical** sentinel with the 07-08 tool-call mechanism, then walked it back before writing any code: the app already orchestrates both agents directly, so the tool call would have added no real capability while risking a silent break of "Generic always answers first" (a tool call preempts an agent's own answer text in the same turn — confirmed in the spike). Corrected design: use Agent Studio's native config.suggestions feature as the offer-detection signal; keep the direct Technical call unchanged. This also collapses the old separate "native suggestions for follow-ups" job into the same mechanism. Confirmed as a side question: multi-turn continuity across a deep dive needs no new platform capability (stateless /completions, pure frontend history bookkeeping) — exact context shape deferred to Build. Full detail: ADR 2026-07-09. Dev-loop run in progress: repo .development-loop/run-2026-07-08-001/.
• 2026-07-09 (evening) — Full 9-task dev-loop build (B0-B9) shipped: native config.suggestions on both agents, consult_technical_specialist tool removed from Generic (R12), multi-turn history summarization (R11, segment-aware after a code-health finding that the naive version silently deleted Technical's content), full test coverage (25 vitest + 8 node:test), code health + security review both clean. Deployed to main (111c8fd) + Vercel prod, verified live.
• 2026-07-09 (evening, live incident) — Production broke: gemini-2.5-flash-lite deprecated by Google mid-session (confirmed via the provider's own 404). Diagnosed with real browser+network inspection after curl alone gave a false "it works" signal (curl doesn't request gzip/HTTP2 the way a browser does, so it never hit the resulting HTTP/2 protocol error). Fixed: switched every agent + the suggestions config to gemini-2.5-flash (commit 225b04b), pushed live to both agents immediately. Then found, while re-testing: (a) Generic had lost its brevity constraint when the old HANDOFF section was deleted during the suggestions migration — the "dead" tool-call prose was actually the only thing enforcing "don't write the full code yourself," restored explicitly (commit 0958e32); (b) both agents recap the previous turn's topic before answering a new question, traced to the shared "never make the user repeat themselves" instruction plus full history now in context — fixed with an explicit "answer only the current turn" rule (commit 64c48fc); (c) a sample-question chip's exact wording got cache-poisoned by the day's own heavy repeat-testing, same bug class as a 2026-07-03 incident — reworded (commit d7a999c). All fixes verified live in a real Chrome session (navigate/click/network-inspect), not just curl, both before and after each push. Also surfaced: Arijit's mandate-guard.sh hook and Claude Code's built-in auto-mode classifier block each other on every git push/vercel --prod, even with explicit in-session authorization — every push tonight had to be run manually by Arijit; not yet resolved.
• 2026-07-09 (late evening) — UI polish shipped + deployed: MessageMarkdown.tsx now renders real <ul><li> bullet lists instead of literal asterisks-in-a-paragraph; SourcePills.tsx's count badge is now always clickable (was only clickable when a group had hidden release-note sources) and toggles the whole group's pills open/closed via a new independent open state. Committed 6e430f5, pushed to main, verified live in the served bundle (index-C4PEX_JM.js contains list-disc and the new toggle's this group aria-label text). Push again hit the mandate-guard.sh/auto-mode-classifier conflict; Arijit ran the token-unlock + push himself. Arijit then asked for the gate to accept a spoken "arijit-approved" word instead of the file-unlock dance — design written up (a UserPromptSubmit hook reacting to the literal word in Arijit's own chat message, writing the existing token file) but NOT applied — self-modifying the permission hook that gates the assistant's own pushes is itself something the auto-mode classifier correctly refuses to let the assistant do unattended; Arijit needs to paste the hook file in himself. Full exhaustive distillation of both build days (all 3 handoff-mechanism generations, all 17 gotchas, exact env vars, deploy checklist) written to the porting playbook for reuse on Algolia-Central2.
• 2026-07-10 (post-midnight) — Fixed the real offer-caching-race bug (a dedicated ACS-classifier-neural agent replaces the racy async config.suggestions job). Pure-orchestrator design validated via real E2E (10/10) then deliberately killed for ACS — provably redundant once the classifier existed — kept shelved for AC2. Full development-loop build (A1-A9, FULL path, Risk+Architecture Review), 2 Critical findings fixed pre-Build, 1 real classifier precision bug caught+fixed via live probe before flip. Merged, pushed, deployed. THEN 3 more real bugs caught by Arijit actually using the live site (empty-answer offer, numbered-list rendering — 2 attempts, second one verified via real DOM query on production). All fixed, deployed, verified live. Source: Projects/Algolia-Central/spectrum/log.md, .development-loop/run-2026-07-09-002/.
• 2026-07-12 — No code touched; doc/planning cleanup + a walkthrough session. Arijit asked for a plain-English explanation of the classifier architecture (agent roster, decision logic, examples of fire/no-fire) — answered by reading instructions_classifier.md directly rather than recalling from memory. Archived the stale 2026-07-09 tool-call-revert plan (docs/plans/archive/). Deleted and rewrote docs/plans/2026-07-10-reconciled-handoff-architecture-build.md in place — its Track A/B framing never shipped; replaced with an as-shipped summary of the classifier design plus a scoped AC2-port task list carrying forward the one still-real open item, with 3 decisions flagged as Arijit's to make (agent roster collapse, browser-direct vs backend-mediated, dead-code disposition). Ran the brainstorming skill on the unscoped "sample-questions UI hint" open item — root-caused the actual problem (chips exist but look inert, no explicit label, only a hover state reveals they're clickable) and wrote+committed a small approved spec: docs/superpowers/specs/2026-07-10-empty-state-sample-question-nudge-design.md (copy label + promoted resting-style chips, empty-state only, not built yet). Asked Arijit for decisions on 3 queued items: mandate-guard.sh fix (chose: redesign the hook, not a settings.json allow-rule — not started), AC2 port (chose: scope it now — 3 decisions still pending), 100-Q eval + judge calibration (chose: skip this session — still never run). Commits: fc2b9b8 (archive + spec), 24887d0 (plan rewrite).