Brainstorm: ZIO SBT AI Skills Plugin

## Overview This issue proposes a new sbt plugin — **`zio-sbt-ai`** — that manages, installs, and updates AI skills for ZIO projects. The goal is to eliminate the repetitive, error-prone work of setting up AI tooling (Claude Code, Cursor, GitHub Copilot, etc.) across ZIO repositories and give the community a shared, versioned, curated set of ZIO-specific skills. --- ## The Problem Every ZIO project that adopts AI tooling faces the same friction: - **Repetitive setup** — writing the same slash commands and config files across dozens of ZIO repositories - **Drift** — skills improve over time but old projects fall behind - **Discovery** — developers don't know what skills exist or what they do - **Inconsistency** — each developer or team sets up their AI tools differently - **ZIO-specific gaps** — general-purpose AI assistants often get ZIO idioms wrong (ZLayer wiring, typed errors, ZIO Test patterns); project-level skills can encode correct patterns --- ## What Is an AI Skill? An AI skill is a named, versioned bundle of files placed at well-known paths in a project to configure AI coding tools. Examples: | Tool | File Location | Purpose | |------|--------------|---------| | Claude Code | `.claude/commands/commit.md` | Slash command prompt | | Claude Code | `CLAUDE.md` | Project-level instructions | | Cursor | `.cursor/rules/zio.mdc` | Coding rules | | GitHub Copilot | `.github/copilot-instructions.md` | Custom instructions | | Windsurf | `.windsurfrules` | Rules | A skill bundles one or more such files, plus metadata (name, version, description, target tools). --- ## Proposed Plugin: `zio-sbt-ai` ### sbt Commands ``` aiSkillsList # List all available skills aiSkillsInstall <name> # Install a specific skill aiSkillsSync # Install/update all configured skills aiSkillsStatus # Show installed skills and their versions aiSkillsRemove <name> # Remove a skill ``` ### Configuration ```scala // build.sbt aiSkills := Seq("commit", "review-pr", "zlayer-design", "write-spec", "error-design") aiSkillsTools := Seq("claude-code", "cursor") // filter by target tool aiSkillsDir := file(".ai-skills") // local cache / lockfile ``` ### Skill Metadata Format ```json { "name": "zlayer-design", "version": "1.0.0", "description": "Design and implement ZLayer dependency graphs", "targets": ["claude-code", "cursor"], "tags": ["zio-core", "dependency-injection"], "files": [ { "src": "zlayer.md", "dest": ".claude/commands/zlayer-design.md", "tool": "claude-code" }, { "src": "zlayer.mdc", "dest": ".cursor/rules/zlayer-design.mdc", "tool": "cursor" } ] } ``` --- ## Proposed Skill Registry A companion repository (e.g. `zio/zio-ai-skills`) acts as the central registry. Skills are versioned via git tags. Community contributions via PRs. ``` zio-ai-skills/ commit/ review-pr/ zlayer-design/ error-design/ write-spec/ ... ``` --- ## 20 Proposed Initial Skills ### Workflow (4) | Skill | Description | |-------|-------------| | `commit` | Create well-structured git commits following ZIO project conventions | | `review-pr` | Review a PR for correctness, ZIO idioms, test coverage, and API design | | `upgrade-deps` | Scan `build.sbt` for outdated ZIO ecosystem dependencies and propose updates | | `generate-changelog` | Generate a `CHANGELOG.md` entry from recent commits/PRs since last release | ### ZIO Core (5) | Skill | Description | |-------|-------------| | `zlayer-design` | Design and implement a `ZLayer` dependency graph | | `error-design` | Design the error channel (`E`) — typed errors, defects, union types | | `resource-scope` | Implement safe resource management with `ZIO.acquireRelease` and `Scope` | | `fiber-concurrency` | Implement concurrent workflows using fibers — `fork`, `race`, `zipPar`, interruption | | `stm-design` | Design transactional state using `STM`, `TRef`, `TQueue`, `TSemaphore` | ### ZIO Testing (3) | Skill | Description | |-------|-------------| | `write-spec` | Write a `ZIOSpec` test suite using `ZIO Test`, `TestClock`, `TestRandom` | | `property-test` | Write property-based tests using `Gen` and `check` | | `test-layer` | Build test `ZLayer` — mocks and in-memory implementations | ### ZIO Ecosystem (6) | Skill | Description | |-------|-------------| | `http-endpoint` | Design ZIO HTTP endpoints — routes, middleware, request/response codecs | | `streams-pipeline` | Build `ZStream` pipelines — sources, transducers, sinks, backpressure | | `schema-derive` | Define `ZIO Schema` — derives codecs, validates data | | `config-design` | Design configuration with `ZIO Config` — descriptors, sources, defaults | | `logging-setup` | Instrument with `ZIO Logging` — structured annotations, log levels | | `metrics-instrument` | Add `ZIO Metrics` — counters, gauges, histograms, Prometheus export | ### Migration & Refactoring (2) | Skill | Description | |-------|-------------| | `migrate-to-zio` | Migrate from `Future`, `cats-effect IO`, or imperative style to ZIO | | `refactor-zio-style` | Refactor toward better ZIO idioms — cleaner layer structure, proper error handling | --- ## Design Questions to Resolve 1. **Conflict resolution** — if a skill wants to write a file that already exists, do we append, overwrite, or refuse? 2. **Scope** — per-project (committed to repo, team-shared) or per-developer (gitignored, personal)? 3. **Lockfile** — track exact installed skill versions for reproducibility (like `package-lock.json`)? 4. **Skill source** — bundle core skills in the plugin JAR (offline-first) + fetch community skills from the registry repo on demand? 5. **Dynamic skills** — should skills be able to introspect the project (read `build.sbt`, dependencies, module structure) to generate project-specific prompts? 6. **Auto-install** — should `ZioSbtEcosystemPlugin` auto-suggest a baseline skill set on first load? --- ## Suggested First Step Build a minimal `zio-sbt-ai` module with: - A small set of bundled skills (e.g. `commit`, `zlayer-design`, `write-spec`) shipped as JAR resources - `aiSkillsSync` task that writes them to the correct project paths - `aiSkillsList` and `aiSkillsStatus` commands - A `skill.json` metadata format spec This gives a working foundation to iterate on before adding registry/remote fetching.