템플릿과 예시

Templates

FILEworkspace-readme.md

FILEAGENTS.template.md

FILEfirst-day-workspace-checklist.md

FILEfirst-ai-session-prompt.md

FILEpaper-code-experiment-map.md

FILEdataset-archaeology-sheet.md

FILEexperiment-contract.md

FILEstage-local-debugging.md

FILEclaim-evidence-map.md

FILEcodex-porting-checklist.md

FILEweekly-research-ledger.md

FILEresult-provenance-tuple.md

FILEreplay-case.md

FILEuser-reaction-prior.md

FILEpaper-reading-note.md

FILEproject-memory.template.json

Example Workspace

FILEREADME.md

FILEAGENTS.md

FILEproject-memory.json

FILEfirst-day-workspace-checklist.md

FILEfirst-ai-session-prompt.md

FILEfirst-ai-session-message.txt

FILEpaper-code-experiment-map.md

FILEexperiment-contract.md

FILEstage-local-debugging.md

FILEcodex-porting-checklist.md

FILEweekly-research-ledger.md

workspace-readme.md

[PROJECT_NAME] Research Workspace

이 파일은 새 로보틱스/CV 연구 프로젝트의 첫 화면이다. 프로젝트 이름, 주요 repo, dataset 위치, 첫 AI 세션 경계만 채운 뒤 시작한다.

Start Here

1. AGENTS.md를 먼저 읽는다.
2. project-memory.json에서 현재 truth, source_of_truth, current_evidence, first_research_loop, next_smallest_actions를 확인한다.
3. notes/first-day-workspace-checklist.md로 source of truth를 잠근다.
4. 기존 CLAUDE.md, .claude/, Cursor rule이 있으면 notes/codex-porting-checklist.md로 행동 원칙만 옮긴다.
5. session, harness, sandbox 경계를 먼저 쓴다.
6. 첫 AI 세션에는 notes/first-ai-session-prompt.md를 채워 보낸다.

First Run Check

Before the first AI session, the workspace should have these files.

AGENTS.md
README.md
project-memory.json
notes/first-day-workspace-checklist.md
notes/first-ai-session-prompt.md
notes/paper-code-experiment-map.md
notes/experiment-contract.md
artifacts/first-ai-session-message.txt

project-memory.json must parse as JSON. The first message in artifacts/first-ai-session-message.txt should have no bracket placeholders left before it is sent.

project-memory.json should also include source_of_truth, tool_surface_map, current_evidence, first_research_loop, and next_smallest_actions. These fields keep the next AI session from treating memory as proof.

Use the workspace as a managed-agent harness.

• Session: project-memory.json, ledger, replay cases, and artifacts.
• Harness: AGENTS.md, prompt templates, evidence gates, and work modes.
• Sandbox: repos, datasets, commands, tools, and generated outputs.

Workspace Shape

workspace/
├── AGENTS.md
├── README.md
├── project-memory.json
├── repos/
├── datasets/
├── artifacts/
├── notes/
└── templates/

Project Pointers

• Main repo:
• Dataset root:
• Artifact root:
• Paper or manuscript:
• Current experiment:

First Research Loop

Situation	Start With
Read one paper	notes/paper-code-experiment-map.md
Check a dataset	templates/dataset-archaeology-sheet.md
Interpret a number	notes/experiment-contract.md
Narrow an error	notes/stage-local-debugging.md
Repair a claim	templates/claim-evidence-map.md

Evidence Gate

session record to update:
harness rule:
sandbox action:
current evidence permits:
current evidence forbids:
next smallest action:
verification:
ledger update:

Fill these lines before asking for a broad answer.

After the first session, copy the same boundary back into project-memory.json under current_evidence and next_smallest_actions.

AGENTS.template.md

Project AGENTS.md Template

This project is operated Codex-first. If older CLAUDE.md, .claude/, or Cursor rules exist, treat them as source material. Move durable project rules into this AGENTS.md and keep tool-specific install commands separate.

Project Truth

• Current public artifact:
• Current private state file:
• Source of truth for code:
• Source of truth for experiments:
• Source of truth for manuscript:
• Source of truth for reviewer response:
• Source of truth for durable corrections:

Public / Private Boundary

Public:

• README
• guide or paper draft if already public
• templates
• sanitized examples

Private:

• 비공개 대화 원문
• 심사 원문
• 인증 정보
• unpublished results
• 개인 경로
• raw dataset paths if they reveal private storage

Managed Agent Boundary

This workspace follows the managed-agent pattern at the project level.

• Session: project-memory.json, weekly ledger, replay cases, and artifacts.
• Harness: this AGENTS.md, evidence gate, work modes, and durable corrections.
• Sandbox: code repos, datasets, commands, tools, and generated outputs.

Before starting work, state which session record will be updated, which harness rule controls the action, and which sandbox action is currently allowed. Leave a command result, file diff, or artifact path before promoting an observation into a research claim.

Work Modes

Read-only audit

Allowed:

• inspect files
• summarize current state
• identify missing evidence
• state what current evidence permits and forbids

Not allowed:

• edit files
• run destructive commands
• make paper claims from weak evidence

Code execution

Allowed:

• run listed commands
• collect logs
• update run ledger

Required:

• command
• cwd
• expected artifact
• timeout
• verification step

Experiment interpretation

Allowed:

• inspect configs, logs, tables, and metric scripts
• compare numbers only inside a locked protocol

Required:

• dataset
• split or sequence
• query/database direction if retrieval
• ground-truth frame
• metric definition
• baseline
• artifact path

Manuscript edit

Allowed:

• edit claim/evidence structure
• improve prose after argument is correct

Required:

• target claim
• evidence source
• reviewer risk
• build or diff check

Evidence Gate

Before answering, state:

current evidence permits:
current evidence forbids:
promotion requires:

Durable Corrections

When the user corrects an assumption, add it to project memory.

Record:

• wrong assumption:
• corrected fact:
• affected workflow:
• future gate:
• replay case:

Porting Acceptance

If this file was created from CLAUDE.md, .claude/, Cursor rules, or another tool-specific instruction set, do not start research action until the porting checklist has confirmed:

• tool-specific commands have portable replacements;
• local-only settings are not treated as project rules;
• dataset, metric, artifact, claim, reviewer risk, and replay gates exist;
• first AI session prompt reads this AGENTS.md, project memory, first-day checklist, and the chosen target note.

first-day-workspace-checklist.md

First-Day Workspace Checklist

Use this before asking an AI agent to work inside a robotics/CV research workspace.

Workspace Shape

• Workspace root:
• Main code repos:
• Dataset storage:
• Artifact storage:
• Manuscript location:
• Template location:
• Public output location:

Source Of Truth

State	Primary source	Secondary source
project goal
code truth
dataset truth
experiment truth
manuscript truth
reviewer risk
durable corrections

Public / Private Boundary

Public:

• README:
• guide or paper draft:
• templates:
• sanitized examples:

Private:

• private notes:
• reviewer material:
• unpublished results:
• credential material:
• machine-specific paths:

First Agent Read Order

1. AGENTS.md
2. README.md
3. status or roadmap file
4. file tree
5. build/test scripts
6. recent artifacts
7. project memory

First Verification Commands

Purpose	Command	Expected result
build docs
run tests
inspect data
check artifacts

First Research Action

• Object under truth control:
• Current evidence permits:
• Current evidence forbids:
• Smallest next action:
• Verification:

first-ai-session-prompt.md

First AI Session Prompt

Use this as the first message in a new robotics/CV research workspace. Fill the brackets before sending it to an AI agent.

Session Target

• Workspace:
• Research object:
• Current task:
• First research loop target:
• Expected artifact:

Read Order

Read these files before answering.

1. AGENTS.md
2. project-memory.json
3. notes/first-day-workspace-checklist.md
4. notes/weekly-research-ledger.md
5. target note or source file:
6. artifact or command output:

First Research Loop Target

Choose exactly one target note before the first session. The first message should name that target note and the expected artifact.

Common first targets:

• notes/paper-code-experiment-map.md with notes/experiment-contract.md
• notes/stage-local-debugging.md
• templates/dataset-archaeology-sheet.md copied into notes/
• templates/claim-evidence-map.md copied into notes/

Before Answering

Map the workspace into session, harness, and sandbox first.

Session record to update:
Harness rule that controls this action:
Sandbox action allowed now:
Sandbox action not allowed now:
Object under truth control:
Current evidence permits:
Current evidence forbids:
Smallest next action:
Verification:

Allowed First Action

• Inspect source files and named artifacts.
• Separate source truth from summary truth.
• Name missing evidence before proposing a claim.
• Choose one stage-local action.
• Leave a session record, harness rule, sandbox action, and verification record.

Blocked Claims

• Do not infer project truth from summaries when source files or artifacts are available.
• Do not claim experiment improvement before dataset, split, metric, baseline, command, and artifact are known.
• Do not rewrite manuscript claims before allowed wording and forbidden wording are separated.
• Do not publish raw notes, reviewer material, secret material, or machine-specific storage names.

Promotion Requires

The session can move from orientation to research action only after these fields are filled.

object under truth control:
primary evidence:
secondary evidence:
claim allowed:
claim blocked:
next command or file inspection:
ledger update:

Prompt To Send

Read AGENTS.md, project-memory.json, notes/first-day-workspace-checklist.md, and
notes/weekly-research-ledger.md, [target note], and [supporting note] before
answering.

My current task is: [task].
First research loop target: [target note]
Expected artifact: [expected artifact]

Before giving advice, state:
- Session record to update
- Harness rule that controls this action
- Sandbox action allowed now
- Sandbox action not allowed now
- Object under truth control
- Current evidence permits
- Current evidence forbids
- Smallest next action
- Verification

Use source files, artifacts, and command output as primary evidence. Treat
summaries as orientation only. If evidence is missing, say what is missing and
choose the smallest inspection that would promote the claim.
Do not open a second research loop in the first answer.

paper-code-experiment-map.md

Paper-Code-Experiment Map

Paper

• Title:
• Authors:
• Year / venue:
• Link:

Central Claim

• What the paper claims:
• What problem pressure it responds to:
• What assumption it repairs or introduces:

Method Map

Paper concept	Code candidate	Status	Evidence
		unknown

Status labels:

• implemented-active
• implemented-disabled
• configured-unused
• planned-only
• tested-failed
• dead
• unknown

Experiment Contract

• Dataset:
• Split / sequence:
• Sensor / modality:
• Query -> database direction:
• Ground truth:
• Metric:
• Threshold / alignment:
• Baseline:
• Artifact:

Agent Handoff Note

Only include issues that change how the method should be run, evaluated, or cited.

• Session record to update:
• Harness rule triggered:
• Sandbox file / command to inspect next:
• Build issue:
• Dataset convention issue:
• Metric issue:
• Sensor setup issue:
• Claim or limitation issue:
• Verification left for next session:

Reusable Research Output

• Comparison I can reuse:
• Claim this paper supports:
• Claim this paper does not support:
• Next artifact to inspect:

dataset-archaeology-sheet.md

Dataset Archaeology Sheet

Dataset Identity

• Dataset name:
• Version / release:
• Source link:
• License:
• Local storage class:
• Public or private:

Inventory

Item	Expected	Observed	Evidence
sequences / scenes
images / scans / bags
calibration files
ground truth
metadata

Modality And Frame

• Sensors:
• Timestamp convention:
• Coordinate frames:
• Calibration source:
• Known transform direction:
• Missing transform:

Split And Direction

• Train / val / test split:
• Query set:
• Database set:
• Positive definition:
• Negative definition:
• Radius or exact-frame rule:

Data Quality Risks

• Missing files:
• Duplicate files:
• Corrupt files:
• Unsynced timestamps:
• Sequence count mismatch:
• README contradiction:

Evidence Gate

Current evidence permits:

Current evidence forbids:

Promotion requires:

experiment-contract.md

Experiment Contract

Identity

• Experiment name:
• Date:
• Repository:
• Branch / commit if available:
• Operator:

Protocol

• Dataset:
• Split:
• Sequence / scene:
• Query / database direction:
• Sensor or modality:
• Ground truth source:
• Frame / transform convention:
• Metric:
• Threshold:
• Alignment:
• Baseline:
• Failure condition:

Command

Expected Artifacts

• Log:
• Result table:
• Figure:
• Config:

Evidence Gate

Current evidence permits:

Current evidence forbids:

Promotion requires:

Interpretation

• If success:
• If failure:
• If partial:

Verification

• Command completed:
• Artifact exists:
• Sample count checked:
• Metric definition checked:
• Baseline protocol checked:
• Claim boundary updated:

stage-local-debugging.md

Stage-Local Debugging Sheet

Debug Target

• Object under truth control:
• User-visible symptom:
• Current stage:
• Expected signal:
• Observed signal:

Stage Selection

Stage	In scope?	Evidence
data
preprocessing
representation
retrieval / matching
geometry / estimation
optimization
confidence / rejection
evaluation
runtime environment

Candidate Causes

Candidate	Stage	Evidence now	Lowest-risk check

Next Check

• Command:
• Working directory:
• Expected artifact:
• Timeout:
• Success signal:
• Failure signal:

Result

• Command completed:
• Artifact produced:
• New evidence:
• Claim allowed:
• Claim forbidden:

Stop Rule

• Stop if:
• Escalate if:
• Record debt if:

claim-evidence-map.md

Claim Evidence Map

Manuscript Target

• Section:
• Paragraph:
• Figure / table:
• Reviewer pressure:

Claim

Evidence Required

• Artifact:
• Script / command:
• Dataset / protocol:
• Metric:
• Baseline:
• Sample count:

Evidence Available

Evidence Missing

Allowed Wording

Forbidden Wording

Falsification Check

What result or counterexample would make the claim false?

Reviewer Risk

• Likely objection:
• Required concession:
• Revision target:
• Remaining limitation:

codex-porting-checklist.md

Codex Porting Checklist

Use this when a project already has CLAUDE.md, .claude/, Cursor rules, or tool-specific agent instructions.

Source Files

Run a discovery sweep before filling the table. Do not rely on memory or on the files already visible in the editor.

find . -maxdepth 4 \( -name 'CLAUDE.md' -o -path './.claude/*' -o -path './.cursor/*' -o -name '*command*' -o -name '*commands*' \) -print

Inventory result:

• Discovery command:
• Sources found:
• Sources intentionally ignored:
• Missing source types checked:

Source	Exists?	Keep?	Destination
CLAUDE.md			AGENTS.md
.claude/settings.local.json			local notes only
.claude/skills			Codex skill or template
.cursor/rules			AGENTS.md or editor rule
slash commands			script or checklist
MCP/plugin config			local notes or install guide
CI/workflow commands			verification script
project memory			project-memory.json

Move Into AGENTS.md

• Project goal:
• Public/private boundary:
• Source-of-truth read order:
• Stage pipeline:
• Allowed commands:
• Forbidden commands:
• Evidence gate:
• Durable corrections:
• Build or verification commands:

Convert Tool-Specific Commands

Original command	Portable meaning	Codex replacement

Examples:

• plugin install command -> source link plus manual install note
• slash command -> script, template, or checklist
• Claude-only setting -> Codex sandbox/approval note
• MCP/plugin config -> capability note plus local setup boundary
• CI/workflow command -> repo verification command
• coding rule -> project AGENTS.md rule

Research Gates To Add

Claude or coding-agent rules often stop at test pass. Robotics research needs more gates.

• Dataset provenance:
• Metric protocol:
• Artifact path:
• Result provenance:
• Claim/evidence boundary:
• Reviewer risk:
• Replay case:

Do Not Publish

• private machine paths
• raw conversation records
• credential values
• private reviewer text
• unpublished result details

Porting Result

Current evidence permits:

Current evidence forbids:

Promotion requires:

Acceptance Gate

Porting is complete only when these artifacts agree.

• AGENTS.md contains the moved project goal, boundary, read order, evidence gate, durable corrections, and verification commands.
• Discovery sweep was run and every found Claude/Cursor/slash-command/plugin source has a keep/drop/destination decision.
• tool-specific commands have portable replacements in the command conversion table.
• Claude-only, editor-only, or local-only settings are recorded as local notes, not public project rules.
• Robotics research gates were added for dataset, metric, artifact, claim, reviewer risk, and replay.
• project-memory.json contains any durable correction discovered during porting.
• First AI session prompt names AGENTS.md, project-memory.json, first-day checklist, and the first target note.

If one item is missing, the first AI session remains orientation only.

weekly-research-ledger.md

Weekly Research Ledger

Week

• Dates:
• Main project:

Research Progress

• Claim and evidence advanced:
• Experiment protocol verified:
• Paper or code result improved:

Setup Progress

• Environment:
• Tooling:
• Data movement:

Numbers Produced

Number	Result file	Protocol	Can claim?

Open Risks

• Evidence risk:
• Runtime risk:
• Manuscript risk:
• Reviewer risk:

Next Smallest Action

result-provenance-tuple.md

Result Provenance Tuple

Number

• Value:
• Unit:
• Higher is better / lower is better:
• Table or figure target:

Protocol

• Dataset:
• Split / sequence:
• Sensor / modality:
• Query -> database direction:
• Ground truth:
• Metric:
• Threshold:
• Alignment:
• Baseline:

Execution

• Repository:
• Branch / commit if available:
• Command:
• Config:
• Runtime environment:
• Date:
• Operator:

Artifact

• Log:
• Raw result:
• Aggregated table:
• Plot:
• Checkpoint / cache:

Claim Boundary

Current evidence permits:

Current evidence forbids:

Promotion requires:

Agent Handoff Note

• Session record to update:
• Harness rule triggered:
• Sandbox file / command to inspect next:
• Failure observed:
• Claim allowed now:
• Claim blocked now:
• Verification left for next session:

replay-case.md

Replay Case

Failure Name

Trigger

What kind of user request or artifact tends to cause the mistake?

Bad AI Behavior

Required Gate

• Session record to update:
• Harness rule triggered:
• Sandbox file / command to inspect next:

Minimal Test

Correct Behavior

Durable Constraint

Verification Prompt

Use this prompt to test the next AI session:

Given the same trigger, state the required gate before making a claim.
Do not infer from filenames, summaries, or memory when artifact evidence is
required.

user-reaction-prior.md

User Reaction Prior

Use this before a substantial research-agent response, edit, command, or continuation.

The purpose is not to predict the user as a person. The purpose is to stop the agent from repeating known transition failures: shallow summary, local pattern matching, weak evidence promotion, wrong implementation surface, non-operational advice, and drift from the original goal.

When To Use

Use this gate for robotics/CV research work involving code, experiments, datasets, metrics, paper writing, reviewer response, literature positioning, workspace continuation, or durable project memory.

Do not use it for trivial one-line facts or mechanical formatting with no research-state consequence.

Pre-Response Check

Before answering, ask:

reaction_risk_check:
  likely_user_objection:
  violated_transition:
  required_revision:
  revised_action:
  remaining_risk:

If likely_user_objection is nonempty, change the action itself before answering. Do not pass this gate by adding caveats, apologies, or a displayed checklist.

Reaction Classes

User correction cue	Likely agent failure	Required revision
"too shallow"	stopped at first-order summary	raise abstraction and name the reusable transition
"too local"	followed files, words, or counts instead of research state	extract invariant failure mode and control surface
"did you read it?"	detached from retained artifacts	name the source-of-truth artifact and bind the claim to it
"why this implementation surface?"	used the wrong control layer	separate skill, rule, gate, workflow, and script
"can this be used immediately?"	descriptive but not operational	convert to a gate, checklist, replay case, schema field, or workflow entry
"is that sufficiently analyzed?"	promoted weak evidence	demote the claim and state what would promote it
"do you remember the goal?"	optimized a local subtask	restate the higher-order objective and discard irrelevant work
"stop making parallel documents"	scattered state	patch the active surface instead of creating another summary
"proceed / resume / complete all"	stopped at proposal	continue through implementation and verification

Real Revision

A real revision changes at least one of:

• selected skill or typed action;
• source-of-truth artifact inspected before acting;
• evidence tier or blocked claim;
• action mode;
• narrowest next action;
• verification gate;
• durable control surface.

A non-revision only changes tone, length, or confidence language while leaving the same flawed action intact.

Stop Condition

After the reaction-risk check, continue through the active project entrypoint: AGENTS.md, project memory, research-turn skill, issue workflow, or paper workflow. When a correction recurs, turn it into a reusable gate, replay case, skill rule, project memory entry, or bot instruction.

Source model: alexjunholee/robotics-research-agent.

paper-reading-note.md

Paper Reading Note

Bibliographic

• Title:
• Authors:
• Year:
• Venue:
• Link:

One-Sentence Claim

Problem Axis

• Task:
• Setting:
• What is hard:

Method Assumptions

• Observation model:
• State / representation:
• Optimization / learning objective:
• Data assumptions:

Evidence

• Dataset:
• Split:
• Metric:
• Baselines:
• Main result:
• Failure cases:

What This Paper Allows Me To Say

What This Paper Does Not Allow Me To Say

Evidence Gate

Current evidence permits:

Current evidence forbids:

Promotion requires:

Agent Handoff Note

• Session record to update:
• Harness rule triggered:
• Sandbox file / command to inspect next:
• Claim allowed now:
• Claim blocked now:
• Verification left for next session:

Reusable Citation Role

• Background:
• Method comparison:
• Limitation:
• Reviewer defense:

project-memory.template.json

{
  "project": "",
  "workspace_path": "",
  "current_truth": "",
  "source_of_truth": {
    "project_rules": "AGENTS.md",
    "workspace_start": "README.md",
    "current_memory": "project-memory.json",
    "first_day_checklist": "notes/first-day-workspace-checklist.md",
    "weekly_ledger": "notes/weekly-research-ledger.md",
    "artifact_root": "artifacts/"
  },
  "tool_surface_map": [
    {
      "research_scene": "",
      "tool_surface": "",
      "first_gate": ""
    }
  ],
  "current_evidence": {
    "permits": [],
    "forbids": [],
    "promotion_requires": []
  },
  "first_research_loop": {
    "target": "",
    "target_note": "",
    "supporting_note": "",
    "expected_artifact": "",
    "no_second_loop": true
  },
  "durable_constraints": [],
  "known_artifacts": [],
  "experiment_protocols": [],
  "claim_boundaries": [],
  "replay_cases": [],
  "next_smallest_actions": [],
  "last_updated": "YYYY-MM-DD"
}

README.md

First Robotics Workspace

이 폴더는 첫날 로보틱스/CV 연구 프로젝트를 어떻게 채우는지 보여 주는 공개 예시다. 실제 연구 파일, 개인 경로, 원 대화 로그는 들어 있지 않다.

Start Here

1. AGENTS.md를 먼저 읽는다.
2. project-memory.json에서 현재 확인한 사실, source_of_truth, current_evidence, first_research_loop, next_smallest_actions를 확인한다.
3. notes/first-day-workspace-checklist.md로 원 파일과 실행 결과를 정한다.
4. 기존 CLAUDE.md, .claude/, Cursor rule이 있으면 notes/codex-porting-checklist.md로 행동 원칙만 옮긴다.
5. session, harness, sandbox 경계를 먼저 쓴다.
6. 첫 AI 세션에는 notes/first-ai-session-prompt.md를 채워 보낸다.

First Run Check

첫 세션 전에 다음 파일이 있어야 한다.

AGENTS.md
README.md
project-memory.json
notes/first-day-workspace-checklist.md
notes/first-ai-session-prompt.md
notes/paper-code-experiment-map.md
notes/experiment-contract.md
notes/weekly-research-ledger.md
artifacts/first-ai-session-message.txt

project-memory.json은 JSON으로 열려야 한다. 첫 메시지에는 [task], [target note], [supporting note], [expected artifact]가 남아 있으면 안 된다. memory 안의 source_of_truth, tool_surface_map, current_evidence, first_research_loop, next_smallest_actions도 비어 있으면 안 된다.

Read Order

AGENTS.md
project-memory.json
notes/first-day-workspace-checklist.md
notes/weekly-research-ledger.md
notes/first-ai-session-prompt.md

First Research Loop

논문 한 편은 notes/paper-code-experiment-map.md에 남긴다. 실험 숫자는 notes/experiment-contract.md로 protocol을 확인한 뒤 말한다. 에러는 notes/stage-local-debugging.md에서 stage, signal, next check로 좁힌다.

첫 세션의 답은 항상 아래 경계를 포함해야 한다.

session record to update:
harness rule:
sandbox action:
current evidence permits:
current evidence forbids:
next action:
verification:
record update:

이 다섯 줄이 채워지면 AI는 일반 조언 대신 연구 상태 안에서 움직인다. 세션이 끝나면 같은 경계를 project-memory.json의 current_evidence와 next_smallest_actions에 다시 남긴다.

AGENTS.md

Example Robotics Workspace AGENTS.md

This is a sanitized example. Replace names, paths, datasets, and commands with your own project state before using it.

Project Truth

• Current public artifact: project README and paper notes
• Current private state file: project-memory.json
• Source of truth for code: repos/localization-stack
• Source of truth for datasets: dataset inventory sheet
• Source of truth for experiments: notes/experiment-contract.md
• Source of truth for manuscript: notes/claim-evidence-map.md when created
• Source of truth for durable corrections: project-memory.json

Public / Private Boundary

Public:

• README
• sanitized notes
• empty templates
• public paper links

Private:

• raw experiment logs
• reviewer material
• machine-specific storage names
• unpublished result tables

Managed Agent Boundary

• Session: project-memory.json, weekly ledger, replay cases, and artifacts.
• Harness: AGENTS.md, evidence gate, work modes, and durable corrections.
• Sandbox: repos/localization-stack, dataset inventory, commands, and generated outputs.

Before starting work, state the session record to update, the harness rule that controls the action, and the sandbox action currently allowed.

Work Modes

Workspace Resume

Read in this order:

1. AGENTS.md
2. project-memory.json
3. notes/first-day-workspace-checklist.md
4. notes/codex-porting-checklist.md if legacy AI rules exist
5. notes/weekly-research-ledger.md
6. current target note
7. artifacts named in the target note

Experiment Interpretation

Required before any performance claim:

• dataset
• split or sequence
• query/database direction if retrieval
• metric definition
• baseline
• artifact path
• failure condition

Debugging

Use stage-local debugging. State the stage, expected signal, observed signal, candidate causes, and lowest-risk check before naming a root cause.

Evidence Gate

Before answering, state:

current evidence permits:
current evidence forbids:
promotion requires:

Durable Corrections

If a user corrects an assumption, update project-memory.json before continuing.

Porting Acceptance

This example workspace includes a completed notes/codex-porting-checklist.md. Research action starts after the checklist confirms:

• tool-specific commands have portable replacements;
• local-only settings are not treated as project rules;
• dataset, metric, artifact, claim, reviewer risk, and replay gates exist;
• first AI session prompt reads this AGENTS.md, project memory, first-day checklist, and the chosen target note.

project-memory.json

{
  "project": "example-localization-workspace",
  "current_truth": "First-day sanitized workspace for a robotics/CV AI harness. No private data is included.",
  "source_of_truth": {
    "project_rules": "AGENTS.md",
    "workspace_start": "README.md",
    "current_memory": "project-memory.json",
    "first_day_checklist": "notes/first-day-workspace-checklist.md",
    "weekly_ledger": "notes/weekly-research-ledger.md",
    "artifact_root": "artifacts/"
  },
  "tool_surface_map": [
    {
      "research_scene": "connect one localization paper to code and experiment protocol",
      "tool_surface": "coding agent plus terminal for source inspection only after AGENTS.md and memory are read",
      "first_gate": "paper-code-experiment map names central claim, candidate code paths, missing protocol fields"
    },
    {
      "research_scene": "interpret experiment number",
      "tool_surface": "experiment operator role",
      "first_gate": "dataset, split, metric script, baseline, command, and artifact are recorded"
    }
  ],
  "current_evidence": {
    "permits": [
      "The workspace can open a first AI-assisted paper/code/experiment pass.",
      "The first AI prompt can ask for one target note and one expected artifact."
    ],
    "forbids": [
      "No method performance claim is allowed.",
      "No reviewer defense claim is allowed.",
      "No dataset comparison is allowed until split, metric script, baseline, command, and artifact are recorded."
    ],
    "promotion_requires": [
      "Fill notes/paper-code-experiment-map.md with central claim, method assumption, candidate code path, and missing experiment protocol fields.",
      "Fill notes/experiment-contract.md with dataset, split, metric, baseline, command, and artifact.",
      "Update notes/weekly-research-ledger.md with blocked claim and next smallest action."
    ]
  },
  "first_research_loop": {
    "target": "connect one localization paper's central claim to code path candidates and missing experiment protocol fields",
    "target_note": "notes/paper-code-experiment-map.md",
    "supporting_note": "notes/experiment-contract.md",
    "expected_artifact": "filled sections in notes/paper-code-experiment-map.md",
    "no_second_loop": true
  },
  "durable_constraints": [
    "Do not infer experiment success from a command finishing.",
    "Do not compare retrieval numbers unless query/database direction and positive rule are known.",
    "Treat prior summaries as orientation, not evidence."
  ],
  "known_artifacts": [
    {
      "name": "first-day-workspace-checklist",
      "path": "notes/first-day-workspace-checklist.md",
      "status": "filled"
    },
    {
      "name": "codex-porting-checklist",
      "path": "notes/codex-porting-checklist.md",
      "status": "filled"
    },
    {
      "name": "paper-code-experiment-map",
      "path": "notes/paper-code-experiment-map.md",
      "status": "draft"
    },
    {
      "name": "experiment-contract",
      "path": "notes/experiment-contract.md",
      "status": "needs artifact"
    }
  ],
  "experiment_protocols": [],
  "claim_boundaries": [
    {
      "claim": "The workspace is ready for a first AI-assisted paper/code/experiment pass.",
      "allowed": true,
      "blocked_extension": "No method performance claim is allowed yet."
    }
  ],
  "replay_cases": [],
  "next_smallest_actions": [
    "Read AGENTS.md, project-memory.json, first-day checklist, weekly ledger, and the first-session prompt.",
    "Inspect the evaluation script and dataset split file, then fill notes/paper-code-experiment-map.md before opening any second research loop.",
    "Update current_evidence and claim_boundaries after the first artifact is produced."
  ],
  "last_updated": "2026-06-16"
}

first-day-workspace-checklist.md

First-Day Workspace Checklist

This file is filled enough for a first AI-assisted research loop. Replace every example name before using it in a real project.

Workspace Shape

• Workspace root: example-localization-workspace
• Main code repos: repos/localization-stack
• Dataset storage: datasets/public-sequence-sample
• Artifact storage: artifacts/first-pass
• Manuscript location: notes/claim-evidence-map.md when created
• Template location: templates/
• Public output location: README and sanitized notes

Source Of Truth

State	Primary source	Secondary source
project goal	AGENTS.md	project-memory.json
code truth	repos/localization-stack	recent command output
dataset truth	dataset inventory sheet	notes/experiment-contract.md
experiment truth	notes/experiment-contract.md	result provenance tuple
manuscript truth	notes/claim-evidence-map.md	paper notes
reviewer risk	notes/weekly-research-ledger.md	project-memory.json
durable corrections	project-memory.json	replay cases

Public / Private Boundary

Public:

• README
• sanitized notes
• empty templates
• public paper links

Private:

• raw experiment logs
• reviewer material
• unpublished result tables
• credential material
• machine-specific storage names

First Agent Read Order

1. AGENTS.md
2. project-memory.json
3. notes/first-day-workspace-checklist.md
4. notes/weekly-research-ledger.md
5. current target note
6. artifacts named in the target note

First Verification Commands

Purpose	Command	Expected result
inspect project contract	sed -n '1,160p' AGENTS.md	project truth and boundary are visible
inspect memory	python3 -m json.tool project-memory.json	current truth parses as JSON
inspect first loop	sed -n '1,180p' notes/paper-code-experiment-map.md	claim/code/protocol fields are visible
inspect experiment gate	sed -n '1,180p' notes/experiment-contract.md	permitted and blocked claims are visible

First Research Action

• Object under truth control: one paper-code-experiment map for a localization paper
• Current evidence permits: identifying claim, code path candidates, and missing protocol fields
• Current evidence forbids: claiming method performance or reviewer readiness
• Smallest next action: fill the paper claim and active code path candidate
• Verification: cite the paper section, code file, or command output used for each filled field

first-ai-session-prompt.md

First AI Session Prompt

This example starts one paper-code-experiment loop for a localization project.

Session Target

• Workspace: example-localization-workspace
• Research object: one paper-code-experiment map for a localization paper
• Current task: connect the paper claim to code path candidates and missing experiment protocol fields
• Expected artifact: filled sections in notes/paper-code-experiment-map.md

Read Order

Read these files before answering.

1. AGENTS.md
2. project-memory.json
3. notes/first-day-workspace-checklist.md
4. notes/weekly-research-ledger.md
5. notes/paper-code-experiment-map.md
6. notes/experiment-contract.md

Before Answering

State these fields first.

Session record to update:
Harness rule that controls this action:
Sandbox action allowed now:
Sandbox action not allowed now:
Object under truth control:
Current evidence permits:
Current evidence forbids:
Smallest next action:
Verification:

Allowed First Action

• Inspect the paper-code-experiment map.
• Identify central claim and active code path candidates.
• Mark missing dataset, split, metric, baseline, command, and artifact fields.
• Choose one file or command output to inspect next.
• Leave a session record, harness rule, sandbox action, and verification record.

Blocked Claims

• Do not claim method performance.
• Do not state reviewer readiness.
• Do not treat a file name as active implementation proof.
• Do not turn missing protocol fields into manuscript claims.

Promotion Requires

object under truth control:
primary evidence:
secondary evidence:
claim allowed:
claim blocked:
next command or file inspection:
ledger update:

Prompt To Send

Read AGENTS.md, project-memory.json, notes/first-day-workspace-checklist.md,
notes/weekly-research-ledger.md, notes/paper-code-experiment-map.md, and
notes/experiment-contract.md before answering.

My current task is to connect one localization paper's central claim to code path
candidates and missing experiment protocol fields.
First research loop target: notes/paper-code-experiment-map.md
Expected artifact: filled sections in notes/paper-code-experiment-map.md

Before giving advice, state:
- Session record to update
- Harness rule that controls this action
- Sandbox action allowed now
- Sandbox action not allowed now
- Object under truth control
- Current evidence permits
- Current evidence forbids
- Smallest next action
- Verification

Use source files, artifacts, and command output as primary evidence. Treat
summaries as orientation only. If evidence is missing, say what is missing and
choose the smallest inspection that would promote the claim.
Do not open a second research loop in the first answer.

first-ai-session-message.txt

Read AGENTS.md, project-memory.json, notes/first-day-workspace-checklist.md,
notes/weekly-research-ledger.md, notes/paper-code-experiment-map.md, and
notes/experiment-contract.md before answering.

My current task is to connect one localization paper's central claim to code path
candidates and missing experiment protocol fields.
First research loop target: notes/paper-code-experiment-map.md
Expected artifact: filled sections in notes/paper-code-experiment-map.md

Before giving advice, state:
- Session record to update
- Harness rule that controls this action
- Sandbox action allowed now
- Sandbox action not allowed now
- Object under truth control
- Current evidence permits
- Current evidence forbids
- Smallest next action
- Verification

Use source files, artifacts, and command output as primary evidence. Treat
summaries as orientation only. If evidence is missing, say what is missing and
choose the smallest inspection that would promote the claim.
Do not open a second research loop in the first answer.

paper-code-experiment-map.md

Paper-Code-Experiment Map

Paper

• Title: Example visual place recognition paper
• Authors: Public authors
• Year / venue: 2024 / public venue
• Link: https://example.org/public-paper

Central Claim

• What the paper claims: A representation improves place recognition under a defined evaluation.
• What problem pressure it responds to: visual change and cross-condition retrieval.
• What assumption it repairs or introduces: feature space should preserve place identity under appearance change.

Method Map

Paper concept	Code candidate	Status	Evidence
feature extractor	repos/localization-stack/src/features.py	unknown	file candidate only
retrieval index	repos/localization-stack/src/index.py	unknown	file candidate only

Experiment Contract

• Dataset: example urban route dataset
• Split / sequence: not verified
• Sensor / modality: camera
• Query -> database direction: not verified
• Ground truth: not verified
• Metric: R@K, definition not verified
• Threshold / alignment: not verified
• Baseline: not verified
• Artifact: not produced

Agent Handoff Note

Only include issues that change how the method should be run, evaluated, or cited.

• Session record to update: project-memory.json and weekly ledger
• Harness rule triggered: evidence gate before performance claim
• Sandbox file / command to inspect next: evaluation script and dataset split file
• Build issue:
• Dataset convention issue:
• Metric issue:
• Sensor setup issue:
• Claim or limitation issue:
• Verification left for next session: cite the file or command output used for each filled field

Reusable Research Output

• Comparison I can reuse: blocked until protocol is verified.
• Claim this paper supports: candidate representation family for VPR.
• Claim this paper does not support: performance improvement in this workspace.
• Next artifact to inspect: evaluation script and dataset split file.

experiment-contract.md

Experiment Contract

Identity

• Experiment name: example-vpr-baseline
• Date: 2026-06-16
• Repository: repos/localization-stack
• Branch / commit if available: not recorded
• Operator: new user

Protocol

• Dataset: example urban route dataset
• Split: not verified
• Sequence / scene: not verified
• Query / database direction: not verified
• Sensor or modality: camera
• Ground truth source: not verified
• Frame / transform convention: not applicable yet
• Metric: R@K, definition not verified
• Threshold: not verified
• Alignment: not applicable yet
• Baseline: not verified
• Failure condition: missing split, missing artifact, or metric script mismatch

Command

# fill after repository setup

Expected Artifacts

• Log:
• Result table:
• Figure:
• Config:

Evidence Gate

Current evidence permits:

• The experiment can be planned.

Current evidence forbids:

• Any performance or method claim.

Promotion requires:

• dataset split, metric script, baseline, command, and artifact.

Interpretation

• If success: compare only within the locked protocol.
• If failure: classify tool, runtime, data, method, evaluation, or claim failure.
• If partial: record the blocked claim.

Verification

• Command completed:
• Artifact exists:
• Sample count checked:
• Metric definition checked:
• Baseline protocol checked:
• Claim boundary updated:

stage-local-debugging.md

Stage-Local Debugging Sheet

Debug Target

• Object under truth control: ROS2 camera image subscriber
• User-visible symptom: topic appears in graph, callback receives no image
• Current stage: runtime environment / ROS2 communication
• Expected signal: subscriber callback count increases during bag replay
• Observed signal: callback count remains zero

Stage Selection

Stage	In scope?	Evidence
data	no	bag presence not yet inspected
preprocessing	no	subscriber has no input
representation	no	no features computed
retrieval / matching	no	downstream stage
geometry / estimation	no	downstream stage
optimization	no	downstream stage
confidence / rejection	no	downstream stage
evaluation	no	downstream stage
runtime environment	yes	topic visible but callback absent

Candidate Causes

Candidate	Stage	Evidence now	Lowest-risk check
QoS mismatch	runtime environment	publisher exists, callback absent	inspect topic QoS
namespace/remap mismatch	runtime environment	graph has image topic	inspect node subscriptions
simulated time issue	runtime environment	bag replay suspected	inspect clock and use_sim_time

Next Check

• Command: ros2 topic info --verbose /camera/image_raw
• Working directory: repo root
• Expected artifact: copied command output
• Timeout: 10 seconds
• Success signal: publisher/subscriber QoS is visible
• Failure signal: topic missing or command cannot query graph

Result

• Command completed:
• Artifact produced:
• New evidence:
• Claim allowed:
• Claim forbidden:

Stop Rule

• Stop if: two consecutive checks produce no new evidence.
• Escalate if: ROS graph cannot be queried.
• Record debt if: workaround is used before root cause is verified.

codex-porting-checklist.md

Codex Porting Checklist

This is a sanitized example of moving older Claude/Cursor-oriented project rules into a Codex-first robotics research workspace.

Source Files

Discovery sweep:

find . -maxdepth 4 \( -name 'CLAUDE.md' -o -path './.claude/*' -o -path './.cursor/*' -o -name '*command*' -o -name '*commands*' \) -print

• Discovery command: ran against the old workspace root before copying rules
• Sources found: CLAUDE.md, .claude/settings.local.json, .claude/skills, slash commands, project memory
• Sources intentionally ignored: local plugin install notes, private machine paths, unsanitized conversation pointers
• Missing source types checked: .cursor/rules, MCP/plugin config, CI/workflow commands

Source	Exists?	Keep?	Destination
CLAUDE.md	yes	yes	AGENTS.md
.claude/settings.local.json	yes	partial	local notes only
.claude/skills	yes	partial	template or Codex skill
.cursor/rules	no	no	none
slash commands	yes	partial	script or checklist
MCP/plugin config	no	no	none
CI/workflow commands	no	no	none
project memory	yes	yes	project-memory.json

Move Into AGENTS.md

• Project goal: maintain a localization research workspace with clear claim/evidence gates
• Public/private boundary: publish sanitized notes only
• Source-of-truth read order: AGENTS, memory, first-day checklist, target note, named artifacts
• Stage pipeline: resume, choose one loop, run stage-local check, update ledger
• Allowed commands: read files, inspect JSON, run documented verification checks
• Forbidden commands: delete datasets, publish raw logs, infer result quality from filenames
• Evidence gate: current evidence permits, forbids, and promotion requires
• Durable corrections: store repeated wrong assumptions in project memory
• Build or verification commands: commands listed in the target note

Convert Tool-Specific Commands

Original command	Portable meaning	Codex replacement
/resume	reconstruct current project state	read AGENTS.md, project-memory.json, and ledger
/debug-topic	isolate a ROS2 topic failure	fill stage-local-debugging.md
/paper-map	connect a paper to code and experiments	fill paper-code-experiment-map.md
/claim-check	stop unsupported manuscript claims	fill claim-evidence-map.md
plugin install command	install a local UI extension	keep as private setup note, not public guide content
CI/workflow command	run repeatable verification	keep as documented verification command if it exists

Research Gates To Add

• Dataset provenance: dataset inventory or archaeology sheet
• Metric protocol: experiment contract
• Artifact path: result provenance tuple
• Result provenance: command, timestamp, output file, failure condition
• Claim/evidence boundary: claim map before manuscript wording
• Reviewer risk: weekly ledger or claim map
• Replay case: repeated wrong assumption or metric mix-up

Do Not Publish

• private machine paths
• raw conversation records
• credential values
• private reviewer text
• unpublished result details

Porting Result

Current evidence permits:

• Claude/Cursor-era operating rules can be reused as Codex project rules.
• Tool-specific commands have portable meanings that can become scripts or templates.

Current evidence forbids:

• Treating Claude-only settings as Codex permissions.
• Publishing local plugin install notes or private workspace paths.
• Claiming the workspace is experimentally validated.

Promotion requires:

• Run the first chosen research loop.
• Update project-memory.json with any durable correction.
• Add a replay case if the same mistaken assumption recurs.

Acceptance Gate

• AGENTS.md contains the moved project goal, boundary, read order, evidence gate, durable corrections, and verification commands.
• Discovery sweep was run and every found Claude/Cursor/slash-command/plugin source has a keep/drop/destination decision.
• tool-specific commands have portable replacements in the command conversion table.
• Claude-only, editor-only, or local-only settings are recorded as local notes, not public project rules.
• Robotics research gates were added for dataset, metric, artifact, claim, reviewer risk, and replay.
• project-memory.json contains any durable correction discovered during porting.
• First AI session prompt names AGENTS.md, project-memory.json, first-day checklist, and the first target note.

If one item is missing, the first AI session remains orientation only.

weekly-research-ledger.md

Weekly Research Ledger

Week

• Dates: 2026-06-16 to 2026-06-22
• Main project: example localization workspace

Research Progress

• Claim/evidence advanced: workspace boundary and first protocol created
• Experiment protocol verified: none
• Paper or code artifact improved: paper-code-experiment map started

Setup Progress

• Environment: workspace skeleton created
• Tooling: AGENTS.md added
• Data movement: not started

Numbers Produced

Number	Artifact	Protocol	Can claim?
none	none	none	no

Open Risks

• Evidence risk: dataset split and metric definition not verified
• Runtime risk: ROS2 communication issue not yet inspected
• Manuscript risk: no claim/evidence map yet
• Reviewer risk: no paper claim should be made

Next Smallest Action

Inspect the evaluation script and dataset split file, then update notes/paper-code-experiment-map.md and notes/experiment-contract.md before opening any second research loop.