# Architecture Notes — Meta Skill Generator

This document captures the design evolution behind this repository as a reference
for how thinking about coding-agent skill architectures has progressed.

## Original Concept (Nov 2025 — This Repo)

**Toolchain:** Claude Code (Anthropic) — skills packaged as `.skill` ZIP files

**Core insight:** Separate deterministic operations from agent reasoning.
The meta-skill generator analyzes user requirements and classifies each operation
into one of three buckets:

| Bucket | Technology | When |
|--------|-----------|------|
| **Deterministic scripts** | Compiled Go binaries | Format conversion, batch processing, file I/O |
| **Library-heavy scripts** | Python scripts | pandas, ML, visualization |
| **Agent workflows** | Natural language in SKILL.md | Analysis, reasoning, creative tasks |

**Why Go?** The argument was: compiled binaries are fast, have no runtime
dependencies, and are good for things like PDF conversion or CSV processing
that don't need LLM reasoning.

**Pain points discovered:**
- Go scripts are external processes — startup latency, IPC overhead
- Debugging requires attaching to a separate process
- Maintaining Go toolchain for what are often small utilities
- The `.skill` ZIP format is opaque — easy to lose the source

## Evolution (Current Thinking)

**Toolchain:** Pi.dev — extensions (in-process plugins), stored prompts, skills

The same core insight holds (separate deterministic ops from reasoning), but the
implementation has shifted:

| Component | Now | Benefit |
|-----------|-----|---------|
| **Deterministic operations** | Pi.dev extensions (TypeScript/JS) | In-process with the agent, ~10× faster than shell scripts, immediate stack traces, "let it crash" debugging |
| **Prompts / instructions** | Stored prompt templates | Referenced by name, versioned separately from code |
| **Orchestration** | Conversational prompting | More fluid, adaptive to context |

**Key realisations:**
- Extensions running in the same process as the agent give you crashes, stack
  traces, and debugging *right there* instead of having to chase a subprocess.
- The boundary between "code" and "prompt" is blurrier than the original strict
  three-bucket model suggested. Sometimes you want a prompt that references a
  plugin; sometimes a plugin that calls back to the agent.
- The `.skill` → ZIP pattern works but adds friction. Flat source + a tool that
  knows how to load it is simpler.

## Summary

This repo represents an early, structured take on a problem that's still relevant:
**not everything needs an LLM, and not everything needs a subprocess.** The
current approach (Pi.dev extensions + stored prompts) achieves the same
separation with less overhead and tighter integration.

See also the [README](./README.md) banner note and the
[TODO](./TODO.md) for remaining housekeeping.