Imported from Zijie-Tian/omp-academic-writing-agents (AGENTS.md). Install upstream with npx skills add Zijie-Tian/omp-academic-writing-agents. Copyright stays with the author.

Repository Guidelines

Project Overview

This repository is a standalone OMP-native package for academic writing assistance. It is not an application or compiled library. The package installs:

• /academic slash command: payload/commands/academic.md
• academic skill and shared writing principles: payload/skills/academic/
• 12 specialist OMP task agents: payload/agents/*.md

The repo intentionally contains only the OMP package; it does not include the Claude Code plugin wrapper.

Architecture & Data Flow

Install-time flow

install.sh is the only executable distribution layer.

1. User runs ./install.sh --scope user|project.
2. Script resolves PAYLOAD_DIR="$SCRIPT_DIR/payload".
3. Scope selects target root:
   • user: $HOME/.omp/agent
   • project: <project>/.omp
4. Script recursively copies exactly three trees:
   • payload/commands/ -> <target>/commands/
   • payload/skills/ -> <target>/skills/
   • payload/agents/ -> <target>/agents/
5. Existing files are skipped unless --force; --dry-run prints planned copies and writes nothing.

OMP runtime flow

1. User invokes /academic <task>.
2. payload/commands/academic.md tells OMP to use skill://academic, pass $ARGUMENTS, and follow the academic orchestrator workflow.
3. payload/skills/academic/SKILL.md loads:
   • skill://academic/academic-writing.md
   • project AGENTS.md
   • optional .claude/CLAUDE.md as compatibility context only
   • project-local .omp/agents/*.md frontmatter when present
4. The orchestrator presents a deployment plan before spawning workers.
5. Specialist task agents run in parallel or staged pipelines.
6. The orchestrator synthesizes findings into Critical / Important / Minor issues, then asks before invoking action agents unless the user explicitly requested edits.

Important OMP task detail: one task batch has one top-level agent. To run different specialists, issue separate task calls in the same assistant step.

Key Directories

• payload/commands/ — OMP slash-command definitions. Currently academic.md.
• payload/skills/academic/ — skill package:
  • SKILL.md: orchestrator, agent roster, workflows, synthesis format, persistence guidance
  • academic-writing.md: canonical 30 academic-writing principles
• payload/agents/ — 12 specialist Markdown task-agent definitions.
• Root:
  • install.sh: installer and only automation script
  • README.md: user-facing install and usage docs
  • LICENSE: MIT license
  • .gitignore: minimal ignores, including .omp-install-test/

No src/, tests/, scripts/, docs/, .github/, package.json, lockfiles, Makefile, or language build config currently exists.

Development Commands

Clone/open package:

git clone https://github.com/Zijie-Tian/omp-academic-writing-agents.git
cd omp-academic-writing-agents

Install globally for all OMP sessions:

./install.sh --scope user

Install into one project:

./install.sh --scope project --project /path/to/paper-repo

Install into current directory as project scope:

./install.sh --scope project

Dry-run checks without writing:

./install.sh --scope user --dry-run
./install.sh --scope project --project /tmp/omp-academic-test --dry-run

Overwrite existing installed files:

./install.sh --scope user --force

Post-install OMP examples:

/academic review main.tex
/academic polish abstract
/academic audit bibliography
/academic prepare for submission

No repository-level build, lint, test, package, or publish command is documented or evidenced.

Code Conventions & Common Patterns

Markdown/frontmatter payloads

• Command files use YAML frontmatter with description, then prompt body with $ARGUMENTS.
• Skill files use YAML frontmatter with name and description.
• Agent files use YAML frontmatter with:
  • name: kebab-case, matching filename
  • description: one-line role summary
  • tools: OMP tool list
• Do not add fixed model: by default. Agents inherit the active/task model. README documents optional model: pi/DOCS after the user configures modelRoles.DOCS.

Agent tool grants

Keep tool grants aligned with role safety:

• Read-only reviewers: [read, glob, grep]
  • consistency-checker
  • logic-reviewer
  • technical-reviewer
  • writing-reviewer
• Web/research agents: [read, glob, grep, web_search]
  • research-analyst
  • brainstormer
  • paper-crawler
• Verification auditors:
  • latex-layout-auditor: [read, glob, grep, bash]
  • bibliography-auditor: [read, glob, grep, bash, web_search]
• Action agents:
  • prose-polisher: [read, glob, grep, edit]
  • section-drafter: [read, glob, grep, edit, write, bash]
  • latex-figure-specialist: [read, glob, grep, edit, write, bash]

Safety patterns

• Preserve review-then-act: reviewers diagnose, orchestrator synthesizes, action agents edit only after explicit user request or approved plan.
• paper-crawler is report-only by default. Do not make it write papers.json or classifications.json unless the user explicitly requests saved files and the installed agent has write permission.
• Installer must not modify ~/.omp/agent/config.yml, enable advisors, or create .review/ files.
• For web fetching in agents, prefer URL reads and web_search; do not reintroduce Claude-only WebFetch wording.
• All agents should consult skill://academic/academic-writing.md and project context such as AGENTS.md.

Academic-writing conventions embedded in payload

The canonical principles are in payload/skills/academic/academic-writing.md. They emphasize:

• claim-first exposition and Goal-Problem-Solution rhythm
• one central nugget per paper
• analytical prose: claim -> evidence -> mechanism -> example -> principle
• calibrated confidence for empirical facts vs hypotheses
• explicit figure/table interpretation and self-sufficient captions
• citation completeness for named models, benchmarks, and datasets
• avoidance of AI-writing tells such as not X, but Y, filler phrases, and repeated formulaic transitions

Important Files

• README.md — install commands, examples, model role note, safety model.
• install.sh — argument parser and installer. Uses set -euo pipefail; supports --scope, --project, --dry-run, --force, and --help.
• .gitignore — ignores .DS_Store, Python bytecode/cache, and .omp-install-test/.
• payload/commands/academic.md — /academic command entrypoint.
• payload/skills/academic/SKILL.md — main orchestrator behavior, agent roster, workflows, synthesis format.
• payload/skills/academic/academic-writing.md — shared 30-principle writing doctrine.
• payload/agents/*.md — distributable specialist task-agent prompts.

Runtime/Tooling Preferences

• Required installer runtime: Bash via #!/usr/bin/env bash.
• Shell utilities used by install.sh: mkdir, cp, find, dirname, pwd, and standard shell parameter expansion.
• OMP is the target runtime. After project-level install, start OMP from the project root so .omp/commands, .omp/skills, and .omp/agents are discoverable.
• Bun, Node, npm, pnpm, yarn, Python package tooling, and compiled build systems are not required or evidenced by repo files.
• Keep this package portable: prefer plain Markdown payloads and Bash installer behavior over introducing dependency-heavy tooling.

Testing & QA

No formal test suite, CI workflow, coverage config, lint config, or package-manager manifest exists.

Use installer-focused smoke checks:

./install.sh --help
./install.sh --scope user --dry-run
./install.sh --scope project --project /tmp/omp-academic-test --dry-run

When writes are allowed, use an isolated project-scope fixture and verify copied paths:

./install.sh --scope project --project .omp-install-test

Expected installed structure:

.omp-install-test/.omp/commands/academic.md
.omp-install-test/.omp/skills/academic/SKILL.md
.omp-install-test/.omp/skills/academic/academic-writing.md
.omp-install-test/.omp/agents/*.md   # 12 files

Then remove .omp-install-test/ after inspection; it is gitignored.

Payload consistency checks for AI assistants:

• agent filename matches frontmatter name
• no stale Claude-only terms: subagent_type, Agent tool, model: opus, WebFetch, /Users/owl/.claude
• slash command and skill references resolve to existing payload files
• action-agent safety text matches actual tool grants
• README command examples use root-level ./install.sh, not ./omp/install.sh