# imbad0202/academic-research-skills architecture

> Architecture diagram of the GitHub repository imbad0202/academic-research-skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/imbad0202/academic-research-skills
- Repository: https://github.com/imbad0202/academic-research-skills

## Overview

1. **What this repo is**
   This is not an application server; it is a **Claude Code skill suite**. The core product is a set of markdown-defined agents, modes, commands, and validation rules that extend Claude Code for academic research, paper writing, peer review, and end-to-end pipeline orchestration.

2. **Top-level product boundaries**
   The repository is organized into four major skill subsystems:
   - `deep-research` for research discovery and evidence gathering
   - `academic-paper` for drafting and revising papers
   - `academic-paper-reviewer` for multi-perspective review and calibration
   - `academic-pipeline` for orchestrating the full research-to-publication workflow

   Each subsystem has its own `SKILL.md`, agent prompts, examples, and reference protocols, which makes them independently deployable as Claude Code skills.

3. **Distribution / packaging layer**
   The repo also contains the packaging surface for Claude Code:
   - `.claude-plugin/` for marketplace metadata and plugin manifest
   - `commands/` for `/ars-*` slash commands that map to modes
   - `agents/` for plugin-exposed agent entrypoints
   - `hooks/` for session bootstrap behavior

   This layer is what turns the markdown content into an installable plugin rather than just a cloned repository.

4. **Shared contract and policy layer**
   `shared/` is the central governance boundary. It holds reusable schemas, rubrics, protocols, templates, and policy artifacts used across all four skill suites. This includes:
   - JSON Schema contracts for passports, audits, reviewer outputs, benchmark reports, sprint contracts
   - shared rubrics and reasoning frameworks
   - policy data and disclosure/provenance guidance
   - handoff schemas that define what downstream agents are allowed to consume

   Architecturally, this is the repo’s “type system” and compliance layer.

5. **Primary execution flow**
   User input enters through Claude Code and is routed by skill/mode selection into one of the skill suites. From there, agent prompts drive a staged workflow:
   - intake / planning / research
   - synthesis or drafting
   - review or verification
   - formatting / disclosure / finalization
   - optional post-run audit or process summary

   The important diagram boundary is that **the LLM conversation is orchestrated by stage contracts**, not free-form prompting.

6. **Academic pipeline as the highest-level orchestrator**
   `academic-pipeline` is the repo’s main system-of-systems controller. It models a multi-stage workflow with explicit checkpoints, including mandatory integrity gates and a final process summary stage. It consumes outputs from the other skill suites and converts them into a staged research-to-paper lifecycle with tracked state, provenance, and user confirmation points.

7. **Evidence and provenance flow**
   The repo is heavily centered on **Material Passport** and provenance artifacts. These travel through the pipeline as structured inputs/outputs and carry:
   - literature corpus entries
   - timeline and citation provenance
   - claim audit results
   - reset ledgers and compliance histories
   - integrity / temporal / contamination signals

   This is the main data backbone for cross-session continuity and auditability.

8. **Research and citation verification subsystem**
   `deep-research` and parts of `academic-pipeline` integrate external evidence sources and verification tooling. The scripts reference:
   - Semantic Scholar
   - OpenAlex
   - Crossref

   These are used for reference validation, deduplication, source matching, contamination detection, and claim-level checks. The architecture explicitly separates **advisory evidence** from hard-blocking output gates.

9. **Writing and publication subsystem**
   `academic-paper` is the document-generation side: it handles drafting, abstracting, literature reviews, revision coaching, citation formatting, LaTeX/PDF hardening, and disclosure generation. Its outputs are manuscript artifacts, formatting conversions, and revision-tracking templates, rather than research evidence itself.

10. **Review and evaluation subsystem**
   `academic-paper-reviewer` is a distinct read-only subsystem for evaluation. It produces peer-review reports, editorial decisions, and calibration outputs using rubric-based scoring and multiple reviewer roles. The key boundary is that this subsystem **does not modify the manuscript**; it assesses it and generates review artifacts.

11. **Python tooling and deterministic checks**
   `scripts/` contains the operational layer: schema linters, integrity auditors, migration utilities, external API clients, and end-to-end checks. These scripts enforce the contracts defined in `shared/` and are wired into CI. In architecture terms, they are the repo’s deterministic guardrails around otherwise probabilistic LLM behavior.

12. **Tests, fixtures, and release governance**
   `tests/` and `scripts/fixtures/` provide the validation harness for routing, phase boundaries, audit logic, temporal verification, and pattern protection. GitHub Actions workflows in `.github/workflows/` continuously enforce spec consistency, pytest coverage, freshness, and release-related checks. This is a repo where **documentation, schemas, tests, and prompts are all first-class architectural elements**.

13. **External/runtime dependencies that matter**
   The repo depends on Claude Code as the runtime host, with optional document tooling like Pandoc and tectonic for DOCX/PDF output. For data verification it reaches out to bibliographic and citation services, and for plugin distribution it uses GitHub-hosted marketplace metadata. These dependencies matter because they shape what is generated locally versus what is verified externally.

14. **How to draw the diagram**
   A correct architecture diagram should show:
   - Claude Code as the host runtime at the top
   - four skill subsystems underneath
   - `shared/` as the common contract/policy layer across all of them
   - `scripts/` and CI as the enforcement/verification layer
   - external citation and metadata APIs as the evidence sources
   - artifacts flowing through passports, audits, reviews, and final manuscripts

   The most important structural idea is that this repo is a **contract-driven LLM workflow platform**, not a monolithic application.

Main entry points: [`academic-pipeline/SKILL.md`](https://github.com/imbad0202/academic-research-skills/blob/main/academic-pipeline/SKILL.md) (Paper pipeline), [`deep-research/SKILL.md`](https://github.com/imbad0202/academic-research-skills/blob/main/deep-research/SKILL.md) (Deep research), [`shared/contracts/README.md`](https://github.com/imbad0202/academic-research-skills/blob/main/shared/contracts/README.md) (Shared contracts), [`academic-paper/SKILL.md`](https://github.com/imbad0202/academic-research-skills/blob/main/academic-paper/SKILL.md) (Academic paper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Claude Code host"]
  node_claude_code(("Claude Code<br/>runtime host"))
  node_plugin_manifest["Plugin pack<br/>distribution<br/>[plugin.json]"]
  node_slash_commands["Slash commands<br/>entrypoints<br/>[ars-full.md]"]
  node_agent_entrypoints["Agent entrypoints<br/>plugin agents"]
  node_session_hooks["Session hooks<br/>bootstrap<br/>[hooks.json]"]
end

subgraph group_skills["Skill suites"]
  node_deep_research["Deep research<br/>skill<br/>[SKILL.md]"]
  node_academic_paper["Academic paper<br/>skill<br/>[SKILL.md]"]
  node_paper_reviewer["Paper reviewer<br/>skill<br/>[SKILL.md]"]
  node_academic_pipeline["Paper pipeline<br/>orchestrator skill<br/>[SKILL.md]"]
end

subgraph group_governance["Shared contracts"]
  node_shared_contracts[("Shared contracts<br/>governance layer<br/>[README.md]")]
  node_shared_rubrics["Rubrics & policy<br/>governance rules"]
  node_passport_flow[("Passport flow<br/>provenance backbone")]
end

subgraph group_verification["Checks and CI"]
  node_deterministic_checks["Deterministic checks<br/>scripts"]
  node_adapters["Corpus adapters<br/>tooling<br/>[zotero.py]"]
  node_ci_workflows["CI workflows<br/>automation"]
  node_fixtures["Fixtures<br/>validation data<br/>[README.md]"]
end

subgraph group_external["External sources"]
  node_semantic_scholar(("Semantic Scholar<br/>evidence API"))
  node_openalex(("OpenAlex<br/>evidence API"))
  node_crossref(("Crossref<br/>citation API"))
  node_doc_tooling(("Pandoc/tectonic<br/>document tooling"))
end

node_claude_code -->|"loads"| node_plugin_manifest
node_plugin_manifest -->|"exposes"| node_slash_commands
node_plugin_manifest -->|"exposes"| node_agent_entrypoints
node_plugin_manifest -->|"boots"| node_session_hooks
node_claude_code -->|"routes to"| node_deep_research
node_claude_code -->|"routes to"| node_academic_paper
node_claude_code -->|"routes to"| node_paper_reviewer
node_claude_code -->|"routes to"| node_academic_pipeline
node_deep_research -->|"consumes"| node_shared_contracts
node_academic_paper -->|"consumes"| node_shared_contracts
node_paper_reviewer -->|"consumes"| node_shared_contracts
node_academic_pipeline -->|"consumes"| node_shared_contracts
node_shared_contracts -->|"defines"| node_passport_flow
node_shared_rubrics -->|"guides"| node_paper_reviewer
node_shared_rubrics -->|"guides"| node_academic_paper
node_shared_rubrics -->|"guides"| node_academic_pipeline
node_academic_pipeline -->|"moves"| node_passport_flow
node_deep_research -->|"queries"| node_semantic_scholar
node_deep_research -->|"queries"| node_openalex
node_deep_research -->|"queries"| node_crossref
node_academic_paper -->|"renders with"| node_doc_tooling
node_deterministic_checks -->|"validates"| node_shared_contracts
node_deterministic_checks -->|"audits"| node_passport_flow
node_adapters -->|"ingests into"| node_passport_flow
node_ci_workflows -->|"runs"| node_deterministic_checks
node_fixtures -->|"exercise"| node_deterministic_checks
node_academic_pipeline -->|"consumes outputs"| node_deep_research
node_academic_pipeline -->|"consumes outputs"| node_academic_paper
node_academic_pipeline -->|"consumes outputs"| node_paper_reviewer

click node_plugin_manifest "https://github.com/imbad0202/academic-research-skills/blob/main/.claude-plugin/plugin.json"
click node_slash_commands "https://github.com/imbad0202/academic-research-skills/blob/main/commands/ars-full.md"
click node_agent_entrypoints "https://github.com/imbad0202/academic-research-skills/blob/main/agents/research_architect_agent.md"
click node_session_hooks "https://github.com/imbad0202/academic-research-skills/blob/main/hooks/hooks.json"
click node_deep_research "https://github.com/imbad0202/academic-research-skills/blob/main/deep-research/SKILL.md"
click node_academic_paper "https://github.com/imbad0202/academic-research-skills/blob/main/academic-paper/SKILL.md"
click node_paper_reviewer "https://github.com/imbad0202/academic-research-skills/blob/main/academic-paper-reviewer/SKILL.md"
click node_academic_pipeline "https://github.com/imbad0202/academic-research-skills/blob/main/academic-pipeline/SKILL.md"
click node_shared_contracts "https://github.com/imbad0202/academic-research-skills/blob/main/shared/contracts/README.md"
click node_shared_rubrics "https://github.com/imbad0202/academic-research-skills/blob/main/shared/compliance_checkpoint_protocol.md"
click node_passport_flow "https://github.com/imbad0202/academic-research-skills/blob/main/shared/contracts/passport/literature_corpus_entry.schema.json"
click node_deterministic_checks "https://github.com/imbad0202/academic-research-skills/blob/main/scripts/check_pipeline_integrity.py"
click node_adapters "https://github.com/imbad0202/academic-research-skills/blob/main/scripts/adapters/zotero.py"
click node_ci_workflows "https://github.com/imbad0202/academic-research-skills/blob/main/.github/workflows/spec-consistency.yml"
click node_fixtures "https://github.com/imbad0202/academic-research-skills/blob/main/tests/fixtures/issue_133_routing/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_claude_code,node_plugin_manifest,node_slash_commands,node_agent_entrypoints,node_session_hooks toneBlue
class node_deep_research,node_academic_paper,node_paper_reviewer,node_academic_pipeline toneAmber
class node_shared_contracts,node_shared_rubrics,node_passport_flow toneMint
class node_deterministic_checks,node_adapters,node_ci_workflows,node_fixtures toneRose
class node_semantic_scholar,node_openalex,node_crossref,node_doc_tooling toneIndigo
```

## Components

### Claude Code host

Plugin packaging and session entrypoints that load the skill suite into Claude Code.

- **Claude Code**: runtime host · Conversation runtime that loads the plugin and routes user requests into skills.
- [Plugin pack](https://github.com/imbad0202/academic-research-skills/blob/main/.claude-plugin/plugin.json): distribution · Marketplace metadata and plugin manifest that package the repository as an installable skill suite. · `.claude-plugin/plugin.json`
- [Slash commands](https://github.com/imbad0202/academic-research-skills/blob/main/commands/ars-full.md): entrypoints · /ars-* command surface that maps user intent into modes and workflows. · `commands/ars-full.md`
- [Agent entrypoints](https://github.com/imbad0202/academic-research-skills/blob/main/agents/research_architect_agent.md): plugin agents · Top-level agents exposed to Claude Code for routing, synthesis, and reporting. · `agents/research_architect_agent.md`
- [Session hooks](https://github.com/imbad0202/academic-research-skills/blob/main/hooks/hooks.json): bootstrap · Hook configuration that initializes session behavior and orchestration defaults. · `hooks/hooks.json`

### Skill suites

Independent markdown-defined subsystems for research, writing, review, and orchestration.

- [Deep research](https://github.com/imbad0202/academic-research-skills/blob/main/deep-research/SKILL.md): skill · Discovery, evidence gathering, source verification, and synthesis for research tasks. · `deep-research/SKILL.md`
- [Academic paper](https://github.com/imbad0202/academic-research-skills/blob/main/academic-paper/SKILL.md): skill · Drafting, revision, citation handling, structure, and publication-oriented manuscript generation. · `academic-paper/SKILL.md`
- [Paper reviewer](https://github.com/imbad0202/academic-research-skills/blob/main/academic-paper-reviewer/SKILL.md): skill · Read-only peer review and editorial evaluation with multi-perspective rubrics. · `academic-paper-reviewer/SKILL.md`
- [Paper pipeline](https://github.com/imbad0202/academic-research-skills/blob/main/academic-pipeline/SKILL.md): orchestrator skill · System-of-systems workflow that stages research-to-publication with checkpoints and summaries. · `academic-pipeline/SKILL.md`

### Shared contracts

Reusable schemas, rubrics, policies, and handoff protocols that constrain all skills.

- [Shared contracts](https://github.com/imbad0202/academic-research-skills/blob/main/shared/contracts/README.md): governance layer · Central schema and policy boundary for passports, audits, reviewers, disclosures, and handoffs. · `shared/contracts/README.md`
- [Rubrics & policy](https://github.com/imbad0202/academic-research-skills/blob/main/shared/compliance_checkpoint_protocol.md): governance rules · Rubrics, compliance checkpoints, cross-model verification, and disclosure policies used across skills. · `shared/compliance_checkpoint_protocol.md`
- [Passport flow](https://github.com/imbad0202/academic-research-skills/blob/main/shared/contracts/passport/literature_corpus_entry.schema.json): provenance backbone · Material passport, citation provenance, timeline, reset ledger, and audit result artifacts that carry state across stages. · `shared/contracts/passport/literature_corpus_entry.schema.json`

### Checks and CI

Deterministic scripts, fixtures, tests, and workflows that validate repo contracts and workflows.

- [Deterministic checks](https://github.com/imbad0202/academic-research-skills/blob/main/scripts/check_pipeline_integrity.py): scripts · Schema linters, auditors, migration utilities, and end-to-end validators that enforce repo contracts. · `scripts/check_pipeline_integrity.py`
- [Corpus adapters](https://github.com/imbad0202/academic-research-skills/blob/main/scripts/adapters/zotero.py): tooling · Import adapters for Zotero, Obsidian, and folder scans that normalize literature corpus inputs. · `scripts/adapters/zotero.py`
- [CI workflows](https://github.com/imbad0202/academic-research-skills/blob/main/.github/workflows/spec-consistency.yml): automation · GitHub Actions gates for spec consistency, freshness, pytest, and release-related checks. · `.github/workflows/spec-consistency.yml`
- [Fixtures](https://github.com/imbad0202/academic-research-skills/blob/main/tests/fixtures/issue_133_routing/README.md): validation data · Golden inputs and expected outputs that exercise routing, integrity, temporal, and pattern-protection behaviors. · `tests/fixtures/issue_133_routing/README.md`

### External sources

Runtime and evidence services used for citation lookup, document rendering, and marketplace distribution.

- **Semantic Scholar**: evidence API · Bibliographic source used for source verification and reference matching.
- **OpenAlex**: evidence API · External metadata source used for literature discovery and deduplication.
- **Crossref**: citation API · Reference metadata and citation validation source used by research tooling.
- **Pandoc/tectonic**: document tooling · Optional document-conversion and PDF-hardening tools for manuscript output.

## Connections

- Claude Code → Plugin pack: loads · Claude Code installs the repository as a plugin package.
- Plugin pack → Slash commands: exposes · Marketplace packaging surfaces slash commands to the host.
- Plugin pack → Agent entrypoints: exposes · Plugin metadata exposes entrypoint agents for orchestration.
- Plugin pack → Session hooks: boots · Plugin bootstrap config wires session initialization behavior.
- Claude Code → Deep research: routes to · User requests are routed into the research skill when discovery is needed.
- Claude Code → Academic paper: routes to · User requests are routed into the writing skill for drafting and revision.
- Claude Code → Paper reviewer: routes to · User requests are routed into the review skill for evaluation only.
- Claude Code → Paper pipeline: routes to · End-to-end workflows are routed into the pipeline orchestrator skill.
- Deep research → Shared contracts: consumes · Research outputs are constrained by shared schemas and handoff contracts.
- Academic paper → Shared contracts: consumes · Manuscript artifacts use shared writer and disclosure schemas.
- Paper reviewer → Shared contracts: consumes · Review artifacts follow shared reviewer and audit schemas.
- Paper pipeline → Shared contracts: consumes · Pipeline state and passports are governed by shared contracts.
- Shared contracts → Passport flow: defines · Passport-related schemas define the repository’s provenance backbone.
- Rubrics & policy → Paper reviewer: guides · Rubrics shape reviewer scoring, calibration, and editorial decisions.
- Rubrics & policy → Academic paper: guides · Writing protocols guide drafting, disclosure, and formatting choices.
- Rubrics & policy → Paper pipeline: guides · Integrity gates and stage protocols govern pipeline checkpoints.
- Paper pipeline → Passport flow: moves · Pipeline stages carry passports, audits, timelines, and reset ledgers.
- Deep research → Semantic Scholar: queries · Research tooling consults bibliographic search and verification APIs.
- Deep research → OpenAlex: queries · Research tooling consults metadata sources for discovery and deduplication.
- Deep research → Crossref: queries · Research tooling validates and enriches citation metadata.
- Academic paper → Pandoc/tectonic: renders with · Paper outputs can be hardened into DOCX/PDF via document tooling.
- Deterministic checks → Shared contracts: validates · Scripts enforce schema and contract consistency across the repository.
- Deterministic checks → Passport flow: audits · Integrity scripts verify passports, claim audits, and temporal constraints.
- Corpus adapters → Passport flow: ingests into · Corpus adapters normalize external literature into passport-compatible structures.
- CI workflows → Deterministic checks: runs · GitHub Actions execute the repo’s validation scripts.
- Fixtures → Deterministic checks: exercise · Golden fixtures drive checks for routing, integrity, and phase boundaries.
- Paper pipeline → Deep research: consumes outputs · The orchestrator consumes research artifacts and evidence packets.
- Paper pipeline → Academic paper: consumes outputs · The orchestrator consumes draft and revision artifacts.
- Paper pipeline → Paper reviewer: consumes outputs · The orchestrator consumes review and calibration artifacts.
