feat: agent-orchestrator v0.1.0 — generic multi-agent harness

Extracted and generalized from a project-specific agent launch engine. No project
specifics remain in code: paths, the loop kickoff preamble, handoff conventions, and the
on-complete hook are all config/template driven; session_prefix + log_dir are required.

- agents.py: driver + watchdog (data-driven backends via prompt_delivery arg|ping|exec;
  required session_prefix/log_dir; project-rooted path resolution; configurable kickoff
  template, handoff patterns, on_complete task; tmux-safe; selftest + init verbs)
- agent-log.py: config-driven claude transcript renderer
- agents.example.toml: self-contained 2-agent example (dependency-free demo backend)
- prompts/: generic builder/adversary/kickoff templates
- smoke.sh: isolated up+down sandbox proof that cleans up after itself
- flake.nix/.lock: devShell (python311 + tmux + git)
- README.md: schema + verbs + AI-PO usage + nix

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

flake.nix

@@ -0,0 +1,39 @@
+{
+  description = "agent-orchestrator — a generic multi-agent orchestration harness (tmux + watchdog)";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/50ab793786d9de88ee30ec4e4c24fb4236fc2674";
+  };
+
+  outputs = { self, nixpkgs }:
+    let
+      systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
+      forAllSystems = f: nixpkgs.lib.genAttrs systems (system: f nixpkgs.legacyPackages.${system});
+    in
+    {
+      # Reproducible devShell with the harness runtime deps. The driver itself is pure Python
+      # stdlib (it needs tomllib, so python >= 3.11); the rest is what the agents/watchdog shell
+      # out to. Make the agent CLIs (claude / opencode) available on PATH separately — they are
+      # external, non-Nix tools; install them per their own docs, then `nix develop` here.
+      devShells = forAllSystems (pkgs: {
+        default = pkgs.mkShell {
+          packages = [
+            pkgs.python311   # stdlib tomllib (>=3.11) — the driver imports it
+            pkgs.tmux        # every agent/session/watchdog runs in tmux
+            pkgs.git         # handoff signalling watches origin/main
+            pkgs.coreutils
+            pkgs.bash
+          ];
+          shellHook = ''
+            echo "agent-orchestrator devShell — $(python3 --version), $(tmux -V), $(git --version)"
+            echo "try: python3 agents.py selftest  |  ./smoke.sh  |  python3 agents.py status --config agents.example.toml"
+          '';
+        };
+      });
+
+      # `nix flake check` evaluates this — a cheap smoke that the devShell builds.
+      checks = forAllSystems (pkgs: {
+        devshell-builds = self.devShells.${pkgs.system}.default;
+      });
+    };
+}