Init Research Project

init-research-project

Initialize durable, structured project context for Codex. After initialization, the repository should contain enough project goals, environment details, commands, constraints, and known pitfalls that future tasks do not require the user to repeat the same background.

Core behavior

• Start with a quick directory scan before asking questions.
• Conduct the interview conversationally, one round at a time, with at most three questions per round.
• Reuse facts the user already provided and offer defaults inferred from the repository.
• Ask only questions that are still needed; stop early when the user says to generate the files.
• Keep AGENTS.md concise because it is always-on project guidance. Put detailed or evolving information in project-context/.
• Do not overwrite an existing AGENTS.md or existing project-context/ files without explicit permission. If they exist, inspect them and propose a merge or update first.
• If the scan finds task_plan.md or a planning-with-files plan, treat it as the existing plan source of truth. Do not create a duplicate roadmap without explicit permission.

Workflow

Step 0: Scan the project

Before asking questions, inspect the current directory:

pwd
rg --files -g '!.git/**' -g '!*.pyc' -g '!__pycache__/**' | head -80
rg --files --hidden -g '!.git/**' -g '**/task_plan.md'

Look for README files, language manifests, build files, experiment scripts, configuration, data directories, documentation, and any task_plan.md. Use those clues to make later choices specific to this project.

Step 1: Interview in rounds

Ask conversational questions instead of presenting the full questionnaire at once. Use the following rounds as a menu and skip anything already known.

Round 1 — Project identity

Ask:

1. What kind of project is this? Offer choices such as ML/AI research, systems/infra, web application, data science, mobile/embedded, or other.
2. What is the one-sentence goal? Offer templates based on the detected project type, such as “Optimize inference on [hardware]”, “Build a [service] for [audience]”, or “Benchmark [approaches] for [problem]”.

Round 2 — Stack and environment

Ask only the options relevant to the project:

• Primary languages and frameworks, such as Python + PyTorch, C++/CUDA, TypeScript + React, Go, Rust, or other.
• Development environments: local machine, remote Linux over SSH, cloud VM, mobile/embedded device, or CI/CD.
• Package manager: conda/mamba, pip/venv, uv/poetry, npm/pnpm/yarn, cargo, or other.

Round 3 — Remote or target hardware details

Ask this round only when the project uses a remote machine or target device:

• SSH connection or host alias.
• Working directory and environment activation command.
• Target hardware, OS, memory limit, accelerator, or other deployment constraints.

Never invent hostnames, credentials, paths, or hardware facts. Use [unknown] when the user chooses not to provide them.

Round 4 — Operations and guardrails

Ask:

• How to run, test, benchmark, or reproduce the project.
• Which files or directories are protected from modification without permission.
• Which non-obvious pitfalls are already known.

Suggest commands based on the scan, such as python train.py, pytest, bash scripts/run.sh, make, cmake --build ., or a project-specific command.

Round 5 — Optional research context and roadmap

If useful, ask for:

• Baseline numbers, target metrics, or comparison methodology.
• Key papers, documentation, repositories, or prior work.
• An adaptive research roadmap only for a research project when the user has mentioned multi-stage work, a deadline, changing direction from evidence, or explicitly asked for a roadmap. Offer:
  • “Create and maintain it after results that can change the research direction.”
  • “Create an initial roadmap only.”
  • “Skip it.”

If an existing task plan was found, do not offer a separate roadmap by default. Explain that it is the source of truth, and only merge research decision gates into it with explicit permission.

Skip this round when the user is in a hurry or no optional context is useful. Do not infer a roadmap request from “just generate the files”; generate one only when the user explicitly chose it or already asked for it.

Round 6 — Working preferences

Offer three or four adaptive preferences and allow multiple selections. Examples:

• Record failed experiments in project-context/faults.md.
• Profile before optimizing a kernel or system component.
• Explain tradeoffs before changing architecture.
• Update project context after meaningful results or decisions.
• No special preferences.

If “No special preferences” is selected with other options, treat it as the only selection.

Step 2: Generate the context files

Create the following files at the project root. Print a short summary after each file is created or updated:

AGENTS.md
project-context/
├── project-statements.md
├── environment.md
├── rules.md
├── faults.md
├── references.md              # only when references were provided
└── roadmap.md                 # only when the user chose it

Do not generate .claude/, CLAUDE.md, or .claude/settings.json from this skill. Those belong to the Claude Code target.

AGENTS.md — always-on entry point

Keep this file focused on facts and rules Codex must know before every task:

# [Project Name]

> [One-sentence goal]

## Mission
[Core hypothesis or product goal, scope, non-goals, and current status.]

## Environment and commands
- Stack: [languages and frameworks]
- Environment: [local, remote, device, or cloud details]
- Run: `[primary command]`
- Test or benchmark: `[verification command]`

## Guardrails
- [Protected files and important conventions]
- [Communication or review expectations]

## Detailed context
- Read `project-context/project-statements.md` when changing scope or evaluating success.
- Read `project-context/environment.md` before changing setup or execution commands.
- Read `project-context/rules.md` before modifying protected areas.
- Read `project-context/faults.md` before repeating experiments or debugging known issues.
- Read `project-context/references.md` before making claims about listed prior work, when that file exists.
- Read `project-context/roadmap.md` before changing a research direction or interpreting a decision-gate result, when that file exists.

Do not paste a full interview transcript into AGENTS.md. Put details in the linked context files and keep the always-on guidance within Codex’s project instruction budget.

project-context/project-statements.md

# Project Statements

## [Core Hypothesis / Product Goal]
[Specific objective and why it matters.]

## Scope
**In scope:**
- [Included work]

**Out of scope:**
- [Explicit exclusions]

## Success Criteria
| Metric | Target | Notes |
|--------|--------|-------|
| [metric] | [value] | [measurement method] |

## Venue / Deadline
- [Conference, release date, or TBD]

## Current Status
[One sentence describing the current state.]

For research projects, use “Core Hypothesis” and include venue/deadline. For engineering projects, use “Product Goal” and include non-goals.

project-context/environment.md

Include only applicable sections:

# Environment

## Local Machine
- OS: [macOS Apple Silicon, Ubuntu, etc.]
- Constraints: [local limitations]

## Remote Server
- SSH: `[user@host or alias]`
- Working directory: `[path]`
- Environment setup: `[activation command]`

## Target Hardware
- Device: [device or accelerator]
- Constraints: [memory, architecture, power, or latency limits]

## Tech Stack
- Languages: [languages and versions]
- Frameworks: [key frameworks]
- Package manager: [manager]

## How to Run
```bash
[primary command]
[test or benchmark command]

### `project-context/rules.md`

```markdown
# Rules

## Protected files — do not modify without explicit permission
- `[file or directory]` — [reason]

## Conventions
- [Coding and workflow conventions]

## Before certain operations
- [Backup, benchmark, or review requirement]

## Communication
- [Language, comment, reporting, or explanation preference]

Do not invent protected files or constraints. If none were provided, keep the sections and record only a safe general rule such as “Never hardcode credentials.”

When the user selected “Create and maintain it”, add this under ## Workflow:

• After a completed experiment or planned review that can change the research direction, update project-context/roadmap.md with the evidence link and the resulting continue, redirect, or stop decision. Do not change direction for incomplete or invalid results.

project-context/faults.md

Record only user-provided or stack-specific non-obvious pitfalls:

# Known Faults & Pitfalls

## Project-specific
<!-- Add each discovered issue with what happened, how it was found, and the fix. -->
[No project-specific faults recorded yet.]

## Common pitfalls for [stack]
[Only genuinely surprising stack-specific pitfalls; omit this section when none apply.]

project-context/references.md

Create this file only when the user provides papers, documentation, repositories, or other references:

# Key References

| Title | Source | Relation to this project |
|-------|--------|--------------------------|
| [name] | [author, URL, or document] | [baseline, inspiration, or dependency] |

When discussing an item in this table, inspect the actual paper or documentation before making detailed claims. Do not rely on the title alone.

project-context/roadmap.md

Create this file only when the user chose an adaptive research roadmap. Do not generate it for non-research projects, merely because a project has a deadline, or when an existing task plan is already the agreed source of truth. It records long-range research decisions, not daily tasks or raw experiment logs.

# Research Roadmap

> Read `project-statements.md` for the durable goal, scope, and success criteria.

## Update rule
Update this file only after a completed experiment or planned review that can change the research direction. Preserve previous decisions in the history below.

## Current decision gates
| Stage | Research question / hypothesis | Largest uncertainty | Decisive experiment or evidence | Continue / redirect / stop condition | Current decision | Next review |
|-------|--------------------------------|---------------------|---------------------------------|--------------------------------------|------------------|-------------|
| [stage] | [claim to test] | [what could invalidate it] | [smallest useful test] | [quantitative or observable criterion] | [pending] | [date or trigger] |

## Decision history
| Date | New evidence | Decision | Rationale and impact |
|------|--------------|----------|----------------------|
| [date] | [link to record] | [continue / redirect / stop] | [which condition changed and what follows] |

After generation

List the files created or updated and remind the user:

• project-context/faults.md should grow whenever a new non-obvious pitfall is found.
• project-context/project-statements.md should be updated when the goal or scope changes.
• When present, project-context/roadmap.md should be updated only after evidence changes a research decision.
• AGENTS.md should contain only durable, always-on project guidance.