cs-scientist-plugin

A multi-agent system for rigorous research, development, and teaching — built for opencode and Claude Code.

The core principle is borrowed from DeepMind's most reliable systems (AlphaFold, AlphaProof, FunSearch):

The model proposes. An external verifier decides.

No self-assessed output advances to the next phase. Every gate is evaluated by a fresh agent with zero session context.

How it works

┌─────────────────────────────────────────────────────────┐
│                    cs-scientist                         │
│               (Primary — Tab-visible)                   │
│         health check → session init → dispatch          │
└───────────┬──────────────┬──────────────┬──────────────┘
            │  Task tool   │  Task tool   │  Task tool
            ▼              ▼              ▼
         RESEARCH         DEV           TEACH
        (subagent)     (subagent)     (subagent)
         10 phases      7 phases       7 phases
            │              │              │
       GATE_1,2,3    GATE_1,2          GATE_1,2,3
            │              │              │
            └──────────────┴──────────────┘
                           │  Task tool
               ┌───────────▼───────────┐
               │   cs-scientist-critic  │
               │      (subagent)        │
               │  zero session context  │
               │  zero disk access      │
               │  PASS / FAIL /         │
               │  HUMAN_REQUIRED        │
               └───────────────────────┘

Only cs-scientist appears in the agent Tab cycle alongside opencode's built-in Build and Plan agents. All other agents (research, dev, teach, critic, consultant, arbiter) are internal subagents — dispatched programmatically by the orchestrator via the Task tool. The user never manually switches to them.

On FAIL → mode agent corrects (max 2 attempts), then HUMAN_REQUIRED. On domain-specific failure → cs-scientist-consultant resolves, then retry.

Example: Critic rejecting a research hypothesis

Task tool → cs-scientist-critic:
  GATE: GATE_3
  ARTIFACT:
    HYPOTHESIS: Transformers outperform RNNs on sequential tasks
    VERIFIER: Run both on Penn Treebank and compare perplexity
    EVIDENCE: [FACT] transformers scale better, [FACT] attention is O(n²)

cs-scientist-critic returns:
  VERDICT: FAIL
  FAILURES:
    - HYPOTHESIS is not falsifiable as stated: "outperform" has no threshold.
      A result of 0.1 perplexity difference would technically satisfy it.
      Rewrite: "Transformer achieves ≥5% lower perplexity on PTB vs best LSTM baseline."
    - EVIDENCE cites [FACT] but neither fact directly supports the hypothesis.
      [FACT] "transformers scale better" does not imply they outperform on PTB specifically.
  NEXT: Mode agent must rewrite hypothesis and re-submit to GATE_3.

The critic has zero session context — it cannot be talked out of a FAIL. Only the artifact matters.

What it does

Three operating modes, each a structured loop with adversarial gates:

| Mode | Purpose | External verifier | |------|---------|------------------| | RESEARCH | Investigate a topic: hypothesis, sources, triangulation, report | Reproducible experiment or ≥3 independent sources | | DEV | Build something with correctness guarantees: TDD, verified design, traced decisions | Compiler / type checker / tests (formality hierarchy enforced) | | TEACH | Learn or teach from provided source materials: progressive explanation, tiered exercises | Student can solve Tier 3 exercises that recall alone cannot answer |

Agents

| Agent | Mode | Role | |-------|------|------| | cs-scientist | primary | Orchestrator — session init, health check, programmatic dispatch to mode agents | | cs-scientist-research | subagent | Research loop — 10 phases: SCOPE → DECOMPOSE → RETRIEVE → TRIANGULATE → PROPOSE → EXPERIMENT → ANALYZE → SYNTHESIZE → CRITIQUE → DOCUMENT | | cs-scientist-dev | subagent | Dev loop — 7 phases: SCOPE → DESIGN → PLAN → IMPLEMENT → VERIFY → ITERATE → DOCUMENT | | cs-scientist-teach | subagent | Teaching loop — 7 phases: INTAKE → MAP → SCAFFOLD → EXPLAIN → VERIFY → ITERATE → DOCUMENT | | cs-scientist-critic | subagent | Adversarial gate validator — zero session context, structured PASS/FAIL/HUMAN_REQUIRED | | cs-scientist-consultant | subagent | Domain expert for gate failures caused by missing domain knowledge | | cs-scientist-arbiter | subagent | Council of State synthesis — evaluates 3+ competing options situationally |

In opencode, only cs-scientist is Tab-visible. All others are dispatched internally via the Task tool — the user interacts only with the orchestrator.

Skills

| Skill | When to use | |-------|-------------| | deep-research | Directed research on a single question with KB-compatible output | | parallel-research | Independent multi-angle searches with no cross-contamination | | kb-validate | Validate KB integrity before a gate: tag consistency, source completeness, circular refs | | session-status | Human-readable session state — useful for manual inspection at any point | | negative-results | Document what didn't work and why: gate failures, refuted hypotheses, discarded approaches | | notebooklm | Convert a completed research report to podcast script, FAQ, or executive briefing | | writing-plans | Ultra-detailed TDD implementation plans — actual code in every step, no placeholders | | project-onboarding | Generate a Day 1 guide for a new team member from the current repo state | | concept-explainer | Explain a concept at 3 levels (accessible / practitioner / researcher) without starting a session | | paper-outline | Map a research session KB to an academic paper skeleton | | lesson-plan | Generate a structured lesson plan for class preparation |

Install

npm install -g cs-scientist-plugin
cs-scientist-plugin

The first command installs the package. The second copies agents and skills into your tool — it detects opencode and Claude Code automatically and asks before writing anything.

Note: The postinstall script runs automatically on npm install -g and installs silently without prompts. Run cs-scientist-plugin manually for interactive installation (choose platforms) or run cs-scientist-plugin --force to overwrite existing files on updates.

Clone and install manually:

git clone https://github.com/QuiquiMatCom2004/cs-scientist-plugin.git
cd cs-scientist-plugin
node bin/install.js

Options:

node bin/install.js              # interactive — asks per platform
node bin/install.js --opencode   # opencode only
node bin/install.js --claude     # Claude Code only
node bin/install.js --force      # overwrite existing files on update

Where files go:

| Platform | Agents | Skills | |----------|--------|--------| | opencode | ~/.config/opencode/agents/ | ~/.config/opencode/skills/<name>/SKILL.md | | Claude Code | ~/.claude/agents/ | ~/.claude/commands/ |

Quick start

In opencode: Tab to cs-scientist.

In Claude Code: /cs-scientist or say investiga, desarrolla con rigor, quiero aprender, modo research, modo dev, modo teach.

The orchestrator runs a project health check, asks which mode and topic, initializes three session files in .cs-scientist/{session_id}/, then dispatches the mode agent via the Task tool — no manual switching required.

Research

cs-scientist → What is the impact of transformers on NLP compared to RNNs?
             → A) RESEARCH

The research agent runs 10 phases. GATE_1 verifies the question is falsifiable. GATE_2 verifies ≥3 independent sources per claim. GATE_3 verifies the hypothesis is falsifiable and non-circular.

Dev

cs-scientist → Implement a sliding window rate limiter with Redis
             → B) DEV

The dev agent runs 7 phases. GATE_1_DEV verifies the done criterion is external and binary. GATE_2_DEV verifies the design is unambiguous. Phase 3 PLAN invokes the writing-plans skill to produce ultra-detailed TDD steps with actual code in every task.

Teach

cs-scientist → I want to understand backpropagation
             → C) TEACH

The teach agent loads your source materials (papers, books, lecture notes), maps concept dependencies, scaffolds a lesson from your current level to the objective, and teaches each concept with a 7-step extractor:

1. Minimal intuition — using only vocabulary you already have
2. Formal definition — verbatim from source
3. Best example — concrete, not abstract
4. Counter-example — what this is NOT
5. Implication — what knowing this lets you do
6. Connection backwards — how this links to what came before
7. What it unlocks — preview of what comes next

Verification: Tier 1 (recall), Tier 2 (apply in source domain), Tier 3 (new scenario where recalling the source is insufficient — reasoning is mandatory).

Resuming a session

Activate cs-scientist again. The orchestrator automatically detects active sessions in .cs-scientist/, shows their state (mode, phase, last action, next step), and dispatches the mode agent to continue — no copy-paste required.

Session files

Every session creates .cs-scientist/{session_id}/ in the project root:

.cs-scientist/
└── topic-slug_mode_YYYYMMDD/
    ├── session_state.json    # state machine — phase, gates, next action
    ├── goals.md              # goal tracker — active, completed, blocked
    ├── activity_log.jsonl    # append-only action history (last 5 read each turn)
    ├── knowledge_base.md     # verified findings accumulator
    ├── plan.md               # (dev) TDD implementation plan
    └── lesson.md             # (teach) lesson with exercises and solutions

session_state.json is the single source of truth for where the session is. The orchestrator reads it on every activation to resume or route correctly.

The Verified Loop

Every mode runs a variant of this cycle:

PROPOSE → CRITIQUE → VERIFY (external) → PERSIST → ITERATE

What makes it rigorous:

• External verifier — defined in SCOPE before any work starts. Not "I'll review it" — a concrete test, benchmark, or experiment that a fresh agent can check independently.
• Adversarial critic — evaluates artifacts with zero session context. Cannot be reassured by prior conversation. Only the artifact matters.
• Structured failures — FAILURES must cite the exact part of the artifact that fails. "Needs improvement" is not a failure.
• Verifier hierarchy — formal verifiers (compiler, type checker, proof assistant) are preferred over tests, tests over empirical measurement, empirical over human review. Self-assessment is never a final gate.

Gates

| Gate | Phase transition | What the critic checks | |------|-----------------|----------------------| | GATE_1 | Research SCOPE | Falsifiable question, external binary truth criterion, explicit scope | | GATE_2 | Research TRIANGULATE | ≥3 independent sources per [FACT], contradictions documented | | GATE_3 | Research PROPOSE | Hypothesis falsifiable, non-circular, evidence from [VERIFIED] only | | GATE_1_DEV | Dev SCOPE | External binary verifier, unambiguous done criterion, explicit constraints | | GATE_2_DEV | Dev DESIGN | Any developer can implement without clarifying questions, all [DECISION] entries present | | GATE_1_TEACH | Teach INTAKE | Objective is measurable (a capability, not "understand X"), sources sufficient | | GATE_2_TEACH | Teach SCAFFOLD | All bridges start from student's actual knowledge, no forward dependencies | | GATE_3_TEACH | Teach VERIFY | Tier 3 exercises cannot be answered by recall alone |

Gate failure routing

Is the failure methodological? ("verifier not binary", "circular", "ambiguous")
→ Mode agent corrects directly — max 2 attempts, then HUMAN_REQUIRED

Is the failure domain-specific? (unknown framework behavior, unclear protocol)
→ Dispatch cs-scientist-consultant — one correction, then retry

Knowledge base tags

Research and teach sessions accumulate findings in knowledge_base.md:

Research KB:

[FACT]       — stated in a source, not yet triangulated
[VERIFIED]   — confirmed by ≥3 independent sources or experiment
[HYPOTHESIS] — model-generated, not yet verified
[SYNTHESIS]  — model-generated connection between verified facts
[REFUTED]    — tested and disproven

Teach KB:

[CORE]         — fundamental concept on the critical path to the objective
[ADVANCED]     — builds on CORE, required for full depth
[APPLIED]      — application of a concept to a specific domain
[PREREQUISITE] — needed but not taught in this session
[MISCONCEPTION]— common wrong understanding, addressed explicitly in EXPLAIN

Protocol

The full inter-agent communication contract is in PROTOCOL.md. It defines the dispatch/return envelope format, gate criteria per gate type, the Iron Rule (3 mandatory reads per turn), verifier hierarchy, and session file schemas.

If an agent behavior conflicts with PROTOCOL.md, the protocol wins.

Requirements

• Node.js ≥ 18
• opencode and/or Claude Code
• A model API key configured in your tool

License

MIT