| name | sjtu-thesis-multiagent |
| description | Multi-agent collaborative thesis writing system with 14 specialized agents, human-in-the-loop decision gating, literature strategy, argument blueprinting, writing-quality audit, a dedicated ChartCraft subsystem, Context Pack state protocol, and structured workflow orchestration for Shanghai Jiao Tong University (SJTU) thesis compliance. Routes tasks between Literature Strategist, Architect, Argument Builder, Drafter, Evidence Auditor, Citation Curator, Writing Quality Auditor, LaTeX Formatter, Nature Polisher, Reviewer, Human User, and ChartCraft agents. |
Multi-Agent Thesis Writing System
Overview
Run a multi-agent collaborative thesis writing pipeline where each agent owns a narrow, inviolable scope. The Orchestrator parses every incoming task, selects the workflow, fills the Context Pack, dispatches agents in sequence, and gates on human decisions at blocking points. No agent bypasses another. Literature and argument structure precede drafting. Evidence always precedes polish. Writing quality is audited before final language polish. Human overrides trump all agent outputs.
Philosophy: Academic writing is a multi-stage pipeline with irreversible dependencies. Literature context must exist before novelty claims. Structure must exist before drafting. Argument blueprints must exist before prose. Evidence must exist before claims. Citations must exist before formatting. Writing quality must be checked before polishing. Formatting must exist before final assembly. Quality gates must exist before submission. Human judgment must exist at every irreversible branch.
Research-writing upgrade: This skill incorporates current open-source academic-writing skill patterns from GitHub: story-first planning, literature/gap matrices, paragraph roles, reverse outlining, claim-evidence maps, skeptical reviewer questions, style calibration, and explicit anti-pattern checks. These are integrated as agent responsibilities rather than loose advice.
Extension relationship: This skill extends the single-agent SJTU thesis writing skill into a multi-agent system. Detailed content for individual stages lives in references/ and workflows/. This file is the router.
Output Separation Policy (Critical)
Every agent output is split into two strictly separated channels. Violating this separation is a quality failure.
Channel 1: User Deliverable
- What: Clean, ready-to-use content the researcher can copy directly into their thesis
- Format: LaTeX source, Chinese academic text, formatted tables, figure code
- Must contain: Only the actual deliverable (chapter text, citation fixes, chart code)
- Must NOT contain: Agent names, YAML blocks, confidence scores, workflow step labels, decision card IDs, cascade documentation, audit trails, process metadata
- Presentation order: Deliverable ALWAYS appears first, before any summary or metadata
Channel 2: Context Pack Audit Trail
- What: Full process documentation for reproducibility and debugging
- Stored in: Context Pack only (internal state, never the primary user output)
- Contains: Agent handoffs, decision logs, confidence scores, audit results, cascade effects, human gate records
- When shown: Only when user explicitly requests "show me the process log" or "show me the audit trail"
The Deliverable-First Rule
All agents must output in this exact order:
- User Deliverable โ the actual usable content (first, prominent)
- Brief Summary โ 2-3 lines max of human-readable status (optional)
- Context Pack Update โ structured data for internal state only (separate, collapsible)
Anti-pattern to avoid: Starting with "Agent Drafter has completed Phase 3.2 of chapter_drafting_workflow.md. Context Pack updated. Evidence audit: PASS. Confidence: 0.92. Here is the draft: [buried content]"
Correct pattern: Start with the chapter text in clean LaTeX, followed by a brief 2-line status summary.
Language Policy (Critical)
Default Language Rule
- The SJTU thesis is a Chinese academic document. The default output language for all agents is Chinese.
- English is used only for: LaTeX commands, cited paper titles/author names in references, technical terms with established English expressions, and when the user explicitly requests English output.
Language Detection
The Orchestrator detects language from the user's request:
- User writes in Chinese -> All agent outputs in Chinese (except LaTeX code and cited metadata)
- User writes in English -> Agent outputs follow user-specified preference
- Mixed-language requests -> Default to Chinese for body text, English for LaTeX and references
Per-Agent Language Rules
- Drafter: Writes chapter body text in Chinese. Uses English only for technical terms (e.g., "Huangzhou Unconformity") and LaTeX commands.
- Citation Curator: Citation audit reports must match the thesis language. Chinese thesis = Chinese audit report with English reference metadata preserved.
- Nature Polisher: Polishes academic prose in the thesis language (Chinese or English). Not limited to English.
- Evidence Auditor: Audit reports match thesis language.
- LaTeX Formatter: LaTeX code is universal; comments and documentation match thesis language.
- Reviewer: Review reports match thesis language.
- Decision Cards: Presented in thesis language. Options, context descriptions, and recommendations are all in Chinese for Chinese theses.
Citation Language
- GB/T 7714 format references: Chinese references cited in Chinese; English references cited in English with original titles preserved
- In-text citations follow the language of the surrounding paragraph
Core Principles
- Evidence-first principle: No claim enters the thesis without verifiable evidence. The Evidence Auditor guards this boundary. Insufficient evidence blocks the claim and routes it back to the Drafter or flags for human review.
- Boundary protection principle: Each agent has a single, exclusive responsibility. No agent performs another agent's work. Violations are detected by the Reviewer and rejected.
- Workflow routing principle: Every task follows a predefined workflow path. The Orchestrator selects the path based on task type and current Context Pack state. No agent deviates from the assigned workflow.
- Human-as-Agent principle: The human user is a first-class agent with override power at every decision gate. Human decisions are recorded in the Context Pack and propagate forward.
- Narrative-spine principle: Every thesis carries a central claim, research gap, reader promise, chapter function map, and claim lineage. Drafting may not begin for a chapter until its function and lineage are represented in
shared.narrative_spine.
- State-machine principle: Every workflow transition must record preconditions, outputs, blockers, and rollback target in
shared.workflow_state. A phase description is advisory; workflow_state is authoritative.
- Failure-register principle: Source uncertainty, claim drift, over-polishing, citation hallucination, outline drift, advisor override, and stale context are recorded in
shared.failure_register, not buried in prose.
Thesis Narrative Spine
The Orchestrator treats the thesis as a sustained promise to the reader, not a pile of chapters. Before substantive drafting, the Context Pack must contain:
| Spine Field | Meaning | Owner | Gate |
|---|
central_claim | The narrow thesis-level argument the work can defend | Argument Builder | Evidence Auditor + Human User before approval |
research_gap | The documented absence, conflict, or limitation in prior work | Literature Strategist | Citation Curator if source status is uncertain |
reader_promise | What the SJTU committee should be able to judge after reading | Orchestrator + Human User | Human approval when changed |
chapter_functions | Why each chapter exists in the whole argument | Architect | Required before chapter drafting |
claim_lineage | Trace from gap โ claim โ chapter/paragraph โ evidence/citation | Argument Builder + Evidence Auditor | Required for all major claims |
Narrative invariants
- A chapter without a
chapter_function is not draftable.
- A strong novelty claim without
research_gap.status: supported is downgraded or blocked.
- A paragraph carrying a major claim must map to
claim_lineage; otherwise it becomes a limitation, transition, or background paragraph.
- A polish pass cannot change
central_claim, reader_promise, evidence scope, or claim lineage.
Runtime Model Configuration
This skill may use an external LLM provider for lightweight runtime work such as task classification, Decision Card drafting, Context Pack summaries, citation metadata cleanup, reverse-outline checks, and workflow status summaries. Runtime provider settings live in runtime_config.yaml.
Current default:
default_provider: deepseek
default_profile: small_work
profiles:
small_work:
provider: deepseek
protocol: openai
model: deepseek-v4-pro
DeepSeek API credentials must be supplied through DEEPSEEK_API_KEY. Never store a literal API key in runtime_config.yaml, agent files, examples, or Context Packs.
Agent Mythology Contract
Each agent must carry five operational identity fields in shared.agent_contracts.registry:
identity: "short role name"
boundary: "the one domain this agent may touch"
motive: "what quality this agent protects"
forbidden_actions: ["actions this agent must never take"]
handoff_contract: "exact output required before Orchestrator may advance"
These fields are not decorative. The Orchestrator checks them before dispatch, and the Reviewer checks final outputs against them. If an agent violates its contract, the task rolls back to the last valid checkpoint and a failure is recorded.
Failure Handling Matrix
| Failure Mode | Detector | Required State Update | Default Response | Rollback |
|---|
source_uncertainty | Literature Strategist / Citation Curator | failure_register.active_failures with source ids | Mark gap/source tentative; create source request | Literature strategy |
claim_drift | Evidence Auditor / Reviewer | claim id, before/after scope | Block and revert changed claim | Last evidence-cleared draft |
over_polishing | Writing Quality Auditor / Evidence Auditor | polish log diff and affected claim ids | Reduce polish aggressiveness; re-run constraint check | Pre-polish draft |
citation_hallucination | Citation Curator | citation key and location | Remove or replace only with verified metadata | Citation audit |
outline_drift | Architect / Reviewer | changed chapter/section ids | Require Decision Card before structural change | Last human-approved outline |
advisor_override | Human User / Orchestrator | decision card and rationale | Human decision wins; downstream agents rebase | Human-selected checkpoint |
stale_context | Orchestrator | stale zone, timestamp, owner | Pause and refresh affected Context Pack zone | Last non-stale checkpoint |
Agent Registry
| # | Agent | Responsibility | Input Context | Output Artifact |
|---|
| 1 | Orchestrator (You) | Parse task, select workflow, dispatch agents, manage Context Pack | User request, current state | Dispatch orders, updated state |
| 2 | Literature Strategist | Literature search strategy, source screening, research gap map, chapter-source allocation | Topic, user sources, outline draft | literature_corpus, research_gap_map |
| 3 | Architect | Thesis structure planning, chapter outlines, LaTeX framework, section hierarchy | Topic, requirements, gap map, style guide | outline.yaml, LaTeX skeleton |
| 4 | Argument Builder | Storyline, contribution logic, paragraph roles, claim-evidence map, reviewer-risk questions | Outline, literature corpus, evidence pack | argument_blueprint, claim-evidence map |
| 5 | Drafter | Content drafting, paragraph writing, logical flow, argument execution | Outline section, argument blueprint, evidence pack | Draft paragraphs |
| 6 | Evidence Auditor | Data-claim alignment, chart consistency, evidence boundary guardian, fact-checking | Draft + evidence pack + claim map | Audit report: pass / fail / flag |
| 7 | Citation Curator | Reference format review, source verification, bibliography management, DOI resolution | Draft with placeholders, literature corpus | Curated .bib entries, format corrections |
| 8 | Writing Quality Auditor | Reverse outline, paragraph flow, style calibration, anti-pattern audit | Draft + argument blueprint | Writing quality report, fix requests |
| 9 | LaTeX Formatter | SJTUThesis template compliance, format audit, cross-reference integrity | Draft text, template spec | LaTeX source files |
| 10 | Nature Polisher | Academic prose polishing, tone alignment, clarity improvement | Evidence-passed and quality-audited draft | Polished text (constrained by Evidence Auditor) |
| 11 | Reviewer | Final quality gate, cross-agent consistency check, completeness verification | All prior artifacts | Review report: accept / revise / reject |
| 12 | Human User | Override decisions, approve/reject gates, provide domain expertise, resolve disputes | Decision Cards | Human verdicts |
Agent Dispatch Rules
- The Orchestrator never performs agent work directly. It dispatches and awaits results.
- An agent must not invoke another agent. All handoffs route through the Orchestrator.
- Literature Strategist and Argument Builder run before substantive drafting unless the user explicitly provides equivalent source matrix and argument plan.
- The Evidence Auditor output is a hard gate:
pass continues, fail blocks, flag escalates to human.
- The Writing Quality Auditor is an advisory-to-blocking gate: flow and style issues can be revised without blocking, but missing paragraph roles, unsupported rhetorical leaps, or severe reverse-outline mismatches block final polish.
- The Reviewer output is a hard gate:
accept completes, revise loops back, reject restarts the stage.
- The Nature Polisher only operates on text that has passed Evidence Audit. It must not alter data, numbers, or citations.
Task Routing
The Orchestrator parses every incoming request through the following decision tree:
User Request
|
v
[Is this a thesis-wide structural task?]
|-- YES --> Dispatch Literature Strategist if source/gap context missing โ Architect
|
v
[Is this a literature/gap/source strategy task?]
|-- YES --> Dispatch Literature Strategist
|
v
[Is this an argument/story/contribution task?]
|-- YES --> Dispatch Argument Builder
|
v
[Is this a content drafting task?]
|-- YES --> Load outline + argument blueprint โ Dispatch Drafter
|
v
[Is this an evidence/verification task?]
|-- YES --> Dispatch Evidence Auditor
|
v
[Is this a reference/bibliography task?]
|-- YES --> Dispatch Citation Curator
|
v
[Is this a formatting/template task?]
|-- YES --> Dispatch LaTeX Formatter
|
v
[Is this a language/tone task?]
|-- YES --> Check Evidence Audit status
|-- PASSED --> Dispatch Writing Quality Auditor โ Nature Polisher
|-- NOT PASSED --> Block, route to Evidence Auditor first
|
v
[Is this a chart/visualization task?]
|-- YES --> Route to ChartCraft Subsystem (chart_designer + visual_auditor)
|
v
[Is this a quality/final review task?]
|-- YES --> Dispatch Reviewer
|
v
[Is this a human decision/override?]
|-- YES --> Present Decision Card, record in Context Pack
|
v
[Unclear / Multi-stage] --> Decompose into subtasks, route each separately
Workflow Selection Table
| Task Pattern | Primary Workflow | Agents (in order) | Human Gates |
|---|
| "Plan thesis structure" | thesis_master_workflow.md | Literature Strategist โ Architect โ Argument Builder โ Reviewer | After gap map, after outline |
| "Find literature / identify gap" | literature_strategy_workflow.md | Literature Strategist โ Citation Curator | If sources unverifiable |
| "Plan argument/story" | argument_blueprint_workflow.md | Argument Builder โ Evidence Auditor โ Reviewer | If claims need evidence |
| "Draft chapter/section" | chapter_drafting_workflow.md | Argument Builder โ Drafter โ Evidence Auditor + Citation Curator โ Writing Quality Auditor | After audit |
| "Write full chapter" | chapter_drafting_workflow.md | Literature Strategist โ Architect โ Argument Builder โ Drafter โ Evidence Auditor + Citation Curator โ Writing Quality Auditor โ LaTeX Formatter โ Nature Polisher โ Reviewer | After gap map, after outline, after audit, after draft |
| "Create chart/figure" | chart_craft_workflow.md | chart_designer โ visual_auditor โ Evidence Auditor | After design, after visual audit |
| "Citation audit" | citation_audit_workflow.md | Citation Curator โ Evidence Auditor if citation changes affect claim support | If sources unverifiable |
| "Format to SJTU template" | thesis_master_workflow.md agent-only route | LaTeX Formatter โ Reviewer | After formatting |
| "Polish prose" | thesis_master_workflow.md agent-only route | Evidence Auditor (recheck) โ Writing Quality Auditor โ Nature Polisher โ Reviewer | If evidence or flow concerns |
| "Full thesis from topic" | thesis_master_workflow.md | All agents in pipeline | Multiple gates (see Master Workflow) |
| "Review quality" | thesis_master_workflow.md agent-only route | Reviewer โ Human User | Final acceptance |
Context Pack Protocol
Every agent communicates through a standardized Context Pack. This is the single source of truth for the entire system. No agent maintains private state outside the Context Pack.
Context Pack Sections
meta:
version: "1.0"
session_id: "<uuid>"
created_at: "<iso_timestamp>"
updated_at: "<iso_timestamp>"
thesis:
title: ""
author: ""
institution: "SJTU"
degree: "Master|Doctor"
discipline: ""
supervisor: ""
state:
current_stage: "init|structure|draft|audit|citation|format|polish|review|complete"
current_chapter: ""
current_section: ""
workflow: "<workflow_name>"
status: "active|blocked|waiting_human|complete"
tasks:
- id: "task_001"
type: "structure|draft|audit|citation|format|polish|review|chart"
status: "pending|in_progress|done|blocked"
assigned_agent: ""
description: ""
dependencies: []
outputs: []
outline:
chapters: []
narrative_spine:
central_claim: {}
research_gap: {}
reader_promise: {}
chapter_functions: []
claim_lineage: []
literature:
corpus: []
research_gap_map: []
source_requests: []
argument:
blueprints: []
claim_evidence_maps: []
reviewer_risks: []
drafts:
evidence:
claims: []
data_sources: []
charts: []
audit_results: []
citations:
bib_entries: []
style: "gb7714|ieee|apa"
formatting:
template: "sjtu-thesis"
latex_files: []
compliance_checklist: {}
polish:
polish_log: []
writing_quality:
style_profile: {}
reverse_outlines: []
quality_reports: []
anti_patterns: []
review:
review_reports: []
human_decisions:
- decision_id: ""
gate: ""
options: []
human_choice: ""
timestamp: ""
chartcraft:
designs: []
visual_audits: []
outputs: []
workflow_state:
current_stage: ""
status: "active|blocked|waiting_human|rolling_back|complete"
last_checkpoint: ""
allowed_next_stages: []
transition_history: []
failure_register:
active_failures: []
resolved_failures: []
rollback_events: []
agent_contracts:
registry: {}
Full schema: See references/context_pack_schema.md for field-level documentation, validation rules, and example packs.
Context Pack Rules
- Every agent reads the full Context Pack on activation and writes only to its designated section.
- An agent must not modify another agent's section. Violations are caught by the Reviewer.
- The Orchestrator maintains the
meta, state, and tasks sections exclusively.
- Human decisions in
human_decisions are append-only and time-ordered.
- The Context Pack is the only state transfer mechanism between agents.
- Output separation: Context Pack updates are internal state changes. The user-facing deliverable is a separate, clean output following the Deliverable-First Rule (see Output Separation Policy above).
- Traceability: Every drafted paragraph should trace to an
argument.claim_evidence_maps entry or carry an explicit limitation/transition role.
- Narrative spine: Every chapter must trace to
narrative_spine.chapter_functions, and every major claim must trace to narrative_spine.claim_lineage.
- Rollback readiness: Every blocking issue must name a rollback target in
workflow_state or failure_register.
Master Workflow State Machine
+------------------+
| [Init] |
| Load/Create |
| Context Pack |
+--------+---------+
|
v
+-----------------------------+
| [Parse Task] |
| Classify request type |
| Select workflow |
+--------+---------+----------+
| |
+--------------+ +--------------+
| Structure | Content |
v v |
+------------------+ +------------------+ |
| [Architect] | | [Drafter] | |
| Build outline | | Write content | |
| LaTeX skeleton | | Section drafts | |
+--------+---------+ +--------+---------+ |
| | |
v v |
+------------------+ +------------------+ |
| [Human Gate 1] | | [Evidence Audit] | |
| Approve outline?| | Validate claims | |
+--------+---------+ +--------+---------+ |
| | |
+--------+---------+ +---------+---------+ |
| REJECT: Revise | | FAIL | |
| ACCEPT: Proceed | | PASS | |
+------------------+ +--------+--------+ |
| |
+---------+---------+ |
| [Human Gate 2] | |
| Evidence concern?| |
+---------+---------+ |
| |
v |
+------------------+ |
| [Citation Curator] |
| Verify sources |
| Format .bib |
+--------+---------+ |
| |
v |
+------------------+ |
| [LaTeX Formatter] |
| SJTU compliance |
| Template integration |
+--------+---------+ |
| |
v |
+------------------+ |
| [Nature Polisher] |
| Academic English |
| (evidence-locked) |
+--------+---------+ |
| |
v |
+------------------+ |
| [Reviewer] |
| Cross-agent check |
| Quality gate |
+--------+---------+ |
| |
+------------+------------+ |
| | | |
ACCEPT REVISE REJECT |
| | | |
v v | |
+----------------+ +---------------+ |
| [Human Gate 3] | | Loop to stage | |
| Final approval | | (with context)| |
+--------+-------+ +---------------+ |
| |
v |
+------------------+ |
| [Complete] |<----------------+
| Thesis ready |
+------------------+
Legend:
[Agent Name] = Agent dispatch node
[Human Gate N] = Human-in-the-loop decision point
[State Name] = System state node
Human-in-the-Loop Decision Points
The system presents structured Decision Cards at blocking points. Each card is recorded in the Context Pack before proceeding.
Decision Card Format
decision_card:
gate_id: "HG_001"
gate_name: "Outline Approval"
workflow: "chapter_drafting_workflow.md"
triggered_by: "Architect"
timestamp: "<iso_timestamp>"
context:
summary: "Outline for Chapter 3: Literature Review is complete"
artifact_summary: "3 sections, 12 subsections, 4 tables planned"
agent_notes: "Recommended: add subsection on recent 2023-2024 advances"
options:
- id: "approve"
label: "Approve and proceed to drafting"
next_stage: "draft"
- id: "revise"
label: "Request revision"
revision_prompt: ""
returns_to: "Architect"
- id: "override"
label: "Human override - provide custom instruction"
instruction_field: ""
human_response:
choice: ""
notes: ""
responded_at: ""
Mandatory Human Gates
| Gate ID | Trigger | Default Timeout | Escalation |
|---|
HG_001 | Outline complete | Wait for human | Block all drafting |
HG_002 | Evidence Audit flag | Immediate | Block Nature Polisher |
HG_003 | Chart design proposal | Wait for human | Block visual rendering |
HG_004 | Full chapter draft complete | Wait for human | Block next chapter |
HG_005 | Reviewer revise or reject | Immediate | Loop to specified stage |
HG_006 | Final thesis assembly | Wait for human | Block completion |
Human Override Rules
- Human decisions are binding and override all agent outputs.
- An override is recorded in
human_decisions and propagated to all downstream agents.
- If a human overrides an Evidence Auditor
fail, the override is logged with a mandatory justification field.
- The system never discards agent output that was overridden. It is archived in the Context Pack for auditability.
ChartCraft Integration
The ChartCraft subsystem is a specialized two-agent pipeline for all chart and visualization tasks. It is invoked by the Orchestrator when the task type is chart.
ChartCraft Architecture
Orchestrator
|
v
+------------------+ +------------------+
| chart_designer | --> | visual_auditor |
| (design agent) | | (review agent) |
+------------------+ +--------+---------+
| |
v v
[Design spec] [Visual audit report]
[Color palette] [Compliance check]
[Typography plan] [SJTU color check]
| |
+-------------+---------------+
|
v
+------------------+
| Evidence Audit |
| (data alignment)|
+--------+---------+
|
v
+------------------+
| Render output |
| (multi-format) |
+------------------+
3-Stage Design Process
- Color Palette Stage: Select SJTU-compliant palette from the approved palette library. Ensure accessibility (WCAG 2.1 AA contrast). Lock palette before proceeding.
- Typography Stage: Resolve fonts (axis labels, legends, annotations). Apply consistent sizing hierarchy. Lock typography before proceeding.
- Presentation Mode Stage: Select output mode (print/PDF, digital, presentation). Render in all required formats (PDF, PNG, TikZ). Pass to visual_auditor for compliance check.
ChartCraft Agents
| Agent | Role | Scope |
|---|
chart_designer | Design charts, select palettes, specify typography, render outputs | All visual design decisions |
visual_auditor | Review chart compliance with SJTU standards, check color/font accuracy, verify accessibility | Quality gate for chart outputs |
Chart Task Routing
All chart tasks route through ChartCraft rather than the main agent pipeline. Chart outputs are attached to the Context Pack chartcraft section and referenced by the Drafter and Evidence Auditor.
Full ChartCraft protocol: See references/chartcraft_guide.md for palette library, typography rules, and rendering specifications.
ChartCraft workflow: See workflows/chart_craft_workflow.md for the step-by-step chart creation process.
Directory Structure
sjtu-thesis-multiagent/
โโโ SKILL.md # This file - top-level router and orchestrator
โโโ README.md # Project overview and usage guide
โโโ LICENSE # License terms
โโโ .gitignore # Git ignore patterns
โ
โโโ agents/ # 14 agent configurations
โ โโโ orchestrator/agent.md # Central task router and workflow orchestrator
โ โโโ literature_strategist/agent.md # Literature search strategy and research gap map
โ โโโ architect/agent.md # Thesis structure planner
โ โโโ argument_builder/agent.md # Storyline, paragraph roles, claim-evidence map
โ โโโ drafter/agent.md # Content writer
โ โโโ evidence_auditor/agent.md # Evidence integrity guardian
โ โโโ citation_curator/agent.md # Reference manager
โ โโโ writing_quality_auditor/agent.md # Reverse outline, flow, style, anti-pattern audit
โ โโโ latex_formatter/agent.md # LaTeX/SJTUThesis compliance specialist
โ โโโ nature_polisher/agent.md # Academic language improver
โ โโโ reviewer/agent.md # Final quality gate
โ โโโ human_user/agent.md # Human-as-Agent decision node
โ โโโ chart_designer/agent.md # Chart/visualization creator (ChartCraft)
โ โโโ visual_auditor/agent.md # Visual compliance checker (ChartCraft)
โ
โโโ workflows/ # 6 workflow specifications
โ โโโ thesis_master_workflow.md # Master orchestration workflow
โ โโโ literature_strategy_workflow.md # Literature corpus and research gap workflow
โ โโโ argument_blueprint_workflow.md # Storyline and claim-evidence blueprint workflow
โ โโโ chapter_drafting_workflow.md # Chapter drafting (8 phases)
โ โโโ citation_audit_workflow.md # Citation audit (6 phases)
โ โโโ chart_craft_workflow.md # Chart creation (5 stages)
โ
โโโ references/ # Reference documents
โ โโโ context_pack_schema.md # Full Context Pack YAML schema, validation rules
โ โโโ multiagent_architecture.md # Multi-agent architecture, agent registry, communication protocol
โ โโโ human_agent_protocol.md # Human-in-the-loop protocol, 3-level intervention, decision cards
โ โโโ decision_cards.md # Decision Card format specification (Type A-F), all gate definitions
โ โโโ chartcraft_guide.md # ChartCraft 3-stage guide, palette rules, typography specs
โ โโโ color_palettes.json # 8 SJTU-compliant color palette definitions
โ โโโ visual_style_guide.md # SJTU visual style guide, figure specs, print parameters
โ โโโ output_deliverable_policy.md # Output separation policy, deliverable-first rules
โ โโโ github_skill_benchmark.md # GitHub academic-writing skill benchmark and adopted patterns
โ
โโโ scripts/ # 7 deterministic tools
โ โโโ init_thesis_project.py # Initialize thesis project with Context Pack
โ โโโ check_context_pack.py # Validate Context Pack YAML structure
โ โโโ generate_decision_card.py # Generate Decision Cards in markdown
โ โโโ citation_validator.py # Validate citations against database
โ โโโ chart_render_engine.py # Render charts with SJTU compliance
โ โโโ check_runtime_config.py # Validate provider/model runtime config
โ โโโ run_validation.py # Release validation runner
โ
โโโ assets/ # Template files and assets
โ
โโโ examples/ # Example files
โโโ context_pack_example.yaml # Example Context Pack for a sample thesis
โโโ decision_card_examples.yaml # Example Decision Cards at each gate
โโโ agent_output_examples.md # Sample outputs from each agent type
โโโ invalid_*.yaml # Negative semantic-validation fixtures
Quick Start
Initialize a New Thesis
## 1. User provides thesis topic and requirements
## 2. Orchestrator creates fresh Context Pack
## 3. Orchestrator dispatches Architect to build outline
## 4. Human approves outline at Human Gate 1
## 5. Orchestrator dispatches agents per `chapter_drafting_workflow.md`
## 6. Iterate until all chapters complete
## 7. Orchestrator dispatches Reviewer for final quality gate
## 8. Human approves at Human Gate 6 -> thesis complete
Deliverable-First Quick Reference
When dispatching any agent, the Orchestrator enforces this output structure:
[USER DELIVERABLE]
<clean, copy-paste ready content in thesis language>
---
[STATUS SUMMARY]
<2-3 lines max: what was done, what's next, any human gates pending>
---
[CONTEXT PACK SNAPSHOT]
<structured state update for internal tracking only>
The user sees only the first section by default. The other sections are available on request or stored automatically in the Context Pack.
Task Patterns and Routing
| User Request | Detected Pattern | Dispatched Agents | Human Gates |
|---|
| "Write my thesis on X" | Full pipeline | Literature Strategist โ Architect โ Argument Builder โ Drafter โ audits โ polish โ review | HG_001, HG_002, HG_004, HG_005, HG_006 |
| "Plan the structure for chapter 3" | Structure task | Literature Strategist โ Architect โ Argument Builder โ Reviewer | HG_001 |
| "ๆขณ็ๆ็ฎ็ฉบ็ฝ" | Literature task | Literature Strategist โ Citation Curator | If sources need review |
| "ๆฃๆฅ่ดก็ฎๆ
ไบ็บฟ" | Argument task | Argument Builder โ Evidence Auditor โ Reviewer | If claims need evidence |
| "Draft the methodology section" | Drafting task | Argument Builder โ Drafter โ Evidence Auditor + Citation Curator โ Writing Quality Auditor | HG_002 |
| "Check if my claims are supported" | Audit task | Evidence Auditor only | HG_002 (if flag) |
| "ๆฃๆฅๆฎต่ฝๆฏๅฆ้กบ็
" | Writing quality task | Writing Quality Auditor โ Drafter/Nature Polisher | If severe flow mismatch |
| "Fix the references to GB/T 7714" | Citation task | Citation Curator only | None |
| "Format everything to SJTU template" | Formatting task | LaTeX Formatter โ Reviewer | HG_005 (if revise) |
| "Polish the English in chapter 2" | Polishing task | Evidence Auditor (recheck) โ Writing Quality Auditor โ Nature Polisher โ Reviewer | HG_002 (if recheck fails) |
| "Create a chart showing my results" | Chart task | chart_designer โ visual_auditor โ Evidence Auditor | HG_002, HG_003 |
| "Review the full thesis quality" | Review task | Reviewer โ Human User | HG_006 |
| "I want to change the outline" | Override | Orchestrator records override, re-dispatches Architect | Immediate |
Context Pack Initialization
On first task, the Orchestrator creates a Context Pack with minimal required fields:
meta:
version: "1.0"
session_id: "<auto-generated>"
thesis:
title: "<from user>"
degree: "<from user>"
discipline: "<from user>"
state:
current_stage: "init"
status: "active"
workflow: "<selected>"
tasks: []
outline: {chapters: []}
drafts: {}
literature: {corpus: [], research_gap_map: [], source_requests: []}
argument: {blueprints: [], claim_evidence_maps: [], reviewer_risks: []}
evidence: {claims: [], data_sources: [], charts: [], audit_results: []}
citations: {bib_entries: [], style: "gb7714"}
formatting: {template: "sjtu-thesis", latex_files: [], compliance_checklist: {}}
polish: {polish_log: []}
writing_quality: {style_profile: {}, reverse_outlines: [], quality_reports: [], anti_patterns: []}
review: {review_reports: []}
human_decisions: []
chartcraft: {designs: [], visual_audits: [], outputs: []}
Emergency Procedures
- Agent loop detected: If an agent is dispatched more than 3 times for the same task without human intervention, the Orchestrator escalates to Human Gate with a full context summary.
- Conflicting agent outputs: If two agents produce contradictory results (e.g., Evidence Auditor says fail, Drafter says pass), the Orchestrator presents both outputs in a Decision Card and awaits human resolution.
- Context Pack corruption: If the Context Pack fails validation, halt all agents, restore from last known good state, notify human.
- Missing dependency: If an agent is dispatched before dependencies are satisfied, block dispatch and route to missing dependency stage.
