English | 简体中文

Glassroom

🧭 A structured intelligence analysis CLI and workflow core for turning raw sources into reusable analytic artifacts.

Glassroom is a CLI and workflow core for structured intelligence analysis.

It helps move from raw sources to reusable outputs such as source bundles, bias analysis, structured analysis, shared case objects, and downstream teaching or writing artifacts.

TL;DR

# Install skills into an OpenClaw workspace
npx glassroom install openclaw

# Or into the current project
npx glassroom install project

# List what got installed
npx glassroom list-skills

Full details in Installation. Runnable examples in Quick start.

✨ What Glassroom is

Glassroom is not just an agent prompt pack and not just a single skill.

It is a project with two layers:

• a workflow core

  • shared case object
  • intermediate artifacts
  • reusable analysis modules

• an integration layer

  • mountable OpenClaw skills
  • a CLI surface
  • public-safe docs and templates

Use Glassroom when you want a workflow that can:

• turn fragmented analysis outputs into a shared case object
• keep source, bias, mitigation, and structured-analysis layers connected
• support downstream HTML teaching pages or writing deliverables
• expose a reusable schema instead of trapping logic inside one-off prompts
• preserve teaching patterns that can survive beyond a single class artifact

🚫 What Glassroom is not

It is not trying to be:

• a generic essay generator
• a pile of unrelated classroom prompts
• a direct republication channel for classroom-owned artifacts
• a finished end-user platform before the core workflow contract is stable

The open-source rule is simple: publish the portable backbone first, then add public-safe modules that can stand on their own.

⚡ Quick start

The fastest path right now is to assemble a shared case object from public-safe example inputs.

CLI path

glassroom assemble case \
  --base-case examples/base-case.json \
  --source-card examples/source-card.json \
  --bias-analysis examples/bias-analysis.json \
  --mitigation-pack examples/mitigation-pack.json \
  --structured-analysis examples/structured-analysis.json \
  --out-json /tmp/glassroom-case.json \
  --out-md /tmp/glassroom-case.md

Package script path

python3 packages/case-assembler/assemble_case.py \
  --base-case examples/base-case.json \
  --source-card examples/source-card.json \
  --bias-analysis examples/bias-analysis.json \
  --mitigation-pack examples/mitigation-pack.json \
  --structured-analysis examples/structured-analysis.json \
  --out-json /tmp/glassroom-case.json \
  --out-md /tmp/glassroom-case.md

You can also run the public analysis modules directly:

python3 packages/cognitive-bias/build_bias_analysis.py \
  --input examples/bias-input.json \
  --out-json /tmp/bias-analysis.json \
  --out-md /tmp/bias-analysis.md

python3 packages/structured-analysis/build_structured_analysis.py \
  --input examples/structured-analysis-input.json \
  --out-json /tmp/structured-analysis.json \
  --out-md /tmp/structured-analysis.md

python3 packages/source-intake/fetch_source_bundle.py \
  --input examples/source-input.json \
  --out-json /tmp/source-bundle.json \
  --out-md /tmp/source-bundle.md

📦 Installation

Glassroom ships with an installer CLI. The preferred install path is npm.

Command summary

Command	What it does
glassroom install openclaw	Install skills into ~/.openclaw/workspace/skills/
glassroom install project	Install skills into <cwd>/skills/
glassroom install … --skills a,b,c	Install only the named skills
glassroom install … --mode copy|symlink	Override the default install mode
glassroom install … --target <dir>	Override the install target directory
glassroom list-skills [--json]	List all available skills
glassroom assemble case …	Merge intermediate outputs into a case object
glassroom --version / glassroom version	Print the CLI version

Install from npm

npx glassroom install openclaw                                   # into ~/.openclaw/workspace/
npx glassroom install project                                    # into the current project
npx glassroom install openclaw --skills glassroom-router,glassroom-source-intake
npx glassroom list-skills

Alongside the selected skills, the installer also places packages/ and schemas/ as siblings of the skills target so skill wrappers can locate shared utilities. On Unix the default mode is symlink; on Windows it is copy. Override with --mode copy or --mode symlink.

GitHub fallback

If npm is unavailable, you can still run Glassroom directly from GitHub:

npx github:NanAquarius/Glassroom install openclaw
npx github:NanAquarius/Glassroom install project
npx github:NanAquarius/Glassroom list-skills

One-sentence install prompt for AI CLIs

For Claude Code, OpenCode, or similar coding-agent CLIs:

Run `npx glassroom install project` in this workspace and tell me which Glassroom skills are now available.

If the tool has access to your OpenClaw workspace:

Run `npx glassroom install openclaw` and tell me which Glassroom skills were installed into ~/.openclaw/workspace/skills/.

Manual install fallback

Clone the repository and copy or symlink the folders under skills/ into either ~/.openclaw/workspace/skills/ or ./skills/. The installer exists to make that process shorter, cleaner, and easier to repeat.

Relocating the Glassroom root

Skill wrappers find packages/ by walking up from the wrapper's own location. If you relocate the files in a way the walker can't follow, set GLASSROOM_HOME to the Glassroom root and the wrappers will resolve packages/ from there.

export GLASSROOM_HOME=/path/to/Glassroom

🧩 Current public scope

The open-source surface includes:

• a shared Glassroom case schema (schemas/glassroom-case.schema.json) with caseId and title required
• a workflow contract describing how each module enriches that schema
• four analysis packages: case-assembler, cognitive-bias, structured-analysis, source-intake
  • cognitive-bias ships an expanded built-in bias catalog with tradecraft-oriented mitigations
  • structured-analysis validates method parameters
  • source-intake includes URL scheme validation (SSRF prevention), provider-aware extraction, and retry-with-backoff
• a shared utility layer (packages/shared/) used by every analysis module
• five mountable OpenClaw skills under skills/, each a thin wrapper over the package layer
• a de-identified UI template reference library under docs/ui-template-library/
• a Node.js CLI (bin/glassroom.js) with install commands and assemble case
• a CI pipeline: ruff lint + format, mypy type check, unit tests with coverage, Node CLI smoke tests

See Roadmap direction for what is coming next.

🗺 Workflow artifact map

The current core flow looks like this:

partial analysis artifacts
  → shared case object
  → reusable intermediate outputs
  → HTML pages / writing deliverables / teaching artifacts

A more concrete version of that flow is:

base-case.json
  + source-card.json
  + bias-analysis.json
  + mitigation-pack.json
  + structured-analysis.json
    → glassroom-case.json
    → glassroom-case.md

What this structure buys you:

• one reusable unit of work instead of many disconnected outputs
• cleaner handoff between modules
• easier rendering into multiple downstream formats
• less prompt-only logic trapped in one place

🔧 Shared unit of work

Glassroom uses a shared case object as the default unit of work.

See:

• schemas/glassroom-case.schema.json
• docs/workflow-contract.md

Not every module needs every field. The intermediate JSON files under examples/ (source cards, bias analyses, structured analyses, etc.) are partial views of the case object — they intentionally do not validate against the full case schema. Only the final assembled case produced by case-assembler does.

The shared schema is the backbone that lets source intake, bias analysis, structured analysis, mitigations, rendering, and writing outputs keep talking to each other.

🧱 Module families

Package layer

• packages/shared/

  • shared utilities (load_json, write_json, uniq, etc.) used by all analysis modules

• packages/case-assembler/

  • merges partial outputs into one reusable case object

• packages/cognitive-bias/

  • turns candidate biases and excerpts into a reusable bias-analysis artifact
  • bias catalog externalized to bias_catalog.json for easier maintenance and extension

• packages/structured-analysis/

  • turns a policy question, hypotheses, assumptions, and evidence into a structured-analysis artifact

• packages/source-intake/

  • fetches, classifies, and structures source materials with provider-aware retrieval for stronger upstream evidence
  • automatic retry with backoff for transient network errors

Test layer

• tests/
  • 135 unit tests covering shared utilities, case-assembler, cognitive-bias, source-card, source-bundle extraction, and structured-analysis modules
  • run with python -m unittest discover -s tests -v (pytest also works: pytest tests/)

Integration layer

• skills/glassroom-router/
• skills/glassroom-source-intake/
• skills/glassroom-case-assembler/
• skills/glassroom-cognitive-bias/
• skills/glassroom-structured-analysis/
• bin/glassroom.js

Skill scripts are thin wrappers that delegate to packages/, keeping a single source of truth for all analysis logic. The bin/ layer provides the CLI-facing entry point.

🎨 UI template library

Glassroom also includes the beginning of a public-safe UI template library:

• docs/ui-template-library/README.md
• docs/ui-template-library/templates/
• docs/ui-template-library/reference-pages/

This library is for preserving reusable teaching-page structure after de-identification.

It is not a dump of classroom-owned pages.

The rule is to preserve instructional flow, information architecture, and reusable UI logic while removing personal, instructor, course-owner, and source-specific identity markers.

🗂 Repository layout

Glassroom/
├── .github/workflows/ci.yml
├── bin/                  ← Node.js CLI (glassroom.js)
├── docs/
│   └── ui-template-library/
├── examples/             ← public-safe sample inputs and intermediates
├── packages/             ← canonical Python analysis code (single source of truth)
│   ├── shared/           ← shared utilities (load_json, write_json, uniq …)
│   ├── case-assembler/
│   ├── cognitive-bias/
│   ├── source-intake/
│   └── structured-analysis/
├── schemas/
│   └── glassroom-case.schema.json
├── skills/               ← mountable OpenClaw skills, thin wrappers over packages/
│   ├── glassroom-router/
│   ├── glassroom-source-intake/
│   ├── glassroom-case-assembler/
│   ├── glassroom-cognitive-bias/
│   └── glassroom-structured-analysis/
├── tests/                ← unittest + pytest test suite
├── package.json          ← npm metadata + CLI entry point
├── pyproject.toml        ← ruff / mypy / coverage config
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── LICENSE
├── README.md
└── README.zh-CN.md

🧪 Testing

Run the full test suite:

python -m unittest discover -s tests -v   # what CI runs
pytest tests/                              # also supported

CI runs automatically on push and pull requests to main:

1. Lint — ruff check + format verification
2. Type check — mypy static type analysis
3. Python tests — unittest with coverage across Python 3.11/3.12/3.13
4. CLI smoke tests — version, help, and list-skills across Node.js 18/20/22

Local dev only needs Python ≥3.10 and Node ≥18.

🛣 Roadmap direction

Near-term priorities:

1. strengthen the CLI around real analysis commands
2. expand source-ingestion coverage
3. expose more reusable renderer and delivery layers
4. keep OpenClaw integration thin and package-backed

Planned public-facing module families still include:

• OSINT pitfalls and mitigations
• case HTML rendering
• course writing outputs

📐 Design principles

• prefer stable structure over clever inference
• make intermediate artifacts reusable
• keep the shared schema recoverable across modules
• separate workflow orchestration from presentation layers
• open-source only what is public-safe, portable, and maintainable

📌 Status

Glassroom is still in an early extraction phase, but past the "docs-only" stage: the core contract, the first analysis modules, the first de-identified UI reference pattern, and the install + assemble case commands are all public.

Expect the schema, examples, module boundaries, and public-safe renderer layer to keep improving as more of the local Glassroom system is opened up. See CHANGELOG.md for what shipped in each release.

Reference books

These two books are now part of the working reference set behind Glassroom's current direction:

• OSINT Techniques: Resources for Uncovering Online Information — Michael Bazzell, Jason Edison (2024)
• Structured Analytic Techniques for Intelligence Analysis — CQ Press (2020)

License

MIT

Changelog

See CHANGELOG.md.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

---

If Glassroom helps your teaching, analysis, or workflow design, consider giving it a Star, opening an issue, or sharing how you use it.

_{⭐ Star  ·  🐛 Issue  ·  🤝 PR}