project-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Init Workflow

项目初始化工作流

Initialize a research project as a control root, not just as two sibling repos.

Use this skill when the user wants a new ML research project where agents should work from

<ProjectName>/

while

paper/

code/

, and optional

slides/

remain independent component repositories.

Pair this skill with:

```
research-project-memory
```
to bootstrap cross-component memory
```
init-latex-project
```
to create the paper repo
```
init-python-project
```
to create the code repo
```
new-workspace
```
to create code-owned branches or worktrees
```
remote-project-control
```
when code runs on SSH/HPC servers
```
safe-git-ops
```
before non-trivial Git work

将研究项目初始化为控制根，而非仅仅是两个同级仓库。

当用户希望创建一个新的ML研究项目，且Agent需从

<ProjectName>/

开展工作，同时

paper/

、

code/

和可选的

slides/

保持为独立组件仓库时，使用此技能。

可搭配以下技能使用：

```
research-project-memory
```
：启动跨组件内存
```
init-latex-project
```
：创建论文仓库
```
init-python-project
```
：创建代码仓库
```
new-workspace
```
：创建代码所属分支或工作树
```
remote-project-control
```
：当代码在SSH/HPC服务器上运行时
```
safe-git-ops
```
：在进行复杂Git操作前

Expected Project Shape

预期项目结构

Default shape:

text

<ProjectName>/
├── PROJECT.md
├── AGENTS.md
├── memory/
│   ├── project.yaml
│   ├── component-index.yaml
│   ├── current-status.md
│   ├── decision-log.md
│   ├── claim-board.md
│   ├── evidence-board.md
│   ├── risk-board.md
│   └── action-board.md
├── paper/                 # independent LaTeX git repo
├── code/                  # independent Python/ML git repo
├── code-worktrees/         # sibling worktree root for code repo branches
├── slides/                # optional independent git repo
├── reviewer/              # reviewer simulation state
├── rebuttal/              # real review and response state
├── artifact/              # artifact-evaluation and release handoff state
└── docs/
    ├── updates/
    ├── audits/
    └── timelines/

Do not create a top-level

experiments/

directory by default. Experiment execution, run summaries, result reports, and raw artifact pointers belong inside

code/

or the relevant code worktree.

Recommended code-side evidence paths:

text

code/docs/results/         # stable result summaries, table notes, figure notes
code/docs/reports/         # experiment-report-writer outputs
code/docs/runs/            # run registry, job pointers, config and commit pointers

默认结构：

text

<ProjectName>/
├── PROJECT.md
├── AGENTS.md
├── memory/
│   ├── project.yaml
│   ├── component-index.yaml
│   ├── current-status.md
│   ├── decision-log.md
│   ├── claim-board.md
│   ├── evidence-board.md
│   ├── risk-board.md
│   └── action-board.md
├── paper/                 # 独立的LaTeX git仓库
├── code/                  # 独立的Python/ML git仓库
├── code-worktrees/         # 代码仓库分支的同级工作树根目录
├── slides/                # 可选的独立git仓库
├── reviewer/              # 评审模拟状态
├── rebuttal/              # 真实评审与回复状态
├── artifact/              # 工件评估与发布交接状态
└── docs/
    ├── updates/
    ├── audits/
    └── timelines/

默认不创建顶级

experiments/

目录。实验执行、运行摘要、结果报告和原始工件指针应放在

code/

或相关代码工作树内。

推荐的代码端证据路径：

text

code/docs/results/         # 稳定的结果摘要、表格说明、图表说明
code/docs/reports/         # 实验报告生成器输出
code/docs/runs/            # 运行注册表、任务指针、配置与提交指针

Core Principles

核心原则

```
<ProjectName>/
```
is the agent control root.
```
paper/
```
,
```
code/
```
, and
```
slides/
```
are component repos, not mere folders.
The code component owns algorithm implementation, experiment execution, run records, result reports, remote execution state, and code worktrees.
Code worktrees should not be nested inside
```
code/
```
by default. Use the sibling root
```
code-worktrees/
```
so Git, IDEs, search tools, and agents do not confuse worktrees with normal source files.
Project memory stores durable cross-component state; code docs store code-side experiment details.
Root Git is optional. If enabled, do not accidentally commit nested component repos unless the user explicitly wants submodules.

```
<ProjectName>/
```
是Agent控制根。
```
paper/
```
、
```
code/
```
和
```
slides/
```
是组件仓库，而非单纯的文件夹。
代码组件负责算法实现、实验执行、运行记录、结果报告、远程执行状态和代码工作树。
默认情况下，代码工作树不应嵌套在
```
code/
```
内。使用同级根目录
```
code-worktrees/
```
，避免Git、IDE、搜索工具和Agent将工作树与普通源文件混淆。
项目内存存储持久化的跨组件状态；代码文档存储代码端实验细节。
根级Git为可选配置。若启用，除非用户明确需要子模块，否则不要意外提交嵌套的组件仓库。

Step 1 - Gather Project Information

步骤1 - 收集项目信息

Ask for these fields in one message:

Project name and parent directory.
Research summary: method idea, target problem, datasets, baselines, metrics, and current maturity.
Target venue or milestone, if known.
Component choices:
- paper repo: create new, connect existing, or skip for now
- code repo: create new, connect existing, or skip for now
- slides repo: create new, connect existing, or skip
- reviewer/rebuttal/artifact state dirs: create now or later
Git policy:
- root control-plane git repo: yes/no
- component remotes for paper/code/slides, if available
- whether component repos should be submodules or ignored by root Git
Code worktree policy:
- default sibling root:
```
<ProjectName>/code-worktrees/
```
- remote server worktree root, if different
- branch naming conventions, if any

Wait for the user's answers before creating files.

在一条消息中询问以下信息：

项目名称和父目录。
研究摘要：方法思路、目标问题、数据集、基线、指标和当前成熟度。
目标会议/期刊或里程碑（如有）。
组件选择：
- 论文仓库：新建、连接现有或暂时跳过
- 代码仓库：新建、连接现有或暂时跳过
- 幻灯片仓库：新建、连接现有或跳过
- reviewer/rebuttal/artifact状态目录：现在创建或稍后创建
Git策略：
- 是否启用根级控制平面git仓库
- paper/code/slides的组件远程仓库（如有）
- 组件仓库应作为子模块还是被根级Git忽略
代码工作树策略：
- 默认同级根目录：
```
<ProjectName>/code-worktrees/
```
- 远程服务器工作树根目录（如有不同）
- 分支命名规范（如有）

等待用户回复后再创建文件。

Step 2 - Create the Control Root

步骤2 - 创建控制根

Create:

text

<parent-dir>/<ProjectName>/
├── memory/
├── docs/updates/
├── docs/audits/
├── docs/timelines/
├── reviewer/.agent/
├── rebuttal/.agent/
├── artifact/.agent/
└── code-worktrees/

Create optional

slides/

only when the user wants a slides component now.

If root Git is enabled, initialize it at

<ProjectName>/

and add a root

.gitignore

that ignores component repos and worktrees unless the user explicitly wants submodules:

gitignore

/paper/
/code/
/slides/
/code-worktrees/

If the user wants submodules, use submodule commands deliberately rather than relying on accidental nested Git behavior.

创建：

text

<parent-dir>/<ProjectName>/
├── memory/
├── docs/updates/
├── docs/audits/
├── docs/timelines/
├── reviewer/.agent/
├── rebuttal/.agent/
├── artifact/.agent/
└── code-worktrees/

仅当用户现在需要幻灯片组件时，才创建可选的

slides/

。

若启用根级Git，在

<ProjectName>/

初始化并添加根级

.gitignore

，忽略组件仓库和工作树，除非用户明确需要子模块：

gitignore

/paper/
/code/
/slides/
/code-worktrees/

若用户需要子模块，需刻意使用子模块命令，而非依赖意外的嵌套Git行为。

Step 3 - Bootstrap Project Memory

步骤3 - 启动项目内存

Use

research-project-memory

templates or equivalent files to create:

```
memory/project.yaml
```
```
memory/component-index.yaml
```
```
memory/current-status.md
```
```
memory/decision-log.md
```
```
memory/claim-board.md
```
```
memory/evidence-board.md
```
```
memory/risk-board.md
```
```
memory/action-board.md
```

The component index should record:

yaml

components:
  code:
    path: code
    worktree_root: code-worktrees
    owns:
      - algorithm implementation
      - experiment execution
      - code-side result reports
      - remote execution state
  paper:
    path: paper
    owns:
      - paper claims and narrative
      - figures and tables selected for submission
  slides:
    path: slides
    status: optional
  reviewer:
    path: reviewer
  rebuttal:
    path: rebuttal
  artifact:
    path: artifact

Root memory should store pointers to code-side evidence, not duplicate detailed run logs.

使用

research-project-memory

模板或等效文件创建：

```
memory/project.yaml
```
```
memory/component-index.yaml
```
```
memory/current-status.md
```
```
memory/decision-log.md
```
```
memory/claim-board.md
```
```
memory/evidence-board.md
```
```
memory/risk-board.md
```
```
memory/action-board.md
```

组件索引应记录：

yaml

components:
  code:
    path: code
    worktree_root: code-worktrees
    owns:
      - algorithm implementation
      - experiment execution
      - code-side result reports
      - remote execution state
  paper:
    path: paper
    owns:
      - paper claims and narrative
      - figures and tables selected for submission
  slides:
    path: slides
    status: optional
  reviewer:
    path: reviewer
  rebuttal:
    path: rebuttal
  artifact:
    path: artifact

根级内存应存储指向代码端证据的指针，而非重复详细的运行日志。

Step 4 - Create Root-Level Agent Guidance

步骤4 - 创建根级Agent指引

Write

<ProjectName>/AGENTS.md

It must state:

agents start from
```
<ProjectName>/
```
unless a task is explicitly component-local

use

git -C code ...

git -C paper ...

, and

git -C slides ...

for component repos

code worktrees live under
```
code-worktrees/
```
by default
experiment results live under
```
code/docs/results/
```
,
```
code/docs/reports/
```
,
```
code/docs/runs/
```
, or the same paths inside a code worktree
raw outputs, logs, checkpoints, and wandb/tensorboard caches are not project-root artifacts
project memory gets durable claim/evidence/risk/action summaries
use
```
update-docs
```
during code changes, not only at release time
use
```
add-git-tag
```
for stable code, paper, artifact, or root milestones

编写

<ProjectName>/AGENTS.md

。

必须包含以下内容：

Agent应从
```
<ProjectName>/
```
启动，除非任务明确为组件本地任务

对组件仓库使用

git -C code ...

、

git -C paper ...

和

git -C slides ...

命令

代码工作树默认位于
```
code-worktrees/
```
下
实验结果存储在
```
code/docs/results/
```
、
```
code/docs/reports/
```
、
```
code/docs/runs/
```
或代码工作树内的相同路径
原始输出、日志、检查点和wandb/tensorboard缓存不属于项目根级工件
项目内存存储持久化的声明/证据/风险/行动摘要
在代码变更期间使用
```
update-docs
```
，而非仅在发布时
为稳定的代码、论文、工件或根级里程碑使用
```
add-git-tag
```

Step 5 - Initialize or Connect Component Repos

步骤5 - 初始化或连接组件仓库

Paper

论文

If creating a new paper repo, use

init-latex-project

at:

text

<ProjectName>/paper/

If connecting an existing paper repo, clone or record its path and remote. Then create

paper/.agent/

if missing.

若创建新论文仓库，使用

init-latex-project

在以下路径创建：

text

<ProjectName>/paper/

若连接现有论文仓库，克隆或记录其路径和远程仓库。若缺少

paper/.agent/

则创建该目录。

Code

代码

If creating a new code repo, use

init-python-project

at:

text

<ProjectName>/code/

For ML projects, ensure the code repo has:

text

code/docs/results/
code/docs/reports/
code/docs/runs/

If connecting an existing code repo, do not force a full scaffold. Add missing high-value memory/docs paths only after reporting gaps.

若创建新代码仓库，使用

init-python-project

在以下路径创建：

text

<ProjectName>/code/

对于ML项目，确保代码仓库包含：

text

code/docs/results/
code/docs/reports/
code/docs/runs/

若连接现有代码仓库，不要强制完整搭建。仅在报告缺失后添加高价值的内存/文档路径。

Slides

幻灯片

If requested, create or connect:

text

<ProjectName>/slides/

Slides may be a separate git repo. Create

slides/.agent/

for story, audience, and stale-evidence notes.

若用户要求，创建或连接：

text

<ProjectName>/slides/

幻灯片可以是独立的git仓库。创建

slides/.agent/

用于存储故事线、受众和过时证据记录。

Step 6 - Establish Code Worktree Policy

步骤6 - 确立代码工作树策略

Default policy:

text

main code repo:       <ProjectName>/code/
code worktree root:   <ProjectName>/code-worktrees/
worktree path:        <ProjectName>/code-worktrees/<branch-type>-<branch-name>/

Record this in:

```
memory/project.yaml
```
```
memory/component-index.yaml
```
```
<ProjectName>/AGENTS.md
```
```
code/docs/ops/current-status.md
```
when remote execution is involved

If the remote server only has the code repo, record the remote-specific worktree root in

code/infra/remote-projects.yaml

code/docs/ops/current-status.md

. Do not assume the remote server has

paper/

or root project memory.

默认策略：

text

主代码仓库:       <ProjectName>/code/
代码工作树根目录:   <ProjectName>/code-worktrees/
工作树路径:        <ProjectName>/code-worktrees/<branch-type>-<branch-name>/

将此策略记录在：

```
memory/project.yaml
```
```
memory/component-index.yaml
```
```
<ProjectName>/AGENTS.md
```
涉及远程执行时，记录在
```
code/docs/ops/current-status.md
```

若远程服务器仅包含代码仓库，将远程特定的工作树根目录记录在

code/infra/remote-projects.yaml

或

code/docs/ops/current-status.md

中。不要假设远程服务器存在

paper/

或根级项目内存。

Step 7 - Write PROJECT.md

步骤7 - 编写PROJECT.md

Create

<ProjectName>/PROJECT.md

with:

markdown

undefined

创建

<ProjectName>/PROJECT.md

，内容如下：

markdown

undefined

<ProjectName>

<one-line research description>

<一行研究描述>

Project Control Root

项目控制根

Agents should start from this directory for cross-component work. Component repos are independent.

Agent开展跨组件工作时应从此目录启动。组件仓库相互独立。

Components

组件

Component	Path	Git	Purpose
paper	`paper/`	independent repo	LaTeX paper and paper-facing claims
code	`code/`	independent repo	implementation, experiments, code-side evidence
code worktrees	`code-worktrees/`	linked worktrees of code repo	isolated experiments, baselines, rebuttal fixes
slides	`slides/`	optional independent repo	talks and advisor/lab presentations
reviewer	`reviewer/`	root state dir	simulated reviews and pre-submission risk
rebuttal	`rebuttal/`	root state dir	real reviews, responses, promised revisions
artifact	`artifact/`	root state dir	artifact evaluation and release handoff

组件	路径	Git状态	用途
paper	`paper/`	独立仓库	LaTeX论文及面向论文的声明
code	`code/`	独立仓库	实现、实验、代码端证据
code worktrees	`code-worktrees/`	代码仓库的关联工作树	隔离实验、基线、反驳修正
slides	`slides/`	可选独立仓库	演讲及导师/实验室汇报
reviewer	`reviewer/`	根级状态目录	模拟评审及提交前风险评估
rebuttal	`rebuttal/`	根级状态目录	真实评审、回复、承诺的修订
artifact	`artifact/`	根级状态目录	工件评估与发布交接

Code Evidence Policy

代码证据策略

runnable experiment logic lives in
```
code/experiments/
```
stable code-side result summaries live in
```
code/docs/results/
```
experiment reports live in
```
code/docs/reports/
```
run pointers and job summaries live in
```
code/docs/runs/
```
raw outputs, logs, checkpoints, and wandb/tensorboard caches stay outside Git or in ignored paths
paper-facing evidence is promoted through
```
paper-evidence-board
```
or
```
project-sync
```

可运行的实验逻辑位于
```
code/experiments/
```
稳定的代码端结果摘要位于
```
code/docs/results/
```
实验报告位于
```
code/docs/reports/
```
运行指针和任务摘要位于
```
code/docs/runs/
```
原始输出、日志、检查点和wandb/tensorboard缓存不纳入Git或放在忽略路径中
面向论文的证据通过
```
paper-evidence-board
```
或
```
project-sync
```
提升

Worktree Policy

工作树策略

default root:
```
code-worktrees/
```
naming:
```
<branch-type>-<branch-name>
```
every research worktree needs
```
.agent/worktree-status.md
```
exit condition: merge, continue, park, or kill

默认根目录:
```
code-worktrees/
```
命名规范:
```
<branch-type>-<branch-name>
```
每个研究工作树需包含
```
.agent/worktree-status.md
```
结束条件: 合并、继续、暂停或终止

Memory Policy

内存策略

project-level durable summaries live in
```
memory/
```
component details live in
```
<component>/.agent/
```
code-side run details live in
```
code/docs/
```
volatile scheduler or job state must be re-verified before action

undefined

项目级持久化摘要位于
```
memory/
```
组件细节位于
```
<component>/.agent/
```
代码端运行细节位于
```
code/docs/
```
易失性调度器或任务状态在执行操作前必须重新验证

undefined

Step 8 - Final Summary

步骤8 - 最终总结

Report:

text

Project initialized: <ProjectName>
Control root: <path>

Components:
  paper: <created|connected|skipped>
  code: <created|connected|skipped>
  slides: <created|connected|skipped>
  reviewer/rebuttal/artifact state: <created|deferred>

Code worktree root:
  <ProjectName>/code-worktrees/

Next skills:
  research-project-memory -> inspect or update project state
  new-workspace -> create a code branch/worktree
  remote-project-control -> configure SSH/HPC execution for code
  experiment-design-planner -> plan first experiment matrix

汇报：

text

项目已初始化: <ProjectName>
控制根路径: <path>

组件状态:
  paper: <已创建|已连接|已跳过>
  code: <已创建|已连接|已跳过>
  slides: <已创建|已连接|已跳过>
  reviewer/rebuttal/artifact状态: <已创建|已推迟>

代码工作树根目录:
  <ProjectName>/code-worktrees/

后续推荐技能:
  research-project-memory -> 检查或更新项目状态
  new-workspace -> 创建代码分支/工作树
  remote-project-control -> 为代码配置SSH/HPC执行环境
  experiment-design-planner -> 规划首个实验矩阵

Final Sanity Check

最终检查

Before finishing:

root agent guidance exists
root memory files exist or are explicitly deferred
```
paper/
```
,
```
code/
```
, and
```
slides/
```
Git boundaries are clear
```
code-worktrees/
```
policy is recorded
there is no top-level
```
experiments/
```
directory unless the user explicitly requested it
code-side evidence paths are inside
```
code/docs/
```
component remotes and root Git policy are not ambiguous

完成前确认：

根级Agent指引已存在
根级内存文件已存在或已明确推迟创建
```
paper/
```
、
```
code/
```
和
```
slides/
```
的Git边界清晰
```
code-worktrees/
```
策略已记录
除非用户明确要求，否则不存在顶级
```
experiments/
```
目录
代码端证据路径位于
```
code/docs/
```
内
组件远程仓库和根级Git策略无歧义