ace-swarm 1.1.0

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

@@ -0,0 +1,502 @@
+---
+name: codemunch
+description: 
+  Holistic AST-driven codebase comprehension. Uses ast-grep to surgically extract structural knowledge into lightweight artifacts, enabling deep understanding of any foreign codebase without reading raw files. Operates as a capability-research module inside the ACE Framework.
+---
+
+# CodeMunch — AST-Driven Codebase Intelligence
+
+**IMPORTANT**: NEVER read raw source files to understand a codebase. Every structural fact MUST
+be extracted via an `ast-grep` query. Raw file reads burn 10–100× more tokens than equivalent
+AST queries. The only exception is a single-file glance at an entry point to confirm language
+and project purpose. The goal is to **produce artifacts, not chat**. If a CodeMunch session
+ends without writing at least `CODEBASE_MAP.md`, it has failed.
+
+---
+
+## 0. ACE Role Declaration
+
+CodeMunch is a `capability-research` module. In every session it:
+
+- **Emits** a `SOURCE_VALIDATED` event when a structural claim is confirmed by ast-grep output.
+- **Writes** findings to `./agent-state/` as append-only artifacts.
+- **Blocks** downstream modules (`capability-spec`, `capability-build`) from acting on unverifiable structural assumptions.
+- **Hands off** via `HANDOFF.json` once `CODEBASE_MAP.md` and `PATTERNS.md` are locked.
+
+ACE Clarity Protocol headers (`[STATE_ANALYSIS]`, `[STRATEGY_SELECTOR]`, `[EXECUTION_LOG]`,
+`[ARTIFACT_UPDATE]`, `[VERIFICATION]`) must be used at each phase boundary in your response.
+
+---
+
+## 1. Socratic Question Stack
+
+Before running a single command, answer these questions in order. Stop at the first one you cannot answer — that is your first ast-grep target.
+
+**Tier 0 — Orientation (answer from README or a 30-second scan)**
+1. What is the primary language and build system?
+2. What is the stated purpose of this codebase in one sentence?
+3. Where is the entry point (`main`, `__init__`, `index`, `lib.rs`, etc.)?
+
+**Tier 1 — Skeleton (answer via ast-grep)**
+4. What are the top-level public types / classes / structs / enums?
+5. What are the primary exported functions or public API symbols?
+6. How many modules/crates/packages exist, and how are they named?
+7. What external dependencies are imported at the top level?
+
+**Tier 2 — Relationships (answer via ast-grep)**
+8. Which modules call which other modules? (call-site mapping)
+9. Where does data enter the system and where does it leave?
+10. What trait / interface / protocol implementations exist?
+11. Where is error handling centralised? What error types exist?
+
+**Tier 3 — Patterns (answer via ast-grep)**
+12. What repeated structural idioms appear 3+ times? (factory, builder, strategy, etc.)
+13. What test coverage patterns exist? (unit, integration, property-based?)
+14. Are there any TODO/FIXME/HACK/unsafe markers that signal risk areas?
+15. What configuration / deserialisation surface exists?
+
+**Tier 4 — Goal Alignment (answer from the task)**
+16. What is the specific goal? (understand / debug / add feature / contribute / get inspired)
+17. Which modules are in the critical path for this goal?
+18. What is the simplest change that would advance this goal?
+
+> **Rule**: Each unanswered question maps to exactly one ast-grep command in Phase 2.
+> Write the question → answer pairs into `SOCRATIC_LOG.md` as you go.
+
+---
+
+## 2. Execution Protocol
+
+### Phase 0 — Bootstrap `[STATE_ANALYSIS]`
+
+Detect the language, structure, and project skeleton without reading any source files.
+
+**Step 1 — Language detection**
+```bash
+# Count files by extension to confirm language mix
+find . -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -20
+
+# Confirm primary language for ast-grep --lang flag
+# Common values: rust, python, js, ts, tsx, go, java, cpp, c, cs, ruby
+```
+
+**Step 2 — Entry point identification**
+```bash
+# Rust
+ast-grep --pattern 'fn main() { $$$ }' --lang rust --json
+
+# Python
+ast-grep --pattern 'if __name__ == "__main__": $$$' --lang python --json
+
+# JS/TS
+ast-grep --pattern 'export default $EXPR' --lang ts --json
+ast-grep --pattern 'module.exports = $EXPR' --lang js --json
+```
+
+**Step 3 — Top-level module map**
+```bash
+# Count lines and files per directory (structural overview, no source reading)
+find . -name "*.rs" | head -60
+find . -name "*.py" | head -60
+```
+
+**Output**: Write `CODEBASE_MAP.md` stub:
+```markdown
+# CODEBASE_MAP.md
+Language: <lang>
+Entry Point: <path>
+Build System: <cargo/pip/npm/make>
+Module Count: <n>
+Purpose: <one sentence from README>
+```
+
+---
+
+### Phase 1 — Skeleton Extraction `[STRATEGY_SELECTOR]`
+
+Extract the full public API surface using targeted ast-grep patterns. Do NOT read
+implementations — extract signatures only.
+
+**Step 4 — Public types**
+```bash
+# Rust: structs, enums, traits
+ast-grep --pattern 'pub struct $NAME { $$$ }' --lang rust
+ast-grep --pattern 'pub enum $NAME { $$$ }' --lang rust
+ast-grep --pattern 'pub trait $NAME { $$$ }' --lang rust
+
+# Python: classes
+ast-grep --pattern 'class $NAME: $$$' --lang python
+
+# TypeScript: interfaces, types, classes
+ast-grep --pattern 'export interface $NAME { $$$ }' --lang ts
+ast-grep --pattern 'export type $NAME = $TYPE' --lang ts
+ast-grep --pattern 'export class $NAME { $$$ }' --lang ts
+```
+
+**Step 5 — Public functions / methods**
+```bash
+# Rust: public fns (with --json for machine-parseable output)
+ast-grep --pattern 'pub fn $NAME($$$) -> $RET { $$$ }' --lang rust --json
+
+# Rust: public fns (no return type)
+ast-grep --pattern 'pub fn $NAME($$$) { $$$ }' --lang rust
+
+# Python: top-level defs
+ast-grep --pattern 'def $NAME($$$): $$$' --lang python
+
+# TypeScript: exported functions
+ast-grep --pattern 'export function $NAME($$$): $RET { $$$ }' --lang ts
+ast-grep --pattern 'export const $NAME = ($$$) => $BODY' --lang ts
+```
+
+**Step 6 — External dependencies**
+```bash
+# Rust: use statements (top-level imports)
+ast-grep --pattern 'use $PATH' --lang rust
+
+# Python: imports
+ast-grep --pattern 'import $MODULE' --lang python
+ast-grep --pattern 'from $MODULE import $NAME' --lang python
+
+# JS/TS: imports
+ast-grep --pattern 'import $NAME from "$PATH"' --lang ts
+ast-grep --pattern 'import { $$$ } from "$PATH"' --lang ts
+```
+
+**Output**: Append to `CODEBASE_MAP.md`:
+```markdown
+## Public API Surface
+### Types
+- `TypeName` — <kind: struct/enum/class> — <file:line>
+
+### Functions
+- `fn_name(args) -> ret` — <file:line>
+
+### Key Dependencies
+- <dep_name>: <apparent purpose>
+```
+
+---
+
+### Phase 2 — Relationship Mapping `[EXECUTION_LOG]`
+
+Find how components connect. This answers Socratic questions 8–11.
+
+**Step 7 — Trait/interface implementations**
+```bash
+# Rust: impl blocks (what implements what)
+ast-grep --pattern 'impl $TRAIT for $TYPE { $$$ }' --lang rust
+
+# Rust: plain impl blocks
+ast-grep --pattern 'impl $TYPE { $$$ }' --lang rust
+```
+
+**Step 8 — Call-site mapping (who calls what)**
+```bash
+# Find all calls to a specific function (replace TARGET with function name)
+ast-grep --pattern '$OBJ.TARGET($$$)' --lang rust
+ast-grep --pattern 'TARGET($$$)' --lang rust
+
+# Find all method calls on a type
+ast-grep --pattern '$VAR: $TYPE' --lang rust   # find variable declarations of a type
+```
+
+**Step 9 — Error handling topology**
+```bash
+# Rust: Result types and ? operator usage
+ast-grep --pattern 'Result<$T, $E>' --lang rust
+ast-grep --pattern '$EXPR?' --lang rust
+
+# Rust: custom error enums
+ast-grep --pattern 'pub enum $NAME { $$$ }' --lang rust  # filter for Error suffix
+
+# Python: exception definitions
+ast-grep --pattern 'class $NAME(Exception): $$$' --lang python
+ast-grep --pattern 'except $EXC: $$$' --lang python
+```
+
+**Step 10 — Configuration and deserialization surface**
+```bash
+# Rust: serde derives (anything Deserialize is config/data entry)
+ast-grep --pattern '#[derive($$$Deserialize$$$)] $STRUCT' --lang rust
+
+# Python: dataclasses, pydantic models
+ast-grep --pattern '@dataclass' --lang python
+ast-grep --pattern 'class $NAME(BaseModel): $$$' --lang python
+
+# TypeScript: zod schemas, JSON parse points
+ast-grep --pattern 'z.object({ $$$ })' --lang ts
+```
+
+**Output**: Write `DEPENDENCY_GRAPH.md`:
+```markdown
+# DEPENDENCY_GRAPH.md
+## Module Relationships
+- `module_a` → calls → `module_b` (via fn_name)
+
+## Trait Implementations
+- `TypeX` implements `TraitY`
+
+## Error Taxonomy
+- `ErrorVariant`: exits at <file:line>
+
+## Config / Data Entry Points
+- `StructName` (Deserialize): loaded at <file>
+```
+
+---
+
+### Phase 3 — Pattern & Idiom Mining `[EXECUTION_LOG]`
+
+Identify recurring structural decisions. These reveal the codebase's philosophy.
+
+**Step 11 — Test patterns**
+```bash
+# Rust: test functions
+ast-grep --pattern '#[test] fn $NAME() { $$$ }' --lang rust
+ast-grep --pattern '#[tokio::test] async fn $NAME() { $$$ }' --lang rust
+
+# Python: pytest / unittest
+ast-grep --pattern 'def test_$NAME($$$): $$$' --lang python
+ast-grep --pattern 'class $NAME(TestCase): $$$' --lang python
+
+# JS/TS: jest / vitest
+ast-grep --pattern 'it("$DESC", $$$)' --lang ts
+ast-grep --pattern 'describe("$DESC", $$$)' --lang ts
+```
+
+**Step 12 — Unsafe / risk markers**
+```bash
+# Rust: unsafe blocks (security/correctness hotspots)
+ast-grep --pattern 'unsafe { $$$ }' --lang rust
+ast-grep --pattern 'unsafe fn $NAME($$$)' --lang rust
+
+# TODO/FIXME markers (language-agnostic comment scan)
+grep -rn "TODO\|FIXME\|HACK\|SAFETY\|PANIC\|unwrap()" --include="*.rs" | head -40
+grep -rn "TODO\|FIXME\|HACK\|BUG" --include="*.py" | head -40
+```
+
+**Step 13 — Builder / factory / newtype patterns**
+```bash
+# Rust: builder pattern (fn new / fn build)
+ast-grep --pattern 'fn new($$$) -> Self { $$$ }' --lang rust
+ast-grep --pattern 'fn build(self) -> $TYPE { $$$ }' --lang rust
+
+# Rust: newtype wrappers
+ast-grep --pattern 'pub struct $NAME($INNER);' --lang rust
+
+# Python: class methods / factories
+ast-grep --pattern '@classmethod' --lang python
+```
+
+**Step 14 — Async / concurrency patterns**
+```bash
+# Rust: async functions
+ast-grep --pattern 'async fn $NAME($$$)' --lang rust
+ast-grep --pattern 'tokio::spawn($$$)' --lang rust
+
+# Python: async
+ast-grep --pattern 'async def $NAME($$$): $$$' --lang python
+
+# JS/TS
+ast-grep --pattern 'await $EXPR' --lang ts
+```
+
+**Output**: Append to `PATTERNS.md`:
+```markdown
+# PATTERNS.md
+## Design Patterns Detected
+- Builder: <count> usages, primary in <module>
+- Newtype: <count> usages
+
+## Test Coverage Profile
+- Unit tests: <count>
+- Integration tests: <count>
+- Async tests: <count>
+
+## Risk Markers
+- unsafe blocks: <count> in <files>
+- TODOs: <list of top ones>
+
+## Concurrency Model
+- <async/sync/threaded/actor> — evidence: <fn names>
+```
+
+---
+
+### Phase 4 — Artifact Generation `[ARTIFACT_UPDATE]`
+
+All findings are now crystallised into locked artifacts. No reasoning from memory — only
+from the written artifacts below.
+
+**Required artifacts** (write all before Phase 5):
+
+| Artifact | Purpose |
+|---|---|
+| `CODEBASE_MAP.md` | Language, entry points, module list, public API surface |
+| `DEPENDENCY_GRAPH.md` | Module relationships, trait impls, error taxonomy |
+| `PATTERNS.md` | Design patterns, test profile, risk markers, concurrency model |
+| `SOCRATIC_LOG.md` | Every question + its ast-grep-verified answer |
+| `EVIDENCE_LOG.md` | Raw ast-grep output snippets used as evidence (append-only) |
+
+**Artifact write protocol:**
+```bash
+# Each ast-grep query output MUST be appended to EVIDENCE_LOG.md immediately
+echo "## Query: pub fn signatures (rust)" >> ./agent-state/EVIDENCE_LOG.md
+ast-grep --pattern 'pub fn $NAME($$$) -> $RET { $$$ }' --lang rust --json   >> ./agent-state/EVIDENCE_LOG.md
+```
+
+**Optional artifacts** (generate when goal demands it):
+
+| Artifact | When to generate |
+|---|---|
+| `CALL_GRAPH.md` | Goal = debug / trace data flow |
+| `CONTRIBUTION_GUIDE.md` | Goal = contribute / extend |
+| `INSPIRATION_NOTES.md` | Goal = extract ideas for new project |
+| `BUG_HYPOTHESIS.md` | Goal = debug specific issue |
+
+---
+
+### Phase 5 — Synthesis Pass `[VERIFICATION]`
+
+**ONLY after all Phase 4 artifacts are written**, perform a final reasoning pass.
+Read ONLY the artifacts — not any source files.
+
+**Step 15 — Self-verification checklist**
+- [ ] Can I describe the codebase architecture in 3 sentences from `CODEBASE_MAP.md` alone?
+- [ ] Can I name the 5 most important types/functions without looking at source?
+- [ ] Can I explain the data flow from entry to exit from `DEPENDENCY_GRAPH.md`?
+- [ ] Have all Tier 2 Socratic questions been answered in `SOCRATIC_LOG.md`?
+- [ ] Does `EVIDENCE_LOG.md` have at least one ast-grep snippet per structural claim?
+
+**Step 16 — Goal-aligned synthesis**
+
+*Mode: UNDERSTAND*
+> Synthesise `CODEBASE_MAP.md` + `PATTERNS.md` into a plain-English architecture document.
+
+*Mode: DEBUG*
+> Trace the bug-relevant call path using `CALL_GRAPH.md`. Write `BUG_HYPOTHESIS.md`
+> with: symptom → suspected module → ast-grep evidence → falsification criteria.
+
+*Mode: CONTRIBUTE / ADD FEATURE*
+> From `DEPENDENCY_GRAPH.md`, identify the minimum insertion point. Write
+> `CONTRIBUTION_GUIDE.md` with: interface contract, which existing tests to extend,
+> which patterns to follow (from `PATTERNS.md`).
+
+*Mode: INSPIRE*
+> Extract architectural decisions, naming conventions, idioms from `PATTERNS.md` into
+> `INSPIRATION_NOTES.md` with annotations on what can be adapted.
+
+**Step 17 — HANDOFF**
+
+Emit `HANDOFF.json` when synthesis is complete:
+```json
+{
+  "meta": { "timestamp": "<ISO8601>", "skill": "codemunch", "session_id": "<uuid>" },
+  "transition": {
+    "from": "capability-research",
+    "to": "capability-spec",
+    "status": "READY_FOR_HANDOFF",
+    "reason": "Codebase map and pattern artifacts are locked."
+  },
+  "payload": {
+    "primary_artifact": "./agent-state/CODEBASE_MAP.md",
+    "supporting_artifacts": [
+      "./agent-state/DEPENDENCY_GRAPH.md",
+      "./agent-state/PATTERNS.md",
+      "./agent-state/SOCRATIC_LOG.md"
+    ],
+    "evidence_pointer": "./agent-state/EVIDENCE_LOG.md",
+    "known_unknowns": ["<list any unanswered Tier 3/4 questions>"]
+  }
+}
+```
+
+---
+
+## 3. ast-grep Quick Reference
+
+### Universal Flags
+```bash
+--lang <lang>         # rust | python | js | ts | tsx | go | java | cpp | c | html | css
+--pattern / -p        # inline pattern
+--rule <file.yml>     # YAML rule file for complex patterns
+--json / -j           # machine-readable JSON output (use for artifact writing)
+--no-ignore           # scan files ignored by .gitignore
+--color never         # disable ANSI in output (use when piping to artifact files)
+```
+
+### Meta-variable Syntax
+```
+$NAME     — single AST node (identifier, expression, etc.)
+$$$       — zero or more AST nodes (variadic / body capture)
+$$ARGS    — named multi-match capture
+$_        — anonymous wildcard (matches anything, not captured)
+```
+
+### YAML Rule Template (complex structural queries)
+```yaml
+# Save as ./codemunch-rules/<rule-name>.yml
+id: find-pattern-name
+language: rust
+rule:
+  pattern: pub fn $NAME($$$) -> Result<$T, $E> { $$$ }
+  # Optional filters:
+  inside:
+    pattern: impl $TRAIT for $TYPE { $$$ }
+  has:
+    pattern: $EXPR?      # contains at least one ? operator
+  not:
+    pattern: todo!()     # exclude unimplemented stubs
+```
+Run: `ast-grep scan --rule ./codemunch-rules/<rule-name>.yml`
+
+### Language Cheat Sheet
+
+**Rust**
+```bash
+ast-grep -p 'pub fn $N($$$)' -l rust                         # public functions
+ast-grep -p 'impl $T for $U { $$$ }' -l rust                 # trait impls
+ast-grep -p '#[derive($$$)]' -l rust                          # all derives
+ast-grep -p 'Err($E)' -l rust                                 # error emission sites
+ast-grep -p '$V.unwrap()' -l rust                             # panic hotspots
+```
+
+**Python**
+```bash
+ast-grep -p 'def $N($$$) -> $R: $$$' -l python               # typed functions
+ast-grep -p '@$DECORATOR' -l python                           # all decorators
+ast-grep -p 'raise $E' -l python                              # exception sites
+ast-grep -p '__all__ = [$$$]' -l python                       # public exports
+```
+
+**TypeScript / JavaScript**
+```bash
+ast-grep -p 'export { $$$ }' -l ts                            # barrel exports
+ast-grep -p 'const $N = useCallback($$$)' -l tsx              # React hooks
+ast-grep -p 'throw new $E($$$)' -l ts                         # throw sites
+ast-grep -p 'satisfies $TYPE' -l ts                           # type constraints
+```
+
+---
+
+## 4. Failure Modes & Circuit Breakers
+
+| Failure | Signal | Recovery |
+|---|---|---|
+| `ast-grep` returns no matches | Pattern may be wrong for this dialect | Use `--json` + inspect one sample node kind first |
+| Artifact file > 500 lines | Too much raw output captured | Summarise into bullet points; keep only exemplars in EVIDENCE_LOG |
+| Socratic question unresolvable via AST | Deep runtime behaviour | Mark as `KNOWN_UNKNOWN` in SOCRATIC_LOG; do NOT guess |
+| Goal changes mid-session | New task injected | Emit `GATE_FAILED`, re-enter Phase 0 with updated goal |
+
+---
+
+## 5. Activation
+
+When you receive a codebase (path, repo, or CXML dump) with a goal, type:
+
+**`munch <path> --goal <understand|debug|contribute|inspire> [--lang <lang>]`**
+
+CodeMunch will automatically enter Phase 0, execute the Socratic Question Stack, run
+ast-grep queries in order, and produce the Phase 4 artifacts before delivering the
+Phase 5 synthesis. No raw file reading. No token waste. Only structure.