symphifo 0.1.0

package/SYMPHIFO.md

@@ -0,0 +1,171 @@
+# Symphifo local runtime reference
+
+This repository runs Symphifo as a pure TypeScript local orchestrator with no external tracker dependency.
+
+## What this package provides
+
+- Filesystem-backed orchestration through the local persistence runtime.
+- Optional seed issues from `src/fixtures/local-issues.json`.
+- Durable tracker state that can also start empty and accept work over HTTP.
+- Local workspace snapshots for reproducible execution.
+- Queue runner with concurrency, retries, retry backoff, and stale-run recovery.
+- Local event log, API, and dashboard through the `s3db.js` `ApiPlugin`.
+- Multi-agent pipelines with `codex` and `claude`.
+
+## Relevant files
+
+- Workflow template: [WORKFLOW.md](./WORKFLOW.md)
+- Published entrypoint: [bin/symphifo.js](./bin/symphifo.js)
+- CLI router: [src/cli.ts](./src/cli.ts)
+- Runtime engine: [src/runtime/run-local.ts](./src/runtime/run-local.ts)
+- Dashboard: [src/dashboard/index.html](./src/dashboard/index.html)
+
+## Environment variables
+
+```bash
+export SYMPHIFO_TRACKER_KIND=filesystem
+export SYMPHIFO_WORKSPACE_ROOT=$PWD
+export SYMPHIFO_PERSISTENCE=$PWD
+export SYMPHIFO_ISSUES_FILE=/path/to/issues.json
+export SYMPHIFO_ISSUES_JSON='[{"id":"LOCAL-1","title":"...","description":"...","state":"Todo"}]'
+export SYMPHIFO_AGENT_COMMAND='codex run --json "$SYMPHIFO_ISSUE_JSON"'
+export SYMPHIFO_AGENT_PROVIDER=codex
+export SYMPHIFO_WORKER_CONCURRENCY=2
+export SYMPHIFO_MAX_ATTEMPTS=3
+export SYMPHIFO_AGENT_MAX_TURNS=4
+```
+
+`SYMPHIFO_AGENT_COMMAND` is required unless `WORKFLOW.md` provides `codex.command` or `claude.command`.
+
+Node requirement:
+
+- Node.js 23 or newer
+
+## Start examples
+
+```bash
+npx symphifo
+```
+
+Default state location:
+
+```bash
+./.symphifo/
+```
+
+Override the persistence root:
+
+```bash
+npx symphifo --persistence /path/to/root
+```
+
+Run the MCP server:
+
+```bash
+npx symphifo mcp
+```
+
+Run a single cycle:
+
+```bash
+npx symphifo --once
+```
+
+Run with the API and dashboard:
+
+```bash
+npx symphifo --port 4040 --concurrency 2 --attempts 3
+```
+
+## Runtime behavior
+
+- Local bootstrap creates a source snapshot under `./.symphifo/source`.
+- Issues are loaded from the configured JSON source when available.
+- Workflow is rendered to `./.symphifo/WORKFLOW.local.md`.
+- Runtime state is stored under `./.symphifo/s3db/` by the `s3db.js` `FileSystemClient`.
+- Event log is stored in `./.symphifo/symphifo-local.log`.
+- `WORKFLOW.md` front matter and Markdown body define the execution contract when present.
+- `hooks.after_create` runs once for a new issue workspace; otherwise the runtime copies the local source snapshot.
+- `hooks.before_run` and `hooks.after_run` can wrap each agent turn.
+- `agent.provider` can be `codex` or `claude`.
+- `agent.providers[]` can mix both in one pipeline.
+- `agent.profile` resolves to local profile files from workspace or home directories.
+- `routing.enabled` can disable automatic task routing.
+- `routing.priorities` can override the default scheduler order by capability category.
+- `routing.overrides[]` can override the automatic provider/profile selection for matching tasks.
+- `routing.overrides[].match.paths` can force routing based on target directories or files.
+- Issue payloads can carry `paths[]` so routing can use the real change surface, not only text and labels.
+- When `paths[]` is omitted, Symphifo infers routing hints from path-like text mentions and from files changed inside an existing persisted workspace.
+- Symphifo derives labels like `capability:<category>` and `overlay:<name>` from the routing result for queue triage and visibility.
+- The rendered prompt is written to `symphifo-prompt.md` and exported through `SYMPHIFO_PROMPT` and `SYMPHIFO_PROMPT_FILE`.
+- Each issue runs as a multi-turn session controlled by `agent.max_turns`.
+- Each turn exports `SYMPHIFO_AGENT_PROVIDER`, `SYMPHIFO_AGENT_ROLE`, `SYMPHIFO_AGENT_PROFILE`, `SYMPHIFO_AGENT_PROFILE_FILE`, `SYMPHIFO_AGENT_PROFILE_INSTRUCTIONS`, `SYMPHIFO_SESSION_ID`, `SYMPHIFO_SESSION_KEY`, `SYMPHIFO_TURN_INDEX`, `SYMPHIFO_MAX_TURNS`, `SYMPHIFO_TURN_PROMPT`, `SYMPHIFO_TURN_PROMPT_FILE`, `SYMPHIFO_PREVIOUS_OUTPUT`, and `SYMPHIFO_RESULT_FILE`.
+- The agent can continue, finish, block, or fail by printing `SYMPHIFO_STATUS=...` or by writing `symphifo-result.json`.
+- Session and pipeline state are persisted in `s3db`.
+- Workspace JSON artifacts are temporary CLI handoff files, not the source of truth.
+- The `s3db` resources are partitioned for the main operational lookups (`state`, `capabilityCategory`, `issueId`, `kind`, `attempt`, `provider/role`).
+- The scheduler advances one turn per execution slot and resumes persisted `In Progress` work.
+- When issue priority ties, the scheduler prefers more critical capability categories first (`security`, `bugfix`, `backend`, `devops`, `frontend-ui`, `architecture`, `documentation`, `default`) unless `routing.priorities` overrides that order.
+- `npx symphifo mcp` keeps the scheduler alive even without the dashboard port.
+- `npx symphifo mcp` starts a stdio MCP server backed by the same durable `s3db` state as the runtime.
+- frontend-heavy tasks automatically carry stricter review overlays such as `impeccable` when matched by the capability resolver.
+
+## MCP capabilities
+
+Resources:
+
+- `symphifo://guide/overview`
+- `symphifo://guide/runtime`
+- `symphifo://guide/integration`
+- `symphifo://state/summary`
+- `symphifo://issues`
+- `symphifo://workspace/workflow`
+- `symphifo://issue/<id>`
+
+Tools:
+
+- `symphifo.status`
+- `symphifo.list_issues`
+- `symphifo.create_issue`
+- `symphifo.update_issue_state`
+- `symphifo.integration_config`
+
+Prompts:
+
+- `symphifo-integrate-client`
+- `symphifo-plan-issue`
+- `symphifo-review-workflow`
+
+Recommended MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "symphifo": {
+      "command": "npx",
+      "args": ["symphifo", "mcp", "--workspace", "/path/to/workspace", "--persistence", "/path/to/workspace"]
+    }
+  }
+}
+```
+
+## HTTP surface
+
+Compatibility routes:
+
+- `/api/state`
+- `/api/issues` with optional `state` and `capabilityCategory` query filters
+- `POST /api/issues`
+- `/api/issue/:id/pipeline`
+- `/api/issue/:id/sessions`
+- `/api/events` with optional `issueId`, `kind`, and `since` query filters
+- `/api/health`
+
+Generated documentation and native resources:
+
+- `/docs`
+- `/symphifo_runtime_state`
+- `/symphifo_issues`
+- `/symphifo_events`
+- `/symphifo_agent_sessions`
+- `/symphifo_agent_pipelines`

package/WORKFLOW.md

@@ -0,0 +1,39 @@
+---
+tracker:
+  kind: filesystem
+workspace:
+  root: ./.symphifo/workspaces
+agent:
+  provider: codex
+  profile: ""
+  max_concurrent_agents: 2
+  max_attempts: 3
+  max_turns: 4
+  providers:
+    - provider: claude
+      role: planner
+      profile: ""
+    - provider: codex
+      role: executor
+      profile: ""
+    - provider: claude
+      role: reviewer
+      profile: ""
+codex:
+  command: ""
+claude:
+  command: ""
+routing:
+  enabled: true
+  priorities: {}
+  overrides: []
+---
+
+You are working on {{ issue.identifier }}.
+
+Title: {{ issue.title }}
+Description:
+{{ issue.description }}
+
+Target paths:
+{{ issue.paths }}

package/bin/symphifo.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { cwd, env, exit, argv, execPath } from "node:process";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageRoot = resolve(__dirname, "..");
+const workspaceRoot = env.SYMPHIFO_WORKSPACE_ROOT ?? cwd();
+const cliScript = resolve(packageRoot, "src", "cli.ts");
+const require = createRequire(import.meta.url);
+const tsxCli = require.resolve("tsx/cli");
+
+const child = spawn(execPath, [tsxCli, cliScript, ...argv.slice(2)], {
+  cwd: workspaceRoot,
+  stdio: "inherit",
+  env: {
+    ...env,
+    SYMPHIFO_WORKSPACE_ROOT: workspaceRoot,
+  },
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+
+  exit(code ?? 1);
+});
+
+child.on("error", (error) => {
+  console.error(`Failed to start symphifo CLI: ${String(error)}`);
+  exit(1);
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "symphifo",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Filesystem-backed local Symphifo orchestrator with a TypeScript CLI, MCP mode, and multi-agent Codex or Claude workflows.",
+  "bin": {
+    "symphifo": "./bin/symphifo.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "WORKFLOW.md",
+    "README.md",
+    "SYMPHIFO.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forattini-dev/symphifo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/forattini-dev/symphifo/issues"
+  },
+  "homepage": "https://github.com/forattini-dev/symphifo#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=23"
+  },
+  "dependencies": {
+    "cli-args-parser": "^1.0.6",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "raffel": "^1.0.7",
+    "s3db.js": "^21.2.2",
+    "tsx": "^4.21.0",
+    "yaml": "^2.8.1"
+  },
+  "scripts": {
+    "start": "node ./bin/symphifo.js",
+    "mcp": "node ./bin/symphifo.js mcp"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,213 @@
+import { spawn } from "node:child_process";
+import { cwd, env, execPath, exit, kill, pid } from "node:process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import { createCLI, type CommandParseResult } from "cli-args-parser";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageRoot = resolve(__dirname, "..");
+const require = createRequire(import.meta.url);
+const packageJson = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8")) as {
+  name?: string;
+  version?: string;
+  description?: string;
+};
+const runtimeScript = resolve(packageRoot, "src", "runtime", "run-local.ts");
+const mcpScript = resolve(packageRoot, "src", "mcp", "server.ts");
+const tsxCli = require.resolve("tsx/cli");
+
+const commonOptions = {
+  workspace: {
+    type: "string",
+    description: "Target workspace root. Defaults to the current directory.",
+  },
+  persistence: {
+    type: "string",
+    description: "Persistence root. Defaults to the current directory.",
+  },
+  port: {
+    type: "number",
+    description: "Start the local API/dashboard on the provided port.",
+  },
+  concurrency: {
+    type: "number",
+    description: "Maximum number of concurrent workers.",
+  },
+  attempts: {
+    type: "number",
+    description: "Maximum attempts per issue.",
+  },
+  poll: {
+    type: "number",
+    description: "Scheduler interval in milliseconds.",
+  },
+  once: {
+    type: "boolean",
+    description: "Process one scheduler cycle and exit.",
+    default: false,
+  },
+} as const;
+
+function getStringOption(result: CommandParseResult, key: keyof typeof commonOptions): string | undefined {
+  const value = result.options[key];
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function getNumberOption(result: CommandParseResult, key: keyof typeof commonOptions): number | undefined {
+  const value = result.options[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function getBooleanOption(result: CommandParseResult, key: keyof typeof commonOptions): boolean {
+  return result.options[key] === true;
+}
+
+function buildRuntimeArgs(result: CommandParseResult): string[] {
+  const runtimeArgs: string[] = [];
+  const workspace = getStringOption(result, "workspace");
+  const persistence = getStringOption(result, "persistence");
+  const port = getNumberOption(result, "port");
+  const concurrency = getNumberOption(result, "concurrency");
+  const attempts = getNumberOption(result, "attempts");
+  const poll = getNumberOption(result, "poll");
+
+  if (workspace) {
+    runtimeArgs.push("--workspace", workspace);
+  }
+  if (persistence) {
+    runtimeArgs.push("--persistence", persistence);
+  }
+  if (typeof port === "number") {
+    runtimeArgs.push("--port", String(port));
+  }
+  if (typeof concurrency === "number") {
+    runtimeArgs.push("--concurrency", String(concurrency));
+  }
+  if (typeof attempts === "number") {
+    runtimeArgs.push("--attempts", String(attempts));
+  }
+  if (typeof poll === "number") {
+    runtimeArgs.push("--poll", String(poll));
+  }
+  if (getBooleanOption(result, "once")) {
+    runtimeArgs.push("--once");
+  }
+
+  return runtimeArgs;
+}
+
+async function runRuntime(mode: "cli" | "mcp", result: CommandParseResult): Promise<void> {
+  const workspace = getStringOption(result, "workspace");
+  const workspaceRoot = resolve(workspace ?? env.SYMPHIFO_WORKSPACE_ROOT ?? cwd());
+  const runtimeArgs = buildRuntimeArgs(result);
+
+  const outcome = await new Promise<{ code?: number | null; signal?: NodeJS.Signals | null }>((resolvePromise, rejectPromise) => {
+    const child = spawn(execPath, [tsxCli, runtimeScript, ...runtimeArgs], {
+      cwd: workspaceRoot,
+      stdio: "inherit",
+      env: {
+        ...env,
+        SYMPHIFO_INTERFACE: mode,
+        SYMPHIFO_WORKSPACE_ROOT: workspaceRoot,
+      },
+    });
+
+    child.on("exit", (code, signal) => {
+      resolvePromise({ code, signal });
+    });
+
+    child.on("error", (error) => {
+      rejectPromise(error);
+    });
+  });
+
+  if (outcome.signal) {
+    kill(pid, outcome.signal);
+    return;
+  }
+
+  if (typeof outcome.code === "number" && outcome.code !== 0) {
+    exit(outcome.code);
+  }
+}
+
+async function runMcpServer(result: CommandParseResult): Promise<void> {
+  const workspace = getStringOption(result, "workspace");
+  const persistence = getStringOption(result, "persistence");
+  const workspaceRoot = resolve(workspace ?? env.SYMPHIFO_WORKSPACE_ROOT ?? cwd());
+  const persistenceRoot = resolve(persistence ?? env.SYMPHIFO_PERSISTENCE ?? workspaceRoot);
+
+  const outcome = await new Promise<{ code?: number | null; signal?: NodeJS.Signals | null }>((resolvePromise, rejectPromise) => {
+    const child = spawn(execPath, [tsxCli, mcpScript], {
+      cwd: workspaceRoot,
+      stdio: "inherit",
+      env: {
+        ...env,
+        SYMPHIFO_WORKSPACE_ROOT: workspaceRoot,
+        SYMPHIFO_PERSISTENCE: persistenceRoot,
+      },
+    });
+
+    child.on("exit", (code, signal) => {
+      resolvePromise({ code, signal });
+    });
+
+    child.on("error", (error) => {
+      rejectPromise(error);
+    });
+  });
+
+  if (outcome.signal) {
+    kill(pid, outcome.signal);
+    return;
+  }
+
+  if (typeof outcome.code === "number" && outcome.code !== 0) {
+    exit(outcome.code);
+  }
+}
+
+const cli = createCLI({
+  name: packageJson.name ?? "symphifo",
+  version: packageJson.version ?? "0.0.0",
+  description: packageJson.description ?? "Filesystem-backed local multi-agent orchestrator.",
+  commands: {
+    run: {
+      description: "Run the local Symphifo runtime with the dashboard/API enabled when --port is provided.",
+      options: commonOptions,
+      handler: (result) => runRuntime("cli", result),
+    },
+    mcp: {
+      description: "Run a Symphifo MCP server over stdio with resources, tools, and prompts backed by the local durable store.",
+      options: commonOptions,
+      handler: (result) => runMcpServer(result),
+    },
+  },
+});
+
+function normalizeArgs(rawArgs: string[]): string[] {
+  if (rawArgs.length === 0) {
+    return ["run"];
+  }
+
+  const first = rawArgs[0];
+  if (["--help", "-h", "help", "--version", "-v", "version"].includes(first)) {
+    return rawArgs;
+  }
+
+  if (first.startsWith("-")) {
+    return ["run", ...rawArgs];
+  }
+
+  return rawArgs;
+}
+
+const args = normalizeArgs(process.argv.slice(2));
+
+cli.run(args).catch((error) => {
+  console.error(`Failed to start symphifo CLI: ${String(error)}`);
+  exit(1);
+});