Arc

Agent Research Copilot (ARC)

ARC is a cache-first research toolkit for theoretical-physics papers and research-domain construction. Use ARC tools instead of scraping arXiv/INSPIRE or reimplementing paper/domain workflows.

Preflight Gate

Choose one entry path before any ARC CLI call:

• Implicit paper entry: activate for any task owned by arc-paper, even when the user does not name ARC. This includes its complete paper-access, acquisition, search, citation, paper-cache, and summary surfaces. LLM-backed paper summaries and summary batches remain eligible for implicit activation; whether an arc-paper operation uses an LLM is not a trigger boundary.
• Explicit ARC entry: require the user to name ARC, invoke $arc, or make an unambiguous continuation of an already-started explicit ARC task before selecting an AC Foundation capability or a managed ARC workflow. Supporting calls that arc-paper explicitly requires remain part of the selected paper task; they do not authorize an independent non-paper capability. Do not infer broader opt-in from a general research request, a paper identifier, or a successful arc-paper call. Route only the requested capability.

This package boundary is the complete trigger policy; do not add a separate cost, duration, or LLM-call classifier. After entry, decide whether the request is a managed ARC workflow run or a direct ARC tool task. All accepted requests default to automation_level: auto; never ask the user to choose an execution mode at startup. Use interactive only when the user explicitly asks for manual, step-by-step, or major-step review or confirmation. A request to discuss before running creates a pre-run pause rather than a third mode.

Managed workflow runs follow workflows/domain.md, workflows/ideas.md, workflows/check.md, workflows/plan.md, or workflows/calculate.md, and create project-local workflow artifacts such as domain references, ranked ideas, work notes, note-check records, calculation records, reports, rankings, recommendations, research directions, or follow-up project directories. They always require the explicit ARC entry. For these, read rules/interaction.md and only the workflow and manuals selected by the requested capability. Use the latest explicit user steer as the current automation level through the end of the managed run or until another explicit steer changes it. Perform exactly the workflow scope requested by the caller. Finish at that scope boundary: an automatic domain request does not authorize idea generation, and automatic idea generation does not authorize planning or calculation. Required prerequisites named by the owning workflow may still run, but they do not expand the requested outcome.

Direct ARC tool tasks use the same default-auto and explicit-review policy. Implicitly activated direct tasks stay within arc-paper. These include bounded paper facts such as title, authors, abstract, citation count, section text, or equation context, plus paper-tool orchestration such as collecting citers or references, filtering papers by date, generating paper summaries or summary batches, or combining those steps into a non-evaluative paper-data output. An explicit ARC request may instead select a direct AC Foundation tool. Direct tasks must not produce recommendations, research directions, scientific rankings, ARC reports, or managed-workflow artifacts; route those through the owning managed workflow. Durable state and outputs owned by the selected arc-paper operation remain allowed. Run direct tasks automatically with safe defaults unless the user explicitly asks to review or confirm steps. Example: download papers that cited 0911.3380 since 2024 and create a full summary of these papers may implicitly activate direct arc-paper orchestration; it is not a managed workflow mode prompt.

AC model calls have no default runtime or inactivity timeout. A caller may set an explicit positive idle timeout through the owning command when operationally needed. Use the owning package's status command or the host's background-command facility for long-running work. Do not stop merely because the call is long or quiet. An explicit user stop pauses the current attempt for same-run resume.

Required References

Read the relevant reference before calling ARC tools. These reads are required, not optional.

• For an implicit paper entry, read manuals/arc-paper.md. Read another rule or manual below only when the selected arc-paper operation requires that topic. Do not read or start a managed workflow.

• For an explicit ARC entry, read only the rules, workflow, and manuals needed by the requested capability. Do not preload unrelated capability documents.

• User choices, automation mode, and confirmation behavior: read rules/interaction.md. Use its Selection Protocol only for a real business choice; mandatory safety or scientific gates may require a direct question.

• Scientific claims, gap scoring, automated workflow decisions, warning behavior, or robustness-sensitive execution: read rules/integrity.md.

• General ARC operating rules: read rules/operating.md.

• User-facing Markdown math and TeX typesetting: read rules/math_typeset.md.

• Explicit ARC note-checking, verification, or audit requests: read workflows/check.md before any parse, section read, or equation extraction call.

• When an explicit ARC request selects a workflow-specific file (workflows/check.md, workflows/domain.md, workflows/ideas.md, workflows/plan.md, or workflows/calculate.md), read that workflow file and follow its steps. Reading the workflow file is a blocking requirement before any workflow CLI call.

• Managed ARC workflow completion checks and improvement notes: read rules/self-reflection.md.

• Single-paper metadata, full text, sections, equations, citers, references, paper summaries, or summary batches: read manuals/arc-paper.md.

• Local source import/parsing, exact cached-document reads, neutral text or equation search, keyword inventories, rich-document export, or document-cache administration: read manuals/ac-document.md.

• Research field/domain construction, foundation-paper selection, domain networks, evidence packs, graph HTML, or field briefings: read manuals/arc-domain.md.

• Durable run inspection, validation, live work-group concurrency adjustment, or stop requests: read manuals/ac-jobs.md.

• Host LLM/provider detection, model choice, direct prompt tests, or provider troubleshooting: read manuals/ac-llm.md.

• Host model handoff, awaiting_host, or subagent coordination: read manuals/host-execution.md. Check actual coordinator capabilities; export and submit through public ac-llm operations, then resume the original workflow. Work/Cowork/dot use Host; coding agents prefer their native provider with conservative pre-launch fallback. Scientific workers require independent contexts. Model preferences may use the host model when unsupported, with truthful provenance. Never edit private run state or bypass user stops.

• Typed proposer-reviewer batch construction, resume, or safe observation of committed rounds: read manuals/ac-proposer-reviewer.md.

• User-facing Markdown report export: use the ordinary blocking Pandoc/XeLaTeX command in rules/math_typeset.md; see manuals/ac-jobs.md for the workflow failure boundary.

CLI Resolution

Use ac-document, arc-paper, arc-domain, ac-llm, and ac-jobs directly when the host plugin exposes them on PATH. In DeepSeek Harness, prefer the trusted launcher exported as $DSH_ARC_RUNTIME when it is present; this avoids assuming that a plugin's package-local bin/ directory has already been added to the model shell's PATH. The core-only ac-proposer-reviewer tool deliberately has no plugin-bin wrapper; invoke it through the runtime launcher. For a standalone Skill install, or when a bare command is unavailable, invoke the same command through:

bashCopy code
<skill-dir>/scripts/arc-runtime <arc-command> [args...]

Within DeepSeek Harness, the equivalent portable form is:

bashCopy code
"$DSH_ARC_RUNTIME" arc-paper <subcommand> [args...]

For example:

bashCopy code
<skill-dir>/scripts/arc-runtime ac-proposer-reviewer trace \
  --run-root <run-root> --run-id <run-id>

Run Skill-owned Python workflow adapters inside that same private environment:

bashCopy code
<skill-dir>/scripts/arc-runtime script <skill-dir>/scripts/<workflow>.py [args...]

inspect, trace, and show-round are the only public observation surface for a proposer-reviewer batch. inspect activity is best effort and cannot drive ranking, recovery, retries, or resume. trace exposes only verified committed-round refs and revision vectors; show-round alone expands a committed proposal/review JSON payload. Never read durable loop or artifact layout to substitute for these queries.

The first real CLI call lazily installs the immutable locked runtime. At task startup, use <skill-dir>/scripts/arc-runtime doctor to check readiness; if needed, initialize with <skill-dir>/scripts/arc-runtime setup before research calls. Installation needs access to its locked sources and dependencies. If it fails, inspect the reported installer output/log and correct the cause, then use setup --retry within the task's existing authority. Respect user stops and host permission decisions; do not repeat retries without a changed cause. The base Skill never installs or starts MCP.

The launcher defaults AC_HOME to $HOME/.ac; set AC_RUNTIME_HOME for an explicit portable runtime location. Neutral document cache defaults to .ac/cache/ac-document/, while paper cache defaults to .arc/cache/arc-paper/ below the launch directory. Set AC_DOCUMENT_CACHE or ARC_PAPER_CACHE for explicit portable locations. Durable workflow state belongs in each project's hidden .arc/ directory. doctor reports the resolved runtime identity and environment. Provider selection remains owned by the installed ac-llm package.

Workflow

Follow the workflow step by step. Do not skip any step, and do not kill or stop any job because it is slow or time consuming.

Phase 1: Setup

Step 1: Set the automation level and requested scope. Use this step only for managed ARC workflow runs. For direct ARC tool tasks, skip the Workflow section and use the relevant manuals and CLI tools directly.

Default to auto without asking. If the user explicitly requests manual, step-by-step, staged review, or confirmation at key steps, use interactive. Follow runtime steering, one-shot checkpoints, and hard-gate rules in rules/interaction.md. Preserve the caller's requested workflow boundary; auto suppresses routine confirmation questions but never opts the caller into downstream workflows.

Step 2: Extract <user-intent>. Keep the research/scientific request. Remove operational instructions such as automation mode, project directory, and output formatting.

Preserve scientific domain anchors in <user-intent>, including phrases such as "in the field started by arXiv:..." or "in the literature around ...". Those phrases are part of the scientific request, not workflow metadata. Keep the same paper identifiers separately in seed_paper_list as structured routing data.

If the request references or attaches accessible files such as .md, .pdf, .doc, or .jpg, read or extract the relevant content and summarize it as part of <user-intent>. Treat collaborator notes or images as source context for routing, domain building, checking, or later workflows.

Step 3: Resolve <seed-paper-list>. Use explicit paper identifiers when present. Otherwise infer seed papers from <user-intent> through ARC paper tools. For a domain request whose relative date applies to field papers (for example, “field X in the last two years”), do not treat that date as a seed-paper filter: first resolve a date-unbounded canonical origin, then use the date window for its citers as specified in workflows/domain.md. Keep the candidate evidence and origin-selection result separately; only each selected/explicit foundation becomes an entry in seed_paper_list for its domain build. See manuals/arc-paper.md for paper identifier inference and manuals/ac-jobs.md for background jobs.

Step 4: Resolve <project-dir>. Capture <arc-run-root> by running pwd -P in the directory where the user launched the agent command. Do not use host-internal project/cache locations. If <arc-run-root> is under .claude, .codex, a plugin directory, or a cache directory, print WARNING: and stop before writing artifacts.

Use a user-specified project directory when present. Otherwise derive <project_dir_name> as a safe directory stem from <seed-paper-list> with ARC paper tools, then resolve <project-dir> with:

bashCopy code
python3 <skill-dir>/scripts/resolve-project-dir.py \
  --name <project_dir_name> \
  --run-root <arc-run-root> \
  --json

The generated <project-dir> must be the direct child <arc-run-root>/<project_dir_name>. Do not create arc-output/<project_dir_name>, do not wrap the safe name in another directory, and do not write generated workflow artifacts under .claude, .codex, plugin dirs, or cache dirs. If the directory already exists, follow the automation policy in rules/interaction.md.

Step 5: Write <project-dir>/context.json. Include automation_level, workflow, original_request, user_intent, arc_run_root, project_dir_name, project_dir, run_id, created_at, skill_version, skill_dir, skill_workflow_json_dir, seed_paper_list, provider, model_tier, workers, refresh, recent_window_days, and as_of_date. A domain origin-resolution path additionally records origin_candidates, origin_selections, origin_selection_run_ids, domain_deduplications, foundation_mode, citer_selection_mode, and, when required, source_provenance plus the requested refactor ancestor.

Default recent_window_days to 365 and freeze as_of_date to the run's UTC date. When the request says "the last two years", use the exact number of days between as_of_date and the corresponding calendar date two years earlier.

Set provider to auto unless the user pins a provider. Set model_tier to medium unless the user explicitly asks otherwise. Never select the max model tier automatically; use it only when the user explicitly requests the max model tier. See manuals/ac-llm.md for model tiers.

Use a stable safe run_id: lowercase ASCII letters, digits, and underscores, for example a short intent slug plus UTC timestamp. Set skill_dir to the ARC skill directory and skill_workflow_json_dir to <skill-dir>/workflows/json.

When resuming a managed run, reconcile automation_level with the latest explicit user steer and update the existing context.json in place. Do the same after a runtime switch. Direct tool tasks do not create a state file solely for this field; follow the latest explicit instruction in the current session.

Phase 2: Route Selection

Resolve the user's intent and classify it into one of the six cases below. Choose only the case needed for the requested outcome. Run another case only when it is an explicit prerequisite below or the caller also requested that outcome. Never interpret auto as permission to advance to a later case.

Case 1: Build domain references only. Read and execute workflows/domain.md.

Case 2: Suggest ideas from a request without a concrete idea. First complete Case 1. Then read and execute workflows/ideas.md. The workflow owns one public BatchRequest in its project-local RunRepository; inspect and rank only its verified committed rounds. Do not substitute private loop files, worker sessions, retired intermediary artifacts, nested ARC CLIs, or MCP calls for that contract.

Case 3: Check note files or collaborator notes. Use when the request asks to check, verify, audit, or mark work-note premises and claims in one or more accessible .md or .pdf notes. workflows/check.md was already loaded in Required References. Follow its 5-phase workflow: Parse -> Preflight -> Write Planning Handoff -> Execute plan.md and calculate.md -> Record Note-Check Status. Do not skip directly to parsing results; the preflight, planning handoff, and owned-workflow execution steps are mandatory.

Before leaving Case 3 or sending a final response, read <project-dir>/.arc/calculate/<run-id>/work-note.md. If any ready detailed step exists, execute workflows/calculate.md. If no ready detailed step exists but rough or pending coverage remains from the original note-check request, return to workflows/plan.md. Adjudicate every item in Rough Steps For Later Planning: promote and execute it, remove or mark it obsolete/not triggered, or record an explicit stop condition in Open Questions or Calculation Status. Only stop when requested coverage is complete and no triggered rough/pending item remains.

Case 4: Calculate from an explicit idea. If the idea is not explicit enough, first complete Case 1 and Case 2, then ask the user to select one concrete idea only in interactive mode. In auto mode, use ranked idea #1 without asking. If the idea is explicit enough: Step 1: Read and execute workflows/plan.md. It writes or updates the hidden current work note under <project-dir>/.arc/calculate/<run-id>/ and publishes the visible <project-dir>/work-note.pdf. Step 2: Read and execute workflows/calculate.md. If calculate.md requests macro expansion or blocked-step refinement, return to Step 1 for that region.

Before leaving Case 4 or sending a final response, read <project-dir>/.arc/calculate/<run-id>/work-note.md. If any ready detailed step exists, execute workflows/calculate.md. If no ready detailed step exists but rough or pending coverage remains from the original calculation request, return to workflows/plan.md to promote the next coherent chunk. Adjudicate every item in Rough Steps For Later Planning: promote and execute it, remove or mark it obsolete/not triggered, or record an explicit stop condition in Open Questions or Calculation Status. Only stop when requested calculation coverage is complete and no triggered rough/pending item remains.

Phase 3: Self-Reflection

Read and follow rules/self-reflection.md.