cs-scientist-plugin 0.1.0

package/PROTOCOL.md

@@ -0,0 +1,431 @@
+# CS-Scientist Plugin — Communication Protocol v1.1
+
+This document is the authoritative contract for all agents in the plugin.
+Before writing or modifying any agent prompt, read this file.
+If a behavior conflicts with this document, this document wins.
+
+---
+
+## Agent Registry
+
+Each agent has exactly one responsibility. If it does more than one thing, it is incorrectly designed.
+
+| Agent | Single Responsibility | Writes to disk | Reads from disk |
+|-------|-----------------------|---------------|-----------------|
+| `cs-scientist` | Routing + session init | `session_state.json`, `goals.md` (init only) | `session_state.json` |
+| `cs-scientist-research` | Research loop (phases 1–10) | `session_state.json`, `goals.md`, `activity_log.jsonl`, KB | `session_state.json`, `goals.md`, `activity_log.jsonl` (last 5), KB |
+| `cs-scientist-dev` | Dev loop (phases 1–7) | `session_state.json`, `goals.md`, `activity_log.jsonl`, KB | `session_state.json`, `goals.md`, `activity_log.jsonl` (last 5), KB |
+| `cs-scientist-teach` | Teaching loop (phases 1–7) | `session_state.json`, `goals.md`, `activity_log.jsonl`, KB, `lesson.md` | `session_state.json`, `goals.md`, `activity_log.jsonl` (last 5), KB, sources |
+| `cs-scientist-critic` | Gate validation | Nothing | Nothing |
+| `cs-scientist-consultant` | Domain diagnosis | Nothing | Nothing |
+| `cs-scientist-arbiter` | Council synthesis | Nothing | Nothing |
+
+Sub-agents (critic, consultant, arbiter) **never touch disk**.
+They receive structured input and return structured output. Period.
+Sub-agent outcomes are logged by the mode agent that called them, not by the sub-agent itself.
+
+---
+
+## Session Files
+
+Every session lives in `.cs-scientist/{session_id}/` relative to the project root.
+The session contains exactly these files:
+
+| File | Purpose | Append-only |
+|------|---------|-------------|
+| `session_state.json` | State machine — where the session is right now | No (overwritten) |
+| `goals.md` | Goal tracker — what the session is trying to achieve | No (updated) |
+| `activity_log.jsonl` | Action history — what each agent did per turn | Yes |
+| `knowledge_base.md` | Verified facts accumulator | No (updated) |
+
+---
+
+## session_state.json
+
+The single file that defines where the session is.
+Everything else (KB, logs) is content. This is the state machine.
+
+```json
+{
+  "schema_version": "1.0",
+  "session_id": "topic-slug_mode_YYYYMMDD",
+  "mode": "research | dev | null",
+  "topic": "string",
+  "verifier": "string — external truth criterion",
+
+  "phase": "SCOPE | DECOMPOSE | RETRIEVE | TRIANGULATE | PROPOSE | EXPERIMENT | ANALYZE | SYNTHESIZE | CRITIQUE | DOCUMENT | DESIGN | PLAN | IMPLEMENT | VERIFY | ITERATE | INTAKE | MAP | SCAFFOLD | EXPLAIN | ITERATE_TEACH",
+  "phase_status": "active | blocked | completed",
+
+  "gates": {
+    "GATE_1":       "pending | pass | fail",
+    "GATE_2":       "pending | pass | fail",
+    "GATE_3":       "pending | pass | fail",
+    "GATE_1_DEV":   "pending | pass | fail",
+    "GATE_2_DEV":   "pending | pass | fail",
+    "GATE_1_TEACH": "pending | pass | fail",
+    "GATE_2_TEACH": "pending | pass | fail",
+    "GATE_3_TEACH": "pending | pass | fail"
+  },
+
+  "active_artifact_ref": "path or inline ID of artifact being worked on",
+  "next_action": "concrete action, no ambiguity, for the next turn",
+  "blocked_reason": "string | null",
+
+  "iteration_count": 0,
+  "last_updated": "ISO8601",
+  "last_agent": "id of the agent that wrote this",
+  "last_agent_summary": "≤1 sentence of what that agent did"
+}
+```
+
+### Write rules
+
+- Orchestrator writes only on init (creates the file)
+- Mode agents write after every phase or gate transition — not before, not mid-phase
+- Sub-agents never write this file
+- If `next_action` is empty or ambiguous, the file is malformed
+
+---
+
+## goals.md
+
+Tracks what the session is trying to achieve at every level.
+Written by the orchestrator on init, updated by mode agents as work progresses.
+
+### Schema
+
+```markdown
+# Session Goals
+
+## Primary Goal
+{set at init, never modified — the overarching objective of this session}
+
+## Active
+- [ ] HIGH | {goal description} | phase: {phase_name}
+- [ ] MEDIUM | {goal description} | phase: {phase_name}
+- [ ] LOW | {goal description} | phase: {phase_name}
+
+## Completed
+- [x] {goal description} | closed_at: {phase_name} | result: {one sentence}
+
+## Blocked
+- [!] {goal description} | blocked_by: {reason} | unblocks_when: {condition}
+```
+
+### Write rules
+
+- Orchestrator writes the Primary Goal and initial Active goals at init
+- Orchestrator may also close or add goals if the user requests it mid-session
+- Mode agents add goals when a phase reveals new objectives
+- Mode agents move goals from Active → Completed after phase exit with a verified result
+- Mode agents move goals from Active → Blocked when a gate returns FAIL and the cause is unresolved
+- Priority values are fixed: `HIGH`, `MEDIUM`, `LOW` — no other values
+- Primary Goal section is never modified after init
+
+---
+
+## activity_log.jsonl
+
+Append-only log of every significant action. One JSON object per line.
+Mode agents read the last 5 entries at the start of every turn to reconstruct what happened in the previous context window.
+
+### Schema (one entry per line)
+
+```json
+{
+  "ts": "ISO8601",
+  "agent": "cs-scientist | cs-scientist-research | cs-scientist-dev",
+  "phase": "SCOPE | RETRIEVE | ...",
+  "action_type": "phase_enter | phase_complete | gate_dispatch | gate_return | subagent_dispatch | subagent_return | kb_update | goal_update | session_init | session_resume",
+  "summary": "≤1 sentence — what happened",
+  "result": "outcome or null",
+  "iteration": 0
+}
+```
+
+### Write rules
+
+- Written after every significant action — not every thought, every action
+- Significant actions: phase enter, phase complete, gate dispatch, gate return, sub-agent dispatch, sub-agent return, KB update, goal state change
+- Sub-agent outcomes are logged by the mode agent that called them, with `action_type: "subagent_return"`
+- Never rewrite or delete entries — append only
+- `iteration` increments on each full Verified Loop cycle, not on each action
+
+---
+
+## Dispatch and Return Contracts
+
+All inter-agent communication uses this envelope:
+
+```
+[DISPATCH → {agent_id}]
+---
+{payload structured per agent spec below}
+---
+```
+
+```
+[RETURN → {agent_id}]
+---
+{structured response payload}
+---
+```
+
+### cs-scientist-critic
+
+**Dispatch payload:**
+```
+GATE: GATE_1 | GATE_2 | GATE_3 | GATE_1_DEV | GATE_2_DEV | GATE_1_TEACH | GATE_2_TEACH | GATE_3_TEACH | CRITIQUE_LIBRE
+ARTIFACT:
+{artifact verbatim}
+```
+
+**Return payload:**
+```
+VERDICT: PASS | FAIL | HUMAN_REQUIRED
+GATE: {gate_id}
+FAILURES:
+- {failure 1}
+- {failure 2}
+HUMAN_QUESTIONS:
+- {question if HUMAN_REQUIRED}
+PASS_NOTES:
+- {caveats if PASS}
+```
+
+### cs-scientist-consultant
+
+**Dispatch payload:**
+```
+DOMAIN: {one sentence}
+GATE_DIAGNOSIS: {FAILURES verbatim from Critic return}
+FAILED_ARTIFACT:
+{artifact verbatim}
+```
+
+**Return payload:**
+```
+ROOT_CAUSE: {specific, not generic}
+CORRECTION: {concrete change — which line/section and how}
+WHY_APPROACH_FAILED: {domain-specific reason}
+```
+
+### cs-scientist-arbiter
+
+**Dispatch payload:**
+```
+BRIEF: {~800 tokens of shared context}
+DEFENDER_A: {structured output from defender agent}
+DEFENDER_B: {structured output from defender agent}
+DEFENDER_C: {structured output from defender agent}
+```
+
+**Return payload:**
+```
+SYNTHESIS:
+- In {situation A}: → Option {X} | {reason ≤1 line}
+- In {situation B}: → Option {Y} | {reason ≤1 line}
+NOT_RECOMMENDED_IF:
+- Option A: {disqualifying condition}
+- Option B: {disqualifying condition}
+- Option C: {disqualifying condition}
+FOR_CURRENT_CONTEXT:
+→ {recommended option} | {justification ≤3 lines}
+```
+
+---
+
+## Iron Rule — applied in every agent prompt that touches disk
+
+```
+FIRST action every turn:
+  1. Read session_state.json
+  2. Read goals.md
+  3. Read last 5 entries of activity_log.jsonl
+
+AFTER every significant action:
+  4. Append one entry to activity_log.jsonl
+
+AFTER any phase or gate transition:
+  5. Update session_state.json
+  6. Update goals.md if goal state changed
+
+If session_state.json does not exist: stop and notify the user — do not improvise state.
+If activity_log.jsonl does not exist: create it empty, then proceed.
+If goals.md does not exist: stop and notify the user — do not improvise goals.
+```
+
+This is not a guideline. It appears as a NEVER block in every mode agent.
+
+---
+
+## Isolation Rule
+
+The value of sub-agents comes from having zero session context.
+When dispatching, pass only the structured artifact — never session history, never "for context."
+A critic with session context cannot evaluate adversarially.
+
+---
+
+## Gate Failure Routing
+
+Before acting on a gate failure, classify the cause:
+
+```
+Does the failure mention methodological terms ("falsifiable", "circular", "verifier")?
+→ METHODOLOGICAL → mode agent corrects directly (max 2 attempts, then HUMAN_REQUIRED)
+
+Does the failure mention datasets, algorithms, libraries, domain terminology?
+→ DOMAIN → dispatch cs-scientist-consultant before retrying
+```
+
+---
+
+## Project Health Check
+
+The orchestrator runs this check **before** asking the user for mode (Research or Dev).
+Never skip it. Never run it after the session has started.
+The goal is to ensure the project has the files it needs to be maintainable by agents and humans.
+
+### Universal files — any project
+
+| File | Purpose | Action if missing |
+|------|---------|-------------------|
+| `AGENTS.md` or `CLAUDE.md` | AI agent instructions for this project | Run AGENTS.md questionnaire (see below) |
+| `README.md` | What it is, how to run, how to test | Notify user — do not create without their input |
+| `.gitignore` | Exclude files from version control | Create base version for detected project type |
+| `CHANGELOG.md` | Version history | Create empty with standard header |
+| `docs/adr/` | Architecture Decision Records | Propose creating first ADR if architectural decisions are made during session |
+
+### Project-type files
+
+Detect project type from existing files, then check for:
+
+| Type | Required files |
+|------|---------------|
+| Node / Web | `package.json`, `.env.example` |
+| Python | `pyproject.toml` or `requirements.txt`, `.python-version` |
+| Container | `Dockerfile`, `docker-compose.yml` |
+| CI/CD active | `.github/workflows/` or equivalent |
+| ML / Data | `data/README.md`, `MODEL_CARD.md` |
+
+### Rules
+
+- Missing universal files → notify user with a checklist before proceeding
+- Missing project-type files → notify, offer to create, do not block the session
+- `README.md` is never auto-created — it requires human context
+- `AGENTS.md` triggers the questionnaire below — it is the most important file for agents
+- ADRs are proposed, never created silently
+
+---
+
+## AGENTS.md Questionnaire
+
+Run when `AGENTS.md` (or `CLAUDE.md`) does not exist.
+Ask exactly these 8 questions — no more, no less.
+Every line in the resulting file must earn its place. Verbose autogenerated files hurt agent performance.
+
+```
+1. What type of project is this?
+   (web app / CLI / library / data pipeline / ML / embedded system / other)
+
+2. What language(s) and main frameworks?
+
+3. What architecture pattern does it follow?
+   (monolith / microservices / MVC / event-driven / CQRS / no formal architecture)
+
+4. What are the exact commands to: run locally, run tests, deploy?
+
+5. What is the "done" criterion for a task?
+   (tests pass / linter clean / review approved / specific metrics)
+
+6. What should an AI agent NEVER do in this project?
+   (touch prod / modify migrations / push without review / other)
+
+7. Are there non-obvious architectural decisions an agent must know about?
+   (something that looks wrong but has a reason)
+
+8. Are there hard constraints?
+   (performance targets, security requirements, compliance, backwards compatibility)
+```
+
+From the answers, generate a minimal `AGENTS.md` with these sections only:
+
+```markdown
+# AGENTS.md
+
+## Project
+{type} — {language/framework} — {architecture pattern}
+
+## Run
+{exact commands}
+
+## Done means
+{done criterion}
+
+## Never
+- {forbidden action 1}
+- {forbidden action 2}
+
+## Non-obvious decisions
+- {decision}: {reason}
+
+## Hard constraints
+- {constraint}
+```
+
+Omit any section for which the user had no answer. Do not pad with generic advice.
+
+---
+
+## Verifier Hierarchy
+
+Inspired by DeepMind's AlphaProof: the most rigorous verification is the most formal available.
+When defining the external truth criterion (SCOPE phase, GATE_1), choose the highest applicable level.
+
+```
+Level 1 — Formal (strongest)
+  Compiler, type checker, proof assistant (Lean, Coq), constraint solver.
+  If it compiles and type-checks, the property holds by construction.
+  Use when: type safety, protocol conformance, mathematical theorems.
+
+Level 2 — Automated test
+  Unit test, integration test, property-based test (Hypothesis, QuickCheck).
+  Executable and repeatable. Fails predictably.
+  Use when: functional correctness, contract compliance, regression prevention.
+
+Level 3 — Empirical measurement
+  Benchmark, statistical test, A/B comparison, reproducible experiment.
+  Results must be reproducible with the same seed/dataset.
+  Use when: performance, quality metrics, model evaluation.
+
+Level 4 — Expert review
+  A qualified human evaluates against explicit criteria.
+  The criteria must be written down before the review — not derived from the output.
+  Use when: no automated verifier exists for the property being checked.
+
+Level 5 — Self-assessment (weakest — avoid)
+  The model evaluates its own output.
+  Only acceptable as a preliminary filter before a higher-level verifier.
+  Never as the final gate.
+```
+
+### Rules
+
+- The mode agent declares the verifier level in `session_state.json` during SCOPE
+- Never accept a Level 5 verifier as a gate — it is a Verified Loop violation
+- If no verifier above Level 4 exists for a claim, the claim stays `[HYPOTHESIS]`
+- When multiple verifiers apply, use the highest level — do not settle for a lower one
+  because it is more convenient
+- Error messages from Level 1/2 verifiers feed back into the next attempt verbatim —
+  not summarized, not interpreted. The raw error is the structured input.
+
+---
+
+## Schema Version
+
+When this protocol changes in a breaking way, increment `schema_version` in `session_state.json`.
+Mode agents must reject state files with a schema version they do not recognize.
+
+Current version: `1.2`
+Changes from `1.1`: Added Project Health Check and AGENTS.md Questionnaire sections.

package/README.md

@@ -0,0 +1,256 @@
+# cs-scientist-plugin
+
+A multi-agent system for rigorous research, development, and teaching — built for [opencode](https://opencode.ai) and [Claude Code](https://claude.ai/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.
+
+---
+
+## 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 | Role |
+|-------|------|
+| `cs-scientist` | Orchestrator — routes to modes, runs project health check, initializes session |
+| `cs-scientist-research` | Research loop — 10 phases: SCOPE → DECOMPOSE → RETRIEVE → TRIANGULATE → PROPOSE → EXPERIMENT → ANALYZE → SYNTHESIZE → CRITIQUE → DOCUMENT |
+| `cs-scientist-dev` | Dev loop — 7 phases: SCOPE → DESIGN → PLAN → IMPLEMENT → VERIFY → ITERATE → DOCUMENT |
+| `cs-scientist-teach` | Teaching loop — 7 phases: INTAKE → MAP → SCAFFOLD → EXPLAIN → VERIFY → ITERATE → DOCUMENT |
+| `cs-scientist-critic` | Adversarial gate validator — zero session context, structured PASS/FAIL/HUMAN_REQUIRED |
+| `cs-scientist-consultant` | Domain expert for gate failures caused by missing domain knowledge |
+| `cs-scientist-arbiter` | Council of State synthesis — evaluates 3+ competing options situationally |
+
+Sub-agents (critic, consultant, arbiter) **never touch disk**. They receive a structured artifact and return a structured verdict.
+
+---
+
+## 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 + ready-to-paste resume block after context compaction |
+| `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
+
+```bash
+npm install -g cs-scientist-plugin
+```
+
+The postinstall script detects which tools you have and asks before copying anything.
+
+**Manual install:**
+
+```bash
+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/` |
+| Claude Code | `~/.claude/agents/` | `~/.claude/commands/` |
+
+---
+
+## Quick start
+
+Activate the orchestrator:
+
+```
+/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}/`, and dispatches to the mode agent.
+
+### 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 after context compaction
+
+```
+/session-status
+```
+
+Returns the current phase, gate states, active goals, last 5 actions, and a ready-to-paste dispatch block. Single copy-paste to resume.
+
+---
+
+## 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 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]       — verified by ≥3 independent sources
+[VERIFIED]   — confirmed by experiment
+[HYPOTHESIS] — plausible but unverified
+[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](https://opencode.ai) and/or [Claude Code](https://claude.ai/code)
+- A model API key configured in your tool
+
+---
+
+## License
+
+MIT