cs-scientist-plugin 0.1.0

package/bin/install.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readdirSync, copyFileSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENTS_SRC = join(__dirname, "..", "agents");
+const SKILLS_SRC = join(__dirname, "..", "skills");
+
+const TARGETS = {
+  opencode: {
+    agents: join(homedir(), ".config", "opencode", "agents"),
+    skills: join(homedir(), ".config", "opencode", "skills"),
+  },
+  claude: {
+    agents: join(homedir(), ".claude", "agents"),
+    skills: join(homedir(), ".claude", "commands"),
+  },
+};
+
+const PLATFORM_PRESENCE = {
+  opencode: join(homedir(), ".config", "opencode"),
+  claude:   join(homedir(), ".claude"),
+};
+
+function copyDir(src, dest, force = false, indent = "  ") {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    if (statSync(srcPath).isDirectory()) {
+      copyDir(srcPath, destPath, force, indent + "  ");
+    } else if (entry.endsWith(".md")) {
+      if (!force && existsSync(destPath)) {
+        console.log(`${indent}~ ${entry} (already exists — skipped, use --force to overwrite)`);
+        continue;
+      }
+      copyFileSync(srcPath, destPath);
+      console.log(`${indent}✓ ${entry}${force && existsSync(destPath) ? " (overwritten)" : ""}`);
+    }
+  }
+}
+
+function detect() {
+  return {
+    opencode: existsSync(PLATFORM_PRESENCE.opencode),
+    claude:   existsSync(PLATFORM_PRESENCE.claude),
+  };
+}
+
+async function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(question, answer => { rl.close(); resolve(answer.trim().toLowerCase()); });
+  });
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const forceOpencode = args.includes("--opencode");
+  const forceClaude   = args.includes("--claude");
+  const force         = args.includes("--force");
+  const silent        = args.includes("--silent"); // used by postinstall
+  const detected      = detect();
+
+  const copy = (src, dest) => copyDir(src, dest, force);
+
+  let installOpencode = forceOpencode || (detected.opencode && !forceClaude);
+  let installClaude   = forceClaude   || (detected.claude   && !forceOpencode);
+
+  if (!silent && !forceOpencode && !forceClaude) {
+    if (detected.opencode) {
+      const ans = await ask("Install agents + skills for opencode? [Y/n] ");
+      installOpencode = ans === "" || ans === "y";
+    }
+    if (detected.claude) {
+      const ans = await ask("Install agents + skills for Claude Code? [Y/n] ");
+      installClaude = ans === "" || ans === "y";
+    }
+  }
+
+  if (!installOpencode && !installClaude) {
+    console.log("Nothing to install. Use --opencode or --claude to force.");
+    process.exit(0);
+  }
+
+  if (installOpencode) {
+    console.log(`\nInstalling agents for opencode → ${TARGETS.opencode.agents}`);
+    copy(AGENTS_SRC, TARGETS.opencode.agents);
+    console.log(`\nInstalling skills for opencode → ${TARGETS.opencode.skills}`);
+    copy(SKILLS_SRC, TARGETS.opencode.skills);
+  }
+
+  if (installClaude) {
+    console.log(`\nInstalling agents for Claude Code → ${TARGETS.claude.agents}`);
+    copy(AGENTS_SRC, TARGETS.claude.agents);
+    console.log(`\nInstalling skills for Claude Code → ${TARGETS.claude.skills}`);
+    copy(SKILLS_SRC, TARGETS.claude.skills);
+  }
+
+  console.log("\nDone. Restart your tool to pick up the new agents and skills.");
+  if (!force) {
+    console.log("Tip: use --force to overwrite existing files on future updates.");
+  }
+}
+
+main().catch(err => { console.error(err.message); process.exit(1); });

package/index.js

@@ -0,0 +1,3 @@
+// Minimal opencode plugin export — agents are installed via postinstall.
+// This file satisfies the opencode plugin module import requirement.
+export default {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "cs-scientist-plugin",
+  "version": "0.1.0",
+  "description": "Verified Loop multi-agent system for rigorous research and development in opencode and Claude Code",
+  "type": "module",
+  "main": "./index.js",
+  "bin": {
+    "cs-scientist-plugin": "./bin/install.js"
+  },
+  "scripts": {
+    "postinstall": "node bin/install.js --silent"
+  },
+  "files": [
+    "agents/",
+    "skills/",
+    "bin/",
+    "index.js",
+    "README.md",
+    "PROTOCOL.md"
+  ],
+  "keywords": [
+    "opencode",
+    "claude-code",
+    "ai-agent",
+    "research",
+    "verified-loop",
+    "cs-scientist",
+    "multi-agent",
+    "knowledge-base"
+  ],
+  "author": "enriqueagm <kikialeglez@gmail.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/QuiquiMatCom2004/cs-scientist-plugin.git"
+  }
+}

package/skills/concept-explainer.md

@@ -0,0 +1,78 @@
+---
+description: >-
+  Lightweight single-concept explainer. No session required. Takes a concept
+  and a student level, explains it at three levels of depth: accessible /
+  practitioner / researcher. Each level is a standalone explanation — not a
+  progression. Quick use during research or dev sessions when a concept needs
+  clarification without starting a full TEACH session.
+---
+
+# concept-explainer
+
+## Input
+
+```
+$ARGUMENTS — "concept [@ level]"
+```
+
+Examples:
+- `gradient descent`
+- `gradient descent @ nivel 0`
+- `transformers @ investigador`
+
+Level options: `nivel 0` (no background) / `grado` (undergraduate) / `investigador` (researcher)
+
+If no level specified: generate all three.
+
+## Rules before explaining
+
+1. If you have a cs-scientist session active with a source KB, derive explanations from KB facts where they apply. Mark with `[KB]`.
+2. If no session KB: explain from general knowledge. Do not cite sources you cannot verify.
+3. Every explanation must include one concrete example. No purely abstract explanations.
+
+## Output format
+
+```
+─── {CONCEPT} ───────────────────────────────────────────────
+
+NIVEL 0 — Para alguien sin conocimiento previo
+{3-5 sentences. Use only analogies to everyday objects or experiences.
+ No formulas. No technical vocabulary.}
+Ejemplo: {one everyday analogy or story}
+
+─────────────────────────────────────────────────────────────
+
+NIVEL GRADO — Para un estudiante universitario
+{5-8 sentences. Technical vocabulary is fine. Show the formal definition but explain it.
+ Connect to concepts a CS undergraduate would know.}
+Ejemplo: {code snippet, equation, or concrete technical scenario}
+
+─────────────────────────────────────────────────────────────
+
+NIVEL INVESTIGADOR — Para alguien activo en el área
+{3-5 sentences. No hand-holding. Highlight the non-obvious aspects,
+ known limitations, open problems, or common misconceptions in the literature.}
+Puntero: {one specific area, paper type, or term to search if they want to go deeper}
+
+─────────────────────────────────────────────────────────────
+
+CONCEPTO RELACIONADO QUE VALE LA PENA CONOCER:
+{one concept that connects to this one — name + one sentence on the connection}
+```
+
+## If session KB is active and concept is in KB
+
+Lead with:
+```
+[KB] Este concepto está en tu base de conocimiento:
+{KB entry verbatim}
+
+Expandiendo desde esa base:
+{then the level(s) requested}
+```
+
+## NEVER
+
+- NEVER make up citations or paper titles — if you can't verify a source, don't cite it
+- NEVER give a researcher-level explanation that is just a longer undergraduate explanation — it must add something a practitioner would actually find useful
+- NEVER skip the concrete example — "I'll skip the example since this concept is abstract" is not acceptable

package/skills/deep-research.md

@@ -0,0 +1,98 @@
+---
+description: >-
+  Systematic multi-source research skill. Takes a research question and
+  returns structured output in cs-scientist KB format (confirmed/insufficient/
+  contradictory/partial). Output is directly importable into the KB without
+  reformatting. Works standalone or as Phase 3 RETRIEVE accelerator.
+---
+
+# deep-research
+
+## Input
+
+```
+$ARGUMENTS — the research question or topic to investigate
+```
+
+If called from cs-scientist-research Phase 3, $ARGUMENTS is the scientific question from SCOPE.
+
+## What you do
+
+Execute systematic research across source types. Do not summarize — extract and classify.
+
+### Step 1 — Search across source types
+
+For every question, search across at least 4 of these source types:
+- Academic / peer-reviewed (arxiv, semantic scholar, pubmed, ACM, IEEE)
+- Industry / technical documentation (official docs, engineering blogs, whitepapers)
+- News / analysis (recent coverage, expert commentary)
+- Primary data / code (GitHub repos, datasets, benchmarks, official repos)
+
+### Step 2 — Classify each claim
+
+For every claim extracted, assign a status:
+
+| Status | Meaning | Output tag |
+|--------|---------|-----------|
+| `confirmed` | ≥3 independent sources agree | `[FACT]` |
+| `contradictory` | Sources disagree — both versions documented | Open Question |
+| `insufficient` | <3 sources or only one source type | `[HYPOTHESIS]` |
+| `partial` | Supported but with caveats or limited scope | `[HYPOTHESIS]` + note |
+
+### Step 3 — Output in KB format
+
+```
+DEEP-RESEARCH: {question}
+DEPTH: standard | deep
+SOURCES_CONSULTED: {N}
+SOURCE_TYPES: {list of types used}
+
+---
+
+CONFIRMED:
+- [FACT] {exact claim} — Source: {title}, {year}, {URL}
+- [FACT] {exact claim} — Source: {title}, {year}, {URL}
+
+INSUFFICIENT:
+- [HYPOTHESIS] {claim} | Supporting: {source}, {year}
+
+CONTRADICTORY:
+- CLAIM: {claim}
+  FOR: {source URL} — {quote or evidence}
+  AGAINST: {source URL} — {quote or evidence}
+  STATUS: open question — do not advance as [FACT]
+
+PARTIAL:
+- [HYPOTHESIS] {claim} | Evidence: {source} | Note: {scope limitation}
+
+OPEN_QUESTIONS:
+- {question that research could not resolve}
+```
+
+## Integration with cs-scientist-research
+
+When called from Phase 3 RETRIEVE, the mode agent maps this output directly:
+
+```
+confirmed  → [FACT] in KB (pending TRIANGULATE)
+insufficient  → [HYPOTHESIS] in KB
+contradictory → register both versions as Open Question
+partial → [HYPOTHESIS] with note "partial evidence — scope limited to {X}"
+```
+
+Phase 4 TRIANGULATE still applies to [FACT] items — deep-research confirming a claim does not
+replace the triangulation requirement. It accelerates source collection.
+
+## Depth modes
+
+`standard` — 2-3 sources per claim, covers main source types, good for established topics
+`deep` — 5+ sources per claim, includes grey literature and primary data, for contested or novel topics
+
+If $ARGUMENTS does not specify depth, use `standard`.
+
+## NEVER
+
+- NEVER mark a claim [VERIFIED] — that tag is reserved for the cs-scientist mode agent after TRIANGULATE
+- NEVER omit contradictory evidence — if sources disagree, both versions are required
+- NEVER summarize sources — quote the specific claim from the source
+- NEVER use secondary sources to confirm a primary claim — independence of sources matters

package/skills/kb-validate.md

@@ -0,0 +1,101 @@
+---
+description: >-
+  Validates the integrity of a cs-scientist knowledge base before advancing
+  to a gate or critical phase. Checks tag consistency, source completeness,
+  circular references, and schema compliance. Returns a structured report
+  with PASS/FAIL and a list of violations. Safe to run at any point.
+---
+
+# kb-validate
+
+## Input
+
+```
+$ARGUMENTS — path to knowledge_base.md, OR session directory path
+```
+
+If $ARGUMENTS is a session directory, look for `knowledge_base.md` inside it.
+
+## What you check
+
+### 1 — Tag consistency
+
+Every item must use exactly one of these tags: `[FACT]`, `[VERIFIED]`, `[HYPOTHESIS]`,
+`[SYNTHESIS]`, `[REFUTED]`, `[DATO]`, `[OPINIÓN]`.
+
+Violations:
+- Item with no tag
+- Item with multiple tags
+- Item with a tag not in this list
+- `[VERIFIED]` item with no source citation
+
+### 2 — Source completeness
+
+Every `[FACT]` and `[VERIFIED]` item must have: title, year, URL (or "experiment_{date}" for experiments).
+
+Violations:
+- Missing source on [FACT] or [VERIFIED]
+- Source present but URL missing
+- "et al." or "various sources" as a source (not specific enough)
+
+### 3 — Circular references
+
+A `[SYNTHESIS]` item cited as evidence for a `[VERIFIED]` item is a circular reference.
+A `[HYPOTHESIS]` used as evidence for another `[HYPOTHESIS]` without noting the chain is a weak chain.
+
+Violations:
+- [SYNTHESIS] cited as [VERIFIED] evidence
+- [HYPOTHESIS] chain without explicit "depends on unverified hypothesis" note
+
+### 4 — Refuted items still referenced
+
+If a `[REFUTED]` claim is cited as evidence anywhere in the KB, it is a contamination.
+
+Violations:
+- Any reference to a [REFUTED] item as supporting evidence
+
+### 5 — Open Questions coverage
+
+If there are claims marked as contradictory but no corresponding Open Question entry, the
+contradiction is silently resolved.
+
+Violations:
+- Contradictory sources cited for the same claim, no Open Question registered
+
+## Output format
+
+```
+KB-VALIDATE: {kb path}
+TIMESTAMP: {ISO8601}
+RESULT: PASS | FAIL
+
+VIOLATIONS:
+- [TAG_CONSISTENCY] Line {N}: {description}
+- [SOURCE_COMPLETENESS] "{claim excerpt}": missing {what}
+- [CIRCULAR_REF] "{synthesis item}": cited as evidence for "{verified item}"
+- [REFUTED_CONTAMINATION] "{refuted claim}": still referenced at line {N}
+- [CONTRADICTION_UNREGISTERED] "{claim}": contradictory sources, no Open Question entry
+
+STATS:
+- [FACT]: {count}
+- [VERIFIED]: {count}
+- [HYPOTHESIS]: {count}
+- [SYNTHESIS]: {count}
+- [REFUTED]: {count}
+- Open Questions: {count}
+
+RECOMMENDATION:
+{one sentence — what to fix before proceeding, or "KB is clean, proceed."}
+```
+
+## Integration with cs-scientist
+
+Run before any gate dispatch to catch KB issues before the critic sees them.
+If FAIL: fix violations before dispatching to cs-scientist-critic.
+If PASS: proceed — the critic evaluates logic, not format.
+
+## NEVER
+
+- NEVER modify the KB — read only
+- NEVER pass a KB with [CIRCULAR_REF] or [REFUTED_CONTAMINATION] violations — these are hard failures
+- NEVER report PASS if any violation exists, even minor ones — the user decides what to fix

package/skills/lesson-plan.md

@@ -0,0 +1,107 @@
+---
+description: >-
+  Lightweight lesson plan generator. Takes a topic, target audience, and
+  available time, and produces a structured lesson plan with learning objective,
+  concept sequence, and suggested activities. Lighter than the full TEACH mode —
+  generates the plan document without running an interactive teaching session.
+  Use to prepare materials before a class.
+---
+
+# lesson-plan
+
+## Input
+
+```
+$ARGUMENTS — "topic [@ audience] [@ duration]"
+```
+
+Examples:
+- `árboles de decisión`
+- `árboles de decisión @ estudiantes de 2do año @ 90 minutos`
+- `gradient descent @ investigadores @ 30 minutos`
+
+Audience options: `bachillerato` / `grado` (default) / `máster` / `investigadores` / `profesionales`
+Duration: in minutes (default: 60)
+
+## Output format
+
+```markdown
+# Plan de Clase: {topic}
+**Audiencia:** {audience} | **Duración:** {N} min | **Fecha:** {today}
+
+---
+
+## Objetivo de Aprendizaje
+
+Al finalizar esta clase, el estudiante podrá:
+{1-2 measurable capabilities — not "understand X", but "solve Y" or "explain Z to someone else"}
+
+---
+
+## Mapa de Conceptos (de prerequisito a objetivo)
+
+{concept} → {concept} → {objective}
+Prerequisitos asumidos: {what students must already know}
+
+---
+
+## Estructura de la Clase
+
+| Bloque | Duración | Actividad | Objetivo del bloque |
+|--------|----------|-----------|---------------------|
+| Apertura | {N} min | {hook — question, problem, or surprising fact} | Activar conocimiento previo |
+| Bloque 1 | {N} min | {core concept 1 — brief description} | {what students can do after} |
+| Bloque 2 | {N} min | {core concept 2} | {capability} |
+| {…} | | | |
+| Verificación | {N} min | {exercise or question type} | Confirmar comprensión |
+| Cierre | {N} min | {summary + forward link} | Consolidar y conectar |
+
+Nota: reserva {10% of duration} para preguntas — redistribuye si no hay.
+
+---
+
+## Actividad de Verificación
+
+{1 exercise or question that tests the learning objective}
+Nivel: Tier 2 (aplicación) — el alumno debe usar el concepto, no solo recordarlo
+
+Si el tiempo lo permite — Tier 3:
+{1 extension exercise that requires applying the idea to a new context}
+
+---
+
+## Material de Apoyo Sugerido
+
+- Requisito mínimo: {one diagram or visual that makes the core idea clearer}
+- Opcional: {code example / dataset / paper reference}
+
+---
+
+## Puntos de Confusión Anticipados
+
+- {common misconception about this topic} → abordar en {block N}
+
+---
+
+## Conexión con Clases Adyacentes
+
+- Viene de: {previous topic in a typical curriculum}
+- Lleva a: {next topic}
+```
+
+## If a cs-scientist TEACH session is active for this topic
+
+Prepend:
+```
+[SESIÓN TEACH ACTIVA]
+Este plan se apoya en los conceptos ya mapeados en tu sesión de teach.
+Fuentes cargadas: {source titles from teach session}
+```
+Then derive concept sequence from the session's source KB rather than generating from scratch.
+
+## NEVER
+
+- NEVER write the full lecture — only the plan
+- NEVER make the learning objective unmeasurable ("entender", "conocer", "apreciar")
+- NEVER omit the verification activity — a class with no verification is not a lesson, it is a presentation
+- NEVER assume prerequisites beyond what the audience level suggests

package/skills/negative-results.md

@@ -0,0 +1,100 @@
+---
+description: >-
+  Documents what was attempted and failed during a cs-scientist session.
+  Extracts gate failures, refuted hypotheses, discarded design decisions, and
+  abandoned approaches from session files. Negative results are first-class
+  scientific findings — they narrow the search space for future attempts.
+  Inspired by DeepMind's practice of documenting what did NOT work.
+---
+
+# negative-results
+
+## Input
+
+```
+$ARGUMENTS — session directory path, OR empty to scan .cs-scientist/ in current project
+```
+
+If $ARGUMENTS is empty:
+1. `git rev-parse --show-toplevel 2>/dev/null || pwd`
+2. List sessions in `{project_root}/.cs-scientist/`
+3. If multiple: ask which one. If one: use it. If none: report no active session.
+
+## What you extract
+
+### From activity_log.jsonl
+- Every entry with `result: fail` or `result: human_required`
+- Every `gate_return` with failure verdict
+
+### From knowledge_base.md
+- All `[REFUTED]` items — claims that were tested and disproven
+- All open questions that were explicitly closed as "unresolvable" in this session
+
+### From plan.md (dev sessions only)
+- `[DECISION]` entries with `Alternatives discarded:` — alternatives that were rejected and why
+
+### From session_state.json
+- Gate failures recorded in the `gates` object
+- `blocked_reason` if present
+
+## Output format
+
+```
+NEGATIVE RESULTS — {session_id}
+Fecha: {ISO8601}
+Modo: {research | dev | teach}
+─────────────────────────────────────────────────────────────────
+
+## 1. Hipótesis Refutadas
+
+{from [REFUTED] KB items}
+- [{REFUTED}] {claim} — Refutado porque: {reason from KB}
+  → Implicación: {what this rules out for future attempts}
+
+## 2. Fallos de Gate
+
+{from activity_log gate_return failures}
+- {GATE_ID} falló en fase {phase}
+  Causa diagnóstica: {FAILURES from critic verbatim}
+  Corrección aplicada: {what was done} | Resultado: {outcome}
+
+## 3. Enfoques Descartados
+
+{from [DECISION] discarded alternatives in dev, or abandoned research angles}
+- Descartado: {approach}
+  Razón: {why not}
+  Condición de reapertura: {under what circumstances this would become viable again}
+
+## 4. Preguntas Abiertas Sin Resolver
+
+{open questions from KB that were not answered in this session}
+- {question} — Estado al cierre: {why unresolved}
+  Sugerencia para próxima sesión: {where to look}
+
+## 5. Bloqueos No Resueltos
+
+{if blocked_reason in session_state.json}
+- Bloqueado en: {phase}
+  Razón: {blocked_reason verbatim}
+
+─────────────────────────────────────────────────────────────────
+RESUMEN
+Hipótesis refutadas: {N} | Fallos de gate: {N} | Enfoques descartados: {N}
+Preguntas sin resolver: {N}
+
+VALOR PARA LA PRÓXIMA SESIÓN:
+{1-2 sentences — what the next session should NOT try again, and where to start instead}
+```
+
+## Save behavior
+
+Ask the user: "¿Guardo esto en `.cs-scientist/{session_id}/negative_results.md`? [S/n]"
+
+Default yes. Do not save automatically — the user decides.
+
+## NEVER
+
+- NEVER infer failures not recorded in the files — only report what is there
+- NEVER present refuted claims as "partially valid" — if [REFUTED], it is refuted
+- NEVER modify KB or session files — read only
+- NEVER omit the "Condición de reapertura" for discarded approaches — it is what makes this useful