academic-army 0.1.0

package/skills/academic-army-repo-scaffold/agents/openai.yaml

@@ -0,0 +1,10 @@
+interface:
+  display_name: "Academic Army Repo Scaffold"
+  short_description: "Create template-first Academic Army research repo scaffolds"
+  default_prompt: "Use $academic-army-repo-scaffold to initialize a template-first research repository scaffold from my paper_blueprint, experiment plan, coding plan, and target repo path."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "academic_army_mcp_tools"
+      description: "DeepResearch for repository template, harness, and ecosystem research."

package/src/README.md

@@ -0,0 +1,79 @@
+# TypeScript Pipelines
+
+`src` contains the TypeScript runners that turn AcademicArmy planning artifacts into repeatable agent workflows.
+
+[中文说明](README.zh-CN.md)
+
+## What This Code Owns
+
+The CLI entry point is [`cli.ts`](cli.ts). It exposes three pipelines through [`package.json`](../package.json) scripts:
+
+| Pipeline | Package script | What it does |
+|---|---|---|
+| `developing` | `npm run developing` | Runs the code development loop implemented in `developing/`. |
+| `developing-skill` | `npm run developing-skill` | Runs the same development loop with a trajectory optimizer that can revise the coding-style skill from concrete development feedback. |
+| `evolve-skill` | `npm run evolve-skill` | Runs the skill self-evolution loop implemented in `evolve-skill/`. |
+
+[`pipeline.ts`](pipeline.ts) provides the shared wrapper used by these commands. It parses pipeline-specific arguments, loads one or more YAML config files with `coding-agent-forge`, builds an `AgentTeam` from the configured factories, runs the selected pipeline, and closes the team afterward.
+
+## Quick Start
+
+Install dependencies once from the repository root:
+
+```bash
+npm install
+```
+
+The shared CLI shape is:
+
+```bash
+npm run cli -- <pipeline> [...args]
+```
+
+For most project workflows, use the prepared shell scripts:
+
+```bash
+bash runs/develop.sh
+bash metaskills/academic-army-architect/envolve.sh
+```
+
+## Directory Guide
+
+| Path | Purpose |
+|---|---|
+| [`cli.ts`](cli.ts) | Selects a pipeline by name and forwards the remaining CLI arguments. |
+| [`pipeline.ts`](pipeline.ts) | Shared pipeline definition, config loading, agent-team construction, and cleanup. |
+| [`developing/`](developing/) | Reads `paper_blueprint.md`, `experiment_plan.md`, and `coding_plan.md`, then iteratively implements the target codebase. See [`developing/README.md`](developing/README.md). |
+| [`developing/pipelineskill.ts`](developing/pipelineskill.ts) | Wraps the development loop with `trajectory-optimizer` hooks for improving the coding-style skill while development runs. |
+| [`evolve-skill/`](evolve-skill/) | Runs a skill on a fixed task, evaluates the artifact against a metaskill, and asks a modifier agent to revise the skill. See [`evolve-skill/README.md`](evolve-skill/README.md). |
+
+## How The Shared Wrapper Works
+
+Each pipeline provides pipeline-specific arguments and configured factories. [`pipeline.ts`](pipeline.ts) loads one or more YAML config files with `coding-agent-forge`, builds an `AgentTeam` from the configured factories, runs the selected pipeline, and closes the team afterward.
+
+This keeps the config loading, agent-team construction, and cleanup shared across the TypeScript runners.
+
+## Relationship To Shell Scripts
+
+Shell scripts under [`runs/`](../runs/) and the metaskill scripts described in [`metaskills/README.md`](../metaskills/README.md) are convenience wrappers around these TypeScript pipelines.
+
+| Script | Calls |
+|---|---|
+| [`runs/develop.sh`](../runs/develop.sh) | `npm run developing` |
+| [`runs/develop-skill.sh`](../runs/develop-skill.sh) | `npm run developing-skill` |
+| `metaskills/*/envolve.sh` | `npm run evolve-skill` |
+
+## Development Checks
+
+Run these before changing runner code:
+
+```bash
+npm run check
+npm run lint
+```
+
+## Where To Go Next
+
+- Development loop details: [`developing/README.md`](developing/README.md)
+- Skill evolution loop details: [`evolve-skill/README.md`](evolve-skill/README.md)
+- User-facing skill evolution workflow: [`../metaskills/README.md`](../metaskills/README.md)

package/src/README.zh-CN.md

@@ -0,0 +1,79 @@
+# TypeScript Pipelines
+
+`src` 存放 AcademicArmy 的 TypeScript runner，用来把规划产物转成可重复运行的 agent workflow。
+
+[English README](README.md)
+
+## 这层代码负责什么
+
+CLI 入口是 [`cli.ts`](cli.ts)。它通过 [`package.json`](../package.json) scripts 暴露三个 pipeline：
+
+| Pipeline | Package script | 作用 |
+|---|---|---|
+| `developing` | `npm run developing` | 运行 `developing/` 中实现的代码开发循环。 |
+| `developing-skill` | `npm run developing-skill` | 运行带 `trajectory-optimizer` hook 的开发循环，可根据具体开发反馈优化 coding-style skill。 |
+| `evolve-skill` | `npm run evolve-skill` | 运行 `evolve-skill/` 中实现的 skill self-evolution 循环。 |
+
+[`pipeline.ts`](pipeline.ts) 是这些命令共用的封装层。它解析各 pipeline 自己的参数，使用 `coding-agent-forge` 加载一个或多个 YAML 配置文件，根据配置好的 factories 创建 `AgentTeam`，运行选中的 pipeline，并在结束后关闭 team。
+
+## 快速开始
+
+在仓库根目录先安装依赖：
+
+```bash
+npm install
+```
+
+共享 CLI 形态是：
+
+```bash
+npm run cli -- <pipeline> [...args]
+```
+
+多数项目 workflow 直接使用预设 shell scripts：
+
+```bash
+bash runs/develop.sh
+bash metaskills/academic-army-architect/envolve.sh
+```
+
+## 目录说明
+
+| 路径 | 作用 |
+|---|---|
+| [`cli.ts`](cli.ts) | 根据名称选择 pipeline，并把剩余 CLI 参数传给对应 pipeline。 |
+| [`pipeline.ts`](pipeline.ts) | 共享的 pipeline 定义、配置加载、agent team 构建和清理逻辑。 |
+| [`developing/`](developing/) | 读取 `paper_blueprint.md`、`experiment_plan.md` 和 `coding_plan.md`，然后迭代实现目标代码库。详见 [`developing/README.zh-CN.md`](developing/README.zh-CN.md)。 |
+| [`developing/pipelineskill.ts`](developing/pipelineskill.ts) | 给开发循环叠加 `trajectory-optimizer` hooks，用于在开发过程中优化 coding-style skill。 |
+| [`evolve-skill/`](evolve-skill/) | 在固定任务上运行某个 skill，根据 metaskill 评价产物，并让 modifier agent 修改 skill。详见 [`evolve-skill/README.zh-CN.md`](evolve-skill/README.zh-CN.md)。 |
+
+## 共享 Wrapper 如何工作
+
+每个 pipeline 提供自己的参数和配置好的 factories。[`pipeline.ts`](pipeline.ts) 使用 `coding-agent-forge` 加载一个或多个 YAML 配置文件，根据配置好的 factories 创建 `AgentTeam`，运行选中的 pipeline，并在结束后关闭 team。
+
+这样 TypeScript runners 可以共享配置加载、agent team 构建和清理逻辑。
+
+## 和 Shell 脚本的关系
+
+[`runs/`](../runs/) 和 [`metaskills/README.zh-CN.md`](../metaskills/README.zh-CN.md) 中说明的 metaskill scripts 是这些 TypeScript pipeline 的便捷包装。
+
+| Script | 调用 |
+|---|---|
+| [`runs/develop.sh`](../runs/develop.sh) | `npm run developing` |
+| [`runs/develop-skill.sh`](../runs/develop-skill.sh) | `npm run developing-skill` |
+| `metaskills/*/envolve.sh` | `npm run evolve-skill` |
+
+## 开发检查
+
+修改 runner code 前运行：
+
+```bash
+npm run check
+npm run lint
+```
+
+## 下一步阅读
+
+- 开发循环细节：[`developing/README.zh-CN.md`](developing/README.zh-CN.md)
+- Skill evolution loop 细节：[`evolve-skill/README.zh-CN.md`](evolve-skill/README.zh-CN.md)
+- 面向用户的 skill evolution workflow：[`../metaskills/README.zh-CN.md`](../metaskills/README.zh-CN.md)

package/src/cli.ts

@@ -0,0 +1,55 @@
+import { type AgentVariablesByName } from "coding-agent-forge";
+import { type PipelineDefinition, runPipelineCli } from "./pipeline.js";
+import { developingPipeline, developingSkillPipeline } from "./developing/index.js";
+import { evolveSkillPipeline } from "./evolve-skill/index.js";
+
+function defineCli<VariablesByName extends AgentVariablesByName, Options>(entry: {
+  name: string;
+  description: string;
+  definition: PipelineDefinition<VariablesByName, Options>;
+}) {
+  return {
+    name: entry.name,
+    description: entry.description,
+    run: (args: readonly string[]) => runPipelineCli(entry.definition, args),
+  };
+}
+
+const cliDefinitions = [
+  defineCli({
+    name: "developing",
+    description: "Run the code development loop.",
+    definition: developingPipeline,
+  }),
+  defineCli({
+    name: "developing-skill",
+    description: "Run the code development loop and evolve its skill.",
+    definition: developingSkillPipeline,
+  }),
+  defineCli({
+    name: "evolve-skill",
+    description: "Run the skill evolution loop.",
+    definition: evolveSkillPipeline,
+  }),
+] as const;
+
+function buildHelp(): string {
+  const pipelineList = cliDefinitions
+    .map((pipeline) => `  ${pipeline.name.padEnd(16)} ${pipeline.description}`)
+    .join("\n");
+
+  return `Usage: npm run cli -- <pipeline> [...args]
+
+Available pipelines:
+${pipelineList}`;
+}
+
+const [pipelineName, ...pipelineArgs] = process.argv.slice(2);
+const pipelineDefinition = cliDefinitions.find((pipeline) => pipeline.name === pipelineName);
+
+if (pipelineDefinition === undefined) {
+  console.log(buildHelp());
+  process.exitCode = 1;
+} else {
+  await pipelineDefinition.run(pipelineArgs);
+}

package/src/developing/README.md

@@ -0,0 +1,146 @@
+# Developing Pipeline
+
+[`src/developing`](.) implements the code-writing loop used after the three planning artifacts are ready.
+
+[中文说明](README.zh-CN.md)
+
+## What This Pipeline Does
+
+The usual entry point is [`runs/develop.sh`](../../runs/develop.sh), which calls `npm run developing` with paths for:
+
+- `paper_blueprint.md`
+- `experiment_plan.md`
+- `coding_plan.md`
+- `skills/academic-army-coding-style/SKILL.md`
+- the artifact directory containing `TODO.md`
+- the target codebase directory
+- the development archive directory, passed through the current CLI option name `--achive-dir`
+
+The pipeline works in the configured `--target-path`, maintains `TODO.md` under the configured `--artifact-path`, and archives per-iteration task/review artifacts under the configured archive directory.
+
+For the overall TypeScript pipeline usage and entry points, see [`src/README.md`](../README.md).
+
+## Core Idea: Developing And Coding Style
+
+`src/developing` turns the three planning artifacts into a repeatable code-writing trajectory. `coding-manager` reads the current repository and `TODO.md`, chooses one concrete developer task, `developer` edits the target repository, and `code-reviewer` either returns `ACCEPT` or sends revision feedback back into the same task.
+
+The coding-style skill is [`skills/academic-army-coding-style/SKILL.md`](../../skills/academic-army-coding-style/SKILL.md). Its job is to control the code-writing agent's code structure and style. The upstream user task decides what to implement; this skill decides how to keep the implementation readable, local, low-coupling, and consistent with the current framework.
+
+Every developer run loads the configured coding-style skill through `--coding-style-skill-path`. [`agents/developer.ts`](agents/developer.ts) prepends the instruction from [`agents/prompts.ts`](agents/prompts.ts): load and follow that skill before reading the blueprint, experiment plan, coding plan, repository files, and current task. That makes the writing agent use the same code-structure and style preferences across features, refactors, harness/test work, methods, baselines, metrics, result exports, and framework docs.
+
+`academic-army-coding-style` is generic for any code-writing task. It does not decide the research method, experiment content, task priority, or repository template initialization. It only keeps code concise, readable, low-friction, easy to modify, and aligned with the existing repository structure.
+
+Put durable code-structure and style preferences in [`metaskills/academic-army-coding-style/METASKILL.md`](../../metaskills/academic-army-coding-style/METASKILL.md), then run [`runs/develop-skill.sh`](../../runs/develop-skill.sh) from the repository root to update the skill.
+
+## Quick Start
+
+From the repository root, run the prepared wrapper:
+
+```bash
+bash runs/develop.sh
+```
+
+Use the wrapper with the conventional project paths listed above to write code under `output/codebase`.
+
+## Direct Command
+
+`runs/develop.sh` calls:
+
+```bash
+npm run developing -- \
+  --config "agent-forge.yaml" \
+  --config "secret.yaml" \
+  --target-path "output/codebase" \
+  --achive-dir "output/developing-archives" \
+  --artifact-path "output/developing" \
+  --coding-style-skill-path "skills/academic-army-coding-style" \
+  --paper-blueprint-path "output/paper_blueprint.md" \
+  --experiment-plan-path "output/experiment_plan.md" \
+  --coding-plan-path "output/coding_plan.md" \
+  --max-iterations "100" \
+  --max-revision-iterations "10"
+```
+
+The current CLI option name is `--achive-dir`.
+
+## Options Reference
+
+| Option | Description |
+|---|---|
+| `--config` | One or more YAML config files loaded with `coding-agent-forge`. |
+| `--target-path` | Target codebase directory. |
+| `--achive-dir` | Development archive directory. |
+| `--artifact-path` | Artifact directory containing `TODO.md`. |
+| `--coding-style-skill-path` | Configured coding-style skill. |
+| `--paper-blueprint-path` | `paper_blueprint.md`. |
+| `--experiment-plan-path` | `experiment_plan.md`. |
+| `--coding-plan-path` | `coding_plan.md`. |
+| `--max-iterations` | Stops the outer loop if `coding-manager` has not returned `FINISHED`. |
+| `--max-revision-iterations` | Limits the inner developer/reviewer repair loop. |
+
+## Main Flow
+
+[`pipeline.ts`](pipeline.ts) parses CLI options and repeats an outer coding-manager task loop with an inner developer/reviewer repair loop.
+
+Each iteration does the following:
+
+1. `coding-manager` scans the current repository and `TODO.md` in the artifact directory, then chooses one developer task.
+2. `developer` loads the configured coding-style skill, edits the repository, and reports what changed for review.
+3. `code-reviewer` reads the code and developer report, then returns exactly `ACCEPT` or revision feedback.
+4. If the reviewer returns feedback, `developer` fixes the same task and `code-reviewer` reviews again.
+5. After the review loop ends, the pipeline archives the task and reports, then asks `coding-manager` to update the TODO file.
+6. The pipeline stops when `coding-manager` returns `FINISHED` or `--max-iterations` is reached.
+
+## Developing-Skill And Trajectory Feedback
+
+[`runs/develop-skill.sh`](../../runs/develop-skill.sh) calls the related `developing-skill` pipeline in [`pipelineskill.ts`](pipelineskill.ts). It runs the same development loop, adds `--metaskill-path`, and invokes `trajectory-optimizer` before the revision loop and after TODO updates so the coding-style skill can be improved from concrete development feedback.
+
+The first `trajectory-optimizer` call runs in `scan` mode before the developer starts. It reads the target repository, the current coding-style skill, the blueprint, the experiment plan, and the coding plan so the optimizer has the same project context as the code-writing loop.
+
+The second `trajectory-optimizer` call runs in `optimize` mode after the TODO update report is produced. It reads the metaskill, target repository, plans, current task, revision report, and TODO update report; evaluates whether the skill produced a good modification trajectory; then edits the coding-style skill directly. The prompt focuses the optimizer on missing, misleading, or redundant guidance that affected task selection, coding, review, or TODO update.
+
+The intended loop is:
+
+1. Add code-style preferences, failure modes, and review tips to [`metaskills/academic-army-coding-style/METASKILL.md`](../../metaskills/academic-army-coding-style/METASKILL.md).
+2. Run `bash runs/develop-skill.sh`.
+3. Let `developer`, `code-reviewer`, `coding-manager`, and `trajectory-optimizer` expose where the current skill helped or failed.
+4. Inspect the updated [`skills/academic-army-coding-style/SKILL.md`](../../skills/academic-army-coding-style/SKILL.md), keep the useful changes, and repeat when new code-style preferences appear.
+
+This is the coding-style version of skill self-improvement: the metaskill states what "good style guidance" means, the trajectory records how the agent actually modified code, and `develop-skill` uses that evidence to make the reusable skill more precise over time.
+
+Related work points in the same direction, though `developing-skill` is a local AcademicArmy implementation rather than a direct implementation of these papers:
+
+- [Reflexion](https://arxiv.org/abs/2303.11366) shows language agents improving across trials by turning task feedback into verbal reflection instead of updating model weights.
+- [Agent Trajectory Explorer](https://research.ibm.com/publications/agent-trajectory-explorer-visualizing-and-providing-feedback-on-agent-trajectories) argues that raw agent trajectories need navigable formats so developers can inspect behavior and provide feedback for future improvement.
+- [Agent-as-a-Judge](https://openreview.net/forum?id=Nn9POI9Ekt) evaluates agentic code-generation systems with an agentic evaluator that can consider the step-by-step task-solving process, not only the final output.
+- [When Agents go Astray](https://arxiv.org/abs/2509.02360) studies trajectory-level errors in software-engineering agents and uses process feedback to detect and course-correct inefficient trajectories during execution.
+
+## Output Artifacts
+
+The pipeline maintains:
+
+| Artifact | Where it lives |
+|---|---|
+| `TODO.md` | Under the configured artifact directory; the coding-manager-maintained task list. |
+| Timestamped archive folders | Under the configured archive directory; contains each selected task, per-revision reports, and TODO update reports. |
+
+## Important Files
+
+| Path | Purpose |
+|---|---|
+| [`pipeline.ts`](pipeline.ts) | Argument parsing, loop orchestration, archive creation, and per-agent handoff. |
+| [`pipelineskill.ts`](pipelineskill.ts) | `developing-skill` wrapper that adds trajectory optimization hooks around the base loop. |
+| [`agents/factory.ts`](agents/factory.ts) | Registers the developing coding manager, developer, and reviewer agents. |
+| [`agents/types.ts`](agents/types.ts) | Shared workspace-aware base class and variables. |
+| [`agents/manager.ts`](agents/manager.ts) | Maintains the TODO file and selects outer-loop tasks. |
+| [`agents/developer.ts`](agents/developer.ts) | Edits the target repository using the shared coding-style skill. |
+| [`agents/reviewer.ts`](agents/reviewer.ts) | Performs the read-only code review gate. |
+| [`agents/trajectory-optimizer.ts`](agents/trajectory-optimizer.ts) | Scans the trajectory and proposes coding-style skill improvements for `developing-skill`. |
+
+## Troubleshooting
+
+| Problem | Likely cause | Fix |
+|---|---|---|
+| The loop stops with `FINISHED` | `coding-manager` decided no further developer task is needed. | Inspect `TODO.md` in the artifact directory and the latest archive. |
+| A task keeps returning revision feedback | The inner developer/reviewer repair loop has not reached `ACCEPT`. | Read the per-revision reports in the timestamped archive folder. |
+| The archive option looks misspelled | The current CLI option name is `--achive-dir`. | Use the current option name until the CLI changes. |

package/src/developing/README.zh-CN.md

@@ -0,0 +1,146 @@
+# Developing Pipeline
+
+[`src/developing`](.) 实现三份规划产物准备好之后使用的代码编写循环。
+
+[English README](README.md)
+
+## 这个 Pipeline 做什么
+
+常用入口是 [`runs/develop.sh`](../../runs/develop.sh)，它会调用 `npm run developing`，并传入以下路径：
+
+- `paper_blueprint.md`
+- `experiment_plan.md`
+- `coding_plan.md`
+- `skills/academic-army-coding-style/SKILL.md`
+- 包含 `TODO.md` 的 artifact 目录
+- 目标代码库目录
+- development archive 目录；当前 CLI 参数名仍是 `--achive-dir`
+
+pipeline 会在配置的 `--target-path` 中继续写代码，维护配置的 `--artifact-path` 下的 `TODO.md`，并把每轮 task/review 产物归档到 archive 目录。
+
+TypeScript pipeline 的整体用法和入口见 [`src/README.zh-CN.md`](../README.zh-CN.md)。
+
+## 核心思想：Developing 和 Coding Style
+
+`src/developing` 会把三份规划产物变成一条可重复执行的代码编写 trajectory。`coding-manager` 读取当前 repo 和 `TODO.md`，选择一个具体 developer task；`developer` 修改目标 repo；`code-reviewer` 返回严格的 `ACCEPT`，或者把 revision feedback 送回同一个 task。
+
+coding-style skill 是 [`skills/academic-army-coding-style/SKILL.md`](../../skills/academic-army-coding-style/SKILL.md)。它的功能是控制写代码 agent 的代码结构和代码风格。上游用户任务决定要实现什么；这个 skill 决定如何让实现保持 readable、local、low-coupling，并和当前 framework 保持一致。
+
+每次 developer run 都会通过 `--coding-style-skill-path` 加载配置的 coding-style skill。[`agents/developer.ts`](agents/developer.ts) 会把 [`agents/prompts.ts`](agents/prompts.ts) 里的说明放到 developer prompt 前面：先 load and follow 这个 skill，再读取 blueprint、experiment plan、coding plan、repo files 和 current task。这样负责写代码的 agent 在 feature、refactor、harness/test work、methods、baselines、metrics、result exports 和 framework docs 等各种任务里，都会用同一套代码结构和风格偏好，保证输出的代码结构和风格统一。
+
+`academic-army-coding-style` 对各种代码编写任务都是通用的。它不决定 research method、experiment content、task priority 或 repository template initialization；它只关心代码结构和风格，让代码 concise、readable、low-friction、easy to modify，并贴合现有 repo 结构。
+
+任何对代码结构和代码风格的长期偏好，都放进 [`metaskills/academic-army-coding-style/METASKILL.md`](../../metaskills/academic-army-coding-style/METASKILL.md)，然后在仓库根目录运行 [`runs/develop-skill.sh`](../../runs/develop-skill.sh) 来更新这个 skill。
+
+## 快速开始
+
+在仓库根目录运行预设 wrapper：
+
+```bash
+bash runs/develop.sh
+```
+
+使用这个 wrapper 按上面列出的项目约定路径在 `output/codebase` 下写代码。
+
+## 直接命令
+
+`runs/develop.sh` 会调用：
+
+```bash
+npm run developing -- \
+  --config "agent-forge.yaml" \
+  --config "secret.yaml" \
+  --target-path "output/codebase" \
+  --achive-dir "output/developing-archives" \
+  --artifact-path "output/developing" \
+  --coding-style-skill-path "skills/academic-army-coding-style" \
+  --paper-blueprint-path "output/paper_blueprint.md" \
+  --experiment-plan-path "output/experiment_plan.md" \
+  --coding-plan-path "output/coding_plan.md" \
+  --max-iterations "100" \
+  --max-revision-iterations "10"
+```
+
+当前 CLI 参数名是 `--achive-dir`。
+
+## 参数参考
+
+| 参数 | 说明 |
+|---|---|
+| `--config` | 用 `coding-agent-forge` 加载的一个或多个 YAML config 文件。 |
+| `--target-path` | 目标代码库目录。 |
+| `--achive-dir` | Development archive 目录。 |
+| `--artifact-path` | 包含 `TODO.md` 的 artifact 目录。 |
+| `--coding-style-skill-path` | 配置的 coding-style skill。 |
+| `--paper-blueprint-path` | `paper_blueprint.md`。 |
+| `--experiment-plan-path` | `experiment_plan.md`。 |
+| `--coding-plan-path` | `coding_plan.md`。 |
+| `--max-iterations` | 当 `coding-manager` 尚未返回 `FINISHED` 时限制外层循环。 |
+| `--max-revision-iterations` | 限制内层 developer/reviewer 修复循环。 |
+
+## 主流程
+
+[`pipeline.ts`](pipeline.ts) 负责解析 CLI 参数，并重复运行外层 coding-manager 选任务循环和内层 developer/reviewer 修复循环。
+
+每轮迭代执行以下步骤：
+
+1. `coding-manager` 扫描当前 repo 和 artifact 目录中的 `TODO.md`，然后选择一个 developer task。
+2. `developer` 加载配置的 coding-style skill，修改 repo，并报告自己改了哪些内容给 reviewer。
+3. `code-reviewer` 阅读代码和 developer report，返回严格的 `ACCEPT` 或 revision feedback。
+4. 如果 reviewer 返回 feedback，`developer` 继续修同一个任务，然后 `code-reviewer` 再审。
+5. review 循环结束后，pipeline 归档 task 和 reports，然后让 `coding-manager` 更新 TODO 文件。
+6. 当 `coding-manager` 返回 `FINISHED` 或达到 `--max-iterations` 时停止。
+
+## developing-skill 和 Trajectory Feedback
+
+[`runs/develop-skill.sh`](../../runs/develop-skill.sh) 会调用 [`pipelineskill.ts`](pipelineskill.ts) 中的 `developing-skill` pipeline。它复用同一套开发循环，额外传入 `--metaskill-path`，并在 revision loop 前和 TODO 更新后调用 `trajectory-optimizer`，让 coding-style skill 能根据具体开发反馈继续优化。
+
+第一次 `trajectory-optimizer` 调用发生在 developer 开始前，使用 `scan` 模式。它会读取目标 repo、当前 coding-style skill、blueprint、experiment plan 和 coding plan，让 optimizer 拿到和代码编写循环相同的项目上下文。
+
+第二次 `trajectory-optimizer` 调用发生在 TODO update report 生成后，使用 `optimize` 模式。它会读取 metaskill、target repo、plans、current task、revision report 和 TODO update report；根据 [`metaskills/academic-army-coding-style/METASKILL.md`](../../metaskills/academic-army-coding-style/METASKILL.md) 中写的偏好评估这次修改 trajectory 的质量；然后直接修改 coding-style skill。这个 prompt 会重点检查哪些 guidance 缺失、误导或冗余，并看这些问题是否影响 task selection、coding、review 或 TODO update。
+
+推荐的使用循环是：
+
+1. 把代码风格偏好、failure modes 和 review tips 写进 [`metaskills/academic-army-coding-style/METASKILL.md`](../../metaskills/academic-army-coding-style/METASKILL.md)。
+2. 运行 `bash runs/develop-skill.sh`。
+3. 让 `developer`、`code-reviewer`、`coding-manager` 和 `trajectory-optimizer` 暴露当前 skill 在真实开发轨迹里哪里有效、哪里失效。
+4. 检查更新后的 [`skills/academic-army-coding-style/SKILL.md`](../../skills/academic-army-coding-style/SKILL.md)，保留有用修改；当出现新的代码偏好时继续重复。
+
+这就是 coding-style 版本的 skill self-improvement：metaskill 说明什么是“好的代码风格 guidance”，trajectory 记录 agent 实际如何修改代码，`develop-skill` 根据这些证据修改可复用的 skill，让这个 skill 越用越强。
+
+相关研究也在支持类似方向；这里的 `developing-skill` 是 AcademicArmy 的本地实现，不是对下面论文的直接复现：
+
+- [Reflexion](https://arxiv.org/abs/2303.11366) 展示了 language agents 可以把任务反馈转成 verbal reflection，在不更新模型权重的情况下跨 trial 改善表现。
+- [Agent Trajectory Explorer](https://research.ibm.com/publications/agent-trajectory-explorer-visualizing-and-providing-feedback-on-agent-trajectories) 讨论了 raw agent trajectory 不适合直接做人工分析，需要更容易浏览的格式来检查行为并提供 future improvement feedback。
+- [Agent-as-a-Judge](https://openreview.net/forum?id=Nn9POI9Ekt) 使用 agentic evaluator 评价 agentic code-generation systems，强调评价时不只看 final output，也看 step-by-step task-solving process。
+- [When Agents go Astray](https://arxiv.org/abs/2509.02360) 研究 software-engineering agents 的 trajectory-level errors，并用 process feedback 在执行中检测和纠正低效 trajectory。
+
+## 输出产物
+
+pipeline 会维护：
+
+| Artifact | 位置 |
+|---|---|
+| `TODO.md` | 配置的 artifact 目录下，由 coding-manager 维护的任务列表。 |
+| 按时间戳归档的文件夹 | 配置的 archive 目录下，保存 selected task、每次 revision 的 reports 和 TODO update reports。 |
+
+## 重要文件
+
+| 路径 | 作用 |
+|---|---|
+| [`pipeline.ts`](pipeline.ts) | 参数解析、循环编排、archive 创建和各 agent 之间的交接。 |
+| [`pipelineskill.ts`](pipelineskill.ts) | 给基础开发循环增加 trajectory optimization hooks 的 `developing-skill` 包装。 |
+| [`agents/factory.ts`](agents/factory.ts) | 注册 developing coding manager、developer 和 reviewer agents。 |
+| [`agents/types.ts`](agents/types.ts) | 共享的 workspace-aware base class 和变量定义。 |
+| [`agents/manager.ts`](agents/manager.ts) | 维护 TODO 文件并选择外层任务。 |
+| [`agents/developer.ts`](agents/developer.ts) | 使用共享 coding-style skill 修改目标 repo。 |
+| [`agents/reviewer.ts`](agents/reviewer.ts) | 执行只读代码审阅 gate。 |
+| [`agents/trajectory-optimizer.ts`](agents/trajectory-optimizer.ts) | 扫描开发轨迹，并为 `developing-skill` 提出 coding-style skill 优化建议。 |
+
+## 常见问题
+
+| 问题 | 常见原因 | 解决办法 |
+|---|---|---|
+| Loop 以 `FINISHED` 停止 | `coding-manager` 判断不需要继续选择 developer task。 | 检查 artifact 目录中的 `TODO.md` 和最新 archive。 |
+| 某个任务持续返回 revision feedback | 内层 developer/reviewer 修复循环尚未达到 `ACCEPT`。 | 阅读按时间戳归档的 per-revision reports。 |
+| Archive 参数看起来拼错 | 当前 CLI 参数名就是 `--achive-dir`。 | 在 CLI 改名前继续使用当前参数名。 |

package/src/developing/agents/developer.ts

@@ -0,0 +1,40 @@
+import { codingStyleSkillInstruction } from "./prompts.js";
+import { DevelopingAgent, type DevelopingAgentVariables } from "./types.js";
+
+export type DeveloperVariables = DevelopingAgentVariables & {
+  currentTask: string;
+  reviewerReport?: string;
+};
+
+export class DeveloperAgent extends DevelopingAgent<DeveloperVariables> {
+  protected buildPrompt(variables: Readonly<DeveloperVariables>): string {
+    const codingStyleSkillPath = this.workspaceRelativePath(variables.codingStyleSkillPath);
+    const targetPath = this.workspaceRelativePath(variables.targetPath);
+    const paperBlueprintPath = this.workspaceRelativePath(variables.paperBlueprintPath);
+    const experimentPlanPath = this.workspaceRelativePath(variables.experimentPlanPath);
+    const codingPlanPath = this.workspaceRelativePath(variables.codingPlanPath);
+    const reviewerReport = variables.reviewerReport ?? "(none)";
+    const codingStyleSkillInstructionText = codingStyleSkillInstruction(codingStyleSkillPath);
+
+    return `
+${codingStyleSkillInstructionText}
+
+Work only in the target repository at ${targetPath}/.
+
+Read:
+- paper blueprint: ${paperBlueprintPath}
+- experiment plan: ${experimentPlanPath}
+- coding plan: ${codingPlanPath}
+
+Current developer task:
+${variables.currentTask}
+
+Reviewer report:
+${reviewerReport}
+
+Modify the target repository code for the current task. If a reviewer report is present, update the code according to that report.
+
+Output a concise developer report with the main changes.
+`;
+  }
+}

package/src/developing/agents/factory.ts

@@ -0,0 +1,11 @@
+import type { AgentFactoryMap } from "coding-agent-forge";
+
+import { DeveloperAgent } from "./developer.js";
+import { CodingManagerAgent } from "./manager.js";
+import { CodeReviewerAgent } from "./reviewer.js";
+
+export const agentFactories: AgentFactoryMap = {
+  "coding-manager": (thread, constants) => new CodingManagerAgent(thread, constants),
+  developer: (thread, constants) => new DeveloperAgent(thread, constants),
+  "code-reviewer": (thread, constants) => new CodeReviewerAgent(thread, constants),
+};

package/src/developing/agents/index.ts

@@ -0,0 +1,8 @@
+export { CodingManagerAgent, type CodingManagerVariables } from "./manager.js";
+export { DeveloperAgent, type DeveloperVariables } from "./developer.js";
+export { CodeReviewerAgent, type CodeReviewerVariables } from "./reviewer.js";
+export {
+  TrajectoryOptimizerAgent,
+  type TrajectoryOptimizerVariables,
+} from "./trajectory-optimizer.js";
+export { agentFactories } from "./factory.js";

package/src/developing/agents/manager.ts

@@ -0,0 +1,74 @@
+import { codingStyleSkillInstruction, goalInstruction } from "./prompts.js";
+import { DevelopingAgent, type DevelopingAgentVariables } from "./types.js";
+
+type SelectCodingManagerVariables = DevelopingAgentVariables & {
+  todoPath: string;
+  finishMark: string;
+  phase: "select";
+};
+
+type UpdateCodingManagerVariables = DevelopingAgentVariables & {
+  todoPath: string;
+  finishMark: string;
+  phase: "update";
+  currentTask: string;
+  revisionReport: string;
+};
+
+export type CodingManagerVariables = SelectCodingManagerVariables | UpdateCodingManagerVariables;
+
+export class CodingManagerAgent extends DevelopingAgent<CodingManagerVariables> {
+  protected buildPrompt(variables: Readonly<CodingManagerVariables>): string {
+    const codingStyleSkillPath = this.workspaceRelativePath(variables.codingStyleSkillPath);
+    const targetPath = this.workspaceRelativePath(variables.targetPath);
+    const paperBlueprintPath = this.workspaceRelativePath(variables.paperBlueprintPath);
+    const experimentPlanPath = this.workspaceRelativePath(variables.experimentPlanPath);
+    const codingPlanPath = this.workspaceRelativePath(variables.codingPlanPath);
+    const todoPath = this.workspaceRelativePath(variables.todoPath);
+    const codingStyleSkillInstructionText = codingStyleSkillInstruction(codingStyleSkillPath);
+    const goalInstructionText = goalInstruction(variables.goal);
+
+    if (variables.phase === "update") {
+      return `
+${codingStyleSkillInstructionText}
+
+Update the TODO file after a developer task.
+Work only in the TODO file at ${todoPath}. Scan the target repository at ${targetPath}/ before editing it.
+
+Read:
+- paper blueprint: ${paperBlueprintPath}
+- experiment plan: ${experimentPlanPath}
+- coding plan: ${codingPlanPath}
+${goalInstructionText}
+
+Current developer task:
+${variables.currentTask}
+
+Revision report:
+${variables.revisionReport}
+
+The revision report lists each Developer report and Reviewer report from the review loop, ending with whether the Reviewer accepted the changes or the loop reached the max revision iterations.
+
+Update the TODO so completed work and future developer tasks match the current repository. If you find a better future plan, update it too.
+`;
+    }
+
+    return `
+${codingStyleSkillInstructionText}
+
+Select the next developer task for the target repository.
+Scan the target repository at ${targetPath}/ and the TODO file at ${todoPath}.
+
+Read:
+- paper blueprint: ${paperBlueprintPath}
+- experiment plan: ${experimentPlanPath}
+- coding plan: ${codingPlanPath}
+${goalInstructionText}
+
+Choose exactly one new bounded task for the Developer.
+
+When no further developer task is needed, return exactly:
+${variables.finishMark}
+`;
+  }
+}