Compute module playbook decision guide constraints and references

[anand-testcompare]

Why This Exists

Even with better tool defaults, agents still make bad compute-module design choices because they lack a clear decision guide and concise, trustworthy references.

This issue is the product-facing playbook: what to build and how to choose the right compute module variation.

Desired Outcome

A maintainer/agent can quickly answer:

• Which compute module variation should we use for this requirement?
• What are the hard constraints/limitations?
• What examples should we reference first?

Without copying huge external docs into this repo.

Scope

In scope:

• Compute module decision guide (variation selection by requirement).
• Capability matrix (interfaces, constraints, known limitations).
• Explicit stream-output-required paths and caveats.
• Lean reference catalog of best-in-class example repos.
• Context7-first sourcing strategy (requirements and curation rules).
• Design brief for unsupported-task fallback via platform APIs (handoff to Platform API fallback CLI for unsupported tasks stream-first #28).

Out of scope:

• Implementing Context7 catalog/retrieval mechanics (tracked in Context7 source catalog for curated compute examples #29).
• Implementing platform API fallback CLI (tracked in Platform API fallback CLI for unsupported tasks stream-first #28).
• Adding gh MCP or gh_grep dependency.

Success Criteria

• Decision guide maps representative requests to one recommended variation.
• Capability matrix makes interface limits and stream constraints explicit.
• Reference catalog links each repo to a specific use-case class.
• Strategy stays lean: link to canonical sources, avoid duplicating large external docs.
• Handoff requirements for Platform API fallback CLI for unsupported tasks stream-first #28 and Context7 source catalog for curated compute examples #29 are clear and actionable.

High-Level Plan

1. Define decision tree + capability matrix.
2. Curate example repos with concise “why this repo” notes.
3. Add lean sourcing policy for Context7-based curation.
4. Write fallback design brief for unsupported MCP tasks.

Dependencies

• Blocked by: Foundry defaults: hard-signature profiles and unified default policy #22
• Blocks: Platform API fallback CLI for unsupported tasks stream-first #28, Context7 source catalog for curated compute examples #29
• Related: Auto-download Palantir docs database on plugin install (post-install hook) #19

[anand-testcompare]

Grep by Vercel
Add the Grep by Vercel MCP server to search through code snippets on GitHub.

opencode.json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"gh_grep": {
"type": "remote",
"url": "https://mcp.grep.app"
}
}
}

Since we named our MCP server gh_grep, you can add use the gh_grep tool to your prompts to get the agent to use it.

What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool

Alternatively, you can add something like this to your AGENTS.md.

AGENTS.md
If you are unsure how to do something, use gh_grep to search code examples from GitHub.

---

in this case we know exactly which reference repos to include, but lets solve more holistically by likely enabling this for the foundry-librarian and some prompts in foundry agent maybe even general agents.md to make sure it knows how to / can use it for parallel browsing

[anand-testcompare]

Research update after digging into oh-my-opencode oracle design.

I reviewed these upstream files for how Oracle is actually defined and used:

• src/agents/oracle.ts
• src/shared/model-requirements.ts
• src/agents/dynamic-agent-prompt-builder.ts
• src/agents/builtin-agents/general-agents.ts
• src/shared/agent-tool-restrictions.ts

What they do well (and we can adapt)

1. Oracle is an advisor agent, not an execution agent

   • Subagent mode with consultation-focused prompt.
   • Tool restrictions make it effectively read-only (no write/edit/delegation behavior in normal use).

2. They avoid hard deterministic routing

   • Oracle usage is guided by metadata (useWhen / avoidWhen) and orchestration heuristics.
   • This keeps latitude for reasoning while still giving the main agent guardrails.

3. Prompt design is structured but not brittle

   • Strong reasoning frame: pragmatic minimalism, clear recommendation, explicit uncertainty handling.
   • Output scaffolding exists, but still allows freeform judgment and tradeoff discussion.

4. Model strategy is explicit and provider-resilient

   • Oracle fallback chain in code is: gpt-5.2 -> gemini-3-pro -> claude-opus-4-6.
   • Runtime configuration can override the model per user/team.

5. Orchestrator integration is where value compounds

   • Oracle is embedded in planner/orchestrator behavior, not just defined as an isolated static agent.
   • Practical effect: high-value consults for architecture/debugging, not constant overuse.

Proposed update to #23 scope (to match our direction)

I propose we position #23 as a Foundry compute architecture expertise framework + oracle handoff, not a strict decision router.

Add these deliverables to #23

• Foundry-Oriented Decision Framework (non-rigid)

  • Clarify where each compute module variation works / does not work.
  • Include constraints, caveats, and failure modes.

• Foundry-Oracle Design Brief

  • Agent role and boundaries (advisor vs executor).
  • Reasoning style expectations (tradeoffs, assumptions, confidence, alternatives).
  • Integration contract with foundry-librarian (evidence gathering) and foundry (execution).

• Curated Local Knowledge Plan (repo-local)

  • Define curated corpus shape in-repo (example manifests + groomed notes + provenance metadata).
  • Include manual capture workflow for browser-discovered Foundry docs/UI insights.
  • Keep retrieval lean and local-first.

• Handoff requirements for Context7 source catalog for curated compute examples #29 and Platform API fallback CLI for unsupported tasks stream-first #28

  • Context7 source catalog for curated compute examples #29: implement curated source catalog + retrieval mechanics for the oracle/librarian path.
  • Platform API fallback CLI for unsupported tasks stream-first #28: implement fallback CLI capabilities needed when MCP gaps block execution.

Explicit non-goal for #23

• Do not build a rigid one-path-only decision engine that over-constrains model reasoning.

If this direction looks good, I can turn this into a concrete v1 artifact list (files + schemas + command/agent touchpoints) in the next pass.