@nbardy/oompa 0.1.0 → 0.3.0

package/README.md

@@ -79,25 +79,51 @@ This repo has a fleshed out version of the idea. The oompa loompas are organized
 
 ### Configuration
 
-**oompa.json**:
+**oompa.json** — the only file you need:
 ```json
 {
   "review_model": "codex:codex-5.2",
   "workers": [
-    {"model": "claude:opus-4.5", "iterations": 5, "count": 1, "prompt": "config/prompts/planner.md"},
-    {"model": "codex:codex-5.2-mini", "iterations": 10, "count": 3, "prompt": "config/prompts/executor.md"}
+    {"model": "claude:opus-4.5", "prompt": ["config/prompts/planner.md"], "iterations": 5, "count": 1},
+    {"model": "codex:codex-5.2-mini", "prompt": ["config/prompts/executor.md"], "iterations": 10, "count": 3, "can_plan": false}
   ]
 }
 ```
 
 This spawns:
-- **1 planner** (opus) — creates tasks, doesn't write code
+- **1 planner** (opus) — reads spec, explores codebase, creates/refines tasks
 - **3 executors** (mini) — claims and executes tasks fast
 - **Reviews** done by codex-5.2 before any merge
 
+#### Worker fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `model` | yes | `harness:model` (e.g. `claude:opus-4.5`, `codex:codex-5.2-mini`) |
+| `prompt` | no | String or array of paths — concatenated into one prompt |
+| `iterations` | no | Max iterations per worker (default: 10) |
+| `count` | no | Number of workers with this config (default: 1) |
+| `can_plan` | no | If `false`, worker waits for tasks before starting (default: `true`) |
+
+#### Composable prompts
+
+`prompt` accepts a string or an array. Arrays get concatenated, so you can reuse a shared base across workers:
+
+```json
+{
+  "workers": [
+    {"model": "claude:opus-4.5", "prompt": ["prompts/base.md", "prompts/architect.md"], "count": 1},
+    {"model": "codex:codex-5.2-mini", "prompt": ["prompts/base.md", "prompts/frontend.md"], "count": 2},
+    {"model": "codex:codex-5.2-mini", "prompt": ["prompts/base.md", "prompts/backend.md"], "count": 2}
+  ]
+}
+```
+
+Every worker automatically gets task management instructions injected above your prompts. Your prompts just say *what* the worker should do — the framework handles *how* tasks work.
+
 ### Task System
 
-Workers self-organize via filesystem:
+Workers self-organize via the filesystem. Tasks live at the project root and are shared across all worktrees:
 
 ```
 tasks/
@@ -106,20 +132,31 @@ tasks/
 └── complete/*.edn    # done
 ```
 
-Workers can:
-- **Claim tasks**: `mv pending/task.edn current/`
-- **Complete tasks**: `mv current/task.edn complete/`
-- **Create tasks**: write new `.edn` to `pending/`
+From inside a worktree, workers reach tasks via `../tasks/`:
+- **See tasks**: `ls ../tasks/pending/`
+- **Claim**: `mv ../tasks/pending/task.edn ../tasks/current/`
+- **Complete**: `mv ../tasks/current/task.edn ../tasks/complete/`
+- **Create**: write new `.edn` to `../tasks/pending/`
+
+Task file format:
+```edn
+{:id "task-001"
+ :summary "Add user authentication"
+ :description "Implement JWT-based auth for the API"
+ :difficulty :medium
+ :files ["src/auth.py" "tests/test_auth.py"]
+ :acceptance ["Login endpoint returns token" "Tests pass"]}
+```
 
-### Prompts
+### Bundled Prompts
 
-Three built-in worker types:
+Three prompt files ship with oompa that you can use in your `prompt` arrays:
 
-| Prompt | Role | Creates Tasks? | Executes Tasks? |
-|--------|------|----------------|-----------------|
-| `worker.md` | Hybrid | ✓ | ✓ |
-| `planner.md` | Planner | ✓ | ✗ |
-| `executor.md` | Executor | ✗ | ✓ |
+| Prompt | Creates Tasks? | Executes Tasks? | Best For |
+|--------|----------------|-----------------|----------|
+| `config/prompts/worker.md` (default) | yes | yes | General purpose |
+| `config/prompts/planner.md` | yes | sometimes | Big models — task design |
+| `config/prompts/executor.md` | no | yes | Small/fast models — heads-down work |
 
 ---
 

package/agentnet/src/agentnet/cli.clj

@@ -300,10 +300,12 @@
       (println "{")
       (println "  \"review_model\": \"codex:codex-5.2\",")
       (println "  \"workers\": [")
-      (println "    {\"model\": \"codex:codex-5.2-mini\", \"iterations\": 10, \"count\": 3},")
-      (println "    {\"model\": \"codex:codex-5.2\", \"iterations\": 5, \"count\": 1, \"prompt\": \"prompts/planner.md\"}")
+      (println "    {\"model\": \"codex:codex-5.2-mini\", \"prompt\": \"prompts/executor.md\", \"iterations\": 10, \"count\": 3, \"can_plan\": false},")
+      (println "    {\"model\": \"claude:opus-4.5\", \"prompt\": [\"prompts/base.md\", \"prompts/planner.md\"], \"count\": 1}")
       (println "  ]")
       (println "}")
+      (println)
+      (println "prompt: string or array of paths — concatenated into one prompt.")
       (System/exit 1))
     (let [config (json/parse-string (slurp f) true)
           review-model (some-> (:review_model config) parse-model-string)
@@ -325,7 +327,8 @@
                            :harness harness
                            :model model
                            :iterations (or (:iterations wc) 10)
-                           :custom-prompt (:prompt wc)
+                           :prompts (:prompt wc)
+                           :can-plan (:can_plan wc)
                            :review-harness (:harness review-model)
                            :review-model (:model review-model)})))
                     expanded-workers)]

package/agentnet/src/agentnet/worker.clj

@@ -93,15 +93,31 @@
 ;; Worker State
 ;; =============================================================================
 
+(def ^:private package-root
+  "Root of the oompa package — set by bin/oompa.js, falls back to cwd."
+  (or (System/getenv "OOMPA_PACKAGE_ROOT") "."))
+
+(defn- load-prompt
+  "Load a prompt file. Tries path as-is first, then from package root."
+  [path]
+  (or (agent/load-custom-prompt path)
+      (agent/load-custom-prompt (str package-root "/" path))))
+
 (defn create-worker
-  "Create a worker config"
-  [{:keys [id swarm-id harness model iterations custom-prompt review-harness review-model]}]
+  "Create a worker config.
+   :prompts is a string or vector of strings — paths to prompt files.
+   :can-plan when false, worker waits for tasks before starting (backpressure)."
+  [{:keys [id swarm-id harness model iterations prompts can-plan review-harness review-model]}]
   {:id id
    :swarm-id swarm-id
    :harness (or harness :codex)
    :model model
    :iterations (or iterations 10)
-   :custom-prompt custom-prompt
+   :prompts (cond
+              (vector? prompts) prompts
+              (string? prompts) [prompts]
+              :else [])
+   :can-plan (if (some? can-plan) can-plan true)
    :review-harness review-harness
    :review-model review-model
    :completed 0
@@ -128,25 +144,36 @@
 
 (defn- run-agent!
   "Run agent with prompt, return {:output string, :done? bool, :exit int}"
-  [{:keys [id swarm-id harness model custom-prompt]} worktree-path context]
-  (let [;; Load prompt (check config/prompts/ as default)
-        prompt-content (or (agent/load-custom-prompt custom-prompt)
-                           (agent/load-custom-prompt "config/prompts/worker.md")
-                           "Goal: Match spec.md\nProcess: Create/claim tasks in tasks/{pending,current,complete}/*.edn\nMethod: Isolate changes to your worktree, commit and merge when complete")
-
-        ;; Inject worktree and context
-        full-prompt (str "Worktree: " worktree-path "\n"
-                         "Task Status: " (:task_status context) "\n\n"
-                         prompt-content)
+  [{:keys [id swarm-id harness model prompts]} worktree-path context]
+  (let [;; 1. Task header (always, from package)
+        task-header (or (load-prompt "config/prompts/_task_header.md") "")
+
+        ;; 2. Load and concatenate all user prompts (string or list)
+        user-prompts (if (seq prompts)
+                       (->> prompts
+                            (map load-prompt)
+                            (remove nil?)
+                            (str/join "\n\n"))
+                       (or (load-prompt "config/prompts/worker.md")
+                           "You are a worker. Claim tasks, execute them, complete them."))
+
+        ;; Assemble: task header + status + user prompts
+        full-prompt (str task-header "\n"
+                         "Task Status: " (:task_status context) "\n"
+                         "Pending: " (:pending_tasks context) "\n\n"
+                         user-prompts)
         session-id (str/lower-case (str (java.util.UUID/randomUUID)))
         swarm-id* (or swarm-id "unknown")
         tagged-prompt (str "[oompa:" swarm-id* ":" id "] " full-prompt)
         abs-worktree (.getAbsolutePath (io/file worktree-path))
 
-        ;; Build command
+        ;; Build command — both harnesses run with cwd=worktree, no sandbox
+        ;; so agents can `..` to reach project root for task management
         cmd (case harness
-              :codex (cond-> ["codex" "exec" "--full-auto" "--skip-git-repo-check"
-                              "-C" worktree-path "--sandbox" "workspace-write"]
+              :codex (cond-> ["codex" "exec"
+                              "--dangerously-bypass-approvals-and-sandbox"
+                              "--skip-git-repo-check"
+                              "-C" abs-worktree]
                        model (into ["--model" model])
                        true (conj "--" full-prompt))
               :claude (cond-> ["claude" "-p" "--dangerously-skip-permissions"
@@ -156,14 +183,13 @@
         _ (when (= harness :codex)
             (persist-message! id session-id abs-worktree "user" tagged-prompt))
 
-        ;; Run agent
+        ;; Run agent — both run with cwd=worktree
         result (try
                  (if (= harness :claude)
-                   ;; Claude reads from stdin
-                   (process/sh cmd {:in tagged-prompt :out :string :err :string})
-                   ;; Codex takes prompt as arg
-                   (process/sh cmd {:out :string :err :string}))
+                   (process/sh cmd {:dir abs-worktree :in tagged-prompt :out :string :err :string})
+                   (process/sh cmd {:dir abs-worktree :out :string :err :string}))
                  (catch Exception e
+                   (println (format "[%s] Agent exception: %s" id (.getMessage e)))
                    {:exit -1 :out "" :err (.getMessage e)}))]
 
     (when (= harness :codex)
@@ -194,20 +220,24 @@
                            "- NEEDS_CHANGES with bullet points of issues\n"
                            "- REJECTED if fundamentally wrong")
 
-        ;; Build command
+        abs-wt (.getAbsolutePath (io/file worktree-path))
+
+        ;; Build command — cwd=worktree, no sandbox
         cmd (case review-harness
-              :codex (cond-> ["codex" "exec" "--full-auto" "--skip-git-repo-check"
-                              "-C" worktree-path "--sandbox" "workspace-write"]
+              :codex (cond-> ["codex" "exec"
+                              "--dangerously-bypass-approvals-and-sandbox"
+                              "--skip-git-repo-check"
+                              "-C" abs-wt]
                        review-model (into ["--model" review-model])
                        true (conj "--" review-prompt))
               :claude (cond-> ["claude" "-p" "--dangerously-skip-permissions"]
                         review-model (into ["--model" review-model])))
 
-        ;; Run reviewer
+        ;; Run reviewer — cwd=worktree
         result (try
                  (if (= review-harness :claude)
-                   (process/sh cmd {:in review-prompt :out :string :err :string})
-                   (process/sh cmd {:out :string :err :string}))
+                   (process/sh cmd {:dir abs-wt :in review-prompt :out :string :err :string})
+                   (process/sh cmd {:dir abs-wt :out :string :err :string}))
                  (catch Exception e
                    {:exit -1 :out "" :err (.getMessage e)}))
 
@@ -229,9 +259,13 @@
                         feedback "\n\n"
                         "Please fix these issues in the worktree.")
 
+        abs-wt (.getAbsolutePath (io/file worktree-path))
+
         cmd (case harness
-              :codex (cond-> ["codex" "exec" "--full-auto" "--skip-git-repo-check"
-                              "-C" worktree-path "--sandbox" "workspace-write"]
+              :codex (cond-> ["codex" "exec"
+                              "--dangerously-bypass-approvals-and-sandbox"
+                              "--skip-git-repo-check"
+                              "-C" abs-wt]
                        model (into ["--model" model])
                        true (conj "--" fix-prompt))
               :claude (cond-> ["claude" "-p" "--dangerously-skip-permissions"]
@@ -239,8 +273,8 @@
 
         result (try
                  (if (= harness :claude)
-                   (process/sh cmd {:in fix-prompt :out :string :err :string})
-                   (process/sh cmd {:out :string :err :string}))
+                   (process/sh cmd {:dir abs-wt :in fix-prompt :out :string :err :string})
+                   (process/sh cmd {:dir abs-wt :out :string :err :string}))
                  (catch Exception e
                    {:exit -1 :out "" :err (.getMessage e)}))]
 
@@ -249,18 +283,18 @@
 
 (defn- merge-to-main!
   "Merge worktree changes to main branch"
-  [wt-path wt-id worker-id]
+  [wt-path wt-id worker-id project-root]
   (println (format "[%s] Merging changes to main" worker-id))
   (let [;; Commit in worktree if needed
         _ (process/sh ["git" "add" "-A"] {:dir wt-path})
         _ (process/sh ["git" "commit" "-m" (str "Work from " wt-id) "--allow-empty"]
                       {:dir wt-path})
-        ;; Checkout main and merge
+        ;; Checkout main and merge (in project root, not worktree)
         checkout-result (process/sh ["git" "checkout" "main"]
-                                    {:out :string :err :string})
+                                    {:dir project-root :out :string :err :string})
         merge-result (when (zero? (:exit checkout-result))
                        (process/sh ["git" "merge" wt-id "--no-edit"]
-                                   {:out :string :err :string}))]
+                                   {:dir project-root :out :string :err :string}))]
     (and (zero? (:exit checkout-result))
          (zero? (:exit merge-result)))))
 
@@ -310,15 +344,17 @@
    Returns {:status :done|:continue|:error, :task task-or-nil}"
   [worker iteration total-iterations]
   (let [worker-id (:id worker)
-        wt-id (format ".w%s-i%d" worker-id iteration)
+        project-root (System/getProperty "user.dir")
+        wt-dir (format ".w%s-i%d" worker-id iteration)
+        wt-branch (format "oompa/%s-i%d" worker-id iteration)
 
         ;; Create worktree
         _ (println (format "[%s] Starting iteration %d/%d" worker-id iteration total-iterations))
-        wt-path (str (System/getProperty "user.dir") "/" wt-id)]
+        wt-path (str project-root "/" wt-dir)]
 
     (try
-      ;; Setup worktree
-      (process/sh ["git" "worktree" "add" wt-id "-b" wt-id])
+      ;; Setup worktree (in project root) — dir starts with . but branch name must be valid
+      (process/sh ["git" "worktree" "add" wt-dir "-b" wt-branch] {:dir project-root})
 
       ;; Build context
       (let [context (build-context)
@@ -336,7 +372,7 @@
           ;; Agent errored
           (not (zero? exit))
           (do
-            (println (format "[%s] Agent error (exit %d)" worker-id exit))
+            (println (format "[%s] Agent error (exit %d): %s" worker-id exit (subs (or output "") 0 (min 200 (count (or output ""))))))
             {:status :error :exit exit})
 
           ;; Success - run review loop before merge
@@ -344,7 +380,7 @@
           (let [{:keys [approved?]} (review-loop! worker wt-path worker-id)]
             (if approved?
               (do
-                (merge-to-main! wt-path wt-id worker-id)
+                (merge-to-main! wt-path wt-branch worker-id project-root)
                 (println (format "[%s] Iteration %d/%d complete" worker-id iteration total-iterations))
                 {:status :continue})
               (do
@@ -352,13 +388,33 @@
                 {:status :continue})))))
 
       (finally
-        ;; Cleanup worktree
-        (process/sh ["git" "worktree" "remove" wt-id "--force"])))))
+        ;; Cleanup worktree (in project root)
+        (process/sh ["git" "worktree" "remove" wt-dir "--force"] {:dir project-root})))))
 
 ;; =============================================================================
 ;; Worker Loop
 ;; =============================================================================
 
+(def ^:private max-wait-for-tasks 60)
+(def ^:private wait-poll-interval 5)
+
+(defn- wait-for-tasks!
+  "Wait up to 60s for pending/current tasks to appear. Used for backpressure
+   on workers that can't create their own tasks (can_plan: false)."
+  [worker-id]
+  (loop [waited 0]
+    (cond
+      (pos? (tasks/pending-count)) true
+      (pos? (tasks/current-count)) true
+      (>= waited max-wait-for-tasks)
+      (do (println (format "[%s] No tasks after %ds, proceeding anyway" worker-id waited))
+          false)
+      :else
+      (do (when (zero? (mod waited 15))
+            (println (format "[%s] Waiting for tasks... (%ds)" worker-id waited)))
+          (Thread/sleep (* wait-poll-interval 1000))
+          (recur (+ waited wait-poll-interval))))))
+
 (defn run-worker!
   "Run worker loop until done or iterations exhausted.
 
@@ -372,6 +428,10 @@
                      (or (:model worker) "default")
                      iterations))
 
+    ;; Backpressure: workers that can't create tasks wait for tasks to exist
+    (when-not (:can-plan worker)
+      (wait-for-tasks! id))
+
     (loop [iter 1
            completed 0]
       (if (> iter iterations)

package/bin/oompa.js

@@ -18,7 +18,7 @@ if (!fs.existsSync(swarmScript) || !fs.existsSync(classpath)) {
 const result = spawnSync("bb", ["--classpath", classpath, swarmScript, ...argv], {
   stdio: "inherit",
   cwd: process.cwd(),
-  env: process.env
+  env: { ...process.env, OOMPA_PACKAGE_ROOT: packageRoot }
 });
 
 if (result.error) {

package/config/prompts/_task_header.md

@@ -0,0 +1,46 @@
+## Task Management (auto-injected by oompa)
+
+You are working in a git worktree. Your code changes go in `.` (current directory).
+Tasks live in the project root at `../tasks/`. You can reach them from your worktree.
+
+### See available tasks
+
+```bash
+ls ../tasks/pending/
+cat ../tasks/pending/*.edn
+```
+
+### Claim a task (mark as in-progress)
+
+```bash
+mv ../tasks/pending/<task-file>.edn ../tasks/current/<task-file>.edn
+```
+
+### Complete a task
+
+```bash
+mv ../tasks/current/<task-file>.edn ../tasks/complete/<task-file>.edn
+```
+
+### Create a new task
+
+```bash
+cat > ../tasks/pending/task-NNN.edn << 'EOF'
+{:id "task-NNN"
+ :summary "Short imperative description"
+ :description "What needs to happen and why"
+ :difficulty :easy  ;; :easy :medium :hard
+ :files ["src/relevant-file.py"]
+ :acceptance ["Specific condition that means done"]}
+EOF
+```
+
+### Rules
+
+- Before starting work: read the project spec and all tasks to understand scope.
+- First action: claim your task by moving it to `../tasks/current/`.
+- If the `mv` fails (another worker claimed it first), pick a different task.
+- One task per commit (or a small, tightly-related set with overlapping files).
+- If tasks are missing or underspecified: stop and write tasks before coding.
+- If work emerges during execution: create new tasks in `../tasks/pending/`.
+- When all tasks are complete and the spec is satisfied, output: __DONE__

package/config/prompts/executor.md

@@ -1,32 +1,7 @@
-Goal: Execute tasks from tasks/pending/
-Process: Claim task (mv pending/ → current/), execute, complete (mv current/ → complete/)
-Method: Isolate changes to your worktree, commit and merge when complete
+You are an executor. You claim tasks and complete them. Nothing else.
 
-## Your Role
-
-You are an executor. You:
-- Claim and execute tasks
-- Do NOT create new tasks
-- Do NOT plan or design
-- Just execute what's assigned
-
-## Workflow
-
-1. Pick a task from tasks/pending/
-2. Move it to tasks/current/
-3. Execute the task in your worktree
-4. Commit your changes
-5. Move task to tasks/complete/
-6. Merge your worktree to main
-
-## Guidelines
-
-- Focus on one task at a time
-- Follow the task description exactly
-- If a task is unclear, skip it (leave in pending/)
-- Keep changes minimal and focused
-
-## Exit Condition
-
-When tasks/pending/ is empty:
-Output: __DONE__
+- Pick a task from pending, claim it, execute it, complete it.
+- Follow the task description and acceptance criteria exactly.
+- Do not create new tasks. Do not redesign. Do not refactor beyond the task scope.
+- If a task is unclear, skip it (leave in pending/) and pick another.
+- Keep changes minimal.

package/config/prompts/planner.md

@@ -1,35 +1,11 @@
-Goal: Break spec.md into executable tasks
-Process: Create tasks in tasks/pending/*.edn
-Method: Do NOT write code. Only create and refine tasks.
-
-## Your Role
-
-You are a planner. You:
-- Read spec.md to understand the goal
-- Create small, focused tasks in tasks/pending/
-- Monitor progress by checking tasks/complete/
-- Refine or split tasks that are too large
-- Do NOT execute tasks yourself
-
-## Task Creation
-
-Write .edn files to tasks/pending/:
-```edn
-{:id "task-001"
- :summary "Add user authentication"
- :description "Implement JWT-based auth for the API"
- :files ["src/auth.py" "tests/test_auth.py"]
- :acceptance ["Login endpoint returns token" "Tests pass"]}
-```
-
-## Guidelines
-
-- Keep tasks small (1-2 files max)
-- Be specific about acceptance criteria
-- Consider dependencies between tasks
-- Check what's already complete before creating duplicates
-
-## Exit Condition
-
-When spec.md is fully covered by tasks and all are complete:
-Output: __DONE__
+You are a planner. You read the spec, explore the codebase, and create well-scoped tasks.
+
+- Read spec.md and understand the full goal before creating any tasks.
+- Explore the existing code to understand what exists and what's missing.
+- Create small, focused tasks with clear acceptance criteria.
+- Set :difficulty on each task (:easy, :medium, :hard) so the right worker picks it up.
+- Refine or split tasks that are too large or vague.
+- Check ../tasks/complete/ before creating duplicates.
+- Do NOT claim or complete tasks. Your job is to create them for other workers.
+- Do NOT write application code. Only write task .edn files.
+- Spend time thinking. Good task decomposition is the highest-leverage thing you can do.

package/config/prompts/worker.md

@@ -1,31 +1,6 @@
-Goal: Match spec.md
-Process: Create/claim tasks in tasks/{pending,current,complete}/*.edn
-Method: Isolate changes to your worktree, commit and merge when complete
+You are a worker. You claim tasks, execute them, and complete them.
 
-## Task Management
-
-Check tasks/pending/ for available work:
-- To claim: move file from pending/ to current/
-- To complete: move file from current/ to complete/
-- To create: write new .edn file to pending/
-
-Task file format:
-```edn
-{:id "task-001"
- :summary "Short description"
- :description "Detailed description"
- :files ["src/foo.py"]}
-```
-
-## Workflow
-
-1. Check if tasks/pending/ has tasks
-2. If yes: claim one (mv to current/), execute it, complete it (mv to complete/)
-3. If no: check spec.md for gaps, create new tasks if needed
-4. Commit changes to your worktree
-5. Merge your worktree branch to main
-
-## Exit Condition
-
-When spec.md is fully satisfied and no more tasks are needed:
-Output: __DONE__
+- Pick tasks that match your strengths.
+- If no tasks exist, read the spec and create them.
+- Keep changes focused. Commit when a task is done.
+- If a task is too big, split it into smaller tasks and work on one.

package/oompa.example.json

@@ -4,15 +4,16 @@
   "workers": [
     {
       "model": "claude:opus-4.5",
+      "prompt": ["config/prompts/planner.md"],
       "iterations": 5,
-      "count": 1,
-      "prompt": "config/prompts/planner.md"
+      "count": 1
     },
     {
       "model": "codex:codex-5.2-mini",
+      "prompt": ["config/prompts/executor.md"],
       "iterations": 10,
       "count": 3,
-      "prompt": "config/prompts/executor.md"
+      "can_plan": false
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nbardy/oompa",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Git-worktree multi-agent swarm orchestrator for Codex and Claude",
   "license": "MIT",
   "type": "commonjs",