@team-agent/installer 0.1.0

package/examples/team.spec.yaml

@@ -0,0 +1,206 @@
+version: 1
+team:
+  name: teamspec-full-example
+  mode: supervisor_worker
+  objective: Build, research, review, and document a code change with Codex CLI workers.
+  workspace: .
+leader:
+  id: leader
+  role: leader
+  provider: codex
+  model: null
+  tools:
+    - fs_read
+    - fs_list
+    - mcp_team
+    - provider_builtin
+  context_policy:
+    keep_user_thread: true
+    receive_worker_outputs: structured_only
+    max_worker_result_tokens: 4000
+agents:
+  - id: codex_implementer
+    role: implementation_engineer
+    provider: codex
+    model: null
+    working_directory: .
+    system_prompt:
+      inline: |
+        You are the implementation worker. Make focused code changes, run relevant tests,
+        and report a result_envelope_v1 with changed files, tests, risks, artifacts, and next actions.
+      file: null
+    tools:
+      - fs_read
+      - fs_write
+      - fs_list
+      - execute_bash
+      - git_diff
+      - mcp_team
+      - provider_builtin
+    permission_mode: restricted
+    preferred_for:
+      - implementation
+      - bug_fix
+      - test
+    avoid_for:
+      - final_risk_signoff
+    output_contract:
+      format: result_envelope_v1
+      required_fields:
+        - task_id
+        - status
+        - summary
+        - artifacts
+  - id: codex_researcher
+    role: researcher
+    provider: codex
+    model: null
+    working_directory: .
+    system_prompt:
+      inline: |
+        You are the research worker. Prefer read-only analysis and summarize findings
+        as result_envelope_v1. Do not edit files.
+      file: null
+    tools:
+      - fs_read
+      - fs_list
+      - network
+      - mcp_team
+      - provider_builtin
+    permission_mode: restricted
+    preferred_for:
+      - research
+      - architecture
+      - docs
+    avoid_for:
+      - implementation
+    output_contract:
+      format: result_envelope_v1
+      required_fields:
+        - task_id
+        - status
+        - summary
+        - artifacts
+  - id: codex_reviewer
+    role: code_reviewer
+    provider: codex
+    model: null
+    working_directory: .
+    system_prompt:
+      inline: |
+        You are the reviewer. Find correctness, regression, security, and missing-test risks.
+        Stay read-only unless the leader explicitly changes your permissions.
+      file: null
+    tools:
+      - fs_read
+      - fs_list
+      - git_diff
+      - mcp_team
+      - provider_builtin
+    permission_mode: restricted
+    preferred_for:
+      - review
+      - risk_check
+    avoid_for:
+      - implementation
+    output_contract:
+      format: result_envelope_v1
+      required_fields:
+        - task_id
+        - status
+        - summary
+        - artifacts
+routing:
+  default_assignee: leader
+  rules:
+    - id: implementation-to-codex
+      when: task.type in ["implementation", "bug_fix", "test"]
+      assign_to: codex_implementer
+      priority: 100
+    - id: research-to-codex
+      when: task.type in ["research", "architecture", "docs"]
+      assign_to: codex_researcher
+      priority: 90
+    - id: review-to-codex
+      when: task.type in ["review", "risk_check"]
+      assign_to: codex_reviewer
+      priority: 90
+communication:
+  protocol: mcp_inbox
+  topology: leader_centered
+  worker_to_worker: false
+  ack_timeout_sec: 60
+  result_format: result_envelope_v1
+  message_store:
+    sqlite: .team/runtime/team.db
+    mirror_files: .team/messages
+runtime:
+  backend: tmux
+  display_backend: none
+  session_name: teamspec-full-example
+  auto_launch: true
+  require_user_approval_before_launch: true
+  dangerous_auto_approve: false
+  max_active_agents: 3
+  startup_order:
+    - codex_implementer
+    - codex_researcher
+    - codex_reviewer
+context:
+  state_file: team_state.md
+  artifact_dir: .team/artifacts
+  log_dir: .team/logs
+  summarization:
+    worker_full_logs: retain_outside_leader_context
+    state_update: after_each_result
+tasks:
+  - id: task_research
+    title: Read the task context and identify design risks.
+    type: research
+    assignee: null
+    deps: []
+    acceptance:
+      - Result envelope includes summary and risks.
+    status: pending
+    requires_tools:
+      - fs_read
+    files:
+      - "**/*"
+    risk: medium
+    retry_limit: 1
+    human_confirmation: false
+  - id: task_impl
+    title: Implement the requested code change and run tests.
+    type: implementation
+    assignee: null
+    deps:
+      - task_research
+    acceptance:
+      - Changed files and tests are reported.
+    status: pending
+    requires_tools:
+      - fs_write
+      - execute_bash
+    files:
+      - "src/**"
+      - "tests/**"
+    risk: medium
+    retry_limit: 1
+    human_confirmation: false
+  - id: task_review
+    title: Review implementation output and identify regressions.
+    type: review
+    assignee: null
+    deps:
+      - task_impl
+    acceptance:
+      - Findings are structured with risk and artifacts.
+    status: pending
+    requires_tools:
+      - fs_read
+      - git_diff
+    files:
+      - "**/*"
+    risk: medium
+    retry_limit: 0
+    human_confirmation: false

package/examples/team_state.md

@@ -0,0 +1,35 @@
+# Team State
+
+Updated: 2026-05-12T14:16:08.963244+00:00
+
+## Objective
+
+Build, research, review, and document a code change with Codex CLI workers.
+
+## Team
+
+- Name: teamspec-full-example
+- Runtime session: teamspec-full-example
+
+## Agents
+
+- codex_implementer: implementation_engineer on codex (running)
+- codex_researcher: researcher on codex (running)
+- codex_reviewer: code_reviewer on codex (running)
+
+## Task Graph
+
+- task_research [pending], assignee=codex_researcher, deps=none: Read the task context and identify design risks.
+- task_impl [pending], assignee=codex_implementer, deps=task_research: Implement the requested code change and run tests.
+- task_review [pending], assignee=codex_reviewer, deps=task_impl: Review implementation output and identify regressions.
+
+## Latest Results
+
+
+## Blockers
+
+- None
+
+## Next Step
+
+- Continue routing ready tasks and collect result envelopes.

package/npm/install.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, "..");
+const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+
+const command = process.argv[2] || "install";
+const args = process.argv.slice(3);
+
+if (["-h", "--help", "help"].includes(command)) {
+  printHelp();
+  process.exit(0);
+}
+
+if (command === "install" || command === "update") {
+  install(args);
+} else if (command === "doctor") {
+  runDoctor(args);
+} else if (command === "uninstall") {
+  uninstall(args);
+} else {
+  console.error(`unknown command: ${command}`);
+  printHelp();
+  process.exit(2);
+}
+
+function printHelp() {
+  console.log(`Team Agent installer
+
+Usage:
+  npx @team-agent/installer@latest install
+  npx @team-agent/installer@latest doctor
+  npx @team-agent/installer@latest uninstall
+
+Options:
+  --prefix <dir>       wrapper install prefix, default ~/.local
+  --runtime-dir <dir>  stable runtime root, default ~/.team-agent/runtime
+  --python <path>      Python executable, otherwise TEAM_AGENT_PYTHON, python3, python
+  --purge-runtime      uninstall also removes the runtime root
+`);
+}
+
+function install(argv) {
+  const opts = parseOptions(argv);
+  const python = resolvePython(opts.python);
+  const prefix = path.resolve(expandHome(opts.prefix || path.join(os.homedir(), ".local")));
+  const binDir = path.join(prefix, "bin");
+  const runtimeRoot = path.resolve(expandHome(opts.runtimeDir || path.join(os.homedir(), ".team-agent", "runtime")));
+  const version = packageJson.version || "dev";
+  const dest = path.join(runtimeRoot, version);
+  const tmp = path.join(runtimeRoot, `.${version}.${process.pid}.tmp`);
+  const backup = path.join(runtimeRoot, `.${version}.previous`);
+
+  fs.mkdirSync(runtimeRoot, { recursive: true });
+  fs.rmSync(tmp, { recursive: true, force: true });
+  copyTree(packageRoot, tmp);
+  fs.rmSync(backup, { recursive: true, force: true });
+  if (fs.existsSync(dest)) {
+    fs.renameSync(dest, backup);
+  }
+  fs.renameSync(tmp, dest);
+
+  fs.mkdirSync(binDir, { recursive: true });
+  writeWrapper(path.join(binDir, "team-agent"), dest, "team_agent", python);
+  writeWrapper(path.join(binDir, "team_orchestrator"), dest, "team_agent.mcp_server", python);
+  writeWrapper(path.join(binDir, "team-agent-coordinator"), dest, "team_agent.coordinator", python);
+
+  const teamAgent = path.join(binDir, "team-agent");
+  const skill = spawnSync(teamAgent, ["install-skill", "--target", "all"], {
+    text: true,
+    encoding: "utf8",
+  });
+  if (skill.status !== 0) {
+    process.stderr.write(skill.stderr || skill.stdout || "team-agent install-skill failed\n");
+    process.exit(skill.status || 1);
+  }
+
+  console.log(`installed: ${teamAgent}`);
+  console.log(`runtime: ${dest}`);
+  console.log(`python: ${python}`);
+  console.log(`skill: installed for Codex and Claude`);
+  console.log(`PATH: ensure ${binDir} is on PATH`);
+
+  const doctor = spawnSync(teamAgent, ["doctor", "--json"], { text: true, encoding: "utf8" });
+  if (doctor.status === 0) {
+    console.log("doctor: ok");
+  } else {
+    console.log("doctor: has blockers; run `team-agent doctor` after updating PATH");
+  }
+}
+
+function runDoctor(argv) {
+  const opts = parseOptions(argv);
+  const prefix = path.resolve(expandHome(opts.prefix || path.join(os.homedir(), ".local")));
+  const teamAgent = path.join(prefix, "bin", "team-agent");
+  if (!fs.existsSync(teamAgent)) {
+    console.error(`team-agent wrapper not found: ${teamAgent}`);
+    process.exit(1);
+  }
+  const proc = spawnSync(teamAgent, ["doctor"], { stdio: "inherit" });
+  process.exit(proc.status || 0);
+}
+
+function uninstall(argv) {
+  const opts = parseOptions(argv);
+  const prefix = path.resolve(expandHome(opts.prefix || path.join(os.homedir(), ".local")));
+  for (const name of ["team-agent", "team_orchestrator", "team-agent-coordinator"]) {
+    fs.rmSync(path.join(prefix, "bin", name), { force: true });
+  }
+  for (const skillDir of [
+    path.join(os.homedir(), ".codex", "skills", "team-agent"),
+    path.join(os.homedir(), ".claude", "skills", "team-agent"),
+  ]) {
+    fs.rmSync(skillDir, { recursive: true, force: true });
+  }
+  console.log(`removed wrappers from ${path.join(prefix, "bin")}`);
+  console.log("removed skills from ~/.codex/skills/team-agent and ~/.claude/skills/team-agent");
+  if (opts.purgeRuntime) {
+    const runtimeRoot = path.resolve(expandHome(opts.runtimeDir || path.join(os.homedir(), ".team-agent", "runtime")));
+    fs.rmSync(runtimeRoot, { recursive: true, force: true });
+    console.log(`removed runtime root ${runtimeRoot}`);
+  } else {
+    console.log("runtime directories are left under ~/.team-agent/runtime for rollback; pass --purge-runtime only when no teams are running.");
+  }
+}
+
+function parseOptions(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const item = argv[i];
+    if (item === "--prefix") {
+      opts.prefix = argv[++i];
+    } else if (item.startsWith("--prefix=")) {
+      opts.prefix = item.slice("--prefix=".length);
+    } else if (item === "--runtime-dir") {
+      opts.runtimeDir = argv[++i];
+    } else if (item.startsWith("--runtime-dir=")) {
+      opts.runtimeDir = item.slice("--runtime-dir=".length);
+    } else if (item === "--python") {
+      opts.python = argv[++i];
+    } else if (item.startsWith("--python=")) {
+      opts.python = item.slice("--python=".length);
+    } else if (item === "--purge-runtime") {
+      opts.purgeRuntime = true;
+    } else {
+      throw new Error(`unknown option: ${item}`);
+    }
+  }
+  return opts;
+}
+
+function resolvePython(explicit) {
+  const candidates = pythonCandidates(explicit);
+  for (const candidate of candidates) {
+    const resolved = path.isAbsolute(candidate) ? candidate : which(candidate) || candidate;
+    if (!resolved) {
+      continue;
+    }
+    const proc = spawnSync(resolved, ["-c", "import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)"], {
+      text: true,
+      encoding: "utf8",
+    });
+    if (proc.status === 0) {
+      return resolved;
+    }
+  }
+  console.error("No usable Python >= 3.10 found. Set TEAM_AGENT_PYTHON or pass --python.");
+  process.exit(1);
+}
+
+function pythonCandidates(explicit) {
+  const candidates = [explicit, process.env.TEAM_AGENT_PYTHON, "python3", "python"];
+  const commonPaths = [
+    "/opt/homebrew/bin/python3",
+    "/usr/local/bin/python3",
+    "/usr/bin/python3",
+    "/opt/homebrew/opt/python@3/bin/python3",
+    "/usr/local/opt/python@3/bin/python3",
+  ];
+  candidates.push(...commonPaths);
+  for (const root of ["/opt/homebrew/opt", "/usr/local/opt"]) {
+    try {
+      for (const entry of fs.readdirSync(root)) {
+        if (!entry.startsWith("python@")) {
+          continue;
+        }
+        const bin = path.join(root, entry, "bin");
+        for (const name of fs.readdirSync(bin)) {
+          if (/^python3(\.\d+)?$/.test(name)) {
+            candidates.push(path.join(bin, name));
+          }
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  return [...new Set(candidates.filter(Boolean))];
+}
+
+function which(commandName) {
+  for (const directory of (process.env.PATH || "").split(path.delimiter)) {
+    if (!directory) {
+      continue;
+    }
+    const candidate = path.join(directory, commandName);
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return candidate;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+function writeWrapper(file, runtimeDir, moduleName, python) {
+  const content = `#!/usr/bin/env sh
+PYTHON_BIN="\${TEAM_AGENT_PYTHON:-${doubleQuoteValue(python)}}"
+PYTHONPATH="${doubleQuoteValue(path.join(runtimeDir, "src"))}" exec "$PYTHON_BIN" -m ${moduleName} "$@"
+`;
+  fs.writeFileSync(file, content, { mode: 0o755 });
+  fs.chmodSync(file, 0o755);
+}
+
+function copyTree(src, dest) {
+  const ignored = new Set([".git", ".team", "node_modules", "__pycache__", ".pytest_cache", ".venv"]);
+  const stat = fs.lstatSync(src);
+  if (stat.isDirectory()) {
+    const name = path.basename(src);
+    if (ignored.has(name) || src.endsWith(path.join("team-agent-core", "target"))) {
+      return;
+    }
+    fs.mkdirSync(dest, { recursive: true, mode: stat.mode });
+    for (const entry of fs.readdirSync(src)) {
+      if (entry === ".DS_Store") {
+        continue;
+      }
+      copyTree(path.join(src, entry), path.join(dest, entry));
+    }
+    return;
+  }
+  if (stat.isFile()) {
+    fs.copyFileSync(src, dest);
+    fs.chmodSync(dest, stat.mode);
+  }
+}
+
+function expandHome(value) {
+  if (value === "~") {
+    return os.homedir();
+  }
+  if (value.startsWith("~/")) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+  return value;
+}
+
+function doubleQuoteValue(value) {
+  return String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\$/g, "\\$").replace(/`/g, "\\`");
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@team-agent/installer",
+  "version": "0.1.0",
+  "description": "npx installer for Team Agent",
+  "bin": {
+    "team-agent-installer": "npm/install.mjs"
+  },
+  "files": [
+    "npm",
+    "scripts",
+    "src",
+    "skills",
+    "templates",
+    "examples",
+    "schemas",
+    "crates/team-agent-core/Cargo.toml",
+    "crates/team-agent-core/src",
+    "pyproject.toml",
+    "README.md",
+    "!**/__pycache__/**",
+    "!**/*.pyc",
+    "!**/target/**"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED"
+}

package/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "teamspec-agent-mode"
+version = "0.1.0"
+description = "Spec-first CLI-native team agent runtime for Claude Code, Codex CLI, and Gemini CLI workers."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.optional-dependencies]
+test = []
+
+[project.scripts]
+team-agent = "team_agent.cli:main"
+team_orchestrator = "team_agent.mcp_server:main"
+team-agent-coordinator = "team_agent.coordinator:main"
+
+[tool.team-agent]
+run = "PYTHONPATH=src python3 -m team_agent"

package/schemas/result-envelope.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://teamspec.local/schemas/result-envelope.schema.json",
+  "title": "TeamSpec result_envelope_v1",
+  "type": "object",
+  "required": ["schema_version", "task_id", "agent_id", "status", "summary", "changes", "tests", "risks", "artifacts", "next_actions"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "const": "result_envelope_v1" },
+    "task_id": { "type": "string", "minLength": 1 },
+    "agent_id": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["success", "blocked", "failed", "partial"] },
+    "summary": { "type": "string" },
+    "changes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "kind", "description"],
+        "additionalProperties": false,
+        "properties": {
+          "path": { "type": "string" },
+          "kind": { "enum": ["created", "modified", "deleted", "observed"] },
+          "description": { "type": "string" }
+        }
+      }
+    },
+    "tests": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["command", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "command": { "type": "string" },
+          "status": { "enum": ["passed", "failed", "not_run", "skipped"] },
+          "detail": { "type": "string" }
+        }
+      }
+    },
+    "risks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["severity", "description"],
+        "additionalProperties": false,
+        "properties": {
+          "severity": { "enum": ["low", "medium", "high"] },
+          "description": { "type": "string" }
+        }
+      }
+    },
+    "artifacts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "description"],
+        "additionalProperties": false,
+        "properties": {
+          "path": { "type": "string" },
+          "description": { "type": "string" }
+        }
+      }
+    },
+    "next_actions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["description"],
+        "additionalProperties": false,
+        "properties": {
+          "description": { "type": "string" }
+        }
+      }
+    }
+  }
+}