@voybio/ace-swarm 0.1.0

package/assets/scripts/render-mcp-configs.sh

@@ -0,0 +1,396 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+WORKSPACE_ROOT="$(cd -- "${SCRIPT_DIR}/../.." && pwd)"
+
+ACE_ROOT=".agents/ACE"
+MCP_CONFIG_DIR="${ACE_ROOT}/.mcp-config"
+GITHUB_DIR="${ACE_ROOT}/.github"
+CLAUDE_DIR="${ACE_ROOT}/.claude"
+CURSOR_DIR="${ACE_ROOT}/.cursor"
+VSCODE_DIR="${ACE_ROOT}/.vscode"
+HOOK_COMMAND="node ./.agents/ACE/scripts/ace/ace-hook-dispatch.mjs"
+HOOK_COMMAND_WINDOWS="node .\\\\.agents\\\\ACE\\\\scripts\\\\ace\\\\ace-hook-dispatch.mjs"
+
+mkdir -p "${MCP_CONFIG_DIR}"
+mkdir -p "${GITHUB_DIR}/hooks"
+mkdir -p "${CLAUDE_DIR}"
+mkdir -p "${CURSOR_DIR}"
+mkdir -p "${VSCODE_DIR}"
+
+cat > "${MCP_CONFIG_DIR}/vscode.mcp.json" <<JSON
+{
+  "servers": {
+    "ace-swarm": {
+      "type": "stdio",
+      "command": "/bin/zsh",
+      "args": ["-lc", "cd \"${WORKSPACE_ROOT}\" && ACE_WORKSPACE_ROOT=\"${WORKSPACE_ROOT}\" npx -y ace-swarm mcp"]
+    }
+  }
+}
+JSON
+
+cat > "${MCP_CONFIG_DIR}/cursor.mcp.json" <<JSON
+{
+  "mcpServers": {
+    "ace-swarm": {
+      "command": "/bin/zsh",
+      "args": ["-lc", "cd \"${WORKSPACE_ROOT}\" && ACE_WORKSPACE_ROOT=\"${WORKSPACE_ROOT}\" npx -y ace-swarm mcp"]
+    }
+  }
+}
+JSON
+
+cat > "${MCP_CONFIG_DIR}/claude_desktop_config.json" <<JSON
+{
+  "mcpServers": {
+    "ace-swarm": {
+      "command": "/bin/zsh",
+      "args": ["-lc", "cd \"${WORKSPACE_ROOT}\" && ACE_WORKSPACE_ROOT=\"${WORKSPACE_ROOT}\" npx -y ace-swarm mcp"]
+    }
+  }
+}
+JSON
+
+cat > "${MCP_CONFIG_DIR}/antigravity.mcp.json" <<JSON
+{
+  "mcpServers": {
+    "ace-swarm": {
+      "command": "/bin/zsh",
+      "args": ["-lc", "cd \"${WORKSPACE_ROOT}\" && ACE_WORKSPACE_ROOT=\"${WORKSPACE_ROOT}\" npx -y ace-swarm mcp"]
+    }
+  }
+}
+JSON
+
+cat > "${MCP_CONFIG_DIR}/codex.config.toml" <<TOML
+# ACE instructions are scaffolded into .agents/ACE/AGENTS.md during bootstrap.
+[mcp_servers.ace-swarm]
+command = "/bin/zsh"
+args = ["-lc", "cd \"${WORKSPACE_ROOT}\" && ACE_WORKSPACE_ROOT=\"${WORKSPACE_ROOT}\" npx -y ace-swarm mcp"]
+TOML
+
+cat > "${ACE_ROOT}/CLAUDE.md" <<MD
+# ACE Instructions For Claude Code
+
+This workspace is ACE-governed. Ground truth lives in `.agents/ACE/agent-state/TASK.md`,
+`.agents/ACE/agent-state/STATUS.md`, `.agents/ACE/agent-state/SCOPE.md`, and `.agents/ACE/agent-state/EVIDENCE_LOG.md`.
+
+Before significant work, call `recall_context`. Use `route_task` and
+`get_agent_instructions` for role guidance. After meaningful edits or state
+changes, call `execute_gates` and persist evidence/handoffs in ACE artifacts.
+MD
+
+cat > "${GITHUB_DIR}/copilot-instructions.md" <<MD
+# ACE Instructions For GitHub Copilot
+
+This workspace is ACE-governed. Read file-backed ACE state before acting:
+`.agents/ACE/agent-state/TASK.md`, `.agents/ACE/agent-state/STATUS.md`, `.agents/ACE/agent-state/SCOPE.md`, and
+`.agents/ACE/agent-state/EVIDENCE_LOG.md`.
+
+Before significant work, call `recall_context`. Route with `route_task`.
+After material changes, call `execute_gates` and update durable ACE artifacts.
+MD
+
+cat > "${ACE_ROOT}/.cursorrules" <<MD
+# ACE Instructions For Cursor
+
+This workspace is ACE-governed. Do not rely on chat history for state. Use
+`recall_context` to load task, scope, and status from `.agents/ACE/agent-state/*`.
+
+Use `route_task` and `get_agent_instructions` for role guidance. After edits,
+run `execute_gates` and persist evidence/handoffs in ACE artifacts.
+MD
+
+cat > "${ACE_ROOT}/AGENTS.md" <<MD
+# ACE Instructions For Codex
+
+This workspace is ACE-governed. File-backed ACE state is authoritative:
+`.agents/ACE/agent-state/TASK.md`, `.agents/ACE/agent-state/STATUS.md`, `.agents/ACE/agent-state/SCOPE.md`, and
+`.agents/ACE/agent-state/EVIDENCE_LOG.md`.
+
+Before significant work, call `recall_context`. Use `route_task` and
+`get_agent_instructions` for role guidance. After meaningful edits or state
+changes, call `execute_gates` and persist evidence or handoffs.
+MD
+
+cat > "${GITHUB_DIR}/hooks/ace-copilot.json" <<JSON
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "${HOOK_COMMAND}",
+        "windows": "${HOOK_COMMAND_WINDOWS}",
+        "timeout": 10
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "type": "command",
+        "command": "${HOOK_COMMAND}",
+        "windows": "${HOOK_COMMAND_WINDOWS}",
+        "timeout": 10
+      }
+    ],
+    "PreToolUse": [
+      {
+        "type": "command",
+        "command": "${HOOK_COMMAND}",
+        "windows": "${HOOK_COMMAND_WINDOWS}",
+        "timeout": 10
+      }
+    ],
+    "PostToolUse": [
+      {
+        "type": "command",
+        "command": "${HOOK_COMMAND}",
+        "windows": "${HOOK_COMMAND_WINDOWS}",
+        "timeout": 10
+      }
+    ],
+    "PreCompact": [
+      {
+        "type": "command",
+        "command": "${HOOK_COMMAND}",
+        "windows": "${HOOK_COMMAND_WINDOWS}",
+        "timeout": 10
+      }
+    ],
+    "SubagentStart": [
+      {
+        "type": "command",
+        "command": "${HOOK_COMMAND}",
+        "windows": "${HOOK_COMMAND_WINDOWS}",
+        "timeout": 10
+      }
+    ],
+    "SubagentStop": [
+      {
+        "type": "command",
+        "command": "${HOOK_COMMAND}",
+        "windows": "${HOOK_COMMAND_WINDOWS}",
+        "timeout": 10
+      }
+    ],
+    "Stop": [
+      {
+        "type": "command",
+        "command": "${HOOK_COMMAND}",
+        "windows": "${HOOK_COMMAND_WINDOWS}",
+        "timeout": 10
+      }
+    ]
+  }
+}
+JSON
+
+cat > "${CLAUDE_DIR}/settings.json" <<JSON
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${HOOK_COMMAND}"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${HOOK_COMMAND}"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${HOOK_COMMAND}"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${HOOK_COMMAND}"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${HOOK_COMMAND}"
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${HOOK_COMMAND}"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${HOOK_COMMAND}"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${HOOK_COMMAND}"
+          }
+        ]
+      }
+    ]
+  }
+}
+JSON
+
+cat > "${VSCODE_DIR}/ace-hooks.json" <<JSON
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "${HOOK_COMMAND}",
+        "windows": "${HOOK_COMMAND_WINDOWS}",
+        "timeout": 10
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "type": "command",
+        "command": "${HOOK_COMMAND}",
+        "windows": "${HOOK_COMMAND_WINDOWS}",
+        "timeout": 10
+      }
+    ],
+    "PreToolUse": [
+      {
+        "type": "command",
+        "command": "${HOOK_COMMAND}",
+        "windows": "${HOOK_COMMAND_WINDOWS}",
+        "timeout": 10
+      }
+    ],
+    "PostToolUse": [
+      {
+        "type": "command",
+        "command": "${HOOK_COMMAND}",
+        "windows": "${HOOK_COMMAND_WINDOWS}",
+        "timeout": 10
+      }
+    ],
+    "PreCompact": [
+      {
+        "type": "command",
+        "command": "${HOOK_COMMAND}",
+        "windows": "${HOOK_COMMAND_WINDOWS}",
+        "timeout": 10
+      }
+    ],
+    "SubagentStart": [
+      {
+        "type": "command",
+        "command": "${HOOK_COMMAND}",
+        "windows": "${HOOK_COMMAND_WINDOWS}",
+        "timeout": 10
+      }
+    ],
+    "SubagentStop": [
+      {
+        "type": "command",
+        "command": "${HOOK_COMMAND}",
+        "windows": "${HOOK_COMMAND_WINDOWS}",
+        "timeout": 10
+      }
+    ],
+    "Stop": [
+      {
+        "type": "command",
+        "command": "${HOOK_COMMAND}",
+        "windows": "${HOOK_COMMAND_WINDOWS}",
+        "timeout": 10
+      }
+    ]
+  }
+}
+JSON
+
+cp "${VSCODE_DIR}/ace-hooks.json" "${CURSOR_DIR}/hooks.json"
+cp "${VSCODE_DIR}/ace-hooks.json" "${MCP_CONFIG_DIR}/gemini.hooks.json"
+cp "${VSCODE_DIR}/ace-hooks.json" "${MCP_CONFIG_DIR}/antigravity.hooks.json"
+
+cat > "${MCP_CONFIG_DIR}/codex.hooks.toml" <<TOML
+# ACE lifecycle hook scaffold for Codex-compatible runtimes.
+# Merge these entries into the host hook config that supports SessionStart/SubagentStart hooks.
+
+[[hooks]]
+event = "SessionStart"
+command = "${HOOK_COMMAND}"
+
+[[hooks]]
+event = "UserPromptSubmit"
+command = "${HOOK_COMMAND}"
+
+[[hooks]]
+event = "PreToolUse"
+command = "${HOOK_COMMAND}"
+
+[[hooks]]
+event = "PostToolUse"
+command = "${HOOK_COMMAND}"
+
+[[hooks]]
+event = "PreCompact"
+command = "${HOOK_COMMAND}"
+
+[[hooks]]
+event = "SubagentStart"
+command = "${HOOK_COMMAND}"
+
+[[hooks]]
+event = "SubagentStop"
+command = "${HOOK_COMMAND}"
+
+[[hooks]]
+event = "Stop"
+command = "${HOOK_COMMAND}"
+TOML
+
+echo "Wrote ACE MCP configs, host instruction files, and hook configs under ${ACE_ROOT}"

package/assets/tasks/README.md

@@ -0,0 +1,48 @@
+# ACE Tasks Control Plane
+
+This directory contains shared execution artifacts consumed by ACE prompts, tools, and resources.
+
+## Files
+
+- `todo.md`: active execution board and verification checklist.
+- `lessons.md`: durable guardrails captured after failures/corrections.
+- `role_tasks.md`: bounded task packs for each ACE role.
+- `cli_work_split.md`: Codex CLI vs Gemini CLI routing contract.
+- `SWARM_HANDOFF.template.json`: canonical inter-agent handoff schema.
+- `SWARM_HANDOFF.example*.json`: concrete routing examples.
+- `agent-state/job-queue.json`: scheduler job queue for deferred/gated dispatch.
+- `agent-state/job-locks.json`: collision-free scheduler locks.
+- `agent-state/scheduler-lease.json`: active scheduler lease ownership.
+
+## When To Read This Directory
+
+- Before starting non-trivial work that needs explicit task, role, or handoff structure.
+- Before issuing or consuming a `SWARM_HANDOFF`.
+- When recovering blocked or deferred work through the scheduler and TODO surfaces.
+- When a repeated failure should become a durable lesson or guardrail.
+
+## Common Workflows
+
+1. Start work: check `todo.md`, then use `role_tasks.md` to confirm the bounded contract for the active role.
+2. Route work: begin from `SWARM_HANDOFF.template.json`, then compare with the example payloads before publishing.
+3. Recover work: inspect `agent-state/job-queue.json`, `agent-state/job-locks.json`, and `agent-state/scheduler-lease.json` together instead of in isolation.
+4. Harden work: write repeatable failures to `lessons.md` so the same mistake does not re-enter the loop.
+
+## Operating Rules
+
+1. Update `todo.md` before non-trivial work and after verification.
+2. Log every repeatable correction pattern in `lessons.md`.
+3. Use `SWARM_HANDOFF.template.json` as the base for all routing payloads.
+4. Keep acceptance criteria measurable and tied to file-based evidence.
+
+## Validation Rules
+
+- Handoffs must reference real artifacts, owners, and acceptance criteria.
+- Scheduler state is advisory unless it matches current task and status artifacts.
+- Lessons should capture a failure pattern, a guardrail, and a verification check, not just an anecdote.
+
+## Common Failure Modes
+
+- `todo.md` is stale while work has already moved; refresh it before trusting downstream routing.
+- A handoff exists without evidence or acceptance criteria; treat it as incomplete, not merely “draft.”
+- Scheduler files disagree with task or status truth; route the contradiction through ops instead of guessing which surface won.

package/assets/tasks/SWARM_HANDOFF.example.json

@@ -0,0 +1,53 @@
+{
+  "handoff_id": "HND-20260302-014",
+  "timestamp_utc": "2026-03-02T20:15:00.000Z",
+  "router": {
+    "from": "ACE-Orchestrator",
+    "via": "ACE-Orchestrator",
+    "to": "ACE-VOS"
+  },
+  "task": {
+    "title": "Stress test venture thesis for pricing model",
+    "type": "venture",
+    "priority": "P1",
+    "owner": "ACE-VOS",
+    "depends_on": [],
+    "scope": "Validate pricing and monetization thesis against ICP"
+  },
+  "context": {
+    "business_requirement": "venture-state/THESIS.md#pricing",
+    "design_constraint": "brand-state/BRAND_VOICE.md#positioning",
+    "engineering_constraint": "engineering-state/ARCHITECTURE.md#current-billing-surface",
+    "directive": "Produce a revised pricing thesis with pass/fail assumptions and a go/no-go recommendation."
+  },
+  "acceptance_criteria": [
+    "Includes explicit ICP, willingness-to-pay assumption, and monetization mechanism",
+    "Defines testable kill criteria for invalidation"
+  ],
+  "deliverables": [
+    "venture-state/THESIS.md",
+    "venture-state/RISKS.md"
+  ],
+  "verification": {
+    "required_evidence": [
+      "artifact_pointers",
+      "verification_evidence"
+    ],
+    "review_check": "Would a staff engineer approve this?",
+    "status": "pending"
+  },
+  "risks": [],
+  "open_questions": [],
+  "lessons_hook": {
+    "on_correction_update": "tasks/lessons.md",
+    "rule_format": "Never <bad pattern>; always <guardrail>."
+  },
+  "return_payload_contract": {
+    "must_include": [
+      "updated_artifact_pointers",
+      "verification_evidence",
+      "residual_risks",
+      "explicit_blockers_or_done_state"
+    ]
+  }
+}

package/assets/tasks/SWARM_HANDOFF.example_ui_to_coders.json

@@ -0,0 +1,55 @@
+{
+  "handoff_id": "HND-20260302-033",
+  "timestamp_utc": "2026-03-02T20:50:00.000Z",
+  "router": {
+    "from": "ACE-UI",
+    "via": "ACE-Orchestrator",
+    "to": "ACE-Coders"
+  },
+  "task": {
+    "title": "Implement updated onboarding copy and flow",
+    "type": "engineering",
+    "priority": "P0",
+    "owner": "ACE-CODERS",
+    "depends_on": [
+      "brand-state/COPY_DECK.md#onboarding"
+    ],
+    "scope": "Apply approved UX copy and flow updates with tests"
+  },
+  "context": {
+    "business_requirement": "venture-state/MVP_SPEC.md#activation",
+    "design_constraint": "brand-state/COPY_DECK.md#onboarding",
+    "engineering_constraint": "engineering-state/src/onboarding/",
+    "directive": "Implement string/key updates and flow behavior, then provide test evidence."
+  },
+  "acceptance_criteria": [
+    "All onboarding copy keys updated to approved values",
+    "Behavioral tests pass for new flow and edge cases"
+  ],
+  "deliverables": [
+    "engineering-state/src/onboarding/",
+    "engineering-state/TEST_LOG.md"
+  ],
+  "verification": {
+    "required_evidence": [
+      "artifact_pointers",
+      "verification_evidence"
+    ],
+    "review_check": "Would a staff engineer approve this?",
+    "status": "pending"
+  },
+  "risks": [],
+  "open_questions": [],
+  "lessons_hook": {
+    "on_correction_update": "tasks/lessons.md",
+    "rule_format": "Never <bad pattern>; always <guardrail>."
+  },
+  "return_payload_contract": {
+    "must_include": [
+      "updated_artifact_pointers",
+      "verification_evidence",
+      "residual_risks",
+      "explicit_blockers_or_done_state"
+    ]
+  }
+}

package/assets/tasks/SWARM_HANDOFF.example_vos_to_ui.json

@@ -0,0 +1,55 @@
+{
+  "handoff_id": "HND-20260302-021",
+  "timestamp_utc": "2026-03-02T20:35:00.000Z",
+  "router": {
+    "from": "ACE-VOS",
+    "via": "ACE-Orchestrator",
+    "to": "ACE-UI"
+  },
+  "task": {
+    "title": "Translate thesis into onboarding UX narrative",
+    "type": "ux",
+    "priority": "P1",
+    "owner": "ACE-UI",
+    "depends_on": [
+      "venture-state/THESIS.md#core-loop"
+    ],
+    "scope": "Rewrite first-run onboarding and trust messaging"
+  },
+  "context": {
+    "business_requirement": "venture-state/THESIS.md#core-loop",
+    "design_constraint": "brand-state/BRAND_VOICE.md#tone",
+    "engineering_constraint": "engineering-state/src/onboarding/",
+    "directive": "Produce a copy deck and string map that reduces first-session drop-off."
+  },
+  "acceptance_criteria": [
+    "Copy deck includes before/after rationale for each screen",
+    "String map is component-keyed and developer-ready"
+  ],
+  "deliverables": [
+    "brand-state/COPY_DECK.md",
+    "brand-state/ASSETS/strings.json"
+  ],
+  "verification": {
+    "required_evidence": [
+      "artifact_pointers",
+      "verification_evidence"
+    ],
+    "review_check": "Would a staff engineer approve this?",
+    "status": "pending"
+  },
+  "risks": [],
+  "open_questions": [],
+  "lessons_hook": {
+    "on_correction_update": "tasks/lessons.md",
+    "rule_format": "Never <bad pattern>; always <guardrail>."
+  },
+  "return_payload_contract": {
+    "must_include": [
+      "updated_artifact_pointers",
+      "verification_evidence",
+      "residual_risks",
+      "explicit_blockers_or_done_state"
+    ]
+  }
+}

package/assets/tasks/SWARM_HANDOFF.template.json

@@ -0,0 +1,52 @@
+{
+  "handoff_id": "HND-YYYYMMDD-001",
+  "timestamp_utc": "2026-01-01T00:00:00.000Z",
+  "router": {
+    "from": "ACE-Orchestrator",
+    "via": "ACE-Orchestrator",
+    "to": "ACE-Coders"
+  },
+  "task": {
+    "title": "Short task title",
+    "type": "engineering",
+    "priority": "P1",
+    "owner": "ACE-CODERS",
+    "depends_on": [],
+    "scope": "Bounded scope statement"
+  },
+  "context": {
+    "business_requirement": "path/to/file.md#line",
+    "design_constraint": "path/to/file.md#line",
+    "engineering_constraint": "path/to/file.md#line",
+    "directive": "Precise action directive"
+  },
+  "acceptance_criteria": [
+    "Criterion 1 with measurable condition",
+    "Criterion 2 with measurable condition"
+  ],
+  "deliverables": [
+    "path/to/updated/artifact"
+  ],
+  "verification": {
+    "required_evidence": [
+      "artifact_pointers",
+      "verification_evidence"
+    ],
+    "review_check": "Would a staff engineer approve this?",
+    "status": "pending"
+  },
+  "risks": [],
+  "open_questions": [],
+  "lessons_hook": {
+    "on_correction_update": "tasks/lessons.md",
+    "rule_format": "Never <bad pattern>; always <guardrail>."
+  },
+  "return_payload_contract": {
+    "must_include": [
+      "updated_artifact_pointers",
+      "verification_evidence",
+      "residual_risks",
+      "explicit_blockers_or_done_state"
+    ]
+  }
+}

package/assets/tasks/cli_work_split.md

@@ -0,0 +1,22 @@
+# CLI Work Split Contract
+
+## Codex CLI (Primary)
+
+Use Codex CLI for:
+
+- File edits, refactors, implementation changes.
+- Running tests, linters, builds, and local verification.
+- Updating authoritative project artifacts and state files.
+
+## Gemini CLI (Optional Secondary)
+
+Use Gemini CLI for:
+
+- Variant ideation, alternative framing, and style exploration.
+- Comparative brainstorming where direct repo mutation is not required.
+
+## Guardrails
+
+1. Final source-of-truth edits happen via Codex CLI.
+2. Any external suggestion must be validated against local artifacts before adoption.
+3. Verification evidence must be produced from local project commands.