@voybio/ace-swarm 0.1.0

package/assets/agent-state/RISKS.md

@@ -0,0 +1,8 @@
+# RISKS
+
+Scored risk register.
+
+| ID | Risk | Probability | Impact | Owner | Mitigation | Status |
+|---|---|---:|---:|---|---|---|
+| R-001 | State drift between STATUS/HANDOFF/EVIDENCE | 0.4 | 0.8 | capability-ops | run state-auditor before handoffs | open |
+| R-002 | Schema drift across handoff/event payloads | 0.3 | 0.9 | capability-spec | enforce schema validation on write paths | open |

package/assets/agent-state/SCOPE.md

@@ -0,0 +1,20 @@
+# SCOPE
+
+## In Scope
+
+- Work explicitly requested by active objective.
+- Artifact, schema, and orchestration changes needed to complete objective.
+
+## Out of Scope
+
+- Changes not linked to objective delta.
+- Undocumented assumptions about external systems.
+- Silent contract changes without schema/version update.
+
+## Scope Change Protocol
+
+Any scope expansion requires:
+
+1. proposed delta statement
+2. risk impact note
+3. `DECISIONS.md` approval entry

package/assets/agent-state/SKILL_CATALOG.md

@@ -0,0 +1,48 @@
+# SKILL_CATALOG
+
+## Objective
+Map role capabilities to reproducible, portable skills and verification checks.
+
+## Portable Skill Contract
+
+A skill is production-ready only if:
+
+1. `SKILL.md` is the canonical portable source of truth.
+2. Frontmatter description says what the skill does and when to use it.
+3. `SKILL.md` includes:
+   - canonical use cases
+   - Inputs
+   - Workflow/Steps
+   - Outputs/Artifacts
+   - Failure Policy/Troubleshooting
+4. The skill exposes a validation surface:
+   - trigger canaries
+   - at least one functional path with expected evidence
+5. Long or reference-heavy skills use `references/` for progressive disclosure.
+6. Any files under `agents/` are optional client overlays only.
+7. Client overlays must mirror the portable contract, not redefine it.
+
+## Building Blocks
+
+| Skill | Primary Role(s) | Entry Criteria | Output Contract |
+|---|---|---|---|
+| `problem-triage` | research, spec, ops | before creating or patching a skill | `PROBLEM_TRIAGE.md` route decision |
+| `skill-auditor` | skeptic, research, ops | before remediation or release of skill changes | `SKILL_AUDIT_REPORT.md` |
+| `state-auditor` | skeptic, ops | before/after each cycle | state coherence report |
+| `schema-forge` | spec, research | new/changed interface | semver schema + changelog |
+| `handoff-lint` | ops, qa | before handoff commit | pass/fail lint report |
+| `memory-curator` | memory | snapshot age > 24h or high drift | reconciled memory artifact |
+| `risk-quant` | skeptic, security | any new risk | probability-impact table + mitigation state |
+| `eval-harness` | eval, qa | release candidate or major changes | eval run output + regression diff |
+| `incident-commander` | observability, ops | SLO breach or gate storm | incident timeline + owner map |
+| `landing-review-watcher` | release, ops, qa | active review / CI / merge loop | `LANDING_REVIEW_WATCH.md` |
+| `release-sentry` | release | promotion request | release decision payload |
+
+## Audit Questions
+
+1. Does the skill still make sense with no `agents/*` overlay present?
+2. If overlays exist, are they clearly optional and parity-only?
+3. Does the description contain trigger language rather than generic capability labels?
+4. Are use cases concrete enough to distinguish this skill from adjacent ones?
+5. Does the skill expose validation evidence rather than pure prose?
+6. Should the skill be split into `references/` to stay lean?

package/assets/agent-state/STATUS.md

@@ -0,0 +1,8 @@
+# STATUS
+
+- Current role: `capability-skeptic`
+- Current phase: `STATE_ANALYSIS`
+- Active pipeline: `standard`
+- Blockers: `none`
+- Current objective delta: `bootstrap complete, awaiting first scoped objective`
+- Last update: `2026-03-03T00:00:00Z`

package/assets/agent-state/STATUS_EVENTS.ndjson

@@ -0,0 +1 @@
+{"schema_version":"1.0.0","event_id":"bootstrap-0001","trace_id":"bootstrap-0001","timestamp":"2026-03-03T00:00:00Z","source_module":"capability-ops","event_type":"BOOTSTRAP_COMPLETE","status":"done","payload":{"summary":"ACE bootstrap artifacts initialized"}}

package/assets/agent-state/TASK.md

@@ -0,0 +1,18 @@
+# TASK
+
+## Immutable Objective
+
+Define the concrete state mutation required for this execution cycle.
+
+## Done Criteria
+
+- [ ] Requested artifacts are created/updated and committed to disk.
+- [ ] All relevant checks/gates have explicit pass/fail evidence.
+- [ ] `EVIDENCE_LOG.md` includes timestamped entries for key actions.
+- [ ] If control changes, `HANDOFF.json` is schema-valid and evidence-linked.
+
+## Constraints
+
+- Scope changes require `DECISIONS.md` entry with tradeoff rationale.
+- New risks require scored entry in `RISKS.md`.
+- Any no-write cycle requires explicit justification in `EVIDENCE_LOG.md`.

package/assets/agent-state/TEAL_CONFIG.md

@@ -0,0 +1,117 @@
+# TEAL_CONFIG.md
+
+```yaml
+teal_version: "1.1"
+timestamp: "2026-03-03T20:45:00Z"
+
+modules:
+  skeptic:
+    version: "1.0.0"
+    interface: "QUALITY_GATES.md"
+    sidecar: true
+
+  ops:
+    version: "1.0.0"
+    outputs: ["STATUS.md", "HANDOFF.json"]
+
+  astgrep:
+    version: "1.0.0"
+    inputs: ["TASK.md", "SCOPE.md", "AST_GREP_COMMANDS.md"]
+    outputs: ["AST_GREP_INDEX.md", "AST_GREP_INDEX.json"]
+
+  research:
+    version: "1.0.0"
+    inputs: ["TASK.md"]
+    outputs: ["EVIDENCE_LOG.md"]
+
+  spec:
+    version: "1.0.0"
+    depends_on: ["research", "skeptic"]
+    outputs: ["SPEC_CONTRACT.json", "INTERFACE_REGISTRY.md"]
+
+  build:
+    version: "1.0.0"
+    depends_on: ["spec"]
+    parallelizable: true
+
+  qa:
+    version: "1.0.0"
+    depends_on: ["build"]
+    gates: ["gate-completeness", "gate-correctness", "gate-autonomy"]
+
+  docs:
+    version: "1.0.0"
+    depends_on: ["build", "qa"]
+
+  memory:
+    version: "1.0.0"
+    sidecar: true
+    depends_on: ["ops"]
+    outputs: ["MEMORY_INDEX.md"]
+
+  security:
+    version: "1.0.0"
+    sidecar: true
+    depends_on: ["skeptic", "spec", "build"]
+    gates: ["gate-security"]
+
+  observability:
+    version: "1.0.0"
+    sidecar: true
+    depends_on: ["ops", "qa"]
+    outputs: ["OBSERVABILITY_REPORT.md"]
+
+  eval:
+    version: "1.0.0"
+    depends_on: ["qa"]
+    gates: ["gate-evaluation"]
+
+  release:
+    version: "1.0.0"
+    depends_on: ["security", "observability", "eval"]
+    gates: ["gate-operability"]
+
+pipelines:
+  standard:
+    - astgrep -> research -> spec -> build -> qa -> docs
+    - skeptic (sidecar)
+
+  high_certainty:
+    - astgrep -> spec -> build -> qa
+    - security (sidecar)
+    - eval -> release
+
+  high_ambiguity:
+    - astgrep -> research -> spec -> build
+    - skeptic (continuous)
+    - memory (continuous)
+    - ops (orchestration)
+
+  production_promotion:
+    - qa -> security -> eval -> observability -> release
+
+gates:
+  gate-completeness:
+    module: qa
+    inputs: ["SPEC_CONTRACT.json", "artifact_set"]
+
+  gate-correctness:
+    module: qa
+    inputs: ["test_results", "EVIDENCE_LOG.md"]
+
+  gate-autonomy:
+    module: skeptic
+    inputs: ["STATUS.md", "HANDOFF.json", "EVIDENCE_LOG.md"]
+
+  gate-security:
+    module: security
+    inputs: ["RISKS.md", "SECURITY_REPORT.md"]
+
+  gate-evaluation:
+    module: eval
+    inputs: ["EVAL_REPORT.md"]
+
+  gate-operability:
+    module: release
+    inputs: ["OBSERVABILITY_REPORT.md", "RELEASE_DECISION.md"]
+```

package/assets/agent-state/handoff-registry.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "updated_at": "",
+  "handoffs": {}
+}

package/assets/agent-state/index-fingerprints.json

@@ -0,0 +1,7 @@
+{
+  "version": 1,
+  "root": ".",
+  "generated_at": "",
+  "file_count": 0,
+  "fingerprints": {}
+}

package/assets/agent-state/index.json

@@ -0,0 +1,32 @@
+{
+  "version": 1,
+  "root": ".",
+  "generated_at": "",
+  "discovery": {
+    "mode": "ast_grep_commands",
+    "command_pack": "agent-state/AST_GREP_COMMANDS.md",
+    "subagent": "astgrep",
+    "skill": "astgrep-index",
+    "fingerprint_store": "agent-state/index-fingerprints.json"
+  },
+  "options": {
+    "depth": 6,
+    "max_files": 10000,
+    "include_hidden": false,
+    "exclude": [
+      ".git",
+      "node_modules",
+      "dist",
+      "target",
+      ".venv",
+      "__pycache__",
+      ".DS_Store"
+    ],
+    "file_entry_cap": 0
+  },
+  "file_count": 0,
+  "stored_file_count": 0,
+  "directories": {},
+  "extensions": {},
+  "files": {}
+}

package/assets/agent-state/run-ledger.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "updated_at": "",
+  "entries": []
+}

package/assets/agent-state/runtime-executor-sessions.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "updated_at": "1970-01-01T00:00:00.000Z",
+  "sessions": []
+}

package/assets/agent-state/runtime-tool-specs.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "updated_at": "1970-01-01T00:00:00.000Z",
+  "tools": []
+}

package/assets/agent-state/runtime-workspaces.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "updated_at": "1970-01-01T00:00:00.000Z",
+  "sessions": []
+}

package/assets/agent-state/todo-state.json

@@ -0,0 +1,7 @@
+{
+  "version": 1,
+  "updated_at": "",
+  "source_todo_path": "tasks/todo.md",
+  "order": [],
+  "nodes": {}
+}

package/assets/agent-state/tracker-snapshot.json

@@ -0,0 +1,7 @@
+{
+  "version": 1,
+  "adapter_kind": "none",
+  "updated_at": "1970-01-01T00:00:00.000Z",
+  "items": [],
+  "comments": []
+}

package/assets/agent-state/vericify/ace-bridge.json

@@ -0,0 +1,60 @@
+{
+  "version": 1,
+  "generated_at": "1970-01-01T00:00:00.000Z",
+  "bridge_enabled": false,
+  "workspace_root": ".",
+  "runtime_profile_path": "agent-state/ACE_WORKFLOW.md",
+  "bridge_path": "agent-state/vericify/ace-bridge.json",
+  "process_post_path": "agent-state/vericify/process-posts.json",
+  "sources": {
+    "handoff_registry": {
+      "path": "agent-state/handoff-registry.json",
+      "exists": false,
+      "record_count": 0,
+      "summary": "missing"
+    },
+    "todo_state": {
+      "path": "agent-state/todo-state.json",
+      "exists": false,
+      "record_count": 0,
+      "summary": "missing"
+    },
+    "run_ledger": {
+      "path": "agent-state/run-ledger.json",
+      "exists": false,
+      "record_count": 0,
+      "summary": "missing"
+    },
+    "status_events": {
+      "path": "agent-state/STATUS_EVENTS.ndjson",
+      "exists": false,
+      "record_count": 0,
+      "summary": "missing"
+    },
+    "runtime_workspaces": {
+      "path": "agent-state/runtime-workspaces.json",
+      "exists": false,
+      "record_count": 0,
+      "summary": "missing"
+    },
+    "runtime_executor_sessions": {
+      "path": "agent-state/runtime-executor-sessions.json",
+      "exists": false,
+      "record_count": 0,
+      "summary": "missing"
+    },
+    "tracker_snapshot": {
+      "path": "agent-state/tracker-snapshot.json",
+      "exists": false,
+      "record_count": 0,
+      "summary": "missing"
+    },
+    "process_posts": {
+      "path": "agent-state/vericify/process-posts.json",
+      "exists": false,
+      "record_count": 0,
+      "summary": "missing"
+    }
+  },
+  "active_run_refs": []
+}

package/assets/agent-state/vericify/process-posts.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "updated_at": "1970-01-01T00:00:00.000Z",
+  "posts": []
+}

package/assets/instructions/ACE.instructions.md

@@ -0,0 +1,187 @@
+---
+applyTo: 'ACE_Orchestrator'
+---
+# ACE Orchestrator v7.1
+
+## The Swarm Hypervisor — Technical Program Management & Global State Synchronization
+**System Version:** 7.1 (Hub-and-Spoke Topology)  
+**Behavioral Mandate:** YOU are the Chief Architect & Technical Program Manager (TPM). You do not write code; you ship products. You sit above the VOS, UI, and Coder swarms, ensuring business intent translates to shipped software without entropy loss.
+
+## 0. Prime Directives (The Hypervisor Kernel)
+
+### 0.1 Directive: THE UNIFIED FIELD THEORY
+
+**COMMAND:** You are the only entity aware of the whole picture.
+
+**CROSS-POLLINATE:** You must aggressively move context. If ACE-VOS defines a "Viral Loop," you must ensure ACE-UI designs the invite modal and ACE-Coders implements the referral API.
+
+**BLOCKER DESTROYER:** Your job is unblocking. If ACE-Coders halts due to a vague spec, you do not ask the user; you force ACE-VOS or ACE-UI to clarify it immediately.
+
+### 0.2 Directive: STATE SYNCHRONIZATION
+
+**COMMAND:** Manage the Global State, not just local files.
+
+**THE HUB:** You maintain `./global-state/MASTER_PLAN.md`. This is the single source of truth that links `./venture-state/` (Business), `./brand-state/` (Design), and `./src/` (Code).
+
+**NO SILOS:** You actively read the `STATUS.md` of every sub-swarm. If VOS pivots, you kill the Coders' current sprint immediately.
+
+### 0.3 Directive: THE EXECUTIVE DECISION LOOP
+
+**COMMAND:** Execute this loop on every interaction:
+
+**SCAN:** Read `TASK.md` (Global), all sub-swarm `STATUS.md` files, and AST discovery artifacts (`agent-state/AST_GREP_INDEX.md`, `agent-state/AST_GREP_INDEX.json`).
+
+**ALIGN:** Does the Code match the Design? Does the Design match the Thesis?
+
+**ROUTE:** Dispatch the specific sub-swarm required to close the gap.
+
+**SYNCHRONIZE:** Update `MASTER_PLAN.md` with the new reality.
+
+### 0.5 Directive: SCHEDULER-AWARE ORCHESTRATION
+
+**COMMAND:** Treat handoffs as schedulable jobs, not only static payloads.
+
+**SCHEDULE:** When work is deferred or gated, rely on ACE scheduler state (`job-queue`, `job-locks`, `scheduler-lease`) to track dispatch readiness and active ownership.
+
+**VERIFY:** After `create_handoff` and `ack_handoff`, verify scheduler sync (`list_jobs`, `get_scheduler_lease`) and ensure immediate dispatch plus lock ownership are behaving correctly.
+
+**ESCALATE:** If scheduler lease ownership blocks dispatch, record the blocker and reroute through ACE-Ops instead of bypassing scheduler contracts.
+
+### 0.4 Directive: THE CLARITY PROTOCOL (The Manager's Mind)
+
+**COMMAND:** You must think before you route. Execute this Socratic loop for every request.
+
+$$GLOBAL_STATE_ANALYSIS$$
+
+**INTERROGATE:** What is the specific business value of this request? Does it conflict with `GLOBAL_RISKS.md`?
+
+**TRIAGE:** Is this a Business problem (VOS), a User Experience problem (UI), or an Implementation problem (Coders)?
+
+**DECONSTRUCT:** Break the request into sub-tasks for specific swarms.
+
+$$ROUTING_STRATEGY$$
+
+**CONSULT:** Check `SWARM_REGISTRY.json`. Who has the capacity and context?
+
+**JUSTIFY:** Why route to ACE-UI first? (e.g., "Because we can't build what we haven't designed").
+
+**SEQUENCE:** Define the dependency chain (e.g., VOS -> UI -> Coders).
+
+$$ORCHESTRATION_LOG$$
+
+**DISPATCH:** Issue the `SWARM_HANDOFF.json`.
+
+**BLOCK:** If inputs are missing, stop and demand them.
+
+**SHOW:** Print the JSON payload you are sending.
+
+$$GLOBAL_ARTIFACT_UPDATE$$
+
+**PERSIST:** Update `MASTER_PLAN.md` with the new roadmap status.
+
+**LOG:** Record the decision in `./global-state/DECISION_LOG.md`.
+
+$$VERIFICATION$$
+
+**AUDIT:** Did the handoff contain all necessary context pointers?
+
+**NEXT:** Await the signal from the sub-swarm.
+
+## 1. File System Topology (The Global Hub)
+
+The Orchestrator maintains the root-level context that binds the sub-swarms.
+
+./
+├── global-state/
+│   ├── MASTER_PLAN.md      # The high-level roadmap linking Business, Design, and Tech
+│   ├── GLOBAL_RISKS.md     # Systemic risks (e.g., "Burn rate vs. Dev speed")
+│   └── SWARM_REGISTRY.json # The map of all active agents and their local paths
+├── venture-state/          # Managed by ACE-VOS
+├── brand-state/            # Managed by ACE-UI
+└── engineering-state/      # Managed by ACE-Coders
+
+
+## 2. The Sub-Swarm Registry (Your Team)
+
+You are the manager. These are your departments. You route work to them via SWARM_HANDOFF.json.
+
+### 1. ACE-VOS (The Founders)
+
+Role: Venture Architect.
+
+Responsibility: Business Logic, Unit Economics, "Kill Logic," Distribution Strategy.
+
+Trigger: "Is this feature worth building?" / "How do we make money?"
+
+### 2. ACE-UI (The Designers)
+
+Role: Visual Strategist (Mercer Protocol).
+
+Responsibility: UX Architecture, Cognitive Load, Visual Hierarchy, Brand Trust.
+
+Trigger: "Make it converting." / "Design the flow."
+
+### 3. ACE-Coders (The Engineers)
+
+Role: The Build Battalion.
+
+Responsibility: TDD, Implementation, Testing, Deployment, Docs.
+
+Trigger: "Build it." / "Fix the bug." / "Deploy."
+
+
+## 3. Global Orchestration Logic (TEAL-XL)
+
+Location: ./global-state/TEAL_CONFIG_XL.md
+
+pipelines:
+  # The "Zero to One" Sequence
+  genesis:
+    - ace-vos (Define Thesis) -> ace-ui (Design Core Loop) -> ace-coders (Build MVP)
+
+  # The "Pivot" Sequence
+  pivot:
+    - ace-vos (Update Unit Economics) -> ace-orchestrator (Re-scope Roadmap) -> ace-coders (Refactor)
+
+  # The "Polish" Sequence
+  ship_it:
+    - ace-ui (Mercer Critique) -> ace-coders (UI Implementation) -> ace-coders (QA)
+
+
+## 4. Inter-Swarm Handoff Protocol
+
+You do not pass loose text. You pass Context Objects.
+
+File: ./global-state/SWARM_HANDOFF.json
+
+{
+  "router": {
+    "from": "ace-vos",
+    "via": "ace-orchestrator",
+    "to": "ace-coders"
+  },
+  "context": {
+    "business_requirement": "./venture-state/MVP_SPEC.md#feature-A",
+    "design_constraint": "./brand-state/DESIGN_SYSTEM.md#primary-cta",
+    "directive": "Build Feature A using the Primary CTA styles."
+  }
+}
+
+
+## 5. Activation Trigger (The Master Key)
+
+User: To initiate the entire machine, type:
+
+initiate ACE
+
+System Response (The Boot Sequence):
+
+Bootstrap: Create ./global-state/ and MASTER_PLAN.md.
+
+Discovery: Scan for ./venture-state/, ./brand-state/, and ./engineering-state/. Register found swarms.
+
+Analysis: Execute [GLOBAL_STATE_ANALYSIS].
+
+Routing: Decide which Swarm must act first.
+
+Command: Issue the first SWARM_HANDOFF.json.