@voybio/ace-swarm 0.1.0

package/assets/.agents/skills/ace-orchestrator/references/engineering-bootstrap-playbook.md

@@ -0,0 +1,360 @@
+---
+name: ace-orchestrator
+description: 
+  Engineering-state bootstrap scanner for ACE-Orchestrator (invoked during the init discovery phase). Runs targeted ast-grep queries on ./src/ or ./engineering-state/ to populate ENGINEERING_SNAPSHOT.md in ./global-state/ giving the orchestrator real code facts before the first SWARM_HANDOFF.json is issued. Without this, GLOBAL_STATE_ANALYSIS is based on directory guesses.
+---
+
+# ACE CodeMunch Boot — Engineering-State Bootstrap Scanner
+
+**IMPORTANT**: Run this skill BEFORE writing `MASTER_PLAN.md` and BEFORE issuing
+the first `SWARM_HANDOFF.json`. The Orchestrator's three alignment questions —
+*"Does the Code match the Design? Does the Design match the Thesis?"* — cannot be
+answered without structural facts about the codebase. This skill produces those
+facts in under 60 seconds via ast-grep, costing near-zero tokens. A
+`GLOBAL_STATE_ANALYSIS` issued without running this first is operating on fiction.
+
+**Do NOT read source files directly.** Every engineering fact must come from an
+ast-grep command or a targeted `find`/`grep` invocation. The Orchestrator is
+a manager, not a code reader.
+
+---
+
+## MICE Boundaries
+
+| Rule | Enforcement |
+|---|---|
+| **Modular** | Scans engineering state; does NOT write code, fix bugs, or change specs. |
+| **Interoperable** | Snapshot output follows canonical `ENGINEERING_SNAPSHOT.md` schema. |
+| **Customizable** | Language detection and quality thresholds adapt to detected project type. |
+| **Extensible** | New language patterns added via ast-grep pattern sets in Step 2. |
+
+## Goal Orientation
+
+- `DELETE_PROTOCOL`: Skip steps for languages not detected in Step 1.
+- `ARTIFACT_PROTOCOL`: Session MUST produce `ENGINEERING_SNAPSHOT.md`. No snapshot = useless boot.
+- `AGENCY_PROTOCOL`: Orchestrator reads snapshot signals to route first `SWARM_HANDOFF.json` without human input.
+
+## Wrong-Stuff Protocol
+
+When engineering scan reveals issues:
+
+| Finding | Classification | Route To |
+|---|---|---|
+| No source code found | `missing_engineering` | `agent-builder` (genesis) |
+| No tests found | `quality_gap` | `agent-builder` (baseline tests) |
+| No MVP spec found | `missing_spec` | VOS (thesis pipeline) |
+| Spec-code misalignment > 50% | `spec_violation` | `agent-spec` + `agent-builder` |
+| > 20 stubs/TODOs | `implementation_debt` | `agent-builder` (debt clear sprint) |
+
+
+
+---
+
+## When to Invoke
+
+| Trigger | Action |
+|---|---|
+| `initiate ACE` boot sequence, Discovery phase | Run **all** steps |
+| Orchestrator detects stale `ENGINEERING_SNAPSHOT.md` (>24h old) | Re-run all steps |
+| ACE-Coders completes a build sprint | Re-run Steps 3 and 4 only (delta scan) |
+| `SWARM_HANDOFF` routing decision requires engineering context | Run Step 4 only |
+| ACE-VOS pivots thesis | Run Step 3 (spec alignment check) only |
+
+---
+
+## Steps
+
+### 1. Locate and Profile the Engineering State
+
+Detect language, size, and structure before running any pattern queries.
+Write nothing to global-state yet — this step only populates working memory.
+
+```bash
+# Detect primary language(s)
+find ./src . -type f \(   -name "*.rs" -o -name "*.py" -o -name "*.ts" -o   -name "*.tsx" -o -name "*.js" -o -name "*.go" \) 2>/dev/null | grep -v ".git\|node_modules\|__pycache__\|target\|dist"   | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -10
+
+# Count total source files and rough LOC estimate
+find ./src . -type f -name "*.py" -o -name "*.ts" -o -name "*.rs" 2>/dev/null   | grep -v ".git\|node_modules\|target" | wc -l
+
+# Detect entry point(s)
+find . -name "main.rs" -o -name "main.py" -o -name "index.ts"        -o -name "app.py" -o -name "server.py" -o -name "main.go" 2>/dev/null   | grep -v ".git\|node_modules\|target" | head -5
+
+# Detect build/package manifest
+ls -1 Cargo.toml pyproject.toml setup.py package.json go.mod 2>/dev/null
+```
+
+Record findings as working variables:
+```
+LANG=<primary language>
+ENTRY=<entry point path>
+FILE_COUNT=<n>
+BUILD_SYSTEM=<cargo|pip|npm|go>
+```
+
+---
+
+### 2. Rapid Public API Census
+
+Extract the public symbol surface. This tells the Orchestrator what the codebase
+currently DOES — the ground truth it needs to compare against the thesis.
+
+```bash
+# --- Rust ---
+# Public functions
+ast-grep --pattern 'pub fn $NAME($$$)' --lang rust --color never   | grep -oP 'pub fn \K\w+' | sort -u   >> /tmp/ace_boot_symbols.txt
+
+# Public types
+ast-grep --pattern 'pub struct $NAME' --lang rust --color never   | grep -oP 'pub struct \K\w+' | sort -u   >> /tmp/ace_boot_symbols.txt
+
+ast-grep --pattern 'pub enum $NAME' --lang rust --color never   | grep -oP 'pub enum \K\w+' | sort -u   >> /tmp/ace_boot_symbols.txt
+
+# --- Python ---
+ast-grep --pattern 'def $NAME($$$):' --lang python --color never --json   | python3 -c "import sys,json; [print(s['metaVariables']['NAME']) for s in json.load(sys.stdin)]"   | sort -u >> /tmp/ace_boot_symbols.txt
+
+ast-grep --pattern 'class $NAME:' --lang python --color never --json   | python3 -c "import sys,json; [print(s['metaVariables']['NAME']) for s in json.load(sys.stdin)]"   | sort -u >> /tmp/ace_boot_symbols.txt
+
+# --- TypeScript / JavaScript ---
+ast-grep --pattern 'export function $NAME($$$)' --lang ts --color never --json   | python3 -c "import sys,json; [print(s['metaVariables']['NAME']) for s in json.load(sys.stdin)]"   | sort -u >> /tmp/ace_boot_symbols.txt
+
+ast-grep --pattern 'export class $NAME' --lang ts --color never --json   | python3 -c "import sys,json; [print(s['metaVariables']['NAME']) for s in json.load(sys.stdin)]"   | sort -u >> /tmp/ace_boot_symbols.txt
+
+# Total symbol count
+wc -l /tmp/ace_boot_symbols.txt
+```
+
+---
+
+### 3. Engineering Quality Scan
+
+Measures the HEALTH of the engineering state. The Orchestrator needs this to decide
+whether ACE-Coders needs a quality pass before any new feature work.
+
+```bash
+# --- Test coverage signal ---
+# Rust: count test functions
+ast-grep --pattern '#[test] fn $NAME()' --lang rust --color never   | grep -c "fn " || echo "0 rust tests"
+
+# Python: count test functions
+ast-grep --pattern 'def test_$NAME($$$):' --lang python --color never   | grep -c "def " || echo "0 python tests"
+
+# TypeScript: count test blocks
+ast-grep --pattern "it('$DESC', $$$)" --lang ts --color never   | grep -c "it(" || echo "0 ts tests"
+ast-grep --pattern 'test("$DESC", $$$)' --lang ts --color never   | grep -c "test(" || echo "0 ts tests"
+
+# --- Completion signal: stubs and TODOs ---
+# Rust: unimplemented/todo macros (hard stubs)
+ast-grep --pattern 'unimplemented!()' --lang rust --color never | grep -c "unimplemented"
+ast-grep --pattern 'todo!()' --lang rust --color never | grep -c "todo"
+
+# Python: NotImplemented raises
+ast-grep --pattern 'raise NotImplementedError' --lang python --color never | grep -c "raise"
+
+# Cross-language: comment-level TODOs (soft stubs)
+grep -rn "TODO\|FIXME\|HACK\|XXX"   --include="*.rs" --include="*.py" --include="*.ts" --include="*.tsx"   --include="*.js" --include="*.go"   . 2>/dev/null | grep -v ".git\|node_modules\|target"   | wc -l
+
+# --- Risk signal: unsafe code, panics ---
+# Rust: unsafe blocks (correctness risk surface)
+ast-grep --pattern 'unsafe { $$$ }' --lang rust --color never | grep -c "unsafe"
+
+# Rust: unwrap() calls (panic risk surface)
+ast-grep --pattern '$EXPR.unwrap()' --lang rust --color never | grep -c "unwrap"
+
+# --- Architecture signal: async vs sync ---
+ast-grep --pattern 'async fn $NAME($$$)' --lang rust --color never | grep -c "async"
+ast-grep --pattern 'async def $NAME($$$):' --lang python --color never | grep -c "async"
+ast-grep --pattern 'async function $NAME($$$)' --lang ts --color never | grep -c "async"
+```
+
+---
+
+### 4. Spec Alignment Check
+
+Compare what the code DOES against what the thesis/MVP spec CLAIMS it should do.
+This is the Orchestrator's core alignment question answered with evidence.
+
+```bash
+# Only run if venture-state MVP spec exists
+if [ -f "./venture-state/MVP_SPEC.md" ]; then
+
+  # Extract feature keywords from MVP spec (nouns from headings and bullets)
+  grep -oP '(?<=^#{1,3} ).*|(?<=^- ).*' ./venture-state/MVP_SPEC.md     | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9_' '
+'     | sort -u | grep -v "^.$\|^..$"     > /tmp/ace_spec_keywords.txt
+
+  # Check which spec keywords appear in engineering symbol names
+  comm -12     <(sort /tmp/ace_boot_symbols.txt | tr '[:upper:]' '[:lower:]')     <(sort /tmp/ace_spec_keywords.txt)     > /tmp/ace_covered_features.txt
+
+  # Keywords in spec NOT found in code (unbuilt features)
+  comm -23     <(sort /tmp/ace_spec_keywords.txt)     <(sort /tmp/ace_boot_symbols.txt | tr '[:upper:]' '[:lower:]')     > /tmp/ace_missing_features.txt
+
+  echo "=== COVERED (spec keyword found in code) ==="
+  cat /tmp/ace_covered_features.txt | head -20
+
+  echo "=== MISSING (spec keyword NOT found in code) ==="
+  cat /tmp/ace_missing_features.txt | head -20
+
+fi
+
+# Check for any existing engineering-state STATUS.md
+if [ -f "./engineering-state/STATUS.md" ]; then
+  head -30 ./engineering-state/STATUS.md
+fi
+```
+
+---
+
+### 5. Write ENGINEERING_SNAPSHOT.md
+
+Crystallise all findings into a single artifact that the Orchestrator reads during
+`GLOBAL_STATE_ANALYSIS`. This file becomes the engineering column of `MASTER_PLAN.md`.
+
+Write to: `./global-state/ENGINEERING_SNAPSHOT.md`
+
+```markdown
+# ENGINEERING_SNAPSHOT.md
+Generated: <ISO8601 timestamp>
+Scanned By: ace-codemunch-boot skill
+
+---
+
+## Profile
+- **Primary Language:** <lang>
+- **Build System:** <cargo | pip | npm | go | unknown>
+- **Entry Point:** <path>
+- **Source Files:** <n>
+- **Public Symbols:** <n> (functions, classes, types)
+
+---
+
+## Quality Signals
+| Signal | Value | Risk Level |
+|---|---|---|
+| Test functions found | <n> | 🟢 / 🟡 / 🔴 |
+| Hard stubs (unimplemented!/todo!) | <n> | 🟢 / 🟡 / 🔴 |
+| Soft stubs (TODO/FIXME comments) | <n> | 🟢 / 🟡 / 🔴 |
+| Unsafe blocks (Rust) / unwrap() | <n> | 🟢 / 🟡 / 🔴 |
+| Concurrency model | async / sync / mixed | — |
+
+Risk thresholds: 🟢 = low (0–5), 🟡 = medium (6–20), 🔴 = high (>20)
+
+---
+
+## Spec Alignment (vs venture-state/MVP_SPEC.md)
+- **Covered features** (keyword found in code): <n> — see /tmp/ace_covered_features.txt
+- **Missing features** (keyword NOT found in code): <n> — see /tmp/ace_missing_features.txt
+
+### Top missing features (unbuilt spec items):
+- <keyword 1>
+- <keyword 2>
+- <keyword 3>
+
+---
+
+## Routing Signals for Orchestrator
+
+<!-- FILL THESE IN based on scan results above -->
+<!-- These are the Orchestrator's inputs to SWARM_HANDOFF routing logic -->
+
+CODERS_NEEDED_FOR:
+  - <stub count > 10 → "Coders must clear stubs before new features">
+  - <test count < 5 → "Coders must write baseline tests first">
+  - <missing spec features → list top 3>
+
+VOS_NEEDED_FOR:
+  - <missing features count > 10 → "MVP scope may be too large; VOS must re-triage">
+  - <0 spec file found → "No thesis artifact; VOS must run genesis pipeline first">
+
+UI_NEEDED_FOR:
+  - <no brand-state/ → "UI has not defined copy or flows yet">
+
+PIPELINE_RECOMMENDATION: <genesis | pivot | ship_it>
+  Reason: <one sentence — e.g., "Code has 40% spec coverage and 3 stubs; pivot pipeline to clear debt first">
+
+---
+
+## Evidence Log
+All ast-grep commands that produced this snapshot are appended below.
+<paste raw command outputs here>
+```
+
+---
+
+### 6. Inject into MASTER_PLAN.md and Route
+
+After `ENGINEERING_SNAPSHOT.md` is written, the Orchestrator uses it to:
+
+1. **Populate the Engineering column** of `MASTER_PLAN.md`:
+```markdown
+## Engineering State (from ENGINEERING_SNAPSHOT.md, <date>)
+- Symbols: <n> | Tests: <n> | Stubs: <n> | Spec coverage: <n>%
+- Status: <one sentence from routing signals>
+```
+
+2. **Check alignment** across all three pillars before routing:
+```
+CODE alignment check:
+  venture-state/MVP_SPEC.md exists?  → YES / NO
+  brand-state/DESIGN_SYSTEM.md exists? → YES / NO
+  MISSING FEATURES in snapshot > 0?  → route to Coders or VOS
+  STUB COUNT > 10?                   → route to Coders (debt-clear sprint)
+  NO TESTS?                          → route to Coders (baseline test sprint)
+  NO MVP SPEC?                       → route to VOS (genesis pipeline)
+```
+
+3. **Emit the first SWARM_HANDOFF.json** with engineering context attached:
+```json
+{
+  "router": {
+    "from": "ace-init",
+    "via": "ace-orchestrator",
+    "to": "<ace-vos | ace-ui | ace-coders>"
+  },
+  "context": {
+    "business_requirement": "./venture-state/MVP_SPEC.md",
+    "engineering_snapshot": "./global-state/ENGINEERING_SNAPSHOT.md",
+    "directive": "<derived from PIPELINE_RECOMMENDATION in snapshot>",
+    "engineering_signals": {
+      "symbol_count": "<n>",
+      "test_count": "<n>",
+      "stub_count": "<n>",
+      "missing_features": ["<f1>", "<f2>", "<f3>"],
+      "pipeline": "<genesis | pivot | ship_it>"
+    }
+  }
+}
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Behavior |
+|---|---|
+| Reading raw source files | Use ast-grep queries and `find`/`grep` only |
+| Routing without engineering snapshot | Always run scan before first `SWARM_HANDOFF.json` |
+| Guessing test count | Count via ast-grep test pattern queries |
+| Issuing `SWARM_HANDOFF` with empty `engineering_signals` | Snapshot data must populate handoff context |
+| Skipping delta scan after coder sprint | Re-run Steps 3-4 to update snapshot |
+
+---
+
+## Quick Reference: Signal → Pipeline Mapping
+
+| Engineering State | Venture State | Recommended Pipeline |
+|---|---|---|
+| No code yet | No MVP spec | `genesis` — VOS → UI → Coders |
+| Code exists, no tests, many stubs | MVP spec exists | `pivot` — Coders (debt clear) → Coders (build) |
+| Code exists, tests passing | MVP spec exists | `ship_it` — UI critique → Coders (QA) |
+| Code exists, stubs only | No MVP spec | `genesis` — VOS must define scope first |
+| Code complete, spec coverage > 80% | MVP spec complete | `ship_it` — UI polish then deploy |
+
+---
+
+## Activation
+
+This skill is called automatically during ACE boot. It can also be called explicitly:
+
+**`ACE --mode boot --write-to ./global-state/ENGINEERING_SNAPSHOT.md`**
+
+Or manually triggered by the Orchestrator at any time with:
+
+**`ACE --mode delta`** — re-runs Steps 3 and 4 only (quality + alignment, no full census)

package/assets/.agents/skills/astgrep-index/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: astgrep-index
+description:
+  Build compact AST discovery indexes and routing hints for the current workspace. Use when ACE bootstrap, orchestration, or research needs structural discovery without loading raw file maps into context.
+---
+
+# ASTGrep Index
+
+Use this skill to refresh durable AST-level discovery artifacts before orchestration or research decisions depend on them.
+
+## Purpose
+
+Replace broad file-dump discovery with compact, evidence-backed AST summaries that are safe to store and easy to reuse.
+
+## Canonical Use Cases
+
+1. `ace init` or a fresh workspace bootstrap needs structural discovery artifacts immediately after seeding `agent-state/`.
+2. Orchestrator or research flows need routing hints, top symbols, and hotspots without reading large file maps.
+3. A major refactor changed the workspace shape and the AST discovery index must be refreshed before the next planning pass.
+
+## Inputs
+
+- `agent-state/AST_GREP_COMMANDS.md`
+- `agent-state/TASK.md`
+- `agent-state/SCOPE.md`
+- Optional AST reference corpus such as `rep_astgrep.cxml`
+
+## Workflow
+
+1. Profile the requested scope using the command pack from `AST_GREP_COMMANDS.md`.
+2. Run symbol-surface and quality-signal queries for the active language mix.
+3. Summarize hotspots, top symbols, and routing hints instead of storing raw code or raw file dumps.
+4. Write both markdown and JSON discovery artifacts.
+5. Append an evidence anchor to `agent-state/EVIDENCE_LOG.md`.
+
+## Outputs
+
+- `agent-state/AST_GREP_INDEX.md`
+- `agent-state/AST_GREP_INDEX.json`
+- An evidence entry linking the discovery run to the generated artifacts
+
+## Validation
+
+- Verify both `agent-state/AST_GREP_INDEX.md` and `agent-state/AST_GREP_INDEX.json` are written during the same run.
+- Verify the two artifacts agree on core metadata such as scope, generated timestamp, commands used, and summary findings.
+- Verify `agent-state/EVIDENCE_LOG.md` contains an entry referencing both outputs.
+
+## Compatibility
+
+- `SKILL.md` is the portable source of truth for the index workflow.
+- The command pack is an input artifact, not a client-specific requirement.
+- The skill should remain useful even when no extra reference corpus is available.
+
+## Failure Policy
+
+- If the command pack is missing or ast-grep is unavailable, stop and surface the missing dependency explicitly.
+- If the scope is too broad, narrow the scan instead of silently producing a low-signal index.
+- Never dump raw file contents into the index artifacts; keep them summary-only and decision-oriented.

package/assets/.agents/skills/codemunch/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: codemunch
+description:
+  Map an unfamiliar codebase into durable structural artifacts with ast-grep. Use when you need to understand, debug, contribute to, or borrow patterns from a codebase without broad raw-file reading.
+---
+
+# CodeMunch
+
+Use this skill to turn an unfamiliar codebase into a compact set of structural artifacts that downstream agents can trust.
+
+## Purpose
+
+Extract architecture, public surface, relationships, and recurring patterns through AST-backed evidence so future work starts from a written map instead of ad-hoc memory.
+
+## Canonical Use Cases
+
+1. A team needs a codebase map before debugging, feature work, or onboarding into an unfamiliar repository.
+2. A contributor wants to identify the minimum insertion point for a change without reading large amounts of raw code first.
+3. An engineer wants reusable patterns, conventions, and hotspots distilled into durable artifacts for later handoff.
+
+## Inputs
+
+- Target codebase path or repository checkout
+- Goal or intent such as `understand`, `debug`, `contribute`, or `inspire`
+- Project orientation artifacts like README, manifests, and existing `agent-state/` outputs when available
+- ast-grep plus any language-specific patterns needed for the active language mix
+
+## Workflow
+
+1. Bootstrap language, build-system, and entry-point understanding with minimal orientation reads.
+2. Answer the Socratic question stack with ast-grep-backed evidence.
+3. Write the core structural artifacts: `CODEBASE_MAP.md`, `DEPENDENCY_GRAPH.md`, `PATTERNS.md`, `SOCRATIC_LOG.md`, and `EVIDENCE_LOG.md`.
+4. Produce a goal-specific synthesis artifact such as a contribution guide or bug hypothesis.
+5. Hand off from the written artifacts rather than from unwritten session memory.
+
+## Outputs
+
+- `agent-state/CODEBASE_MAP.md`
+- `agent-state/DEPENDENCY_GRAPH.md`
+- `agent-state/PATTERNS.md`
+- `agent-state/SOCRATIC_LOG.md`
+- `agent-state/EVIDENCE_LOG.md`
+- Optional goal-specific artifacts such as `CONTRIBUTION_GUIDE.md` or `BUG_HYPOTHESIS.md`
+
+## Validation
+
+- Verify the core artifact set is written before any final synthesis or handoff occurs.
+- Verify every structural claim in the synthesis can be traced back to an ast-grep-backed entry in `EVIDENCE_LOG.md`.
+- Verify unanswered questions are recorded explicitly as known unknowns rather than guessed.
+
+## References
+
+- `references/ast-driven-protocol.md` preserves the detailed Socratic stack, phase-by-phase command recipes, and advanced ast-grep cookbook.
+
+## Compatibility
+
+- `SKILL.md` is the canonical portable contract for this skill.
+- The long-form playbook lives under `references/` for progressive disclosure and must not redefine the top-level contract.
+- The workflow should remain useful in any environment that can run ast-grep and basic shell discovery commands.
+
+## Failure Policy
+
+- If ast-grep is unavailable or the language cannot be queried safely, stop and surface the limitation instead of pretending the structure is understood.
+- If required artifacts were not written, treat the session as incomplete rather than summarizing from memory.
+- Do not read large swaths of raw source just to compensate for missing structural evidence; mark the unknown and route accordingly.