academic-army 0.1.0

package/src/developing/agents/prompts.ts

@@ -0,0 +1,12 @@
+export function codingStyleSkillInstruction(codingStyleSkillPath: string): string {
+  return `Load and follow the skill at ${codingStyleSkillPath}. It describes how to keep repository code concise, readable, low-friction, and easy to modify.`;
+}
+
+export function goalInstruction(goal: string): string {
+  return `
+Current goal:
+${goal}
+
+Use this goal as the current high-level objective.
+`;
+}

package/src/developing/agents/reviewer.ts

@@ -0,0 +1,44 @@
+import { codingStyleSkillInstruction } from "./prompts.js";
+import { DevelopingAgent, type DevelopingAgentVariables } from "./types.js";
+
+export type CodeReviewerVariables = DevelopingAgentVariables & {
+  acceptMark: string;
+  currentTask: string;
+  developerReport: string;
+};
+
+export class CodeReviewerAgent extends DevelopingAgent<CodeReviewerVariables> {
+  protected buildPrompt(variables: Readonly<CodeReviewerVariables>): 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 codingStyleSkillInstructionText = codingStyleSkillInstruction(codingStyleSkillPath);
+
+    return (
+      codingStyleSkillInstructionText +
+      `
+
+Review the current developer task result. Read only.
+
+Read:
+- target repository: ${targetPath}
+- paper blueprint: ${paperBlueprintPath}
+- experiment plan: ${experimentPlanPath}
+- coding plan: ${codingPlanPath}
+
+Current developer task:
+${variables.currentTask}
+
+Developer report:
+${variables.developerReport}
+
+If the code for the current task is complete and needs no more changes, output exactly:
+${variables.acceptMark}
+
+Otherwise output the revision feedback for the Developer.
+`
+    );
+  }
+}

package/src/developing/agents/trajectory-optimizer.ts

@@ -0,0 +1,70 @@
+import { Agent } from "coding-agent-forge/agent";
+import { readFileSync } from "node:fs";
+import type { DevelopingAgentVariables } from "./types.js";
+
+type ScanTrajectoryOptimizerVariables = DevelopingAgentVariables & {
+  phase: "scan";
+  currentTask: string;
+};
+
+type OptimizeTrajectoryOptimizerVariables = DevelopingAgentVariables & {
+  phase: "optimize";
+  currentTask: string;
+  revisionReport: string;
+  todoUpdateReport: string;
+  metaskillPath: string;
+};
+
+export type TrajectoryOptimizerVariables =
+  | ScanTrajectoryOptimizerVariables
+  | OptimizeTrajectoryOptimizerVariables;
+
+export class TrajectoryOptimizerAgent extends Agent<TrajectoryOptimizerVariables> {
+  protected buildPrompt(variables: Readonly<TrajectoryOptimizerVariables>): string {
+    if (variables.phase === "scan") {
+      return `
+Read only. Scan the target repository before the Developer starts the current task.
+
+Read:
+- skill: ${variables.codingStyleSkillPath}
+- target repository: ${variables.targetPath}
+- paper blueprint: ${variables.paperBlueprintPath}
+- experiment plan: ${variables.experimentPlanPath}
+- coding plan: ${variables.codingPlanPath}
+
+Current developer task:
+${variables.currentTask}
+
+Output a concise baseline of the repository state relevant to this task and the main guidance the skill should provide.
+`;
+    }
+
+    const metaskill = readFileSync(variables.metaskillPath, "utf8");
+    return `
+Revise the skill at ${variables.codingStyleSkillPath} so it produces better development trajectories.
+
+The metaskill below contains the design goals and tips of this skill:
+
+${metaskill}
+
+Read:
+- target repository: ${variables.targetPath}
+- paper blueprint: ${variables.paperBlueprintPath}
+- experiment plan: ${variables.experimentPlanPath}
+- coding plan: ${variables.codingPlanPath}
+
+Current developer task:
+${variables.currentTask}
+
+Revision report:
+${variables.revisionReport}
+
+TODO update report:
+${variables.todoUpdateReport}
+
+Evaluate whether the skill produced a good modification trajectory, then edit the skill directly. Focus on missing, misleading, or redundant guidance that affected task selection, coding, review, or TODO update.
+
+Output a concise optimizer report with the main skill changes.
+`;
+  }
+}

package/src/developing/agents/types.ts

@@ -0,0 +1,41 @@
+import type { PromptConstants, Thread } from "coding-agent-forge";
+import { Agent } from "coding-agent-forge/agent";
+import { statSync } from "node:fs";
+import path from "node:path";
+
+export type DevelopingAgentVariables = {
+  targetPath: string;
+  codingStyleSkillPath: string;
+  paperBlueprintPath: string;
+  experimentPlanPath: string;
+  codingPlanPath: string;
+  goal: string;
+};
+
+export type DevelopingAgentConstants = {
+  workspacePath: string;
+};
+
+export abstract class DevelopingAgent<Variables extends DevelopingAgentVariables> extends Agent<
+  Variables,
+  DevelopingAgentConstants
+> {
+  protected readonly workspacePath: string;
+
+  constructor(thread: Thread, constants: Readonly<PromptConstants>) {
+    if (!constants.workspacePath) {
+      throw new Error("Developing agent constants.workspacePath must be configured.");
+    }
+
+    const workspacePath = path.resolve(constants.workspacePath);
+    if (!statSync(workspacePath).isDirectory()) {
+      throw new Error(`workspacePath must be a directory: ${workspacePath}`);
+    }
+    super(thread, { workspacePath });
+    this.workspacePath = workspacePath;
+  }
+
+  protected workspaceRelativePath(filePath: string): string {
+    return path.relative(this.workspacePath, path.resolve(filePath)) || ".";
+  }
+}

package/src/developing/index.ts

@@ -0,0 +1,2 @@
+export * from "./pipeline.js";
+export * from "./pipelineskill.js";

package/src/developing/pipeline.ts

@@ -0,0 +1,306 @@
+import { AgentTeam, type RecordCallback } from "coding-agent-forge";
+import { existsSync } from "node:fs";
+import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { definePipeline, type ParsedPipelineArgs } from "../pipeline.js";
+import {
+  agentFactories,
+  type CodingManagerVariables,
+  type CodeReviewerVariables,
+  type DeveloperVariables,
+} from "./agents/index.js";
+import type { DevelopingAgentVariables } from "./agents/types.js";
+
+export type DevelopingAgentVariablesByName = {
+  "coding-manager": CodingManagerVariables;
+  developer: DeveloperVariables;
+  "code-reviewer": CodeReviewerVariables;
+};
+
+export type DevelopingOptions = {
+  targetPath: string;
+  achiveDir: string;
+  artifactPath: string;
+  codingStyleSkillPath: string;
+  paperBlueprintPath: string;
+  experimentPlanPath: string;
+  codingPlanPath: string;
+  goalPath: string;
+  maxIterations: number;
+  maxRevisionIterations: number;
+  hooks?: DevelopingHooks;
+};
+
+export type DevelopingHooks = {
+  beforeRevisionLoop?: (
+    agentVariables: DevelopingAgentVariables,
+    currentTask: string,
+  ) => Promise<void> | void;
+  afterRevision?: (
+    revision: number,
+    agentVariables: DevelopingAgentVariables,
+    currentTask: string,
+    developerReport: string,
+    reviewerReport: string,
+    revisionReports: readonly string[],
+  ) => Promise<void> | void;
+  afterTodoUpdate?: (
+    agentVariables: DevelopingAgentVariables,
+    currentTask: string,
+    revisionReport: string,
+    todoUpdateReport: string,
+  ) => Promise<void> | void;
+};
+
+const USAGE = [
+  "Usage: npm run developing --",
+  "--config <path>",
+  "--target-path <folder>",
+  "--achive-dir <folder>",
+  "--artifact-path <folder>",
+  "--coding-style-skill-path <path>",
+  "--paper-blueprint-path <path>",
+  "--experiment-plan-path <path>",
+  "--coding-plan-path <path>",
+  "--goal-path <path>",
+  "[--max-iterations <positive-integer>]",
+  "[--max-revision-iterations <positive-integer>]",
+].join(" ");
+
+const FINISH_MARK = "FINISHED";
+const ACCEPT_MARK = "ACCEPT";
+
+export function parseDevelopingArgs(
+  args: readonly string[],
+): ParsedPipelineArgs<DevelopingOptions> {
+  const {
+    values: {
+      config,
+      "target-path": targetPath,
+      "achive-dir": achiveDir,
+      "artifact-path": artifactPath,
+      "coding-style-skill-path": codingStyleSkillPath,
+      "paper-blueprint-path": paperBlueprintPath,
+      "experiment-plan-path": experimentPlanPath,
+      "coding-plan-path": codingPlanPath,
+      "goal-path": goalPath,
+      "max-iterations": maxIterations,
+      "max-revision-iterations": maxRevisionIterations,
+    },
+  } = parseArgs({
+    args: [...args],
+    options: {
+      config: { type: "string", multiple: true },
+      "target-path": { type: "string" },
+      "achive-dir": { type: "string" },
+      "artifact-path": { type: "string" },
+      "coding-style-skill-path": { type: "string" },
+      "paper-blueprint-path": { type: "string" },
+      "experiment-plan-path": { type: "string" },
+      "coding-plan-path": { type: "string" },
+      "goal-path": { type: "string" },
+      "max-iterations": { type: "string" },
+      "max-revision-iterations": { type: "string" },
+    },
+  });
+
+  if (
+    config === undefined ||
+    targetPath === undefined ||
+    achiveDir === undefined ||
+    artifactPath === undefined ||
+    codingStyleSkillPath === undefined ||
+    paperBlueprintPath === undefined ||
+    experimentPlanPath === undefined ||
+    codingPlanPath === undefined ||
+    goalPath === undefined
+  ) {
+    throw new Error(USAGE);
+  }
+
+  return {
+    configPaths: config,
+    runningOptions: {
+      targetPath,
+      achiveDir,
+      artifactPath,
+      codingStyleSkillPath,
+      paperBlueprintPath,
+      experimentPlanPath,
+      codingPlanPath,
+      goalPath,
+      maxIterations: Number(maxIterations ?? 10),
+      maxRevisionIterations: Number(maxRevisionIterations ?? 3),
+    },
+  };
+}
+
+export async function developing(
+  team: AgentTeam<DevelopingAgentVariablesByName>,
+  options: DevelopingOptions,
+): Promise<void> {
+  const logRecord: RecordCallback = (thread, record) => {
+    console.log(thread.recordToPrettyString(record));
+  };
+
+  const achiveDir = path.resolve(options.achiveDir);
+  const artifactPath = path.resolve(options.artifactPath);
+  const todoPath = path.join(artifactPath, "TODO.md");
+  const goal = await readGoal(options.goalPath);
+  const agentVariables: DevelopingAgentVariables = {
+    targetPath: path.resolve(options.targetPath),
+    codingStyleSkillPath: path.resolve(options.codingStyleSkillPath),
+    paperBlueprintPath: path.resolve(options.paperBlueprintPath),
+    experimentPlanPath: path.resolve(options.experimentPlanPath),
+    codingPlanPath: path.resolve(options.codingPlanPath),
+    goal,
+  };
+
+  await mkdir(achiveDir, { recursive: true });
+  await mkdir(artifactPath, { recursive: true });
+  if (!existsSync(todoPath)) {
+    await writeText(todoPath, "# TODO");
+  }
+  await mkdir(agentVariables.targetPath, { recursive: true });
+
+  for (let iteration = 1; iteration <= options.maxIterations; iteration++) {
+    console.log(`\n# Developing iteration ${String(iteration)}\n`);
+    const archiveDir = path.join(achiveDir, new Date().toISOString().replace(/[:.]/g, "-"));
+    await mkdir(archiveDir, { recursive: true });
+
+    const codingManager = await team.createAgent("coding-manager");
+    const developer = await team.createAgent("developer");
+    const codeReviewer = await team.createAgent("code-reviewer");
+
+    const currentTask = (
+      await codingManager.runStreamed(
+        {
+          ...agentVariables,
+          todoPath,
+          finishMark: FINISH_MARK,
+          phase: "select",
+        },
+        logRecord,
+      )
+    ).trim();
+    await writeText(path.join(archiveDir, "current_task.md"), currentTask);
+
+    if (currentTask.trim() === FINISH_MARK) {
+      console.log(`\n# ${FINISH_MARK}\n`);
+      return;
+    }
+
+    let previousReviewerReport = "";
+    const revisionReports: string[] = [];
+
+    await options.hooks?.beforeRevisionLoop?.(agentVariables, currentTask);
+
+    for (let revision = 1; revision <= options.maxRevisionIterations; revision++) {
+      console.log(`\n# Review revision ${String(revision)}\n`);
+
+      const developerVariables: DeveloperVariables = {
+        ...agentVariables,
+        currentTask,
+      };
+      if (previousReviewerReport) {
+        developerVariables.reviewerReport = previousReviewerReport;
+      }
+
+      const developerReport = (await developer.runStreamed(developerVariables, logRecord)).trim();
+      await writeText(
+        path.join(archiveDir, `developer_report_${String(revision).padStart(3, "0")}.md`),
+        developerReport,
+      );
+      revisionReports.push(`Developer report ${String(revision)}:\n${developerReport}`);
+
+      const reviewerReport = (
+        await codeReviewer.runStreamed(
+          {
+            ...agentVariables,
+            acceptMark: ACCEPT_MARK,
+            currentTask,
+            developerReport,
+          },
+          logRecord,
+        )
+      ).trim();
+      await writeText(
+        path.join(archiveDir, `code_review_${String(revision).padStart(3, "0")}.md`),
+        reviewerReport,
+      );
+      revisionReports.push(`Reviewer report ${String(revision)}:\n${reviewerReport}`);
+
+      const accepted = reviewerReport.trim() === ACCEPT_MARK;
+      if (accepted) {
+        revisionReports.push("Reviewer accepted the changes.");
+      }
+
+      if (!accepted && revision === options.maxRevisionIterations) {
+        revisionReports.push("Reviewer did not accept the changes before max revision iterations.");
+      }
+
+      await options.hooks?.afterRevision?.(
+        revision,
+        agentVariables,
+        currentTask,
+        developerReport,
+        reviewerReport,
+        revisionReports,
+      );
+      if (accepted) {
+        break;
+      }
+      previousReviewerReport = reviewerReport;
+    }
+
+    const revisionReport = revisionReports.join("\n\n");
+    await writeText(path.join(archiveDir, "revision_report.md"), revisionReport);
+
+    const todoUpdateReport = (
+      await codingManager.runStreamed(
+        {
+          ...agentVariables,
+          todoPath,
+          finishMark: FINISH_MARK,
+          phase: "update",
+          currentTask,
+          revisionReport,
+        },
+        logRecord,
+      )
+    ).trim();
+    await writeText(path.join(archiveDir, "todo_update_report.md"), todoUpdateReport);
+    await cp(artifactPath, path.join(archiveDir, "artifacts"), { recursive: true });
+
+    await options.hooks?.afterTodoUpdate?.(
+      agentVariables,
+      currentTask,
+      revisionReport,
+      todoUpdateReport,
+    );
+  }
+
+  throw new Error(
+    `Reached --max-iterations ${String(options.maxIterations)} before the coding-manager returned ${FINISH_MARK}.`,
+  );
+}
+
+async function writeText(filePath: string, content: string): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${content.trimEnd()}\n`, "utf8");
+}
+
+async function readGoal(goalPath: string): Promise<string> {
+  const goal = (await readFile(path.resolve(goalPath), "utf8")).trim();
+  if (goal === "") {
+    throw new Error(`Goal file must not be empty: ${goalPath}`);
+  }
+  return goal;
+}
+
+export const developingPipeline = definePipeline({
+  agentFactories,
+  parseArgs: parseDevelopingArgs,
+  run: developing,
+});

package/src/developing/pipelineskill.ts

@@ -0,0 +1,169 @@
+import { type AgentFactoryMap, AgentTeam, type RecordCallback } from "coding-agent-forge";
+import type { Agent } from "coding-agent-forge/agent";
+import { parseArgs } from "node:util";
+import { definePipeline, type ParsedPipelineArgs } from "../pipeline.js";
+import {
+  agentFactories as developingAgentFactories,
+  TrajectoryOptimizerAgent,
+  type TrajectoryOptimizerVariables,
+} from "./agents/index.js";
+import {
+  developing,
+  type DevelopingAgentVariablesByName,
+  type DevelopingOptions,
+} from "./pipeline.js";
+
+export type DevelopingSkillAgentVariables = DevelopingAgentVariablesByName & {
+  "trajectory-optimizer": TrajectoryOptimizerVariables;
+};
+
+export type DevelopingSkillOptions = DevelopingOptions & {
+  metaskillPath: string;
+};
+
+const USAGE = [
+  "Usage: npm run developing-skill --",
+  "--config <path>",
+  "--target-path <folder>",
+  "--achive-dir <folder>",
+  "--artifact-path <folder>",
+  "--coding-style-skill-path <path>",
+  "--metaskill-path <path>",
+  "--paper-blueprint-path <path>",
+  "--experiment-plan-path <path>",
+  "--coding-plan-path <path>",
+  "--goal-path <path>",
+  "[--max-iterations <positive-integer>]",
+  "[--max-revision-iterations <positive-integer>]",
+].join(" ");
+
+export function parseDevelopingSkillArgs(
+  args: readonly string[],
+): ParsedPipelineArgs<DevelopingSkillOptions> {
+  const {
+    values: {
+      config,
+      "target-path": targetPath,
+      "achive-dir": achiveDir,
+      "artifact-path": artifactPath,
+      "coding-style-skill-path": codingStyleSkillPath,
+      "metaskill-path": metaskillPath,
+      "paper-blueprint-path": paperBlueprintPath,
+      "experiment-plan-path": experimentPlanPath,
+      "coding-plan-path": codingPlanPath,
+      "goal-path": goalPath,
+      "max-iterations": maxIterations,
+      "max-revision-iterations": maxRevisionIterations,
+    },
+  } = parseArgs({
+    args: [...args],
+    options: {
+      config: { type: "string", multiple: true },
+      "target-path": { type: "string" },
+      "achive-dir": { type: "string" },
+      "artifact-path": { type: "string" },
+      "coding-style-skill-path": { type: "string" },
+      "metaskill-path": { type: "string" },
+      "paper-blueprint-path": { type: "string" },
+      "experiment-plan-path": { type: "string" },
+      "coding-plan-path": { type: "string" },
+      "goal-path": { type: "string" },
+      "max-iterations": { type: "string" },
+      "max-revision-iterations": { type: "string" },
+    },
+  });
+
+  if (
+    config === undefined ||
+    targetPath === undefined ||
+    achiveDir === undefined ||
+    artifactPath === undefined ||
+    codingStyleSkillPath === undefined ||
+    metaskillPath === undefined ||
+    paperBlueprintPath === undefined ||
+    experimentPlanPath === undefined ||
+    codingPlanPath === undefined ||
+    goalPath === undefined
+  ) {
+    throw new Error(USAGE);
+  }
+
+  return {
+    configPaths: config,
+    runningOptions: {
+      targetPath,
+      achiveDir,
+      artifactPath,
+      codingStyleSkillPath,
+      metaskillPath,
+      paperBlueprintPath,
+      experimentPlanPath,
+      codingPlanPath,
+      goalPath,
+      maxIterations: Number(maxIterations ?? 10),
+      maxRevisionIterations: Number(maxRevisionIterations ?? 3),
+    },
+  };
+}
+
+export async function developingSkill(
+  team: AgentTeam<DevelopingSkillAgentVariables>,
+  options: DevelopingSkillOptions,
+): Promise<void> {
+  const logRecord: RecordCallback = (thread, record) => {
+    console.log(thread.recordToPrettyString(record));
+  };
+  let trajectoryOptimizer: Agent<TrajectoryOptimizerVariables> | undefined;
+
+  await developing(team, {
+    ...options,
+    hooks: {
+      beforeRevisionLoop: async (agentVariables, currentTask) => {
+        trajectoryOptimizer = await team.createAgent("trajectory-optimizer");
+        const repositoryScan = (
+          await trajectoryOptimizer.runStreamed(
+            {
+              ...agentVariables,
+              phase: "scan",
+              currentTask,
+            },
+            logRecord,
+          )
+        ).trim();
+        console.log(`\n# Skill trajectory repository scan\n${repositoryScan}\n`);
+      },
+      afterTodoUpdate: async (agentVariables, currentTask, revisionReport, todoUpdateReport) => {
+        if (trajectoryOptimizer === undefined) {
+          throw new Error("Trajectory optimizer must scan the repository before optimizing.");
+        }
+
+        const optimizerReport = (
+          await trajectoryOptimizer.runStreamed(
+            {
+              ...agentVariables,
+              phase: "optimize",
+              currentTask,
+              revisionReport,
+              todoUpdateReport,
+              metaskillPath: options.metaskillPath,
+            },
+            logRecord,
+          )
+        ).trim();
+
+        console.log(`\n# Skill trajectory optimizer report\n${optimizerReport}\n`);
+      },
+    },
+  });
+}
+
+export const developingSkillAgentFactories: AgentFactoryMap = {
+  ...developingAgentFactories,
+  "trajectory-optimizer": (thread, constants) => new TrajectoryOptimizerAgent(thread, constants),
+};
+
+export const developingSkillPipeline = definePipeline({
+  agentFactories: developingSkillAgentFactories,
+  parseArgs: parseDevelopingSkillArgs,
+  run: developingSkill,
+});