Add ARCHITECTURE.md documenting design evolution; update TODO

ARCHITECTURE.md

@@ -0,0 +1,60 @@
+# 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.

TODO.md

@@ -6,7 +6,12 @@
 - [x] Extract source from `.skill` into `source/`
 
 ## Remaining
-- [ ] Add Creative Commons license file (e.g., CC-BY-4.0)
-- [ ] Review and clean up `source/meta-skill-generator/scripts/__pycache__/` (`.pyc` files — can be deleted, they're build artifacts)
-- [ ] Make repo public
-- [ ] Optionally: add a brief `ARCHITECTURE.md` capturing the evolution from this approach to Pi.dev extensions
+- [ ] **Make repo public** — create a remote (GitHub/GitLab/ etc.) and push:
+      ```bash
+      git remote add origin <url>
+      git push -u origin main
+      # Then set visibility to public in the hosting UI
+      ```
+
+## Future Ideas (not planned)
+- Port the meta-skill concept to Pi.dev extensions for generating other Pi.dev skills