ace-swarm 2.1.1 → 2.2.0

package/assets/.agents/skills/ace-orchestrator/SKILL.md

@@ -1,360 +1,63 @@
 ---
 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.
+description:
+  Build an engineering snapshot for ACE bootstrap and routing. Use when `ace init` starts discovery, the orchestrator needs current code facts before a handoff, or the existing engineering snapshot is stale.
 ---
 
-# ACE CodeMunch Boot — Engineering-State Bootstrap Scanner
+# ACE Orchestrator
 
-**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.
+Use this skill to ground orchestration in real engineering evidence before planning or routing begins.
 
-**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.
+## Purpose
 
----
-
-## 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>
-```
+Produce a fast, decision-ready engineering snapshot from ast-grep and lightweight filesystem scans so ACE routes work from facts instead of directory guesses.
 
----
-
-### 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"
+## Canonical Use Cases
 
-# --- 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"
+1. `ace init` or discovery boot needs a first-pass engineering snapshot before `MASTER_PLAN.md` or the first handoff is written.
+2. The orchestrator is about to route work, but `global-state/ENGINEERING_SNAPSHOT.md` is stale or missing.
+3. A build sprint, thesis pivot, or major refactor requires a delta re-scan before the next orchestration decision.
 
-# 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"
-```
-
----
+## Inputs
 
-### 4. Spec Alignment Check
+- The current source tree, especially `./src/` or `./engineering-state/`
+- Project manifests and entry-point candidates
+- `./venture-state/MVP_SPEC.md` when spec-alignment checks are available
+- Existing `./global-state/ENGINEERING_SNAPSHOT.md` if a refresh is being evaluated
 
-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.
+## Workflow
 
-```bash
-# Only run if venture-state MVP spec exists
-if [ -f "./venture-state/MVP_SPEC.md" ]; then
+1. Detect the language mix, manifests, entry points, and rough source profile.
+2. Build a public API census using ast-grep and other narrow structural commands instead of raw code reading.
+3. Measure quality signals such as tests, stubs, TODO density, and risk markers.
+4. Compare engineering signals against the MVP/spec surface when those artifacts exist.
+5. Write `./global-state/ENGINEERING_SNAPSHOT.md` with routing signals, quality signals, and spec-alignment notes.
+6. Feed the snapshot into orchestrator planning and handoff decisions.
 
-  # 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
+## Outputs
 
-  # 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
+- `./global-state/ENGINEERING_SNAPSHOT.md`
+- Routing-ready engineering signals for the next `SWARM_HANDOFF.json`
+- A concise summary suitable for the engineering section of `MASTER_PLAN.md`
 
-  # 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
+## Validation
 
-  echo "=== COVERED (spec keyword found in code) ==="
-  cat /tmp/ace_covered_features.txt | head -20
+- Verify `./global-state/ENGINEERING_SNAPSHOT.md` is written and includes language, build system, entry point, and source-file counts.
+- Verify quality signals and routing recommendations are populated from command output, not guesses.
+- If `./venture-state/MVP_SPEC.md` exists, verify the snapshot records both covered and missing spec-alignment signals.
 
-  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 |
-
----
+## References
 
-## Activation
+- `references/engineering-bootstrap-playbook.md` preserves the detailed scan playbook, command recipes, and routing tables.
 
-This skill is called automatically during ACE boot. It can also be called explicitly:
+## Compatibility
 
-**`ACE --mode boot --write-to ./global-state/ENGINEERING_SNAPSHOT.md`**
+- `SKILL.md` is the canonical portable contract for this skill.
+- The detailed playbook lives under `references/` for progressive disclosure and should not redefine the top-level workflow.
+- The skill remains usable in any client that can run ast-grep and standard shell discovery commands.
 
-Or manually triggered by the Orchestrator at any time with:
+## Failure Policy
 
-**`ACE --mode delta`** — re-runs Steps 3 and 4 only (quality + alignment, no full census)
+- If no usable source tree is present, classify that as missing engineering context and route accordingly instead of fabricating a snapshot.
+- If required discovery commands are unavailable, stop and report the missing tool or environment constraint explicitly.
+- Do not route from stale or partial engineering assumptions when a fresh scan was required but could not be completed.