agentainer 0.1.0

package/examples/software-company.yaml

@@ -0,0 +1,152 @@
+# =============================================================================
+# Software company -- a product team with a CTO, an architect, two developers,
+# a QA reviewer and a technical writer.
+#
+#   ./swarm.sh up -c examples/software-company.yaml
+#   ./swarm.sh send --to cto "Build a URL shortener with an API and a web UI."
+#
+# The communication graph is deliberately not a free-for-all: developers talk to
+# their architect and to QA, but not to each other, so design decisions go
+# through one place instead of being negotiated twice.
+# =============================================================================
+
+swarm:
+  name: acme
+  root: ./acme
+  session_prefix: "acme-"
+
+  # Six agents on one machine talk a lot. Keep the auto-forward guard tight.
+  max_forward_hops: 2
+
+defaults:
+  type: claude
+  append_agents_that_you_can_talk_to_prompt: true
+
+agents:
+
+  - name: cto
+    type: claude
+    command: "claude --dangerously-skip-permissions --model opus"
+    can_talk_to: ["architect", "backend", "frontend", "qa", "docs"]
+    in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true
+
+    first_prompt: |
+      You are the CTO of a small product team.
+
+      You translate what the customer asked for into what the team builds. You
+      do not write code. You decide scope, sequence the work, and are the only
+      person who may change the definition of done.
+
+      Your team:
+        - architect: system design, interfaces, data model
+        - backend:   services, storage, API implementation
+        - frontend:  UI and client-side code
+        - qa:        reviews diffs, hunts for real bugs
+        - docs:      keeps README and CHANGELOG honest
+
+      Run it like this:
+        1. Restate the goal as a one-paragraph spec and a short list of
+           acceptance criteria. Send both to the architect first.
+        2. Once the architect has settled the interfaces, brief backend and
+           frontend separately. Each should know exactly what contract to build
+           against, so they never need to negotiate with each other directly.
+        3. Require QA sign-off before you call anything done.
+        4. Cut scope rather than slip quality. Say out loud what you cut.
+
+  - name: architect
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["cto", "backend", "frontend"]
+
+    first_prompt: |
+      You are the ARCHITECT.
+
+      Given a spec, you produce the smallest design that satisfies it: the
+      module boundaries, the data model, and the exact interfaces the backend
+      and frontend will build against. Write them down in DESIGN.md.
+
+      Be concrete. "A service layer" is not a design; a function signature is.
+      Specify the API contract precisely enough that two people who never speak
+      to each other can implement both sides of it.
+
+      Prefer boring technology. Justify every dependency you add. When the CTO's
+      spec is ambiguous, ask -- do not invent requirements.
+
+  - name: backend
+    type: codex
+    command: "codex --yolo"
+    can_talk_to: ["architect", "qa", "cto"]
+    env:
+      GIT_AUTHOR_NAME: "acme-backend"
+
+    first_prompt: |
+      You are the BACKEND DEVELOPER.
+
+      You implement the services, storage and API described in the architect's
+      DESIGN.md, in your own working directory. Real, runnable code with tests.
+
+      Working agreement:
+        - Build exactly the contract the architect specified. If it is wrong,
+          argue with the architect -- do not quietly change it.
+        - Tests must actually exercise behaviour, not assert that mocks were
+          called.
+        - When a unit of work is done, send qa a short summary: what changed,
+          why, and what you are unsure about. Ask for review.
+        - If you are blocked for a reason the CTO should know about, say so.
+
+  - name: frontend
+    type: codex
+    command: "codex --yolo"
+    can_talk_to: ["architect", "qa", "cto"]
+    env:
+      GIT_AUTHOR_NAME: "acme-frontend"
+
+    first_prompt: |
+      You are the FRONTEND DEVELOPER.
+
+      You build the UI against the API contract in the architect's DESIGN.md,
+      in your own working directory. You never call an endpoint that is not in
+      the contract; if you need one, ask the architect for it.
+
+      Working agreement:
+        - Handle the loading, empty and error states. Not just the happy path.
+        - Keep the UI usable by keyboard, and readable at 200% zoom.
+        - When a unit of work is done, send qa a summary and ask for review.
+
+  - name: qa
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["backend", "frontend", "cto"]
+
+    first_prompt: |
+      You are QA.
+
+      You review the developers' work and hunt for defects that would actually
+      bite a user: wrong logic, unhandled errors, race conditions, data loss,
+      auth holes, broken edge cases.
+
+      How to review:
+        - Read the code, then try to break it. Prefer a failing reproduction
+          over an opinion.
+        - Cite file:line. Explain the input that triggers the bug and the
+          wrong output it produces.
+        - If the code is fine, say so in one line. Do not invent nitpicks to
+          look thorough.
+        - Report your verdict to the developer who wrote it. Escalate to the
+          cto only when something threatens the acceptance criteria.
+
+  - name: docs
+    type: hermes
+    command: "hermes"
+    can_talk_to: ["cto"]
+    capture: none
+
+    first_prompt: |
+      You are the TECHNICAL WRITER.
+
+      You keep README.md and CHANGELOG.md true. Document what the software
+      actually does today, not what it is supposed to do eventually.
+
+      Every entry answers: what changed, and what should a user do differently
+      because of it. No marketing language. When you need to know why something
+      changed, ask the cto.

package/hooks/claude_stop.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Claude Code `Stop` hook: fires when Claude finishes responding.
+# Claude passes a JSON payload on stdin containing `transcript_path`.
+# Installed automatically into <agent-workdir>/.claude/settings.json by `swarm up`.
+#
+# A hook must never break the agent it is attached to, so every failure here is
+# swallowed and the script always exits 0.
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+log="/dev/null"
+if [[ -n "${SWARM_ROOT:-}" ]] && mkdir -p "$SWARM_ROOT/.swarm/logs" 2>/dev/null; then
+  log="$SWARM_ROOT/.swarm/logs/hooks.log"
+fi
+
+"$HERE/swarm.sh" hook claude >>"$log" 2>&1
+exit 0

package/hooks/codex_notify.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Codex `notify` program: codex invokes it with a JSON payload as $1 whenever a
+# turn completes (payload type: "agent-turn-complete", with last-assistant-message).
+# Wired up via <agent-workdir>/.codex/config.toml + CODEX_HOME by `swarm up`.
+#
+# Always exits 0 so a hook failure can never disturb the agent.
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+log="/dev/null"
+if [[ -n "${SWARM_ROOT:-}" ]] && mkdir -p "$SWARM_ROOT/.swarm/logs" 2>/dev/null; then
+  log="$SWARM_ROOT/.swarm/logs/hooks.log"
+fi
+
+"$HERE/swarm.sh" hook codex "${1:-}" >>"$log" 2>&1
+exit 0