/agent-research-aggregator

name: agent-research-aggregator
description: Pre-pipeline aggregator that scans AI agent cache directories (.claude, .cursor, .antigravity, .openclaw) or any user-specified directory for experimentation logs, extracts insights and numeric results, and formats them as PaperOrchestra-ready inputs (idea.md + experimental_log.md). TRIGGER when the user says "aggregate my agent logs for paper writing", "extract experiments from my coding agent history", "prepare PaperOrchestra inputs from my cache", "turn my agent logs into a paper", mentions a folder or directory they want to use as the basis for a paper, or wants to run PaperOrchestra but only has scattered agent experiment histories rather than structured inputs. Run this BEFORE paper-orchestra. Also called automatically by paper-orchestra when workspace/inputs/idea.md or workspace/inputs/experimental_log.md are missing.

agent-research-aggregator

---

Should I run? (decision gate)

Before starting Phase 1, check whether aggregation is actually needed:

| Situation | Action | |---|---| | `workspace/inputs/idea.md` **and** `workspace/inputs/experimental_log.md` both exist and are non-empty | **Skip this skill entirely.** Proceed directly to `paper-orchestra`. | | Either file is missing or empty, **and** the user provided a directory path | **Run this skill** with that directory as `--search-roots`. | | Either file is missing or empty, **and** no directory was provided | Scan cwd and `~` by default; show the discovery summary to the user before continuing. | | The inputs exist but look thin (e.g. idea.md has < 5 lines, no numeric data in experimental_log.md) | **Ask the user** whether to supplement with aggregation or proceed as-is. |

The skill is intentionally a pre-pass — it is cheap to skip and should only run when the structured inputs don't already exist.

---

A pre-processing skill for PaperOrchestra (arXiv:2604.05018). Reads scattered experimentation artifacts from AI coding-agent cache directories and synthesizes them into the structured `(I, E)` input pair the PaperOrchestra pipeline expects.

[.claude/]  [.cursor/]  [.antigravity/]  [.openclaw/]
      │            │              │               │
      └────────────┴──────────────┴───────────────┘
                          │
                    Phase 1: Discovery
                  (discover_logs.py)
                          │
                    discovered_logs.json
                          │
                    Phase 2: Extraction
                  (LLM call per log batch)
                          │
                    raw_experiments.json
                          │
                    Phase 3: Synthesis
                  (LLM call — consolidate)
                          │
                    synthesis.json
                          │
                    Phase 4: Formatting
                  (format_po_inputs.py)
                          │
             ┌────────────┴────────────┐
      workspace/inputs/         workspace/ara/
        idea.md                   aggregation_report.md
        experimental_log.md       discovered_logs.json
                                  raw_experiments.json
                                  synthesis.json

The output drops directly into `workspace/inputs/` so the user can immediately run `paper-orchestra` on the same workspace.

---

Inputs

| Parameter | Required | Default | Description | |---|---|---|---| | `--search-roots` | no | cwd, `~` | Comma-separated directories to scan for agent caches | | `--agents` | no | all | Comma-separated subset: `claude,cursor,antigravity,openclaw` | | `--workspace` | no | `./workspace` | PaperOrchestra workspace root | | `--depth` | no | 4 | Max directory scan depth (prevents runaway scans on large home dirs) | | `--since` | no | none | Only include logs modified after this date (ISO 8601: `2025-01-01`) |

The user specifies these when invoking the skill, or you may ask them for `--search-roots` if the current directory has no detectable agent caches.

---

Phase 1 — Discovery (deterministic)

Run the discovery script to catalog every relevant log file:

python skills/agent-research-aggregator/scripts/discover_logs.py \
    --search-roots <roots> \
    --agents <agents> \
    --depth <depth> \
    --since <since> \
    --out workspace/ara/discovered_logs.json

The script exits with code **2** when no `--project` filter is set (this is expected on the first run). It prints a **"Projects found"** list to stdout — show it to the user immediately.

**If no logs are found at all:** stop and ask the user to specify `--search-roots` or point you at a directory that contains agent cache folders.

---

Phase 1.5 — Project Selection (mandatory)

**A paper can only be written from a single project. You must ask the user which project to use before any LLM processing begins.**

1. Display the numbered project list from the discovery summary, e.g.:

   Projects found:
     [1] /home/alice/projects/my-rl-experiment  (42 files)
     [2] /home/alice/projects/llm-eval-suite    (17 files)
     [3] /home/alice/projects/old-demo          (3 files)

2. Ask: *"Which project should this paper be based on? Please choose a number or paste the project path."* 3. **Do not proceed to Phase 2 until the user has answered.** 4. Re-run discovery with the chosen project to filter the manifest:

python skills/agent-research-aggregator/scripts/discover_logs.py \
    --search-roots <roots> \
    --agents <agents> \
    --depth <depth> \
    --since <since> \
    --project "<chosen project path>" \
    --out workspace/ara/discovered_logs.json

This overwrites `discovered_logs.json` so only the selected project's files remain. The script exits 0 on success.

**If the discovery finds only one project:** skip the question and inform the user: *"Only one project found: `<path>`. Using it for the paper."* — then re-run with `--project` automatically.

**If the discovery summary