manticore-jfc

An autonomous multi-agent framework for cosmological analysis of the Manticore reconstructions of the local Universe — the constrained posterior density, velocity, and initial-condition fields produced by Bayesian forward modelling (BORG/ARES).

You describe the science. The agents plan, implement, review, and document the analysis. You intervene at two points: approving the subset result before reading the full answer, and merging the harvest MR at the end.

---

How it works

The framework is a specification + prompt scaffold that turns Claude Code into a multi-agent cosmology pipeline. There is almost no executable analysis code here — the agents write that themselves, informed by the shared conventions and library.

A thin orchestrator holds the science prompt and coordinates. It never writes analysis code directly. Instead it spawns specialist subagents for each phase, collects their review verdicts, loops until clean, commits, and advances.

You: "Measure the bulk flow out to 150 Mpc/h."
        ↓
  ORCHESTRATOR
        ↓
  Phase 1 — Strategy        → executor → 4-bot review → commit
  Phase 2 — Exploration     → executor → self-review  → commit
  Phase 3 — Estimator       → executor → 1-bot review → commit
  Phase 4a — Pipeline       → executor → note writer → typesetter → 4-bot+bib review
  Phase 4b — Subset result  → executor → note writer → typesetter → 4-bot+bib review
                                                              ↓
                                                       HUMAN GATE ← you approve here
  Phase 4c — Full ensemble  → executor → note writer → 1-bot review
  Phase 5 — Documentation   → executor → note writer → typesetter → 5-bot review
  Harvest                   → harvester → MR to main ← you merge here

Each review panel classifies findings as (A) must resolve, (B) must fix, or (C) suggestion. The orchestrator does not advance a phase with unresolved A or B items. If a reviewer finds a science issue traceable to an earlier phase, the orchestrator regresses to fix the origin before re-running downstream.

---

What makes Manticore different

Most cosmological analyses work with a single best-estimate reconstruction. Manticore provides a posterior ensemble — hundreds of realizations of the density, velocity, and IC fields, each consistent with the data. This changes how results are reported:

• A result is a statistic computed per realization, then aggregated across the ensemble. The across-realization spread is the posterior uncertainty — the primary, well-defined error budget.
• "Systematics" become robustness sources: prior cosmology, bias model, survey mask, noise model, resolution, ensemble convergence. These are reported separately from the posterior uncertainty and then combined.
• The Phase 4 staging (forecast → subset → full ensemble) is the cosmology analogue of blinding: you build and validate the full pipeline before reading the posterior answer.

---

Analysis modes

Choose a mode when you scaffold. The mode shapes Phase 1 and activates mode-specific conventions and agents.

measurement — estimate a cosmological quantity

Use when you want a new measurement from the Manticore ensemble: a bulk flow amplitude, a power spectrum, a σ₈ estimate, a cross-correlation signal.

pixi run scaffold analyses/bulk_flow --type measurement

"Measure the bulk flow of the local Universe out to 150 Mpc/h and compare to the CMB dipole prediction."

comparison — validate or correlate against external data

Use when you want to cross-correlate Manticore fields with an external dataset (CMB maps, galaxy catalogs, void catalogs, cluster catalogs) to test for agreement or detect a signal.

pixi run scaffold analyses/isw_planck --type comparison

"Cross-correlate the Manticore density field with the Planck CMB temperature map and measure the ISW signal."

reproduction — apply a paper's method to Manticore data

Use when you want to apply the analysis method from a published paper to the Manticore ensemble and compare results. The framework fetches the paper from ADS/arXiv, reads its LaTeX source, extracts the estimator and required data, sources the inputs (or asks you), implements the method, and applies it to Manticore.

pixi run scaffold analyses/isw_granett2008 --type reproduction
claude

"Reproduce the ISW stacking analysis from Granett, Neyrinck & Szapudi 2008, arXiv:0805.1588."

Before Phase 1 begins, the orchestrator runs Phase 0:

1. Asks you which paper(s) to target (title, arXiv ID, or ADS bibcode)
2. Literature reader acquires the paper via the mcp-ads-arxiv MCP, reads the methods and results sections directly from the LaTeX source, and writes PAPER_SUMMARY.md — the estimator, all required data with specifics, and the key published numbers that become binding comparison targets
3. Data sourcing checks what is available in your external_data_dir and the Manticore API, searches public archives for anything else, and pauses to ask you about any dataset it cannot locate automatically

For papers not on arXiv, extract the tarball manually:

tar -xf paper.tar.gz -C analyses/isw_granett2008/target_literature/isw_granett2008/

The literature reader will read it from disk as a fallback.

investigation — hypothesis-driven anomaly hunt

Use when you want to investigate a claimed anomaly or test a specific hypothesis with discriminating tests. The framework maintains a running investigation log, tracks premises with revision conditions, and runs adversarial review.

pixi run scaffold analyses/cold_spot --type investigation

"Investigate the anomalous ISW signal reported in Granett et al. 2008. Is it consistent with the Manticore posterior, or does it require something beyond ΛCDM?"

---

Repository layout

One standalone monorepo. The orchestrator runs claude from the repository root, so all shared references resolve directly — no symlinks, no per-analysis environments.

manticore_jfc/
├── CLAUDE.md                  # the orchestrator spec (auto-loaded by claude)
├── pyproject.toml             # single pixi environment for the whole repo
├── bootstrap.py               # one-command setup for a fresh machine
├── scaffold_analysis.py       # creates analyses/<name>/
│
├── methodology/               # the multi-agent process
│   ├── 03-phases.md           # what each phase does
│   ├── 06-review.md           # review protocol, A/B/C classification
│   ├── 13-harvest.md          # the learning loop
│   └── ...
│
├── agents/                    # self-contained agent role definitions
│   ├── executor.md            # writes analysis code and figures
│   ├── literature_reader.md   # reads LaTeX source → PAPER_SUMMARY.md
│   ├── note_writer.md         # writes the analysis note prose
│   ├── physics_reviewer.md    # senior cosmologist review
│   ├── critical_reviewer.md   # find all flaws
│   ├── harvester.md           # promotes code/wisdom to main after Phase 5
│   └── ...
│
├── conventions/               # the cosmology domain knowledge
│   ├── manticore-data.md      # data products, API, ensemble handling
│   ├── cosmo-constants.md     # fiducial cosmology, citation policy
│   ├── statistical-hygiene.md # nulls, significance, look-elsewhere
│   ├── technical-pitfalls.md  # frame/units/h-factor/sign traps
│   ├── plotting.md            # figure standards (ensemble spread mandatory)
│   ├── reproduction-protocol.md
│   ├── investigation-protocol.md
│   └── ...                    # technique files (power-spectrum, bulk-flow, …)
│
├── lib/common/                # shared, recyclable analysis library
│   ├── manticore_api.py       # data loading, ensemble iteration
│   ├── statistics.py          # significance, covariance, posteriors
│   └── ...
│
├── templates/                 # per-phase CLAUDE.md templates (instantiated by scaffold)
│
└── analyses/                  # one subdirectory per analysis
    └── <name>/
        ├── ANALYSIS.md        # landing doc (what this analysis is)
        ├── prompt.md          # the science question (written by orchestrator)
        ├── .analysis_config   # data_dir and allowed paths
        ├── experiment_log.md  # running log (agents append throughout)
        ├── target_literature/ # (reproduction mode) LaTeX source + PAPER_SUMMARY.md
        ├── phase1_strategy/outputs/STRATEGY.md
        ├── phase2_exploration/
        ├── phase3_estimator/
        ├── phase4_inference/
        └── phase5_documentation/outputs/ANALYSIS_NOTE.pdf

---

Setup (fresh machine)

git clone ssh://git@git.aquila-consortium.org:2428/jens_jasche/manticore_jfc.git
cd manticore_jfc
python3 bootstrap.py

This installs pixi if missing, creates the single project environment (scientific stack + the editable lib/common + manticore_data + tectonic/pandoc for PDF rendering), verifies imports, and reports any missing tokens or MCP setup.

One-time token and MCP setup:

# 1. NASA ADS token (free): https://ui.adsabs.harvard.edu/user/settings/token
# 2. Gitea token: Settings → Applications → Generate New Token (repo read+write)
# 3. Install the literature MCP (macOS):
brew tap estevesjh/mcp && brew install mcp-ads-arxiv

# Add to ~/.zshrc:
export ADS_API_TOKEN="your-ads-token"
export LIT_CACHE_DIR="$HOME/.manticore_papers"   # shared paper library
export GITEA_TOKEN="your-gitea-token"

# Register the MCP with Claude Code:
claude mcp add --scope user mcp-ads-arxiv \
  -e ADS_API_TOKEN=$ADS_API_TOKEN \
  -e LIT_CACHE_DIR=$LIT_CACHE_DIR \
  -- mcp-ads-arxiv

Run python3 bootstrap.py --check at any time to verify everything is in place.

Shared data directory: data/external/ in the repo root is for external datasets (CMB maps, catalogs) shared across analyses. Set external_data_dir in each analysis's .analysis_config to point here (or to a mounted volume if the data lives on a cluster).

---

Running an analysis

Step 1 — sync and branch

git pull origin main                                     # get latest harvested wisdom
git checkout -b <your_username>/<analysis_name>          # your personal branch

Step 2 — scaffold

pixi run scaffold analyses/<analysis_name> --type <mode>

Edit analyses/<analysis_name>/.analysis_config and set:

• data_dir — path to your Manticore ensemble on disk
• external_data_dir — path to the shared external dataset folder (default: data/external/ in the repo root)

For reproduction mode, you do not need to prepare the paper in advance — the orchestrator will ask you for the paper identifier (arXiv ID, ADS bibcode, or title) and fetch it automatically. Only needed if the paper is not on arXiv: extract the tarball into analyses/<analysis_name>/target_literature/<slug>/.

Step 3 — describe the science

claude

Tell the orchestrator what you want in plain language. You do not need to specify the technique — the orchestrator chooses it in Phase 1 based on the science question and the available conventions.

Step 4 — wait (the agents do the work)

The orchestrator runs each phase autonomously. You can watch the experiment log grow at analyses/<analysis_name>/experiment_log.md.

For reproduction mode, the orchestrator will pause before Phase 1 if it cannot locate a required dataset. It will present you with the options it found and wait for your input — you may have access to data or know where to get it. It will also ask your permission before installing any new packages.

Step 5 — human gate (Phase 4b)

The orchestrator pauses after Phase 4b and shows you the compiled PDF containing the analysis note with the subset result (a fraction of the full ensemble). You review it and respond:

• APPROVE — proceed to Phase 4c (full ensemble run)
• ITERATE — something needs fixing; specify what and re-review
• REGRESS(N) — fundamental problem traced to Phase N; triggers a re-run

This gate exists so you see and approve the method and partial result before the full ensemble computation runs.

Step 6 — merge the harvest MR

After Phase 5, the harvester agent automatically:

1. Identifies reusable code from the analysis and adds it to lib/common/
2. Extracts new domain wisdom and adds it to conventions/
3. Pushes a harvest/<name> branch and opens a MR to main on Gitea

You (or a colleague) review the diff and merge. That is the only way anything reaches main. Every future analysis on the team then starts with this knowledge baked in.

---

The learning loop

main is the accumulation branch. It holds only reviewed, harvested improvements — never raw analysis work. Each analysis:

1. Starts by pulling main (latest lib + conventions) and scanning open harvest MRs (pending wisdom from colleagues not yet merged)
2. Runs on a personal branch <user>/<analysis>
3. Ends with a harvest MR that proposes what to promote back to main

Over time the shared library grows richer, the conventions capture more pitfalls, and each new analysis benefits from everything the team has learned — without any manual sync step.

---

Multi-user workflow

Each collaborator clones the repo, works on their own branch, and contributes back via harvest MRs. No one commits directly to main.

# First time on a new machine:
git clone ssh://git@git.aquila-consortium.org:2428/jens_jasche/manticore_jfc.git
cd manticore_jfc
python3 bootstrap.py
echo 'export GITEA_TOKEN=<your-token>' >> ~/.zshrc && source ~/.zshrc

# Starting each new analysis:
git pull origin main
git checkout -b <username>/<analysis>
pixi run scaffold analyses/<analysis> --type <mode>
# edit .analysis_config
claude

---

Requirements

Requirement	Notes
pixi	environment management — one env for the whole repo
Claude Code	the agent runtime (claude CLI)
manticore_data	Aquila data API — resolved automatically by pixi from the Aquila git
GITEA_TOKEN env var	Gitea personal access token for autonomous harvest MR creation
RAG / literature MCP	ADS/arXiv corpus for search / get_paper — see methodology/appendix-integration.md

---

Status

v0. Cosmology-native throughout; the full agent pipeline, tiered review, regression protocol, and harvest learning loop are specified and wired. The multi-user branching model and reproduction mode (with literature reader and data-sourcing gate) are implemented.

Remaining roadmap: end-to-end smoke test of a full analysis run.