@cephalization/math 0.2.0

package/README.md

@@ -0,0 +1,190 @@
+# math - Multi-Agent Todo Harness
+
+A light meta agent orchestration harness designed to coordinate multiple AI agents working together to accomplish tasks from a TODO list.
+
+## Core Concept
+
+The primary responsibility of this harness is to **reduce context bloat** by digesting a project plan into three documents:
+
+| Document | Purpose |
+| ---------- | --------- |
+| `TASKS.md` | Task list with status tracking and dependencies |
+| `LEARNINGS.md` | Accumulated insights from completed tasks |
+| `PROMPT.md` | System prompt with guardrails ("signs") |
+
+The harness consists of a simple for-loop, executing a new coding agent with a mandate from `PROMPT.md` to complete a *single* task from `TASKS.md`, while reading and recording any insight gained during the work into `LEARNINGS.md`.
+
+## Requirements
+
+**[Bun](https://bun.sh) is required** to run this tool. Node.js is not supported.
+
+```bash
+# Install Bun (macOS, Linux, WSL)
+curl -fsSL https://bun.sh/install | bash
+```
+
+Why Bun?
+- This tool is written in TypeScript and uses Bun's native TypeScript execution (no compilation step)
+- The CLI uses a `#!/usr/bin/env bun` shebang for direct execution
+- Bun's speed makes the agent loop faster and more responsive
+
+## Installation
+
+### From npm (recommended)
+
+```bash
+# One-off usage (recommended)
+bunx @cephalization/math <command>
+
+# Global install
+bun install -g @cephalization/math
+```
+
+### From source (for development)
+
+```bash
+git clone https://github.com/cephalization/math.git
+cd math
+bun install
+bun link
+```
+
+## Usage
+
+### Initialize a project
+
+```bash
+math init
+```
+
+Creates a `todo/` directory with template files and offers to run **planning mode** to help you break down your goal into tasks.
+
+Options:
+
+- `--no-plan` - Skip the planning prompt
+- `--model <model>` - Model to use (default: `anthropic/claude-opus-4-5`)
+
+### Plan your tasks
+
+```bash
+math plan
+```
+
+Options:
+
+- `--model <model>` - Model to use (default: `anthropic/claude-opus-4-5`)
+- `--quick` - Skip clarifying questions and generate plan immediately
+
+Interactively plan your tasks with AI assistance. The planner uses a two-phase approach:
+
+1. **Clarification phase**: The AI analyzes your goal and asks 3-5 clarifying questions
+2. **Planning phase**: Using your answers, it generates a well-structured task list
+
+Use `--quick` to skip the clarification phase if you want a faster, assumption-based plan.
+
+### Run the agent loop
+
+```bash
+math run
+```
+
+Options:
+
+- `--model <model>` - Model to use (default: `anthropic/claude-opus-4-5`)
+- `--max-iterations <n>` - Safety limit (default: 100)
+- `--pause <seconds>` - Pause between iterations (default: 3)
+
+### Check status
+
+```bash
+math status
+```
+
+Shows task progress with a visual progress bar and next task info.
+
+### Start a new sprint
+
+```bash
+math iterate
+```
+
+Backs up `todo/` to `todo-{M}-{D}-{Y}/` and resets for a new goal:
+
+- TASKS.md and LEARNINGS.md are reset to templates
+- PROMPT.md is preserved (keeping your accumulated "signs")
+- Offers to run planning mode for your new goal
+
+Options:
+
+- `--no-plan` - Skip the planning prompt
+
+## Task Format
+
+Tasks in `TASKS.md` follow this format:
+
+```markdown
+### task-id
+
+- content: Description of what to implement
+- status: pending | in_progress | complete
+- dependencies: task-1, task-2
+```
+
+## The Loop
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      math run (loop)                        │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │  1. Check TASKS.md for pending tasks                  │  │
+│  │  2. If all complete → EXIT SUCCESS                    │  │
+│  │  3. Invoke agent with PROMPT.md + TASKS.md            │  │
+│  │  4. Agent: pick task → implement → test → commit      │  │
+│  │  5. Agent: update TASKS.md → log learnings → EXIT     │  │
+│  │  6. Loop back to step 1                               │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Planning Mode
+
+When you run `math init`, `math iterate`, or `math plan`, the harness can invoke [OpenCode](https://opencode.ai/docs/cli/) to help you plan:
+
+1. You describe your high-level goal
+2. OpenCode asks clarifying questions to understand your requirements
+3. You answer the questions interactively
+4. OpenCode breaks your goal into discrete, implementable tasks
+5. Tasks are written to `TASKS.md` with proper dependencies
+6. You're ready to run `math run`
+
+This bridges the gap between "I want to build X" and a structured task list. The clarifying questions phase uses OpenCode's session continuation feature to maintain context across the conversation.
+
+## Signs (Guardrails)
+
+"Signs" are explicit guardrails in `PROMPT.md` that prevent common agent mistakes. Add new signs whenever you discover a failure mode:
+
+```markdown
+### SIGN: Descriptive Name
+
+Clear explanation of what to do or avoid.
+
+❌ WRONG: Example of the mistake
+✅ RIGHT: Example of correct behavior
+```
+
+Signs accumulate over time, making the agent increasingly reliable.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MODEL`  | `anthropic/claude-opus-4-20250514` | Model to use |
+
+## Credits
+
+- **Ralph Methodology**: [Geoffrey Huntley](https://ghuntley.com/ralph/)
+- **Agent Runtime**: [OpenCode](https://opencode.ai)
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,155 @@
+#!/usr/bin/env bun
+
+import { init } from "./src/commands/init";
+import { run } from "./src/commands/run";
+import { status } from "./src/commands/status";
+import { iterate } from "./src/commands/iterate";
+import { plan } from "./src/commands/plan";
+import { prune } from "./src/commands/prune";
+import { DEFAULT_MODEL } from "./src/constants";
+
+// ANSI colors
+const colors = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+};
+
+function printHelp() {
+  console.log(`
+${colors.bold}math${colors.reset} - Multi-Agent Todo Harness
+
+A light meta agent orchestration harness designed to coordinate multiple AI 
+agents working together to accomplish tasks from a TODO list.
+
+${colors.bold}USAGE${colors.reset}
+  math <command> [options]
+
+${colors.bold}COMMANDS${colors.reset}
+  ${colors.cyan}init${colors.reset}      Create todo/ directory with template files
+  ${colors.cyan}plan${colors.reset}      Run planning mode to flesh out tasks
+  ${colors.cyan}run${colors.reset}       Start the agent loop until all tasks complete
+  ${colors.cyan}status${colors.reset}    Show current task counts
+  ${colors.cyan}iterate${colors.reset}   Backup todo/ and reset for a new sprint
+  ${colors.cyan}prune${colors.reset}     Delete backup artifacts (todo-M-D-Y directories)
+  ${colors.cyan}help${colors.reset}      Show this help message
+
+${colors.bold}OPTIONS${colors.reset}
+  ${colors.dim}--model <model>${colors.reset}          Model to use (default: ${DEFAULT_MODEL})
+  ${colors.dim}--max-iterations <n>${colors.reset}    Safety limit (default: 100)
+  ${colors.dim}--pause <seconds>${colors.reset}       Pause between iterations (default: 3)
+  ${colors.dim}--no-plan${colors.reset}              Skip planning mode after init/iterate
+  ${colors.dim}--ui${colors.reset}                   Enable web UI server (run command only)
+  ${colors.dim}--quick${colors.reset}                Skip clarifying questions in plan mode
+  ${colors.dim}--force${colors.reset}                Skip confirmation prompts (prune)
+
+${colors.bold}EXAMPLES${colors.reset}
+  ${colors.dim}# Initialize and plan a new project${colors.reset}
+  math init
+
+  ${colors.dim}# Initialize without planning${colors.reset}
+  math init --no-plan
+
+  ${colors.dim}# Run planning mode on existing todo/${colors.reset}
+  math plan
+
+  ${colors.dim}# Quick planning without clarifying questions${colors.reset}
+  math plan --quick
+
+  ${colors.dim}# Run the agent loop${colors.reset}
+  math run
+
+  ${colors.dim}# Run with web UI${colors.reset}
+  math run --ui
+
+  ${colors.dim}# Check task status${colors.reset}
+  math status
+
+  ${colors.dim}# Start a new sprint (backup current, reset, plan)${colors.reset}
+  math iterate
+`);
+}
+
+function parseArgs(args: string[]): Record<string, string | boolean> {
+  const parsed: Record<string, string | boolean> = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg) continue;
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = args[i + 1];
+      if (next && !next.startsWith("--")) {
+        parsed[key] = next;
+        i++;
+      } else {
+        parsed[key] = true;
+      }
+    }
+  }
+  return parsed;
+}
+
+async function main() {
+  const [command, ...rest] = Bun.argv.slice(2);
+  const options = parseArgs(rest);
+
+  try {
+    switch (command) {
+      case "init":
+        await init({
+          skipPlan: !!options["no-plan"],
+          model: options.model as string,
+        });
+        break;
+      case "plan":
+        await plan({
+          model: options.model as string | undefined,
+          quick: !!options.quick,
+        });
+        break;
+      case "run":
+        await run(options);
+        break;
+      case "status":
+        await status();
+        break;
+      case "iterate":
+        await iterate({
+          skipPlan: !!options["no-plan"],
+          model: options.model as string,
+        });
+        break;
+      case "prune":
+        await prune({
+          force: !!options.force,
+        });
+        break;
+      case "help":
+      case "--help":
+      case "-h":
+      case undefined:
+        printHelp();
+        break;
+      default:
+        console.error(
+          `${colors.red}Unknown command: ${command}${colors.reset}`
+        );
+        printHelp();
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(
+      `${colors.red}Error: ${error instanceof Error ? error.message : error}${
+        colors.reset
+      }`
+    );
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@cephalization/math",
+  "version": "0.2.0",
+  "author": "Tony Powell <powell.anthonyd@proton.me>",
+  "access": "public",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cephalization/math"
+  },
+  "homepage": "https://github.com/cephalization/math",
+  "bugs": {
+    "url": "https://github.com/cephalization/math/issues"
+  },
+  "description": "Multi-Agent Todo Harness - A light meta agent orchestration harness",
+  "type": "module",
+  "bin": {
+    "math": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "bun index.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "changeset": "bunx changeset"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.8",
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "multi-agent",
+    "todo",
+    "orchestration",
+    "bun"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@types/react": "^19.2.8",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3"
+  }
+}

package/src/agent.test.ts

@@ -0,0 +1,179 @@
+import { test, expect, describe } from "bun:test";
+import {
+  MockAgent,
+  createMockAgent,
+  createLogEntry,
+  createAgentOutput,
+  type LogCategory,
+  type AgentRunOptions,
+} from "./agent";
+
+describe("MockAgent", () => {
+  test("isAvailable returns true by default", async () => {
+    const agent = createMockAgent();
+    expect(await agent.isAvailable()).toBe(true);
+  });
+
+  test("isAvailable returns false when configured", async () => {
+    const agent = createMockAgent({ available: false });
+    expect(await agent.isAvailable()).toBe(false);
+  });
+
+  test("run returns default logs and output", async () => {
+    const agent = createMockAgent();
+    const options: AgentRunOptions = {
+      model: "test-model",
+      prompt: "test prompt",
+      files: ["file1.md", "file2.md"],
+    };
+
+    const result = await agent.run(options);
+
+    expect(result.exitCode).toBe(0);
+    expect(result.logs).toHaveLength(2);
+    expect(result.logs[0]!.category).toBe("info");
+    expect(result.logs[0]!.message).toBe("Mock agent starting...");
+    expect(result.logs[1]!.category).toBe("success");
+    expect(result.logs[1]!.message).toBe("Mock agent completed");
+    expect(result.output).toHaveLength(1);
+    expect(result.output[0]!.text).toBe("Mock agent output\n");
+  });
+
+  test("run uses configured logs", async () => {
+    const customLogs = [
+      { category: "info" as LogCategory, message: "Custom log 1" },
+      { category: "warning" as LogCategory, message: "Custom warning" },
+      { category: "error" as LogCategory, message: "Custom error" },
+    ];
+    const agent = createMockAgent({ logs: customLogs });
+
+    const result = await agent.run({
+      model: "test",
+      prompt: "test",
+      files: [],
+    });
+
+    expect(result.logs).toHaveLength(3);
+    expect(result.logs[0]!.message).toBe("Custom log 1");
+    expect(result.logs[1]!.message).toBe("Custom warning");
+    expect(result.logs[2]!.message).toBe("Custom error");
+  });
+
+  test("run uses configured output", async () => {
+    const customOutput = ["Line 1\n", "Line 2\n", "Line 3\n"];
+    const agent = createMockAgent({ output: customOutput });
+
+    const result = await agent.run({
+      model: "test",
+      prompt: "test",
+      files: [],
+    });
+
+    expect(result.output).toHaveLength(3);
+    expect(result.output[0]!.text).toBe("Line 1\n");
+    expect(result.output[1]!.text).toBe("Line 2\n");
+    expect(result.output[2]!.text).toBe("Line 3\n");
+  });
+
+  test("run uses configured exit code", async () => {
+    const agent = createMockAgent({ exitCode: 1 });
+
+    const result = await agent.run({
+      model: "test",
+      prompt: "test",
+      files: [],
+    });
+
+    expect(result.exitCode).toBe(1);
+  });
+
+  test("run calls event callbacks", async () => {
+    const agent = createMockAgent({
+      logs: [{ category: "info", message: "Test log" }],
+      output: ["Test output"],
+    });
+
+    const receivedLogs: string[] = [];
+    const receivedOutput: string[] = [];
+
+    await agent.run({
+      model: "test",
+      prompt: "test",
+      files: [],
+      events: {
+        onLog: (entry) => receivedLogs.push(entry.message),
+        onOutput: (out) => receivedOutput.push(out.text),
+      },
+    });
+
+    expect(receivedLogs).toEqual(["Test log"]);
+    expect(receivedOutput).toEqual(["Test output"]);
+  });
+
+  test("configure updates agent behavior", async () => {
+    const agent = createMockAgent();
+
+    // Initial run
+    let result = await agent.run({
+      model: "test",
+      prompt: "test",
+      files: [],
+    });
+    expect(result.exitCode).toBe(0);
+
+    // Reconfigure
+    agent.configure({
+      exitCode: 2,
+      logs: [{ category: "error", message: "Reconfigured error" }],
+      output: ["Reconfigured output"],
+    });
+
+    // Run again
+    result = await agent.run({
+      model: "test",
+      prompt: "test",
+      files: [],
+    });
+
+    expect(result.exitCode).toBe(2);
+    expect(result.logs[0]!.message).toBe("Reconfigured error");
+    expect(result.output[0]!.text).toBe("Reconfigured output");
+  });
+
+  test("run respects delay configuration", async () => {
+    const agent = createMockAgent({ delay: 50 });
+
+    const start = Date.now();
+    await agent.run({
+      model: "test",
+      prompt: "test",
+      files: [],
+    });
+    const elapsed = Date.now() - start;
+
+    expect(elapsed).toBeGreaterThanOrEqual(49); // 50ms delay, but allow for some jitter
+  });
+});
+
+describe("helper functions", () => {
+  test("createLogEntry creates entry with timestamp", () => {
+    const before = new Date();
+    const entry = createLogEntry("success", "Test message");
+    const after = new Date();
+
+    expect(entry.category).toBe("success");
+    expect(entry.message).toBe("Test message");
+    expect(entry.timestamp.getTime()).toBeGreaterThanOrEqual(before.getTime());
+    expect(entry.timestamp.getTime()).toBeLessThanOrEqual(after.getTime());
+  });
+
+  test("createAgentOutput creates output with timestamp", () => {
+    const before = new Date();
+    const output = createAgentOutput("Test output");
+    const after = new Date();
+
+    expect(output.text).toBe("Test output");
+    expect(output.timestamp.getTime()).toBeGreaterThanOrEqual(before.getTime());
+    expect(output.timestamp.getTime()).toBeLessThanOrEqual(after.getTime());
+  });
+});