academic-army 0.1.0

package/mcp-server/deepresearch/tools.py

@@ -0,0 +1,33 @@
+import os
+import time
+
+from openai import OpenAI
+
+
+def deepresearch(prompt: str) -> dict:
+    client = OpenAI()
+    response = client.responses.create(
+        model="gpt-5.5",
+        reasoning={"effort": "high"},
+        tools=[{"type": "web_search"}],
+        tool_choice="auto",
+        include=["web_search_call.action.sources"],
+        background=True,
+        input=prompt,
+    )
+    deadline = time.monotonic() + 3600
+
+    while response.status in {"queued", "in_progress"}:
+        if time.monotonic() > deadline:
+            raise TimeoutError(f"OpenAI response did not complete within 3600 seconds; response_id={response.id}")
+        time.sleep(1)
+        response = client.responses.retrieve(response.id)
+
+    return response.model_dump(mode="json")
+
+
+def register_deepresearch(mcp) -> None:
+    if not os.environ.get("OPENAI_API_KEY"):
+        raise RuntimeError("DeepResearch MCP startup validation failed: OPENAI_API_KEY is not set in the environment or current .env")
+    OpenAI()
+    mcp.tool()(deepresearch)

package/mcp-server/requirements.txt

@@ -0,0 +1,4 @@
+mcp[cli]>=1.27.1
+openai>=2.38.0
+python-dotenv>=1.2.2
+tomlkit>=0.13.3

package/metaskills/README.md

@@ -0,0 +1,131 @@
+# Metaskills
+
+`metaskills` stores the design notes and self-evolve workflow used to build and improve AcademicArmy skills.
+
+[中文说明](README.zh-CN.md)
+
+## Why This Directory Exists
+
+The core design idea is skill self-evolve: use one evaluator agent to judge the output produced by a skill, pass that evaluation to a modifier agent, let the modifier revise the skill, and repeat the loop until the skill becomes better through concrete output, critique, and revision.
+
+A normal skill describes how an agent should complete a research-planning task. A metaskill describes how that skill itself should be designed: its goals, writing style, expected outputs, and the issues to watch for when revising it. During self-evolve, the evaluator uses the metaskill as the standard for judging the artifact, and the modifier uses it as the standard for revising the skill.
+
+## When To Use This Workflow
+
+If a skill's output is unsatisfactory, improve the matching metaskill first instead of editing the skill from vague impressions.
+
+This is especially useful for the three planning skills used at the start of the AcademicArmy workflow: `academic-army-architect`, `academic-army-experiment-plan`, and `academic-army-coding-plan`. When their direct outputs are not what you want, write the dissatisfaction into the matching metaskill and run several `envolve.sh` rounds.
+
+## Quick Start
+
+### 1. Pick the matching metaskill
+
+Prepared AcademicArmy skill metaskills:
+
+| Skill | Edit this file | Run this script |
+|---|---|---|
+| `academic-army-architect` | [`academic-army-architect/METASKILL.md`](academic-army-architect/METASKILL.md) | [`academic-army-architect/envolve.sh`](academic-army-architect/envolve.sh) with `bash` |
+| `academic-army-experiment-plan` | [`academic-army-experiment-plan/METASKILL.md`](academic-army-experiment-plan/METASKILL.md) | [`academic-army-experiment-plan/envolve.sh`](academic-army-experiment-plan/envolve.sh) with `bash` |
+| `academic-army-coding-plan` | [`academic-army-coding-plan/METASKILL.md`](academic-army-coding-plan/METASKILL.md) | [`academic-army-coding-plan/envolve.sh`](academic-army-coding-plan/envolve.sh) with `bash` |
+| `academic-army-repo-scaffold` | [`academic-army-repo-scaffold/METASKILL.md`](academic-army-repo-scaffold/METASKILL.md) | [`academic-army-repo-scaffold/envolve.sh`](academic-army-repo-scaffold/envolve.sh) with `bash` |
+| `academic-army-coding-style` | [`academic-army-coding-style/METASKILL.md`](academic-army-coding-style/METASKILL.md) | [`../runs/develop-skill.sh`](../runs/develop-skill.sh) with `bash` |
+
+Before calling `evolve-skill` for `academic-army-architect`, create or confirm [`academic-army-architect/ENVOLVETASK.md`](academic-army-architect/ENVOLVETASK.md). This fixed task is what the runner uses to test the architect skill across evolution rounds.
+
+The `academic-army-repo-scaffold` metaskill defines the template-first repository initialization skill: generate a real starter repo from a selected initializer or template, overlay `data/`, `output/`, `results/`, and `harness/`, write repo-local installation instructions, configure installable dependencies without running installation, record reference-only sources, preserve the template's test layout, and keep README text objective and present-state.
+
+The `academic-army-coding-style` metaskill defines the code structure and style preferences used by code-writing agents. Add any durable preference about concise code, module boundaries, dependency choices, review standards, naming, or repository-local style to [`academic-army-coding-style/METASKILL.md`](academic-army-coding-style/METASKILL.md), then use [`runs/develop-skill.sh`](../runs/develop-skill.sh) to update [`skills/academic-army-coding-style/SKILL.md`](../skills/academic-army-coding-style/SKILL.md) from real developing trajectories.
+
+### 2. Add concrete tips
+
+Open the corresponding metaskill file and add concrete tips about the failure mode: what the artifact did wrong, what the skill should prefer, and what it should avoid next time.
+
+The metaskill design document for a target skill should describe what the skill is trying to produce, what good output looks like, what common failure modes matter, and what should stay out of the skill.
+
+### 3. Run the prepared script
+
+Install dependencies once:
+
+```bash
+npm install
+```
+
+Run a prepared skill evolution script from the repository root:
+
+```bash
+bash metaskills/academic-army-architect/envolve.sh
+```
+
+Run the prepared script to call the `evolve-skill` pipeline with that skill's paths. See [`src/evolve-skill/README.md`](../src/evolve-skill/README.md) for what the script runs and how the loop behaves.
+
+### 4. Inspect the new artifact
+
+Inspect the new artifact and repeat if the skill is still not stable enough.
+
+Running the linked evolution scripts calls the TypeScript `evolve-skill` pipeline. See [`src/README.md`](../src/README.md) for the TypeScript entry points and [`src/evolve-skill/README.md`](../src/evolve-skill/README.md) for the evolution loop implementation.
+
+## What The Evolution Loop Does
+
+AcademicArmy skills are developed through an iterative meta-skill workflow rather than written once and treated as final.
+
+We first draft an initial version of the skill. The prompts and notes used for this initial drafting process are kept in the matching [`metaskills`](.) directory, so readers can inspect how the skill itself was produced.
+
+After that, we choose a fixed test topic and repeatedly run the following loop:
+
+1. Execute the skill on the fixed topic.
+2. Give the skill output, together with the relevant records from `metaskills`, to an evaluator agent.
+3. Ask that agent to analyze the skill carefully: what problems it has, which parts are redundant, and where its language, structure, or content can be improved.
+4. Give the resulting revision suggestions to Codex and ask Codex to update the skill.
+5. Execute the revised skill again on the same fixed topic.
+
+This loop lets us compare different versions under a stable task setting. The goal is to make each skill more precise, less redundant, and easier for future agents to execute consistently.
+
+Running the scripts calls the TypeScript [`evolve-skill`](../src/evolve-skill/README.md) pipeline, which is different from a direct single skill run: it uses fresh runner agents to produce artifacts on fixed tasks, an evaluator agent to judge those artifacts against the metaskill, and a modifier agent to revise the skill itself. Repeating that loop usually improves the next direct output from the skill.
+
+## Directory Layout
+
+Each skill can have a matching folder under `metaskills`:
+
+```text
+metaskills/
+  academic-army-architect/
+    METASKILL.md
+    ENVOLVETASK.md
+    envolve.sh
+```
+
+[`METASKILL.md`](academic-army-architect/METASKILL.md) records the skill's design goals and tips.
+
+[`ENVOLVETASK.md`](academic-army-architect/ENVOLVETASK.md) is the fixed task used to test the skill during evolution.
+
+[`envolve.sh`](academic-army-architect/envolve.sh) runs the evolution loop for that skill. The file name is kept as `envolve.sh` to match the current project convention.
+
+The shared runner is the `evolve-skill` pipeline, not part of each individual skill's metaskill folder. See [`src/evolve-skill/README.md`](../src/evolve-skill/README.md) for the TypeScript implementation.
+
+In this structure, [`METASKILL.md`](academic-army-architect/METASKILL.md) and [`ENVOLVETASK.md`](academic-army-architect/ENVOLVETASK.md) provide the required inputs to the `evolve-skill` pipeline. The local [`envolve.sh`](academic-army-architect/envolve.sh) file is only a convenience command that fills in those paths for one specific skill, including the artifact output folder.
+
+## Language Contract
+
+When a metaskill designs or revises a planning skill, keep the artifact-language contract fixed: the AI-facing plan is English, and the human-facing explanation is Chinese. For the current planning skills this means `paper_blueprint.md`, `experiment_plan.md`, and `coding_plan.md` stay English-only, while `paper_blueprint.explain.md`, `experiment_plan.explain.md`, and `coding_plan.explain.md` use Chinese explanations with English technical identifiers preserved when useful.
+
+## Add A New Metaskill
+
+Create a folder under `metaskills` with:
+
+```text
+METASKILL.md
+ENVOLVETASK.md
+envolve.sh
+```
+
+Write the fixed evolution task as a representative task. It should be stable enough that different skill versions can be compared across rounds.
+
+Copy an existing [`envolve.sh`](academic-army-architect/envolve.sh) and update the paths.
+
+## Troubleshooting
+
+| Problem | Likely cause | Fix |
+|---|---|---|
+| The skill output is still not stable enough | The metaskill guidance is still too vague or incomplete. | Add concrete tips about the failure mode and repeat the evolution script. |
+| Different versions are hard to compare | The fixed evolution task is not stable enough. | Rewrite `ENVOLVETASK.md` as a representative fixed task. |
+| The script fails before the loop starts | Dependencies or pipeline config are missing. | Run `npm install` and check the TypeScript entry points and config paths. |

package/metaskills/README.zh-CN.md

@@ -0,0 +1,131 @@
+# Metaskills
+
+`metaskills` 用来保存 AcademicArmy skills 的设计说明和 self-evolve 工作流。
+
+[English README](README.md)
+
+## 为什么有这个目录
+
+核心设计思想是 skill self-evolve：用一个 evaluator agent 评价某个 skill 产出的 artifact，把评价交给一个 modifier agent，让 modifier 根据评价修改这个 skill，然后不断循环。这样 skill 不是靠一次性手工编写变好，而是通过稳定任务下的真实输出、具体评价和针对性修改逐轮提升。
+
+普通 skill 描述 agent 应该如何完成某个研究规划任务。metaskill 描述这个 skill 本身应该如何设计：它的目标、写作方式、预期输出，以及修改时需要重点检查的问题。在 self-evolve 中，evaluator 用 metaskill 作为评价 artifact 的标准，modifier 用 metaskill 作为修改 skill 的标准。
+
+## 什么时候使用
+
+如果觉得某个 skill 的输出不满意，先修改对应的 metaskill，而不是凭模糊印象直接改 skill。
+
+这对 AcademicArmy 开头使用的三个规划类 skill 尤其重要：`academic-army-architect`、`academic-army-experiment-plan` 和 `academic-army-coding-plan`。如果它们直接生成的产物不满意，就把不满意点写进对应 metaskill，再运行几轮 `envolve.sh`。
+
+## 快速开始
+
+### 1. 找到对应 metaskill
+
+当前已准备的 AcademicArmy skill metaskill 如下：
+
+| Skill | 修改这个文件 | 运行这个脚本 |
+|---|---|---|
+| `academic-army-architect` | [`academic-army-architect/METASKILL.md`](academic-army-architect/METASKILL.md) | 用 `bash` 运行 [`academic-army-architect/envolve.sh`](academic-army-architect/envolve.sh) |
+| `academic-army-experiment-plan` | [`academic-army-experiment-plan/METASKILL.md`](academic-army-experiment-plan/METASKILL.md) | 用 `bash` 运行 [`academic-army-experiment-plan/envolve.sh`](academic-army-experiment-plan/envolve.sh) |
+| `academic-army-coding-plan` | [`academic-army-coding-plan/METASKILL.md`](academic-army-coding-plan/METASKILL.md) | 用 `bash` 运行 [`academic-army-coding-plan/envolve.sh`](academic-army-coding-plan/envolve.sh) |
+| `academic-army-repo-scaffold` | [`academic-army-repo-scaffold/METASKILL.md`](academic-army-repo-scaffold/METASKILL.md) | 用 `bash` 运行 [`academic-army-repo-scaffold/envolve.sh`](academic-army-repo-scaffold/envolve.sh) |
+| `academic-army-coding-style` | [`academic-army-coding-style/METASKILL.md`](academic-army-coding-style/METASKILL.md) | 用 `bash` 运行 [`../runs/develop-skill.sh`](../runs/develop-skill.sh) |
+
+对 `academic-army-architect` 调用 `evolve-skill` 前，先创建或确认 [`academic-army-architect/ENVOLVETASK.md`](academic-army-architect/ENVOLVETASK.md)（Windows 路径：`metaskills\academic-army-architect\ENVOLVETASK.md`）。这个固定任务是 runner 在 evolution 轮次中测试 architect skill 的输入。
+
+`academic-army-repo-scaffold` 这个 metaskill 定义 template-first 的仓库初始化 skill：先用选定 initializer 或 template 生成真实 starter repo，再叠加 `data/`、`output/`、`results/` 和 `harness/`；写出 repo-local 安装说明；配置可安装依赖但不执行安装；记录只能作为参考的外部来源；保留模板决定的测试结构；README 只客观说明当前仓库结构和用法。
+
+`academic-army-coding-style` 这个 metaskill 定义写代码 agent 使用的代码结构和代码风格偏好。任何关于 concise code、module boundaries、dependency choices、review standards、naming 或 repo-local style 的长期偏好，都写进 [`academic-army-coding-style/METASKILL.md`](academic-army-coding-style/METASKILL.md)，然后用 [`runs/develop-skill.sh`](../runs/develop-skill.sh) 根据真实 developing trajectories 更新 [`skills/academic-army-coding-style/SKILL.md`](../skills/academic-army-coding-style/SKILL.md)。
+
+### 2. 补充具体 tips
+
+打开对应的 metaskill 文件，在里面补充具体 tips：这次 artifact 哪里不好、后续应该更偏向什么写法、应该避免什么问题。
+
+metaskill 设计文档应该说明目标 skill 想产出什么、什么样的输出算好、哪些常见失败模式需要避免，以及哪些内容不应该写进 skill。
+
+### 3. 运行预设脚本
+
+首次使用先安装依赖：
+
+```bash
+npm install
+```
+
+在仓库根目录运行某个已经准备好的 evolution 脚本：
+
+```bash
+bash metaskills/academic-army-architect/envolve.sh
+```
+
+运行这个脚本时，会用该 skill 对应的路径调用 `evolve-skill` pipeline。脚本实际运行内容和 loop 行为见 [`src/evolve-skill/README.zh-CN.md`](../src/evolve-skill/README.zh-CN.md)。
+
+### 4. 检查新一轮 artifact
+
+检查新一轮 artifact；如果还不稳定，就继续补充 tips 并再次运行。
+
+运行这些已链接的 evolution 脚本时，会调用 TypeScript 的 `evolve-skill` pipeline。TypeScript 入口和目录结构见 [`src/README.zh-CN.md`](../src/README.zh-CN.md)，skill evolution loop 的实现见 [`src/evolve-skill/README.zh-CN.md`](../src/evolve-skill/README.zh-CN.md)。
+
+## Evolution loop 做什么
+
+AcademicArmy 的 skill 不是一次性写完就固定下来，而是通过一套 meta-skill 迭代流程逐步打磨。
+
+我们会先初步编写一个 skill。这个阶段用到的相关 prompt 和记录保存在对应的 [`metaskills`](.) 目录中，方便读者查看这个 skill 最初是如何被制作出来的。
+
+随后，我们选择一个固定选题，并围绕这个选题反复运行下面的循环：
+
+1. 执行当前版本的 skill。
+2. 把 skill 的输出和 `metaskills` 中的相关记录一起交给 evaluator agent。
+3. 让 evaluator agent 仔细分析当前 skill 存在哪些问题：有没有冗余的地方，语言是否清晰，内容是否完整，结构是否适合后续 agent 稳定执行。
+4. 把修改意见交给 Codex，让 Codex 修改 skill。
+5. 再次执行修改后的 skill，并继续用同一个固定选题检验效果。
+
+这个循环的作用是让不同版本的 skill 在稳定任务条件下可比较。我们的目标是逐步减少冗余、修正表达和内容问题，并让每个 skill 更容易被后续 agent 一致地执行。
+
+运行这些脚本时，会调用 TypeScript 的 [`evolve-skill`](../src/evolve-skill/README.zh-CN.md) pipeline；它不同于直接运行一次 skill，而是一个简单的 multi-agent loop：新的 runner agents 在固定任务上生成产物，evaluator agent 按 metaskill 评价这些产物，modifier agent 根据评价修改 skill 本身。这个循环多跑几轮，通常能让下一次直接运行 skill 的输出更接近预期。
+
+## 目录结构
+
+每个 skill 可以在 `metaskills` 下有一个对应目录：
+
+```text
+metaskills/
+  academic-army-architect/
+    METASKILL.md
+    ENVOLVETASK.md
+    envolve.sh
+```
+
+[`METASKILL.md`](academic-army-architect/METASKILL.md) 记录这个 skill 的设计目标和 tips。
+
+[`ENVOLVETASK.md`](academic-army-architect/ENVOLVETASK.md) 是 evolution 时固定使用的测试任务。
+
+[`envolve.sh`](academic-army-architect/envolve.sh) 用来运行这个 skill 的 evolution loop。文件名保留为 `envolve.sh`，和当前项目约定一致。
+
+共享 runner 是 `evolve-skill` pipeline，不属于每个 skill 自己的 metaskill 目录。TypeScript 实现见 [`src/evolve-skill/README.zh-CN.md`](../src/evolve-skill/README.zh-CN.md)。
+
+在这个目录结构里，[`METASKILL.md`](academic-army-architect/METASKILL.md) 和 [`ENVOLVETASK.md`](academic-army-architect/ENVOLVETASK.md) 为 `evolve-skill` pipeline 提供必需输入。当前目录下的 [`envolve.sh`](academic-army-architect/envolve.sh) 只是一个便捷命令：它把某个具体 skill 的 `--skill-path`、`--artifact-path` 输出文件夹、`--metaskill-path` 和 `--task-path` 填好，然后调用共享 runner。
+
+## 语言契约
+
+metaskill 在设计或修改规划类 skill 时，固定采用同一个产物语言契约：面向 AI 执行的主计划使用英文，面向用户确认的解释文件使用中文。当前规划类 skills 中，`paper_blueprint.md`、`experiment_plan.md` 和 `coding_plan.md` 保持 English-only；`paper_blueprint.explain.md`、`experiment_plan.explain.md` 和 `coding_plan.explain.md` 使用中文解释，并在有助于准确表达时保留英文技术标识符。
+
+## 新增 Metaskill
+
+在 `metaskills` 下创建一个新目录，包含：
+
+```text
+METASKILL.md
+ENVOLVETASK.md
+envolve.sh
+```
+
+固定 evolution task 应该是一个有代表性的固定任务，方便不同版本的 skill 在多轮迭代中进行对比。
+
+可以复制已有的 [`envolve.sh`](academic-army-architect/envolve.sh)，然后修改其中的路径。
+
+## 常见问题
+
+| 问题 | 常见原因 | 解决办法 |
+|---|---|---|
+| Skill 输出仍然不稳定 | Metaskill guidance 仍然太模糊或不完整。 | 继续补充具体 failure mode 和 tips，然后再次运行 evolution 脚本。 |
+| 不同版本难以比较 | 固定 evolution task 不够稳定。 | 把 `ENVOLVETASK.md` 改成更有代表性的固定任务。 |
+| 脚本在 loop 开始前失败 | 依赖或 pipeline config 缺失。 | 运行 `npm install`，并检查 TypeScript 入口和 config 路径。 |

package/metaskills/academic-army-architect/METASKILL.md

@@ -0,0 +1,91 @@
+这个skill属于一套基于Codex的autoresearch工具链，任务是为论文生成战略层面的paper blueprint，而不是生成完整论文、实验计划、绘图计划或面向用户的建议清单。
+论文蓝图主要是给后续AI规划skill读取和继承的，不是主要给人看的；因此蓝图应像一份可实施的论文战略方案，客观描述论文方案、核心信息、目标、约束和开放变量。
+skill应默认承担战略判断责任，但不应伪造实验结论；凡是能由用户已明确内容和deepresearch推出明显最优选择的项目，应直接形成蓝图决策，凡是必须通过实验比较才能判断的方法组合或改进路线，应形成候选方法空间并交给后续实验规划skill收敛，而不是作为用户开放验证项反复询问。
+后续还会运行论文内容编排规划、实验规划、绘图规划等更具体的skill；本skill只负责明确能支撑后续规划的核心论文信息，不应提前细化section段落、实验表、figure layout、实现步骤或战术级选择。
+paper blueprint skill只定义论文蓝图生成这一项任务的领域逻辑；工具权限、沙盒限制、文件读取方式、MCP故障、命令fallback等运行环境问题属于上层agent/tooling规范，不应写进skill，也不应出现在任何输出文件中。
+
+skill应明确使用来自`academic_army_mcp_tools`的deepresearch工具；这个工具本质是把prompt通过OpenAI API转发给带web search能力的GPT-5.5，因此目标venue、高引论文、近期写作风格、autoresearch工具现状等动态信息应现场检索，不必硬编码进skill。
+
+`paper_blueprint.md`和`paper_blueprint.explain.md`都是Markdown文件；`paper_blueprint.md`只包含英文论文蓝图，`paper_blueprint.explain.md`只包含中文论文蓝图解释，skill中必须明确两个文件的内容边界，避免互相混入。
+`paper_blueprint.md`固定用英文输出；`paper_blueprint.explain.md`固定用中文输出，但可以自然保留英文论文标题、会议名、数据集、benchmark、method name和技术术语。
+中英混排要自然：中文解释应以中文句子为主体，英文术语只在保留原名更准确、更符合领域习惯时出现，术语命名应稳定一致，避免机械翻译和反复中英文并列。
+
+skill应调研SIGGRAPH、CVPR、SIGCOMM、NSDI等顶级会议中的高引论文，分析它们为什么优秀，并提炼问题定义、贡献定位、storytelling、证据链、实验说服力、领域影响等方面的共性模式。
+skill输出的`paper_blueprint.explain.md`中应针对目标venue和相关领域分析高引论文的优点，并把这些优秀模式用于解释当前蓝图中的取舍。
+分析写作手法和storytelling时，使用的论文必须较新，以反映当前审稿人偏好的叙事方式和写作风格；分析method、数据集、benchmark、baseline、技术背景时，可以使用稍早但仍有代表性的经典论文。
+
+编写skil时应使用`academic_army_mcp_tools`里的deepresearch调研相关autoresearch工具、论文、开源代码、benchmark、agent workflow和prompt设计案例，并根据具体发现提炼对当前skill有用的设计模式。调研对象不限于相关autoresearch工具，也可以包括autoresearch论文、open-source code、agent workflow、paper-writing agent、literature-review agent、scientific discovery agent、prompt template和benchmark。
+
+一个优秀的论文蓝图应明确论文的核心idea、核心问题、目标读者、目标venue、领域语境、审稿预期，以及为什么这个问题对该venue的读者重要。
+蓝图应明确现有方法、系统、数据集、benchmark或理论框架的关键不足，并说明本文与已有工作的差异化定位。
+蓝图应明确论文希望审稿人相信的1到3个核心claim，以及每个claim需要哪类证据支撑。
+蓝图应明确论文的贡献形态，例如method、system、dataset、benchmark、analysis、theory、measurement、application insight等，并说明这些贡献如何共同服务核心claim。
+蓝图应明确method或系统设计背后的高层逻辑，但不展开具体模块实现、参数设置、训练细节或工程步骤。
+蓝图应明确实验或评估的战略目标，例如要证明有效性、泛化性、鲁棒性、效率、可解释性、实际部署价值或领域洞察，但不提前生成具体实验表格和逐项实验安排。
+蓝图应明确数据集、benchmark、baseline和metric的选择原则，而不是过早固定所有战术配置。
+蓝图应明确最小充分证据链，即论文至少需要哪些证据才能让核心claim成立。
+蓝图应明确各部分如何共同支撑核心claim，使后续内容规划、实验规划和绘图规划都能围绕同一条认知路径展开。
+蓝图应明确论文最重要的风险点和薄弱环节，但这些风险点应作为论文方案中的开放变量或后续规划重点，而不是写成面向用户的提醒。
+蓝图应明确哪些信息已经由用户指定，哪些信息仍是开放变量；已经被用户明确指定的内容应被当作设计约束，而不是再次变成“需要验证的问题”。
+蓝图应明确后续skill需要继承的核心约束，例如叙事目标、核心claim、证据需求、术语命名、目标venue偏好、贡献边界和读者认知路径。
+蓝图应偏向战略规划，减少让用户在多个精确战术方向上做选择；当信息不足时，应先基于用户已明确内容和deepresearch结果做综合判断，能判断出明显最优选择的项目应直接纳入蓝图，只有无法可靠判断且会实质性影响论文战略的项目才标为开放变量。
+“开放验证项”应是最后手段，不是默认输出；skill在提出开放验证项前，必须先尝试基于用户已经明确的内容、deepresearch调研结果、目标venue偏好、相关论文模式和论文自身目标做出综合判断。
+如果某个项目可以从用户已确定信息和deepresearch结果中推导出明显更优的选择，skill应直接在论文蓝图中采用该选择；但如果该项目属于“必须通过实验结果才能判断优劣的方法组合、模块改进或实现路线”，skill应输出候选方法空间和实验收敛路径，而不是假装已经知道最佳方法。
+skill做选择时应以“对当前论文最有利”为标准综合评判，而不是机械保持中立；可考虑但不限于问题定位是否更清晰、是否更符合目标venue、是否更能支撑核心claim、是否更容易形成强贡献、证据链是否更可执行、是否降低审稿风险、是否便于后续内容规划、实验规划和绘图规划继承。
+“明显最优选择”的判断标准不应在tips里写死成固定打分表；编写skill的agent和运行skill的agent都应根据当前论文类型、目标venue、用户输入和deepresearch结果现场判断哪些因素最重要。
+当skill直接选择某个方案时，`paper_blueprint.md`中应只写被选中的论文方案，不要保留“方案A/方案B/请用户选择”式分叉结构，除非这些分叉本身就是论文战略中必须保留的开放变量。
+当skill直接选择某个方案时，`paper_blueprint.explain.md`应解释选择理由：说明这个选择如何来自用户已明确内容、目标venue偏好、相关高质量论文模式、核心claim需求和后续规划约束。
+如果存在多个可行选项，但其中一个在论文战略上明显更稳妥、更有说服力或更符合目标venue，skill应选择该选项，并在解释文件中简要说明为什么没有采用其他主要备选方向。
+可以把skill做成目标导向：先明确idea，再将idea分解为若干论文目标，然后围绕目标组织蓝图中的问题定位、贡献策略、证据策略、venue fit和后续规划约束。
+蓝图中的每个目标都应服务核心claim，并能指导后续skill展开内容、实验或图表规划。
+蓝图解释中应解释每个目标背后的思想、目标之间的联系，以及蓝图中的安排如何帮助论文达成这些目标。
+
+蓝图结构采用清晰标题和局部条目，而不是复杂全局编号；每个section可以有自己的1、2、3，但不要使用C1/C2/C3/B1/B2/B3这类需要反复回看的编号系统。
+推荐蓝图包含类似Core Thesis、Paper Goals、Target Venue Fit、Contribution Strategy、Evidence Strategy、Positioning Against Prior Work、Downstream Planning Constraints等战略性section。
+`paper_blueprint.explain.md`的主要功能是帮助用户确认`paper_blueprint.md`中的项目是否合理，而不是解释skill流程、模板设计或工具调用过程。
+解释文件应让用户理解整篇论文的核心出发点，也就是“为什么要这么写”，并说明蓝图中每个细节如何从这些出发点推导出来，从而使得用户看到不合理内容时可以通过解释文件判断是哪个核心出发点错了，还是从核心出发点推导到具体安排的中间环节错了。
+解释文件应包含对论文蓝图重点内容的概括，不能只有解释；每段解释前应先复述对应蓝图正文内容，让解释文件可以相对独立阅读，不必频繁对照蓝图文件。
+解释文件应按蓝图标题顺序逐条解释重要内容，说明每条蓝图内容与核心思想、其他部分、核心claim、venue偏好、证据链和后续规划之间的关系。
+解释文件应避免大量跨引用编号，不要使用c1/c2/c3/b1/b2/b3式引用；section已有标题时，应优先用标题、自然简称或近义表达指代对应部分。
+解释文件的写法应更像对论文方案的清晰讲解，而不是对模板字段的逐项说明；不要到处写“见第几条”“对应B2”这类需要跳转理解的表达。
+
+解释文件开头应记录“用户已经明确的内容”，例如idea、目标venue、领域、方法方向、数据集、benchmark、技术限制、写作偏好等；这部分只放在解释文件，不放进蓝图文件。后续用户用skill修改蓝图时，“用户已经明确的内容”应持续累积，并作为之后生成和修改蓝图的设计约束。
+“需要验证的问题”或“开放验证项”应与“用户已经明确的内容”联动：每次生成或修改时先检查某个问题是否已被用户明确指定，若已指定则转化为已确认约束；若未指定，也应先综合用户已明确内容和deepresearch结果判断是否存在明显最优选择，只有无法可靠判断且确实影响蓝图合理性时才保留为开放验证项。
+只有当某个问题依赖用户私有偏好、资源条件、未公开实验条件、真实项目限制，或者deepresearch和现有信息不足以判断哪种选择明显更优时，才应保留为开放验证项；如果问题本质上需要实验比较才能回答，则应进入“候选方法/候选实验路线”，而不是进入用户开放验证项。
+保留开放验证项时，也应尽量给出默认推荐方向；不要只把问题抛给用户，而应说明当前蓝图暂时采用或倾向于哪个方向，以及什么信息会改变这个判断。
+开放验证项应尽量少而关键，只保留需要用户补充信息才能解决、且会实质性改变论文定位、核心claim、贡献边界、证据链或后续规划约束的问题；需要实验结果才能解决的方法优劣问题，应交给后续实验规划skill处理。
+开放验证项应先说明为什么当前无法从用户已明确内容和deepresearch结果中推出明显最优选择，再说明它影响哪个设计选择、关联哪个核心出发点，以及如果该项变化，蓝图中哪些部分可能需要调整。
+随着用户明确的信息越来越多、deepresearch调研越充分，开放验证项应越来越少；skill应主动把可判断的问题转化为蓝图中的确定选择，而不是继续保持开放问题。
+每次修改蓝图时，skill应重新检查已有开放验证项：如果新用户输入或deepresearch结果已经足以支持一个合理选择，就应删除该开放验证项并把选择写入蓝图。
+解释文件中的开放验证项不应写成“你需要验证的问题”这种用户待办语气，而应写成“当前仍会影响蓝图合理性的开放变量”，并说明为什么它尚未能被用户已知信息和deepresearch结果解决。
+
+在“具体用什么方法”这类问题上，skill不应默认选择唯一最终方法，因为很多论文的最终方法通常来自对一种或多种已有方法的组合、改进、替换或消融，真实效果需要后续实验才能判断。
+对于依赖实验结果才能判断优劣的方法选择，论文蓝图应先构建“理论上可行的方法空间”，而不是提前输出一个看似确定但未经实验支持的最终method。
+skill应使用`academic_army_mcp_tools`里的deepresearch调研相关方法、近期高质量论文、可复现代码、常用baseline、benchmark结果和已有方法组合方式，分析哪些方法可以作为基础方法、哪些部分可能被组合、哪些模块或机制可能成为创新点。
+方法空间探索不应写成固定模板；编写skill的agent应根据当前研究问题、目标venue、领域惯例和deepresearch结果，现场判断需要调研哪些方法族、组件、组合路径和改进方向。
+论文蓝图可以给出一批理论上可行的方法组合和改进方案，例如“以方法A为主干，引入方法B的模块，并在关键瓶颈处加入新的改进点”；但这些方案应被标记为后续实验规划skill需要评估的候选路线，而不是当前论文已经确定的最终结论。
+如果多个方法组合都理论上可行，但没有实际实验结果无法判断优劣，skill不应臆断哪个一定最好；应把它们组织成候选方法族，并说明每个候选方案可能支撑什么claim、可能带来什么优势、可能对应什么审稿风险。
+这类“实验后才能选择”的方法候选不应放进普通“开放验证项”，因为它不是要求用户凭主观判断来选择，而是要求后续实验规划skill设计实验、运行实验、比较结果后选择。
+蓝图中应区分“已确定的战略方法方向”和“待实验选择的候选实现路线”：前者服务论文定位和核心claim，后者交给后续实验规划skill通过实验结果收敛。
+在这种机制下，`paper_blueprint.md`中可以保留方法候选空间，但应保持战略粒度，例如说明候选方法组合、潜在改进点、与核心claim的关系、后续实验需要比较的方向，而不是展开到训练细节、参数设置或具体实验表。
+如果某些方法组合未来被证明效果最好，它们的完整版本可以成为论文的proposed method；其他候选方法或去掉关键改进点后的版本，则可以在后续实验规划中转化为baseline、ablation baseline或variant baseline。
+skill应提醒后续实验规划skill：baseline不只是已有方法原版，也可能包括“候选方法去掉本文改进点后的版本”“只使用单一基础方法的版本”“只使用部分组合模块的版本”或“替换关键模块的版本”；具体baseline集合由后续实验规划根据资源和公平性确定。
+论文蓝图应明确候选方法之间的公平比较原则，例如尽量控制数据、训练预算、输入输出形式、评估协议和实现质量；但具体实验设计、运行预算、超参数搜索和结果表格应留给实验规划skill。
+`paper_blueprint.explain.md`中应解释为什么当前没有直接选择唯一方法：原因不是蓝图不完整，而是方法优劣依赖后续实验结果，当前阶段更合理的产物是一组由文献调研支持的候选方法组合和改进方向。
+`paper_blueprint.explain.md`中应解释每个候选方法组合的来源、理论动机、与核心idea的关系、可能作为创新点的改进部分，以及它未来如何通过实验转化为proposed method、baseline或ablation variant。
+如果deepresearch显示某个方法在相关benchmark、目标venue或近期论文中明显更适合作为主干，skill可以在蓝图中给出“推荐主干方法”，但仍应保留其他有价值的候选组合给后续实验规划评估。
+如果deepresearch和用户已明确内容足以判断某些方法明显不适合，例如与任务设定不兼容、缺少必要输入、计算成本明显不可接受、与目标claim不匹配，skill可以直接剔除这些方法，并在解释文件中简要说明剔除理由。
+对方法路线的输出应避免两种错误：一是过早决定未经实验验证的唯一最佳方法；二是把所有可能方法无差别罗列成文献清单。正确做法是构建一个有理论动机、有组合逻辑、有后续实验收敛路径的方法候选空间。
+
+蓝图中不应出现Artifact cautions、Do not assume reviewers will run code、Assumptions to validate这类面向用户的提醒或待办式内容。
+与reproducibility、artifact、assumption相关的内容如果确实与论文方案有关，应改写成论文内部的客观设计约束、证据需求或开放变量，而不是写成用户提醒。
+skill应检查输出中是否混入与论文本身无关的内容，例如用户操作建议、artifact cautions、流程解释、模板解释、工具使用理由等；这些内容应删除或改写为论文设计信息。
+解释文件不应输出“为什么正式蓝图采用实施计划格式”这类skill内部决策；这类问题的根因通常是skill没有区分“内部生成流程”和“用户可见解释”。
+内部流程、格式选择、工具调用、模板设计属于skill实现细节；用户可见解释只解释论文层面的设计决策及其推导关系。
+
+skill应减少过度defensive写法，优先用正向语言描述期望输出，例如“蓝图以论文方案为对象，使用客观陈述描述已选策略和开放变量”，而不是堆叠“不要写什么”。
+必要的反向限制只保留少数高风险边界；多数约束应改写为目标导向的正向要求，例如“解释文件只解释论文设计决策及其推导关系”。
+skill prompt应清晰、具体、结构化，明确输入、输出文件、语言、目标、边界、动态检索策略和质量标准，减少模型自行补充无关内容的空间。
+编写skill时应把目标改成“生成目标导向的论文战略蓝图”，把蓝图对象改成“供后续AI规划skill继承的论文核心信息”，把解释文件对象改成“供用户确认蓝图合理性的推导说明”。
+编写skill时应加入User-specified facts累积机制、Open validation items收缩机制、文件边界规则、解释前复述蓝图内容的规则、用标题自然引用section的规则，以及“只解释论文设计，不解释skill流程”的规则。
+编写skill时应删除或改写Artifact cautions、Assumptions to validate等面向用户的字段，并确保蓝图偏战略、后续skill补战术。

package/metaskills/academic-army-architect/envolve.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+npm run evolve-skill -- \
+  --config agent-forge.yaml \
+  --skill-path skills/academic-army-architect \
+  --artifact-path output/evolve-academic-army-architect \
+  --metaskill-path metaskills/academic-army-architect/METASKILL.md \
+  --task-path metaskills/academic-army-architect/ENVOLVETASK.md

package/metaskills/academic-army-coding-plan/ENVOLVETASK.md

@@ -0,0 +1 @@
+Create a coding plan based on the paper blueprint in output/paper_blueprint.md and the experiment plan in output/experiment_plan.md.

package/metaskills/academic-army-coding-plan/METASKILL.md

@@ -0,0 +1,118 @@
+这个skill属于一套基于Codex的autoresearch工具链，任务是根据`paper_blueprint`和`experiment plan`制定`coding plan`。
+`paper_blueprint`和`experiment plan`中会包含组成一篇论文所需的实验信息，例如要实现的系统、要做的实验、候选methods、baseline、要测的数据和指标等。
+这个skill需要根据已有实验信息规划如何用代码实现整个实验体系。
+这个skill只制定`coding plan`，不具体写代码；后续会有专门的写代码skill负责代码实现。
+`coding plan`应尽可能详细，尤其要把模块划分清楚，为后续写代码skill提供坚实基础。
+
+`coding_plan.md`固定使用英文输出，`coding_plan.explain.md`固定使用中文输出。
+中文解释中可以自然保留必要的英文仓库名、方法名、数据集、benchmark、metric、命令语义和代码标识符；只有在用户输入或已有项目明确给出某些现有文件路径时，才保留必要的路径事实。
+中英混排应自然：中文解释以中文句子为主体，英文术语、命令语义、代码标识符和必要的既有路径事实在保留原文更准确时直接保留，并保持命名一致。
+
+`coding_plan.md`和`coding_plan.explain.md`都是Markdown格式。
+`coding_plan.md`里只放`coding plan`，`coding_plan.explain.md`里只放`coding plan`解释，skill中要明确两个文件的内容边界。
+
+`coding_plan.md`和`coding_plan.explain.md`都应使用自然、可读的写法，通过清晰标题、语义化名称、短段落和bullet组织内容，不应依赖复杂编号系统来维持理解。
+编号只作为局部组织工具使用；只有在表达执行顺序、阶段顺序、优先级或步骤关系时，才使用编号列表。
+对并列模块、候选method、baseline、harness、测试类别、结果artifact等内容，应优先使用标题、短段落和bullet，而不是强行编号。
+每个section内部可以使用自己的局部`1、2、3`，但这些编号只服务当前section内部的阅读，不应扩展成跨section或跨文件的引用系统。
+`coding_plan.md`和`coding_plan.explain.md`都应避免使用`C1/C2/C3/B1/B2/B3/H1/H2/T1/T2`这类抽象编号系统，因为这种编号会迫使读者反复跳转查找含义。
+如果需要跨部分引用，应优先使用section标题、逻辑模块名、harness名称、测试类别、method名称、artifact类型或自然简称，而不是抽象编号。
+`coding_plan.explain.md`应优先用自然简称指代蓝图内容，例如“method替换模块”“candidate筛选harness”“result export layer”“CLI smoke tests”等表达，而不是写“见H2”“对应T3”。
+`coding_plan.explain.md`解释某个设计时，应先简要复述或概括对应的`coding_plan.md`内容，再说明为什么这样设计，减少用户对照两个文件来回查找的成本。
+`coding_plan.explain.md`可以按`coding_plan.md`的主要标题顺序解释，但解释文字应像自然说明文，而不是模板字段说明或编号索引表。
+如果多个内容之间有紧密关系，解释文件应直接用自然语言说明关系，例如“candidate筛选harness依赖method替换模块提供统一接口”，而不是写“C2依赖M1并服务H3”。
+`coding plan`中的命名应尽量语义化：逻辑模块名、harness名、测试类别名和artifact类型名本身应能表达用途，减少额外编号解释的需要。
+harness结构可以用有意义的名称组织，例如`Candidate Method Selection Harness`、`Module Optimization Harness`、`Full-System Evaluation Harness`，而不是`Harness H1/H2/H3`。
+testing结构可以用功能目标命名，例如`Data Loading Tests`、`Metric Computation Tests`、`Result Export Tests`、`CLI Smoke Tests`，而不是`Test T1/T2/T3`。
+对复杂实验阶段，可以在某个section内部使用局部阶段编号，例如`1. Data preparation`、`2. Candidate run`、`3. Evaluation export`，但不要把这些编号变成全局交叉引用系统。
+如果某个编号只是在生成过程中方便模型组织思路，但不提升最终读者理解，最终输出时应改写为标题、bullet或自然段落。
+skill应在输出前检查是否存在过度编号、抽象编号引用、跨文件编号依赖或需要反复跳转才能理解的表达，并将其改写为自然标题和语义化名称。
+核心原则是：编号可以帮助表达顺序，但不应成为理解`coding plan`的主要机制；`coding_plan.md`和`coding_plan.explain.md`都应靠清晰标题、语义化名称和自然引用来保持可读性。
+coding plan skill只沉淀“如何把论文蓝图和实验计划转化为代码规划”的领域方法；工具调用、文件访问、沙盒权限、fallback路径和运行故障恢复属于外层runtime/orchestrator，不进入skill，也不进入`coding_plan.md`或`coding_plan.explain.md`。
+
+skill应采用“最小任务上下文”策略：本地任务输入只来自`paper_blueprint`和`experiment plan`；开始时先根据用户路径、约定文件名或明确语义匹配定位这两个文件，确认后只读取这两个文件。
+定位输入的文件识别只服务于确认必要输入，不扩展为当前目录、子目录、历史计划、日志、README、草稿、运行输出、旧`coding_plan`或其他中间产物的探索；如果多个候选同时存在，优先选择用户显式指定、命名最匹配或语义最直接相关的文件。
+当前目录其他内容只有在`paper_blueprint`或`experiment plan`明确引用且对`coding plan`必不可少时，才作为显式依赖处理；缺失的通用工程模式、harness思想或外部经验应通过deepresearch补充，而不是从无关本地文件中猜测。
+输出前做一次input hygiene检查：`coding plan`是否只依赖`paper_blueprint`、`experiment plan`和必要deepresearch结果，是否混入当前目录无关内容；如有，应移除噪声，并把真正影响计划的缺口标记为开放变量。
+
+已有的deepresearch MCP工具来自`academic_army_mcp_tools`，本质是把prompt通过OpenAI API转发给带web search能力的GPT-5.5。
+可以现场搜索得到的信息不需要硬编码保存在skill里。
+在开始制定`coding plan`之前，应先用`academic_army_mcp_tools`中的deepresearch调研相关系统通常如何进行逻辑架构、组件边界、接口和实验流程设计。
+deepresearch调研实现组织方式时应优先参考高度工程化的代码库，不要从质量较差的代码库中学习结构。
+skill应现场分析相关高质量代码库的设计思路、逻辑组件、接口模式和实验框架模式，再据此组织当前项目的代码计划。
+调研对象不应在skill里被提前写死，可以包括相关领域代码库、benchmark框架、实验框架、evaluation harness、配置系统、实验记录工具、开源论文代码和工程化研究项目。
+
+`coding plan`需要包含充分具体的coding内容规划，但不安排具体文件路径、目录结构或文件名。
+`coding plan`规划逻辑模块，而不是物理文件布局；模块可以有语义化名称、职责、输入输出、接口、依赖关系和实现要点，但不指定它们必须位于哪个路径。
+后续写代码skill负责根据实际项目结构创建或修改具体文件；本skill只提供足够清晰的模块级、接口级和流程级实现计划。
+如果需要描述代码组织，应使用`logical module`、`component`、`interface`、`entrypoint`、`artifact type`、`configuration concept`等抽象表达，而不是具体路径表达。
+如果用户输入或已有项目明确给出了某些现有文件路径，`coding plan`可以把这些路径作为外部事实引用，但不基于它们继续扩展或发明新的文件路径。
+不再要求“所有路径都写成相对于项目顶层目录的相对路径”；新的要求是“默认不安排具体路径；只有在引用用户已明确给出的现有路径时，才保留必要的相对路径信息”。
+
+`coding plan`应把系统划分为清晰的逻辑模块，例如数据准备模块、method接口模块、candidate method适配模块、baseline适配模块、评估模块、harness执行模块、testing模块和结果导出模块；这些是逻辑职责，不是文件路径安排。
+每个逻辑模块应说明它负责什么、接收什么输入、输出什么结果、依赖哪些其他模块、对后续写代码skill有什么实现要求。
+可替换的candidate methods和baselines应映射到统一的逻辑接口或插件式结构，但不需要指定具体文件放置位置。
+`coding plan`可以说明“需要一个统一的method registry / adapter layer / evaluation entrypoint / result export interface”这类代码设计内容，但不说明这些东西位于某个具体路径。
+对复杂实验，`coding plan`应规划阶段化执行流程和命令行参数语义，例如阶段、参数、输入类型、输出artifact类型和运行结果含义；不指定具体脚本路径。
+
+`coding plan`除了划分系统功能模块，还需要明确区分两类执行结构：`harness structure`和`testing structure`。
+`harness structure`服务论文实验目标，回答“某个module change、method variant或optimization是否帮助达成论文目标指标”。
+`testing structure`服务功能正确性，回答“代码的数据处理、接口、配置、metric计算、结果导出和CLI入口是否按预期工作”。
+这两类结构都需要在`coding_plan.md`中单独成节规划，并在`coding_plan.explain.md`中解释它们如何承接`paper_blueprint`和`experiment plan`。
+
+`harness structure`不是泛泛的单元测试或回归测试，而是面向论文优化目标的可执行评测结构。
+skill应吸收传统test harness中stubs、drivers、test data、execution tools等受控执行环境思想，也应吸收OpenAI Evals、EleutherAI lm-evaluation-harness、SWE-bench等evaluation harness中输入、执行环境、评价逻辑、指标和结果记录分离的思想。
+skill应使用deepresearch现场调研与当前项目相关的evaluation harness、benchmark harness、paper code、工程化实验框架和测试组织方式，再决定当前coding plan中harness的具体结构。
+每个harness都应对应一个清晰的研究或实验目标；该目标应能通过某个可运行入口语义得到明确结果，而不是停留在“改进效果”“提升性能”这类抽象描述。
+在学术论文场景中，harness目标通常对应会影响最终论文结果的性能指标，例如accuracy、latency、throughput、memory、cost、robustness、generalization、sample efficiency、quality score或领域特定metric；具体指标由`paper_blueprint`和`experiment plan`决定。
+每个harness应明确它关联论文中的哪个claim、实验问题或方法选择问题，例如“选择哪个candidate method作为主方法”“某个模块改动是否提升关键metric”“某个优化是否值得进入最终系统”。
+每个harness应说明目标、被修改的逻辑模块、可修改边界、运行入口语义、输入数据类型、控制变量、metric、输出artifact和比较方式。
+候选methods和baselines应尽量映射到可替换模块结构中，使harness可以在相同输入、相同流程、相同metric下比较不同method或method variant。
+当论文需要从多个候选methods中选择主方法时，harness应支持“naive method / modified method / baseline method”的可比运行方式，帮助判断哪个method在当前应用场景下经过修改后最有潜力。
+harness应支持后续写代码skill反复执行“修改模块 -> 运行harness -> 读取结果 -> 再修改”的循环，因此需要稳定的entrypoint语义、固定的输入协议、可解析的输出格式和清晰的metric定义；具体文件组织留给写代码skill决定。
+每个harness可以规划“需要一个可运行入口来执行candidate method筛选”或“需要一个可运行入口来执行module optimization评测”，并说明参数语义如何指定method、dataset、split、seed和config，但不规定这个入口对应哪个具体文件路径。
+harness应尽量固定非目标变量，例如数据切分、随机种子、评估协议、资源预算和metric计算方式，以便比较结果主要反映被修改模块的差异。
+harness输出应描述为artifact schema和数据字段，包括最原始、最小加工的运行结果，例如per-example prediction、raw score、timing trace、resource usage、intermediate decision、error case、log metadata、config id和metric values。
+harness应明确artifact类型、数据粒度、文件格式倾向和最小字段，例如method name、variant name、config id、dataset、split、seed、commit or run id、timestamp、metric values和raw artifact references，而不是具体输出目录或文件路径。
+面向论文图表的数据聚合和转换应留给后续分析或绘图skill；harness只负责稳定运行、记录原始结果和输出可解析artifact。
+对复杂实验，harness可以按阶段组织，例如data preparation、candidate method run、module-level optimization run、full-system evaluation、ablation run、stress or robustness run；阶段划分由`experiment plan`决定。
+每个阶段应尽量有清晰的运行入口语义，并能通过参数语义在不同数据、method、config或seed上复用同一套流程。
+`coding plan`应说明不同harness之间的关系，例如哪些harness用于早期快速筛选，哪些harness用于最终主实验，哪些harness用于ablation或diagnostic analysis。
+
+`testing structure`应独立于harness规划；testing关注功能正确性，harness关注研究目标、性能指标和方法筛选。
+`coding plan`应把项目的功能目标具体化为一批测试能力，使后续写代码skill在写好或改好代码后可以运行测试确认功能没有坏。
+testing structure应规划功能测试覆盖哪些逻辑模块、测试目标是什么、使用什么最小输入、期望什么行为、pass/fail标准是什么。
+测试可以按功能命名，例如Data Loading Tests、Method Interface Tests、Metric Computation Tests、Result Export Tests、CLI Smoke Tests；这些名称是测试类别或测试目标，不是具体测试文件名。
+每个功能测试类别应说明它验证什么功能、调用哪个逻辑模块或entrypoint语义、使用什么最小输入、期望什么输出或行为。
+testing structure应覆盖核心功能路径，而不是只测试最终实验指标；例如数据能否正确读取、method接口是否返回预期格式、metric计算是否正确、结果导出字段是否完整、命令行参数是否能正确传递。
+测试能力应尽量使用小型fixture、toy data、mock data或最小样例，保证测试运行快、失败原因清晰、适合后续写代码skill频繁调用。
+测试结构可以包含不同粒度的测试，例如模块级测试、集成级测试、CLI smoke test和结果导出测试；具体粒度由项目复杂度决定。
+testing structure可以说明需要运行“全部功能测试”“method接口测试”“结果导出测试”等测试集合；pytest等工具的测试发现、fixture、setup/teardown和命令行选择机制可以作为组织测试能力的参考，但不安排具体测试脚本路径。
+测试应有明确pass/fail标准；功能正确性测试验证代码行为、接口契约、数据格式和结果导出是否正确，不用论文性能是否达到最好作为通过标准。
+当harness依赖某些关键模块时，testing structure应包含这些模块的功能测试，避免harness结果异常时无法判断是method效果不好还是代码功能错误。
+testing structure应规划测试数据和真实实验数据的关系：测试数据用于快速验证功能，真实实验数据用于harness和正式实验。
+testing structure应说明测试输出如何记录，例如terminal output、test report、temporary artifact或minimal log；这些输出主要服务debug，应和论文实验结果分开管理。
+`coding plan`应让后续写代码skill形成基本开发循环：先通过功能测试保证模块正确，再运行harness评估模块修改对论文目标的影响。
+testing structure应帮助后续写代码skill知道应该实现哪些测试能力，而不是替它决定测试文件放在哪里。
+
+写代码完成后，还会有更多skill根据实验结果画图和写论文，因此`coding plan`需要规划实验结果如何从系统中导出。
+结果导出应尽量以对系统内部逻辑影响小的方式进行。
+`coding plan`应规划实验结果导出的数据结构、字段、粒度和转换关系，但不安排具体输出路径。
+结果导出应优先描述原始artifact类型和schema，例如raw predictions、per-sample metrics、aggregate metrics、runtime traces、error cases、configuration metadata等。
+`coding plan`应优先规划导出最原始的数据。
+不应把面向论文图表或表格的数据转换逻辑写进核心代码库内部。
+`coding plan`应说明`experiment plan`需要的论文表格、图和统计结果如何由这些原始artifact转换得到，但不把转换逻辑绑定到具体路径或文件名。
+面向论文图表的数据聚合、转换和展示逻辑应留给后续分析、绘图或论文写作skill；本skill只说明原始数据需要以什么结构导出。
+
+**Logical design over file layout原则**：`coding plan`应规划代码实现的逻辑结构、模块职责、接口关系、执行流程、harness结构、testing结构和结果artifact schema；它不安排具体文件路径、目录结构或文件名，除非用户输入中已经明确给出某个现有路径且必须引用。
+**Downstream handoff原则**：本skill负责告诉后续写代码skill“需要实现哪些代码能力、模块如何协作、harness和测试如何验证目标”；后续写代码skill负责根据实际仓库结构决定“在哪些文件中实现”。
+**Path hygiene检查**：输出前检查`coding_plan.md`和`coding_plan.explain.md`是否发明了具体路径、目录树或文件名；如果有，应改写成逻辑模块名、接口名、entrypoint语义、artifact schema或测试类别。
+
+写skill时应调研AI生成文本中的defensive现象，并在编写skill时避免过度defensive。
+skill应优先用正向语言严格描述它应该生成什么、服务什么目标、输出内容边界、包含哪些规划信息。
+skill应减少堆叠反向限制条件，避免把输出写成大量“不要做什么”的防御性规则。
+必要边界应尽量转化为正向约束，例如“本skill只输出coding plan和中文解释，代码实现交给后续skill”。
+skill里包含目标、输入输出边界、规划对象和关键机制；具体学习哪些代码库、采用哪些工程模式、如何设计模块、harness structure和testing structure，应由skill通过deepresearch现场分析后决定。
+
+`coding plan`解释文件应说明当前coding plan为什么这样组织逻辑模块、阶段、harness structure、testing structure、结果导出和artifact schema。
+`coding plan`解释文件应帮助用户理解该计划如何承接`paper_blueprint`和`experiment plan`，以及如何为后续写代码、功能测试、实验执行、画图和论文写作skill提供基础。

package/metaskills/academic-army-coding-plan/envolve.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+npm run evolve-skill -- \
+  --config agent-forge.yaml \
+  --skill-path skills/academic-army-coding-plan \
+  --artifact-path output/evolve-academic-army-coding-plan \
+  --metaskill-path metaskills/academic-army-coding-plan/METASKILL.md \
+  --task-path metaskills/academic-army-coding-plan/ENVOLVETASK.md