academic-army 0.1.0

package/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true

package/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish
+
+on:
+  push:
+    paths:
+      - package.json
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "20.x"
+          package-manager-cache: false
+
+      - name: Update npm
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Type check
+        run: npm run check
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish to npm
+        run: npm publish --provenance

package/.prettierrc.json

@@ -0,0 +1,3 @@
+{
+  "printWidth": 100
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Howard Yin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# AcademicArmy
+
+AcademicArmy is a Codex-based workflow for turning research ideas into structured paper-planning artifacts and an implementation codebase. Its current core is a sequence of planning skills, a repository scaffold skill, and TypeScript pipelines that run development and skill-evolution agents from those artifacts.
+
+> Status: experimental workflow infrastructure. The generated project lives under `output/`, which is ignored by git.
+
+[中文说明](README.zh-CN.md)
+
+## Why It Exists
+
+The central principle of AcademicArmy is: build according to the planning artifacts.
+
+`paper_blueprint.md`, `experiment_plan.md`, and `coding_plan.md` should be specific enough that downstream agents can implement the project without redesigning its research direction, evidence strategy, or code contract during development.
+
+Parts that require fine-grained research should mainly be handled by skills that know how to call Deep Research through APIs. This avoids saving large amounts of local data only for retrieval, keeping the project lighter and making research updates easier to refresh.
+
+## How The Workflow Fits Together
+
+First use three planning skills to produce three AI-facing Markdown artifacts:
+
+| Step | Artifact | Role |
+|---|---|---|
+| `academic-army-architect` | `paper_blueprint.md` | The strategic paper blueprint that fixes the paper identity, target venue posture, claims, contribution boundary, candidate method space, evidence needs, and downstream constraints. |
+| `academic-army-experiment-plan` | `experiment_plan.md` | The experiment strategy that maps paper claims to evidence, datasets or workloads, metrics, baselines, ablations, robustness checks, and reviewer-facing validation needs. |
+| `academic-army-coding-plan` | `coding_plan.md` | The implementation contract that turns the blueprint and experiment plan into logical module boundaries, interface and entrypoint semantics, harnesses, testing categories, raw-result artifact schemas, and method-freeze rules. |
+
+Each planning skill also writes a Chinese `*.explain.md` companion for human review, but the development runner consumes the three English Markdown files above.
+
+Planning skills use a fixed language split. AI-facing artifacts such as `paper_blueprint.md`, `experiment_plan.md`, and `coding_plan.md` are written in English and contain only the plan or specification. Their companion explanation files, such as `paper_blueprint.explain.md`, `experiment_plan.explain.md`, and `coding_plan.explain.md`, are written in Chinese so the user can review the reasoning, trade-offs, and confirmation state.
+
+## Quick Start
+
+### 1. Install local dependencies
+
+Install package dependencies once:
+
+```bash
+npm install
+```
+
+Install MCP server dependencies from [`mcp-server/requirements.txt`](mcp-server/requirements.txt) if needed:
+
+```bash
+python -m pip install -r ./mcp-server/requirements.txt
+```
+
+### 2. Configure DeepResearch MCP
+
+Create `.env` in the repository root:
+
+```env
+OPENAI_API_KEY=your_api_key_here
+```
+
+For project pipeline runs, use the `academic_army_mcp_tools` server through [`agent-forge.yaml`](agent-forge.yaml). That config launches the server as `python -m mcp-server` with `PYTHONPATH=.` and `cwd=.` from the repository root, so the evolve/developing runners do not need a separate Codex MCP installation step.
+
+When running AcademicArmy skills directly in Codex, use [`install_mcp.py`](install_mcp.py) to install the same MCP server into Codex so the skill can call `academic_army_mcp_tools.deepresearch` outside the project pipeline:
+
+```bash
+python install_mcp.py
+```
+
+### 3. Generate the planning artifacts
+
+Start with an idea. The idea can be rough or detailed; it does not need to be a complete research plan.
+
+Use `academic-army-architect` to turn the idea into `paper_blueprint.md`. Because an early idea is usually underspecified, this step may involve multiple rounds of clarification and revision before the blueprint is specific enough to guide downstream work.
+
+Once you are satisfied with the paper blueprint, continue with the next planning skills to derive `experiment_plan.md` and `coding_plan.md`. Those three artifacts become the project starting point for repository scaffolding and iterative code development.
+
+### 4. Initialize the codebase scaffold
+
+After the three planning artifacts are ready, use `academic-army-repo-scaffold` to initialize a real starter repository for the codebase. It uses DeepResearch to choose a template, official initializer, or high-quality template repository, generates the starter repository, then adds the fixed experiment directories `data/`, `output/`, `results/`, and `harness/`. It writes dependency declarations and repo-local installation instructions, records installable dependencies and reference-only sources in `REFERENCES.md` and `REFERENCES.zh-CN.md`, preserves the template's test layout, and keeps README text focused on the current repository structure and usage.
+
+The repo scaffold skill does not implement paper methods, harness logic, tests, metrics, loaders, exporters, or experiment runners. Those belong to later implementation work.
+
+### 5. Run the development loop
+
+After the planning artifacts are ready, run:
+
+```bash
+bash runs/develop.sh
+```
+
+Run [`runs/develop.sh`](runs/develop.sh) to call the TypeScript `developing` pipeline, which reads the three planning artifacts and iteratively writes code under `output/codebase`. See [`src/README.md`](src/README.md) for the TypeScript entry points and [`src/developing/README.md`](src/developing/README.md) for the development loop implementation.
+
+## Common Tasks
+
+### Improve a planning skill output
+
+If the direct output from `academic-army-architect`, `academic-army-experiment-plan`, or `academic-army-coding-plan` is not satisfactory, do not only patch the generated artifact by hand. Add the concrete dissatisfaction, preferred behavior, and failure pattern to the matching metaskill under [`metaskills/`](metaskills/), then run the corresponding `envolve.sh` script for several rounds.
+
+Running those scripts calls the TypeScript [`evolve-skill`](src/evolve-skill/README.md) pipeline. Unlike directly running a skill once, `evolve-skill` is a small multi-agent loop: fresh runner agents test the skill on fixed tasks, an evaluator agent judges the produced artifacts against the metaskill, and a modifier agent revises the skill itself from that review. A few rounds usually make the next direct skill output much closer to the desired shape.
+
+### Run TypeScript pipelines directly
+
+Use the shell scripts as convenience wrappers around these TypeScript pipelines:
+
+```bash
+npm run developing
+npm run developing-skill
+npm run evolve-skill
+```
+
+For the shared CLI and pipeline structure, see [`src/README.md`](src/README.md).
+
+### Call DeepResearch
+
+AcademicArmy includes a local stdio MCP implementation in the [`mcp-server`](mcp-server) directory. It exposes one tool:
+
+- `deepresearch(prompt: str)`: runs the prompt with OpenAI Responses using `gpt-5.5`, high reasoning, web search, background mode, and source inclusion.
+
+Agents should call the `deepresearch` tool with a single self-contained prompt. For example:
+
+```text
+Use deepresearch with prompt:
+Find the closest papers to this research idea, compare their methods, and return a cited structured report.
+```
+
+## Project Structure
+
+| Path | Purpose |
+|---|---|
+| `agent-forge.yaml` | Agent and team wiring. |
+| `install_mcp.py` | Installs the project MCP server into Codex for direct skill runs. |
+| `mcp-server/` | Local stdio MCP implementation that exposes `deepresearch`. |
+| `skills/` | Prepared AcademicArmy skills. |
+| `metaskills/` | Matching metaskill design/evolution files. |
+| `runs/` | Convenience wrappers around TypeScript pipelines. |
+| `src/` | TypeScript pipeline structure and implementation notes. |
+| `output/` | Generated planning artifacts, codebase output, and archives. |
+
+Agent and team wiring lives in [`agent-forge.yaml`](agent-forge.yaml). The current TypeScript agents are implemented under [`src/developing/agents`](src/developing/agents) and [`src/evolve-skill/agents`](src/evolve-skill/agents).
+
+Prepared AcademicArmy skills live under [`skills/`](skills/), and their matching metaskill design/evolution files live under [`metaskills/`](metaskills/).
+
+## Configuration Reference
+
+| File or variable | Required for | Notes |
+|---|---|---|
+| `.env` / `OPENAI_API_KEY` | DeepResearch MCP | Read by the MCP server and by `install_mcp.py`. |
+| `agent-forge.yaml` | Project pipelines | Launches `academic_army_mcp_tools` as `python -m mcp-server` with `PYTHONPATH=.` and `cwd=.`. |
+| `secret.yaml` | Prepared shell scripts | Local ignored config overlay used by the prepared wrappers. It may contain passwords, API keys, runtime credentials, or other private values that must not be committed or uploaded to GitHub. |
+
+To override or add environment variables directly when installing MCP into Codex, repeat `-e/--env NAME=VALUE`:
+
+```bash
+python install_mcp.py -e OPENAI_API_KEY=your_api_key_here
+```
+
+Running the installer refreshes the Codex `academic_army_mcp_tools` entry, registers the current Python executable with `-m mcp-server`, sets the repository root as the MCP working directory, reads `.env`, and forwards those values to the MCP server.
+
+## Troubleshooting
+
+| Problem | Likely cause | Fix |
+|---|---|---|
+| `OPENAI_API_KEY` is missing | `.env` is not present or was not forwarded to Codex MCP. | Create `.env`; when running skills directly in Codex, rerun `python install_mcp.py`. |
+| A wrapper cannot find `secret.yaml` | The prepared shell scripts pass a local config overlay for private values such as passwords, API keys, and runtime credentials. | Create local `secret.yaml` or adjust the script to use your config files. Do not commit or upload this file to GitHub. |
+| Development output is drifting | The planning artifacts are not specific enough. | Revise `paper_blueprint.md`, `experiment_plan.md`, and `coding_plan.md` before continuing development. |
+
+## Development
+
+Use the normal TypeScript checks before changing runner code:
+
+```bash
+npm run check
+npm run lint
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,172 @@
+# AcademicArmy
+
+AcademicArmy 是一个基于 Codex 的研究工作流，用来把研究想法转成结构化论文规划产物和可持续开发的实现代码库。当前核心由一组规划类 skills、一个仓库 scaffold skill，以及驱动开发和 skill evolution agents 的 TypeScript pipelines 组成。
+
+> 当前状态：实验性工作流基础设施。生成的项目和运行产物位于 `output/`，该目录被 git 忽略。
+
+[English README](README.md)
+
+## 为什么需要它
+
+AcademicArmy 的主体核心可以概括为一句话：按图施工。
+
+这里的“施工图”就是 `paper_blueprint.md`、`experiment_plan.md` 和 `coding_plan.md`。它们应该足够具体，让下游 agents 在实现阶段不需要重新设计研究方向、证据策略或代码契约。
+
+需要精细调研的部分，主要通过会使用 API 的 skill 调用 Deep Research 来完成。这样可以避免为了检索而在本地保存大量数据，让项目更轻量，也方便后续刷新调研结果。
+
+## 工作流如何衔接
+
+先使用三个规划类 skill 交互生成三份面向 AI 执行的 Markdown 产物：
+
+| 步骤 | Artifact | 作用 |
+|---|---|---|
+| `academic-army-architect` | `paper_blueprint.md` | 论文战略蓝图，用来固定论文身份、目标 venue 姿态、核心 claims、贡献边界、候选方法空间、证据需求和下游约束。 |
+| `academic-army-experiment-plan` | `experiment_plan.md` | 实验策略，把论文 claims 映射到证据链、数据集或 workload、指标、baselines、消融、鲁棒性检查和审稿人关心的验证点。 |
+| `academic-army-coding-plan` | `coding_plan.md` | 代码实现契约，把论文蓝图和实验方案转成逻辑模块边界、接口与 entrypoint 语义、实验 harness、测试类别、raw result artifact schema 和 method freeze 规则。 |
+
+每个规划类 skill 还会同时生成一份中文 `*.explain.md` 解释文件，方便用户审阅；但后续开发 runner 读取的是上面三份英文 Markdown。
+
+规划类 skills 使用固定语言分工。面向后续 AI 执行的产物，例如 `paper_blueprint.md`、`experiment_plan.md` 和 `coding_plan.md`，统一使用英文，并且只放方案或规范本身。配套解释文件，例如 `paper_blueprint.explain.md`、`experiment_plan.explain.md` 和 `coding_plan.explain.md`，统一使用中文，用来帮助用户确认推导逻辑、关键取舍和当前确认状态。
+
+## 快速开始
+
+### 1. 安装本地依赖
+
+首次使用先安装依赖：
+
+```bash
+npm install
+```
+
+如有需要，从 [`mcp-server/requirements.txt`](mcp-server/requirements.txt) 安装 MCP server 依赖：
+
+```bash
+python -m pip install -r ./mcp-server/requirements.txt
+```
+
+### 2. 配置 DeepResearch MCP
+
+先在仓库根目录创建 `.env`：
+
+```env
+OPENAI_API_KEY=your_api_key_here
+```
+
+运行项目 pipeline 时，通过 [`agent-forge.yaml`](agent-forge.yaml) 使用 `academic_army_mcp_tools`。该配置会在仓库根目录以 `PYTHONPATH=.` 和 `cwd=.` 运行 `python -m mcp-server`，因此 evolve/developing runner 不需要额外执行 Codex MCP 安装步骤。
+
+如果直接在 Codex 中运行 AcademicArmy skills，需要用 [`install_mcp.py`](install_mcp.py) 把同一个 MCP server 安装到 Codex 里，这样 skill 才能在项目 pipeline 之外调用 `academic_army_mcp_tools.deepresearch`：
+
+```bash
+python install_mcp.py
+```
+
+### 3. 生成规划产物
+
+从一个想法开始。这个想法可以很粗略，也可以比较详细，不需要一开始就是完整的研究方案。
+
+使用 `academic-army-architect` 把这个想法整理成 `paper_blueprint.md`，也就是后续执行用的核心“施工图”。由于最初的想法通常还不够收敛，这一步可以通过多轮澄清和修改，把论文蓝图逐步调整到足够支撑下游工作的状态。
+
+当你对论文蓝图满意后，继续使用后续规划类 skills 生成 `experiment_plan.md` 和 `coding_plan.md`。这三份规划产物共同构成 AcademicArmy 的施工图，成为仓库初始化和迭代代码开发的项目起点。
+
+### 4. 初始化代码库 Scaffold
+
+三份规划产物准备好后，使用 `academic-army-repo-scaffold` 为代码库初始化一个真实 starter repository。它会使用 DeepResearch 选择合适的 template、官方 initializer 或高质量 template repository，生成 starter repository，然后叠加固定实验目录 `data/`、`output/`、`results/` 和 `harness/`。它会写入依赖声明和 repo-local 安装说明，在 `REFERENCES.md` 和 `REFERENCES.zh-CN.md` 中记录可安装依赖和仅作参考的外部来源，保留模板决定的测试结构，并让 README 聚焦当前仓库结构和用法。
+
+repo scaffold skill 不实现论文方法、harness 逻辑、测试、metric、loader、exporter 或实验 runner；这些属于后续实现工作。
+
+### 5. 运行开发循环
+
+三份规划产物准备好后，运行：
+
+```bash
+bash runs/develop.sh
+```
+
+运行 [`runs/develop.sh`](runs/develop.sh) 来调用 TypeScript 的 `developing` pipeline，读取三份规划产物，并在 `output/codebase` 下迭代写代码。TypeScript 入口和目录结构见 [`src/README.zh-CN.md`](src/README.zh-CN.md)，开发循环实现见 [`src/developing/README.zh-CN.md`](src/developing/README.zh-CN.md)。
+
+## 常见任务
+
+### 改进规划 Skill 输出
+
+如果 `academic-army-architect`、`academic-army-experiment-plan` 或 `academic-army-coding-plan` 直接生成的产物不满意，不建议只手工修产物本身。更好的做法是打开 [`metaskills/`](metaskills/) 下对应的 metaskill，把不满意的地方、希望偏向的写法和失败模式写进去，然后运行对应的 `envolve.sh` 脚本多迭代几轮。
+
+运行这些脚本时，会调用 TypeScript 的 [`evolve-skill`](src/evolve-skill/README.zh-CN.md) pipeline。`evolve-skill` 不同于直接运行一次 skill，它是一个简单的 multi-agent loop：新的 runner agent 用固定任务测试 skill，evaluator agent 按 metaskill 评价产物，modifier agent 再根据评价修改 skill 本身。通常多跑几轮后，再直接运行该 skill，就能得到更接近预期的结果。
+
+### 直接运行 TypeScript Pipelines
+
+使用 shell scripts 作为这些 TypeScript pipeline 的便捷包装：
+
+```bash
+npm run developing
+npm run developing-skill
+npm run evolve-skill
+```
+
+TypeScript pipeline 的目录结构和实现说明见 [`src/README.zh-CN.md`](src/README.zh-CN.md)。
+
+### 调用 DeepResearch
+
+AcademicArmy 在 [`mcp-server`](mcp-server) 目录下提供了本地 stdio MCP 实现。它只暴露一个工具：
+
+- `deepresearch(prompt: str)`：把 prompt 交给 OpenAI Responses，以 `gpt-5.5`、high reasoning、web search、background mode 和 source inclusion 的固定配置运行。
+
+使用时只需要让 agent 给 `deepresearch` 传入一个自包含 prompt，例如：
+
+```text
+Use deepresearch with prompt:
+Find the closest papers to this research idea, compare their methods, and return a cited structured report.
+```
+
+## 项目结构
+
+| 路径 | 用途 |
+|---|---|
+| `agent-forge.yaml` | Agent 和团队 wiring。 |
+| `install_mcp.py` | 把项目 MCP server 安装到 Codex，供直接运行 skill 时使用。 |
+| `mcp-server/` | 本地 stdio MCP 实现，暴露 `deepresearch`。 |
+| `skills/` | 已准备的 AcademicArmy skills。 |
+| `metaskills/` | 对应的 metaskill 设计与 evolution 文件。 |
+| `runs/` | TypeScript pipelines 的便捷 wrappers。 |
+| `src/` | TypeScript pipeline 的目录结构和实现说明。 |
+| `output/` | 生成的规划产物、代码库输出和归档。 |
+
+Agent 和团队 wiring 位于 [`agent-forge.yaml`](agent-forge.yaml)。当前 TypeScript agents 分别实现于 [`src/developing/agents`](src/developing/agents) 和 [`src/evolve-skill/agents`](src/evolve-skill/agents)。
+
+已准备的 AcademicArmy skills 位于 [`skills/`](skills/)，对应的 metaskill 设计与 evolution 文件位于 [`metaskills/`](metaskills/)。
+
+## 配置参考
+
+| 文件或变量 | 用于 | 说明 |
+|---|---|---|
+| `.env` / `OPENAI_API_KEY` | DeepResearch MCP | MCP server 和 `install_mcp.py` 会读取。 |
+| `agent-forge.yaml` | 项目 pipelines | 以 `PYTHONPATH=.` 和 `cwd=.` 运行 `python -m mcp-server`。 |
+| `secret.yaml` | 预设 shell scripts | 预设 wrappers 使用的本地忽略 config overlay。它可以包含密码、API key、runtime 凭据等不能提交或上传到 GitHub 的隐私内容。 |
+
+如果需要覆盖或补充环境变量，可以重复使用 `-e/--env NAME=VALUE`：
+
+```bash
+python install_mcp.py -e OPENAI_API_KEY=your_api_key_here
+```
+
+运行安装脚本时，会刷新 Codex 中的 `academic_army_mcp_tools` 配置项，注册当前 Python 可执行文件和 `-m mcp-server`，把仓库根目录设置为 MCP 工作目录，读取 `.env`，并把这些环境变量传给 MCP server。
+
+## 常见问题
+
+| 问题 | 常见原因 | 解决办法 |
+|---|---|---|
+| 缺少 `OPENAI_API_KEY` | 没有 `.env`，或没有把变量转发给 Codex MCP。 | 创建 `.env`；如果直接在 Codex 中跑 skill，再执行 `python install_mcp.py`。 |
+| Wrapper 找不到 `secret.yaml` | 预设脚本传入了本地 config overlay，用来放密码、API key、runtime 凭据等隐私内容。 | 创建本地 `secret.yaml`，或调整脚本使用你的 config 文件。不要把这个文件提交或上传到 GitHub。 |
+| 开发输出偏离规划 | 三份规划产物还不够具体。 | 先修订 `paper_blueprint.md`、`experiment_plan.md` 和 `coding_plan.md`，再继续开发。 |
+
+## 开发
+
+修改 runner 代码前，使用常规 TypeScript 检查：
+
+```bash
+npm run check
+npm run lint
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/agent-forge.yaml

@@ -0,0 +1,83 @@
+runtimes:
+  codex:
+    kind: codex
+    options:
+      config:
+        mcp_servers:
+          academic_army_mcp_tools:
+            command: python
+            args:
+              - -m
+              - mcp-server
+            cwd: .
+            env:
+              PYTHONPATH: .
+            tool_timeout_sec: 3600
+  qwen:
+    kind: qwen
+    options:
+      authType: openai
+      model: deepseek-reasoner
+      env:
+        OPENAI_BASE_URL: https://api.deepseek.com
+        OPENAI_MODEL: deepseek-v4-pro
+        OPENAI_REASONING_EFFORT: high
+
+threads:
+  codex-5.5-full-access:
+    runtime: codex
+    options:
+      model: gpt-5.5
+      sandboxMode: danger-full-access
+      workingDirectory: .
+  codex-5.5-read-only:
+    runtime: codex
+    options:
+      model: gpt-5.5
+      sandboxMode: danger-full-access # read-only
+      workingDirectory: .
+  codex-develop-5.5-full-access:
+    runtime: codex
+    options:
+      model: gpt-5.5
+      sandboxMode: danger-full-access
+      workingDirectory: &developerWorkspacePath output/codebase
+  codex-develop-5.5-read-only:
+    runtime: codex
+    options:
+      model: gpt-5.5
+      sandboxMode: danger-full-access # read-only
+      workingDirectory: *developerWorkspacePath
+  codex-develop-5.3-full-access:
+    runtime: codex
+    options:
+      model: gpt-5.3-codex-spark
+      workingDirectory: *developerWorkspacePath
+      sandboxMode: danger-full-access
+  qwen-develop-full-access:
+    runtime: qwen
+    options:
+      cwd: *developerWorkspacePath
+      permissionMode: yolo
+
+agents:
+  skill-runner:
+    thread: codex-5.5-full-access
+  skill-evaluator:
+    thread: codex-5.5-read-only
+  skill-modifier:
+    thread: codex-5.5-full-access
+  coding-manager:
+    thread: codex-develop-5.5-full-access
+    constants:
+      workspacePath: *developerWorkspacePath
+  developer:
+    thread: codex-develop-5.3-full-access
+    constants:
+      workspacePath: *developerWorkspacePath
+  code-reviewer:
+    thread: codex-develop-5.5-read-only
+    constants:
+      workspacePath: *developerWorkspacePath
+  trajectory-optimizer:
+    thread: codex-5.5-full-access

package/eslint.config.js

@@ -0,0 +1,28 @@
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import js from "@eslint/js";
+import { defineConfig, globalIgnores } from "eslint/config";
+import tseslint from "typescript-eslint";
+
+const tsconfigRootDir = dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig(
+  globalIgnores(["dist/**", "node_modules/**", "coverage/**", "output/**"]),
+  {
+    files: ["src/**/*.ts"],
+    extends: [
+      js.configs.recommended,
+      ...tseslint.configs.strictTypeChecked,
+      ...tseslint.configs.stylisticTypeChecked,
+    ],
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir,
+      },
+    },
+    rules: {
+      "@typescript-eslint/consistent-type-definitions": "off",
+    },
+  },
+);

package/install_mcp.py

@@ -0,0 +1,85 @@
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import tomlkit
+from dotenv import dotenv_values
+
+
+SERVER_NAME = "academic_army_mcp_tools"
+
+
+parser = argparse.ArgumentParser(
+    description="Install the AcademicArmy MCP server into Codex."
+)
+parser.add_argument("-e", "--env", action="append", default=[], metavar="NAME=VALUE")
+parser.add_argument(
+    "--timeout",
+    type=int,
+    default=3600,
+    metavar="SECONDS",
+    help="MCP tool timeout in seconds.",
+)
+args = parser.parse_args()
+
+for item in args.env:
+    if "=" not in item or item.startswith("="):
+        parser.error("-e/--env must be NAME=VALUE")
+
+if args.timeout <= 0:
+    parser.error("--timeout must be greater than 0")
+
+repo = Path(__file__).resolve().parent
+
+env_items = {}
+for name, value in dotenv_values(repo / ".env").items():
+    name = name.lstrip("\ufeff")
+    if name and value is not None:
+        env_items[name] = value
+
+for item in args.env:
+    name, value = item.split("=", 1)
+    env_items[name] = value
+
+env_items.setdefault("PYTHONPATH", str(repo))
+
+codex = shutil.which("codex")
+if not codex:
+    raise SystemExit("Could not find the codex command line tool in PATH.")
+
+subprocess.run(
+    [codex, "mcp", "remove", SERVER_NAME],
+    stdout=subprocess.DEVNULL,
+    stderr=subprocess.DEVNULL,
+)
+
+command = [codex, "mcp", "add"]
+for name, value in env_items.items():
+    command += ["--env", f"{name}={value}"]
+command += [SERVER_NAME, "--", str(Path(sys.executable).resolve()), "-m", "mcp-server"]
+
+subprocess.run(command, check=True)
+
+doctor = subprocess.run(
+    [codex, "doctor", "--json"],
+    check=True,
+    capture_output=True,
+    text=True,
+)
+codex_config = Path(json.loads(doctor.stdout)["checks"]["config.load"]["details"]["config.toml"])
+
+config = tomlkit.parse(codex_config.read_text(encoding="utf-8"))
+config["mcp_servers"][SERVER_NAME]["cwd"] = str(repo)
+config["mcp_servers"][SERVER_NAME]["tool_timeout_sec"] = args.timeout
+codex_config.write_text(tomlkit.dumps(config), encoding="utf-8")
+
+print(f"Installed {SERVER_NAME} with {codex}")
+print(f"Python: {Path(sys.executable).resolve()}")
+print(f"Working directory: {repo}")
+print(f"PYTHONPATH: {repo}")
+print(f"Codex config: {codex_config}")
+print(f"Environment variables registered with codex --env: {len(env_items)}")
+print(f"tool_timeout_sec: {args.timeout}")

package/mcp-server/__main__.py

@@ -0,0 +1,33 @@
+import argparse
+import os
+
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+
+from .deepresearch import register_deepresearch
+
+
+mcp = FastMCP(
+    "academic-army",
+    instructions=(
+        "AcademicArmy MCP server. It exposes project-level tools for research, "
+        "blueprint orchestration, and future AcademicArmy workflow functions."
+    ),
+)
+
+
+if __name__ == "__main__":
+    load_dotenv(".env")
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("-e", "--env", action="append", default=[], metavar="NAME=VALUE")
+    args = parser.parse_args()
+
+    for item in args.env:
+        name, separator, value = item.partition("=")
+        if not separator or not name:
+            parser.error("-e/--env must be NAME=VALUE")
+        os.environ[name] = value
+
+    register_deepresearch(mcp)
+    mcp.run(transport="stdio")

package/mcp-server/deepresearch/__init__.py

@@ -0,0 +1,3 @@
+from .tools import deepresearch, register_deepresearch
+
+__all__ = ["deepresearch", "register_deepresearch"]