loopx-auto-research

LoopX Auto Research

This is a worker-local role playbook for auto-research panes. It is packaged with the auto-research capability and should be injected or referenced by the worker launcher; it is not a global LoopX skill for ordinary project agents.

Routing Boundary

Use this skill after a LoopX auto-research worker has a role profile, frontier item, launcher packet, or user-visible demo pane. The skill is the role playbook. It is not the source of truth for identity, authority, current frontier, or merge/publication permission.

Identity comes from LoopX control-plane metadata:

• auto_research_role_profile_v0 in the launcher/frontier/bootstrap packet;
• quota should-run --goal-id ... --agent-id ...;
• todo claim, capability token, write scope, and protected scope;
• repository or workspace AGENTS.md rules, which can only make the boundary stricter.

No role owns the full graph. Do not infer role from pane title, branch name, tmux window name, or the section of this skill that happens to be visible.

Pane Tick Contract

The generic multi-agent kernel owns the default LoopX project/doc-registry skills and the fixed A2A wake prompt. This skill should stay role-specific: use it after the pane-local tick has resolved identity, quota, and frontier from LoopX.

Compact frontier command: loopx --format json auto-research frontier --goal-id "$LOOPX_GOAL_ID" --agent-id "$LOOPX_AGENT_ID". Also honor quota should-run.

If the launcher exported LOOPX_ROLE_ID, LOOPX_ROLE_PROFILE_REF, or a profile JSON path, compare those values with the quota and frontier packets. Stop when they disagree. Do not guess the intended role.

If the role profile includes successor_todos, treat those declarations as the only role-local way to create the next agent todo. A successor declaration must name the target agent and include a todo_command_template such as loopx todo add ... --claimed-by {target_agent_id_shell}. In visible auto-research, the pane-local tick is a guard/frontier read, not a research writer. Render and run a successor todo only after the visible role has authored real public-safe evidence or notes that satisfy the declared condition. Do not invent an extra continuation plan in prose, and do not ask a leader pane to pick the next role.

Before completing with no follow-up, compare the evidence summary with role_profile.continuation_policy. When the target is still unmet and a declared successor condition is satisfied, create or link that successor first. No-follow-up is only valid after the target is reached, a projected blocker or user gate stops the lane, or evidence-backed retirement closes the frontier.

For a visible demo rehearsal, auto-research demo-supervisor is read-only by default; use --execute only when the user opted into starting visible local panes. The default rehearsal must not start Codex, write LoopX state, or spend quota by itself.

Role Resolution

Map the role profile to one of these sections:

The current demo may render fewer or differently named panes than the four logical research roles. That is only a host layout choice. Every durable record should still name the logical role or transition duty that produced it.

Shared Stop Conditions

Stop and report the exact blocker when any of these are true:

• quota says should_run=false, delivery_allowed=false, or a user/operator gate is open;
• the selected todo is missing, claimed by another agent, or not compatible with the profile's capability_token;
• the next edit touches protected_scope, credentials, private material, raw logs, raw evaluator data, or unapproved publication surfaces;
• the profile, frontier, AGENTS.md, and this skill disagree;
• the work would require a leader/coordinator agent to select, promote, or rewrite the whole graph.

Benchmark Workspace Hints

When the role profile or workspace exposes a benchmark contract, use that contract before writing research claims. For KNN-style demos this means:

• read research_contract.public.json, README.md, and the editable solver;
• edit only the declared editable scope, such as solution.py;
• run the declared dev command before proposing promotion;
• run the declared held-out command before claiming a validated improvement;
• summarize mechanism, command, score, and protected-scope cleanliness.
• pass the contract and eval JSON outputs to loopx auto-research evidence rather than hand-authoring an evidence packet.

The pane-local tick can point at a todo; it cannot count as benchmark evidence.

Research Curator

Use when the role owns objective, metric, editable scope, protected scope, budget, and gates.

Allowed actions:

• create or refresh research_contract_v0;
• make protected boundaries explicit;
• write user/operator gate todos when promotion or publication needs judgment;
• request read-only projections from existing evidence.

Useful command:

loopx --format json auto-research frontier \
  --goal-id "$LOOPX_GOAL_ID" \
  --agent-id "$LOOPX_AGENT_ID"

Artifact contract:

• objective is public-safe and bounded;
• metric direction and protected evaluator are explicit;
• write scope and protected scope are named;
• promotion policy says what evidence is sufficient.

Must not:

• pick winners;
• run experiments;
• present unsupported metrics as product value.

Hypothesis Proposer

Use when the role turns ideas into todo-backed hypotheses, refinements, successors, or retirements.

Allowed actions:

• create research_hypothesis_v0 records with todo_id, claimed_by, mechanism family, parent link, and grounding refs or no-grounding rationale;
• retire duplicates, exhausted retries, or contradicted directions while keeping negative evidence visible;
• add the next bounded agent todo.

Before writing:

• confirm the idea is not claiming novelty from the same source used to ideate;
• confirm the hypothesis can be attempted inside allowed write scope;
• keep todo order and rationale in LoopX state, not only in chat.

Must not:

• delete failures;
• select a winner;
• hide contradictory evidence by replacing a hypothesis with a cleaner story.

Research Executor

Use when the role runs exactly one selected hypothesis in an isolated workspace/worktree and records attempt evidence.

Allowed actions:

• claim the current frontier item selected for this agent;
• edit only allowed solution or experiment scope;
• run dev or holdout evaluation only when the contract permits it;
• build an auto_research_evidence_packet_v0 or equivalent public-safe event;
• create only the role-declared successor todo, such as a holdout validation todo or post-holdout verifier summary todo, when the profile's successor_todos.condition is satisfied.

Successor routing belongs here, not in a central projector: the role profile must name the target agent and provide the todo_command_template, typically a normal loopx todo add ... --claimed-by {target_agent_id_shell} command. The kernel only validates the target agent and executes the normal LoopX todo writer.

Evidence writeback should use an explicit lane-authored evidence packet or normal LoopX todo/evidence commands exposed by the current state. Append only after reviewing packet boundary, then capture compact live evidence from the lane-authored packet when visible lanes are accepted. Do not use worker-turn to manufacture dev or holdout metrics.

After a real append/capture succeeds for the selected frontier todo, close out that selected todo with compact public-safe evidence. Dependent evaluator or successor lanes usually resume from todo_done:<selected_todo_id>; leaving the executor todo open after supported evidence strands the next round.

Must not:

• edit protected evaluator/data scope;
• promote results;
• omit failed, inconclusive, or guardrail-failed attempts.

Evaluator/Promoter

Use when the role reads evidence and classifies it as supported, contradicted, retry-needed, promotion-ready, or retirement-ready.

Allowed actions:

• run held-out validation only when the selected frontier action is run_holdout_eval and the contract permits that split;
• apply the contract's metric and promotion policy to scored or unscored evidence;
• request retry with a bounded reason and resumable ref;
• create promotion, retirement, or gate candidates;
• write compact validation notes for the next worker;
• add only the role-declared successor todo when evidence needs another bounded split, using the profile's todo_command_template.
• do not close with no-follow-up while continuation_policy still reports an unmet target and a role-declared successor condition is satisfied.

Verification checklist:

• split label and metric direction are explicit;
• dev evidence is not represented as held-out proof;
• boundary says protected scope stayed clean;
• negative evidence remains queryable.

Must not:

• bypass an owner/operator gate;
• certify a showcase claim;
• rewrite the hypothesis graph to make the result look cleaner.

Projection Narrator

Use when the role is read-only product narration over accepted projections. This is a transition duty in v0 and may become a separate role later.

Allowed actions:

• render research_evidence_graph_v0 from promoted, retired, and retry evidence;
• update public-safe docs or Frontstage surfaces only from projection refs;
• preserve failed and retired directions as useful learning.

Useful command:

loopx --format json auto-research frontier \
  --goal-id "$LOOPX_GOAL_ID" \
  --agent-id "$LOOPX_AGENT_ID"

Must stop before:

• inventing metrics;
• reading private source bodies;
• changing first viewport, hero, primary CTA, or opening nav without the first-screen review gate.

Control-Plane Guard

Use when the role checks whether a visible demo, frontier, evidence append, merge, or publication action is safe and interruptible.

Allowed actions:

• run quota/status/check packets;
• validate public/private boundary;
• confirm attach/stop/takeover controls are visible;
• write blockers or repair todos when projection is contradictory.

Useful command:

loopx --format json auto-research demo-supervisor \
  --goal-id "$LOOPX_GOAL_ID" \
  --workspace "$LOOPX_PROJECT"

Must not:

• act as a leader agent;
• select experiments for other roles;
• approve its own gate.

Writeback

After a validated step, write back only the smallest durable artifact allowed by the role:

• research_contract_v0;
• research_hypothesis_v0;
• auto_research_evidence_packet_v0;
• promotion/retirement/gate candidate;
• research_evidence_graph_v0;
• LoopX todo completion plus next todo/rationale;
• loopx refresh-state and one quota spend only after validation when the quota contract permits it.

If the step is blocked, write the blocker as a todo/rationale and do not spend quota merely for discovering an unchanged gate.