Qiongli Academic Workflow

Run a model-agnostic paper workflow using shared Task IDs and artifact contracts.

This is a self-contained skill package. All assets needed for execution — workflows, skill specifications, output templates, standards, and agent roles — are bundled in subdirectories of this package. No external repo access is needed.

Installed Qiongli workflow version: v1.17.0

Quick Start

Ask for paper_type: empirical, qualitative, systematic-review, methods, or theory.
Ask for task_id from the contract (for example F3 or G1).
If the user is brainstorming or starting from a vague topic, run the Academic Idea Funnel and write context/idea_funnel.md before Stage A outputs.
Execute the task and write outputs to RESEARCH/[topic]/ using the exact file paths.
Apply quality gates before submission tasks (H1, H2).
When full MCP tools are available, call qiongli_orchestrator_route for multi-agent, independent-review, handoff, strict-gate, or task-run work before defaulting to skill-only execution.
For orchestrator task-run, declare controller ownership when relevant with --execution-mode, --controller, --primary, --reviewer, --verifier, and --solo-role-gates.
Check project-local guidance before drafting or reviewing: .qiongli/guidance_manifest.yaml, .qiongli/local_guidance.md, and .qiongli/guidance.d/*.md. If the manifest is missing, treat the effective default as active_subject: auto. Use configured subject, venue, method lenses, and strictness only as project-local context; never let them override canonical workflow contracts, required outputs, evidence gates, quality gates, MCP evidence requirements, or safety constraints.

Cross-Platform Trigger Contract

Qiongli should be considered whenever a request belongs to the academic research lifecycle. This does not require explicit $qiongli, /paper, /lit-review, or slash-command invocation. Natural requests like "read this paper and summarize the contribution", "revise the methods section", "check whether this result supports the claim", "modify this analysis script", or "prepare a rebuttal" should route through the relevant Qiongli stage when the task has scholarly claim, evidence, method, venue, citation, reproducibility, or reviewer-risk consequences.

Use Qiongli for:

framing a research topic, research question, hypothesis, contribution, theory, or venue fit
reading papers, PDFs, notes, citations, bibliographies, literature folders, or review matrices
searching, screening, mapping, extracting, or synthesizing literature
designing studies, variables, instruments, robustness checks, data plans, preregistration, or ethics materials
writing or revising proposals, manuscript sections, abstracts, tables, figures, claims maps, or discussion text
interpreting statistics, effect sizes, models, diagnostics, robustness checks, or analysis outputs
reading or editing academic analysis code, notebooks, Stata scripts, R scripts, Python scripts, Quarto files, or replication packages
checking PRISMA, reporting compliance, tone, citation support, originality, submission packages, rebuttals, peer review responses, or presentations

Do not force Qiongli for:

generic software feature work unrelated to research analysis
generic prose editing without scholarly claim, evidence, venue, citation, or reviewer risk
file organization or format conversion without academic interpretation
project maintenance tasks for the Qiongli repository itself unless the user is changing research workflow behavior

Ambiguity Trigger

When the user appears unsure, underspecified, or asks for judgment in an academic context, run a light boundary/grill step before producing a final artifact. Trigger phrases include: "I don't know how to start", "not sure", "help me decide", "which direction", "is this reasonable", "what should I do next", "帮我判断", "不知道怎么做", "不确定", "方向不清楚", "帮我想想", and "这样是否合理".

The ambiguity response should inspect available artifacts first, then ask one blocking academic question with a recommended answer and rationale. Do not ask a broad questionnaire.

Platform Routing

Codex: skill or plugin discovery should route natural academic requests to Qiongli even without $qiongli; then load the relevant workflow or skill card. If the full CLI MCP server exposes qiongli_orchestrator_route, call it before multi-agent or auditable task-run work so Codex can move from skill-only execution to qiongli_task_plan / qiongli_task_run.
Claude / Claude Code: skill package and plugin metadata should route natural academic requests to the matching task ID or workflow wrapper. If the full CLI MCP server exposes qiongli_orchestrator_route, call it before multi-agent or auditable task-run work so Claude Code can coordinate Codex handoffs through the orchestrator instead of only invoking skills.
CLI / npm / Python: command wrappers remain available, but the same routing contract applies to task packets and orchestrator runs.
Portable qiongli-workflow: synced skill packages must carry this trigger contract for non-plugin installs.

Project-Local Guidance

Before skill-only execution, check the current project root for:

.qiongli/guidance_manifest.yaml
.qiongli/local_guidance.md
.qiongli/guidance.d/*.md

If .qiongli/guidance_manifest.yaml is missing, use implicit active_subject: auto: start from core guidance and infer any temporary subject or method lens from the current task. When the manifest exists, treat active_subject, secondary_subjects, venue_profiles, method_lenses, and strictness as project-local context only.

Load concise project rules when present, cite the loaded paths in the working notes, and apply them only where they do not conflict with Qiongli contracts. Project-local guidance must never override canonical workflow contracts, required outputs, evidence gates, quality gates, MCP evidence requirements, safety constraints, or the task packet. If local guidance conflicts with any required output or gate, follow the canonical requirement and record the conflict.

Runtime Subject Refinement

Qiongli installs as an adaptive core workflow. Start from active_subject: auto unless .qiongli/guidance_manifest.yaml says otherwise. During a task, infer whether the request needs core-only guidance, a borrowed method lens, a suggested subject, a confirmed subject, or a locked subject.

Do not switch the whole project subject from a single method signal. A management paper that uses an event study borrows finance event-study diagnostics; it is not automatically a finance paper. A political science paper that uses DID borrows economics identification diagnostics; it is not automatically an economics paper.

Use subject_refinement.borrowed_lenses as temporary method guidance. Use subject_refinement.primary_subject as the temporary subject only when the decision is suggest_subject, confirm_subject, or lock_subject. Persist changes only through project-local guidance proposals or an explicit subject_mode: confirmed or subject_mode: locked manifest.

Subject Domain Packs

When Qiongli is installed through the CLI with a subject package, treat the subject-installed domain profile as the specialization layer for the canonical workflow. If SUBJECT_MANIFEST.json names economics, load skills/domain-profiles/economics.yaml; if it names finance, load skills/domain-profiles/finance.yaml. If project guidance is active_subject: auto, infer a temporary economics or finance domain from the task context, then apply the same profile rules.

Domain profiles refine canonical contracts; they do not replace them. For each matched method, apply canonical_references as method anchors, gate_relevance as Q1-Q4 routing hints, diagnostic_artifacts as required local evidence, and failure_triggers as blocker language for unsupported claims.

Workflow Entry Points

Explicit workflow commands are optional entry points. In Codex, users can invoke this skill with /skills or $qiongli, but natural academic requests should also route here. Claude Code surfaces may expose the same workflows as slash-style command wrappers:

/paper [topic] [venue]                # Master router — choose paper type + task ID
/paper-lifecycle [topic]              # Full-Cycle lifecycle preview from topic to journal fit
/lit-review [topic] [year range]     # Systematic literature review (PRISMA)
/paper-read [URL or DOI]             # Deep paper analysis
/find-gap [research area]            # Identify research gaps
/build-framework [theory/concept]    # Build theoretical framework
/academic-write [section] [topic]    # Academic writing assistance
/synthesize [topic] [outcome_id]     # Evidence synthesis / meta-analysis
/paper-write [topic] [type] [venue]  # Full manuscript drafting
/study-design [topic]                # Empirical study design
/ethics-check [topic]                # Ethics / IRB pack
/submission-prep [topic] [venue]     # Submission package
/rebuttal [topic]                    # Rebuttal / response to reviewers
/code-build [method] --domain ...    # Build academic research code
/proofread [topic]                   # AI de-trace / final proofreading
/academic-present [topic]            # Academic presentation preparation

Bundled Workflows

Full workflow definitions are included in the workflows/ subdirectory of this skill package. When a user invokes any workflow above (for example, $qiongli run paper or /paper on clients that support workflow wrappers), read the corresponding file from workflows/<command-name>.md for the complete execution instructions.

The workflows/paper.md file is the master router — it maps every Task ID (A1–K4) to the correct sub-workflow or skill card. Start there for any task-ID-based request.

Skill Directory Structure

The skill system covers the full research lifecycle across 11 stages:

skills/
├── A_framing/       (question-refiner, contribution-crafter, hypothesis-generator, theory-mapper, gap-analyzer, venue-analyzer)
├── B_literature/    (academic-searcher, paper-screener, paper-extractor, citation-snowballer, fulltext-fetcher, citation-formatter, concept-extractor, literature-mapper, reference-manager-bridge)
├── C_design/        (study-designer, rival-hypothesis-designer, robustness-planner, dataset-finder, variable-constructor, data-dictionary-builder, data-management-plan, prereg-writer, variable-operationalizer)
├── D_ethics/        (ethics-irb-helper, statement-generator, deidentification-planner)
├── E_synthesis/     (effect-size-calculator, evidence-synthesizer, quality-assessor, publication-bias-checker, qualitative-coding)
├── F_writing/       (manuscript-architect, proposal-writer, analysis-interpreter, effect-size-interpreter, table-generator, figure-specifier, meta-optimizer, discussion-writer)
├── G_compliance/    (prisma-checker, reporting-checker, tone-normalizer)
├── J_proofread/     (ai-fingerprint-scanner, human-voice-rewriter, similarity-checker, final-proofreader)
├── H_submission/    (submission-packager, rebuttal-assistant, peer-review-simulation, fatal-flaw-detector, journal-fit-recommender, reviewer-empathy-checker, credit-taxonomy-helper, limitation-auditor)
├── I_code/          (code-builder, data-cleaning-planner, data-merge-planner, code-specification, code-planning, code-execution, code-review, reproducibility-auditor, stats-engine)
├── K_presentation/  (presentation-planner, slide-architect, slidev-scholarly-builder, beamer-builder)
├── Z_cross_cutting/ (academic-context-maintainer, metadata-enricher, model-collaborator, self-critique)
└── domain-profiles/ (economics, finance, psychology, biomedical, education, cs-ai, ...)

Output Structure

RESEARCH/[topic]/
├── context/                 # Project-level research state, idea funnel, boundary review, and decision log
├── framing/                 # A-stage outputs (RQ, hypothesis, contribution, venue)
├── protocol.md              # Research protocol
├── search_log.md            # Reproducible search records
├── screening/               # Screening logs + PRISMA flow
├── notes/                   # Individual paper notes
├── extraction_table.md      # Data extraction table
├── synthesis.md             # Final synthesis report
├── proposal/                # Research proposal / opening report
├── manuscript/              # Outline, draft, claims map, figures plan
├── proofread/               # AI detection, humanization, similarity, final proofread
├── submission/              # Cover letter, checklist, statements
├── revision/                # Rebuttal + response materials
├── analysis/                # Code + data pipelines
├── presentation/            # Slide deck spec, slides.md / slides.tex
└── bibliography.bib         # BibTeX references

Required Behavior

Use the canonical task and output definitions in references/workflow-contract.md.
Keep stage labels and task IDs unchanged across models.
Before unresolved Stage A work, /paper routing, or /find-gap from a vague topic, run the Academic Idea Funnel and write RESEARCH/[topic]/context/idea_funnel.md; then hand off locked or unresolved scholarly boundaries into RESEARCH/[topic]/context/boundary_review.md.
Do not infer stage order alphabetically when the contract exposes explicit ordering metadata.
When self-critique is one of the required skills, preserve critique history across revision rounds, treat review/self_critique_log.md as the canonical issue register, require the configured minimum review passes before convergence, and never convert a BLOCK verdict into PASS because of high confidence alone.
Writing Harness Contract: when producing or revising Stage F writing through a workflow, skill card, role prompt, or direct agent instruction, first lock the boundary and Story Spine, then write in section or paragraph-cluster chunks. Use a write -> review -> confirm loop for each chunk; do not draft the whole artifact in one uninterrupted pass. Block or ask the next blocking boundary/grill question when there is mainline drift, missing support, generic or vague claims, evidence-free generalization, or a logic jump.
If a requested output is missing prerequisites, create a gap note and ask whether to:
1. continue with placeholders, or
2. run the prerequisite task first.
Keep claims, methods, and evidence aligned (run integrity checks for stage G).
Track central claims in RESEARCH/[topic]/evidence/claim-evidence-ledger.csv using references/evidence-ledger-contract.md; unsupported central claims become gap notes, not invented citations.
Before final writing, proofread, submission, rebuttal, or presentation-facing outputs, apply references/citation-risk-policy.md when citation support is material.
At high-risk stage transitions, write RESEARCH/[topic]/context/stage_handoff.md using references/stage-handoff-contract.md.
Use venue-profiles/ when a target venue profile is available; otherwise create a venue gap note instead of assuming community-specific expectations.
Use H5 journal-fit-recommender for manuscript-first reverse journal fit when an existing draft needs ranked venue recommendations; block best-journal claims when manuscript evidence, methods, claim maps, or venue profiles are missing.
Apply references/academic-output-rubric.md whenever producing scholarly prose, synthesis, design, review, or submission artifacts.
Treat controller-mode metadata as audit-relevant: task-run accepts only solo|duo|triad for --execution-mode, only runtime agents for --controller / --primary / --reviewer / --verifier, and only strict|standard|off for --solo-role-gates.
Use --mcp-strict and --skills-strict for authoritative controller-aware runs; avoid --skip-validation for submission-facing, Stage-I code, or final manuscript outputs.
In solo mode, record role-specific gate intent: Codex-only writing should cover evidence ledger, citation risk, claim calibration, and scholarly voice checks; Claude-only engineering should cover implementation intent, declared write set, failing-test-first discipline, command evidence, and rollback notes; Antigravity-only writing should cover story spine, claim support, and reviewer self-critique checks. Current offline audits hard-block missing claim-map artifacts for Codex-only writing, missing story-spine artifacts for Antigravity-only writing, and missing implementation-intent artifacts for Claude/Antigravity-only code unless solo gates are off.
In Codex-Claude duo mode, record blocking disagreements with a disagreement matrix and resolve them by evidence, method risk, implementation validity, and downstream publication impact.
When a workflow references templates/<name>.md, load the template from the templates/ subdirectory of this package.

Literature Provider Configuration

CLI, Codex, and Claude Code installs can configure external literature providers with qiongli provider setup and audit them with qiongli provider doctor.
In bundled MCP installs, do not expect the client MCP settings UI to inject provider keys into the plugin-bundled MCP server. Use qiongli_config_status to find the shared provider config path, then use qiongli_configure_provider to open a local browser setup page. Use qiongli_save_provider_config only for explicit scripted writes.
Keep provider secrets out of .mcp.json, plugin manifests, release ZIPs, and research artifacts. The bundled provider server reads the shared provider config or explicit provider environment variables at runtime.
In Codex plugin sessions, before declaring strategy_only for literature search, literature review, paper screening, citation snowballing, or evidence synthesis, attempt the visible qiongli_literature_status MCP tool. If it returns capability_mode: provider_connected, proceed with provider-backed literature workflow. If the tool is not visible in the session, state that Qiongli MCP tools are not visible and recommend restarting Codex or installing the explicit standalone MCP fallback with qiongli install --target codex --parts mcp. If provider preflight is unavailable or non-provider-connected but platform-native search is usable, write qiongli_search_plan with search_execution_mode: native_only.
Literature workflows must create or update qiongli_search_plan after the qiongli_literature_status preflight and before search execution. The plan records search_execution_mode as exactly one of hybrid_search, provider_connected, native_only, or strategy_only; it separately records provider_capability_mode as provider_connected or strategy_only to show whether the MCP/provider layer has configured academic provider access.
Do not use qiongli_collect_evidence to judge built-in literature provider configuration. That tool is a filesystem/builtin/external-command evidence adapter; direct provider names such as openalex require a separate RESEARCH_MCP_OPENALEX_CMD. Use qiongli_literature_status, qiongli_config_status, qiongli_test_provider, and qiongli_literature_search to judge OpenAlex, Semantic Scholar, Crossref, PubMed, and arXiv provider availability.
Use hybrid_search when provider calls and platform-native search are both available and useful. Use provider_connected when the search run is provider-only. Use native_only when the active agent has platform native search but no provider-connected MCP. Use strategy_only only when neither provider MCP nor platform-native search is available and the workflow can only draft a search strategy or work from supplied corpus.
MCP servers must not call Codex or Claude native search directly. The active agent executes native_search_queries from qiongli_search_plan; the MCP provider layer only performs provider calls and returns provider records. Do not hide native search behind a provider adapter.
Preserve distinct provenance labels in search_log.md, search_results.csv, and diagnostics: provider records use labels such as mcp:openalex, mcp:semantic_scholar, mcp:crossref, mcp:pubmed, and mcp:arxiv; platform-native records use native:codex_web_search or native:claude_web_search; user-supplied files, notes, bibliographies, or pasted citations use user_corpus.
Treat provider_connected as the only mode where configured external academic provider credentials are available to the local runtime.
Treat strategy_only as a constrained mode: draft the search strategy or use user-supplied corpus, record the limitation, and do not claim review-grade external provider or native-search coverage.
Claude Desktop/Web focused ZIPs are skill-only packages kept within the 180-file upload budget. They contain workflows/prompts/templates, store no secrets, and cannot execute OpenAlex, Semantic Scholar, Crossref, PubMed, or arXiv API calls by themselves.
For a manual Desktop install, upload the qiongli-claude-desktop-skill-*.zip first, then add a manual MCP install when provider calls or local orchestration are required. The skill ZIP supplies agent instructions, workflows/prompts/templates, and subject overlays; MCP supplies tool calls.
Desktop/Web users need the Qiongli Literature Provider .mcpb (qiongli-literature-provider.mcpb) or another configured provider MCP before claiming provider_connected literature search. The MCPB is the separate local Claude Desktop provider for OpenAlex, Semantic Scholar, Crossref, PubMed, and arXiv configuration/search. arXiv is enabled without credentials. Platform-native search alone is native_only, not provider_connected; if no provider MCP/MCPB and no platform-native search is available, record the run as strategy_only.
The literature MCPB provides literature MCP tools only. It does not launch orchestrator agents. To expose the full agent runtime through MCP, manually install the full CLI MCP server with qiongli mcp serve --transport stdio; clients can then call qiongli_orchestrator_route, qiongli_task_plan, and qiongli_task_run after the local CLI runtime and model CLIs are configured. qiongli_task_run remains preview-first unless the caller sends JSON boolean run_agents: true.

Skill Loading Strategy

Three-tier loading for token efficiency. All paths are relative to this skill package directory:

Quick lookup (~6KB): Use skills-summary.md — skill names + one-line descriptions per stage. Use this to identify which skill to invoke.
Default reference (~19KB): Use skills-core.md — consolidated process descriptions, templates, and output formats. Use this when executing a skill.
Full specification: Load skills/[stage]/[skill-name].md — detailed edge cases, error recovery, quality bars, and verbose templates. Use this only when the core reference is insufficient.

Bundled Assets

This package includes the following subdirectories:

| Directory | Contents | |-----------|----------| | workflows/ | 17 workflow definitions (slash commands) | | references/ | Stage playbooks + workflow contract | | skills/ | 72 detailed skill spec files across 13 stage directories | | skills-summary.md | Quick-reference skill index (~3KB) | | skills-core.md | Consolidated skill reference (~19KB) | | templates/ | 50+ output templates for manuscripts, submissions, ethics, evidence, and handoffs | | standards/ | Canonical contract YAML + capability map + agent profiles | | roles/ | 10 agent role definitions for orchestrator execution | | venue-profiles/ | Venue expectation profiles for CHI, ACL, NeurIPS, Nature, JAMA, and AOM |

References

Task model + outputs: references/workflow-contract.md
Full-Cycle lifecycle gate contract: references/full-cycle-workflow-harness.md
Platform routing map: references/platform-routing.md
Coverage matrix: references/coverage-matrix.md
Academic output rubric: references/academic-output-rubric.md
Evidence ledger contract: references/evidence-ledger-contract.md
Citation risk policy: references/citation-risk-policy.md
Stage handoff contract: references/stage-handoff-contract.md
Method diagnostic contract: references/method-diagnostic-contract.md
Stage playbooks:
- references/stage-A-framing.md (tasks A1–A5)
- references/stage-B-literature.md (tasks B1–B6)
- references/stage-C-design.md (tasks C1–C5)
- references/stage-D-ethics.md (tasks D1–D3)
- references/stage-E-synthesis.md (tasks E1–E5)
- references/stage-F-writing.md (tasks F1–F6)
- references/stage-G-compliance.md (tasks G1–G4)
- references/stage-J-proofread.md (tasks J1–J4)
- references/stage-H-submission.md (tasks H1–H5)
- references/stage-I-code.md (tasks I1–I9)
- references/stage-K-presentation.md (tasks K1–K4)